led-driver/docs/API.md

LED Driver API (message format)

This document describes the JSON message format for controlling LED driver devices. The same object is accepted from ESP-NOW (when that transport is enabled) and as one JSON value per line over TCP in Wi-Fi mode (see src/main.py on the device).

Message Format

All messages are JSON objects with the following structure:

{
  "v": "1",
  "presets": { ... },
  "select": { ... }
}

Version Field

• v (required): Message version, must be "1". Messages with other versions are ignored.

Presets

Presets define LED patterns with their configuration. Each preset has a name and contains pattern-specific settings.

Preset Structure

{
  "presets": {
    "preset_name": {
      "pattern": "pattern_type",
      "colors": ["#RRGGBB", ...],
      "delay": 100,
      "brightness": 127,
      "auto": true,
      "n1": 0,
      "n2": 0,
      "n3": 0,
      "n4": 0,
      "n5": 0,
      "n6": 0
    }
  }
}

Preset Fields

• pattern (required): Pattern type. Options:

  • "off" - Turn off all LEDs
  • "on" - Solid colour
  • "blink" - Blinking pattern
  • "rainbow" - Rainbow colour cycle
  • "pulse" - Pulse/fade pattern
  • "transition" - Colour transition
  • "chase" - Chasing pattern
  • "circle" - Circle loading pattern

• colors (optional): Array of hex colour strings (e.g., "#FF0000" for red). Default: ["#FFFFFF"]

  • Colours are automatically converted from hex to RGB and reordered based on device colour order setting
  • Supports multiple colours for patterns that use them

• delay (optional): Delay in milliseconds between pattern updates. Default: 100

• brightness (optional): Brightness level (0-255). Default: 127

• auto (optional): Auto mode flag. Default: true

  • true: Pattern runs continuously
  • false: Pattern advances one step per beat (manual mode)

• n1 through n6 (optional): Pattern-specific numeric parameters. Default: 0

  • See pattern-specific documentation below

Pattern-Specific Parameters

Rainbow

• n1: Step increment (how many colour wheel positions to advance per update). Default: 1

Pulse

• n1: Attack time in milliseconds (fade in)
• n2: Hold time in milliseconds (full brightness)
• n3: Decay time in milliseconds (fade out)
• delay: Delay time in milliseconds (off between pulses)

Transition

• delay: Transition duration in milliseconds

Chase

• n1: Number of LEDs with first colour
• n2: Number of LEDs with second colour
• n3: Movement amount on even steps (can be negative)
• n4: Movement amount on odd steps (can be negative)

Circle

• n1: Head movement rate (LEDs per second)
• n2: Maximum length
• n3: Tail movement rate (LEDs per second)
• n4: Minimum length

Select Messages

Select messages control which preset is active on which device. The format uses a list to support step synchronization.

Select Format

{
  "select": {
    "device_name": ["preset_name"],
    "device_name2": ["preset_name2", step_value]
  }
}

Select Fields

• select: Object mapping device names to selection lists
  • Key: Device name (as configured in device settings)
  • Value: List with one or two elements:
    • ["preset_name"] - Select preset (uses default step behavior)
    • ["preset_name", step] - Select preset with explicit step value (for synchronization)

Step Synchronization

The step value allows precise synchronization across multiple devices:

• Without step: ["preset_name"]

  • If switching to different preset: step resets to 0
  • If selecting "off" pattern: step resets to 0
  • If selecting same preset (beat): step is preserved, pattern restarts

• With step: ["preset_name", 10]

  • Explicitly sets step to the specified value
  • Useful for synchronizing multiple devices to the same step

Beat Functionality

Calling select() again with the same preset name acts as a "beat" - it restarts the pattern generator:

• Single-tick patterns (rainbow, chase in manual mode): Advance one step per beat
• Multi-tick patterns (pulse in manual mode): Run through full cycle per beat

Example beat sequence:

// Beat 1
{"select": {"device1": ["rainbow_preset"]}}

// Beat 2 (same preset = beat)
{"select": {"device1": ["rainbow_preset"]}}

// Beat 3
{"select": {"device1": ["rainbow_preset"]}}

Synchronization

Using "off" Pattern

Selecting the "off" pattern resets the step counter to 0, providing a synchronization point:

{
  "select": {
    "device1": ["off"],
    "device2": ["off"]
  }
}

After all devices are "off", switching to a pattern ensures they all start from step 0:

{
  "select": {
    "device1": ["rainbow_preset"],
    "device2": ["rainbow_preset"]
  }
}

Using Step Parameter

For precise synchronization, use the step parameter:

{
  "select": {
    "device1": ["rainbow_preset", 10],
    "device2": ["rainbow_preset", 10],
    "device3": ["rainbow_preset", 10]
  }
}

All devices will start at step 10 and advance together on subsequent beats.

Complete Example

{
  "v": "1",
  "presets": {
    "red_blink": {
      "pattern": "blink",
      "colors": ["#FF0000"],
      "delay": 200,
      "brightness": 255,
      "auto": true
    },
    "rainbow_manual": {
      "pattern": "rainbow",
      "delay": 100,
      "n1": 2,
      "auto": false
    },
    "pulse_slow": {
      "pattern": "pulse",
      "colors": ["#00FF00"],
      "delay": 500,
      "n1": 1000,
      "n2": 500,
      "n3": 1000,
      "auto": false
    }
  },
  "select": {
    "device1": ["red_blink"],
    "device2": ["rainbow_manual", 0],
    "device3": ["pulse_slow"]
  }
}

Message Processing

1. Version Check: Messages with v != "1" are rejected
2. Preset Processing: Presets are created or updated (upsert behavior)
3. Colour Conversion: Hex colours are converted to RGB tuples and reordered based on device colour order
4. Selection: Devices select their assigned preset, optionally with step value

Best Practices

1. Always include version: Set "v": "1" in all messages
2. Use "off" for sync: Select "off" pattern to synchronize devices before starting patterns
3. Beats for manual mode: Send select messages repeatedly with same preset name to advance manual patterns
4. Step for precision: Use step parameter when exact synchronization is required
5. Colour format: Always use hex strings ("#RRGGBB"), conversion is automatic

Error Handling

• Invalid version: Message is ignored
• Missing preset: Selection fails, device keeps current preset
• Invalid pattern: Selection fails, device keeps current preset
• Missing colours: Pattern uses default white colour
• Invalid step: Step value is used as-is (may cause unexpected behavior)

Notes

• Colours are automatically converted from hex strings to RGB tuples
• Colour order reordering happens automatically based on device settings
• Step counter wraps around (0-255 for rainbow, unbounded for others)
• Manual mode patterns stop after one step/cycle, waiting for next beat
• Auto mode patterns run continuously until changed