picolan 1.0.0__py3-none-any.whl

picolan-1.0.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: picolan
+Version: 1.0.0
+Summary: Update, find and monitor RP2350 + W5500 boards that run the picolan library, over Ethernet
+Author: Avi Raviv
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: tools/LICENSE
+Dynamic: license-file
+
+# picolan command-line tool
+
+The `picolan` command finds, updates and monitors boards that run the picolan firmware library, over Ethernet. You do not need the source code, PlatformIO or a GitHub account.
+
+## Install
+
+Requirement: Python 3.9 or later. The tool uses only the Python standard library.
+
+```sh
+pip install picolan
+```
+
+Update: `pip install -U picolan`. Check the version: `picolan --version`.
+
+| System | Status |
+|---|---|
+| Linux | Tested. All network interfaces are used. |
+| Windows | Supported. Not yet tested on hardware. |
+| macOS | Default network interface only. Not tested. |
+
+## Connect the PC
+
+1. Connect the PC to the network of the boards.
+2. Give the PC an IP address in the subnet of the boards. Example: boards on 192.168.1.x/24, PC on 192.168.1.50/24.
+3. Run `picolan nodes`.
+
+`picolan nodes` also finds boards in another subnet. An update needs an IP route to the board.
+
+## Update a system from a release bundle
+
+A bundle is a zip file. It holds one firmware image per product and a manifest with the SHA-256 of each image.
+
+1. Copy the bundle to the PC, for example `release-v6.4.0.zip`.
+2. Run `picolan nodes`. Make sure that each product of the bundle appears once.
+3. Run `picolan push release-v6.4.0.zip`.
+
+For each image, the tool:
+
+1. Finds the one board that runs the product of the image.
+2. Sends the image. The board restarts on the new firmware.
+3. Waits until the new firmware has run for 10 s, then confirms it.
+4. Checks that the board runs the new firmware.
+
+The tool updates the boards one at a time. It stops at the first failure. At the end it prints one result line per board.
+
+| Situation | Result |
+|---|---|
+| A product of the bundle has no board, or more than one board | Nothing is installed. |
+| An image was changed after the bundle was made | Nothing is installed. |
+| A board already runs the image | Skipped. Use `--reinstall` to install again. |
+| The new firmware fails | The board restores its previous firmware by itself. The tool stops. |
+
+## Commands
+
+| Command | Use |
+|---|---|
+| `picolan nodes` | List the boards: product, chip ID, IP, build, state. |
+| `picolan push <files>` | Update boards from `.bin` files or bundles. |
+| `picolan logs` | Show the log of a board. Ctrl+C to stop. |
+| `picolan wipe` | Erase the stored data of a board (LittleFS and EEPROM). The firmware stays. |
+| `picolan reboot` | Restart a board. |
+| `picolan blink [seconds]` | Blink the LED of a board, if the firmware has one configured. |
+| `picolan bundle -o <zip> <files>` | Make a bundle from `.bin` files. |
+
+## Select a board
+
+`logs`, `wipe`, `reboot` and `blink` act on one board. With one board on the network, no option is necessary. Otherwise add `--node`:
+
+```sh
+picolan --node motor-controller logs      # product name
+picolan --node 192.168.1.4 reboot
+picolan --node 5C82 wipe                  # chip ID or a unique prefix of it
+```
+
+The value must match exactly one board, or the tool stops.
+
+## Install log
+
+The tool adds one line per board to an install log:
+
+| System | File |
+|---|---|
+| Linux | `~/.local/state/picolan/install.log` |
+| Windows | `%LOCALAPPDATA%\picolan\install.log` |
+
+Example line:
+
+```
+2026-11-14T19:02:58+0200 result=OK chip=5C829BF5E4BF9E53 ip=192.168.1.33 product=sensor-hub from=a1b2c3d/2B393BC5 to=d4e5f6a/585622FA release=my-system/v6.4.0 source=release-v6.4.0.zip:sensor-hub.bin
+```
+
+`result` is `OK`, `FAILED`, `SKIPPED` or `UNCONFIRMED`. Use `--log <file>` or the environment variable `PICOLAN_LOG` for another file, and `--no-log` for none.
+
+## Network options
+
+| Option | Use |
+|---|---|
+| `--iface <name or IP>` | Use only this network interface. Linux: interface name, for example `eth0`. Any system: a local IPv4 address. Repeatable. |
+| `PICOLAN_IFACE=eth0,eth1` | The same, as an environment variable. |
+
+Port: 8208, UDP (discovery, commands, log) and TCP (firmware transfer).

picolan-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+picolan.py,sha256=BF2cXCY8wpRwhfhbDQqGOKlI560MfvZ0kPE2cK688lg,36298
+picolan-1.0.0.dist-info/licenses/tools/LICENSE,sha256=bxRQrmzgXg2M9IUAMt9g3FD5tnHmWOAbmJlSwQuCRx0,1066
+picolan-1.0.0.dist-info/METADATA,sha256=I6C8klgli50u1fVMRxYMo7B3_jUpVe5oB3V4j9FGvZo,4398
+picolan-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+picolan-1.0.0.dist-info/entry_points.txt,sha256=k3vnsJQpm9jMjI1jWvxJrMVNFQYE3wTtyZ3abdEw7-s,41
+picolan-1.0.0.dist-info/top_level.txt,sha256=Nv5jX-MMgO5_omJoD5e3yQSot3bdjmNURr2CR1yW0VE,8
+picolan-1.0.0.dist-info/RECORD,,

