Gitea-Admin/led-sync-studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
378620e0bb7319cc029d8d01124bfd23fe781875
led-sync-studio/.planning/research/PITFALLS.md
Claude c3680306ee docs: research complete
2026-04-03 12:14:03 +02:00

22 KiB
Raw Blame History

Domain Pitfalls: LED Sync Studio

Domain: Terminal-based LED choreography with ESP32 + WiFi + audio sync Researched: 2026-04-03 Overall confidence: HIGH — most pitfalls are well-documented in ESP32 community forums and official Espressif issue trackers

Critical Pitfalls

Mistakes that cause rewrites, hardware damage, or make the project non-functional.

Pitfall 1: WiFi Interrupts Corrupt RMT/Single-Wire LED Timing on ESP32-C3

What goes wrong: The SK6812 strip (single-wire NeoPixel-style protocol) is driven via the ESP32's RMT peripheral. On the ESP32-C3 (single core, RISC-V), the WiFi driver shares the same CPU core as RMT interrupt handling. Every ~1ms, the WiFi subsystem inserts an approximately 5 µs delay into the RMT signal stream — far beyond the 150 ns tolerance of WS2812/SK6812 timing. The result is flickering, wrong colors, or partial frame corruption. This is a documented, unsolved problem that appears repeatedly in FastLED, ESPHome, and ESP-IDF issue trackers as recently as February 2026.

Why it happens: The ESP32-C3 has one CPU core. The dual-core ESP32 can pin the LED task to core 1 and WiFi to core 0 — that workaround does not exist on the C3. RMT DMA helps but the DMA buffer can be too small, causing the RMT transmission to break into fragments with WiFi-induced gaps between them.

Consequences: Visible LED flicker whenever a WiFi packet is sent or received. Particularly bad when command acknowledgements and animation frames coincide. Makes music-reactive LED effects look broken even when the logic is correct.

Prevention:

  • Use the RMT peripheral with DMA enabled and set rmt_symbols (buffer size) large enough to hold an entire full frame in one transmission, avoiding mid-frame DMA refills.
  • Disable WiFi power saving (esp_wifi_set_ps(WIFI_PS_NONE)) — this reduces the most common interrupt spike pattern.
  • Consider a dedicated LED controller chip (e.g., WS2801 over SPI does not have this problem — it is clock-driven and tolerates interruptions).
  • For SK6812 specifically: test with WiFi transmitting at maximum rate before accepting the hardware works. Do not test LED timing with WiFi idle.
  • Watch the FastLED issue #1657 for ESP32-C3 specific fixes as the library evolves.

Detection: Flash a static color on SK6812, then send rapid JSON commands from Pi. If LEDs flicker during command bursts but are stable in silence, this pitfall is active.

Phase: Address in firmware foundation phase (Phase 1 of ESP32 work). Validate the RMT+WiFi coexistence before building any animation logic on top.

Pitfall 2: WS2801 SPI Speed vs. Long Cable Signal Integrity

What goes wrong: The WS2801 uses a clock-and-data SPI protocol. The 5m cable run (U-turn around a wardrobe = potentially 10m round trip for the signal ground loop) introduces capacitive load that degrades signal edges at higher SPI clock speeds. Additionally, the WS2801 5V version is documented as "low speed" — writing too fast causes the chip to hang or produce wrong colors. WiFi RF noise from the ESP32's antenna can also couple into the SPI data line if the cable is nearby and unshielded.

Why it happens: Long cables act as antennas and RC low-pass filters. SPI has no built-in re-synchronization — a degraded clock edge causes a wrong bit, and the error propagates through all subsequent LEDs in the chain.

Consequences: Corrupt colors on LEDs at the far end of the strip. Intermittent failures that appear at random (correlated with WiFi transmissions). Very hard to debug without an oscilloscope.

