spore-ui/README.md

SPORE UI

Zero-configuration web interface for monitoring and managing SPORE embedded systems.

Features

• 🌐 Cluster Monitoring: Real-time view of all cluster members with auto-discovery
• 📊 Node Details: Detailed system information including running tasks and available endpoints
• 🚀 OTA: Clusterwide over-the-air firmware updates
• 📱 Responsive: Works on all devices and screen sizes

Screenshots

Cluster

Topology

Firmware

Project Structure

spore-ui/
├── index.js                 # Express.js backend server
├── api/
│   └── openapi.yaml        # API specification
├── src/
│   └── client/             # SPORE API client library
│       ├── index.js        # Main client class
│       ├── package.json    # Client package info
│       ├── README.md       # Client documentation
│       └── example.js      # Usage examples
├── public/                 # Frontend files
│   ├── index.html         # Main HTML page
│   ├── styles.css         # All CSS styles
│   ├── framework.js       # Enhanced component framework with state preservation
│   ├── components.js      # UI components with partial update support
│   ├── view-models.js     # Data models with UI state management
│   ├── app.js             # Main application logic
│   └── test-state-preservation.html  # Test interface for state preservation
├── docs/
│   └── STATE_PRESERVATION.md  # Detailed documentation of state preservation system
└── README.md              # This file

Getting Started

1. Install dependencies: npm install
2. Start the server: npm start
3. Open in browser: http://localhost:3001
4. Test state preservation: http://localhost:3001/test-state-preservation.html

API Endpoints

• / - Main UI page
• /api/cluster/members - Get cluster member information
• /api/tasks/status - Get task status
• /api/node/status - Get system status
• /api/node/status/:ip - Get status from specific node

Technologies Used

• Backend: Express.js, Node.js
• Frontend: Vanilla JavaScript, CSS3, HTML5
• Framework: Custom component-based architecture with state preservation
• API: SPORE Embedded System API
• Design: Glassmorphism, CSS Grid, Flexbox

UDP Auto Discovery

The backend now includes automatic UDP discovery for SPORE nodes on the network. This eliminates the need for hardcoded IP addresses and provides a self-healing, scalable solution for managing SPORE clusters.

🚀 How It Works

1. UDP Server: The backend listens on port 4210 for UDP messages
2. Discovery Message: Nodes send CLUSTER_DISCOVERY messages to broadcast address 255.255.255.255:4210
3. Auto Configuration: When a discovery message is received, the source IP is automatically used to configure the SporeApiClient
4. Dynamic Updates: The system automatically switches to the most recently seen node as the primary connection
5. Health Monitoring: Continuous monitoring of node availability with automatic failover

📡 Discovery Protocol

• Port: 4210 (configurable via UDP_PORT constant)
• Message: CLUSTER_DISCOVERY (configurable via DISCOVERY_MESSAGE constant)
• Broadcast: 255.255.255.255:4210
• Protocol: UDP broadcast listening
• Auto-binding: Automatically binds to the specified port on startup

🔧 Setup Instructions

Backend Setup

# Start the backend server
npm start

# The server will automatically:
# - Start HTTP server on port 3001
# - Start UDP discovery server on port 4210
# - Wait for CLUSTER_DISCOVERY messages

Node Configuration

SPORE nodes should send discovery messages periodically:

# Recommended: Send every 30-60 seconds
# Message format: "CLUSTER_DISCOVERY"
# Target: 255.255.255.255:4210

🌐 Discovery Endpoints

Discovery Management

• GET /api/discovery/nodes - View all discovered nodes and current status
• POST /api/discovery/refresh - Manually trigger discovery refresh
• POST /api/discovery/primary/:ip - Manually set a specific node as primary
• POST /api/discovery/random-primary - Randomly select a new primary node

Health Monitoring

• GET /api/health - Comprehensive health check including discovery status

🧪 Testing & Development

Test Scripts

# Send discovery messages to test the system
npm run test-discovery broadcast

# Send to specific IP
npm run test-discovery 192.168.1.100

# Send multiple messages
npm run test-discovery broadcast 5

# Test random primary node selection
npm run test-random-selection

# Monitor discovery in real-time
npm run demo-discovery

Manual Testing

# Check discovery status
curl http://localhost:3001/api/discovery/nodes

# Check health
curl http://localhost:3001/api/health

# Manual refresh
curl -X POST http://localhost:3001/api/discovery/refresh

# Random primary selection
curl -X POST http://localhost:3001/api/discovery/random-primary

# Set specific primary
curl -X POST http://localhost:3001/api/discovery/primary/192.168.1.100

🔍 Troubleshooting

Common Issues

No Nodes Discovered

# Check if backend is running
curl http://localhost:3001/api/health

# Verify UDP port is open
netstat -tulpn | grep 4210

# Send test discovery message
npm run test-discovery broadcast

UDP Port Already in Use

# Check for conflicting processes
netstat -tulpn | grep 4210

# Kill conflicting processes or change port in code
# Restart backend server

Client Not Initialized

# Check discovery status
curl http://localhost:3001/api/discovery/nodes

# Verify nodes are sending discovery messages
# Check network connectivity

Debug Commands

# Check discovery status
curl http://localhost:3001/api/discovery/nodes

# Check health
curl http://localhost:3001/api/health

# Manual refresh
curl -X POST http://localhost:3001/api/discovery/refresh

# Set primary node
curl -X POST http://localhost:3001/api/discovery/primary/192.168.1.100