14 KiB
14 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-communication-protocol | 01 | execute | 1 |
|
true |
|
|
Purpose: This is the wire contract that microcontrollers (Phase 7) will implement. All packet formats must be correct and tested before building anything on top. Output: lightsync/protocol/ package with encoders, UDP sender, and passing tests.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/03-communication-protocol/03-RESEARCH.mdFrom lightsync/devices/base.py:
class BaseDevice(ABC):
def __init__(self, config: DeviceConfig):
self.config = config
@property
def id(self): return self.config.id
@property
def led_count(self) -> int: return self.config.led_count
@abstractmethod
def encode_frame(self, pixels: list[tuple]) -> bytes: ...
@abstractmethod
def encode_animation_cmd(self, animation: str, params: dict) -> bytes: ...
@property
@abstractmethod
def bytes_per_pixel(self) -> int: ...
From lightsync/models/show.py:
class CueModel(BaseModel):
id: UUID = Field(default_factory=uuid4)
timestamp: float
mode: Literal["animation", "frame_sequence"] = "animation"
animation: str | None = None
params: dict[str, Any] = Field(default_factory=dict)
From lightsync/models/device.py:
StripType = Literal["sk6812", "ws2801", "generic"]
class DeviceConfig(BaseModel):
id: UUID = Field(default_factory=uuid4)
name: str
strip_type: StripType
led_count: int = Field(gt=0, le=1000)
ip: str
port: int = Field(ge=1, le=65535)
enabled: bool = True
Create `lightsync/protocol/drgb.py` with these exact constants and functions:
```python
WLED_PORT = 21324
PROTOCOL_DRGB = 2
PROTOCOL_DRGBW = 3
PROTOCOL_DNRGB = 4
TIMEOUT_BYTE = 2
DRGB_MAX_PX = 490 # (1472 - 2) // 3
DRGBW_MAX_PX = 367 # (1472 - 2) // 4
DNRGB_MAX_PX = 489 # (1472 - 4) // 3
```
Functions:
- `encode_drgb(pixels: list[tuple[int,int,int]]) -> bytes` — header [PROTOCOL_DRGB, TIMEOUT_BYTE] + RGB body, truncate at DRGB_MAX_PX
- `encode_drgbw(pixels: list[tuple[int,int,int,int]]) -> bytes` — header [PROTOCOL_DRGBW, TIMEOUT_BYTE] + RGBW body, truncate at DRGBW_MAX_PX
- `encode_dnrgb_packets(pixels: list[tuple[int,int,int]], start_index: int = 0) -> list[bytes]` — split into chunks of DNRGB_MAX_PX, each with 4-byte header using `struct.pack(">BBH", PROTOCOL_DNRGB, TIMEOUT_BYTE, idx)`. Use big-endian for start index per WLED spec.
Create `lightsync/protocol/animation_cmd.py` with:
```python
ANIM_CMD_MARKER = 0xAC
ANIM_CMD_VERSION = 1
ANIMATION_IDS = {
"solid_color": 0, "chase": 1, "pulse": 2, "rainbow": 3,
"strobe": 4, "color_wipe": 5, "fire": 6,
}
ANIMATION_NAMES = {v: k for k, v in ANIMATION_IDS.items()}
```
Functions:
- `encode_animation_cmd(animation: str, params: dict) -> bytes` — 16-byte packet:
Byte 0: 0xAC, Byte 1: version=1, Byte 2: animation type ID (from ANIMATION_IDS, raise ValueError if unknown),
Byte 3: flags (bit 0 = params.get("reverse", False)),
Bytes 4-7: struct.pack(">f", params.get("speed", 0.5)),
Bytes 8-10: primary color RGB from params.get("color", [0,0,0]),
Bytes 11-13: secondary color RGB from params.get("bg_color", [0,0,0]),
Byte 14: params.get("white", 0),
Byte 15: params.get("density", params.get("size", params.get("cooling", 0))) & 0xFF
- `decode_animation_cmd(data: bytes) -> dict` — inverse of encode. Returns {"animation": str, "params": dict} with speed, color, bg_color, white, density, reverse, flags.
Create `tests/test_protocol.py` with pytest tests covering all behaviors listed above.
class _NullProtocol(asyncio.DatagramProtocol):
def error_received(self, exc: Exception) -> None:
pass # UDP send errors non-fatal for LED 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),
)
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()
self._transport = None
@property
def is_running(self) -> bool:
return self._transport is not None
```
Update `lightsync/devices/sk6812.py` — replace the encode_animation_cmd stub:
- Add import: `from lightsync.protocol.animation_cmd import encode_animation_cmd as _encode_cmd`
- Replace `encode_animation_cmd` method body from `return b""` to `return _encode_cmd(animation, params)`
- Keep the existing `encode_frame` method unchanged.
Update `lightsync/devices/ws2801.py` — identical change:
- Add import: `from lightsync.protocol.animation_cmd import encode_animation_cmd as _encode_cmd`
- Replace `encode_animation_cmd` method body from `return b""` to `return _encode_cmd(animation, params)`
- Keep the existing `encode_frame` method unchanged.
from lightsync.devices.sk6812 import SK6812Device from lightsync.devices.ws2801 import WS2801Device from lightsync.models.device import DeviceConfig cfg = DeviceConfig(name='test', strip_type='sk6812', led_count=10, ip='127.0.0.1', port=21324) sk = SK6812Device(cfg) result = sk.encode_animation_cmd('solid_color', {'color': [255,0,0], 'white': 128}) assert len(result) == 16 and result[0] == 0xAC, f'SK6812 cmd failed: {result.hex()}' print(f'SK6812 encode_animation_cmd: {result.hex()} OK')
cfg2 = DeviceConfig(name='test2', strip_type='ws2801', led_count=10, ip='127.0.0.1', port=21324) ws = WS2801Device(cfg2) result2 = ws.encode_animation_cmd('chase', {'color': [0,255,0], 'speed': 0.7}) assert len(result2) == 16 and result2[0] == 0xAC, f'WS2801 cmd failed: {result2.hex()}' print(f'WS2801 encode_animation_cmd: {result2.hex()} OK') print('ALL OK') " <acceptance_criteria> - lightsync/protocol/udp_sender.py contains "class UDPSender" and "class _NullProtocol" - lightsync/protocol/udp_sender.py contains "def send(self, payload: bytes, ip: str, port: int)" - lightsync/protocol/udp_sender.py contains 'local_addr=("0.0.0.0", 0)' - lightsync/devices/sk6812.py contains "from lightsync.protocol.animation_cmd import encode_animation_cmd" - lightsync/devices/sk6812.py does NOT contain 'return b""' - lightsync/devices/ws2801.py contains "from lightsync.protocol.animation_cmd import encode_animation_cmd" - lightsync/devices/ws2801.py does NOT contain 'return b""' - SK6812Device.encode_animation_cmd("solid_color", {"color":[255,0,0]}) returns 16 bytes starting with 0xAC - WS2801Device.encode_animation_cmd("chase", {"color":[0,255,0]}) returns 16 bytes starting with 0xAC </acceptance_criteria> UDPSender class ready for integration into FastAPI lifespan. Both SK6812Device and WS2801Device produce real 16-byte animation command packets instead of empty stubs.
- `python -m pytest tests/test_protocol.py -v` — all protocol encoding tests pass - `python -c "from lightsync.protocol.drgb import encode_drgb, encode_drgbw, encode_dnrgb_packets; print('imports OK')"` — no import errors - `python -c "from lightsync.protocol.udp_sender import UDPSender; print('UDPSender OK')"` — no import errors - SK6812 and WS2801 encode_animation_cmd return 16-byte packets, not b""<success_criteria>
- WLED DRGB/DRGBW/DNRGB packets match spec byte layout
- DNRGB splits frames exceeding MTU into correct chunks with big-endian start indices
- Animation command 0xAC packets encode/decode round-trip for all 7 animation types
- UDPSender provides async start/stop lifecycle and synchronous send()
- Device stubs replaced with real encoding
- All tests pass </success_criteria>