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>
This commit is contained in:
1 parent
f5ab256b4a
commit
20a9b60d5f
5 files changed
+628
-131
No files matched your search
@@ -1,60 +1,164 @@
|
||||
# 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).
|
||||
Command-line tool for the LED drivers. It configures both firmwares found in this repo, and updates their firmware:
|
||||
|
||||
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.
|
||||
- **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.
|
||||
|
||||
## Common flags
|
||||
The tool detects the firmware on the serial port. Use `--driver idf` or `--driver mpy` to skip detection.
|
||||
|
||||
| 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) |
|
||||
Run `python cli.py -h` for every flag, grouped by firmware, with examples at the end.
|
||||
|
||||
**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.
|
||||
## Connecting
|
||||
|
||||
## ESP-IDF led-driver (USB)
|
||||
| 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. |
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
| 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 |
|
||||
## ESP-IDF led-driver
|
||||
|
||||
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`.
|
||||
### Settings (USB or Wi-Fi)
|
||||
|
||||
Opening the port keeps DTR high and RTS low, so connecting doesn't reset the C3.
|
||||
| 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 |
|
||||
|
||||
Run **`python cli.py -h`** for the full epilog and argument list.
|
||||
`-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
|
||||
|
||||
|
||||
Reference in new issue
Block a user