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