docs(03): research communication protocol — WLED UDP spec, async sender, animation library

2026-04-06 21:28:01 +00:00
parent 37f483e880
commit 32ce615a63
1 changed files with 601 additions and 0 deletions
--- a/.planning/phases/03-communication-protocol/03-RESEARCH.md
+++ b/.planning/phases/03-communication-protocol/03-RESEARCH.md
@@ -0,0 +1,601 @@
 # Phase 3: Communication Protocol - Research
 **Researched:** 2026-04-06
 **Domain:** UDP networking, LED protocol encoding, animation library design, asyncio datagram sockets
 **Confidence:** HIGH
 ---
 ## Summary
 Phase 3 builds the wire protocol and animation library that microcontrollers will implement in Phase 7. The target is WLED-compatible UDP — specifically DRGB (full RGB frame), DRGBW (full RGBW frame), and DNRGB (multi-packet variant for large strips). The protocol is well-documented by the WLED project and has a fixed, binary byte layout. Nothing needs to be invented here: we adopt the WLED spec wholesale.
 The existing codebase already has the scaffolding Phase 3 needs. `BaseDevice` ABC is defined in `lightsync/devices/base.py` with `encode_frame` and `encode_animation_cmd` stubs. SK6812Device and WS2801Device exist with working pixel serialization but stub animation encoding. The device registry can instantiate live device objects. Phase 3 completes the stubs and adds the UDP transport layer on top.
 The two implementation risks are (1) multi-packet framing for large strips — DNRGB must split 300-LED RGBW frames (1200 bytes payload) across multiple 489-LED-per-packet chunks — and (2) defining a custom animation command packet format (the WLED protocol doesn't specify this; it's only for raw frames). Animation commands are custom binary messages Phase 7 firmware will parse.
 **Primary recommendation:** Use a single shared asyncio UDP socket (one `DatagramTransport`) with `sendto(data, addr)` calls to each device. No socket pool needed — UDP is connectionless and a single socket can send to N addresses without overhead. Implement the simulator as an asyncio UDP server on localhost using the same port convention (21324).
 ---
 ## Standard Stack
 ### Core
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | asyncio (stdlib) | 3.11 | Async UDP transport | No dependency, DatagramTransport handles non-blocking sends |
 | struct (stdlib) | 3.11 | Binary packet encoding | Correct byte-order packing, fast, zero dependency |
 | dataclasses / Pydantic | already in project | Animation parameter models | Pydantic already a dependency (pyproject.toml) |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | asyncio.DatagramProtocol | stdlib | UDP send/receive base class | Simulator receiver, optional transport wrapper |
 | typing.TypedDict | stdlib | Structured animation params | Lightweight param typing without full Pydantic model |
 ### Alternatives Considered
 | Instead of | Could Use | Tradeoff |
 |------------|-----------|----------|
 | asyncio DatagramTransport | asyncudp 0.10 | asyncudp adds nicer await-based API but adds a dependency for minimal gain |
 | struct.pack | manual bytearray | struct is faster, clearer, handles endianness correctly |
 | Pydantic for anim params | plain dicts | Plain dicts are fine for params since show.py CueModel already uses `dict[str, Any]` |
 No new dependencies required. All encoding and transport fits cleanly in stdlib asyncio + struct.
 ---
 ## Architecture Patterns
 ### Recommended Project Structure
 ```
 lightsync/
 ├── devices/
 │   ├── base.py          # BaseDevice ABC (already exists — extend, don't replace)
 │   ├── registry.py      # DeviceRegistry (already exists — add instantiate pool)
 │   ├── sk6812.py        # SK6812Device (already exists — fill encode_animation_cmd)
 │   ├── ws2801.py        # WS2801Device (already exists — fill encode_animation_cmd)
 │   └── udp_sender.py    # NEW: UDPSender — shared socket, send_frame / send_cmd
 ├── protocol/
 │   ├── __init__.py
 │   ├── drgb.py          # NEW: encode_drgb, encode_drgbw, encode_dnrgb
 │   ├── animation_cmd.py # NEW: encode_animation_cmd, decode_animation_cmd
 │   └── simulator.py     # NEW: asyncio UDP receiver + packet logger
 └── animations/
    ├── __init__.py
    ├── base.py          # NEW: AnimationBase ABC — render(t, led_count) -> list[tuple]
    ├── chase.py
    ├── pulse.py
    ├── rainbow.py
    ├── strobe.py
    ├── color_wipe.py
    ├── fire.py
    └── solid_color.py
 ```
 ### Pattern 1: Single Socket UDP Sender
 **What:** One asyncio DatagramTransport opened at app startup, held on `app.state`. All device sends use `transport.sendto(payload, (ip, port))`.
 **When to use:** Sending animation commands and pixel frames to N devices from a single FastAPI process.
 ```python
 # Source: Python docs asyncio-protocol.html
 import asyncio
 class _NullProtocol(asyncio.DatagramProtocol):
    """Minimal protocol — we only send, never receive on this socket."""
    def error_received(self, exc: Exception) -> None:
        pass  # UDP send errors are non-fatal for LED strip delivery
 class UDPSender:
    def __init__(self):
        self._transport: asyncio.DatagramTransport | None = None
    async def start(self) -> None:
        loop = asyncio.get_running_loop()
        self._transport, _ = await loop.create_datagram_endpoint(
            _NullProtocol,
            local_addr=("0.0.0.0", 0),  # OS assigns ephemeral port
        )
    def send(self, payload: bytes, ip: str, port: int) -> None:
        if self._transport:
            self._transport.sendto(payload, (ip, port))
    async def stop(self) -> None:
        if self._transport:
            self._transport.close()
 ```
 ### Pattern 2: WLED DRGB/DNRGB Packet Encoding
 **What:** Binary struct packing per the WLED spec. Two-byte header (type, timeout), then pixel data.
 **When to use:** Sending full pixel frames to WLED-compatible or LightSync firmware devices.
 ```python
 # Source: kno.wled.ge/interfaces/udp-realtime/
 import struct
 WLED_PORT = 21324
 PROTOCOL_DRGB  = 2
 PROTOCOL_DRGBW = 3
 PROTOCOL_DNRGB = 4
 TIMEOUT_BYTE   = 2  # seconds before device returns to normal mode
 # Max pixels per packet (stays under 1472 byte UDP payload limit)
 DRGB_MAX_PX   = 490   # 2 header + 490*3 = 1472
 DRGBW_MAX_PX  = 367   # 2 header + 367*4 = 1470
 DNRGB_MAX_PX  = 489   # 4 header + 489*3 = 1471
 def encode_drgb(pixels: list[tuple[int, int, int]]) -> bytes:
    """Full DRGB frame — up to 490 pixels."""
    header = bytes([PROTOCOL_DRGB, TIMEOUT_BYTE])
    body = bytearray()
    for r, g, b in pixels[:DRGB_MAX_PX]:
        body.extend([r & 0xFF, g & 0xFF, b & 0xFF])
    return header + bytes(body)
 def encode_drgbw(pixels: list[tuple[int, int, int, int]]) -> bytes:
    """Full DRGBW frame — up to 367 pixels."""
    header = bytes([PROTOCOL_DRGBW, TIMEOUT_BYTE])
    body = bytearray()
    for r, g, b, w in pixels[:DRGBW_MAX_PX]:
        body.extend([r & 0xFF, g & 0xFF, b & 0xFF, w & 0xFF])
    return header + bytes(body)
 def encode_dnrgb_packets(
    pixels: list[tuple[int, int, int]],
    start_index: int = 0,
 ) -> list[bytes]:
    """Split large RGB frame into DNRGB chunks, each under MTU."""
    packets = []
    for offset in range(0, len(pixels), DNRGB_MAX_PX):
        chunk = pixels[offset:offset + DNRGB_MAX_PX]
        idx = start_index + offset
        header = struct.pack(">BBH", PROTOCOL_DNRGB, TIMEOUT_BYTE, idx)
        body = bytearray()
        for r, g, b in chunk:
            body.extend([r & 0xFF, g & 0xFF, b & 0xFF])
        packets.append(header + bytes(body))
    return packets
 ```
 ### Pattern 3: Custom Animation Command Packet
 **What:** A custom binary packet format for sending "start animation X with params P" to a device. Not part of WLED spec — specific to LightSync firmware.
 **When to use:** Phase 5 live execution fires animation commands when cue timestamps are reached.
 Proposed format (all big-endian):
 ```
 Byte 0:    Protocol type = 0xAC (animation command marker, distinguishes from WLED)
 Byte 1:    Protocol version = 1
 Byte 2:    Animation type ID (0-6, see table below)
 Byte 3:    Flags (bit 0 = loop, bit 1 = reverse, bits 2-7 reserved)
 Bytes 4-7: Speed (float32 big-endian, range 0.0-1.0)
 Bytes 8-10: Primary color R, G, B
 Bytes 11-13: Secondary color R, G, B
 Byte 14:   White channel (for SK6812, 0 for RGB-only strips)
 Byte 15:   Density/length (0-255, animation-specific meaning)
 ```
 Animation type IDs:
 ```
 0 = solid_color
 1 = chase
 2 = pulse
 3 = rainbow
 4 = strobe
 5 = color_wipe
 6 = fire
 ```
 ### Pattern 4: Animation Base + Render Protocol
 **What:** Each animation is a class with a `render(t: float, led_count: int) -> list[tuple]` method. Pure computation, no I/O.
 **When to use:** Phase 3 generates frames for simulator validation; Phase 5 live execution calls render() in real-time.
 ```python
 from abc import ABC, abstractmethod
 class AnimationBase(ABC):
    """Pure animation renderer — no I/O, stateless or state-per-instance."""
    @abstractmethod
    def render(self, t: float, led_count: int) -> list[tuple]:
        """
        Render frame at time t (seconds since animation started).
        Returns list of (R, G, B) or (R, G, B, W) tuples, length == led_count.
        """
        ...
    @classmethod
    @abstractmethod
    def from_params(cls, params: dict) -> "AnimationBase":
        """Construct from CueModel.params dict."""
        ...
 ```
 ### Anti-Patterns to Avoid
 - **Creating one UDP socket per device:** Unnecessary OS resource usage. One socket can sendto() N addresses.
 - **Using TCP for LED data:** Adds head-of-line blocking; a dropped LED frame is better than blocking.
 - **Blocking socket calls in async context:** Never call `socket.send()` directly in a coroutine. Always use DatagramTransport.sendto().
 - **IP fragmentation of large frames:** Always split at the application layer using DNRGB multi-packet. Do not rely on OS fragmentation reassembly on WiFi hardware.
 - **Storing animation state in the packet spec:** Animation command packets are fire-and-forget commands, not streaming state machines. The microcontroller owns animation loop state after receiving the command.
 ---
 ## Don't Hand-Roll
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | Binary packing | Manual bytearray bit manipulation | `struct.pack(">BBH", ...)` | struct handles endianness, sign, alignment |
 | Fire animation math | Custom heat diffusion | Port Fire2012 algorithm (cooling + sparking) | FastLED Fire2012 is battle-tested on thousands of strips |
 | Rainbow hue cycling | Custom HSV math | `colorsys.hsv_to_rgb()` (stdlib) | stdlib handles edge cases, no dependency |
 | MTU calculation | Custom fragmentation logic | WLED DNRGB spec (489 px/packet) | Max values already calculated for standard Ethernet MTU 1500 |
 **Key insight:** The WLED protocol spec eliminates all packet design work. The only custom protocol element is the animation command packet (0xAC header), which is simple enough to implement with struct in ~30 lines.
 ---
 ## WLED Protocol Specification (HIGH confidence)
 Source: [kno.wled.ge/interfaces/udp-realtime/](https://kno.wled.ge/interfaces/udp-realtime/)
 ### Full Byte Layout
 **Common header (all protocols):**
 - Byte 0: Protocol type (1=WARLS, 2=DRGB, 3=DRGBW, 4=DNRGB)
 - Byte 1: Timeout in seconds (recommended: 2; 255=never timeout)
 **DRGB (type=2, max 490 LEDs):**
 ```
 [0x02][timeout][R0][G0][B0][R1][G1][B1]...[Rn][Gn][Bn]
 payload = 2 + led_count * 3 bytes
 ```
 **DRGBW (type=3, max 367 LEDs):**
 ```
 [0x03][timeout][R0][G0][B0][W0][R1][G1][B1][W1]...[Rn][Gn][Bn][Wn]
 payload = 2 + led_count * 4 bytes
 ```
 **DNRGB (type=4, max 489 LEDs per packet — multi-packet):**
 ```
 [0x04][timeout][start_hi][start_lo][R0][G0][B0]...[Rn][Gn][Bn]
 payload = 4 + chunk_led_count * 3 bytes
 start index is 16-bit big-endian (max 65535 LEDs addressable)
 ```
 ### MTU Math (verified)
 Standard Ethernet MTU = 1500 bytes
 IP header = 20 bytes, UDP header = 8 bytes
 Max UDP payload = 1472 bytes
 - DRGB max: (1472 - 2) / 3 = 490 LEDs
 - DRGBW max: (1472 - 2) / 4 = 367 LEDs
 - DNRGB max: (1472 - 4) / 3 = 489 LEDs per packet
 **SK6812 300-LED strip in DRGBW mode requires ceil(300/367) = 1 packet** — fits in MTU.
 **SK6812 300-LED RGBW payload = 2 + 300*4 = 1202 bytes — fits in single packet.**
 However, to stay compliant with DNRGB multi-packet splitting for arbitrarily large strips, Phase 3 MUST implement the chunked sender regardless — the UDP-03 requirement mandates it.
 ### Default Port
 WLED listens on UDP port **21324** (configurable in WLED settings). LightSync should use the same default for firmware compatibility.
 ---
 ## Animation Parameter Shapes
 All 7 required animation types with their parameters (ANI-01, ANI-02):
 ### solid_color
 ```python
 params = {
    "color": [r, g, b],      # Primary color RGB 0-255
    "white": 0,              # W channel for SK6812 (ANI-03)
 }
 ```
 ### chase
 ```python
 params = {
    "color": [r, g, b],
    "white": 0,
    "bg_color": [0, 0, 0],   # Background color
    "speed": 0.5,            # 0.0-1.0 (maps to px/sec)
    "size": 3,               # Lit pixel run length
    "spacing": 7,            # Dark gap after each run
    "reverse": False,
 }
 ```
 ### pulse
 ```python
 params = {
    "color": [r, g, b],
    "white": 0,
    "speed": 0.5,            # Period of one breath cycle (0.0-1.0 → 0.1-5.0 sec)
    "min_brightness": 0,     # Floor brightness 0-255
    "max_brightness": 255,   # Ceiling brightness 0-255
 }
 ```
 ### rainbow
 ```python
 params = {
    "speed": 0.5,            # Hue shift speed (0.0-1.0)
    "period": 1.0,           # How many full rainbow cycles fit on strip (1.0 = one cycle)
 }
 # No color param — rainbow defines its own color progression
 ```
 ### strobe
 ```python
 params = {
    "color": [r, g, b],
    "white": 0,
    "speed": 0.5,            # Flashes per second (maps to 1-20 Hz)
    "duty_cycle": 0.1,       # Fraction of period that LEDs are on (0.05-0.5)
 }
 ```
 ### color_wipe
 ```python
 params = {
    "color": [r, g, b],
    "white": 0,
    "speed": 0.5,            # Fill rate (0.0-1.0 → px/sec)
    "reverse": False,        # Direction: False = start→end, True = end→start
 }
 ```
 ### fire
 ```python
 params = {
    "cooling": 55,           # Heat loss per cycle — 20 (tall flames) to 100 (short flames)
    "sparking": 120,         # Probability of new spark (0-255) — 50 (flicker) to 200 (roaring)
    "speed": 0.5,            # Frame rate multiplier
 }
 # Uses Fire2012 algorithm: cool → drift up → spark → render heat as color
 # Color palette: black → red → yellow → white (heat intensity)
 ```
 **Common fields across all animations:**
 - `speed` (float 0.0-1.0): Normalized speed that each animation maps to its native unit
 - `color` ([R,G,B]): Primary color for animations that use it
 - `white` (int 0-255): W channel, only meaningful for SK6812 (ANI-03 / ANI-04)
 - `reverse` (bool): Direction flag where applicable
 ---
 ## Common Pitfalls
 ### Pitfall 1: DNRGB Start Index Byte Order
 **What goes wrong:** Encoding start index as little-endian instead of big-endian — simulator and firmware parse wrong start position.
 **Why it happens:** Python `struct.pack("<H", idx)` is the default C-style little-endian; WLED spec requires big-endian.
 **How to avoid:** Always use `struct.pack(">H", idx)` or `struct.pack(">BBH", type, timeout, idx)` for DNRGB header.
 **Warning signs:** Simulator logs show LED segments rendering at wrong strip positions.
 ### Pitfall 2: Single Socket Used Across Threads
 **What goes wrong:** DatagramTransport.sendto() called from a non-asyncio thread (e.g., from a sync endpoint) causes race conditions.
 **Why it happens:** asyncio transports are not thread-safe (documented in Python stdlib).
 **How to avoid:** Always call `sender.send()` from within the asyncio event loop using `loop.call_soon_threadsafe()` if bridging from sync code.
 **Warning signs:** Sporadic `RuntimeError: no running event loop` or corrupted packets.
 ### Pitfall 3: SK6812 Frame Mapped to DRGB Instead of DRGBW
 **What goes wrong:** SK6812 device sends DRGB packets — W channel silently dropped, strip shows wrong colors.
 **Why it happens:** `encode_frame()` returns correct bytes but the dispatch logic sends DRGB type byte (0x02) instead of DRGBW (0x03).
 **How to avoid:** Device dispatch must check `device.bytes_per_pixel` — 4 bytes → DRGBW, 3 bytes → DRGB. The type byte must match the data layout.
 **Warning signs:** Simulator shows 4 bytes per pixel in payload but type byte = 0x02.
 ### Pitfall 4: Animation Command Packet Conflicts with WLED Type Byte
 **What goes wrong:** If animation command type byte (0xAC) ever matches WARLS (0x01), DRGB (0x02), DRGBW (0x03), or DNRGB (0x04), WLED firmware would misparse it.
 **Why it happens:** Not reserving a clean namespace for the custom protocol.
 **How to avoid:** Use 0xAC (172) as the animation command marker — well clear of WLED's 0x01-0x04 range.
 ### Pitfall 5: Simulator Bound to Same Port as Sender
 **What goes wrong:** Simulator and the app both try to bind UDP port 21324 on the same machine — bind fails with `OSError: [Errno 98] Address already in use`.
 **Why it happens:** Simulator acts as receiver (needs to bind), app is sender (doesn't bind to destination port).
 **How to avoid:** Simulator binds to 0.0.0.0:21324. App sender socket uses `local_addr=("0.0.0.0", 0)` (OS assigns ephemeral source port). These don't conflict.
 ### Pitfall 6: Fire Animation Indexing Direction
 **What goes wrong:** Fire animation renders with flames at top instead of bottom, or runs at wrong speed.
 **Why it happens:** Python's natural list iteration goes index 0 → N; fire should rise from index 0 (bottom).
 **How to avoid:** Heat array index 0 = bottom of strip (floor/heat source), index N-1 = top. Sparks added at indices 0-2, heat drifts toward index N-1.
 ---
 ## Code Examples
 ### Asyncio UDP Simulator (Receiver)
 ```python
 # Source: Python docs asyncio-protocol.html (DatagramProtocol pattern)
 import asyncio
 import struct
 class SimulatorProtocol(asyncio.DatagramProtocol):
    PROTOCOL_NAMES = {1: "WARLS", 2: "DRGB", 3: "DRGBW", 4: "DNRGB", 0xAC: "ANIM_CMD"}
    def datagram_received(self, data: bytes, addr: tuple) -> None:
        if len(data) < 2:
            return
        proto_type = data[0]
        timeout = data[1]
        name = self.PROTOCOL_NAMES.get(proto_type, f"UNKNOWN(0x{proto_type:02X})")
        if proto_type == 2:  # DRGB
            led_count = (len(data) - 2) // 3
            print(f"[SIM] DRGB from {addr}: {led_count} LEDs, timeout={timeout}s")
        elif proto_type == 3:  # DRGBW
            led_count = (len(data) - 2) // 4
            print(f"[SIM] DRGBW from {addr}: {led_count} LEDs (RGBW), timeout={timeout}s")
        elif proto_type == 4:  # DNRGB
            start = struct.unpack_from(">H", data, 2)[0]
            led_count = (len(data) - 4) // 3
            print(f"[SIM] DNRGB from {addr}: {led_count} LEDs starting at {start}")
        elif proto_type == 0xAC:  # Animation command
            print(f"[SIM] ANIM_CMD from {addr}: {data[2:].hex()}")
 async def run_simulator(host: str = "0.0.0.0", port: int = 21324) -> None:
    loop = asyncio.get_running_loop()
    transport, _ = await loop.create_datagram_endpoint(
        SimulatorProtocol,
        local_addr=(host, port),
    )
    print(f"[SIM] Listening on {host}:{port}")
    try:
        await asyncio.sleep(float("inf"))
    finally:
        transport.close()
 ```
 ### Fire2012 Animation (Python Port)
 ```python
 # Source: FastLED Fire2012 algorithm (fastled.io/docs)
 import random
 import colorsys
 def fire_frame(
    heat: list[int],       # mutable heat array, length = led_count
    led_count: int,
    cooling: int = 55,
    sparking: int = 120,
 ) -> list[tuple[int, int, int]]:
    """One Fire2012 step. Mutates heat array. Returns RGB pixel list."""
    # Step 1: Cool every cell
    for i in range(led_count):
        cooldown = random.randint(0, (cooling * 10 // led_count) + 2)
        heat[i] = max(0, heat[i] - cooldown)
    # Step 2: Heat drifts up (index 0 = bottom)
    for i in range(led_count - 1, 1, -1):
        heat[i] = (heat[i - 1] + heat[i - 2] + heat[i - 2]) // 3
    # Step 3: Randomly ignite new sparks near bottom
    if random.randint(0, 255) < sparking:
        y = random.randint(0, 6)
        if y < led_count:
            heat[y] = min(255, heat[y] + random.randint(160, 255))
    # Step 4: Map heat to color (black → red → yellow → white)
    pixels = []
    for h in heat:
        if h < 85:
            pixels.append((h * 3, 0, 0))
        elif h < 170:
            h2 = h - 85
            pixels.append((255, h2 * 3, 0))
        else:
            h2 = h - 170
            pixels.append((255, 255, h2 * 3))
    return pixels
 ```
 ---
 ## Existing Code Integration (from Phase 1-2)
 Phase 3 builds directly on these existing files — do not replace them:
 | File | What Already Exists | Phase 3 Action |
 |------|---------------------|----------------|
 | `lightsync/devices/base.py` | `BaseDevice` ABC with `encode_frame`, `encode_animation_cmd`, `bytes_per_pixel` | Add `send_frame(sender)` method OR leave I/O in UDPSender |
 | `lightsync/devices/sk6812.py` | `encode_frame()` working, `encode_animation_cmd()` returns `b""` | Fill `encode_animation_cmd()` using struct |
 | `lightsync/devices/ws2801.py` | Same as SK6812 — frame works, cmd stub | Same — fill cmd stub |
 | `lightsync/devices/registry.py` | `instantiate(device_id)` creates live device | Use this in UDPSender to get device object for encoding |
 | `lightsync/models/show.py` | `CueModel` has `animation: str`, `params: dict[str, Any]` | Animation params dict shape must match ANI-02 param schemas |
 | `lightsync/models/device.py` | `StripType = Literal["sk6812", "ws2801", "generic"]` | No change needed — strip type determines DRGB vs DRGBW |
 **Important:** `encode_animation_cmd` stub in SK6812Device/WS2801Device currently returns `b""`. Phase 3 replaces these stubs with real struct packing using the 0xAC animation command format.
 The `app.state` pattern (established in Phase 2 for engine/beats) should be extended to hold `app.state.udp_sender: UDPSender` started in the FastAPI lifespan handler.
 ---
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | One socket per device | Single socket, sendto() per device | Always correct for UDP | Simpler, fewer OS resources |
 | Custom UDP protocol | WLED-compatible DRGB/DRGBW | WLED established ~2020 | Reuse WLED ecosystem clients; firmware Phase 7 has reference implementations |
 | Polling-based animation loop | Event-driven render-on-demand | N/A — this is Phase 3's new code | Render() called at cue time, not in background |
 **Deprecated/outdated:**
 - python-mpv: Removed in Phase 2 redesign — browser audio handles playback. No impact on Phase 3.
 ---
 ## Open Questions
 1. **Animation command: should direction be in the packet or only in params dict?**
   - What we know: CueModel.params is `dict[str, Any]` — flexible
   - What's unclear: Whether firmware should get `reverse` as a packet field or we just send a second animation ID for reversed variant
   - Recommendation: Include `flags` byte (bit 0 = reverse) in animation command packet — avoids doubling animation IDs
 2. **Should UDPSender retry on OS error?**
   - What we know: UDP is fire-and-forget; DatagramProtocol.error_received() is called on OS-level send errors
   - What's unclear: Whether LED strip devices on WiFi need any retry logic for dropped packets
   - Recommendation: No retry in Phase 3 — log errors only. Phase 5 can add retry if needed. Cue timing correctness matters more than delivery guarantee.
 3. **Simulator: standalone script or integrated FastAPI endpoint?**
   - What we know: Phase 3 requirement UDP-04 says "software UDP receiver/simulator for testing without physical hardware"
   - What's unclear: Whether it should be a background task in the app or a separate runnable
   - Recommendation: Implement as both — a background asyncio task startable via `lightsync/protocol/simulator.py` as a `__main__` runnable AND optionally started via FastAPI on a debug endpoint.
 ---
 ## Environment Availability
 No external dependencies beyond stdlib asyncio. All required packages are already in pyproject.toml (fastapi, pydantic, structlog). No new packages needed for Phase 3.
 | Dependency | Required By | Available | Version | Fallback |
 |------------|------------|-----------|---------|----------|
 | asyncio stdlib | UDP transport | Yes | Python 3.11 stdlib | — |
 | struct stdlib | Packet encoding | Yes | Python 3.11 stdlib | — |
 | colorsys stdlib | Rainbow hue math | Yes | Python 3.11 stdlib | — |
 | UDP port 21324 | Simulator receiver | Likely free | — | Use any open port in tests |
 **Missing dependencies with no fallback:** None.
 ---
 <phase_requirements>
 ## Phase Requirements
 | ID | Description | Research Support |
 |----|-------------|------------------|
 | UDP-01 | Animation command packet: device ID, animation type, params — sent when block starts | Custom 0xAC binary packet format specified; struct encoding pattern documented |
 | UDP-02 | Raw pixel frame packet: WLED DRGB/DNRGB/DRGBW protocol — used for AI-generated sequences | Full WLED spec documented with byte layout, confirmed from official kno.wled.ge docs |
 | UDP-03 | Multi-packet framing for frames >MTU (SK6812 300 LEDs RGBW = 1200 bytes, exceeds WiFi MTU) | DNRGB chunked encoding documented; MTU math confirmed (489 px per packet) |
 | UDP-04 | Software UDP receiver/simulator for testing without physical hardware | asyncio DatagramProtocol pattern documented; simulator code example provided |
 | ANI-01 | Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color | All 7 types specified with render approach and parameter shapes |
 | ANI-02 | Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density | Full param shapes documented for all 7 animation types |
 | ANI-03 | RGBW-aware color handling for SK6812 (separate W channel) | DRGBW packet uses 4 bytes/pixel (R,G,B,W); `white` param included in all animation param shapes |
 | ANI-04 | RGB color handling for WS2801 | DRGB packet uses 3 bytes/pixel; existing `WS2801Device.encode_frame()` already correct — needs only dispatch to use type=0x02 |
 </phase_requirements>
 ---
 ## Sources
 ### Primary (HIGH confidence)
 - [kno.wled.ge/interfaces/udp-realtime/](https://kno.wled.ge/interfaces/udp-realtime/) — Full WLED UDP protocol spec, byte layouts, protocol types, max LED counts
 - [docs.python.org/3/library/asyncio-protocol.html](https://docs.python.org/3/library/asyncio-protocol.html) — DatagramProtocol, DatagramTransport.sendto() API and thread safety notes
 - [fastled.io/docs — Fire2012 algorithm](https://fastled.io/docs/df/d28/_fire2012_8ino-example.html) — Canonical fire animation: cooling, sparking, heat diffusion
 ### Secondary (MEDIUM confidence)
 - [GitHub WLED wiki UDP-Realtime-Control](https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control) — Secondary source confirming protocol byte values
 - [WLED discourse: DRGB/DNRGB/WARLS differences](https://wled.discourse.group/t/drgb-dnrgb-warls-differences-best-set-up/688) — Community clarification on protocol selection
 - [CircuitPython LED Animation API](https://docs.circuitpython.org/projects/led-animation/en/latest/api.html) — Reference for animation parameter conventions (chase, color wipe, pulse, rainbow)
 ### Tertiary (LOW confidence)
 - WebSearch results on asyncio socket pool patterns — confirmed LOW: single socket with sendto() is the correct approach, no pool needed
 ---
 ## Metadata
 **Confidence breakdown:**
 - UDP wire protocol (WLED DRGB/DNRGB/DRGBW): HIGH — verified against official kno.wled.ge documentation
 - Animation command packet format (0xAC): MEDIUM — custom design, no external reference, but straightforward struct layout
 - Animation parameter shapes: MEDIUM — informed by Adafruit library conventions and Fire2012 spec, adapted to project requirements
 - Asyncio UDP patterns: HIGH — verified against Python stdlib docs
 - Fire animation algorithm: HIGH — FastLED Fire2012 is canonical reference implementation
 **Research date:** 2026-04-06
 **Valid until:** 2026-10-06 (WLED protocol is stable; Python asyncio API is stable)