Prevention:

  • Set SPI clock to 1 MHz or lower for the WS2801 strip. The chip supports up to 25 MHz in theory, but 1–2 MHz is safe with long cables.
  • Use a 33Ω series resistor at the ESP32 end of the data and clock lines to dampen ringing.
  • Add a 100–470 µF capacitor across the 5V/GND power rails at the strip's input connector.
  • Route SPI cables away from the ESP32's antenna and WiFi power stages.
  • Use twisted pair for clock and data lines if possible.

Detection: Set all LEDs to a solid color; if far-end LEDs show wrong color or flicker only at the strip tail, this is signal integrity, not timing. Reduce SPI speed by half and retest.

Phase: Address in hardware wiring before firmware development. Document the working SPI clock speed in firmware config before writing animation code.

Pitfall 3: Sub-Second Choreography Sync Requires Absolute Timestamps, Not Relative Delays

What goes wrong: The intuitive approach to timeline execution is: "start playing the song, set a timer, fire events when timer reaches the event timestamp." In Python, time.sleep() drifts. asyncio event loop delays accumulate. Over a 3-minute song, drift of 100–200ms per minute is typical, meaning by the end of the song, animations fire 300–600ms late. This makes the choreography feel broken even though the logic is correct.

Why it happens: time.sleep() is a minimum sleep — the OS can wake the process later. Python's GIL, garbage collector pauses, and SSH I/O buffering all add latency. The Textual event loop also processes render and input events on the same loop, competing with timer callbacks.

Consequences: Animations gradually fall out of sync with song playback. The longer the song, the worse the drift. A ballistic "fire and forget" approach accumulates error permanently.

Prevention:

  • Use absolute timestamps throughout: record start_wall_time = time.monotonic() when playback begins, and for each event compute fire_at = start_wall_time + event.timestamp. Schedule based on fire_at - time.monotonic() to get the remaining sleep, recalculated fresh each time.
  • Use time.monotonic() not time.time() — monotonic is immune to NTP adjustments.
  • Run the choreography engine as a dedicated asyncio task that polls remaining time in a tight loop (sleep 1–5ms at a time) rather than a single long sleep.
  • Validate by logging actual fire times vs. expected: measure drift at 30s, 60s, 120s into a test song. Reject any implementation with drift > 20ms/minute.

Detection: Log time.monotonic() at each event fire and compare to the intended song timestamp. Drift that grows linearly over time confirms this pitfall.

Phase: Address in choreography engine milestone before adding any visual polish to the timeline editor.

Pitfall 4: WiFi Packet Jitter Makes "Fire-and-Forget" JSON Commands Unreliable for Music Sync

What goes wrong: JSON commands from the Pi to the ESP32 over WiFi arrive with variable latency. On a home network, typical UDP jitter is ±500 µs under idle conditions but can spike to 10–50ms when other WiFi clients are active or the ESP32's WiFi stack clusters packets. For commands tied to beat events (kick drum, chorus drop), a 50ms late arrival is perceptible as a missed sync.

Why it happens: The ESP32 WiFi stack has documented behavior where UDP packets cluster: they queue for 10–20ms then burst. Home 2.4GHz networks have contention with phones, smart home devices, and neighboring APs. There is no TCP-level retry in a UDP choreography protocol without explicit implementation.

Consequences: Commands arrive too late for beat-locked animations. If TCP is used instead, the TCP ACK round-trip adds another 5–15ms and TCP's Nagle algorithm can buffer small JSON packets, adding additional latency. The system works in testing (quiet network, idle ESP32) but fails in realistic conditions.

Prevention:

  • Use UDP, not TCP, for command delivery. TCP's Nagle algorithm and ACK round-trips are worse than UDP jitter for real-time choreography.
  • Disable Nagle if TCP is used: socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1).
  • Design the animation command protocol to be "early arrival tolerant": include the intended start timestamp in the JSON payload and have the ESP32 defer execution until that timestamp (using its own millis() clock synchronized via NTP or initial handshake).
  • Keep commands small (< 200 bytes) to avoid fragmentation.
  • Disable WiFi power saving on the ESP32: esp_wifi_set_ps(WIFI_PS_NONE).
  • For beat-detection live mode, accept that ~20ms jitter exists and design animations that look good with that tolerance (avoid hard-cut color changes on beat; prefer quick fades that mask ±20ms arrival variance).

