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