picolan-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

picolan-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+picolan = picolan:main

picolan-1.0.0.dist-info/licenses/tools/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avi Raviv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

picolan-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+picolan

picolan.py

@@ -0,0 +1,888 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+"""picolan: find, update and monitor picolan boards over Ethernet.
+
+    picolan nodes                          boards on the network
+    picolan push                           build the PlatformIO project here, update its board
+    picolan push app.bin [more.bin ...]    update each board that runs the product of an image
+    picolan push release.zip               update all boards of a release bundle
+    picolan logs                           network log, like pio device monitor
+    picolan blink [seconds]                blink the LED of a board
+    picolan wipe                           erase LittleFS and EEPROM, restart the board
+    picolan reboot
+    picolan bundle -o release.zip a.bin b.bin
+    picolan mac <chip>                     MAC address derived from a chip ID
+
+Board selection (--node, or --upload-port in PlatformIO): a chip ID or a
+unique prefix of it, an IP address, or a product name. It must match exactly
+one board. Without --node a command uses the only board of the product
+(push: the product of the image; --product), or the only board on the network.
+
+Uses only the Python standard library (3.9+). Linux and Windows; macOS: default
+network interface only.
+"""
+import argparse
+import configparser
+import datetime
+import hashlib
+import io
+import json
+import os
+import re
+import select
+import shutil
+import socket
+import struct
+import subprocess
+import sys
+import time
+import zipfile
+import zlib
+
+__version__ = "1.0.0"
+
+PROTOCOL = 1
+TAG_M1 = 0x4C434950
+TAG_M2 = 0x8E3D71A5
+TAG_FMT = "<III32s32sI"
+TAG_SIZE = struct.calcsize(TAG_FMT)
+SO_BINDTODEVICE = getattr(socket, "SO_BINDTODEVICE", 25)
+BUNDLE_FORMAT = "picolan-bundle"
+BUNDLE_VERSION = 1
+IS_LINUX = sys.platform.startswith("linux")
+
+
+class ToolError(Exception):
+    pass
+
+
+def say(msg=""):
+    print(msg, flush=True)
+
+
+def out(text):
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+
+# ---------------------------------------------------------------- images
+
+def mac_from_chip(chip_hex):
+    h = 0xCBF29CE484222325
+    for b in bytes.fromhex(chip_hex):
+        h ^= b
+        h = (h * 0x100000001B3) & 0xFFFFFFFFFFFFFFFF
+    low = h & 0xFFFFFFFFFF
+    return ":".join("%02X" % x for x in [0xD2] + [(low >> (8 * i)) & 0xFF for i in range(4, -1, -1)])
+
+
+def find_tag(image):
+    """Return (product, build, protocol) of the picolan tag in an image, or None."""
+    magic = struct.pack("<II", TAG_M1, TAG_M2)
+    start = 0
+    while True:
+        off = image.find(magic, start)
+        if off < 0 or off + TAG_SIZE > len(image):
+            return None
+        if off % 4 == 0:
+            _, _, proto, product, build, m3 = struct.unpack_from(TAG_FMT, image, off)
+            if m3 == (~TAG_M1 & 0xFFFFFFFF):
+                def cut(b):
+                    return b.split(b"\0", 1)[0].decode(errors="replace")
+                return cut(product), cut(build), proto
+        start = off + 1
+
+
+class Image:
+    """A firmware image and the data picolan needs from it."""
+
+    def __init__(self, data, source):
+        self.data = data
+        self.source = source
+        tag = find_tag(data)
+        if not tag:
+            raise ToolError("%s does not contain picolan. After this upload the board could not "
+                            "be updated over Ethernet any more. Use USB." % source)
+        self.product, self.build, proto = tag
+        if proto != PROTOCOL:
+            raise ToolError("%s uses picolan protocol %d, this tool speaks %d"
+                            % (source, proto, PROTOCOL))
+        self.crc = zlib.crc32(data) & 0xFFFFFFFF
+        self.sha256 = hashlib.sha256(data).hexdigest()
+
+    @property
+    def crc_hex(self):
+        return "%08X" % self.crc
+
+
+def read_file(path):
+    try:
+        with open(path, "rb") as f:
+            return f.read()
+    except OSError as e:
+        raise ToolError("cannot read %s: %s" % (path, e))
+
+
+# ---------------------------------------------------------------- bundles
+
+def make_bundle(images, name, release):
+    """Return the bytes of a bundle (zip) that holds the images and a manifest."""
+    seen = {}
+    for im in images:
+        if im.product in seen:
+            raise ToolError("%s and %s are both for product '%s'. A bundle holds one image per "
+                            "product." % (seen[im.product], im.source, im.product))
+        seen[im.product] = im.source
+    manifest = {
+        "format": BUNDLE_FORMAT,
+        "version": BUNDLE_VERSION,
+        "name": name,
+        "release": release,
+        "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "tool": __version__,
+        "images": [{"file": "%s.bin" % im.product, "product": im.product, "build": im.build,
+                    "size": len(im.data), "crc32": im.crc_hex, "sha256": im.sha256}
+                   for im in images],
+    }
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("manifest.json", json.dumps(manifest, indent=2) + "\n")
+        for im in images:
+            z.writestr("%s.bin" % im.product, im.data)
+    return buf.getvalue()
+
+
+def load_bundle(data, source):
+    """Return (manifest, [Image]) after checking every image against the manifest."""
+    try:
+        z = zipfile.ZipFile(io.BytesIO(data))
+        manifest = json.loads(z.read("manifest.json").decode())
+    except (zipfile.BadZipFile, KeyError, ValueError) as e:
+        raise ToolError("%s is not a picolan bundle (%s)" % (source, e))
+    if manifest.get("format") != BUNDLE_FORMAT:
+        raise ToolError("%s is not a picolan bundle (no picolan manifest)" % source)
+    if manifest.get("version") != BUNDLE_VERSION:
+        raise ToolError("%s has bundle format %s; this tool reads format %d. Update the tool: "
+                        "pip install -U picolan" % (source, manifest.get("version"),
+                                                    BUNDLE_VERSION))
+    images, products = [], set()
+    for entry in manifest.get("images", []):
+        fname = entry.get("file", "")
+        try:
+            body = z.read(fname)
+        except KeyError:
+            raise ToolError("%s: manifest lists %s, but the file is missing" % (source, fname))
+        if hashlib.sha256(body).hexdigest() != entry.get("sha256"):
+            raise ToolError("%s: %s is damaged or was changed (SHA-256 differs from the manifest)"
+                            % (source, fname))
+        im = Image(body, "%s:%s" % (os.path.basename(source), fname))
+        if im.product != entry.get("product") or im.build != entry.get("build"):
+            raise ToolError("%s: %s contains %s build %s, the manifest says %s build %s"
+                            % (source, fname, im.product, im.build, entry.get("product"),
+                               entry.get("build")))
+        if im.product in products:
+            raise ToolError("%s: two images for product '%s'" % (source, im.product))
+        products.add(im.product)
+        images.append(im)
+    if not images:
+        raise ToolError("%s contains no images" % source)
+    return manifest, images
+
+
+def load_images(paths):
+    """Images from .bin files and bundles. Returns (images, bundle manifests)."""
+    images, manifests = [], []
+    for p in paths:
+        data = read_file(p)
+        if data[:4] == b"PK\x03\x04":
+            m, ims = load_bundle(data, p)
+            manifests.append(m)
+            images += ims
+        else:
+            images.append(Image(data, p))
+    seen = {}
+    for im in images:
+        if im.product in seen:
+            raise ToolError("%s and %s are both for product '%s'. Give one image per product."
+                            % (seen[im.product], im.source, im.product))
+        seen[im.product] = im.source
+    return images, manifests
+
+
+# ---------------------------------------------------------------- PlatformIO project
+
+def find_pio():
+    for name in ("pio", "platformio"):
+        p = shutil.which(name)
+        if p:
+            return p
+    home = os.path.expanduser("~")
+    for p in (os.path.join(home, ".platformio", "penv", "bin", "pio"),
+              os.path.join(home, ".platformio", "penv", "Scripts", "pio.exe")):
+        if os.path.isfile(p):
+            return p
+    raise ToolError("PlatformIO not found. Install it, or give the firmware file: "
+                    "picolan push firmware.bin")
+
+
+def project_envs(ini_path):
+    cp = configparser.ConfigParser(inline_comment_prefixes=(";", "#"), strict=False,
+                                   interpolation=None)
+    cp.read(ini_path)
+    envs = [s[4:] for s in cp.sections() if s.startswith("env:")]
+    default = []
+    if cp.has_option("platformio", "default_envs"):
+        default = [e for e in re.split(r"[,\s]+", cp.get("platformio", "default_envs")) if e]
+    return envs, default
+
+
+def build_project(env_name):
+    """Build the PlatformIO project in the current folder; return the image path."""
+    ini = os.path.join(os.getcwd(), "platformio.ini")
+    if not os.path.isfile(ini):
+        raise ToolError("no firmware file given and no platformio.ini in this folder")
+    envs, default = project_envs(ini)
+    if not env_name:
+        if len(default) == 1:
+            env_name = default[0]
+        elif len(envs) == 1:
+            env_name = envs[0]
+        else:
+            raise ToolError("this project has more than one environment (%s). Select one with "
+                            "-e <env>." % ", ".join(envs))
+    if env_name not in envs:
+        raise ToolError("no environment '%s' in platformio.ini (%s)" % (env_name, ", ".join(envs)))
+    say("Building %s ..." % env_name)
+    rc = subprocess.call([find_pio(), "run", "-e", env_name])
+    if rc != 0:
+        raise ToolError("build failed")
+    return os.path.join(os.getcwd(), ".pio", "build", env_name, "firmware.bin")
+
+
+# ---------------------------------------------------------------- install log
+
+def default_log_path():
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+        return os.path.join(base, "picolan", "install.log")
+    base = os.environ.get("XDG_STATE_HOME") or os.path.join(os.path.expanduser("~"), ".local",
+                                                             "state")
+    return os.path.join(base, "picolan", "install.log")
+
+
+def write_log(path, fields):
+    if not path:
+        return
+    stamp = datetime.datetime.now().astimezone().strftime("%Y-%m-%dT%H:%M:%S%z")
+    line = stamp + " " + " ".join("%s=%s" % (k, str(v).replace(" ", "_")) for k, v in fields)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except OSError as e:
+        say("warning: cannot write the install log %s: %s" % (path, e))
+
+
+# ---------------------------------------------------------------- network
+
+def linux_ifaces():
+    """Physical or USB network interfaces that are up (no loopback/virtual)."""
+    base = "/sys/class/net"
+    found = []
+    try:
+        names = sorted(os.listdir(base))
+    except OSError:
+        return found
+    for name in names:
+        if name == "lo" or os.path.exists(os.path.join("/sys/devices/virtual/net", name)):
+            continue
+        try:
+            with open(os.path.join(base, name, "operstate")) as f:
+                if f.read().strip() not in ("up", "unknown"):
+                    continue
+        except OSError:
+            continue
+        found.append(name)
+    return found
+
+
+def iface_ipv4(name):
+    """(address, netmask) of a Linux interface, or None."""
+    try:
+        import fcntl
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        req = struct.pack("256s", name.encode()[:15])
+        addr = socket.inet_ntoa(fcntl.ioctl(s.fileno(), 0x8915, req)[20:24])  # SIOCGIFADDR
+        mask = socket.inet_ntoa(fcntl.ioctl(s.fileno(), 0x891B, req)[20:24])  # SIOCGIFNETMASK
+        s.close()
+        return addr, mask
+    except (OSError, ImportError):
+        return None
+
+
+def local_ipv4():
+    """IPv4 addresses of this PC (any OS), without loopback."""
+    addrs = set()
+    try:
+        for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            addrs.add(info[4][0])
+    except OSError:
+        pass
+    try:
+        addrs.update(socket.gethostbyname_ex(socket.gethostname())[2])
+    except OSError:
+        pass
+    return sorted(a for a in addrs if not a.startswith("127."))
+
+
+def is_ipv4(text):
+    try:
+        socket.inet_aton(text)
+    except OSError:
+        return False
+    return text.count(".") == 3
+
+
+class Bus:
+    """UDP broadcast on the management port, on every network interface.
+
+    Linux: one socket per interface (SO_BINDTODEVICE). Other systems: one
+    socket per local IPv4 address, plus one on all addresses. A broadcast
+    from a socket bound to an address leaves through that interface."""
+
+    def __init__(self, port, ifaces):
+        self.port = port
+        self.socks = []
+        if IS_LINUX:
+            for name in [i for i in ifaces if not is_ipv4(i)] or ([] if ifaces else linux_ifaces()):
+                s = self._sock()
+                try:
+                    s.setsockopt(socket.SOL_SOCKET, SO_BINDTODEVICE, name.encode())
+                except OSError:
+                    s.close()
+                    continue
+                s.bind(("", 0))
+                self.socks.append((name, s))
+        addrs = [i for i in ifaces if is_ipv4(i)]
+        if not IS_LINUX and not ifaces:
+            addrs = local_ipv4()
+        for a in addrs:
+            s = self._sock()
+            try:
+                s.bind((a, 0))
+            except OSError:
+                s.close()
+                continue
+            self.socks.append((a, s))
+        if not self.socks or (not IS_LINUX and not ifaces):
+            s = self._sock()
+            s.bind(("", 0))
+            self.socks.append(("any", s))
+
+    @staticmethod
+    def _sock():
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        return s
+
+    def send(self, text):
+        for _, s in self.socks:
+            try:
+                s.sendto(text.encode(), ("255.255.255.255", self.port))
+            except OSError:
+                pass
+
+    def recv(self, timeout):
+        """Yield (iface, text) until timeout seconds have passed."""
+        end = time.time() + timeout
+        by_fd = {s.fileno(): (n, s) for n, s in self.socks}
+        while True:
+            left = end - time.time()
+            if left <= 0:
+                return
+            ready, _, _ = select.select(list(by_fd), [], [], left)
+            for fd in ready:
+                name, s = by_fd[fd]
+                try:
+                    data, _ = s.recvfrom(2048)
+                except OSError:
+                    continue
+                yield name, data.decode(errors="replace")
+
+
+def parse_node(text, iface):
+    fields = dict(kv.split("=", 1) for kv in text.split()[1:] if "=" in kv)
+    fields["iface"] = iface
+    return fields
+
+
+def discover(bus, timeout=1.2, max_wait=3.5):
+    """Collect NODE answers. Waits at least `timeout` s; resends DISCOVER once a
+    second until something answers or `max_wait` s have passed (a board with a
+    busy main loop can answer late)."""
+    nodes = {}
+    start = time.time()
+    while True:
+        bus.send("DISCOVER")
+        for iface, text in bus.recv(1.0):
+            if text.startswith("NODE "):
+                n = parse_node(text, iface)
+                if "chip" in n:
+                    nodes[n["chip"]] = n
+        waited = time.time() - start
+        if (nodes and waited >= timeout) or waited >= max(max_wait, timeout):
+            return nodes
+
+
+def print_table(nodes):
+    cols = ["product", "chip", "ip", "build", "state", "conflict", "iface"]
+    head = ["PRODUCT", "CHIP", "IP", "BUILD", "STATE", "IP CONFLICT", "IFACE"]
+    rows = [[n.get(c, "?") if c != "conflict" else ("YES" if n.get(c) == "1" else "no")
+             for c in cols]
+            for n in sorted(nodes.values(), key=lambda n: (n.get("product", ""), n["chip"]))]
+    widths = [max(len(h), *(len(r[i]) for r in rows)) for i, h in enumerate(head)]
+    say("  ".join(h.ljust(w) for h, w in zip(head, widths)).rstrip())
+    for r in rows:
+        say("  ".join(v.ljust(w) for v, w in zip(r, widths)).rstrip())
+    seen = {}
+    for n in nodes.values():
+        seen.setdefault(n.get("ip"), []).append(n["chip"])
+    for ip, chips in seen.items():
+        if len(chips) > 1:
+            say("warning: %s is used by %d boards: %s" % (ip, len(chips), ", ".join(chips)))
+
+
+def match_target(nodes, target):
+    """Boards that a --node value names: IP, product name, or chip ID prefix."""
+    if is_ipv4(target):
+        return [n for n in nodes.values() if n.get("ip") == target]
+    by_product = [n for n in nodes.values() if n.get("product") == target]
+    if by_product:
+        return by_product
+    if re.fullmatch(r"[0-9A-Fa-f]{1,16}", target):
+        t = target.upper()
+        return [n for c, n in nodes.items() if c.upper().startswith(t)]
+    return []
+
+
+def select_node(nodes, target, product):
+    """The one board named by `target`, else the only board of `product`, else
+    the only board on the network."""
+    if target:
+        hits = match_target(nodes, target)
+        what = "'%s'" % target
+    else:
+        hits = [n for n in nodes.values() if not product or n.get("product") == product]
+        what = "product '%s'" % product if product else "any product"
+    if len(hits) == 1:
+        return hits[0]
+    if not hits:
+        if nodes:
+            say("Boards on the network:")
+            print_table(nodes)
+            raise ToolError("no board matches %s" % what)
+        raise ToolError("no board answered. Check the cable and that the firmware contains "
+                        "picolan.")
+    say("More than one board matches %s:" % what)
+    print_table({n["chip"]: n for n in hits})
+    raise ToolError("select one with --node <chip ID or IP> (pio: --upload-port <chip ID or IP>)")
+
+
+def subnet_hint(node):
+    ip = node.get("ip", "?")
+    mine = []
+    if IS_LINUX:
+        for name in linux_ifaces():
+            a = iface_ipv4(name)
+            if a:
+                mine.append("%s %s/%s" % (name, a[0], a[1]))
+    else:
+        mine = local_ipv4()
+    return ("cannot open a TCP connection to %s.\n"
+            "  The PC needs an address in the board's subnet (%s/%s).\n"
+            "  PC addresses: %s\n"
+            "  Fix: give the PC an address in that subnet."
+            % (ip, ip, node.get("subnet", "?"), ", ".join(mine) or "unknown"))
+
+
+def command(bus, node, text, expect, timeout=1.5, tries=3):
+    """Send a chip-addressed command; return the reply split into words, or None."""
+    for _ in range(tries):
+        bus.send(text)
+        for _, reply in bus.recv(timeout):
+            parts = reply.split()
+            if len(parts) >= 3 and parts[1] == expect and parts[2] == node["chip"]:
+                return parts
+    return None
+
+
+def refused(parts):
+    return " ".join(parts[3:]) if parts and len(parts) > 3 else "no answer"
+
+
+# ---------------------------------------------------------------- push
+
+def read_line(sock, timeout):
+    sock.settimeout(timeout)
+    data = b""
+    while not data.endswith(b"\n"):
+        ch = sock.recv(1)
+        if not ch:
+            break
+        data += ch
+    return data.decode(errors="replace").strip()
+
+
+def transfer(node, image, force):
+    """Send the image over TCP. Returns after the board answered OK."""
+    try:
+        sock = socket.create_connection((node["ip"], int(node.get("update", 8208))), timeout=4)
+    except OSError:
+        raise ToolError(subnet_hint(node))
+    with sock:
+        try:
+            hello = read_line(sock, 5).split()
+            if len(hello) < 3 or hello[0] != "PICOLAN":
+                raise ToolError("unexpected answer from %s: %s" % (node["ip"], " ".join(hello)))
+            if hello[2] != node["chip"]:
+                raise ToolError("%s answered as chip %s, not %s: two devices share this IP"
+                                % (node["ip"], hello[2], node["chip"]))
+            sock.sendall(("PUSH %s %d %s %s %d\n" % (node["chip"], len(image.data), image.crc_hex,
+                                                     image.product, 1 if force else 0)).encode())
+            ready = read_line(sock, 30)
+            if ready != "READY":
+                raise ToolError("board refused the update: %s" % (ready or "connection closed"))
+            data = image.data
+            sent, step = 0, max(len(data) // 20, 1)
+            mark = step
+            out("Sending ")
+            while sent < len(data):
+                sent += sock.send(data[sent:sent + 4096])
+                while sent >= mark:
+                    out(".")
+                    mark += step
+            result = read_line(sock, 30)
+        except socket.timeout:
+            raise ToolError("the board stopped answering during the transfer. It keeps its "
+                            "current firmware.")
+        except OSError as e:
+            raise ToolError("connection lost during the transfer (%s). The board keeps its "
+                            "current firmware." % e)
+    if result != "OK":
+        say("")
+        raise ToolError("board refused the image: %s" % (result or "connection closed"))
+
+
+def push_one(bus, node, image, force, confirm):
+    """Update one board. Raises ToolError on failure."""
+    t0 = time.time()
+    say("Board   %s  %s  %s build %s (%s)" % (node["chip"], node["ip"], node.get("product"),
+                                              node.get("build"), node.get("state")))
+    say("Image   %s build %s, %d bytes, crc %s" % (image.product, image.build, len(image.data),
+                                                   image.crc_hex))
+    transfer(node, image, force)
+    say(" OK (%.1f s)" % (time.time() - t0))
+
+    say("Waiting for the board to start the new firmware ...")
+    t1 = time.time()
+    back = None
+    while time.time() - t1 < 60:
+        n = discover(bus, 0.5, 1.0).get(node["chip"])
+        if not n:
+            continue
+        if n.get("state") == "trial" and n.get("trialcrc", "").upper() == image.crc_hex:
+            back = n
+            break
+        if n.get("state") == "rolledback" and n.get("crc") != image.crc_hex:
+            raise ToolError("the new firmware failed (it kept restarting); the board restored "
+                            "the previous firmware. See: picolan logs")
+        if n.get("state") == "committed" and n.get("crc") != image.crc_hex and \
+                time.time() - t1 > 3:
+            raise ToolError("the new firmware did not start; the board runs its previous "
+                            "firmware. See: picolan logs")
+    if not back:
+        raise ToolError("the board did not come back within 60 s. If the new firmware is broken, "
+                        "the board restores the previous firmware by itself. See: picolan logs")
+    say("Running build %s on trial after %.1f s" % (back.get("build"), time.time() - t1))
+    if not confirm:
+        say("Not confirming (--no-confirm): the board restores the previous firmware after %s "
+            "unconfirmed boots." % back.get("maxboots", "?"))
+        return
+
+    # The board accepts the confirmation only after the new firmware has run
+    # normally for a while (confirmAfterMs, default 10 s).
+    out("Confirming ")
+    deadline = time.time() + 45
+    while True:
+        parts = command(bus, node, "COMMIT %s %s" % (node["chip"], image.crc_hex), "COMMIT",
+                        timeout=2, tries=1)
+        if parts and parts[0] == "ACK":
+            break
+        if parts and parts[3:4] == ["rolledback"]:
+            say("")
+            raise ToolError("the new firmware failed (it kept restarting); the board restored "
+                            "the previous firmware. See: picolan logs")
+        if parts and parts[3:5] == ["committed", "not-on-trial"]:
+            break  # an earlier ACK was lost; verified below
+        if (parts and parts[4:5] != ["too-early"]) or time.time() > deadline:
+            say("")
+            raise ToolError("the board did not accept the confirmation (%s). It will restore "
+                            "the previous firmware." % (" ".join(parts) if parts else "no answer"))
+        out(".")
+        time.sleep(1)
+    n = discover(bus, 0.5).get(node["chip"])
+    if not n or n.get("state") != "committed" or n.get("crc") != image.crc_hex:
+        say("")
+        raise ToolError("could not verify the result (board reports state %s, crc %s). "
+                        "Check with: picolan nodes" % (n.get("state") if n else "?",
+                                                      n.get("crc") if n else "?"))
+    say(" ok")
+    say("Confirmed in %.1f s." % (time.time() - t0))
+
+
+def plan_push(nodes, images, target, force):
+    """Pair each image with the one board that receives it."""
+    if target:
+        if len(images) != 1:
+            raise ToolError("--node selects one board; give one image")
+        node = select_node(nodes, target, None)
+        im = images[0]
+        if node.get("product") != im.product and not force:
+            raise ToolError("board %s runs product '%s', the image is '%s'. Use --force-product "
+                            "to change the product of this board."
+                            % (node["chip"], node.get("product"), im.product))
+        return [(im, node)]
+    if force:
+        raise ToolError("--force-product changes the product of a board; name the board with "
+                        "--node <chip ID or IP>")
+    plan, problems = [], []
+    for im in images:
+        hits = [n for n in nodes.values() if n.get("product") == im.product]
+        if len(hits) == 1:
+            plan.append((im, hits[0]))
+        elif not hits:
+            problems.append("no board runs product '%s'" % im.product)
+        else:
+            problems.append("%d boards run product '%s': %s. Update them one at a time with "
+                            "--node." % (len(hits), im.product,
+                                         ", ".join("%s (%s)" % (n["chip"], n.get("ip"))
+                                                   for n in hits)))
+    if problems:
+        if nodes:
+            say("Boards on the network:")
+            print_table(nodes)
+        raise ToolError("nothing was installed:\n  " + "\n  ".join(problems))
+    for im, node in plan:
+        if node.get("conflict") == "1":
+            raise ToolError("board %s reports an IP conflict on %s. Fix the IP first. "
+                            "Nothing was installed." % (node["chip"], node["ip"]))
+    return plan
+
+
+def cmd_push(bus, a):
+    files = a.files or [build_project(a.env)]
+    images, manifests = load_images(files)
+    for m in manifests:
+        say("Bundle  %s %s (%d images, created %s)" % (m.get("name") or "-",
+                                                       m.get("release") or "-",
+                                                       len(m.get("images", [])),
+                                                       m.get("created", "?")))
+    plan = plan_push(discover(bus), images, a.node, a.force_product)
+    log = None if a.no_log else (a.log or os.environ.get("PICOLAN_LOG") or default_log_path())
+    release = ",".join("%s/%s" % (m.get("name") or "-", m.get("release") or "-")
+                       for m in manifests) or "-"
+    results = []
+    for i, (im, node) in enumerate(plan):
+        if len(plan) > 1:
+            say("")
+            say("[%d/%d] %s" % (i + 1, len(plan), im.product))
+        fields = [("chip", node["chip"]), ("ip", node.get("ip")), ("product", im.product),
+                  ("from", "%s/%s" % (node.get("build"), node.get("crc"))),
+                  ("to", "%s/%s" % (im.build, im.crc_hex)), ("release", release),
+                  ("source", im.source)]
+        if node.get("crc") == im.crc_hex and node.get("state") == "committed" and not a.reinstall:
+            say("%s %s already runs build %s; skipped (--reinstall to install again)"
+                % (node["chip"], im.product, im.build))
+            results.append((im, node, "skipped", ""))
+            write_log(log, [("result", "SKIPPED")] + fields)
+            continue
+        try:
+            push_one(bus, node, im, a.force_product, not a.no_confirm)
+        except ToolError as e:
+            results.append((im, node, "FAILED", str(e)))
+            write_log(log, [("result", "FAILED")] + fields + [("reason", str(e).split("\n")[0])])
+            break
+        results.append((im, node, "ok", ""))
+        write_log(log, [("result", "OK" if not a.no_confirm else "UNCONFIRMED")] + fields)
+    failed = [r for r in results if r[2] == "FAILED"]
+    if len(plan) > 1 or failed:
+        say("")
+        say("Result:")
+        done = {r[0].product for r in results}
+        for im, node, res, why in results:
+            say("  %-24s %-16s %-15s %s%s" % (im.product, node["chip"], node.get("ip"), res,
+                                             (": " + why.split("\n")[0]) if why else ""))
+        for im, node in plan:
+            if im.product not in done:
+                say("  %-24s %-16s %-15s not started" % (im.product, node["chip"],
+                                                         node.get("ip")))
+    if failed:
+        raise ToolError("update stopped at %s" % failed[0][0].product)
+    return 0
+
+
+# ---------------------------------------------------------------- other commands
+
+def cmd_nodes(bus, a):
+    nodes = discover(bus)
+    if not nodes:
+        say("No boards answered.")
+        return 1
+    print_table(nodes)
+    return 0
+
+
+def cmd_logs(bus, a):
+    node = select_node(discover(bus), a.node, a.product)
+    chip = node["chip"]
+    say("--- picolan logs %s %s (%s), Ctrl+C to quit ---" % (node.get("product"), chip,
+                                                            node.get("ip")))
+    boot, last, renew = None, None, 0.0
+    end = time.time() + a.seconds if a.seconds else float("inf")
+    pat = re.compile(r"LOG (\S+) ([0-9A-F]{4}) (\d+) ?(.*)", re.S)
+    try:
+        while time.time() < end:
+            if time.time() >= renew:
+                bus.send("MONITOR %s 10" % chip)
+                renew = time.time() + 3
+            for _, text in bus.recv(0.2):
+                m = pat.match(text)
+                if not m or m[1] != chip:
+                    continue
+                b, seq, line = m[2], int(m[3]), m[4]
+                if b != boot:
+                    if boot is not None:
+                        say("--- board restarted ---")
+                    boot, last = b, None
+                if last is not None:
+                    if seq <= last:
+                        continue
+                    if seq > last + 1:
+                        say("--- %d line(s) lost ---" % (seq - last - 1))
+                last = seq
+                say("%s %s" % (time.strftime("%H:%M:%S"), line))
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def cmd_blink(bus, a):
+    node = select_node(discover(bus), a.node, a.product)
+    secs = int(a.args[0]) if a.args else 10
+    parts = command(bus, node, "IDENTIFY %s %d" % (node["chip"], secs), "IDENTIFY")
+    if not parts:
+        raise ToolError("no answer from %s" % node["chip"])
+    if parts[0] != "ACK":
+        raise ToolError("board %s cannot blink: %s" % (node["chip"], refused(parts)))
+    say("Board %s (%s) blinks for %d s." % (node["chip"], node["ip"], secs))
+    return 0
+
+
+def cmd_wipe(bus, a):
+    node = select_node(discover(bus), a.node, a.product)
+    say("Erasing LittleFS and EEPROM of %s %s (%s) ..." % (node.get("product"), node["chip"],
+                                                          node["ip"]))
+    parts = command(bus, node, "WIPE %s" % node["chip"], "WIPE", timeout=60, tries=1)
+    if not parts:
+        raise ToolError("no answer from %s; check the result with: picolan logs" % node["chip"])
+    if parts[0] != "ACK":
+        raise ToolError("wipe failed: %s" % refused(parts))
+    say("Board %s: storage erased and verified. It restarts."
+        % node["chip"])
+    return 0
+
+
+def cmd_reboot(bus, a):
+    node = select_node(discover(bus), a.node, a.product)
+    parts = command(bus, node, "REBOOT %s" % node["chip"], "REBOOT")
+    if not parts or parts[0] != "ACK":
+        raise ToolError("board did not restart: %s" % refused(parts))
+    say("Board %s restarting." % node["chip"])
+    return 0
+
+
+def cmd_bundle(a):
+    images, manifests = load_images(a.files)
+    if manifests:
+        raise ToolError("give .bin files, not bundles")
+    data = make_bundle(images, a.name, a.release)
+    try:
+        with open(a.output, "wb") as f:
+            f.write(data)
+    except OSError as e:
+        raise ToolError("cannot write %s: %s" % (a.output, e))
+    say("%s: %d images, %d bytes" % (a.output, len(images), len(data)))
+    for im in images:
+        say("  %-24s build %-16s %7d bytes  crc %s" % (im.product, im.build, len(im.data),
+                                                      im.crc_hex))
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="picolan", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version="picolan " + __version__)
+    ap.add_argument("--node", "-n", help="board: chip ID (or unique prefix), IP or product name")
+    ap.add_argument("--product", help="without --node: use the only board of this product")
+    ap.add_argument("--iface", action="append", default=[],
+                    help="network interface name (Linux) or local IPv4 address to use "
+                         "(repeatable; default: all)")
+    ap.add_argument("--port", type=int, default=8208, help="picolan port (UDP)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("nodes", aliases=["list"], help="list the boards on the network")
+    p = sub.add_parser("push", help="update boards")
+    p.add_argument("files", nargs="*", help=".bin images or bundles (default: build this project)")
+    p.add_argument("-e", "--env", help="PlatformIO environment to build (without files)")
+    p.add_argument("--force-product", action="store_true",
+                   help="allow an image of another product (needs --node)")
+    p.add_argument("--reinstall", action="store_true",
+                   help="install also when the board already runs this image")
+    p.add_argument("--no-confirm", action="store_true",
+                   help="test only: do not confirm, so the board rolls back")
+    p.add_argument("--log", help="install log file (default: %s)" % default_log_path())
+    p.add_argument("--no-log", action="store_true", help="do not write the install log")
+    lg = sub.add_parser("logs", help="show the network log of a board")
+    lg.add_argument("--seconds", type=float, default=0)
+    for name in ("blink", "wipe", "reboot"):
+        sp = sub.add_parser(name)
+        sp.add_argument("args", nargs="*")
+    b = sub.add_parser("bundle", help="make a release bundle from .bin images")
+    b.add_argument("files", nargs="+")
+    b.add_argument("-o", "--output", required=True)
+    b.add_argument("--name", default="", help="system name, e.g. the product line")
+    b.add_argument("--release", default="", help="release version, e.g. v6.4.0")
+    m = sub.add_parser("mac", help="MAC address derived from a chip ID")
+    m.add_argument("chip")
+    a = ap.parse_args(argv)
+    try:
+        if a.cmd == "mac":
+            say(mac_from_chip(a.chip))
+            return 0
+        if a.cmd == "bundle":
+            return cmd_bundle(a)
+        ifaces = a.iface or [i for i in os.environ.get("PICOLAN_IFACE", "").split(",") if i]
+        bus = Bus(a.port, ifaces)
+        handlers = {"nodes": cmd_nodes, "list": cmd_nodes, "push": cmd_push, "logs": cmd_logs,
+                    "blink": cmd_blink, "wipe": cmd_wipe,
+                    "reboot": cmd_reboot}
+        return handlers[a.cmd](bus, a)
+    except ToolError as e:
+        say("picolan: %s" % e)
+        return 1
+    except BrokenPipeError:  # output piped into a command that exited (head, grep -m)
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())