Detection: Log send timestamp on Pi and receive timestamp on ESP32 (compare millis() after initial NTP sync). Plot the distribution. If 95th-percentile latency exceeds 50ms, the protocol needs redesign.

Phase: Address in communication protocol design before the live reactive mode milestone.

Moderate Pitfalls

Pitfall 5: ESP32-C3 Has No Second Core — Standard Dual-Core WiFi/LED Isolation Advice Does Not Apply

What goes wrong: Almost all ESP32 LED + WiFi tutorials, StackOverflow answers, and FastLED documentation recommend "pin the LED task to core 1, pin WiFi to core 0" as the solution for WiFi-induced LED flicker. The ESP32-C3 SuperMini has one core (RISC-V). This advice silently does nothing — xTaskCreatePinnedToCore(..., 1) on a single-core chip is accepted without error but has no effect.

Why it happens: ESP32-C3 is a cut-down variant. Its documentation is sometimes mixed with the dual-core ESP32 docs in tutorials.

Prevention:

  • Do not follow dual-core pinning advice for this hardware.
  • The correct mitigations for C3 are: RMT DMA with large buffers, WIFI_PS_NONE, and SPI (WS2801) for the strip that needs the most reliability.
  • Double-check any library or tutorial's target chip before applying its advice.

Detection: If CONFIG_FREERTOS_UNICORE is set in sdkconfig, you are on a single-core chip and core pinning is a no-op.

Phase: Firmware setup — verify chip variant before writing any FreeRTOS task pinning code.

Pitfall 6: Textual's Async Event Loop Blocks on Audio I/O if Not Isolated

What goes wrong: PipeWire/PulseAudio audio capture (via pyaudio or sounddevice) uses blocking reads or callbacks on a native thread. If the audio capture thread tries to update Textual widgets directly (e.g., calling self.app.query_one(...).update()), it bypasses Textual's thread safety model, causing race conditions, corrupted widget state, or deadlocks. The bug is intermittent and often appears only under load.

Why it happens: Textual runs on Python asyncio. Its widgets and reactive variables are not thread-safe. Audio libraries operate on OS-level audio threads outside asyncio.

Consequences: The app works during development (small audio buffers, idle system) but crashes or freezes in performance conditions (long choreography run, many beat events per second).

Prevention:

  • Run audio capture in a dedicated thread using Textual's self.run_worker(..., thread=True).
  • Never call Textual widget methods from the audio thread. Instead, use self.app.call_from_thread(callback) to marshal updates back to the asyncio event loop.
  • Use a queue.Queue to pass beat detection events from audio thread to the asyncio event loop, polled by an asyncio task.
  • Set the PipeWire quantum to 512 or 256 samples for low-latency capture (configures via pw-metadata or PIPEWIRE_QUANTUM environment variable).

Detection: Enable Python threading warnings. If RuntimeError: Non-thread-safe operation invoked on the event loop appears under load, this pitfall is active.

Phase: Audio integration milestone. Design the thread boundary upfront, not as a fix after the fact.

Pitfall 7: SK6812 is RGBW (4 bytes per LED), Not RGB (3 bytes)

What goes wrong: SK6812 RGBW LEDs have a white channel in addition to RGB, requiring 4 bytes of data per LED instead of 3. Code written assuming 3-byte RGB (as for WS2812B) will send incorrect data, corrupting color output for the entire strip after the first LED that is calculated wrong.

Why it happens: SK6812 is often listed alongside WS2812 as "NeoPixel-compatible." That is true for the protocol timing, but not for the data width. Library defaults may vary — some assume RGBW, some assume RGB.

Consequences: Colors appear shifted or incorrect. Animations that look correct for the first few LEDs gradually degrade. White channel stuck on or off.

