led-driver/docs/API.md

LED Driver ESPNow API Documentation

This document describes the ESPNow message format for controlling LED driver devices.

Message Format

All messages are JSON objects sent via ESPNow 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 color
  • "blink" - Blinking pattern
  • "rainbow" - Rainbow color cycle
  • "pulse" - Pulse/fade pattern
  • "transition" - Color transition
  • "chase" - Chasing pattern
  • "circle" - Circle loading pattern

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

  • Colors are automatically converted from hex to RGB and reordered based on device color order setting
  • Supports multiple colors 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 color 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 color
• n2: Number of LEDs with second color
• 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. Color Conversion: Hex colors are converted to RGB tuples and reordered based on device color 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. Color 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 colors: Pattern uses default white color
• Invalid step: Step value is used as-is (may cause unexpected behavior)

Notes

• Colors are automatically converted from hex strings to RGB tuples
• Color 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