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
• 💾 State Preservation: Advanced UI state management that preserves user interactions during data refreshes
• ⚡ Smart Updates: Efficient partial updates that only refresh changed data, not entire components

Key Improvements

🆕 State Preservation System

• Expanded Cards: Cluster member cards stay expanded during data refreshes
• Active Tabs: Selected tabs in node detail views are maintained
• User Context: All user interactions are preserved across data updates
• No More UI Resets: Users never lose their place in the interface

🚀 Performance Enhancements

• Partial Updates: Only changed data triggers UI updates
• Smart Change Detection: System automatically detects when data has actually changed
• Efficient Rendering: Reduced DOM manipulation and improved responsiveness
• Batch Operations: Multiple property updates are handled efficiently

Screenshots

Cluster

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

Testing State Preservation

The framework includes a comprehensive test interface to demonstrate state preservation:

1. Expand cluster member cards to see detailed information
2. Change active tabs in node detail views
3. Trigger data refresh using the refresh buttons
4. Verify that all UI state is preserved during updates

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

Architecture Highlights

🏗️ Component Framework

• Base Component Class: Provides state management and partial update capabilities
• ViewModel Pattern: Separates data logic from UI logic
• Event-Driven Updates: Efficient pub/sub system for component communication
• State Persistence: Automatic preservation of UI state across data refreshes

🔄 Smart Update System

• Change Detection: Automatically identifies when data has actually changed
• Partial Rendering: Updates only the necessary parts of the UI
• State Preservation: Maintains user interactions during all updates
• Performance Optimization: Minimizes unnecessary DOM operations

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