One request per line on USB-Serial-JTAG (@api {"id","method","path","body"}),
one @api envelope back; @reboot restarts. Requests run on the httpd task
through the same dispatcher as the WebSocket, so the checks match the web UI
and never race an HTTP handler. Replies go out in chunks under a lock that log
output shares, so a reply over the TX buffer size isn't dropped and log lines
can't land inside one. The primary console moves to USB-Serial-JTAG.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
-
Install dependencies:
pipenv install -
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 tohttp://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