Files

Claude 859f67a06d docs(07-01): complete firmware scaffold plan — SUMMARY, STATE, ROADMAP updated

- SUMMARY.md: firmware scaffold with boot/config/drivers/protocol/main
- STATE.md: plan 1 of 3 complete, 100% progress, decisions recorded
- ROADMAP.md: phase 7 marked Complete (3/3 plans with summaries)

2026-04-07 15:43:27 +00:00

11 KiB

Raw Blame History

gsd_state_version, milestone, milestone_name, status, stopped_at, last_updated, last_activity, progress

gsd_state_version

milestone

milestone_name

status

stopped_at

last_updated

last_activity

progress

1.0

v1.0

milestone

verifying

Completed 07-microcontroller-firmware/07-01-PLAN.md

2026-04-07T15:43:23.619Z

2026-04-07

total_phases	completed_phases	total_plans	completed_plans	percent
7	7	24	24	0

Project State

Project Reference

See: .planning/PROJECT.md (updated 2026-04-05)

Core value: Load a song, build a synchronized light show, play it back live — with precise control over every effect on every device. Current focus: Phase 07 — microcontroller-firmware

Current Position

Phase: 07 (microcontroller-firmware) — EXECUTING Plan: 3 of 3 Status: Phase complete — ready for verification Last activity: 2026-04-07

Progress: [░░░░░░░░░░] 0%

Performance Metrics

Velocity:

Total plans completed: 0
Average duration: —
Total execution time: 0 hours

By Phase:

Phase	Plans	Total	Avg/Plan
-	-	-	-

Recent Trend:

Last 5 plans: —
Trend: —

Accumulated Context

Decisions

Decisions are logged in PROJECT.md Key Decisions table. Recent decisions affecting current work:

