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>
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.