Files
led-tool/README.md
jimmyandClaude Haiku 5.5 20a9b60d5f feat: device configuration over HTTP and OTA updates for the CLI
The CLI reaches a device over HTTP as well as USB: http_device.py holds the
request helpers, driver_ota.py uploads driver firmware, and cli.py and
ota.py use them. The README documents the new options.

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

7.6 KiB
Raw Permalink Blame History

led-tool

Command-line tool for the LED drivers. It configures both firmwares found in this repo, and updates their firmware:

  • ESP-IDF led-driver (ESP32-C3): settings, patterns and presets over USB or Wi-Fi. Changes apply live, so no reset is needed.
  • MicroPython driver: settings.json, presets and files over USB (via mpremote). Changes need a reset to apply.

The tool detects the firmware on the serial port. Use --driver idf or --driver mpy to skip detection.

Run python cli.py -h for every flag, grouped by firmware, with examples at the end.

Connecting

Connection Flag Notes
USB serial (default) -p, --port Default /dev/ttyACM0. Opening the port keeps DTR high and RTS low, so the C3 is not reset on connect.
Wi-Fi --host ADDR IP or name of an ESP-IDF driver, for example --host 192.168.4.20 or --host bar1.local. Port 80.

Over --host every settings, pattern and preset flag works the same as over USB. Two flags need USB: -r (reboot) and -f (follow the serial log). MicroPython is USB only.

ESP-IDF led-driver

Settings (USB or Wi-Fi)

Flag Setting
--pin, -l, -o, --max-brightness LED GPIO, LED count, colour order, global ceiling
-b Brightness
-n NAME, --reset-device-name Hostname (mDNS NAME.local); reset gives led
--ap on|off, --ap-ssid NAME, --ap-password PASS Access point (empty name: led-XXXXXX; empty password: open)
--ddp on|off Receive DDP pixels and frame sync
--dhcp, --static IP NETMASK GATEWAY [DNS], --dns ADDR Wi-Fi client address
--ssid SSID, --wifi-password PASS Wi-Fi network to join; the device reconnects
--default NAME Startup preset (runs at boot)
--scan List the Wi-Fi networks the device can see

-s shows the settings: hardware, brightness, network, Wi-Fi SSID and the startup preset. It is printed after any change.

Network changes can move the device to a new address. If you change --static or --dhcp over --host, the next command needs the new address.

Patterns and presets (USB or Wi-Fi)

Presets are saved on the device. Patterns named with --play or --pattern are the driver's own names; see --list-patterns.

Flag Does
--list-patterns Print the pattern names the driver has
--list-presets Print the saved preset names, with the startup one marked
--preset NAME [--pattern P] [options] Create or replace a saved preset. Only the fields given are changed.
--play PATTERN [options] Show a pattern now, without saving it
--select NAME Show a saved preset now
--delete NAME Delete a saved preset
--preset-order NAME [NAME ...] Set the order of the saved presets
--presets-defaults Add the default presets that are missing

Options for --preset and --play:

Option Meaning
--colors HEX [HEX ...] Colours, for example #ff0000 #00ff00
--background HEX Background colour
--delay MS Delay between steps
--preset-brightness 0-255 Brightness of this preset (not the global level)
--fade MS Fade time
--reverse on|off Run in reverse
--auto on|off Autorun flag
--beat-time on|off Time the pattern to the beat

--preset and --play cannot be used together. Options given without one of them are an error.

Not yet exposed: the preset's numeric parameters n1–n4 and mode.

python cli.py --list-presets
python cli.py --preset warm --pattern chase --colors '#ff0000' '#00ff00' --delay 50 --default warm
python cli.py --select warm
python cli.py --play rainbow --fade 200
python cli.py --host 192.168.4.20 --preset warm --pattern solid --colors '#ffa000'

Reboot and logs (USB only)

python cli.py -r             # reboot
python cli.py -f             # follow the serial log, Ctrl+C to stop
python cli.py -r --pause 2 -f

Firmware updates

Both update over Wi-Fi with the driver's /ota endpoint. The image is always given explicitly for LED drivers.

Flag Does
--ota HOST [IMAGE] Update one v2 controller (ESP32-S3, Ethernet). Image defaults to led_controller_v2.bin under ./v2/build, ./build or ../v2/build.
--ota-drivers [TARGET ...] Find ESP-IDF LED drivers in the given targets and update them in parallel. Default auto is this machine's /24. See the target forms below.
--ota-image PATH Driver firmware for --ota-drivers. Required, for example ../led-driver/build/led_driver.bin.
--ota-jobs N Simultaneous uploads (default 4).
--ota-list Only find and list the drivers; do not update.

Targets:

Form Scans
auto This machine's /24 (default)
192.168.4 The /24, the same as 192.168.4.0/24
10.0.0.0/23 A CIDR network (up to 4096 addresses per run)
192.168.4.10-40 or 192.168.4.10-192.168.4.40 An inclusive address range
192.168.4.25 One address

Give several targets separated by spaces or commas. Duplicates are scanned once. A run can probe at most 4096 addresses; larger targets are refused, so narrow them.

cd led-tool
python cli.py --ota-drivers --ota-image ../led-driver/build/led_driver.bin
python cli.py --ota-drivers 192.168.4.10-40 --ota-list
python cli.py --ota-drivers 192.168.4.0/24 10.0.0.0/25 --ota-jobs 2 --ota-image ../led-driver/build/led_driver.bin
python cli.py --ota-drivers 192.168.4.10-40,192.168.5.7 --ota-image ../led-driver/build/led_driver.bin

--ota-drivers probes GET /ota on each address in the targets, so it only finds devices that run the driver firmware. Drivers are reported with their partition and build; a driver that comes back on the same partition is reported as a failure.

Build the driver image first with make build in led-driver.

MicroPython driver

These flags apply to the MicroPython driver only, and are rejected when an ESP-IDF driver answers.

Flag Does
-n NAME, -l N, -b, -o, --pin Settings written to settings.json
--preset NAME --pattern P Create or replace a preset in presets.json (patterns: off, on, blink, rainbow, pulse, transition, chase, circle)
--default NAME Startup preset
--transport espnow|wifi, --ssid, --wifi-password, --wifi-channel, --id, -d Transport and radio settings
-u SRC [DEST], --src [DIR], --lib [DIR], --patterns [DIR], --all Upload directories to the device
--ls, --rm PATH, -e List, delete or erase files on the device
--flash BINARY Flash a firmware binary with esptool (path, or a filename in bin/)
--reset-device-name Name becomes led- + the STA MAC

Without setting edits, the tool downloads settings.json and prints the merged view. It uploads again only when you pass edits, --preset, or an upload, flash or erase action. Actions run in the order given on the command line, for example --reset --pause 2 --follow.

Installing

install.sh installs the Python dependencies with pipenv, builds dist/led-cli with PyInstaller, and copies it to ~/.local/bin.

./install.sh

Run from source with python cli.py after pipenv install.

Files

File Purpose
cli.py Argument parsing and the commands for both firmwares
idf_device.py ESP-IDF API over USB (@api lines on the serial port)
http_device.py The same ESP-IDF API over Wi-Fi (--host)
device.py MicroPython device access via mpremote
ota.py Firmware upload to one device, used by --ota and --ota-drivers
driver_ota.py Discovery of ESP-IDF drivers on a subnet and parallel update

License

See LICENSE in this directory.