diff --git a/README.md b/README.md index af115d1..6351273 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/cli.py b/cli.py index 0110aa1..b18b50e 100755 --- a/cli.py +++ b/cli.py @@ -17,6 +17,8 @@ from typing import Dict, Any, List, Optional import tempfile import os from ota import ota_update +import driver_ota +import http_device from device import copy_file, DeviceConnection, firmware_default_device_name import idf_device @@ -297,6 +299,11 @@ _IDF_ONLY = { "max_brightness": "--max-brightness", "ap": "--ap", "ap_ssid": "--ap-ssid", "ap_password": "--ap-password", "ddp": "--ddp", "dhcp": "--dhcp", "static": "--static", "dns": "--dns", "scan": "--scan", + "play": "--play", "select": "--select", "delete": "--delete", "presets_defaults": "--presets-defaults", + "preset_order": "--preset-order", "list_presets": "--list-presets", "list_patterns": "--list-patterns", + "colors": "--colors", "background": "--background", "delay": "--delay", + "preset_brightness": "--preset-brightness", "fade": "--fade", "reverse": "--reverse", + "auto": "--auto", "beat_time": "--beat-time", } @@ -311,14 +318,8 @@ def _idf_show(dev: "idf_device.IdfDevice") -> Dict[str, Any]: "master": status.get("master_brightness"), }, "network": dev.get("/api/network"), - "wifi": dev.get("/api/wifi"), - "presets": { - "names": [p.get("name") for p in presets.get("presets", [])], - "selected": presets.get("selected"), - "startup": presets.get("startup"), - }, - "running": {k: v for k, v in status.items() if k not in ("patterns",)}, - "patterns": status.get("patterns", []), + "wifi": {"ssid": dev.get("/api/wifi").get("ssid")}, + "startup_preset": presets.get("startup"), } @@ -330,15 +331,69 @@ def _idf_post(dev: "idf_device.IdfDevice", path: str, body: Dict[str, Any]) -> N print(f" device address: {reply['address']}", file=sys.stderr) +def _hex_rgb(text: str) -> List[int]: + """'#ff8000' or 'ff8000' -> [255, 128, 0].""" + t = text.lstrip("#") + if len(t) != 6: + raise ValueError(f"colour must be six hex digits, e.g. #ff8000: {text}") + try: + return [int(t[i:i + 2], 16) for i in (0, 2, 4)] + except ValueError: + raise ValueError(f"colour must be six hex digits, e.g. #ff8000: {text}") from None + + +def _preset_content(args: argparse.Namespace) -> Dict[str, Any]: + """The preset fields given on the command line (only those; the driver keeps the rest).""" + c: Dict[str, Any] = {} + if args.colors is not None: + c["colors"] = [_hex_rgb(x) for x in args.colors] + if args.background is not None: + c["background"] = _hex_rgb(args.background) + if args.delay is not None: + c["delay"] = args.delay + if args.preset_brightness is not None: + c["brightness"] = args.preset_brightness + if args.fade is not None: + c["fade"] = args.fade + if args.reverse is not None: + c["reverse"] = args.reverse == "on" + if args.auto is not None: + c["auto"] = args.auto == "on" + if args.beat_time is not None: + c["beat_time"] = args.beat_time == "on" + return c + + def run_idf(args: argparse.Namespace, ordered_actions: List[tuple]) -> None: """Configure an ESP-IDF led-driver through its USB API (led-driver main/usb_cfg.cpp).""" - port = args.port bad = [flag for dest, flag in _MPY_ONLY.items() if getattr(args, dest, None) not in (None, False)] if bad: print(f"Error: {', '.join(bad)}: MicroPython driver only (this is an ESP-IDF led-driver)", file=sys.stderr) sys.exit(1) - dev = idf_device.IdfDevice(port, verbose=args.verbose) + try: + content = _preset_content(args) + except ValueError as e: + print(f"Error: {e}", file=sys.stderr) + sys.exit(1) + if args.preset is not None and args.play is not None: + print("Error: use either --preset (saved) or --play (live), not both", file=sys.stderr) + sys.exit(1) + if content and args.preset is None and args.play is None: + print("Error: colour, delay and other preset options need --preset NAME or --play PATTERN", + file=sys.stderr) + sys.exit(1) + if args.pattern is not None and args.preset is None and args.play is None: + print("Error: --pattern needs --preset NAME or --play", file=sys.stderr) + sys.exit(1) + + if args.host: + # Same API over Wi-Fi: everything below works unchanged, except reboot and follow + port = args.host + dev = http_device.HttpDevice(args.host) + else: + port = args.port + dev = idf_device.IdfDevice(port, verbose=args.verbose) try: dev.open() except Exception as e: @@ -434,15 +489,44 @@ def run_idf(args: argparse.Namespace, ordered_actions: List[tuple]) -> None: if args.brightness is not None: _idf_post(dev, "/api/brightness", {"brightness": args.brightness}) edited = True + if args.presets_defaults: + added = dev.post("/api/presets/defaults", {}).get("added", 0) + print(f"/api/presets/defaults: added {added} preset(s)", file=sys.stderr) + edited = True if args.preset is not None: - body: Dict[str, Any] = {"name": args.preset} + body: Dict[str, Any] = {"name": args.preset, **content} if args.pattern is not None: body["pattern"] = args.pattern _idf_post(dev, "/api/presets", body) edited = True + if args.delete is not None: + _idf_post(dev, "/api/presets/delete", {"name": args.delete}) + edited = True + if args.preset_order is not None: + _idf_post(dev, "/api/presets/order", {"names": args.preset_order}) + edited = True if args.default is not None: _idf_post(dev, "/api/presets/startup", {"name": args.default}) edited = True + if args.select is not None: + _idf_post(dev, "/api/presets/select", {"name": args.select}) + edited = True + if args.play is not None: + _idf_post(dev, "/api/pattern", {"pattern": args.play, **content}) + edited = True + if args.list_presets: + presets = dev.get("/api/presets") + startup = presets.get("startup") + for p in presets.get("presets", []): + mark = " (startup)" if p.get("name") == startup else "" + print(f"{p.get('name')}{mark}") + if args.list_patterns: + for name in dev.get("/api/status").get("patterns", []): + print(name) + if args.mode is not None: + _idf_post(dev, "/api/espnow", {"enabled": args.mode == "espnow"}) + edited = True + print(f" mode: {args.mode} (restart to apply: -r)", file=sys.stderr) if wifi: _idf_post(dev, "/api/wifi", wifi) edited = True @@ -464,7 +548,8 @@ def run_idf(args: argparse.Namespace, ordered_actions: List[tuple]) -> None: ssid = n.get("ssid") or "(hidden)" print(f"{ssid:<{width}} {n.get('rssi', 0):>4} {'open' if n.get('open') else 'secured'}") - actions_only = (ordered_actions or args.scan) and not edited and not args.show + listed = args.list_presets or args.list_patterns + actions_only = (ordered_actions or args.scan or listed) and not edited and not args.show if not actions_only: print_settings(_idf_show(dev)) except idf_device.IdfError as e: @@ -479,74 +564,73 @@ def run_idf(args: argparse.Namespace, ordered_actions: List[tuple]) -> None: def main() -> None: parser = argparse.ArgumentParser( - description="LED Bar Configuration CLI Tool", + description="""LED bar configuration tool. + +Two firmwares are supported, found automatically on the serial port: + ESP-IDF led-driver (ESP32-C3, JSON API). Settings apply live, no reset needed. + MicroPython driver (mpremote). Settings are written to settings.json and need a reset. + +The ESP-IDF driver also takes its settings over Wi-Fi: use --host ADDR instead of -p. +Flags marked (ESP-IDF) or (MicroPython) only apply to that firmware.""", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" -Examples: - # Download and print current settings - %(prog)s +Examples + Show settings (either driver): + %(prog)s -s + %(prog)s --host 192.168.4.20 -s - # Download, edit device name and brightness, then upload - %(prog)s -n "LED-Strip-1" -b 128 + Settings (ESP-IDF, USB or Wi-Fi): + %(prog)s -l 60 -o grb --pin 10 -b 128 strip: LEDs, colour order, GPIO, brightness + %(prog)s -n bar1 --ssid home --wifi-password secret + %(prog)s --ap off --static 10.0.0.5 255.255.255.0 10.0.0.1 --dns 1.1.1.1 + %(prog)s --dhcp --ddp on + %(prog)s --scan list Wi-Fi networks the device can see - # Set multiple parameters - %(prog)s -n "MyLED" -b 200 --preset "rainbow" + Patterns and presets (ESP-IDF, USB or Wi-Fi): + %(prog)s --list-patterns pattern names the driver has + %(prog)s --list-presets saved presets, startup marked + %(prog)s --preset warm --pattern chase --colors '#ff0000' '#00ff00' --delay 50 + %(prog)s --preset warm --default warm save a preset and make it the startup + %(prog)s --select warm show a saved preset now + %(prog)s --play rainbow --fade 200 show a pattern now, without saving + %(prog)s --delete old --preset-order warm + %(prog)s --presets-defaults add the default presets that are missing - # Set number of LEDs, color order, and debug mode - %(prog)s -l 60 -o rgb -d 1 + Reboot and logs (USB only): + %(prog)s -r reboot + %(prog)s -f follow the serial log (Ctrl+C to stop) + %(prog)s -r --pause 2 -f reboot, wait 2 s, then follow - # Reset the device - %(prog)s -r + Firmware: + %(prog)s --flash firmware.bin MicroPython: flash over serial + %(prog)s --ota-drivers --ota-image led-driver/build/led_driver.bin + find every ESP-IDF driver on this Wi-Fi subnet + and update them in parallel + %(prog)s --ota-drivers 192.168.4 --ota-list only list the drivers found on 192.168.4.x + %(prog)s --ota 10.1.1.180 [image] update one v2 controller over Ethernet - # Follow device output - %(prog)s -f - - # Reset and then follow output - %(prog)s -r -f - - # Flash firmware binary (full path or filename in bin/) - %(prog)s --flash firmware.bin - %(prog)s -p /dev/ttyUSB0 --flash /path/to/firmware.bin - - # Update a v2 controller over Ethernet (image defaults to led_controller_v2.bin under ./v2/build, ./build or ../v2/build) - %(prog)s --ota 10.1.1.180 - %(prog)s --ota 10.1.1.180 /path/to/led_controller_v2.bin - - # Reset, pause 2 seconds, then follow output - %(prog)s --reset --pause 2 --follow - - # Set name, num_leds, default pattern, and upload - %(prog)s --name "MyStrip" -l 60 --default rainbow - - # Reset logical device name to firmware default (STA MAC based) - %(prog)s --reset-device-name - -ESP-IDF led-driver (found automatically on the port; force with --driver idf): - %(prog)s -s # hardware, brightness, network, Wi-Fi, presets - %(prog)s -l 60 -o rgb --pin 10 -b 128 # strip settings, applied live - %(prog)s -n bar1 --ssid home --wifi-password secret - %(prog)s --preset warm --pattern solid --default warm - %(prog)s --ap off --static 10.0.0.5 255.255.255.0 10.0.0.1 --dns 1.1.1.1 - %(prog)s --scan # Wi-Fi networks the device can see - %(prog)s -r -f # reboot, then follow the log + MicroPython driver: + %(prog)s -n "MyStrip" -l 60 --default rainbow settings.json, then reset to apply + %(prog)s -u ./src upload a directory to the device + %(prog)s --reset-device-name """ ) parser.add_argument( "-p", "--port", default="/dev/ttyACM0", - help="Serial port/device path (default: /dev/ttyACM0)" + help="Serial port of the device, USB (default: /dev/ttyACM0). Not used with --host" ) parser.add_argument( "-n", "--name", - help="Device name" + help="Device name (ESP-IDF: the Wi-Fi hostname, mDNS name .local)" ) parser.add_argument( "--reset-device-name", action="store_true", - help="Set name to firmware default (led-, same as fresh settings.json on led-driver)", + help="Reset the name to the firmware default (MicroPython: led-; ESP-IDF: led)", ) parser.add_argument( @@ -554,21 +638,21 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): dest="device_id", type=int, metavar="0-255", - help="Numeric device ID used for ESPNow (0-255)" + help="(MicroPython) numeric device ID for ESP-NOW (0-255)" ) parser.add_argument( "--pin", type=int, metavar="N", - help="LED GPIO pin number (led_pin in settings.json)" + help="LED GPIO pin number (both drivers)" ) parser.add_argument( "-b", "--brightness", type=int, metavar="0-255", - help="Brightness (0-255)" + help="Brightness, 0-255 (both drivers)" ) parser.add_argument( @@ -576,7 +660,7 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): dest="leds", type=int, metavar="N", - help="Number of LEDs (num_leds in settings.json)" + help="Number of LEDs in the strip (both drivers)" ) parser.add_argument( @@ -585,20 +669,20 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): type=int, choices=[0, 1], metavar="0|1", - help="Debug mode (0 or 1)" + help="(MicroPython) debug mode, 0 or 1" ) parser.add_argument( "-o", "--order", dest="color_order", choices=["rgb", "rbg", "grb", "gbr", "brg", "bgr"], - help="Color order (rgb, rbg, grb, gbr, brg, bgr)" + help="LED colour order (both drivers)" ) parser.add_argument( "--preset", metavar="NAME", - help="Create or replace preset NAME in presets.json (led-driver; use --pattern)", + help="Create or replace preset NAME (both drivers; add --pattern and the preset options under Patterns and presets)", ) parser.add_argument( @@ -610,25 +694,25 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): parser.add_argument( "--default", metavar="NAME", - help="Default/startup preset name in settings.json (which preset runs at boot)", + help="Startup preset: the one that runs at boot (both drivers)", ) parser.add_argument( "--transport", choices=["espnow", "wifi"], - help="led-driver transport_type", + help="(MicroPython) transport_type: espnow or wifi", ) parser.add_argument( "--ssid", - help="led-driver ssid (Wi-Fi network in wifi mode)", + help="Wi-Fi network to join (both drivers)", ) parser.add_argument( "--wifi-password", dest="wifi_password", metavar="PASS", - help="led-driver password (Wi-Fi PSK in wifi mode)", + help="Wi-Fi password for --ssid (both drivers; empty for an open network)", ) parser.add_argument( @@ -636,7 +720,7 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): dest="wifi_channel", type=int, metavar="1-11", - help="led-driver wifi_channel (ESP-NOW mode)", + help="(MicroPython) ESP-NOW channel, 1-11", ) parser.add_argument( @@ -649,7 +733,7 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): parser.add_argument( "-r", "--reset", action="store_true", - help="Reset the device" + help="Reboot the device (USB only, both drivers)" ) parser.add_argument( @@ -658,20 +742,20 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): const=None, type=float, metavar="SECONDS", - help="Follow device output continuously (like tail -f). Optionally specify SECONDS to limit follow duration." + help="(ESP-IDF and MicroPython, USB only) follow the device output like tail -f; optionally stop after SECONDS" ) parser.add_argument( "-s", "--show", action="store_true", - help="Display current settings from device" + help="Show the current settings (both drivers)" ) parser.add_argument( "-u", "--upload", nargs='+', metavar=("SRC", "DEST"), - help="Upload a directory recursively to the device. Usage: -u SRC [DEST] (DEST is optional, defaults to basename of SRC)" + help="(MicroPython) upload a directory recursively to the device: -u SRC [DEST] (DEST defaults to the basename of SRC)" ) parser.add_argument( @@ -679,7 +763,7 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): nargs="?", const="src", metavar="DIR", - help="Upload DIR recursively to device root (:/, no leading directory), excluding patterns/. If DIR is omitted, uses local ./src." + help="(MicroPython) upload DIR to the device root, excluding patterns/ (default: ./src)" ) parser.add_argument( @@ -687,13 +771,13 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): nargs="?", const="lib", metavar="DIR", - help="Upload DIR recursively to /lib on device. If DIR is omitted, uses local ./lib." + help="(MicroPython) upload DIR to /lib on the device (default: ./lib)" ) parser.add_argument( "--all", action="store_true", - help="Upload ./src (excluding patterns), ./src/patterns, and ./lib." + help="(MicroPython) upload ./src, ./src/patterns and ./lib" ) parser.add_argument( @@ -702,39 +786,76 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): nargs="?", const=os.path.join("src", "patterns"), metavar="DIR", - help="Upload DIR recursively to /patterns on device. If DIR is omitted, uses local ./src/patterns." + help="(MicroPython) upload DIR to /patterns on the device (default: ./src/patterns)" ) parser.add_argument( "--ls", action="store_true", - help="List files on the device root (:/)" + help="(MicroPython) list files on the device root (:/)" ) parser.add_argument( "-e", "--erase", dest="erase_all", action="store_true", - help="Erase all code on the device (delete all files except settings.json)" + help="(MicroPython) erase all code on the device, keeping settings.json" ) parser.add_argument( "--rm", metavar="PATH", - help="Delete a file or directory on the device (recursive for directories)" + help="(MicroPython) delete a file or directory on the device (recursive for directories)" ) parser.add_argument( "--ota", nargs="+", metavar=("HOST", "IMAGE"), - help="Update a v2 controller over Ethernet: HOST [IMAGE]. No serial port is used and the tool exits afterwards" + help="Update one v2 controller (the ESP32-S3 controller, not an LED driver) over Ethernet: HOST [IMAGE]. Exits afterwards" + ) + + parser.add_argument( + "--ota-drivers", + nargs="*", + metavar="TARGET", + help="Find LED drivers on the network and update them in parallel. TARGET is auto (this machine's /24, " + "the default), a /24 such as 192.168.4, a CIDR network such as 10.0.0.0/23, an address range such as " + "192.168.4.10-40 or 192.168.4.10-192.168.4.40, or one address. Several targets can be given, " + "separated by spaces or commas. No serial port is used and the tool exits afterwards", + ) + + parser.add_argument( + "--host", + metavar="ADDR", + help="Configure an ESP-IDF led-driver over Wi-Fi at ADDR (IP or name) instead of USB. Every settings " + "flag works the same; -r and -f need USB", + ) + + parser.add_argument( + "--ota-image", + metavar="PATH", + help="Driver firmware for --ota-drivers (required, e.g. led-driver/build/led_driver.bin)", + ) + + parser.add_argument( + "--ota-jobs", + type=int, + default=4, + metavar="N", + help="Simultaneous uploads for --ota-drivers (default 4)", + ) + + parser.add_argument( + "--ota-list", + action="store_true", + help="With --ota-drivers: only discover and list the drivers, do not update", ) parser.add_argument( "--flash", metavar="BINARY", - help="Flash firmware binary to device. Path can be full path or filename in bin/" + help="(MicroPython) flash a firmware binary over serial. Path, or a filename in bin/" ) parser.add_argument( @@ -748,7 +869,7 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): parser.add_argument( "-v", "--verbose", action="store_true", - help="ESP-IDF: print the device's log lines while talking to it", + help="(ESP-IDF, USB) print the device's log lines while talking to it", ) idf = parser.add_argument_group("ESP-IDF led-driver only") @@ -767,6 +888,32 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): help="DNS server for a static address (empty: use the gateway)") idf.add_argument("--scan", action="store_true", help="List the Wi-Fi networks the device can see") + idf.add_argument("--mode", choices=["espnow", "wifi"], + help="ESP-NOW (the Wi-Fi client stays off) or the Wi-Fi client (ESP-NOW off); " + "applies on restart (-r)") + + pat = parser.add_argument_group("ESP-IDF led-driver patterns and presets") + pat.add_argument("--play", metavar="PATTERN", + help="Show PATTERN now without saving it (ESP-IDF: names from -s 'patterns')") + pat.add_argument("--select", metavar="NAME", help="Show the saved preset NAME now") + pat.add_argument("--delete", metavar="NAME", help="Delete the saved preset NAME") + pat.add_argument("--presets-defaults", action="store_true", + help="Add the default presets that are missing") + pat.add_argument("--preset-order", nargs="+", metavar="NAME", + help="Order of the saved presets, by name (names not listed keep their place at the end)") + pat.add_argument("--list-presets", action="store_true", help="Print the saved preset names") + pat.add_argument("--list-patterns", action="store_true", help="Print the pattern names the driver has") + pat.add_argument("--colors", nargs="+", metavar="HEX", + help="Colours for --preset or --play, e.g. #ff0000 #00ff00") + pat.add_argument("--background", metavar="HEX", help="Background colour, e.g. #000000") + pat.add_argument("--delay", type=int, metavar="MS", help="Delay between steps in milliseconds") + pat.add_argument("--preset-brightness", dest="preset_brightness", type=int, metavar="0-255", + help="Brightness of the preset (not the global brightness)") + pat.add_argument("--fade", type=int, metavar="MS", help="Fade time in milliseconds") + pat.add_argument("--reverse", choices=["on", "off"], help="Run the pattern in reverse") + pat.add_argument("--auto", choices=["on", "off"], help="Autorun flag of the preset") + pat.add_argument("--beat-time", dest="beat_time", choices=["on", "off"], + help="Time the pattern to the beat") try: args = parser.parse_args() @@ -775,11 +922,27 @@ ESP-IDF led-driver (found automatically on the port; force with --driver idf): print(f"Error: {e}", file=sys.stderr) sys.exit(1) + if args.ota_drivers is not None: + if not args.ota_list and not args.ota_image: + print("Error: --ota-drivers needs --ota-image PATH (the driver firmware, e.g. " + "led-driver/build/led_driver.bin)", file=sys.stderr) + sys.exit(1) + sys.exit(driver_ota.ota_drivers(args.ota_drivers or ["auto"], args.ota_image, args.ota_jobs, + args.ota_list)) + port = args.port ran_reset = False + if args.host: + if args.driver == "mpy": + print("Error: --host is for the ESP-IDF led-driver (Wi-Fi API); MicroPython has no Wi-Fi API here", + file=sys.stderr) + sys.exit(1) + run_idf(args, ordered_actions) + return + use_idf = args.driver == "idf" - serial_free = bool(ordered_actions) and all(a[0] in ("ota", "pause", "flash") for a in ordered_actions) + serial_free =bool(ordered_actions) and all(a[0] in ("ota", "pause", "flash") for a in ordered_actions) if args.driver == "auto" and not serial_free: use_idf = idf_device.probe(port) if use_idf: diff --git a/driver_ota.py b/driver_ota.py new file mode 100644 index 0000000..713b76a --- /dev/null +++ b/driver_ota.py @@ -0,0 +1,148 @@ +""" +Find every LED driver on a Wi-Fi network or address range, and update them in parallel. + +A driver answers GET /ota with its partition and build info, so discovery is a parallel probe +of each address in the targets. Each driver found then gets the same image, `jobs` at a time. +Uses ota.py for the per-device upload. + +Targets (one or more, comma-separated or as separate arguments): + auto this machine's /24 + 192.168.4 a /24 (same as 192.168.4.0/24) + 192.168.4.0/24 a CIDR network + 192.168.4.10-192.168.4.40 an inclusive range + 192.168.4.10-40 the same, short form + 192.168.4.25 one address +""" + +import concurrent.futures as cf +import ipaddress +import os +import socket +import sys +from typing import List, Optional, Tuple + +from ota import _info, ota_update + +# Largest number of addresses one run will probe, so a typo like 10.0.0.0/8 is refused +MAX_TARGETS = 4096 + + +def local_subnet() -> str: + """First three octets of the address this machine uses to reach the network.""" + s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) + try: + s.connect(("192.0.2.1", 9)) # UDP connect sends no packet + ip = s.getsockname()[0] + finally: + s.close() + return ".".join(ip.split(".")[:3]) + + +def _ip(text: str) -> ipaddress.IPv4Address: + try: + return ipaddress.IPv4Address(text.strip()) + except ValueError: + raise ValueError(f"not an IPv4 address: {text}") from None + + +def _expand(part: str) -> List[ipaddress.IPv4Address]: + """One target (see the module docstring) -> the addresses it covers.""" + if part == "auto": + part = local_subnet() + if "/" in part: + try: + net = ipaddress.IPv4Network(part, strict=False) + except ValueError: + raise ValueError(f"not a network: {part}") from None + if net.num_addresses > MAX_TARGETS: + raise ValueError(f"network too large (max {MAX_TARGETS} addresses): {part}") + return list(net.hosts()) if net.num_addresses > 2 else list(net) + if "-" in part: + first, last = part.split("-", 1) + start = _ip(first) + end = _ip(last) if last.count(".") == 3 else _ip(".".join(first.split(".")[:3] + [last])) + if int(end) < int(start): + raise ValueError(f"range ends before it starts: {part}") + if int(end) - int(start) >= MAX_TARGETS: + raise ValueError(f"range too large (max {MAX_TARGETS} addresses): {part}") + return [ipaddress.IPv4Address(i) for i in range(int(start), int(end) + 1)] + if part.count(".") == 2: + # Three octets: the whole /24, as before + return list(ipaddress.IPv4Network(part + ".0/24").hosts()) + return [_ip(part)] + + +def parse_targets(specs: List[str]) -> List[str]: + """All addresses named by the targets, in order, without duplicates.""" + seen = set() + out: List[str] = [] + for spec in specs: + for part in spec.split(","): + part = part.strip() + if not part: + continue + for addr in _expand(part): + if addr not in seen: + seen.add(addr) + out.append(str(addr)) + if len(out) > MAX_TARGETS: + raise ValueError(f"too many addresses ({len(out)}; max {MAX_TARGETS}). Narrow the targets.") + return out + + +def discover(hosts: List[str], port: int = 80, workers: int = 64) -> List[Tuple[str, dict]]: + """Probe each host for a driver. Returns (host, info) sorted by address.""" + found = [] + with cf.ThreadPoolExecutor(max_workers=workers) as pool: + futures = {pool.submit(_info, h, port): h for h in hosts} + for fut in cf.as_completed(futures): + info = fut.result() + if info: + found.append((futures[fut], info)) + return sorted(found, key=lambda t: int(ipaddress.IPv4Address(t[0]))) + + +def ota_drivers(specs: List[str], image: Optional[str], jobs: int, list_only: bool, + port: int = 80) -> int: + """Discover drivers in the targets and update them. Returns a process exit code.""" + if not list_only: + if not image or not os.path.isfile(image): + print(f"Error: image not found: {image}", file=sys.stderr) + return 1 + try: + hosts = parse_targets(specs or ["auto"]) + except ValueError as e: + print(f"Error: {e}", file=sys.stderr) + return 1 + if not hosts: + print("Error: no addresses to scan", file=sys.stderr) + return 1 + + print(f"Scanning {len(hosts)} address(es) on port {port}: {hosts[0]} .. {hosts[-1]}", file=sys.stderr) + drivers = discover(hosts, port) + if not drivers: + print("No drivers found.", file=sys.stderr) + return 1 + + print(f"Found {len(drivers)} driver(s):", file=sys.stderr) + for host, info in drivers: + print(f" {host:<16} {info.get('partition', '?'):<8} built {info.get('built', '?')}", file=sys.stderr) + if list_only: + return 0 + + print(f"\nUpdating {len(drivers)} driver(s) with {image}, {jobs} at a time...", file=sys.stderr) + failed = [] + with cf.ThreadPoolExecutor(max_workers=jobs) as pool: + futures = {pool.submit(ota_update, h, image, port): h for h, _ in drivers} + for fut in cf.as_completed(futures): + host = futures[fut] + try: + fut.result() + print(f"OK {host}", file=sys.stderr) + except Exception as e: + failed.append(host) + print(f"FAILED {host}: {e}", file=sys.stderr) + + ok = len(drivers) - len(failed) + print(f"\n{ok} updated, {len(failed)} failed" + (f": {' '.join(failed)}" if failed else ""), file=sys.stderr) + return 1 if failed else 0 diff --git a/http_device.py b/http_device.py new file mode 100644 index 0000000..71cf956 --- /dev/null +++ b/http_device.py @@ -0,0 +1,82 @@ +""" +Wi-Fi connection to the ESP-IDF led-driver. + +The driver serves the same JSON API over HTTP on its address (led-driver main/web.cpp) that it +serves over USB (main/usb_cfg.cpp). HttpDevice has the same get/post/call interface as +idf_device.IdfDevice, so the settings code in cli.py works for both transports. + +Not available over Wi-Fi: reboot (no HTTP route) and following the serial log. +""" + +import http.client +import json +import socket +from typing import Any, Optional, Tuple + +from idf_device import IdfError + + +class HttpDevice: + def __init__(self, host: str, port: int = 80, timeout: float = 5.0): + self.host = host + self.port = port + self.timeout = timeout + + def open(self) -> "HttpDevice": + return self + + def close(self) -> None: + pass + + def __enter__(self) -> "HttpDevice": + return self + + def __exit__(self, *exc) -> None: + pass + + def call_raw(self, method: str, path: str, body: Any = None, host: Optional[str] = None, + timeout: Optional[float] = None) -> Tuple[int, Any]: + """Send one request; return (status, parsed body). Does not raise on an error status.""" + if host is not None: + raise IdfError(0, "relay through the driver is USB-only; use --port for that") + conn = http.client.HTTPConnection(self.host, self.port, timeout=timeout or self.timeout) + headers = {} + data = None + if body is not None: + data = json.dumps(body, separators=(",", ":")).encode() + headers["Content-Type"] = "application/json" + try: + conn.request(method, path, body=data, headers=headers) + r = conn.getresponse() + text = r.read().decode("utf-8", "replace") + except socket.timeout as e: + raise TimeoutError(f"no reply from {self.host} to {method} {path}") from e + except OSError as e: + raise TimeoutError(f"cannot reach {self.host}: {e}") from e + finally: + conn.close() + try: + parsed = json.loads(text) if text else {} + except ValueError: + parsed = text + return r.status, parsed + + def call(self, method: str, path: str, body: Any = None, **kw) -> Any: + """Send one request; return the parsed body. Raises IdfError on status >= 400.""" + status, parsed = self.call_raw(method, path, body, **kw) + if status >= 400: + msg = parsed.get("error") if isinstance(parsed, dict) else None + raise IdfError(status, msg or str(parsed)) + return parsed + + def get(self, path: str, **kw) -> Any: + return self.call("GET", path, **kw) + + def post(self, path: str, body: Any, **kw) -> Any: + return self.call("POST", path, body, **kw) + + def reboot(self) -> None: + raise IdfError(0, "reboot is not available over Wi-Fi; use -r with --port (USB)") + + def follow(self, seconds: Optional[float] = None) -> None: + raise IdfError(0, "following the log is not available over Wi-Fi; use -f with --port (USB)") diff --git a/ota.py b/ota.py index 80661c1..456d1dc 100644 --- a/ota.py +++ b/ota.py @@ -45,7 +45,7 @@ def ota_update(host: str, image: Optional[str] = None, port: int = 80) -> None: before = _info(host, port) if before is None: - raise RuntimeError(f"no OTA endpoint at http://{host}:{port}/ota (is this the v2 controller?)") + raise RuntimeError(f"no OTA endpoint at http://{host}:{port}/ota (is this an LED device?)") print(f"Running {before['partition']} (built {before['built']})") print(f"Uploading {image} ({size} bytes)...")