SPORE

SProcket ORchestration Engine

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 (1MB Flash)
• ESP-01S (1MB Flash)
• Other ESP8266 boards with 1MB+ flash

Architecture

Core Components

The system architecture consists of several key components working together:

• 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

Auto Discovery Protocol

The cluster uses a UDP-based discovery protocol for automatic node detection:

1. Discovery Broadcast: Nodes periodically send UDP packets on port 4210
2. Response Handling: Nodes respond with their hostname and IP address
3. Member Management: Discovered nodes are automatically added to the cluster
4. Health Monitoring: Continuous status checking via HTTP API calls

Task Scheduling

The system runs several background tasks at different intervals:

• Discovery Tasks: Send/listen for discovery packets (1s/100ms)
• Status Updates: Monitor cluster member health (1s)
• Heartbeat: Maintain cluster connectivity (2s)
• Member Info: Update detailed node information (10s)
• Debug Output: Print cluster status (5s)

API Endpoints

Node Management

Endpoint	Method	Description
/api/node/status	GET	Get system resources and API endpoints
/api/node/update	POST	Upload and install firmware update
/api/node/restart	POST	Restart the node

Cluster Management

Endpoint	Method	Description
/api/cluster/members	GET	Get cluster membership and status

Node Status Response

{
  "freeHeap": 12345,
  "chipId": 12345678,
  "sdkVersion": "2.2.2-dev(38a443e)",
  "cpuFreqMHz": 80,
  "flashChipSize": 1048576,
  "api": [
    {
      "uri": "/api/node/status",
      "method": "GET"
    }
  ]
}

Cluster Members Response

{
  "members": [
    {
      "hostname": "esp_123456",
      "ip": "192.168.1.100",
      "lastSeen": 1234567890,
      "latency": 5,
      "status": "active",
      "resources": {
        "freeHeap": 12345,
        "chipId": 12345678,
        "sdkVersion": "2.2.2-dev(38a443e)",
        "cpuFreqMHz": 80,
        "flashChipSize": 1048576
      },
      "api": [
        {
          "uri": "/api/node/status",
          "method": "GET"
        }
      ]
    }
  ]
}

Configuration

Environment Setup

Create a .env file in your project root:

# API node IP for cluster management
export API_NODE=192.168.1.100

PlatformIO Configuration

The project uses PlatformIO with the following configuration:

• Framework: Arduino
• Board: ESP-01 with 1MB flash
• Upload Speed: 115200 baud
• Flash Mode: DOUT (required for ESP-01S)

Dependencies

The project requires the following libraries:

• esp32async/ESPAsyncWebServer@^3.8.0 - HTTP API server
• bblanchon/ArduinoJson@^7.4.2 - JSON processing
• arkhipenko/TaskScheduler@^3.8.5 - Cooperative multitasking

Development

Prerequisites

• PlatformIO Core or PlatformIO IDE
• ESP8266 development tools
• jq for JSON processing in scripts

Building

Build the firmware:

./ctl.sh build

Flashing

Flash firmware to a connected device:

./ctl.sh flash

Over-The-Air Updates

Update a specific node:

./ctl.sh ota update 192.168.1.100

Update all nodes in the cluster:

./ctl.sh ota all

Cluster Management

View cluster members:

./ctl.sh cluster members

Implementation Details

Event System

The NodeContext provides an event-driven architecture:

// Subscribe to events
ctx.on("node_discovered", [](void* data) {
    NodeInfo* node = static_cast<NodeInfo*>(data);
    // Handle new node discovery
});

// Publish events
ctx.fire("node_discovered", &newNode);

Node Status Tracking

Nodes are automatically categorized by their activity:

• ACTIVE: Responding within 10 seconds
• INACTIVE: No response for 10-60 seconds
• DEAD: No response for over 60 seconds

Resource Monitoring

Each node tracks:

• Free heap memory
• Chip ID and SDK version
• CPU frequency
• Flash chip size
• API endpoint registry

WiFi Fallback

The system includes automatic WiFi fallback:

1. Attempts to connect to configured WiFi network
2. If connection fails, creates an access point
3. Hostname is automatically generated from MAC address

Current Limitations

• WiFi credentials are hardcoded in Config.cpp (should be configurable)
• Limited error handling for network failures
• No persistent storage for configuration
• Basic health monitoring without advanced metrics

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:

pio device monitor

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
• Uses TaskScheduler for cooperative multitasking
• ESPAsyncWebServer for HTTP API
• ArduinoJson for JSON processing