207 lines
6.1 KiB
Markdown
207 lines
6.1 KiB
Markdown
# 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
|
|
|
|
### Capabilities
|
|
|
|
### 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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# Check for conflicting processes
|
|
netstat -tulpn | grep 4210
|
|
|
|
# Kill conflicting processes or change port in code
|
|
# Restart backend server
|
|
```
|
|
|
|
**Client Not Initialized**
|
|
```bash
|
|
# Check discovery status
|
|
curl http://localhost:3001/api/discovery/nodes
|
|
|
|
# Verify nodes are sending discovery messages
|
|
# Check network connectivity
|
|
```
|
|
|
|
#### Debug Commands
|
|
```bash
|
|
# 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
|
|
```
|