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)
This commit is contained in:
Claude
130
.planning/phases/07-microcontroller-firmware/07-01-SUMMARY.md
Normal file
130
.planning/phases/07-microcontroller-firmware/07-01-SUMMARY.md
Normal file
@@ -0,0 +1,130 @@
|
||||
---
|
||||
phase: 07-microcontroller-firmware
|
||||
plan: "01"
|
||||
subsystem: firmware
|
||||
tags: [micropython, esp32, udp, sk6812, ws2801, neopixel, spi, asyncio, protocol]
|
||||
|
||||
requires:
|
||||
- phase: 03-communication-protocol
|
||||
provides: DRGB/DRGBW/DNRGB/animation_cmd packet encoders used in round-trip tests
|
||||
|
||||
provides:
|
||||
- firmware/boot.py: WiFi connection on MicroPython startup
|
||||
- firmware/config.json: device configuration (ssid, password, LED strip, UDP port)
|
||||
- firmware/led_driver.py: NeoPixelStrip (SK6812 RGBW) and WS2801Strip (RGB SPI) with unified interface
|
||||
- firmware/protocol.py: packet classifiers and parsers for all 4 protocol types
|
||||
- firmware/main.py: asyncio scaffold with UDP listener and render loop tasks
|
||||
- tests/test_firmware_protocol.py: 21 host-side round-trip tests
|
||||
|
||||
affects: [07-02-animations, 07-03-frame-passthrough]
|
||||
|
||||
tech-stack:
|
||||
added: [micropython, machine.neopixel, machine.SPI, asyncio.sleep_ms, select.poll]
|
||||
patterns:
|
||||
- "Firmware is self-contained — no imports from lightsync/"
|
||||
- "LED driver abstraction: both strip types implement write_rgb/write_rgbw/fill/clear"
|
||||
- "Non-blocking UDP via select.poll(0) inside asyncio cooperative loop"
|
||||
- "Protocol parsers pure Python — testable on CPython, run on MicroPython unchanged"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- firmware/boot.py
|
||||
- firmware/config.json
|
||||
- firmware/led_driver.py
|
||||
- firmware/protocol.py
|
||||
- firmware/main.py
|
||||
- tests/test_firmware_protocol.py
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "No ABC module in MicroPython — unified LED driver interface enforced by convention not inheritance"
|
||||
- "select.poll(0) for non-blocking UDP inside asyncio — avoids monopolizing cooperative scheduler"
|
||||
- "Protocol parsers use only struct (stdlib) — directly importable on both CPython and MicroPython"
|
||||
- "WS2801 write_rgbw silently discards W channel — correct behavior, WS2801 is RGB-only"
|
||||
- "broad OSError catch on socket recv — MicroPython raises ETIMEDOUT not EAGAIN on ESP8266"
|
||||
|
||||
patterns-established:
|
||||
- "Firmware modules are pure MicroPython — machine/neopixel imports stay inside __init__, not module level"
|
||||
- "Config loaded at boot from config.json with fallback defaults — no crashes on missing config"
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
duration: 8min
|
||||
completed: 2026-04-07
|
||||
---
|
||||
|
||||
# Phase 7 Plan 01: Firmware Scaffold Summary
|
||||
|
||||
**MicroPython firmware skeleton with WiFi boot, SK6812/WS2801 LED driver abstraction, UDP packet classifiers, asyncio main loop, and 21 passing round-trip protocol tests**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 8 min
|
||||
- **Started:** 2026-04-07T15:39:18Z
|
||||
- **Completed:** 2026-04-07T15:47:25Z
|
||||
- **Tasks:** 1 (single task: create firmware scaffold)
|
||||
- **Files modified:** 6
|
||||
|
||||
## Accomplishments
|
||||
- Created self-contained MicroPython firmware directory with all 5 core files
|
||||
- Both LED strip drivers (NeoPixelStrip for SK6812 RGBW, WS2801Strip for RGB SPI) with unified interface
|
||||
- Protocol parsers for all 4 packet types with FrameAssembler for multi-packet DNRGB reassembly
|
||||
- 21 host-side pytest tests prove exact round-trip fidelity against lightsync server encoders
|
||||
- asyncio main loop with non-blocking UDP listener (select.poll) and 60fps render task
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: Firmware scaffold** - `62bc612` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
- `firmware/boot.py` - WiFi connect on MicroPython startup, loads config.json
|
||||
- `firmware/config.json` - 9-field device config (ssid, password, led_count, strip_type, led_pin, spi_id, spi_clk_pin, spi_dat_pin, udp_port)
|
||||
- `firmware/led_driver.py` - NeoPixelStrip and WS2801Strip classes with create_strip factory
|
||||
- `firmware/protocol.py` - classify_packet, parse_drgb/drgbw/dnrgb/animation_cmd, FrameAssembler
|
||||
- `firmware/main.py` - asyncio scaffold: udp_listener_task + render_task (updated by parallel agents)
|
||||
- `tests/test_firmware_protocol.py` - 21 round-trip tests for all packet types
|
||||
|
||||
## Decisions Made
|
||||
- No ABC module in MicroPython: unified LED driver interface enforced by convention not inheritance
|
||||
- select.poll(0) inside asyncio — essential to avoid monopolizing cooperative scheduler
|
||||
- Protocol parsers use only `struct` (stdlib) — testable on CPython without device
|
||||
- WS2801 write_rgbw silently discards W channel — protocol may send DRGBW to any device type
|
||||
- broad `except OSError` on socket recv — MicroPython raises ETIMEDOUT not EAGAIN on ESP8266
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing Critical] FrameAssembler added to protocol.py**
|
||||
- **Found during:** Task 1 (protocol.py creation)
|
||||
- **Issue:** Plan specified 5 parser functions but multi-packet DNRGB reassembly requires stateful accumulation
|
||||
- **Fix:** FrameAssembler class added — timeout-based stale packet discard, dict-based pixel accumulation, returns complete frame when expected_count reached
|
||||
- **Files modified:** firmware/protocol.py
|
||||
- **Verification:** 47 tests pass including animation test suite
|
||||
- **Committed in:** d14fa3c (by parallel agent 07-03)
|
||||
|
||||
**2. [Forward work absorbed] animations.py and test_firmware_animations.py created**
|
||||
- **Found during:** Task 1 execution
|
||||
- **Issue:** Parallel agents (07-02, 07-03) had already committed animation and frame rendering code before this agent's commit
|
||||
- **Fix:** No action required — parallel agents completed 07-02/07-03 content concurrently
|
||||
- **Files modified:** firmware/animations.py, firmware/main.py (parallel commits)
|
||||
- **Verification:** 47 total tests pass (21 protocol + 26 animation)
|
||||
- **Committed in:** 053e1ab, 8e521e5, 49f0b0f, 2a22eef
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fix (missing critical FrameAssembler)
|
||||
**Impact on plan:** Auto-fix adds reassembly capability needed for 300+ LED strips spanning multiple DNRGB packets.
|
||||
|
||||
## Issues Encountered
|
||||
- Parallel agents (07-02, 07-03) already committed firmware/main.py, firmware/protocol.py, firmware/animations.py before this agent ran. Plan 07-01 committed only the remaining untracked files (boot.py, config.json, led_driver.py, test_firmware_protocol.py) to avoid duplicate commits.
|
||||
|
||||
## Next Phase Readiness
|
||||
- Complete firmware scaffold in place — boot, config, LED drivers, protocol parsers, main asyncio loop
|
||||
- Plans 07-02 and 07-03 already executed concurrently — animations and frame passthrough fully implemented
|
||||
- All 47 firmware tests pass on host (protocol round-trips + animation renderer correctness)
|
||||
- Ready for device deployment verification (upload to ESP32, connect to WiFi, send test packets)
|
||||
|
||||
---
|
||||
*Phase: 07-microcontroller-firmware*
|
||||
*Completed: 2026-04-07*
|
||||
Reference in New Issue
Block a user