Author SHA1 Message Date
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
jimmyandClaude Opus 5.5 f5ab256b4a feat: configure the ESP-IDF led-driver over USB
idf_device.py talks to the driver's USB API (led-driver main/usb_cfg.cpp).
--driver auto (default) asks the port first and falls back to mpremote.
Existing flags map to the driver's API (-s, --pin, -l, -o, -b, --preset,
--default, --ssid/--wifi-password, -n, -r, -f); new ESP-IDF flags cover
the rest of the network settings (--ap, --ap-ssid, --ap-password, --ddp,
--dhcp, --static, --dns), --max-brightness and --scan. Opening the port
keeps DTR high so connecting doesn't reset the C3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:34:36 +13:00
jimmyandClaude Haiku 5.5 c9dea6e142 chore: in-progress CLI and device changes
Work in progress from the same tree as the controller's sequences-v2 changes.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-11-11 14:10:55 +13:00
jimmyandClaude Sonnet 5.5 892ccaec71 feat(cli): add --ota to update a v2 controller over Ethernet
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-01 00:22:55 +13:00
piandCursor d6331a105c feat(cli): add --reset-device-name and WDT feed during uploads
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-03 21:27:29 +12:00
jimmyandCursor 2f3db9272b feat(cli): extend upload flags for src, patterns, lib, and --all
Support --patterns/--paterns, --all, --erase, and src upload excluding patterns/.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-03 14:54:13 +12:00
jimmy 713cd6e9a1 feat(cli): add ls flag and default lib upload
Made-with: Cursor
2026-04-15 00:46:19 +12:00
jimmy 9e72c62481 fix(led-tool): build cli without spec file dependency 2026-04-14 23:13:21 +12:00
9 changed files with 1346 additions and 100 deletions

No files matched your search

