diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index b51452a..b28be0a 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -23,8 +23,8 @@ ### Animation Library -- [ ] **ANI-01**: Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color -- [ ] **ANI-02**: Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density +- [x] **ANI-01**: Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color +- [x] **ANI-02**: Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density - [x] **ANI-03**: RGBW-aware color handling for SK6812 (separate W channel) - [x] **ANI-04**: RGB color handling for WS2801 diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 6b6bf96..25062f1 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -73,7 +73,7 @@ Plans: Plans: - [x] 03-01-PLAN.md — Protocol encoders (DRGB/DRGBW/DNRGB + animation command), UDP sender, device stub completion -- [ ] 03-02-PLAN.md — Animation library (7 built-in types with AnimationBase ABC, registry, factory) +- [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 ### Phase 4: Timeline Editor @@ -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 | 1/3 | In Progress| | +| 3. Communication Protocol | 2/3 | In Progress| | | 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 a97df59..0731b25 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: executing -stopped_at: Completed 03-communication-protocol/03-01-PLAN.md -last_updated: "2026-04-06T21:43:45.010Z" +stopped_at: Completed 03-communication-protocol/03-02-PLAN.md +last_updated: "2026-04-06T21:48:33.912Z" last_activity: 2026-04-06 progress: total_phases: 7 completed_phases: 2 total_plans: 10 - completed_plans: 8 + completed_plans: 9 percent: 0 --- @@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-04-05) ## Current Position Phase: 03 (communication-protocol) — EXECUTING -Plan: 2 of 3 +Plan: 3 of 3 Status: Ready to execute Last activity: 2026-04-06 @@ -60,6 +60,7 @@ Progress: [░░░░░░░░░░] 0% | Phase 02-audio-engine P03 | 8min | 2 tasks | 5 files | | 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 | ## Accumulated Context @@ -92,6 +93,8 @@ Recent decisions affecting current work: - [Phase 03-communication-protocol]: TDD approach for protocol encoders: tests committed RED before implementation, ensuring coverage is meaningful - [Phase 03-communication-protocol]: 0xAC animation command marker chosen well above WLED 0x01-0x04 range — no firmware collision - [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 ### Pending Todos @@ -105,8 +108,8 @@ None yet. ## Session Continuity -Last session: 2026-04-06T21:43:45.002Z -Stopped at: Completed 03-communication-protocol/03-01-PLAN.md +Last session: 2026-04-06T21:48:33.906Z +Stopped at: Completed 03-communication-protocol/03-02-PLAN.md Resume file: None Next action: `/gsd:plan-phase 1` diff --git a/.planning/phases/03-communication-protocol/03-02-SUMMARY.md b/.planning/phases/03-communication-protocol/03-02-SUMMARY.md new file mode 100644 index 0000000..3dcca3f --- /dev/null +++ b/.planning/phases/03-communication-protocol/03-02-SUMMARY.md @@ -0,0 +1,107 @@ +--- +phase: 03-communication-protocol +plan: "02" +subsystem: animations +tags: [animation, rendering, tdd, python, fire2012, rainbow, chase, strobe, pulse] +dependency_graph: + requires: [] + provides: [lightsync.animations, ANIMATION_REGISTRY, create_animation, AnimationBase] + affects: [phase-04-timeline-editor, phase-05-live-execution] +tech_stack: + added: [colorsys (stdlib), math (stdlib), abc (stdlib), random (stdlib)] + patterns: [ABC inheritance, factory registry, TDD red-green, pure functions] +key_files: + created: + - lightsync/animations/__init__.py + - lightsync/animations/base.py + - lightsync/animations/solid_color.py + - lightsync/animations/chase.py + - lightsync/animations/pulse.py + - lightsync/animations/rainbow.py + - lightsync/animations/strobe.py + - lightsync/animations/color_wipe.py + - lightsync/animations/fire.py + - tests/test_animations.py + modified: [] +decisions: + - "chase reverse detection uses offset-not-multiple-of-period for reliable test assertion" + - "FireAnimation lazy-initializes heat array per led_count to support variable strip lengths" + - "speed parameter mapped differently per animation: pulse maps to period, strobe to Hz, chase/wipe to px/sec" +metrics: + duration: "3 min" + completed: "2026-04-06" + tasks_completed: 1 + files_changed: 10 +requirements: [ANI-01, ANI-02] +--- + +# Phase 03 Plan 02: Animation Library Summary + +**One-liner:** 7 animation types (solid_color, chase, pulse, rainbow, strobe, color_wipe, fire) as pure renderers with AnimationBase ABC, ANIMATION_REGISTRY, and create_animation() factory — all via TDD red-green cycle. + +## What Was Built + +The `lightsync/animations/` package provides all animation rendering for the LightSync system. Animations are pure computation: `render(t, led_count) -> list[tuple]`. No I/O, no networking — just pixel data generation that the protocol layer (Plan 01) encodes and sends. + +### AnimationBase ABC + +`lightsync/animations/base.py` defines the contract: +- `render(t: float, led_count: int) -> list[tuple]` — render at time t, returns list of (R,G,B) tuples +- `from_params(params: dict) -> AnimationBase` — construct from CueModel.params dict + +### 7 Animation Types + +| Animation | Algorithm | Key Params | +|-----------|-----------|------------| +| solid_color | Uniform fill | color, white | +| chase | Moving segment, modulo pattern | color, bg_color, speed, size, spacing, reverse | +| pulse | Sine-wave brightness oscillation | color, speed (maps to period 0.1-5.0s), min/max_brightness | +| rainbow | HSV hue cycle via colorsys | speed, period | +| strobe | On/off at 1-20 Hz | color, speed, duty_cycle | +| color_wipe | Progressive fill from start/end | color, speed, reverse | +| fire | Fire2012: cool+drift+spark+heat-color | cooling, sparking, speed | + +### Registry and Factory + +`ANIMATION_REGISTRY` maps all 7 names to classes. `create_animation(name, params)` raises `ValueError` for unknown types. + +## TDD Execution + +**RED phase:** `tests/test_animations.py` (24 tests) committed before any implementation. Tests failed with `ModuleNotFoundError`. + +**GREEN phase:** Implemented all 9 files. One test required a fix: `test_chase_reverse` initially used `t=1.5` which caused `offset % period == 0`, making fwd and rev identical. Fixed to use `t=0.05` (offset=3, not multiple of period=10). + +**Result:** 24/24 tests passing. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Chase reverse test used symmetrical t value** +- **Found during:** TDD GREEN phase verification +- **Issue:** At t=1.5 with speed=1.0, offset=90 which is a multiple of period=10, making forward and reverse chase produce identical pixel patterns +- **Fix:** Changed test t from 1.5 to 0.05 (offset=3, not multiple of period), which reliably distinguishes fwd vs reverse +- **Files modified:** tests/test_animations.py +- **Commit:** f4da956 + +## Known Stubs + +None. All 7 animation types fully implemented and rendering real pixel data. + +## Self-Check: PASSED + +Files: +- FOUND: lightsync/animations/__init__.py +- FOUND: lightsync/animations/base.py +- FOUND: lightsync/animations/solid_color.py +- FOUND: lightsync/animations/chase.py +- FOUND: lightsync/animations/pulse.py +- FOUND: lightsync/animations/rainbow.py +- FOUND: lightsync/animations/strobe.py +- FOUND: lightsync/animations/color_wipe.py +- FOUND: lightsync/animations/fire.py +- FOUND: tests/test_animations.py + +Commits: +- 920243f: test(03-02): add failing tests for animation library +- f4da956: feat(03-02): implement animation library — 7 types with registry and factory