# 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
- **Capability Discovery**: Automatic API endpoint and service capability detection

## 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/node/endpoints` | GET | API endpoints and parameters |
| `/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 |
| `/api/network/status` | GET | WiFi and network status information |
| `/api/network/wifi/scan` | GET/POST | WiFi network scanning and discovery |
| `/api/network/wifi/config` | POST | WiFi configuration management |

**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
- No authentication or security features 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