170 lines
6.1 KiB
Markdown
170 lines
6.1 KiB
Markdown
# SPORE
|
|
|
|
> **S**Procket **OR**chestration **E**ngine
|
|
|
|
SPORE is a cluster engine for ESP8266 microcontrollers that provides automatic node discovery, health monitoring, and over-the-air updates in a distributed network environment.
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Supported Hardware](#supported-hardware)
|
|
- [Architecture](#architecture)
|
|
- [API Reference](#api-reference)
|
|
- [Configuration](#configuration)
|
|
- [Development](#development)
|
|
- [Current Limitations](#current-limitations)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Documentation](#documentation)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
- [Acknowledgments](#acknowledgments)
|
|
|
|
## Features
|
|
|
|
- **WiFi Management**: Automatic WiFi STA/AP configuration with MAC-based hostname generation
|
|
- **Auto Discovery**: UDP-based node discovery with automatic cluster membership
|
|
- **Service Registry**: Dynamic API endpoint discovery and registration
|
|
- **Health Monitoring**: Real-time node status tracking with resource monitoring
|
|
- **Event System**: Local and cluster-wide event publishing/subscription
|
|
- **Over-The-Air Updates**: Seamless firmware updates across the cluster
|
|
- **REST API**: HTTP-based cluster management and monitoring
|
|
|
|
## Supported Hardware
|
|
|
|
- **ESP-01 / ESP-01S** (1MB Flash)
|
|
- **Wemos D1** (4MB Flash)
|
|
- Other ESP8266 boards with 1MB+ flash
|
|
|
|
## Architecture
|
|
|
|
SPORE uses a modular architecture with automatic node discovery, health monitoring, and distributed task management.
|
|
|
|
**Core Components:**
|
|
- **Network Manager**: WiFi connection handling and hostname configuration
|
|
- **Cluster Manager**: Node discovery, member list management, and health monitoring
|
|
- **API Server**: HTTP API server with dynamic endpoint registration
|
|
- **Task Scheduler**: Cooperative multitasking system for background operations
|
|
- **Node Context**: Central context providing event system and shared resources
|
|
|
|
**Key Features:**
|
|
- **Auto Discovery**: UDP-based node detection on port 4210
|
|
- **Health Monitoring**: Continuous status checking via HTTP API
|
|
- **Task Scheduling**: Background tasks at configurable intervals
|
|
- **Event System**: Local and cluster-wide event publishing/subscription
|
|
- **Status Tracking**: Automatic node categorization (ACTIVE, INACTIVE, DEAD)
|
|
- **Resource Monitoring**: Memory, CPU, flash, and API endpoint tracking
|
|
- **WiFi Fallback**: Automatic access point creation if connection fails
|
|
|
|
📖 **Detailed Architecture:** See [`docs/Architecture.md`](./docs/Architecture.md) for comprehensive system design and implementation details.
|
|
|
|
## API Reference
|
|
|
|
The system provides a comprehensive RESTful API for monitoring and controlling the embedded device. All endpoints return JSON responses and support standard HTTP status codes.
|
|
|
|
**Core Endpoints:**
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/api/node/status` | GET | System resources and API endpoint registry |
|
|
| `/api/cluster/members` | GET | Cluster membership and health status |
|
|
| `/api/node/update` | POST | OTA firmware updates |
|
|
| `/api/node/restart` | POST | System restart |
|
|
| `/api/tasks/status` | GET | Task management and monitoring |
|
|
| `/api/tasks/control` | POST | Task control operations |
|
|
|
|
**Response Format:** All endpoints return JSON with standardized error handling and HTTP status codes.
|
|
|
|
📖 **Complete API Documentation:** See [`docs/API.md`](./docs/API.md) for detailed endpoint documentation, examples, and integration guides.
|
|
|
|
🔧 **OpenAPI Specification:** Machine-readable API spec available in [`api/`](./api/) folder for code generation and tooling integration.
|
|
|
|
## Configuration
|
|
|
|
The project uses PlatformIO with Arduino framework and supports multiple ESP8266 boards.
|
|
|
|
**Key Settings:**
|
|
- **Framework**: Arduino
|
|
- **Board**: ESP-01 with 1MB flash (default)
|
|
- **Upload Speed**: 115200 baud
|
|
- **Flash Mode**: DOUT (required for ESP-01S)
|
|
|
|
**Dependencies:**
|
|
- ESPAsyncWebServer, ArduinoJson, TaskScheduler
|
|
- ESP8266WiFi and HTTPClient libraries
|
|
|
|
**Environment Setup:** Create `.env` file for cluster configuration and API node settings.
|
|
|
|
## Development
|
|
|
|
**Quick Commands:**
|
|
```bash
|
|
# Build firmware
|
|
./ctl.sh build target esp01_1m
|
|
|
|
# Flash device
|
|
./ctl.sh flash target esp01_1m
|
|
|
|
# OTA update
|
|
./ctl.sh ota update 192.168.1.100 esp01_1m
|
|
|
|
# Cluster management
|
|
./ctl.sh cluster members
|
|
```
|
|
|
|
**Prerequisites:** PlatformIO Core, ESP8266 tools, `jq` for JSON processing
|
|
|
|
📖 **Complete Development Guide:** See [`docs/Development.md`](./docs/Development.md) for comprehensive build, deployment, and troubleshooting instructions.
|
|
|
|
## Current Limitations
|
|
|
|
- WiFi credentials are hardcoded in `Config.cpp` (should be configurable)
|
|
- Limited error handling for network failures
|
|
- No persistent storage for configuration
|
|
- Task monitoring and system health metrics
|
|
- Task execution history and performance analytics not yet implemented
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Discovery Failures**: Check UDP port 4210 is not blocked
|
|
2. **WiFi Connection**: Verify SSID/password in Config.cpp
|
|
3. **OTA Updates**: Ensure sufficient flash space (1MB minimum)
|
|
4. **Cluster Split**: Check network connectivity between nodes
|
|
|
|
### Debug Output
|
|
|
|
Enable serial monitoring to see cluster activity:
|
|
|
|
```bash
|
|
pio device monitor
|
|
```
|
|
|
|
## Documentation
|
|
|
|
📚 **Comprehensive documentation is available in the [`docs/`](./docs/) folder:**
|
|
|
|
- **[API Reference](./docs/API.md)** - Complete API documentation with examples
|
|
- **[Architecture Guide](./docs/Architecture.md)** - System design and implementation details
|
|
- **[Development Guide](./docs/Development.md)** - Build, deployment, and configuration
|
|
- **[Task Management Guide](./docs/TaskManagement.md)** - Background task management system
|
|
- **[OpenAPI Spec](./api/)** - Machine-readable API specification
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test thoroughly on ESP8266 hardware
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
[Add your license information here]
|
|
|
|
## Acknowledgments
|
|
|
|
- Built with [PlatformIO](https://platformio.org/)
|
|
- Uses [TaskScheduler](https://github.com/arkhipenko/TaskScheduler) for cooperative multitasking
|
|
- [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) for HTTP API
|
|
- [ArduinoJson](https://arduinojson.org/) for JSON processing |