Init: Web UI over TUI — richer DAW interactions while keeping terminal aesthetic via CSS
Init: python-mpv-jsonipc preferred over ctypes binding — no libmpv.dll dependency on Windows
Init: Firmware deferred to Phase 7 — protocol must be validated against simulator first
Init: undo/redo built in Phase 4 — retrofitting command pattern is expensive
[Phase 01-foundation]: Module-level state in main.py for registry/show_store — acceptable for Phase 1, Phase 2 migrates to Depends()
[Phase 01-foundation]: StaticFiles mounted last in create_app() — prevents catch-all interception of /api/* routes
[Phase 01-foundation]: encode_animation_cmd stubs return b'' — Phase 3 implements real UDP animation command encoding
[Phase 01-foundation]: redirect_slashes=False on FastAPI — StaticFiles at root intercepted API redirects
[Phase 01-foundation]: API collection routes use empty-string paths ('') not '/' — canonical /api/devices without redirect
[Phase 01]: window.removeDevice export required for ES module onclick compatibility — functions in type=module scripts are not global
[Phase 01]: CSS accent variable canonical naming: --accent is source of truth, aliases are text-accent and border-bright
[Phase 02-audio-engine]: MPV_AO env var controls audio output — null default for Docker server mode, overridable for local dev
[Phase 02-audio-engine]: 10Hz polling via time.sleep(0.1) over observe_property — observe_property fires per audio frame overwhelming asyncio
[Phase 02-audio-engine]: apply_timer_fix() as Linux no-op — timeBeginPeriod is Windows-only; INF-03 satisfied as platform-guarded stub
[Phase 02-audio-engine]: broadcast_loop accepts get_engine callable instead of direct import — avoids ws.py/main.py circular import
[Phase 02-audio-engine]: asyncio.to_thread for engine.load in REST endpoint — python-mpv-jsonipc load is synchronous, must not block event loop
[Phase 02-audio-engine]: AUD-02 (YouTube URL loading) deferred to Phase 6 — noted in docstring, not implemented in audio.py
[Phase 02-audio-engine]: ffmpeg subprocess pipe for MP3 waveform extraction (libsndfile/soundfile does not support MP3 natively)
[Phase 02-audio-engine]: Transport state driven by WebSocket tick — no frontend polling
[Phase 02-audio-engine]: Browser plays audio via HTML5 audio element — eliminates python-mpv, Docker libmpv dependency, and server-side position polling
[Phase 02-audio-engine]: librosa.beat.beat_track for beat detection — tempo + beat grid in one call, cached in app.state.beats by filepath
[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
[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
[Phase 04-timeline-editor]: Beats API uses 'beats' field not 'beat_times' — loadBeats() handles both with fallback
[Phase 04-timeline-editor]: TimelineCanvas auto-scroll at 80%/20% threshold — standard DAW follow behavior
[Phase 04-timeline-editor]: Revert-then-command pattern in _startMove: live drag updates block.timestamp for visual feedback; mouseup reverts to oldTimestamp then MoveBlockCommand executes — history always has correct before/after state
[Phase 04-timeline-editor]: setCurrentShowId() module-level function routes backend sync without coupling commands to app state
[Phase 04-timeline-editor]: BeatGrid stores raw beat_times unmodified — calibrationOffset subtracted only at getCalibratedBeats()/snap() time — offset slider works without corrupting base data
[Phase 04-timeline-editor]: BeatGrid.load() normalizes API field variants: beats/beat_times and tempo/tempo_bpm — actual API returns 'beats'/'tempo' not the plan's expected field names
[Phase 04-timeline-editor]: UpdateParamsCommand uses currentShowId (module-level var) not this._showId — matches existing command pattern in commands.js
[Phase 04-timeline-editor]: Color input fires 'change' not 'input' to create command — avoids flooding command history during native color picker drag
[Phase 05-live-show-execution]: WebSocket cue scheduler: LOOKAHEAD=60ms inline in tick handler, is_playing gate prevents pause/seek fires, seek rebuilds fired_ids via set comprehension
[Phase 05-live-show-execution]: active_cue tracks already-fired blocks within duration window so preview stays lit; past-cue threshold 100ms for silent skip without UDP dispatch
[Phase 05-live-show-execution]: Preview panel starts hidden (display:none), revealed to flex on show load — avoids empty panel before first show
[Phase 05-live-show-execution]: Strip color uses raw RGB from cue params, not CSS variables — data-driven per UI-SPEC Color section
[Phase 05-live-show-execution]: e.preventDefault() called first in every key branch — suppresses browser defaults before app logic
[Phase 05-live-show-execution]: Space on button elements explicitly skipped — prevents double-toggle with native button click
[Phase 05-live-show-execution]: Ctrl+S uses GET-then-POST round-trip to save current server show state, not in-memory timeline
[Phase 05-live-show-execution]: Audio element event listeners are correct hook for mouse play/pause WS messages — fire for all triggers (button/keyboard/programmatic), idempotent with wireKeyboard() sends
[Phase 06-ai-sync]: sys.executable -m yt_dlp used to avoid PATH issues in Docker container
[Phase 06]: yt-dlp --newline flag required for line-by-line progress parsing
[Phase 06-ai-sync]: Segment band drawing inserted between row banding and waveform in render() for correct Z-order
[Phase 06-ai-sync]: Auto segment count: max(4, min(12, int(duration / 30))) for typical songs
[Phase 06-ai-sync]: Heuristic always available as baseline; LLM opt-in via use_llm flag (D-04)
[Phase 06-ai-sync]: LLM generates from scratch, not post-processing heuristic output (D-06)
[Phase 06-ai-sync]: anthropic imported lazily inside llm_generate to avoid startup crash without API key
[Phase 07]: Inline _hsv_to_rgb replaces colorsys (not available in MicroPython)
[Phase 07]: bytearray for FireAnimation heat buffer avoids GC pressure on device
[Phase 07]: density field maps to size for chase, cooling for fire, ignored for others
[Phase 07]: Frame timeout (2s) reverts to last animation — matches WLED behavior, avoids idle black strip on packet loss
[Phase 07]: FrameAssembler keyed by absolute pixel index — tolerates out-of-order DNRGB chunks
[Phase 07-microcontroller-firmware]: No ABC module in MicroPython: LED driver interface enforced by convention not inheritance
[Phase 07-microcontroller-firmware]: select.poll(0) inside asyncio for non-blocking UDP — avoids monopolizing cooperative scheduler
[Phase 07-microcontroller-firmware]: Protocol parsers use only struct (stdlib) — testable on CPython without MicroPython device

Pending Todos

None yet.

Blockers/Concerns

Phase 2: python-mpv-jsonipc latency on Windows 11 under load is unbenchmarked — validate with timing harness in 02-01
Phase 4: librosa MP3 loading path on Windows needs explicit validation (soundfile falls back to audioread which requires FFmpeg on PATH)
Phase 6: AI sync approach (LLM-assisted) has no reference implementation — treat as spike, not commitment

Session Continuity

Last session: 2026-04-07T15:43:23.612Z Stopped at: Completed 07-microcontroller-firmware/07-01-PLAN.md Resume file: None

Next action: /gsd:plan-phase 1

11 KiB Raw Blame History