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

166 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.
```bash
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)
```bash
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.
```bash
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`.
```bash
./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.