spore-ledlab/docs/MULTI_NODE_UPDATE.md

Multi-Node Canvas Grid Update

Overview

The SPORE LEDLab interface has been redesigned to display all SPORE nodes simultaneously with individual canvases in a responsive grid layout. Each node can be controlled independently with its own preset and parameters.

Key Changes

1. UI Layout Redesign

Before:

• Single canvas display in center
• Node list in right sidebar
• Controls always visible in right sidebar

After:

• Full-width grid layout displaying all nodes
• Each node has its own canvas card
• Floating control panel appears when a node is selected
• Maximizes screen space for displaying multiple nodes

2. New Components

NodeCanvasGrid Component

• Location: /public/scripts/node-canvas-grid.js
• Purpose: Manages the grid of node canvases
• Features:
  • Displays all discovered SPORE nodes in a responsive grid
  • Each node card shows:
    • Node IP address
    • Connection status (connected/streaming)
    • Live canvas with streaming visualization
  • Click on any node to select it and show controls
  • Supports both individual node selection and broadcast mode
  • Real-time frame rendering for each node

Updated PresetControls Component

• Location: /public/scripts/preset-controls.js
• Changes:
  • Now works with floating control panel
  • Tracks parameters per node (using Map)
  • Restores node-specific settings when switching between nodes
  • Sends node-specific commands to server

3. CSS Styling

New Classes

• .matrix-grid-section - Full-width container for node grid
• .node-canvas-grid - CSS grid layout for node cards
• .node-canvas-item - Individual node card styling
  • Hover effects
  • Selected state (green border glow)
  • Streaming animation
• .floating-controls - Floating control panel
  • Appears when node is selected
  • Slides in from right (desktop) or bottom (mobile)
  • Closes when clicking X or deselecting node

Responsive Design

• Desktop: 3-4 columns based on screen width
• Tablet: 2-3 columns
• Mobile: 1-2 columns with controls sliding from bottom

4. Server-Side Multi-Node Streaming

Updated LEDLabServer Class

• Location: /server/index.js
• New Features:
  • nodeStreams Map: Tracks active streams per node
  • nodeConfigurations Map: Stores per-node settings
  • Simultaneous streaming to multiple nodes
  • Per-node preset instances and parameters

Key Methods Updated

• startPreset(presetName, width, height, nodeIp, parameters)

  • Now accepts nodeIp to target specific node
  • Supports initial parameter values

• stopStreaming(nodeIp)

  • Stops streaming for specific node or all nodes

• updatePresetParameter(parameter, value, nodeIp)

  • Updates parameters for specific node or broadcast to all

• streamFrameForNode(nodeIp)

  • Generates and sends frames for specific node
  • Multiple intervals running simultaneously

5. HTML Structure

Stream View (Main View)

<section class="matrix-grid-section">
  <div class="node-canvas-grid">
    <!-- Node cards dynamically created here -->
  </div>
</section>

<aside class="floating-controls">
  <!-- Control panel content -->
</aside>

6. User Workflow

1. Node Discovery

   • Nodes automatically discovered via UDP
   • Each node appears as a card in the grid

2. Node Selection

   • Click any node card to select it
   • Floating control panel appears
   • Node card highlights with green border

3. Configure Node

   • Select preset from dropdown
   • Adjust parameters with sliders
   • Changes apply only to selected node

4. Start Streaming

   • Click "Start Streaming" button
   • Node card shows "streaming" status
   • Canvas displays live animation

5. Multi-Node Operation

   • Select different node
   • Configure with different preset/parameters
   • Start streaming independently
   • Multiple nodes can stream simultaneously

6. Broadcast Mode

   • Click "Broadcast to All" button
   • Control panel shows "Broadcast to All"
   • Preset and parameters apply to all nodes

Technical Details

Per-Node State Management

Client-Side (PresetControls)

this.nodeParameters = new Map(); // nodeIp -> {presetName, parameters}

• Stores preset selection and parameters for each node
• Restores settings when switching between nodes
• Maintains independent state per node

Server-Side (LEDLabServer)

this.nodeStreams = new Map(); // nodeIp -> {preset, presetName, interval, matrixSize}
this.nodeConfigurations = new Map(); // nodeIp -> {presetName, parameters, matrixSize}

• Active streams run independently with separate intervals
• Configurations saved per node
• Multiple presets can run simultaneously

WebSocket Messages

Enhanced Messages

All streaming-related messages now include optional nodeIp field:

{
  type: 'startPreset',
  presetName: 'lava-lamp',
  width: 16,
  height: 16,
  nodeIp: '192.168.1.100', // or null for broadcast
  parameters: {speed: 1.5, scale: 2.0}
}

Frame Rendering

Each node has its own canvas with:

• Independent rendering context
• Automatic sizing based on container
• Serpentine pixel order support
• Glow effects for bright pixels
• Smooth animations

Benefits

1. Visual Overview - See all nodes at once
2. Independent Control - Each node can run different animations
3. Space Efficient - Responsive grid maximizes screen usage
4. Scalable - Works with 1-20+ nodes
5. Intuitive - Click to select, visual feedback
6. Flexible - Individual or broadcast mode

Backwards Compatibility

• Old single-stream API still supported
• Settings view unchanged
• Existing presets work without modification
• UDP discovery unchanged

File Changes Summary

New Files

• /public/scripts/node-canvas-grid.js - New component

Modified Files

• /public/index.html - Updated layout
• /public/styles/main.css - New grid and floating control styles
• /public/scripts/preset-controls.js - Per-node parameter tracking
• /public/scripts/ledlab-app.js - Initialize new component
• /server/index.js - Multi-node streaming support

Unchanged Files

• All preset files (/presets/*.js)
• /server/udp-discovery.js
• /public/scripts/framework.js
• /public/scripts/theme-manager.js
• /public/scripts/navigation.js

Testing Recommendations

1. Test with single node
2. Test with multiple nodes (2-4)
3. Test node selection and switching
4. Test broadcast mode
5. Test parameter independence
6. Test starting/stopping individual streams
7. Test responsive layout on different screen sizes
8. Test node disconnection/reconnection

Future Enhancements

• Drag to reorder nodes
• Group nodes for collective control
• Save/load multi-node scenes
• Node status graphs
• Performance metrics per node