98 lines
4.3 KiB
Markdown
98 lines
4.3 KiB
Markdown
# Phase 1: ESP32 Firmware - Context
|
|
|
|
**Gathered:** 2026-04-03
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
ESP32-C3 SuperMini firmware that drives two LED strips (WS2801 160 LEDs via SPI, SK6812 300 LEDs via RMT/RGBW) and accepts named animation commands over UDP/JSON from a Raspberry Pi. The ESP32 executes animations autonomously — no frame streaming.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Animation Design
|
|
- **D-01:** Animations use a palette-based color system with full RGBW support. Each animation accepts a color palette (1-N colors as RGBW arrays) plus effect-specific parameters (speed, intensity, direction).
|
|
- **D-02:** White channel (W) on SK6812 is auto-derived from RGB when not explicitly specified in the command. User can override W directly for warm/cool white effects.
|
|
- **D-03:** 8 initial animations: Chase, Pulse, Rainbow, Strobe, Color Wash, Breathe, Sparkle, Gradient Sweep. All must work on both strip types.
|
|
- **D-04:** Animation tick rate: 50fps (20ms per frame) as a FreeRTOS task. This is the animation engine update rate, not the LED refresh rate.
|
|
|
|
### JSON Protocol
|
|
- **D-05:** Flat JSON command structure: `{"zone":"schrank"|"wand"|"all", "animation":"chase", "params":{"speed":0.5, "intensity":1.0, "colors":[[255,0,128,0]]}}`. Zone field is mandatory.
|
|
- **D-06:** Additional commands: `{"cmd":"stop","zone":"all"}`, `{"cmd":"brightness","zone":"all","value":100}`, `{"cmd":"status"}` (returns JSON via UDP response).
|
|
- **D-07:** Unknown commands are ignored silently; errors logged to serial console for debugging.
|
|
- **D-08:** Protocol includes a `"v":1` version field in every command for future compatibility.
|
|
|
|
### Power & Safety
|
|
- **D-09:** Firmware-enforced brightness cap at 40% (configurable via JSON command, max 60%). Research flagged 27A peak at full brightness — dedicated 5V supplies per strip required.
|
|
- **D-10:** On WiFi disconnect: continue running the last animation. On reconnect: accept new commands immediately. No auto-off timeout.
|
|
- **D-11:** Startup behavior: boot with a subtle breathing animation (low brightness) to indicate firmware is alive and WiFi is connecting.
|
|
|
|
### Development Setup
|
|
- **D-12:** PlatformIO with Arduino framework. NeoPixelBus (RMT) for SK6812, hardware SPI for WS2801.
|
|
- **D-13:** ArduinoJson v7 for JSON parsing, AsyncUDP for WiFi command reception.
|
|
- **D-14:** Serial debug output for development. No OTA in Phase 1 — flash via USB.
|
|
|
|
### Claude's Discretion
|
|
- FreeRTOS task priorities and stack sizes
|
|
- Exact GPIO pin assignments (validate on hardware — ESP32-C3 SuperMini pinout constraints)
|
|
- DMA buffer sizing for RMT to mitigate WiFi interrupt interference
|
|
- WiFi reconnection strategy and timing
|
|
|
|
</decisions>
|
|
|
|
<canonical_refs>
|
|
## Canonical References
|
|
|
|
**Downstream agents MUST read these before planning or implementing.**
|
|
|
|
### Project Context
|
|
- `.planning/PROJECT.md` — Project vision, hardware specs (WS2801 160 LEDs Schrank, SK6812 300 LEDs Wand, ESP32-C3 SuperMini)
|
|
- `.planning/REQUIREMENTS.md` — FW-01 through FW-05 requirements
|
|
|
|
### Research
|
|
- `.planning/research/STACK.md` — NeoPixelBus RMT, ArduinoJson, PlatformIO recommendations
|
|
- `.planning/research/ARCHITECTURE.md` — Component boundaries, FreeRTOS task structure, data flow
|
|
- `.planning/research/PITFALLS.md` — WiFi+RMT coexistence on single-core C3, SK6812 RGBW 4-byte framing, power budget
|
|
|
|
</canonical_refs>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- None — greenfield project, no existing code
|
|
|
|
### Established Patterns
|
|
- None — first phase establishes firmware patterns
|
|
|
|
### Integration Points
|
|
- UDP port (to be defined) for Pi-to-ESP communication
|
|
- JSON protocol schema must be documented for Phase 2 (Pi-side transport client)
|
|
|
|
</code_context>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Hardware: ESP32-C3 SuperMini with WS2801 5m/160 LEDs (U-turn around Schrank) and SK6812 5m/300 LEDs (along wall)
|
|
- Both strips on one ESP32-C3 via different GPIO pins (SPI for WS2801, RMT for SK6812)
|
|
- Research warns: WiFi interrupts can corrupt SK6812 RMT timing on single-core C3 — must validate with `WIFI_PS_NONE` and proper DMA buffer sizing on day 1
|
|
- 1000uF capacitor at each strip input recommended
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope (auto mode)
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-esp32-firmware*
|
|
*Context gathered: 2026-04-03*
|