- 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>
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
pipenv install
|
|
```
|
|
|
|
2. Deploy to the device:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
. ~/.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.
|