From e508f639d7baf33b9e29241502f892a82fe80aa0 Mon Sep 17 00:00:00 2001 From: 0x1d Date: Sat, 11 Oct 2025 22:02:03 +0200 Subject: [PATCH] feat: update readme --- README.md | 277 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 261 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 56199b2..60e9e92 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,271 @@ # SPORE LEDLab -LEDLab is a tool for streaming animations to SPORE nodes that implement the PixelStreamController. -SPORE LEDLab is a powerful tool for streaming animations to LED matrices connected to SPORE nodes. Create stunning visual effects with real-time parameter control and multi-node streaming capabilities. +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. ![ledlab](assets/ledlab.png) -## Components +## 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 -- listens on UDP port 4210 to discover SPORE nodes -- provides a websocket server API to interact with SPORE nodes over UDP -- can stream PixelStream presets either directly to a SPORE node or to all nodes using the UDP broadcast address -- preset parameters can be adjusted / configured on-the-fly directly through websockets -- if a websocket client is connected (UI), the stream is also sent to the websocket client -- can forward a stream received from websocket to UDP -- default matrix size is 16x16 pixels +The Node.js server provides the backend for SPORE LEDLab: -### Web-UI +- **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 -- default matrix size can be configured in the UI, default is 16x16 pixel -- shows canvas of the currently running stream (scaled up); the stream is received over websocket from the server -- preset selection: select any of the presets defined in the backend to be streamed (by the backend) to one or all SPORE nodes -- preset configuration: the parameters of a preset can be changed on-the-fly and changes the stream in realtime -- the UI is based on the spore-ui project and uses the same component framework and styling. components and other required JS files used in spore-ui are just copied over if needed +### 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.