Files
led-driver/README.md
T
jimmyandClaude Opus 5.5 762ec338bc feat: JSON API on the USB serial port for led-tool
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>
2026-11-11 22:34:36 +13:00

4.0 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