Files
jimmyandClaude Opus 5.5 24dd5ffb15 feat: ESP-NOW link, beat sync and control messages in the C++ driver
- espnow_link, ctrl_msg and beat_sync: the reliable link, envelopes and
  beat-synced timing.
- ctrl_msg: accept an envelope with the trailing save byte.
- patterns_frame() and espnow_link_poll() split out of their tasks, so the
  WebAssembly simulator can drive one frame and one link pass from a timer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 19:32:36 +13:00

5.3 KiB

LED Driver — MicroPython

MicroPython LED driver for ESP32: presets, patterns, Wi-Fi (TCP + UDP discovery) or ESP-NOW transport, optional HTTP polling, and dynamic pattern modules under src/patterns/.

Prerequisites

  • MicroPython firmware on the ESP32
  • USB cable for programming
  • Python 3 with pipenv (on the host, for dev.py / tests)

Setup

  1. Install dependencies:

    pipenv install
    
  2. Deploy to the device:

    pipenv run dev
    

Project layout

led-driver/
├── src/
│   ├── main.py          # Entry: Wi-Fi/TCP or ESP-NOW path, process_data(), manifest OTA
│   ├── presets.py       # Preset runtime + Presets class
│   ├── preset.py        # Single preset helpers
│   ├── settings.py      # settings.json
│   ├── hello.py         # UDP discovery (port 8766) / hello payloads
│   ├── http_poll.py     # Optional HTTP polling helper
│   ├── utils.py         # Colour conversion / ordering
│   ├── presets.json     # Default preset file (on device)
│   └── patterns/        # Pattern modules (.py), loaded dynamically
├── tests/               # Host-side helpers (e.g. udp_client.py, test_mdns.py)
├── test/                # On-device style pattern tests (all.py, patterns/)
├── dev.py               # Deploy / sync to serial device
├── docs/API.md          # Wire format (long keys); Pi app docs short keys
├── msg.json             # Sample message
├── Pipfile
└── LICENSE

Transport: settings.json transport_type is typically wifi (TCP to the Pi on port 8765, discovery on 8766) or espnow. ESP-NOW code paths are loaded only when needed so a Wi-Fi-only image stays smaller.

Further reading

  • docs/API.md — JSON message fields as used in examples (pattern, colors, …). The Pi app may send short keys (p, c, …); behaviour matches once normalised on device.

C++ app (ESP-IDF)

The cpp branch is an ESP-IDF app for the ESP32-C3 at the repo root (CMakeLists.txt, main/, web/). It drives a 119-LED WS2812 strip on GPIO 10 (set in main/patterns.cpp).

Web UI, access point and Wi-Fi client

The firmware runs three things at once:

  • Access point led-XXXXXX (the last three bytes of the MAC), open, no password. Join it and browse to http://192.168.4.1/.
  • Wi-Fi client: set a network from the Settings tab (scan, pick, enter password). Credentials are saved to NVS, and the client reconnects with backoff after a drop.
  • mDNS: once on a network, the device answers as http://led.local/.

Patterns: solid, rainbow, chase, breathe, blink, pulse, transition and circle. The web UI is embedded in the firmware from web/.

JSON API (port 80):

Method Path Purpose
GET /api/status Current pattern and parameters, AP name, client state and IP
POST /api/pattern {"mode","c1":[r,g,b],"c2":[r,g,b],"speed_ms","brightness"}
GET /api/wifi Saved client SSID and connection state
POST /api/wifi {"ssid","password"}: save and connect
GET /api/wifi/scan Visible networks

USB configuration (led-tool)

The JSON API above is also served on the USB serial port (/dev/ttyACM0, main/usb_cfg.cpp), so a driver can be set up without Wi-Fi. One line per request and per reply; every other line is log output:

@api {"id":1,"method":"GET","path":"/api/status"}
@api {"id":1,"status":200,"body":"{...}"}
@api {"id":2,"method":"POST","path":"/api/hardware","body":{"num_leds":60}}
@reboot

Requests run on the web server's task, with the same checks as the web UI. led-tool uses this automatically:

python cli.py -s
python cli.py -l 60 -o rgb --pin 10 -b 128 -n bar1

Open the port with DTR high and RTS low (RTS high with DTR low resets the chip).

Build and flash for the ESP32-C3:

. ~/.espressif/v6.1/esp-idf/export.sh
idf.py set-target esp32c3
idf.py build flash monitor

ESP-NOW (led-controller)

The driver takes part in an ESP-NOW rig run by led-controller (the same 0x4C wire protocol as the MicroPython drivers). It announces itself at boot, so the controller lists it with its name and LED count (transport: espnow), and then takes:

  • presets and selects, the brightness, device settings (device_config), the zones (group commands) and the startup preset, from v2/v3 envelopes and v1 JSON;
  • the controller's reliable messages: acknowledged, reassembled, duplicates dropped, state resynced by digest;
  • pings, and the beat for beat-timed presets (tb), which take their quarter-beat length from the controller's tempo.

Settings (GET/POST /api/espnow): enabled, and channel (1-13). ESP-NOW uses the radio's channel: the access point's, or the router's when the client is joined. Put the controller's bridge on the same channel. A client that is searching for a network that is not in range keeps the radio hopping channels, which breaks ESP-NOW; the access point gives it a fixed channel.

Saving Wi-Fi credentials (POST /api/wifi, or the Settings tab) switches to Wi-Fi mode: ESP-NOW is turned off and the driver restarts, then joins the saved network. Turn ESP-NOW back on with POST /api/espnow and a restart.

Not supported yet: OTA over ESP-NOW, the reverse (reversed) setting, and the lossy-link test mode.