272 lines
7.0 KiB
Markdown
272 lines
7.0 KiB
Markdown
# SPORE LEDLab
|
|
|
|
LEDLab is a tool for streaming animations to LED matrices connected to SPORE nodes. Create visual effects with real-time parameter control and individual node management.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- **Multi-Node Management**: Control multiple SPORE nodes individually
|
|
- **Real-Time Preview**: See live canvas preview for each node
|
|
- **Dynamic Presets**: Choose from 10+ built-in animation presets
|
|
- **Live Parameter Control**: Adjust animation parameters in real-time
|
|
- **Auto-Discovery**: Automatically discovers SPORE nodes on the network
|
|
- **Modern UI**: Clean, responsive interface with dark/light theme support
|
|
|
|
## Architecture
|
|
|
|
### Server
|
|
|
|
The Node.js server provides the backend for SPORE LEDLab:
|
|
|
|
- **UDP Discovery**: Listens on port 4210 to automatically discover SPORE nodes
|
|
- **WebSocket API**: Real-time bidirectional communication with the web UI
|
|
- **Preset Management**: Manages animation presets with configurable parameters
|
|
- **Multi-Node Streaming**: Streams different presets to individual nodes simultaneously
|
|
- **Frame Generation**: Generates animation frames at configurable FPS (1-60)
|
|
- **Node State Management**: Tracks configuration and streaming state per node
|
|
|
|
### Web UI
|
|
|
|
The web interface provides an intuitive control panel:
|
|
|
|
- **Node Grid View**: Visual grid showing all discovered nodes with live canvas previews
|
|
- **Node Selection**: Click any node to open its control panel
|
|
- **Preset Selection**: Choose from available animation presets
|
|
- **Parameter Controls**: Real-time sliders and inputs for preset parameters
|
|
- **Matrix Configuration**: Configurable matrix dimensions (default: 16x16)
|
|
- **Settings Panel**: Test frames and matrix clearing utilities
|
|
- **Theme Support**: Toggle between dark and light themes
|
|
|
|
### Communication Flow
|
|
|
|
```
|
|
Web UI (Browser) <--WebSocket--> Server <--UDP--> SPORE Nodes
|
|
|
|
|
Preset Engine
|
|
|
|
|
Frame Generation (60fps)
|
|
```
|
|
|
|
## Build
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js (v14 or higher)
|
|
- npm (v6 or higher)
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository or navigate to the `spore-ledlab` directory:
|
|
|
|
```bash
|
|
cd spore-ledlab
|
|
```
|
|
|
|
2. Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
This will install:
|
|
- `express`: Web server framework
|
|
- `ws`: WebSocket library for real-time communication
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
spore-ledlab/
|
|
├── server/ # Backend server
|
|
│ ├── index.js # Main server & WebSocket handling
|
|
│ └── udp-discovery.js # UDP node discovery
|
|
├── presets/ # Animation preset implementations
|
|
│ ├── preset-registry.js
|
|
│ ├── base-preset.js
|
|
│ ├── rainbow-preset.js
|
|
│ ├── lava-lamp-preset.js
|
|
│ └── ...
|
|
├── public/ # Frontend web UI
|
|
│ ├── index.html
|
|
│ ├── scripts/ # JavaScript modules
|
|
│ └── styles/ # CSS stylesheets
|
|
└── package.json # Project dependencies
|
|
```
|
|
|
|
## Run
|
|
|
|
### Start the Server
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Or use the dev script (same as start):
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
The server will:
|
|
- Start the HTTP server on port 3000
|
|
- Initialize WebSocket server
|
|
- Begin UDP discovery on port 4210
|
|
- Serve the web UI at http://localhost:3000
|
|
|
|
### Access the Web UI
|
|
|
|
Open your browser and navigate to:
|
|
|
|
```
|
|
http://localhost:3000
|
|
```
|
|
|
|
### Configure SPORE Nodes
|
|
|
|
Ensure your SPORE nodes are:
|
|
1. Connected to the same network as the LEDLab server
|
|
2. Running firmware with PixelStreamController support
|
|
3. Listening on UDP port 4210
|
|
|
|
The nodes will automatically appear in the LEDLab grid view once discovered.
|
|
|
|
## Usage
|
|
|
|
### Basic Workflow
|
|
|
|
1. **Discover Nodes**: Wait for SPORE nodes to appear in the grid (auto-discovery runs every 5 seconds)
|
|
|
|
2. **Select a Node**: Click on any node in the grid to open the control panel
|
|
|
|
3. **Choose a Preset**: Select an animation preset from the dropdown menu
|
|
|
|
4. **Adjust Parameters**: Use sliders and inputs to modify animation parameters in real-time
|
|
|
|
5. **Start Streaming**: Click "Start Streaming" to begin sending frames to the selected node
|
|
|
|
6. **Stop Streaming**: Click "Stop Streaming" to halt the animation
|
|
|
|
### Available Presets
|
|
|
|
- **Rainbow**: Classic rainbow cycle effect
|
|
- **Lava Lamp**: Organic flowing blobs
|
|
- **Aurora Curtains**: Northern lights simulation
|
|
- **Bouncing Ball**: Physics-based bouncing ball
|
|
- **Circuit Pulse**: Digital circuit patterns
|
|
- **Meteor Rain**: Falling meteor trails
|
|
- **Nebula Drift**: Cosmic cloud effects
|
|
- **Ocean Glimmer**: Wave-like shimmer
|
|
- **Spiral Bloom**: Rotating spiral patterns
|
|
- **Voxel Fireflies**: 3D particle system
|
|
- **Wormhole Tunnel**: Depth tunnel effect
|
|
- **Fade Green-Blue**: Simple color fade
|
|
|
|
### Matrix Configuration
|
|
|
|
Default matrix size is 16x16 pixels. To change:
|
|
|
|
1. Click the ⚙️ Settings button
|
|
2. Navigate to the Settings view
|
|
3. Adjust Width and Height values
|
|
4. Click "Apply Changes"
|
|
|
|
### Testing
|
|
|
|
In the Settings view:
|
|
|
|
- **Send Test Frame**: Sends a checkerboard pattern to verify connectivity
|
|
- **Clear Matrix**: Turns off all LEDs on the selected node
|
|
|
|
## Configuration
|
|
|
|
### Server Configuration
|
|
|
|
Edit `server/index.js` to modify:
|
|
|
|
```javascript
|
|
const PORT = 3000; // HTTP/WebSocket port
|
|
const UDP_PORT = 4210; // UDP discovery port
|
|
const DEFAULT_FPS = 20; // Default frame rate
|
|
const MATRIX_WIDTH = 16; // Default matrix width
|
|
const MATRIX_HEIGHT = 16; // Default matrix height
|
|
```
|
|
|
|
### Adding Custom Presets
|
|
|
|
1. Create a new preset file in `presets/`:
|
|
|
|
```javascript
|
|
const BasePreset = require('./base-preset');
|
|
|
|
class MyCustomPreset extends BasePreset {
|
|
constructor(width, height) {
|
|
super(width, height);
|
|
this.name = 'My Custom Preset';
|
|
this.description = 'Description of my preset';
|
|
}
|
|
|
|
defineParameters() {
|
|
return {
|
|
speed: { type: 'range', min: 0.1, max: 5, step: 0.1, default: 1 },
|
|
color: { type: 'color', default: 'ff0000' }
|
|
};
|
|
}
|
|
|
|
update(frameCount) {
|
|
// Animation logic here
|
|
}
|
|
}
|
|
|
|
module.exports = MyCustomPreset;
|
|
```
|
|
|
|
2. Register it in `presets/preset-registry.js`:
|
|
|
|
```javascript
|
|
const MyCustomPreset = require('./my-custom-preset');
|
|
|
|
registerPreset('my-custom', MyCustomPreset);
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Nodes Not Appearing
|
|
|
|
- Verify nodes are on the same network
|
|
- Check firewall settings allow UDP port 4210
|
|
- Ensure nodes are running PixelStreamController firmware
|
|
|
|
### WebSocket Connection Issues
|
|
|
|
- Check browser console for errors
|
|
- Verify server is running on port 3000
|
|
- Try refreshing the browser
|
|
|
|
### Animation Not Streaming
|
|
|
|
- Select a node first by clicking on it
|
|
- Choose a preset from the dropdown
|
|
- Verify the node shows "streaming" status
|
|
|
|
## Technology Stack
|
|
|
|
**Backend:**
|
|
- Node.js
|
|
- Express.js (HTTP server)
|
|
- ws (WebSocket server)
|
|
- UDP (Node discovery and frame streaming)
|
|
|
|
**Frontend:**
|
|
- Vanilla JavaScript (ES6+)
|
|
- Component-based architecture
|
|
- CSS3 with CSS variables for theming
|
|
- Canvas API for visualization
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Credits
|
|
|
|
Based on the SPORE framework and uses styling/components from spore-ui.
|