feat: update readme
This commit is contained in:
277
README.md
277
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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user