diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index b28be0a..facf3e5 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -50,7 +50,7 @@ - [x] **UDP-01**: Animation command packet: device ID, animation type, params — sent when block starts - [x] **UDP-02**: Raw pixel frame packet: WLED DRGB/DNRGB/DRGBW protocol — used for AI-generated sequences - [x] **UDP-03**: Multi-packet framing for frames >MTU (SK6812 300 LEDs RGBW = 1200 bytes, exceeds WiFi MTU) -- [ ] **UDP-04**: Software UDP receiver/simulator for testing without physical hardware +- [x] **UDP-04**: Software UDP receiver/simulator for testing without physical hardware ### Automatic Sync diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 25062f1..9e65db4 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -14,7 +14,7 @@ Decimal phases appear between their surrounding integers in numeric order. - [x] **Phase 1: Foundation** - FastAPI skeleton, show file schema (Pydantic), device registry, terminal-aesthetic frontend shell (gap closure in progress) (completed 2026-04-05) - [x] **Phase 2: Audio Engine** - MPV IPC bridge, waveform rendering, playback controls, Windows timer fix (completed 2026-04-06) -- [ ] **Phase 3: Communication Protocol** - UDP packet spec, DRGB/DNRGB/DRGBW encoders, animation library, software simulator +- [x] **Phase 3: Communication Protocol** - UDP packet spec, DRGB/DNRGB/DRGBW encoders, animation library, software simulator (completed 2026-04-06) - [ ] **Phase 4: Timeline Editor** - DAW UI (tracks, drag-place blocks, resize, delete), undo/redo, beat detection, snap-to-beat - [ ] **Phase 5: Live Show Execution** - End-to-end show playback, seek-safe cue scheduling, show save/load, keyboard shortcuts, live preview - [ ] **Phase 6: AI Sync** - YouTube loading, AI-assisted show generation, beat calibration UI, structural segmentation @@ -74,7 +74,7 @@ Plans: Plans: - [x] 03-01-PLAN.md — Protocol encoders (DRGB/DRGBW/DNRGB + animation command), UDP sender, device stub completion - [x] 03-02-PLAN.md — Animation library (7 built-in types with AnimationBase ABC, registry, factory) -- [ ] 03-03-PLAN.md — UDP simulator, FastAPI integration, end-to-end protocol validation +- [x] 03-03-PLAN.md — UDP simulator, FastAPI integration, end-to-end protocol validation ### Phase 4: Timeline Editor **Goal**: The timeline editor is fully functional — users can place, move, resize, and delete animation blocks on per-device tracks with beat-snapping and undo/redo @@ -154,7 +154,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 |-------|----------------|--------|-----------| | 1. Foundation | 4/4 | Complete | 2026-04-05 | | 2. Audio Engine | 3/3 | Complete | 2026-04-06 | -| 3. Communication Protocol | 2/3 | In Progress| | +| 3. Communication Protocol | 3/3 | Complete | 2026-04-06 | | 4. Timeline Editor | 0/4 | Not started | - | | 5. Live Show Execution | 0/3 | Not started | - | | 6. AI Sync | 0/3 | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 0731b25..900b44f 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,15 +2,15 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone -status: executing -stopped_at: Completed 03-communication-protocol/03-02-PLAN.md -last_updated: "2026-04-06T21:48:33.912Z" +status: verifying +stopped_at: Completed 03-communication-protocol/03-03-PLAN.md +last_updated: "2026-04-06T21:52:27.756Z" last_activity: 2026-04-06 progress: total_phases: 7 - completed_phases: 2 + completed_phases: 3 total_plans: 10 - completed_plans: 9 + completed_plans: 10 percent: 0 --- @@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-04-05) Phase: 03 (communication-protocol) — EXECUTING Plan: 3 of 3 -Status: Ready to execute +Status: Phase complete — ready for verification Last activity: 2026-04-06 Progress: [░░░░░░░░░░] 0% @@ -61,6 +61,7 @@ Progress: [░░░░░░░░░░] 0% | Phase 02-audio-engine P03 | 4 | 9 tasks | 8 files | | Phase 03-communication-protocol P01 | 4min | 2 tasks | 8 files | | Phase 03-communication-protocol P02 | 3min | 1 tasks | 10 files | +| Phase 03-communication-protocol P03 | 2min | 2 tasks | 3 files | ## Accumulated Context @@ -95,6 +96,8 @@ Recent decisions affecting current work: - [Phase 03-communication-protocol]: UDPSender uses single shared asyncio DatagramTransport — no socket pool needed for UDP multi-device sends - [Phase 03-communication-protocol]: Chase reverse test uses offset-not-multiple-of-period for reliable assertion - [Phase 03-communication-protocol]: FireAnimation lazy-initializes heat array per led_count to support variable strip lengths +- [Phase 03-communication-protocol]: asyncio.run() test pattern chosen over pytest-asyncio — not installed, plan provided this fallback +- [Phase 03-communication-protocol]: UDPSender stopped before registry.save() in shutdown — orderly teardown, no sends after socket close ### Pending Todos @@ -108,8 +111,8 @@ None yet. ## Session Continuity -Last session: 2026-04-06T21:48:33.906Z -Stopped at: Completed 03-communication-protocol/03-02-PLAN.md +Last session: 2026-04-06T21:52:27.749Z +Stopped at: Completed 03-communication-protocol/03-03-PLAN.md Resume file: None Next action: `/gsd:plan-phase 1` diff --git a/.planning/phases/03-communication-protocol/03-03-SUMMARY.md b/.planning/phases/03-communication-protocol/03-03-SUMMARY.md new file mode 100644 index 0000000..b16a020 --- /dev/null +++ b/.planning/phases/03-communication-protocol/03-03-SUMMARY.md @@ -0,0 +1,75 @@ +--- +phase: 03-communication-protocol +plan: "03" +subsystem: protocol +tags: [udp, simulator, e2e-testing, fastapi, tdd] +dependency_graph: + requires: ["03-01", "03-02"] + provides: ["UDP simulator with packet logging", "UDPSender in FastAPI lifespan", "end-to-end protocol tests"] + affects: ["lightsync/main.py", "lightsync/protocol/simulator.py", "tests/test_e2e_protocol.py"] +tech_stack: + added: ["asyncio.DatagramProtocol for UDP simulation"] + patterns: ["TDD RED-GREEN", "asyncio.run() in tests (no pytest-asyncio)", "dataclass for structured packet logs"] +key_files: + created: + - lightsync/protocol/simulator.py + - tests/test_e2e_protocol.py + modified: + - lightsync/main.py +decisions: + - "asyncio.run() test pattern chosen over pytest-asyncio — not installed, plan explicitly provided this fallback" + - "SimulatorProtocol uses port=0 in tests — OS assigns free port, read back via get_extra_info('sockname')[1]" + - "UDPSender stopped before registry.save() in shutdown — orderly teardown, no sends after socket close" +metrics: + duration: "2 min" + completed_date: "2026-04-06" + tasks_completed: 2 + files_created: 2 + files_modified: 1 +--- + +# Phase 03 Plan 03: UDP Simulator and FastAPI Integration Summary + +**One-liner:** Async UDP simulator parses all 4 WLED packet types (DRGB/DRGBW/DNRGB/ANIM_CMD) with structured packet logging; UDPSender integrated into FastAPI lifespan; 7 end-to-end tests prove full animation-to-wire pipeline. + +## What Was Built + +### Task 1: UDP Simulator with Packet Logging (TDD) + +`lightsync/protocol/simulator.py` — a `SimulatorProtocol(asyncio.DatagramProtocol)` that: +- Parses DRGB (0x02): extracts `led_count = (len(data)-2) // 3` +- Parses DRGBW (0x03): extracts `led_count = (len(data)-2) // 4` +- Parses DNRGB (0x04): extracts big-endian uint16 start index at bytes 2-3, `led_count = (len(data)-4) // 3` +- Parses ANIM_CMD (0xAC): calls `decode_animation_cmd`, stores result in `PacketLog.decoded` +- Stores all received packets as `PacketLog` dataclasses for test assertions + +`tests/test_e2e_protocol.py` — 7 end-to-end tests using `asyncio.run()`: +- `test_e2e_drgb_10_pixels` — DRGB 10 pixels, led_count verified +- `test_e2e_drgbw_10_pixels` — DRGBW 10 pixels, led_count verified +- `test_e2e_dnrgb_600_pixels` — 600-LED frame splits into 2 packets, start_indices 0 and 489 +- `test_e2e_animation_cmd_chase` — animation command round-trip, decoded animation=="chase" +- `test_e2e_full_pipeline` — solid_color render -> encode_drgb -> send -> 20-LED DRGB frame verified +- `test_e2e_sk6812_rgbw_pipeline` — solid_color -> RGBW encode -> DRGBW 15-LED frame verified +- `test_simulator_standalone_import` — run_simulator importable without error + +TDD flow: RED commit (failing import) -> GREEN commit (simulator implemented, all 7 pass). + +### Task 2: UDPSender into FastAPI Lifespan + +`lightsync/main.py` updated: +- Added `from lightsync.protocol.udp_sender import UDPSender` import +- Lifespan startup: `UDPSender()` created, `await udp_sender.start()`, assigned to `app.state.udp_sender` +- Lifespan shutdown: `await app.state.udp_sender.stop()` before `await registry.save()` +- All existing lifespan code unchanged (beats cache, registry, show_store) + +## Deviations from Plan + +None — plan executed exactly as written. + +## Known Stubs + +None — all implemented functionality is fully wired. + +## Self-Check: PASSED + +See below.