Prevention:

  • Explicitly configure LED type as SK6812 (RGBW, 4 bytes/LED) in the firmware, not as WS2812 (RGB, 3 bytes/LED).
  • When designing animation color representations on the Pi side, include a W (white) channel in the JSON protocol from day one, even if it is always 0 initially. Adding it later requires a protocol version bump.
  • Total strip data frame size: 300 LEDs × 4 bytes = 1,200 bytes per frame. Account for this in RMT buffer sizing.

Detection: Set the first LED to pure red (255, 0, 0). If the second LED glows slightly (white channel bleed), the byte layout is wrong.

Phase: Firmware LED protocol definition — before any animation code is written.

Pitfall 8: Power Budget for 300 SK6812 + 160 WS2801 LEDs is Substantial

What goes wrong: SK6812 RGBW at full white: ~60 mA per LED. 300 LEDs × 60 mA = 18A peak. WS2801 RGB at full white: ~60 mA per LED. 160 LEDs × 60 mA = 9.6A peak. Combined theoretical maximum: ~27A at 5V. Even at 30% brightness, that is 8A. A single 5V/2A supply (or USB power) will cause brown-out resets on the ESP32, corrupt SPI/RMT signals due to voltage drooping, and potentially damage the power supply.

Why it happens: LED power calculations are done at 100% white brightness as a worst case. Developers assume "I'll keep brightness low" without enforcing it in firmware — but demo patterns often briefly hit full white.

Consequences: ESP32 brown-out reset mid-performance. Voltage droop corrupts LED data signals. Intermittent failures that look like software bugs.

Prevention:

  • Power each LED strip from a dedicated 5V supply rated for the strip's expected current, not from the ESP32's USB or VIN pin.
  • Implement a firmware-level brightness cap (e.g., max 40% = ~7A combined). This is a hard limit, not a default.
  • Add a 1000 µF capacitor at each strip's power input to absorb transient draws.
  • Run a separate ground wire from power supply to ESP32 GND alongside the LED power cables to avoid ground loops.
  • Use adequately sized wire: at 10A over 1m, use at minimum 20 AWG; prefer 18 AWG.

Detection: Measure voltage at the far end of the LED strip under full-on load. If it drops below 4.5V, the power delivery is inadequate.

Phase: Hardware setup — before any firmware is written. A brown-out during firmware development wastes hours of debugging time on a hardware problem.

Pitfall 9: JSON Protocol Evolution Without Versioning Causes Firmware/App Desync

What goes wrong: The Pi app and ESP32 firmware are developed in parallel. Early in development, the JSON command schema is simple. As features are added (new animation types, RGBW white channel, zone targeting, timing payloads), the schema grows. Without a version field, old firmware silently ignores unknown fields or misparses them — and there is no way to detect the firmware is out of date.

Why it happens: JSON is schema-less. Missing fields cause no error in most parsers. The developer assumes firmware and app are always in sync because they are updated together — until they are not.

Consequences: New animation commands do nothing on ESP32 without any error output. Debugging requires checking both Pi logs and ESP32 serial output simultaneously, which is slow over SSH.

Prevention:

  • Include a "protocol_version": 2 field in every command from day one.
  • Have the ESP32 respond with its supported protocol version on connection or on version mismatch.
  • Version the command schema in a shared document (even a comment in the firmware source) that is updated whenever the JSON structure changes.
  • Design the protocol to be forward-compatible: ESP32 ignores unknown fields rather than crashing, but logs a warning.

Detection: If adding a new animation parameter on the Pi side produces no change in LED behavior with no error, suspect a protocol version mismatch.

Phase: Communication protocol design milestone — add versioning from the first command sent.

Minor Pitfalls

Pitfall 10: Beat Detection Accuracy Degrades with Complex Mixes

What goes wrong: Simple FFT energy-threshold beat detection works well for 4/4 kick-heavy electronic music but fails on jazz, classical, or poly-rhythmic tracks. The beat detector fires on loud transients (cymbals, snare reverb) rather than the "felt" beat. False positives cause the LED to flash randomly, which looks worse than no sync at all.

