Files

Claude 6548a84ec1 docs(01-01): complete ESP32 firmware scaffold plan — awaiting hardware checkpoint

- 01-01-SUMMARY.md: dual strip driver, WiFi+RMT coexistence test scaffold
- STATE.md: advanced to plan 2, recorded GPIO/SPI/RMT decisions, 25% progress
- ROADMAP.md: phase 1 in-progress (1/4 plans)
- REQUIREMENTS.md: FW-01 marked complete

2026-04-03 13:18:37 +02:00

5.8 KiB

Raw Blame History

phase, plan, subsystem, tags, dependency_graph, tech_stack, key_files, decisions, metrics

phase

plan

subsystem

Phase 01 Plan 01: ESP32 Firmware Scaffold + WiFi+RMT Coexistence Test Summary

PlatformIO project scaffold with dual LED strip driver (WS2801 SPI 2MHz + SK6812 RMT DMA), WiFi initialization with WIFI_PS_NONE, and a hardware coexistence test harness for day-1 validation.

What Was Built

Files Created

File	Purpose
`firmware/platformio.ini`	PlatformIO build config for ESP32-C3 SuperMini with mandatory `-DESP32_ARDUINO_NO_RGB_BUILTIN` flag
`firmware/src/config.h`	All compile-time constants: GPIO pins, LED counts, brightness caps, UDP port, FreeRTOS priorities/stacks
`firmware/src/led_driver.h`	Strip type aliases + public API (initStrips, showBothStrips, setAll, applyBrightness)
`firmware/src/led_driver.cpp`	NeoPixelBus strip object definitions, concurrent show(), brightness clamping
`firmware/src/main.cpp`	Setup + WiFi connect + WIFI_PS_NONE + static loop with coexistence test procedure comments
`firmware/.gitignore`	Excludes `.pio/` build artifacts and `credentials.h`

Architecture Decisions Made

-DESP32_ARDUINO_NO_RGB_BUILTIN flag: Mandatory to prevent fatal CONFLICT! driver_ng is not allowed to be used with the legacy driver on Arduino ESP32 core 3.x when using NeoPixelBus legacy RMT driver.
GPIO3 for SK6812 RMT: Confirmed safe on ESP32-C3 SuperMini (no JTAG conflict). GPIO6/7 for WS2801 SPI with fallback note (GPIO0/1) if JTAG conflict found on hardware.
NeoWs2801Spi2MhzMethod: 2MHz SPI chosen for signal integrity over a 5m cable run (vs. default higher speeds).
stripWand.Show() before stripSchrank.Show(): RMT DMA starts non-blocking for SK6812; SPI blocks ~4ms — both complete within ~10ms window concurrently.
Brightness clamping to [0.0f, BRIGHTNESS_MAX]: Applied in both applyBrightnessW and applyBrightnessR before scaling, respecting the 40% hardware cap (D-09).

Key Interfaces Established for Plans 02 and 03

Strip Type Aliases (led_driver.h)

using StripWand    = NeoPixelBus<NeoGrbwFeature, NeoEsp32Rmt0Ws2812xMethod>;
using StripSchrank = NeoPixelBus<NeoRgbFeature, NeoWs2801Spi2MhzMethod>;

LED Driver API

void initStrips();
void showBothStrips();
void setAllWand(RgbwColor color);
void setAllSchrank(RgbColor color);
RgbwColor applyBrightnessW(RgbwColor c, float factor);
RgbColor  applyBrightnessR(RgbColor c, float factor);
extern StripWand    stripWand;    // direct access for animation engine (Plan 03)
extern StripSchrank stripSchrank;

Config Constants (config.h)

LED_COUNT_WAND = 300, LED_COUNT_SCHRANK = 160
BRIGHTNESS_CAP = 0.40f, BRIGHTNESS_MAX = 0.60f
UDP_PORT = 4210, ANIM_FPS = 50
FreeRTOS priorities: LED_OUTPUT=3, ANIM_TICK=2, WIFI_RECV=1

GPIO Pin Assignments

Signal	GPIO	Notes
SK6812 RMT data	GPIO3	RMT channel 0, confirmed safe on SuperMini
WS2801 SPI MOSI	GPIO7	Hardware SPI; fallback GPIO1 if JTAG conflict
WS2801 SPI CLK	GPIO6	Hardware SPI; fallback GPIO0 if JTAG conflict

Validation required on hardware — hardware may require fallback to GPIO0/GPIO1 for WS2801 if JTAG pins conflict.

Coexistence Test Status

Awaiting hardware checkpoint validation. The firmware is ready to flash. Developer must:

Fill in firmware/src/credentials.h with WiFi credentials
Run cd firmware && pio run — must compile without errors
Flash to ESP32-C3 SuperMini via pio run --target upload
Confirm serial output: "WIFI_PS_NONE set", IP address, both strips lit
Run 300-packet UDP burst at 10 pps for 30 seconds, observe zero flicker

Deviations from Plan

Auto-fixed Issues

None — plan executed exactly as written.

Note: credentials.h was correctly excluded from git (per firmware/.gitignore) rather than committed with placeholder values. This is the intended behavior — the gitignore entry is working correctly.

Commits

Task	Commit	Files
Task 1: PlatformIO scaffold + config.h	`6fe86bc`	firmware/platformio.ini, firmware/src/config.h
Task 2: LED driver	`55aea7a`	firmware/src/led_driver.h, firmware/src/led_driver.cpp
Task 3: main.cpp + gitignore	`88eb8d3`	firmware/src/main.cpp, firmware/.gitignore

Known Stubs

None — no UI rendering or placeholder data. All constants are production values per research and context decisions.

Self-Check: PASSED

firmware/platformio.ini exists: FOUND
firmware/src/config.h exists: FOUND
firmware/src/led_driver.h exists: FOUND
firmware/src/led_driver.cpp exists: FOUND
firmware/src/main.cpp exists: FOUND
firmware/.gitignore exists: FOUND
Commit 6fe86bc exists: FOUND
Commit 55aea7a exists: FOUND
Commit 88eb8d3 exists: FOUND

5.8 KiB Raw Blame History