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
pi eee9327e15 docs: fix readme layout and cli flags
Made-with: Cursor
2026-04-12 00:13:49 +12:00
pi 5f7acf38f0 fix(cli): remove --server-ip flag and settings edit path
Made-with: Cursor
2026-04-11 15:20:22 +12:00
9 changed files with 1355 additions and 87 deletions

No files matched your search

+1 -1
View File
@@ -16,5 +16,5 @@ python_version = "3"
[scripts] [scripts]
web = "python web.py" web = "python web.py"
cli = "python cli.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" install = "pipenv install"
+162 -5
View File
@@ -1,8 +1,165 @@
# led-tool # led-tool
- `-s, --show`: Display current settings from device
- `--no-download`: Don't download settings first (use empty settings)
**Default behavior:** Downloads settings and prints them. If any edit flags are provided, settings are modified and uploaded automatically (unless `--no-upload` is specified).
## Device Connection Command-line tool for the LED drivers. It configures both firmwares found in this repo, and updates their firmware:
The tools use an integrated mpremote transport to communicate with MicroPython devices. Make sure your device is connected and accessible via the specified serial port.## LicenseSee LICENSE file for details. - **ESP-IDF led-driver** (ESP32-C3): settings, patterns and presets over **USB** or **Wi-Fi**. Changes apply live, so no reset is needed.
- **MicroPython driver**: `settings.json`, presets and files over USB (via mpremote). Changes need a reset to apply.
The tool detects the firmware on the serial port. Use `--driver idf` or `--driver mpy` to skip detection.
Run `python cli.py -h` for every flag, grouped by firmware, with examples at the end.
## Connecting
| Connection | Flag | Notes |
|---|---|---|
| USB serial (default) | `-p`, `--port` | Default `/dev/ttyACM0`. Opening the port keeps DTR high and RTS low, so the C3 is not reset on connect. |
| Wi-Fi | `--host ADDR` | IP or name of an ESP-IDF driver, for example `--host 192.168.4.20` or `--host bar1.local`. Port 80. |
Over `--host` every settings, pattern and preset flag works the same as over USB. Two flags need USB: `-r` (reboot) and `-f` (follow the serial log). MicroPython is USB only.
## ESP-IDF led-driver
### Settings (USB or Wi-Fi)
| Flag | Setting |
|---|---|
| `--pin`, `-l`, `-o`, `--max-brightness` | LED GPIO, LED count, colour order, global ceiling |
| `-b` | Brightness |
| `-n NAME`, `--reset-device-name` | Hostname (mDNS `NAME.local`); reset gives `led` |
| `--ap on\|off`, `--ap-ssid NAME`, `--ap-password PASS` | Access point (empty name: `led-XXXXXX`; empty password: open) |
| `--ddp on\|off` | Receive DDP pixels and frame sync |
| `--dhcp`, `--static IP NETMASK GATEWAY [DNS]`, `--dns ADDR` | Wi-Fi client address |
| `--ssid SSID`, `--wifi-password PASS` | Wi-Fi network to join; the device reconnects |
| `--default NAME` | Startup preset (runs at boot) |
| `--scan` | List the Wi-Fi networks the device can see |
`-s` shows the settings: hardware, brightness, network, Wi-Fi SSID and the startup preset. It is printed after any change.
Network changes can move the device to a new address. If you change `--static` or `--dhcp` over `--host`, the next command needs the new address.
### Patterns and presets (USB or Wi-Fi)
Presets are saved on the device. Patterns named with `--play` or `--pattern` are the driver's own names; see `--list-patterns`.
| Flag | Does |
|---|---|
| `--list-patterns` | Print the pattern names the driver has |
| `--list-presets` | Print the saved preset names, with the startup one marked |
| `--preset NAME [--pattern P] [options]` | Create or replace a saved preset. Only the fields given are changed. |
| `--play PATTERN [options]` | Show a pattern now, without saving it |
| `--select NAME` | Show a saved preset now |
| `--delete NAME` | Delete a saved preset |
| `--preset-order NAME [NAME ...]` | Set the order of the saved presets |
| `--presets-defaults` | Add the default presets that are missing |
Options for `--preset` and `--play`:
| Option | Meaning |
|---|---|
| `--colors HEX [HEX ...]` | Colours, for example `#ff0000 #00ff00` |
| `--background HEX` | Background colour |
| `--delay MS` | Delay between steps |
| `--preset-brightness 0-255` | Brightness of this preset (not the global level) |
| `--fade MS` | Fade time |
| `--reverse on\|off` | Run in reverse |
| `--auto on\|off` | Autorun flag |
| `--beat-time on\|off` | Time the pattern to the beat |
`--preset` and `--play` cannot be used together. Options given without one of them are an error.
Not yet exposed: the preset's numeric parameters `n1`–`n4` and `mode`.
```bash
python cli.py --list-presets
python cli.py --preset warm --pattern chase --colors '#ff0000' '#00ff00' --delay 50 --default warm
python cli.py --select warm
python cli.py --play rainbow --fade 200
python cli.py --host 192.168.4.20 --preset warm --pattern solid --colors '#ffa000'
```
### Reboot and logs (USB only)
```bash
python cli.py -r # reboot
python cli.py -f # follow the serial log, Ctrl+C to stop
python cli.py -r --pause 2 -f
```
## Firmware updates
Both update over Wi-Fi with the driver's `/ota` endpoint. The image is always given explicitly for LED drivers.
| Flag | Does |
|---|---|
| `--ota HOST [IMAGE]` | Update one **v2 controller** (ESP32-S3, Ethernet). Image defaults to `led_controller_v2.bin` under `./v2/build`, `./build` or `../v2/build`. |
| `--ota-drivers [TARGET ...]` | Find ESP-IDF LED drivers in the given targets and update them in parallel. Default `auto` is this machine's `/24`. See the target forms below. |
| `--ota-image PATH` | Driver firmware for `--ota-drivers`. **Required**, for example `../led-driver/build/led_driver.bin`. |
| `--ota-jobs N` | Simultaneous uploads (default 4). |
| `--ota-list` | Only find and list the drivers; do not update. |
Targets:
| Form | Scans |
|---|---|
| `auto` | This machine's `/24` (default) |
| `192.168.4` | The `/24`, the same as `192.168.4.0/24` |
| `10.0.0.0/23` | A CIDR network (up to 4096 addresses per run) |
| `192.168.4.10-40` or `192.168.4.10-192.168.4.40` | An inclusive address range |
| `192.168.4.25` | One address |
Give several targets separated by spaces or commas. Duplicates are scanned once. A run can probe at most 4096 addresses; larger targets are refused, so narrow them.
```bash
cd led-tool
python cli.py --ota-drivers --ota-image ../led-driver/build/led_driver.bin
python cli.py --ota-drivers 192.168.4.10-40 --ota-list
python cli.py --ota-drivers 192.168.4.0/24 10.0.0.0/25 --ota-jobs 2 --ota-image ../led-driver/build/led_driver.bin
python cli.py --ota-drivers 192.168.4.10-40,192.168.5.7 --ota-image ../led-driver/build/led_driver.bin
```
`--ota-drivers` probes `GET /ota` on each address in the targets, so it only finds devices that run the driver firmware. Drivers are reported with their partition and build; a driver that comes back on the same partition is reported as a failure.
Build the driver image first with `make build` in `led-driver`.
## MicroPython driver
These flags apply to the MicroPython driver only, and are rejected when an ESP-IDF driver answers.
| Flag | Does |
|---|---|
| `-n NAME`, `-l N`, `-b`, `-o`, `--pin` | Settings written to `settings.json` |
| `--preset NAME --pattern P` | Create or replace a preset in `presets.json` (patterns: off, on, blink, rainbow, pulse, transition, chase, circle) |
| `--default NAME` | Startup preset |
| `--transport espnow\|wifi`, `--ssid`, `--wifi-password`, `--wifi-channel`, `--id`, `-d` | Transport and radio settings |
| `-u SRC [DEST]`, `--src [DIR]`, `--lib [DIR]`, `--patterns [DIR]`, `--all` | Upload directories to the device |
| `--ls`, `--rm PATH`, `-e` | List, delete or erase files on the device |
| `--flash BINARY` | Flash a firmware binary with esptool (path, or a filename in `bin/`) |
| `--reset-device-name` | Name becomes `led-` + the STA MAC |
Without setting edits, the tool downloads `settings.json` and prints the merged view. It uploads again only when you pass edits, `--preset`, or an upload, flash or erase action. Actions run in the order given on the command line, for example `--reset --pause 2 --follow`.
## Installing
`install.sh` installs the Python dependencies with pipenv, builds `dist/led-cli` with PyInstaller, and copies it to `~/.local/bin`.
```bash
./install.sh
```
Run from source with `python cli.py` after `pipenv install`.
## Files
| File | Purpose |
|---|---|
| `cli.py` | Argument parsing and the commands for both firmwares |
| `idf_device.py` | ESP-IDF API over USB (`@api` lines on the serial port) |
| `http_device.py` | The same ESP-IDF API over Wi-Fi (`--host`) |
| `device.py` | MicroPython device access via mpremote |
| `ota.py` | Firmware upload to one device, used by `--ota` and `--ota-drivers` |
| `driver_ota.py` | Discovery of ESP-IDF drivers on a subnet and parallel update |
## License
See **LICENSE** in this directory.
+632 -75
View File
@@ -11,11 +11,16 @@ import argparse
import subprocess import subprocess
import sys import sys
import time import time
import shutil
from typing import Dict, Any, List, Optional from typing import Dict, Any, List, Optional
import tempfile import tempfile
import os 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]: def resolve_flash_binary(path: str) -> Optional[str]:
@@ -146,15 +151,16 @@ def print_settings(settings: Dict[str, Any]) -> None:
_FLAGS_WITH_VALUE = frozenset({ _FLAGS_WITH_VALUE = frozenset({
'-p', '--port', '-n', '--name', '--pin', '-b', '--brightness', '-p', '--port', '-n', '--name', '--pin', '-b', '--brightness',
'-l', '--leds', '-d', '-debug', '--debug', '-o', '--order', '-l', '--leds', '-d', '-debug', '--debug', '-o', '--order',
'--preset', '--pattern', '--default', '--transport', '--server-ip', '--ssid', '--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]: def _get_ordered_actions(argv: List[str]) -> List[tuple]:
""" """
Scan argv and return list of (action_name, value) in order of appearance. 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 = [] actions = []
i = 1 i = 1
@@ -178,6 +184,16 @@ def _get_ordered_actions(argv: List[str]) -> List[tuple]:
else: else:
raise ValueError("--flash requires an argument") raise ValueError("--flash requires an argument")
continue 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'): if arg in ('-r', '--reset'):
actions.append(('reset', None)) actions.append(('reset', None))
i += 1 i += 1
@@ -201,22 +217,47 @@ def _get_ordered_actions(argv: List[str]) -> List[tuple]:
i += 2 i += 2
else: else:
i += 1 i += 1
# Use empty string as remote_dir to map to root on device # Upload source tree excluding patterns/ (handled by --patterns).
actions.append(('upload', [local_dir, ""])) actions.append(('upload_src_no_patterns', local_dir))
continue continue
if arg == '--lib': if arg in ('--patterns', '--paterns'):
# Upload local DIR to /lib on device # Upload local patterns DIR (default: ./src/patterns) to /patterns.
if i + 1 < len(argv): local_dir = os.path.join("src", "patterns")
if i + 1 < len(argv) and not argv[i + 1].startswith('-'):
local_dir = argv[i + 1] local_dir = argv[i + 1]
actions.append(('upload', [local_dir, "lib"]))
i += 2 i += 2
else: 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 continue
if arg == '-e': if arg == '-e':
actions.append(('erase_all', None)) actions.append(('erase_all', None))
i += 1 i += 1
continue continue
if arg == '--erase':
actions.append(('erase_all', None))
i += 1
continue
if arg == '--rm': if arg == '--rm':
if i + 1 < len(argv): if i + 1 < len(argv):
actions.append(('rm', argv[i + 1])) actions.append(('rm', argv[i + 1]))
@@ -247,54 +288,349 @@ def _get_ordered_actions(argv: List[str]) -> List[tuple]:
return actions 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: def main() -> None:
parser = argparse.ArgumentParser( 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, formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=""" epilog="""
Examples: Examples
# Download and print current settings Show settings (either driver):
%(prog)s %(prog)s -s
%(prog)s --host 192.168.4.20 -s
# Download, edit device name and brightness, then upload Settings (ESP-IDF, USB or Wi-Fi):
%(prog)s -n "LED-Strip-1" -b 128 %(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 Patterns and presets (ESP-IDF, USB or Wi-Fi):
%(prog)s -n "MyLED" -b 200 --preset "rainbow" %(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 Reboot and logs (USB only):
%(prog)s -l 60 -o rgb -d 1 %(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 Firmware:
%(prog)s -r %(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 MicroPython driver:
%(prog)s -f %(prog)s -n "MyStrip" -l 60 --default rainbow settings.json, then reset to apply
%(prog)s -u ./src upload a directory to the device
# Reset and then follow output %(prog)s --reset-device-name
%(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
""" """
) )
parser.add_argument( parser.add_argument(
"-p", "--port", "-p", "--port",
default="/dev/ttyACM0", 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( parser.add_argument(
"-n", "--name", "-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( parser.add_argument(
@@ -302,21 +638,21 @@ Examples:
dest="device_id", dest="device_id",
type=int, type=int,
metavar="0-255", 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( parser.add_argument(
"--pin", "--pin",
type=int, type=int,
metavar="N", metavar="N",
help="LED GPIO pin number (led_pin in settings.json)" help="LED GPIO pin number (both drivers)"
) )
parser.add_argument( parser.add_argument(
"-b", "--brightness", "-b", "--brightness",
type=int, type=int,
metavar="0-255", metavar="0-255",
help="Brightness (0-255)" help="Brightness, 0-255 (both drivers)"
) )
parser.add_argument( parser.add_argument(
@@ -324,7 +660,7 @@ Examples:
dest="leds", dest="leds",
type=int, type=int,
metavar="N", metavar="N",
help="Number of LEDs (num_leds in settings.json)" help="Number of LEDs in the strip (both drivers)"
) )
parser.add_argument( parser.add_argument(
@@ -333,58 +669,50 @@ Examples:
type=int, type=int,
choices=[0, 1], choices=[0, 1],
metavar="0|1", metavar="0|1",
help="Debug mode (0 or 1)" help="(MicroPython) debug mode, 0 or 1"
) )
parser.add_argument( parser.add_argument(
"-o", "--order", "-o", "--order",
dest="color_order", dest="color_order",
choices=["rgb", "rbg", "grb", "gbr", "brg", "bgr"], 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( parser.add_argument(
"--preset", "--preset",
metavar="NAME", 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( parser.add_argument(
"--pattern", "--pattern",
choices=[ help="Pattern for --preset (MicroPython: off, on, blink, rainbow, pulse, transition, chase, circle;"
"off", "on", "blink", "rainbow", "pulse", "transition", "chase", "circle", " ESP-IDF: any name from -s 'patterns'). MicroPython default: on",
],
help="Pattern type for --preset (default: on)",
) )
parser.add_argument( parser.add_argument(
"--default", "--default",
metavar="NAME", 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( parser.add_argument(
"--transport", "--transport",
choices=["espnow", "wifi"], choices=["espnow", "wifi"],
help="led-driver transport_type", help="(MicroPython) transport_type: espnow or wifi",
)
parser.add_argument(
"--server-ip",
metavar="IP",
help="led-driver server_ip (Pi TCP host in wifi mode)",
) )
parser.add_argument( parser.add_argument(
"--ssid", "--ssid",
help="led-driver ssid (Wi-Fi network in wifi mode)", help="Wi-Fi network to join (both drivers)",
) )
parser.add_argument( parser.add_argument(
"--wifi-password", "--wifi-password",
dest="wifi_password", dest="wifi_password",
metavar="PASS", 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( parser.add_argument(
@@ -392,7 +720,7 @@ Examples:
dest="wifi_channel", dest="wifi_channel",
type=int, type=int,
metavar="1-11", metavar="1-11",
help="led-driver wifi_channel (ESP-NOW mode)", help="(MicroPython) ESP-NOW channel, 1-11",
) )
parser.add_argument( parser.add_argument(
@@ -405,7 +733,7 @@ Examples:
parser.add_argument( parser.add_argument(
"-r", "--reset", "-r", "--reset",
action="store_true", action="store_true",
help="Reset the device" help="Reboot the device (USB only, both drivers)"
) )
parser.add_argument( parser.add_argument(
@@ -414,20 +742,20 @@ Examples:
const=None, const=None,
type=float, type=float,
metavar="SECONDS", 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( parser.add_argument(
"-s", "--show", "-s", "--show",
action="store_true", action="store_true",
help="Display current settings from device" help="Show the current settings (both drivers)"
) )
parser.add_argument( parser.add_argument(
"-u", "--upload", "-u", "--upload",
nargs='+', nargs='+',
metavar=("SRC", "DEST"), 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( parser.add_argument(
@@ -435,34 +763,158 @@ Examples:
nargs="?", nargs="?",
const="src", const="src",
metavar="DIR", 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( parser.add_argument(
"--lib", "--lib",
nargs="?",
const="lib",
metavar="DIR", metavar="DIR",
help="Upload DIR recursively to /lib on device" help="(MicroPython) upload DIR to /lib on the device (default: ./lib)"
) )
parser.add_argument( 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", dest="erase_all",
action="store_true", 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( parser.add_argument(
"--rm", "--rm",
metavar="PATH", 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( parser.add_argument(
"--flash", "--flash",
metavar="BINARY", 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: try:
args = parser.parse_args() args = parser.parse_args()
ordered_actions = _get_ordered_actions(sys.argv) ordered_actions = _get_ordered_actions(sys.argv)
@@ -470,9 +922,40 @@ Examples:
print(f"Error: {e}", file=sys.stderr) print(f"Error: {e}", file=sys.stderr)
sys.exit(1) 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 port = args.port
ran_reset = False 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 # Execute actions in command-line order
for action_name, value in ordered_actions: for action_name, value in ordered_actions:
if action_name == 'pause': if action_name == 'pause':
@@ -498,6 +981,15 @@ Examples:
print("Error: esptool not found. Install it with: pip install esptool", file=sys.stderr) print("Error: esptool not found. Install it with: pip install esptool", file=sys.stderr)
sys.exit(1) 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': elif action_name == 'reset':
ran_reset = True ran_reset = True
try: try:
@@ -532,6 +1024,50 @@ Examples:
except Exception as e: except Exception as e:
print(f"Error uploading directory: {e}", file=sys.stderr) print(f"Error uploading directory: {e}", file=sys.stderr)
sys.exit(1) 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': elif action_name == 'erase_all':
try: try:
@@ -575,11 +1111,35 @@ Examples:
sys.exit(1) sys.exit(1)
return # follow blocks; when interrupted we're done 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 # Collect all edit parameters
edits: Dict[str, Any] = {} edits: Dict[str, Any] = {}
if args.name is not None: if args.name is not None:
edits["name"] = args.name edits["name"] = args.name
elif default_name_from_device is not None:
edits["name"] = default_name_from_device
if args.pin is not None: if args.pin is not None:
edits["led_pin"] = args.pin edits["led_pin"] = args.pin
@@ -602,9 +1162,6 @@ Examples:
if args.transport is not None: if args.transport is not None:
edits["transport_type"] = args.transport edits["transport_type"] = args.transport
if args.server_ip is not None:
edits["server_ip"] = args.server_ip
if args.ssid is not None: if args.ssid is not None:
edits["ssid"] = args.ssid edits["ssid"] = args.ssid
+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) sys.path.insert(0, lib_path)
from mpremote.transport_serial import SerialTransport from mpremote.transport_serial import SerialTransport
from mpremote.transport import TransportError from mpremote.transport import TransportError, TransportExecError
class DeviceConnection: class DeviceConnection:
"""Wrapper for device communication.""" """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): def __init__(self, device):
"""Connect to a device.""" """Connect to a device."""
self.device = device self.device = device
@@ -53,7 +56,39 @@ class DeviceConnection:
except Exception: except Exception:
pass pass
self.transport = None 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): def copy_from_device(self, remote_path, local_path):
"""Copy a file from device to local filesystem.""" """Copy a file from device to local filesystem."""
self.connect() self.connect()
@@ -70,7 +105,7 @@ class DeviceConnection:
try: try:
with open(local_path, 'rb') as f: with open(local_path, 'rb') as f:
data = f.read() data = f.read()
self.transport.fs_writefile(remote_path, data) self._fs_writefile_with_wdt(remote_path, data)
finally: finally:
self.disconnect() self.disconnect()
@@ -87,6 +122,13 @@ class DeviceConnection:
if not os.path.isdir(local_dir): if not os.path.isdir(local_dir):
raise ValueError(f"{local_dir} is not a directory") 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() self.connect()
try: try:
# Determine remote directory name # Determine remote directory name
@@ -123,6 +165,8 @@ class DeviceConnection:
# Copy files # Copy files
for file in files: for file in files:
if file.endswith((".pyc", ".pyo")):
continue
local_file = os.path.join(root, file) local_file = os.path.join(root, file)
# Handle root directory case properly # Handle root directory case properly
if remote_base == '/': if remote_base == '/':
@@ -133,7 +177,7 @@ class DeviceConnection:
print(f"Uploading: {remote_file}", file=sys.stderr) print(f"Uploading: {remote_file}", file=sys.stderr)
with open(local_file, 'rb') as f: with open(local_file, 'rb') as f:
data = f.read() data = f.read()
self.transport.fs_writefile(remote_file, data) self._fs_writefile_with_wdt(remote_file, data)
files_copied += 1 files_copied += 1
return files_copied, dirs_created return files_copied, dirs_created
@@ -235,6 +279,37 @@ class DeviceConnection:
raise TransportError(f"Failed to follow output: {e}") from e 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): def copy_file(from_device, device, remote_path, local_path):
""" """
Copy a file to/from device. 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 if [ ! -f "dist/led-cli" ] || [ "cli.py" -nt "dist/led-cli" ] || [ "device.py" -nt "dist/led-cli" ]; then
echo "" echo ""
echo "Building binary..." echo "Building binary..."
pipenv run pyinstaller --clean led-cli.spec pipenv run pyinstaller --clean --onefile --name led-cli --paths lib cli.py
fi fi
# Ensure ~/.local/bin exists # 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")