Prevention:

  • Use a moving energy average comparison (current band energy vs. recent window average) rather than a global energy threshold. This adapts to track loudness.
  • Focus the beat detection on the sub-bass frequency band (20–200 Hz) for kick detection specifically.
  • Implement a "beat hold" period (minimum 200ms between beats) to filter double-trigger from reverb.
  • Expose the sensitivity and frequency band as user-adjustable parameters in the TUI, so the user can tune per song.
  • Accept that reactive mode is "best effort" and document it — the timeline/choreography mode is where precise sync is guaranteed.

Phase: Beat detection milestone — include a calibration UI from the start.

Pitfall 11: SSH Terminal Rendering Over Slow/High-Latency Link Causes Textual Frame Drops

What goes wrong: Textual renders full-screen TUI updates over SSH. On a high-quality local network SSH connection, this is fast. But Textual's default refresh rate may generate more terminal output than the SSH pipe can deliver, causing visible tearing, delayed input response, and excessive CPU usage on the Pi for SSH I/O.

Prevention:

  • Set a reasonable Textual refresh rate (e.g., 30 fps maximum) — Textual's REFRESH_RATE = 30 class variable.
  • Profile SSH I/O bandwidth: the Pi's sshd and the client terminal emulator both have buffer limits.
  • Test over a simulated degraded link (e.g., tc qdisc add dev lo root netem delay 20ms) to expose rendering issues before deployment.

Phase: TUI development — set refresh rate early; do not default to Textual's maximum.

Pitfall 12: ESP32-C3 SuperMini Flash is Only 4MB with ~1.25MB Usable for Firmware

What goes wrong: The ESP32-C3 SuperMini has 4MB flash but the default partition table allocates only approximately 1.25MB for the application. A firmware that includes WiFi, JSON parsing (ArduinoJson), FastLED/NeoPixel library, and multiple animation routines can approach this limit. Adding OTA update support requires a second app partition, halving available firmware space to ~600KB.

Prevention:

  • Build the firmware early and check its size before writing many animation effects. Use idf.py size or Arduino IDE's compilation output.
  • Use a custom partition table to allocate more flash to the app partition if OTA is not required.
  • Prefer lean libraries: ArduinoJson v7 is more compact than v6; avoid including unused animation effects.
  • Note: Some clone ESP32-C3 SuperMini boards have been found with no external flash at all (flash-less variants). Verify the chip markings match the ESP32-C3FH4 (which has embedded 4MB flash).

Phase: Firmware setup — check flash size and partition table before writing animation code.

Phase-Specific Warnings

Phase Topic Likely Pitfall Mitigation
ESP32 firmware init WiFi+RMT coexistence (Pitfall 1) Test WiFi+LED simultaneously on day 1 of firmware work
Hardware wiring Power budget / brown-out (Pitfall 8) Use dedicated 5V supply per strip before first flash
Hardware wiring WS2801 SPI signal integrity (Pitfall 2) Reduce SPI clock to 1 MHz, add series resistor
LED protocol definition SK6812 as RGBW not RGB (Pitfall 7) Explicit 4-byte configuration before any animation
Communication protocol JSON versioning (Pitfall 9) Version field in first command
Communication protocol WiFi jitter (Pitfall 4) UDP with timestamp payload, disable power saving
Choreography engine Timeline drift (Pitfall 3) Absolute timestamp scheduling, validate at 120s
Audio integration Textual thread safety (Pitfall 6) call_from_thread, queue.Queue boundary design
Beat detection False positives on complex tracks (Pitfall 10) Moving average + sub-bass focus + user tuning
TUI development SSH rendering throughput (Pitfall 11) Cap refresh rate at 30 fps
Firmware feature expansion Flash size limit (Pitfall 12) Check binary size early, custom partition table

Sources

Reference in New Issue View Git Blame Copy Permalink