spore/README.md

# 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.

## 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

📖 **Detailed Architecture:** See [`docs/Architecture.md`](./docs/Architecture.md) for comprehensive system design and implementation details.

## API Endpoints

The system provides a comprehensive RESTful API for monitoring and controlling the embedded device.

**Core Endpoints:**
- **`/api/node/status`** - System resources and API endpoint registry
- **`/api/cluster/members`** - Cluster membership and health status
- **`/api/node/update`** - OTA firmware updates
- **`/api/node/restart`** - System restart
- **`/api/tasks/status`** - Task management and monitoring
- **`/api/tasks/control`** - Task control operations

**Response Format:** All endpoints return JSON with standardized error handling and HTTP status codes.

📖 **Complete API Reference:** See [`docs/API.md`](./docs/API.md) for detailed endpoint documentation, examples, and integration guides.

## 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 Guide:** See [`docs/Development.md`](./docs/Development.md) for comprehensive build, deployment, and configuration instructions.

## 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 detailed build, deployment, and troubleshooting instructions.

## API Reference

The SPORE system provides a comprehensive RESTful API for monitoring and controlling the embedded device. All endpoints return JSON responses and support standard HTTP status codes.

### Quick Reference

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/tasks/status` | GET | Get comprehensive task status |
| `/api/tasks/control` | POST | Control individual tasks |
| `/api/node/status` | GET | System resource information |
| `/api/cluster/members` | GET | Cluster membership |
| `/api/node/update` | POST | OTA firmware updates |
| `/api/node/restart` | POST | System restart |

**Available Task Actions:** `enable`, `disable`, `start`, `stop`, `status`

📖 **Detailed API Documentation:** See [`docs/API.md`](./docs/API.md) for complete API reference, examples, and integration guides.

🔧 **OpenAPI Specification:** Machine-readable API spec available in [`api/`](./api/) folder for code generation and tooling integration.

## Implementation Details

The system uses an event-driven architecture with automatic resource monitoring and WiFi fallback capabilities.

**Key Systems:**
- **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

📖 **Architecture Details:** See [`docs/Architecture.md`](./docs/Architecture.md) for comprehensive system design and implementation information.

## Task Management

The SPORE system includes a comprehensive TaskManager for background task management with runtime control and monitoring.

**Key Features:**
- **Easy Registration**: Simple API for adding tasks with configurable intervals
- **Dynamic Control**: Enable/disable tasks at runtime without restart
- **Status Monitoring**: Real-time task health and performance tracking
- **Remote Management**: REST API for cluster-wide task control

📖 **Complete Task Management Guide:** See [`docs/TaskManagement.md`](./docs/TaskManagement.md) for detailed usage examples, best practices, and advanced features.

## 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
```

📖 **For detailed task management examples and workflows, see [`docs/API.md`](./docs/API.md).**

## Documentation

📚 **Comprehensive documentation is available in the [`docs/`](./docs/) folder:**

- **[API Reference](./docs/API.md)** - Complete API documentation with examples
- **[TaskManager Guide](./docs/TaskManager.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