The cpp branch is the ESP-IDF firmware; the MicroPython drivers are removed. Uncommitted MicroPython work was saved outside the repo before removal. Co-Authored-By: Claude Haiku 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 |
Build and flash for the ESP32-C3:
. ~/.espressif/v6.1/esp-idf/export.sh
idf.py set-target esp32c3
idf.py build flash monitor