SPORE

Quick Start

#include <Arduino.h>
#include "spore/Spore.h"
#include "spore/Service.h"
#include "spore/core/ApiServer.h"
#include "spore/core/TaskManager.h"

class HelloService : public Service {
public:
    HelloService() {}

    const char* getName() const override { return "HelloService"; }

    void registerEndpoints(ApiServer& api) override {
        api.registerEndpoint("/api/hello", HTTP_GET, [](AsyncWebServerRequest* req) {
            req->send(200, "application/json", "{\"message\":\"hello\"}");
        });
    }

    void registerTasks(TaskManager& taskManager) override {
        taskManager.registerTask("heartbeat", 1000, [this]() { this->heartbeat(); });
    } 

private:
    void heartbeat() {
        // e.g., blink LED, publish telemetry, etc.
    }
};

Spore spore({
    {"app", "my_app"},
    {"role", "controller"}
});

void setup() {
    spore.setup();
    spore.registerService(new HelloService());
    spore.begin();
}

void loop() {
    spore.loop();
}

Technical Specifications

• Supported Hardware: ESP-01/ESP-01S (1MB Flash), Wemos D1 (4MB Flash)
• Discovery Protocol: Discovery and heartbeat via UDP broadcast
• API Interface: RESTful HTTP + WebSocket and UDP streaming
• Dependencies: ESPAsyncWebServer, ArduinoJson
• Framework: Arduino with PlatformIO build system

Architecture & Role

SPORE Registry serves as the central firmware storage and management system for the SPORE ecosystem. It provides versioned storage for firmware binaries, enabling the Gateway to orchestrate firmware rollouts across cluster nodes. The registry integrates seamlessly with the Gateway's rollout system, providing the firmware binaries needed for over-the-air updates.

Storage Structure

Firmware is stored hierarchically in the file system:

registry/
├── base/
│   ├── 1.0.0/
│   │   └── firmware.bin
│   └── 1.1.0/
│       └── firmware.bin
└── sensor/
    └── 2.0.0/
        └── firmware.bin

This structure allows easy organization and access to firmware versions by name and version number.

Integration with Gateway

The registry is tightly integrated with the Gateway's rollout system:

• Firmware Lookup: Gateway queries the registry to find matching firmware for deployment
• Label Matching: Firmware can be organized with labels (app, role, target) for automated deployment
• Version Tracking: Registry maintains version history for rollback and audit purposes
• Binary Distribution: Gateway proxies firmware downloads to nodes during rollout
• Deployment Automation: Full integration with Gateway's rollout orchestration for cluster-wide updates

Usage Examples

# Upload firmware
curl -X POST http://localhost:3002/firmware \
  -F "metadata={\"name\":\"base\",\"version\":\"1.0.0\",\"labels\":{\"app\":\"base\"}}" \
  -F "firmware=@firmware.bin"

# List firmware
curl http://localhost:3002/firmware

# Download firmware
curl http://localhost:3002/firmware/base/1.0.0 -o firmware.bin

# Health check
curl http://localhost:3002/health

Environment Configuration

The registry supports the following configuration via environment variables:

• PORT: Server port (default: 3002)
• DB_PATH: Database file path (default: ./registry.db)
• REGISTRY_PATH: Firmware storage directory (default: registry)
• MAX_UPLOAD_SIZE: Maximum upload size in bytes (default: 32MB)

Technology Stack

• Language: Go (Golang)
• Database: SQLite for metadata storage
• Storage: File system for firmware binaries
• API: HTTP REST API with standard library net/http

Firmware Requirements

LEDLab requires SPORE nodes running the PixelStreamController firmware, which handles UDP-based RGB data streaming to NeoPixel strips and matrices. The firmware subscribes to udp/raw cluster events and converts incoming hex-encoded pixel data into real-time LED animations.

Key firmware features include support for both strip and matrix configurations, serpentine (zig-zag) wiring patterns, and configurable pixel counts, brightness, and matrix dimensions. The controller automatically remaps pixel coordinates for proper matrix display.

See PixelStream documentation for more information.

Capabilities

• Multi-node management with individual control
• Real-time canvas preview for each node
• 10+ built-in animation presets (rainbow, lava lamp, aurora, etc.)
• Visual preset editor with reusable building blocks
• Live parameter control with instant feedback
• Import/export custom presets as JSON
• Auto-discovery of SPORE nodes on network
• Configurable FPS (1-60) and matrix dimensions
• Requires SPORE nodes running PixelStreamController

Building Blocks