+1 -1
View File
@@ -16,5 +16,5 @@ python_version = "3"
[scripts]
web = "python web.py"
cli = "python cli.py"
build = "pyinstaller --clean led-cli.spec"
build = "pyinstaller --clean --onefile --name led-cli --paths lib cli.py"
install = "pipenv install"
+154 -28
View File
@@ -1,38 +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** |
| `--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 |
| `--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
Run **`python cli.py -h`** for the full epilog and argument list.
| 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
+631 -65
View File
@@ -11,11 +11,16 @@ import argparse
import subprocess
import sys
import time
import shutil
from typing import Dict, Any, List, Optional
import tempfile
import os
from device import copy_file, DeviceConnection
from ota import ota_update
import driver_ota
import http_device
from device import copy_file, DeviceConnection, firmware_default_device_name
import idf_device
def resolve_flash_binary(path: str) -> Optional[str]:
@@ -147,14 +152,15 @@ _FLAGS_WITH_VALUE = frozenset({
'-p', '--port', '-n', '--name', '--pin', '-b', '--brightness',
'-l', '--leds', '-d', '-debug', '--debug', '-o', '--order',
'--preset', '--pattern', '--default', '--transport', '--ssid',
'--wifi-password', '--wifi-channel',
'--wifi-password', '--wifi-channel', '--ota', '--src', '--lib', '--patterns', '--paterns',
'--driver', '--max-brightness', '--ap', '--ap-ssid', '--ap-password', '--ddp', '--dns',
})
def _get_ordered_actions(argv: List[str]) -> List[tuple]:
"""
Scan argv and return list of (action_name, value) in order of appearance.
Actions: flash, pause, reset, upload, erase_all, rm, follow.
Actions: flash, ota, pause, reset, upload, ls, erase_all, rm, follow.
"""
actions = []
i = 1
@@ -178,6 +184,16 @@ def _get_ordered_actions(argv: List[str]) -> List[tuple]:
else:
raise ValueError("--flash requires an argument")
continue
if arg == '--ota':
vals = []
i += 1
while i < len(argv) and not argv[i].startswith('-') and len(vals) < 2:
vals.append(argv[i])
i += 1
if not vals:
raise ValueError("--ota requires a host (and optionally an image path)")
actions.append(('ota', vals))
continue
if arg in ('-r', '--reset'):
actions.append(('reset', None))
i += 1
@@ -201,22 +217,47 @@ def _get_ordered_actions(argv: List[str]) -> List[tuple]:
i += 2
else:
i += 1
# Use empty string as remote_dir to map to root on device
actions.append(('upload', [local_dir, ""]))
# Upload source tree excluding patterns/ (handled by --patterns).
actions.append(('upload_src_no_patterns', local_dir))
continue
if arg == '--lib':
# Upload local DIR to /lib on device
if i + 1 < len(argv):
if arg in ('--patterns', '--paterns'):
# Upload local patterns DIR (default: ./src/patterns) to /patterns.
local_dir = os.path.join("src", "patterns")
if i + 1 < len(argv) and not argv[i + 1].startswith('-'):
local_dir = argv[i + 1]
actions.append(('upload', [local_dir, "lib"]))
i += 2
else:
raise ValueError("--lib requires a directory argument")
i += 1
actions.append(('upload', [local_dir, "patterns"]))
continue
if arg == '--all':
actions.append(('upload_src_no_patterns', "src"))
actions.append(('upload', [os.path.join("src", "patterns"), "patterns"]))
actions.append(('upload', ["lib", "lib"]))
i += 1
continue
if arg == '--lib':
# Upload local DIR (default: ./lib) to /lib on device
local_dir = "lib"
if i + 1 < len(argv) and not argv[i + 1].startswith('-'):
local_dir = argv[i + 1]
i += 2
else:
i += 1
actions.append(('upload', [local_dir, "lib"]))
continue
if arg == '--ls':
actions.append(('ls', None))
i += 1
continue
if arg == '-e':
actions.append(('erase_all', None))
i += 1
continue
if arg == '--erase':
actions.append(('erase_all', None))
i += 1
continue
if arg == '--rm':
if i + 1 < len(argv):
actions.append(('rm', argv[i + 1]))
@@ -247,54 +288,349 @@ def _get_ordered_actions(argv: List[str]) -> List[tuple]:
return actions
# Flags that only the MicroPython driver understands (settings.json / file uploads)
_MPY_ONLY = {
"device_id": "--id", "debug": "--debug", "transport": "--transport",
"wifi_channel": "--wifi-channel", "upload": "-u", "src": "--src", "lib": "--lib",
"all": "--all", "patterns_dir": "--patterns", "ls": "--ls", "erase_all": "-e", "rm": "--rm",
}
# And the reverse: flags only the ESP-IDF driver understands
_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",
}
def _idf_show(dev: "idf_device.IdfDevice") -> Dict[str, Any]:
"""Everything the ESP-IDF driver will tell over USB, in one view."""
status = dev.get("/api/status")
presets = dev.get("/api/presets")
return {
"hardware": dev.get("/api/hardware"),
"brightness": {
"global": status.get("global_brightness"),
"master": status.get("master_brightness"),
},
"network": dev.get("/api/network"),
"wifi": {"ssid": dev.get("/api/wifi").get("ssid")},
"startup_preset": presets.get("startup"),
}
def _idf_post(dev: "idf_device.IdfDevice", path: str, body: Dict[str, Any]) -> None:
reply = dev.post(path, body)
msg = reply.get("message") if isinstance(reply, dict) else None
print(f"{path}: {msg or 'ok'}", file=sys.stderr)
if isinstance(reply, dict) and reply.get("address"):
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)."""
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)
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:
print(f"Error: cannot open {port}: {e}", file=sys.stderr)
sys.exit(1)
try:
# Actions in command-line order (reset, pause, follow, flash, ota)
for action_name, value in ordered_actions:
if action_name == "pause":
print(f"Pausing for {value} seconds...", file=sys.stderr)
time.sleep(value)
elif action_name == "reset":
print(f"Rebooting device on {port}...", file=sys.stderr)
dev.reboot()
# The USB port drops and comes back during the restart
dev.close()
time.sleep(2.0)
dev.open()
elif action_name == "follow":
if value is None:
print(f"Following output from {port}... (Press Ctrl+C to stop)", file=sys.stderr)
else:
print(f"Following output from {port} for {value} seconds...", file=sys.stderr)
try:
dev.follow(value)
except KeyboardInterrupt:
print("\nStopped following.", file=sys.stderr)
return
elif action_name == "ota":
ota_update(value[0], value[1] if len(value) > 1 else None)
elif action_name == "flash":
print("Error: --flash with an ESP-IDF driver: use idf.py flash (or --driver mpy for a merged image)",
file=sys.stderr)
sys.exit(1)
# Settings edits, each sent to the API route that owns it. They apply live: no reset.
hw: Dict[str, Any] = {}
if args.pin is not None:
hw["pin"] = args.pin
if args.leds is not None:
hw["num_leds"] = args.leds
if args.color_order is not None:
hw["rgb_order"] = args.color_order
if args.max_brightness is not None:
hw["max_brightness"] = args.max_brightness
net: Dict[str, Any] = {}
if args.name is not None and args.reset_device_name:
print("Error: use either --name or --reset-device-name, not both.", file=sys.stderr)
sys.exit(1)
if args.name is not None:
net["hostname"] = args.name
elif args.reset_device_name:
net["hostname"] = "led"
if args.ap is not None:
net["ap_enabled"] = args.ap == "on"
if args.ap_ssid is not None:
net["ap_ssid"] = args.ap_ssid
if args.ap_password is not None:
net["ap_password"] = args.ap_password
if args.ddp is not None:
net["ddp_enabled"] = args.ddp == "on"
if args.dhcp and args.static:
print("Error: use either --dhcp or --static, not both.", file=sys.stderr)
sys.exit(1)
if args.dhcp:
net["mode"] = "dhcp"
if args.static:
if len(args.static) not in (3, 4):
print("Error: --static needs IP NETMASK GATEWAY [DNS]", file=sys.stderr)
sys.exit(1)
net["mode"] = "static"
net.update(dict(zip(("ip", "netmask", "gateway", "dns"), args.static)))
if args.dns is not None:
if args.static and len(args.static) == 4:
print("Error: DNS given twice (--static's 4th value and --dns)", file=sys.stderr)
sys.exit(1)
net["dns"] = args.dns
wifi: Dict[str, Any] = {}
if args.ssid is not None:
wifi["ssid"] = args.ssid
wifi["password"] = args.wifi_password or ""
elif args.wifi_password is not None:
print("Error: --wifi-password needs --ssid", file=sys.stderr)
sys.exit(1)
edited = False
if hw:
_idf_post(dev, "/api/hardware", hw)
edited = True
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, **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
if net:
# Last: it reconnects Wi-Fi (USB is unaffected)
_idf_post(dev, "/api/network", net)
edited = True
if "dns" in net and net.get("mode", dev.get("/api/network").get("mode")) != "static":
print(" note: DNS is used only with a static address (--static); DHCP supplies its own",
file=sys.stderr)
if args.scan:
print(f"Scanning for Wi-Fi networks on {port}...", file=sys.stderr)
nets = dev.get("/api/wifi/scan", timeout=15).get("networks", [])
nets.sort(key=lambda n: n.get("rssi", -999), reverse=True)
width = max([len(n.get("ssid") or "") for n in nets] + [4])
print(f"{'SSID':<{width}} RSSI SECURITY")
for n in nets:
ssid = n.get("ssid") or "(hidden)"
print(f"{ssid:<{width}} {n.get('rssi', 0):>4} {'open' if n.get('open') else 'secured'}")
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:
print(f"Error from device: {e}", file=sys.stderr)
sys.exit(1)
except TimeoutError as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
finally:
dev.close()
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
# 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
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 <name>.local)"
)
parser.add_argument(
"--reset-device-name",
action="store_true",
help="Reset the name to the firmware default (MicroPython: led-<MAC>; ESP-IDF: led)",
)
parser.add_argument(
@@ -302,21 +638,21 @@ Examples:
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(
@@ -324,7 +660,7 @@ Examples:
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(
@@ -333,52 +669,50 @@ Examples:
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(
"--pattern",
choices=[
"off", "on", "blink", "rainbow", "pulse", "transition", "chase", "circle",
],
help="Pattern type for --preset (default: on)",
help="Pattern for --preset (MicroPython: off, on, blink, rainbow, pulse, transition, chase, circle;"
" ESP-IDF: any name from -s 'patterns'). MicroPython default: on",
)
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(
@@ -386,7 +720,7 @@ Examples:
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(
@@ -399,7 +733,7 @@ Examples:
parser.add_argument(
"-r", "--reset",
action="store_true",
help="Reset the device"
help="Reboot the device (USB only, both drivers)"
)
parser.add_argument(
@@ -408,20 +742,20 @@ Examples:
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(
@@ -429,34 +763,158 @@ Examples:
nargs="?",
const="src",
metavar="DIR",
help="Upload DIR recursively to device root (:/, no leading directory). If DIR is omitted, uses local ./src."
help="(MicroPython) upload DIR to the device root, excluding patterns/ (default: ./src)"
)
parser.add_argument(
"--lib",
nargs="?",
const="lib",
metavar="DIR",
help="Upload DIR recursively to /lib on device"
help="(MicroPython) upload DIR to /lib on the device (default: ./lib)"
)
parser.add_argument(
"-e",
"--all",
action="store_true",
help="(MicroPython) upload ./src, ./src/patterns and ./lib"
)
parser.add_argument(
"--patterns", "--paterns",
dest="patterns_dir",
nargs="?",
const=os.path.join("src", "patterns"),
metavar="DIR",
help="(MicroPython) upload DIR to /patterns on the device (default: ./src/patterns)"
)
parser.add_argument(
"--ls",
action="store_true",
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 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(
"--driver",
choices=["auto", "idf", "mpy"],
default="auto",
help="Device firmware: idf (ESP-IDF led-driver, USB API), mpy (MicroPython, mpremote), "
"or auto (default: ask the port, fall back to mpy)",
)
parser.add_argument(
"-v", "--verbose",
action="store_true",
help="(ESP-IDF, USB) print the device's log lines while talking to it",
)
idf = parser.add_argument_group("ESP-IDF led-driver only")
idf.add_argument("--max-brightness", dest="max_brightness", type=int, metavar="0-255",
help="Ceiling for every output colour")
idf.add_argument("--ap", choices=["on", "off"], help="Turn the access point on or off")
idf.add_argument("--ap-ssid", dest="ap_ssid", metavar="NAME",
help="Access point name (empty: led-XXXXXX)")
idf.add_argument("--ap-password", dest="ap_password", metavar="PASS",
help="Access point password, 8-63 characters (empty: open)")
idf.add_argument("--ddp", choices=["on", "off"], help="Receive DDP pixels and frame sync")
idf.add_argument("--dhcp", action="store_true", help="Wi-Fi client address from DHCP")
idf.add_argument("--static", nargs="+", metavar="ADDR",
help="Static Wi-Fi client address: IP NETMASK GATEWAY [DNS]")
idf.add_argument("--dns", metavar="ADDR",
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()
ordered_actions = _get_ordered_actions(sys.argv)
@@ -464,9 +922,40 @@ Examples:
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)
if args.driver == "auto" and not serial_free:
use_idf = idf_device.probe(port)
if use_idf:
print(f"ESP-IDF led-driver on {port}", file=sys.stderr)
if use_idf:
run_idf(args, ordered_actions)
return
bad = [flag for dest, flag in _IDF_ONLY.items() if getattr(args, dest, None) not in (None, False)]
if bad:
print(f"Error: {', '.join(bad)}: ESP-IDF led-driver only (no ESP-IDF driver answered on {port})",
file=sys.stderr)
sys.exit(1)
# Execute actions in command-line order
for action_name, value in ordered_actions:
if action_name == 'pause':
@@ -492,6 +981,15 @@ Examples:
print("Error: esptool not found. Install it with: pip install esptool", file=sys.stderr)
sys.exit(1)
elif action_name == 'ota':
try:
ota_update(value[0], value[1] if len(value) > 1 else None)
except Exception as e:
print(f"Error: OTA failed: {e}", file=sys.stderr)
sys.exit(1)
if all(a[0] in ('ota', 'pause') for a in ordered_actions):
return # network-only: nothing to download over serial
elif action_name == 'reset':
ran_reset = True
try:
@@ -526,6 +1024,50 @@ Examples:
except Exception as e:
print(f"Error uploading directory: {e}", file=sys.stderr)
sys.exit(1)
elif action_name == 'upload_src_no_patterns':
src_dir = value
if not os.path.exists(src_dir):
print(f"Error: Directory does not exist: {src_dir}", file=sys.stderr)
sys.exit(1)
if not os.path.isdir(src_dir):
print(f"Error: Not a directory: {src_dir}", file=sys.stderr)
sys.exit(1)
try:
with tempfile.TemporaryDirectory() as temp_src:
for entry in sorted(os.listdir(src_dir)):
if entry == "patterns":
continue
src_entry = os.path.join(src_dir, entry)
dst_entry = os.path.join(temp_src, entry)
if os.path.isdir(src_entry):
shutil.copytree(src_entry, dst_entry, ignore=shutil.ignore_patterns('__pycache__', '*.pyc', '*.pyo'))
else:
shutil.copy2(src_entry, dst_entry)
print(
f"Uploading {src_dir} (excluding patterns/) to device root on {port}...",
file=sys.stderr,
)
conn = DeviceConnection(port)
files_copied, dirs_created = conn.upload_directory(temp_src, "")
print(
f"Upload complete: {files_copied} files, {dirs_created} directories created.",
file=sys.stderr,
)
except Exception as e:
print(f"Error uploading src (excluding patterns): {e}", file=sys.stderr)
sys.exit(1)
elif action_name == 'ls':
try:
print(f"Listing files on device {port}...", file=sys.stderr)
conn = DeviceConnection(port)
items = conn.list_files('')
for name, is_dir, size in items:
marker = "d" if is_dir else "-"
print(f"{marker} {size:>8} {name}")
except Exception as e:
print(f"Error listing files: {e}", file=sys.stderr)
sys.exit(1)
elif action_name == 'erase_all':
try:
@@ -569,11 +1111,35 @@ Examples:
sys.exit(1)
return # follow blocks; when interrupted we're done
default_name_from_device: Optional[str] = None
if args.reset_device_name:
if args.name is not None:
print(
"Error: use either --name or --reset-device-name, not both.",
file=sys.stderr,
)
sys.exit(1)
try:
print(
f"Reading firmware default device name (STA MAC) on {port}...",
file=sys.stderr,
)
default_name_from_device = firmware_default_device_name(port)
print(
f"Default name will be {default_name_from_device!r}.",
file=sys.stderr,
)
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
# Collect all edit parameters
edits: Dict[str, Any] = {}
if args.name is not None:
edits["name"] = args.name
elif default_name_from_device is not None:
edits["name"] = default_name_from_device
if args.pin is not None:
edits["led_pin"] = args.pin
+80 -5
View File
@@ -23,12 +23,15 @@ if lib_path not in sys.path and os.path.exists(lib_path):
sys.path.insert(0, lib_path)
from mpremote.transport_serial import SerialTransport
from mpremote.transport import TransportError
from mpremote.transport import TransportError, TransportExecError
class DeviceConnection:
"""Wrapper for device communication."""
#: Feed interval during uploads (led-driver uses WDT(timeout=10000) ms).
WDT_FEED_INTERVAL_SEC = 5.0
def __init__(self, device):
"""Connect to a device."""
self.device = device
@@ -53,7 +56,39 @@ class DeviceConnection:
except Exception:
pass
self.transport = None
def _feed_wdt(self) -> None:
"""Best-effort feed of the ESP task WDT between chunked FS writes."""
if self.transport is None:
return
try:
self.transport.exec(
"try:\n import machine\n machine.WDT(timeout=10000).feed()\nexcept Exception:\n pass\n"
)
except Exception:
pass
def _make_wdt_upload_progress_callback(self):
"""Progress hook for Transport.fs_writefile: feed WDT every WDT_FEED_INTERVAL_SEC."""
last_feed = [time.monotonic()]
def progress(written: int, total: int) -> None:
now = time.monotonic()
if now - last_feed[0] >= self.WDT_FEED_INTERVAL_SEC:
self._feed_wdt()
last_feed[0] = now
return progress
def _fs_writefile_with_wdt(self, remote_path: str, data: bytes) -> None:
"""Write file to device with periodic WDT feeds during long transfers."""
self._feed_wdt()
self.transport.fs_writefile(
remote_path,
data,
progress_callback=self._make_wdt_upload_progress_callback(),
)
def copy_from_device(self, remote_path, local_path):
"""Copy a file from device to local filesystem."""
self.connect()
@@ -70,7 +105,7 @@ class DeviceConnection:
try:
with open(local_path, 'rb') as f:
data = f.read()
self.transport.fs_writefile(remote_path, data)
self._fs_writefile_with_wdt(remote_path, data)
finally:
self.disconnect()
@@ -87,6 +122,13 @@ class DeviceConnection:
if not os.path.isdir(local_dir):
raise ValueError(f"{local_dir} is not a directory")
# Host bytecode must never reach the device: remove it before uploading.
import shutil
for root, dirs, _files in os.walk(local_dir):
for d in [d for d in dirs if d == "__pycache__"]:
shutil.rmtree(os.path.join(root, d), ignore_errors=True)
dirs.remove(d)
self.connect()
try:
# Determine remote directory name
@@ -123,6 +165,8 @@ class DeviceConnection:
# Copy files
for file in files:
if file.endswith((".pyc", ".pyo")):
continue
local_file = os.path.join(root, file)
# Handle root directory case properly
if remote_base == '/':
@@ -133,7 +177,7 @@ class DeviceConnection:
print(f"Uploading: {remote_file}", file=sys.stderr)
with open(local_file, 'rb') as f:
data = f.read()
self.transport.fs_writefile(remote_file, data)
self._fs_writefile_with_wdt(remote_file, data)
files_copied += 1
return files_copied, dirs_created
@@ -235,6 +279,37 @@ class DeviceConnection:
raise TransportError(f"Failed to follow output: {e}") from e
def firmware_default_device_name(device: str) -> str:
"""
Default logical device name on led-driver firmware: led-<sta_mac_hex>,
matching Settings.set_defaults() in led-driver/src/settings.py.
"""
conn = DeviceConnection(device)
conn.connect()
try:
code = (
"import network, ubinascii\n"
"sta = network.WLAN(network.STA_IF)\n"
"sta.active(True)\n"
"mac = ubinascii.hexlify(sta.config('mac')).decode().lower()\n"
"print('led-' + mac)\n"
)
out = conn.transport.exec(code)
except TransportExecError as e:
raise RuntimeError(
"Could not read STA MAC from device (is this MicroPython with network?): "
+ (e.error_output or str(e)).strip()
) from e
finally:
conn.disconnect()
text = out.decode("utf-8", errors="replace").strip()
for line in reversed(text.splitlines()):
line = line.strip()
if line.startswith("led-"):
return line
raise RuntimeError("Device did not return a led-<mac> default name")
def copy_file(from_device, device, remote_path, local_path):
"""
Copy a file to/from device.
+148
View File
@@ -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
+82
View File
@@ -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)")
+172
View File
@@ -0,0 +1,172 @@
"""
USB connection to the ESP-IDF led-driver (ESP32-C3).
The driver serves its JSON API on the USB serial port (led-driver main/usb_cfg.cpp):
@api {"id": n, "method": "GET" or "POST", "path": "/api/...", "body": {...}}
-> @api {"id": n, "status": 200, "body": "<JSON text>"}
@reboot -> @ok, then the device restarts
Every other line on the port is log output.
"""
import json
import sys
import time
from typing import Any, Dict, Optional, Tuple
import serial
API = "@api "
class IdfError(RuntimeError):
"""The device answered with an error status."""
def __init__(self, status: int, message: str):
super().__init__(f"{status}: {message}")
self.status = status
self.message = message
class IdfDevice:
def __init__(self, port: str, verbose: bool = False):
self.port = port
self.verbose = verbose
self._id = 0
self._ser: Optional[serial.Serial] = None
def open(self) -> "IdfDevice":
if self._ser is None:
ser = serial.Serial()
ser.port = self.port
ser.baudrate = 115200
ser.timeout = 0.1
# On the C3's USB-Serial-JTAG, RTS high with DTR low resets the chip. Linux raises both
# on open and pyserial then sets DTR before RTS, so DTR must stay high (DTR low first
# would pass through RTS high, DTR low and reset it). RTS low keeps it running.
ser.dtr = True
ser.rts = False
ser.open()
self._ser = ser
return self
def close(self) -> None:
if self._ser is not None:
self._ser.close()
self._ser = None
def __enter__(self) -> "IdfDevice":
return self.open()
def __exit__(self, *exc) -> None:
self.close()
def _log(self, line: str) -> None:
if self.verbose and line:
print(f"[device] {line}", file=sys.stderr)
def _readline(self, deadline: float) -> Optional[str]:
"""One line from the device, or None at the deadline."""
buf = b""
while time.monotonic() < deadline:
chunk = self._ser.readline()
if not chunk:
continue
buf += chunk
if buf.endswith(b"\n"):
return buf.decode("utf-8", "replace").rstrip("\r\n")
return None
def call_raw(self, method: str, path: str, body: Any = None, host: Optional[str] = None,
timeout: float = 3.0) -> Tuple[int, Any]:
"""Send one request; return (status, parsed body). Does not raise on an error status."""
self.open()
self._id += 1
msg: Dict[str, Any] = {"id": self._id, "method": method, "path": path}
if body is not None:
msg["body"] = body
if host:
msg["host"] = host
self._ser.reset_input_buffer()
self._ser.write(("\n" + API + json.dumps(msg, separators=(",", ":")) + "\n").encode())
self._ser.flush()
deadline = time.monotonic() + timeout
while True:
line = self._readline(deadline)
if line is None:
raise TimeoutError(f"no reply from {self.port} to {method} {path}")
at = line.find(API + "{")
if at < 0:
self._log(line)
continue
if at > 0:
self._log(line[:at])
try:
env = json.loads(line[at + len(API):])
except ValueError:
continue
if env.get("id") != self._id:
continue
text = env.get("body", "")
try:
parsed = json.loads(text) if text else {}
except ValueError:
parsed = text
return int(env.get("status", 0)), 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:
"""Restart the device: the @reboot command, or an RTS reset pulse if it doesn't answer."""
self.open()
self._ser.reset_input_buffer()
self._ser.write(b"\n@reboot\n")
self._ser.flush()
deadline = time.monotonic() + 1.5
while True:
line = self._readline(deadline)
if line is None:
break
if line.strip() == "@ok":
return
self._log(line)
# Hardware reset: RTS high with DTR low holds the chip in reset (DTR low alone would
# mean "boot mode" at release, so RTS goes low first)
self._ser.rts = True
self._ser.dtr = False
time.sleep(0.1)
self._ser.rts = False
self._ser.dtr = True
def follow(self, seconds: Optional[float] = None) -> None:
"""Print the device's output until Ctrl+C, or for SECONDS."""
self.open()
end = time.monotonic() + seconds if seconds is not None else None
while end is None or time.monotonic() < end:
chunk = self._ser.read(256)
if chunk:
sys.stdout.write(chunk.decode("utf-8", "replace"))
sys.stdout.flush()
def probe(port: str, timeout: float = 1.0) -> bool:
"""True if an ESP-IDF led-driver answers the USB API on PORT."""
try:
with IdfDevice(port) as dev:
dev.call_raw("GET", "/api/status", timeout=timeout)
return True
except (TimeoutError, serial.SerialException, OSError):
return False
+1 -1
View File
@@ -10,7 +10,7 @@ pipenv install "$@"
if [ ! -f "dist/led-cli" ] || [ "cli.py" -nt "dist/led-cli" ] || [ "device.py" -nt "dist/led-cli" ]; then
echo ""
echo "Building binary..."
pipenv run pyinstaller --clean led-cli.spec
pipenv run pyinstaller --clean --onefile --name led-cli --paths lib cli.py
fi
# Ensure ~/.local/bin exists
+77
View File
@@ -0,0 +1,77 @@
"""
Over-the-air firmware update for the v2 ESP32-S3 controller (Ethernet, plain HTTP).
The controller takes the raw app image on POST /ota, writes it to the idle slot and reboots.
"""
import http.client
import json
import os
import time
from typing import Optional
IMAGE_NAME = "led_controller_v2.bin"
# Searched in order when no image is given (relative to where the tool is run, since the
# PyInstaller binary has no useful location of its own)
DEFAULT_IMAGES = [
os.path.join("v2", "build", IMAGE_NAME),
os.path.join("build", IMAGE_NAME),
os.path.join("..", "v2", "build", IMAGE_NAME),
]
def _default_image() -> Optional[str]:
return next((p for p in DEFAULT_IMAGES if os.path.isfile(p)), None)
def _info(host: str, port: int) -> Optional[dict]:
try:
conn = http.client.HTTPConnection(host, port, timeout=5)
conn.request("GET", "/ota")
r = conn.getresponse()
return json.loads(r.read().decode()) if r.status == 200 else None
except (OSError, ValueError):
return None
def ota_update(host: str, image: Optional[str] = None, port: int = 80) -> None:
"""Upload image to host and wait for it to come back. Raises RuntimeError on failure."""
image = image or _default_image()
if not image:
raise RuntimeError(f"no image given and {IMAGE_NAME} not found under ./v2/build, ./build or ../v2/build")
if not os.path.isfile(image):
raise RuntimeError(f"image not found: {image}")
size = os.path.getsize(image)
before = _info(host, port)
if before is None:
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)...")
conn = http.client.HTTPConnection(host, port, timeout=60)
with open(image, "rb") as f:
conn.request("POST", "/ota", body=f, headers={
"Content-Length": str(size),
"Content-Type": "application/octet-stream",
})
r = conn.getresponse()
body = r.read().decode()
if r.status != 200:
try:
body = json.loads(body).get("error", body)
except ValueError:
pass
raise RuntimeError(f"update rejected ({r.status}): {body}")
print("Written, waiting for reboot...")
time.sleep(3)
for _ in range(30):
after = _info(host, port)
if after:
print(f"Back up on {after['partition']} (built {after['built']})")
if after["partition"] == before["partition"]:
raise RuntimeError("controller came back on the same slot: new image was rejected or rolled back")
return
time.sleep(1)
raise RuntimeError("controller did not come back within 30 s")