Files
led-tool/README.md
T
jimmyandClaude Opus 5.5 f5ab256b4a feat: configure the ESP-IDF led-driver over USB
idf_device.py talks to the driver's USB API (led-driver main/usb_cfg.cpp).
--driver auto (default) asks the port first and falls back to mpremote.
Existing flags map to the driver's API (-s, --pin, -l, -o, -b, --preset,
--default, --ssid/--wifi-password, -n, -r, -f); new ESP-IDF flags cover
the rest of the network settings (--ap, --ap-ssid, --ap-password, --ddp,
--dhcp, --static, --dns), --max-brightness and --scan. Opening the port
keeps DTR high so connecting doesn't reset the C3.

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

3.8 KiB
Raw Blame History

led-tool

CLI helpers for MicroPython LED devices: settings.json download/upload via mpremote, resets, follow/tail, recursive uploads, optional firmware flash, and led-driver-oriented flags (presets, transport, Wi-Fi fields).

Connection is always via -p / --port (default /dev/ttyACM0). There is no separate “server IP” flag; the Pi or PC address is configured on the device in settings.json when using Wi-Fi mode.

Common flags

Flag Purpose
-p, --port Serial device (default /dev/ttyACM0)
-s, --show Print current settings from the device
-n, --name Device name
--reset-device-name Set name to firmware default (led- + STA MAC hex, same as Settings.set_defaults on led-driver)
--id Numeric device id (ESP-NOW, 0–255)
--pin LED GPIO (led_pin)
-b, --brightness Brightness 0–255
-l, --leds LED count (num_leds)
-d, --debug Debug 0 or 1
-o, --order LED colour order (rgb, grb, …)
--preset / --pattern Create or replace a named preset in led-driver presets.json
--default Startup preset name
--transport espnow or wifi (transport_type on device)
--ssid, --wifi-password, --wifi-channel Wi-Fi / channel fields for the driver
-r, --reset Reset the device
-f, --follow Follow serial output (optional timeout seconds)
--pause Sleep N seconds (for chained actions)
-u, --upload Recursive upload: -u SRC [DEST]
--src, --lib Upload src/ or a tree to /lib
-e Erase device code (keeps settings.json)
--rm Remove a path on the device
--ota Update a v2 controller over Ethernet: --ota HOST [IMAGE] (no serial port; image defaults to led_controller_v2.bin in ./v2/build, ./build or ../v2/build)
--flash Flash a firmware binary (uses esptool on the host)

Default behaviour: the tool always downloads settings.json, prints the merged view, and uploads again only when you pass setting edits (--name, --leds, …), --preset, or the relevant upload/flash/erase actions in order.

ESP-IDF led-driver (USB)

The ESP-IDF led-driver (ESP32-C3) has no files to copy: its settings live in NVS. It serves its JSON API on the USB serial port instead (one @api {...} line per request, see led-driver/main/usb_cfg.cpp), and led-tool talks to it with idf_device.py. The tool asks the port first (--driver auto, the default) and falls back to mpremote when nothing answers; --driver idf or --driver mpy skips the check.

Flag Device API
-s Hardware, brightness, network, Wi-Fi and presets in one view (also printed after edits)
--pin, -l, -o, --max-brightness /api/hardware
-b /api/brightness (this device's level)
--preset NAME [--pattern P], --default NAME /api/presets, /api/presets/startup
--ssid, --wifi-password /api/wifi (save and connect)
-n (mDNS hostname), --reset-device-name (back to led), --ap on/off, --ap-ssid, --ap-password, --ddp on/off, --dhcp, --static IP NETMASK GATEWAY [DNS], --dns ADDR (static only; empty uses the gateway) /api/network
--scan /api/wifi/scan: visible networks, strongest first
-r, -f, --pause Reboot, follow the log, wait
-v Print the device's log lines while talking to it

Edits apply live, so there is no reset afterwards. --id, --debug, --transport, --wifi-channel and the file upload flags are MicroPython only; flash ESP-IDF firmware with idf.py flash or --ota.

Opening the port keeps DTR high and RTS low, so connecting doesn't reset the C3.

Run python cli.py -h for the full epilog and argument list.

License

See LICENSE in this directory.