diff --git a/public/assets/events.png b/public/assets/events.png new file mode 100644 index 0000000..98f93e0 Binary files /dev/null and b/public/assets/events.png differ diff --git a/public/assets/firmware.png b/public/assets/firmware.png index dfca4be..92d7a3b 100644 Binary files a/public/assets/firmware.png and b/public/assets/firmware.png differ diff --git a/public/index.html b/public/index.html index 886fb5f..eba223d 100644 --- a/public/index.html +++ b/public/index.html @@ -25,6 +25,8 @@
Overview Core + Gateway + Registry UI Apps Docs @@ -133,6 +135,199 @@ void loop() {
+
+
+

Gateway

+

Gateway service providing UDP-based node discovery, cluster management, and API endpoints

+

Repository: spore-gateway

+ +
+
+

Node Discovery

+

UDP-based discovery listens for heartbeat messages from SPORE nodes on port 4210 with automatic cluster membership

+
+
+

Cluster Management

+

Real-time node status tracking, primary node selection, and automatic failover for high availability

+
+
+

WebSocket Server

+

Real-time cluster updates and event broadcasting to all connected WebSocket clients

+
+
+

MQTT Integration

+

Subscribe to all MQTT topics and forward messages to WebSocket clients for unified event streaming

+
+
+

Rollout System

+

Orchestrated firmware updates across multiple nodes with parallel processing and progress tracking

+
+
+

Proxy API

+

Generic proxy calls to SPORE node capabilities with automatic failover and load balancing

+
+
+ +
+

Architecture & Integration

+

SPORE Gateway acts as the central orchestrator for the SPORE cluster, bridging the gap between SPORE nodes and the UI. It integrates seamlessly with the SPORE ecosystem and external systems through multiple protocols.

+
+ +
+

Core Components

+
    +
  • UDP Discovery: Listens on port 4210 for node heartbeats and maintains cluster membership in real-time
    • +
  • HTTP API Server: RESTful endpoints for cluster management, node control, and firmware operations
    • +
  • WebSocket Server: Broadcasts cluster updates, events, and rollout progress to all connected clients
    • +
  • MQTT Client: Optional integration to subscribe to MQTT brokers and forward messages via WebSocket
    • +
  • Registry Proxy: Integrates with spore-registry for firmware storage and retrieval
    • +
  • Failover Logic: Automatic primary node switching when nodes go offline
    • +
+
+ +
+

MQTT Integration

+

Enable MQTT integration to stream events from external IoT devices and systems:

+ 
# Start gateway with MQTT integration
+./spore-gateway -mqtt tcp://localhost:1883
+
+# With authentication
+MQTT_USER=username MQTT_PASSWORD=password \
+  ./spore-gateway -mqtt tcp://broker.example.com:1883
+

When enabled, the gateway subscribes to all MQTT topics (#) and forwards messages to connected WebSocket clients, allowing the UI to display both SPORE cluster events and external MQTT events in real-time.

+
+ +
+

Rollout Orchestration

+

The rollout system manages parallel firmware updates across multiple SPORE nodes:

+
    +
  • Automatic Node Discovery: Identifies matching nodes based on firmware labels and current versions
    • +
  • Parallel Processing: Updates multiple nodes simultaneously using goroutines
    • +
  • Real-time Progress: WebSocket broadcasts show update status for each node
    • +
  • Error Recovery: Continues rollout even if individual nodes fail
    • +
  • Registry Integration: Seamless integration with spore-registry for firmware storage
    • +
+
+ +
+

Technology Stack

+
    +
  • Language: Go (Golang)
    • +
  • Framework: Standard library net/http with Go 1.22 ServeMux
    • +
  • WebSocket: gorilla/websocket for real-time communication
    • +
  • MQTT: Eclipse Paho MQTT client library
    • +
  • Logging: Structured logging with logrus
    • +
  • Concurrency: Goroutines and channels for parallel operations
    • +
+
+
+
+ +
+
+

Registry

+

Storage backend and update server for managing versioned firmware binaries

+

Repository: spore-registry

+ +
+
+

Hierarchical Storage

+

Firmware binaries stored in hierarchical structure: registry/{name}/{version}/firmware.bin with semantic versioning support

+
+
+

SQLite Metadata

+

Metadata storage with labels for flexible querying, version management, and deployment tracking

+
+
+

REST API

+

Simple HTTP endpoints for upload, listing, download, and update operations with full CRUD support

+
+
+

Rollout Integration

+

Seamlessly integrated with Gateway for orchestrated firmware deployment across cluster nodes

+
+
+

Version Management

+

Semantic versioning support with unique name-version constraints and version history tracking

+
+
+

Label System

+

Flexible key-value labels for organizing and querying firmware by app, role, or custom attributes

+
+
+ +
+

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
    • +
+
+
+
+

UI

@@ -144,6 +339,10 @@ void loop() { Cluster monitoring view

Real-time cluster member overview with auto-discovery

+
+ Events visualization +

Real-time event flow visualization with interactive graph

+
Network topology visualization

Network topology visualization with node relationships

@@ -162,6 +361,8 @@ void loop() {

Features

-
+

Apps

Application suite built on SPORE

@@ -275,11 +476,30 @@ void loop() {

SPORE UI

+
+

SPORE Gateway

+ +
+
+

SPORE Registry

+ +

SPORE LEDLab

    @@ -302,6 +522,26 @@ void loop() { 
    # Build and flash firmware
 ./ctl.sh build target esp01
 ./ctl.sh flash target esp01
    +
+
+

SPORE Gateway

+ 
# Build and start
+go mod tidy
+go build
+./spore-gateway
+
+# With MQTT integration
+./spore-gateway -mqtt tcp://localhost:1883
+
+
+

SPORE Registry

+ 
# Build and start
+go mod download
+go run main.go
+
+# Or build and run
+go build -o spore-registry
+./spore-registry

SPORE UI

@@ -333,6 +573,8 @@ http://localhost:3000

Source: spore · + spore-gateway · + spore-registry · spore-ui · spore-ledlab