uclog 4__tar.gz

uclog-4/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: uclog
+Version: 4
+Summary: ucLog for scripts: talk to devices through the ucLog hub and decode their logs
+Author: Unit Circle Inc.
+License: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: mdns
+Requires-Dist: zeroconf>=0.38; extra == "mdns"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# uclog: Python library for scripts
+
+Plan: [docs/plans/06-python-client.md](../docs/plans/06-python-client.md).
+
+A small library for test scripts and automation. It does four things:
+
+- finds a running ucLog hub, or starts one;
+- connects to it;
+- sends and receives on any port;
+- decodes logs with CBOR logdata.
+
+All device I/O goes through the native hub (`uclog-hub`), so the library is pure Python and
+behaves the same on every OS. It needs Python 3.9 or later and has no dependencies. The optional
+`uclog[mdns]` extra adds `zeroconf`, for finding hubs on other machines.
+
+```sh
+pip install uclog            # platform wheels bundle uclog-hub
+pip install "uclog[mdns]"    # also find remote hubs over mDNS
+```
+
+The `py3-none-any` wheel has no `uclog-hub`. It uses `$UCLOG_HUB`, or `uclog-hub` (or `uclog`) on
+`PATH`.
+
+## Quick start
+
+```python
+import uclog
+
+with uclog.connect(logdata="build/zephyr/zephyr.elf") as dev:
+    print(dev.device_info)                    # port-62 map: board, app_hash, ...
+    dev.send(61, "version s\r")               # str or bytes, to any port
+    print(dev.recv(61, timeout=1.0))          # next payload on port 61, or None
+    rsp = dev.command({"cmd": "get-info"})    # port 0: CBOR request, waits for rsp == cmd
+    for rec in dev.logs(duration=5.0):        # decoded log records for 5 s
+        print(rec)                            # 1.234:INFO:src/main.c:10:Hello World!
+```
+
+The examples in [examples/](examples/) replace the legacy scripts:
+
+| Example | |
+|---|---|
+| `capture_logs.py` | logs, filtered by level, source and text (replaces `uclog-cli.py`) |
+| `terminal.py` | a line-mode terminal, also piped (replaces `logcmd.py`; works on Windows too) |
+| `command.py` | a CBOR request on port 0 and its reply (replaces `StreamClient.txrx`) |
+| `decode_capture.py` | decode a raw capture of a device's bytes offline |
+| `pytest/` | a pytest fixture for hardware tests (`--uclog-device`), and tests that use it |
+
+`tests/test_examples.py` runs every example against the simulated device. The API reference is
+generated from the docstrings for the docs site (`website/build.py`).
+
+## Choosing a hub
+
+`uclog.connect(host=None, device=None, ...)` goes through these steps in order:
+
+1. **`host` given** (or `$UCLOG_HOST`): connect to it. Examples: `"192.168.1.20"`,
+   `"labpc.local:9001"`, `"tcp://[::1]:9000"`. The default port is 9000.
+2. **One running hub** on this machine (registry), or also on the network with
+   `discover_remote=True`: connect to it. With `device=` (a URI like `serial:/dev/ttyACM0` or a
+   serial number), only that device's hub counts.
+3. **Several hubs** match: `MultipleHubsError`. Its `.candidates` lists them; pass `host=`. The
+   library never guesses.
+4. **No hub**: it runs `uclog-hub list --json`. If exactly one device is found, or `device=` names
+   one, it starts a hub for it and connects. If no device matches it raises `NoHubError`; if
+   several match, `MultipleHubsError`.
+
+A hub the library started is **stopped when the connection closes**, at the end of the `with`
+block, or when the script exits. If the script is killed, the hub sees its stdin close and exits.
+Hubs that were already running are left alone. A started hub listens on `127.0.0.1` only and is
+not advertised over mDNS (`hub_args=["--bind", "0.0.0.0"]` changes that); local clients still
+find it in the registry. Scripts starting a hub for the same device at the same time take turns,
+so only one hub is started.
+
+`connect()` returns once **the device** has sent something (not just the hub's backlog replay),
+waiting up to `device_timeout` (10 s; a hub opens a BLE device in about 5 s). Otherwise it raises
+`DeviceNotRespondingError`.
+
+```python
+uclog.list_hubs()                   # [HubInfo(name, host, port, device, serial_number, busy, pid, ...)]
+uclog.list_hubs(discover_remote=True)
+uclog.list_devices()                # [DeviceInfo(kind, uri, name, serial, description)]
+hub = uclog.start_hub("serial:/dev/ttyACM0")   # keep a hub across several connections
+uclog.stop_hub(hub.pid)             # or uclog.stop_hub("localhost:9001"); only a registered hub
+```
+
+A hub serves **one client at a time**. While the GUI, the TUI or VS Code is connected,
+`connect()` raises `HubBusyError`. A remote hub may hold a new connection open, without data, while
+its operator approves it. `connect()` waits up to `approval_timeout` (60 s), then raises
+`ApprovalTimeoutError`.
+
+## Connection
+
+| Call | |
+|---|---|
+| `send(port, data)` | bytes, or str as UTF-8; at most 1443 bytes |
+| `send_frame(payload)` | a whole payload, frame header included |
+| `recv(port, timeout=None)` | next payload on `port` (bytes), or `None` after `timeout` |
+| `command(obj, timeout=2.0)` | CBOR map on port 0; returns the reply whose `rsp` equals `obj["cmd"]`, or `None`. Other port-0 frames stay queued for `recv(0)` |
+| `logs(timeout=None, duration=None)` | iterator of `LogRecord`s, ending after `timeout` seconds without one or `duration` seconds in all |
+| `frames(timeout=None, duration=None)` | every payload, raw |
+| `console(timeout=None)` | semihost stdout/stderr: `(fid, bytes)` |
+| `device_info` | the port-62 map; waits up to 2 s for it, or until `connect()`'s `device_timeout` ends if that is later |
+| `alive` | bytes arrived within the last 2 s |
+| `dropped` | entries dropped from full queues, by port, `"logs"`, `"frames"` or `"console"` |
+| `notes` | logdata choices and problems (also logged to the `uclog` logger) |
+| `load_logdata(path)` | use another logdata file from now on |
+| `close()` | sends what is still queued (up to 2 s), then closes; also stops a hub the library started |
+
+`LogRecord(ts, level, target, file, line, text, error)`:
+- `ts` is seconds since the connection opened.
+- `error` is set for error records: `no_logdata`, `unknown_format`, `missing_arg`, `extra_bytes`,
+  `framing_invalid`, and so on, with the same texts as the native tools.
+- `str(rec)` gives the legacy `ts:level:file:line:text` line.
+- Logs from the backlog are decoded with the logdata of the device info that preceded them, so
+  logs from before a reflash use the old image's logdata. An image with no logdata gives
+  `no_logdata` records.
+
+**Queues** are bounded by `max_queue` (10 000). When one is full, the oldest entry is dropped and
+counted in `dropped`.
+
+**Backlog:** on connect, the hub first replays what the device sent while no client was
+connected. `skip_backlog=True` drops that replay.
+
+**asyncio:** `uclog.aio.connect(...)` takes the same arguments. Its connection has the same
+calls, awaited, except that `device_info` becomes the method `await dev.device_info(timeout)`.
+`logs()` and `frames()` are async iterators.
+
+```python
+async with await uclog.aio.connect(device="serial:/dev/ttyACM0") as dev:
+    await dev.send(61, "help\r")
+    print(await dev.recv(61, timeout=1))
+```
+
+## Logdata
+
+`connect(logdata=...)` takes one file or a list: `.logdata`, or an ELF file with a
+`.logdata_cbor` section. Each device info (port 62) selects the logdata for its `app_hash`, in this
+order:
+
+1. **The given files.** A file named `<app_hash>.logdata` is used only for that hash.
+2. **The cache directory.** `cache_dir`, which defaults to the native tools' cache
+   (`$UCLOG_CACHE_DIR`, else `$XDG_CACHE_HOME/uclog`, else `~/.cache/uclog`), holding
+   `<app_hash>.logdata` files. The firmware builds copy theirs there.
+3. **fw.unitcircle.ca.** Used when `logdata_domain` (or `$UCLOG_LOGDATA_DOMAIN`) is set, with
+   `logdata_token` / `$UCLOG_LOGDATA_TOKEN`. The download is saved to the cache. A refused token
+   (401) is retried once without it, for accounts that allow reading without a token; the
+   resolver's `token_refused` is then set and `notes` says so.
+4. **The first given file**, with a warning in `notes`.
+
+`uclog.LogData.load(path).decode(addr, args)` decodes without a connection.
+
+## Port 63 (semihost)
+
+A connected script answers the device's syscalls. The hub answers the time calls itself.
+
+- **stdout and stderr** writes go to `console()`.
+- **stdin reads** call `stdin=` (a function taking the maximum byte count and returning bytes or
+  str), or get EOF.
+- **File operations** (OPEN, MKDIR) get `EACCES`, unless `files_dir=DIR` is given. Then they
+  work inside `DIR` only: absolute paths, `..` escapes, symlinks that leave it and names that are
+  not portable (protocol.md §5.5.5) fail with `EACCES`. Errors use newlib errno values.
+
+The connection's own thread answers syscalls, so a script that never reads from it still does not
+stall the device.
+
+## Migrating from the legacy package
+
+The legacy repository's `uclog` package uses the same import name. Uninstall it, or use a separate
+virtual environment.
+
+| Legacy | Now |
+|---|---|
+| `uclog.StreamClient(target, host, raw, stream=0, enc='utf8')` | `uclog.connect(host=..., device=...)` |
+| `sc.tx(obj)` with `enc='cbor'` | `dev.send(port, uclog.cbor.dumps(obj))`, or `dev.command(obj)` for request/reply |
+| `sc.tx(text)` with `enc='utf8'` | `dev.send(port, text)` |
+| `sc.rx(timeout)` | `dev.recv(port, timeout)`; `uclog.cbor.loads(...)` for CBOR |
+| `sc.txrx(obj)` | `dev.command(obj)` |
+| `enc='cbor,crc,cobs'` (legacy port-3 FW update) | `uclog fw-update` |
+| `--target /dev/tty...` (opens the port directly) | `device="serial:/dev/tty..."` (through a hub) |
+| `uclog-cli.py` | `examples/capture_logs.py`, or `uclog tui --plain` |
+| `logcmd.py` | `examples/terminal.py`, or `uclog term` |
+
+FW update from Python is out of scope for v1 (decision 30). Use `uclog fw-update`.
+
+## Development
+
+```sh
+cd python
+uv run --no-project --with pytest pytest          # or: pip install -e ".[test]" && pytest
+```
+
+The integration tests use `$UCLOG_HUB` or `native/target/{release,debug}/uclog-hub`, and the
+simulated `loopback:` device. Without either executable they are skipped.
+
+To build a **platform wheel** that bundles the hub:
+
+```sh
+UCLOG_HUB_BINARY=../native/target/release/uclog-hub UCLOG_WHEEL_PLAT=macosx_11_0_arm64 python -m build --wheel
+```

uclog-4/README.md

@@ -0,0 +1,198 @@
+# uclog: Python library for scripts
+
+Plan: [docs/plans/06-python-client.md](../docs/plans/06-python-client.md).
+
+A small library for test scripts and automation. It does four things:
+
+- finds a running ucLog hub, or starts one;
+- connects to it;
+- sends and receives on any port;
+- decodes logs with CBOR logdata.
+
+All device I/O goes through the native hub (`uclog-hub`), so the library is pure Python and
+behaves the same on every OS. It needs Python 3.9 or later and has no dependencies. The optional
+`uclog[mdns]` extra adds `zeroconf`, for finding hubs on other machines.
+
+```sh
+pip install uclog            # platform wheels bundle uclog-hub
+pip install "uclog[mdns]"    # also find remote hubs over mDNS
+```
+
+The `py3-none-any` wheel has no `uclog-hub`. It uses `$UCLOG_HUB`, or `uclog-hub` (or `uclog`) on
+`PATH`.
+
+## Quick start
+
+```python
+import uclog
+
+with uclog.connect(logdata="build/zephyr/zephyr.elf") as dev:
+    print(dev.device_info)                    # port-62 map: board, app_hash, ...
+    dev.send(61, "version s\r")               # str or bytes, to any port
+    print(dev.recv(61, timeout=1.0))          # next payload on port 61, or None
+    rsp = dev.command({"cmd": "get-info"})    # port 0: CBOR request, waits for rsp == cmd
+    for rec in dev.logs(duration=5.0):        # decoded log records for 5 s
+        print(rec)                            # 1.234:INFO:src/main.c:10:Hello World!
+```
+
+The examples in [examples/](examples/) replace the legacy scripts:
+
+| Example | |
+|---|---|
+| `capture_logs.py` | logs, filtered by level, source and text (replaces `uclog-cli.py`) |
+| `terminal.py` | a line-mode terminal, also piped (replaces `logcmd.py`; works on Windows too) |
+| `command.py` | a CBOR request on port 0 and its reply (replaces `StreamClient.txrx`) |
+| `decode_capture.py` | decode a raw capture of a device's bytes offline |
+| `pytest/` | a pytest fixture for hardware tests (`--uclog-device`), and tests that use it |
+
+`tests/test_examples.py` runs every example against the simulated device. The API reference is
+generated from the docstrings for the docs site (`website/build.py`).
+
+## Choosing a hub
+
+`uclog.connect(host=None, device=None, ...)` goes through these steps in order:
+
+1. **`host` given** (or `$UCLOG_HOST`): connect to it. Examples: `"192.168.1.20"`,
+   `"labpc.local:9001"`, `"tcp://[::1]:9000"`. The default port is 9000.
+2. **One running hub** on this machine (registry), or also on the network with
+   `discover_remote=True`: connect to it. With `device=` (a URI like `serial:/dev/ttyACM0` or a
+   serial number), only that device's hub counts.
+3. **Several hubs** match: `MultipleHubsError`. Its `.candidates` lists them; pass `host=`. The
+   library never guesses.
+4. **No hub**: it runs `uclog-hub list --json`. If exactly one device is found, or `device=` names
+   one, it starts a hub for it and connects. If no device matches it raises `NoHubError`; if
+   several match, `MultipleHubsError`.
+
+A hub the library started is **stopped when the connection closes**, at the end of the `with`
+block, or when the script exits. If the script is killed, the hub sees its stdin close and exits.
+Hubs that were already running are left alone. A started hub listens on `127.0.0.1` only and is
+not advertised over mDNS (`hub_args=["--bind", "0.0.0.0"]` changes that); local clients still
+find it in the registry. Scripts starting a hub for the same device at the same time take turns,
+so only one hub is started.
+
+`connect()` returns once **the device** has sent something (not just the hub's backlog replay),
+waiting up to `device_timeout` (10 s; a hub opens a BLE device in about 5 s). Otherwise it raises
+`DeviceNotRespondingError`.
+
+```python
+uclog.list_hubs()                   # [HubInfo(name, host, port, device, serial_number, busy, pid, ...)]
+uclog.list_hubs(discover_remote=True)
+uclog.list_devices()                # [DeviceInfo(kind, uri, name, serial, description)]
+hub = uclog.start_hub("serial:/dev/ttyACM0")   # keep a hub across several connections
+uclog.stop_hub(hub.pid)             # or uclog.stop_hub("localhost:9001"); only a registered hub
+```
+
+A hub serves **one client at a time**. While the GUI, the TUI or VS Code is connected,
+`connect()` raises `HubBusyError`. A remote hub may hold a new connection open, without data, while
+its operator approves it. `connect()` waits up to `approval_timeout` (60 s), then raises
+`ApprovalTimeoutError`.
+
+## Connection
+
+| Call | |
+|---|---|
+| `send(port, data)` | bytes, or str as UTF-8; at most 1443 bytes |
+| `send_frame(payload)` | a whole payload, frame header included |
+| `recv(port, timeout=None)` | next payload on `port` (bytes), or `None` after `timeout` |
+| `command(obj, timeout=2.0)` | CBOR map on port 0; returns the reply whose `rsp` equals `obj["cmd"]`, or `None`. Other port-0 frames stay queued for `recv(0)` |
+| `logs(timeout=None, duration=None)` | iterator of `LogRecord`s, ending after `timeout` seconds without one or `duration` seconds in all |
+| `frames(timeout=None, duration=None)` | every payload, raw |
+| `console(timeout=None)` | semihost stdout/stderr: `(fid, bytes)` |
+| `device_info` | the port-62 map; waits up to 2 s for it, or until `connect()`'s `device_timeout` ends if that is later |
+| `alive` | bytes arrived within the last 2 s |
+| `dropped` | entries dropped from full queues, by port, `"logs"`, `"frames"` or `"console"` |
+| `notes` | logdata choices and problems (also logged to the `uclog` logger) |
+| `load_logdata(path)` | use another logdata file from now on |
+| `close()` | sends what is still queued (up to 2 s), then closes; also stops a hub the library started |
+
+`LogRecord(ts, level, target, file, line, text, error)`:
+- `ts` is seconds since the connection opened.
+- `error` is set for error records: `no_logdata`, `unknown_format`, `missing_arg`, `extra_bytes`,
+  `framing_invalid`, and so on, with the same texts as the native tools.
+- `str(rec)` gives the legacy `ts:level:file:line:text` line.
+- Logs from the backlog are decoded with the logdata of the device info that preceded them, so
+  logs from before a reflash use the old image's logdata. An image with no logdata gives
+  `no_logdata` records.
+
+**Queues** are bounded by `max_queue` (10 000). When one is full, the oldest entry is dropped and
+counted in `dropped`.
+
+**Backlog:** on connect, the hub first replays what the device sent while no client was
+connected. `skip_backlog=True` drops that replay.
+
+**asyncio:** `uclog.aio.connect(...)` takes the same arguments. Its connection has the same
+calls, awaited, except that `device_info` becomes the method `await dev.device_info(timeout)`.
+`logs()` and `frames()` are async iterators.
+
+```python
+async with await uclog.aio.connect(device="serial:/dev/ttyACM0") as dev:
+    await dev.send(61, "help\r")
+    print(await dev.recv(61, timeout=1))
+```
+
+## Logdata
+
+`connect(logdata=...)` takes one file or a list: `.logdata`, or an ELF file with a
+`.logdata_cbor` section. Each device info (port 62) selects the logdata for its `app_hash`, in this
+order:
+
+1. **The given files.** A file named `<app_hash>.logdata` is used only for that hash.
+2. **The cache directory.** `cache_dir`, which defaults to the native tools' cache
+   (`$UCLOG_CACHE_DIR`, else `$XDG_CACHE_HOME/uclog`, else `~/.cache/uclog`), holding
+   `<app_hash>.logdata` files. The firmware builds copy theirs there.
+3. **fw.unitcircle.ca.** Used when `logdata_domain` (or `$UCLOG_LOGDATA_DOMAIN`) is set, with
+   `logdata_token` / `$UCLOG_LOGDATA_TOKEN`. The download is saved to the cache. A refused token
+   (401) is retried once without it, for accounts that allow reading without a token; the
+   resolver's `token_refused` is then set and `notes` says so.
+4. **The first given file**, with a warning in `notes`.
+
+`uclog.LogData.load(path).decode(addr, args)` decodes without a connection.
+
+## Port 63 (semihost)
+
+A connected script answers the device's syscalls. The hub answers the time calls itself.
+
+- **stdout and stderr** writes go to `console()`.
+- **stdin reads** call `stdin=` (a function taking the maximum byte count and returning bytes or
+  str), or get EOF.
+- **File operations** (OPEN, MKDIR) get `EACCES`, unless `files_dir=DIR` is given. Then they
+  work inside `DIR` only: absolute paths, `..` escapes, symlinks that leave it and names that are
+  not portable (protocol.md §5.5.5) fail with `EACCES`. Errors use newlib errno values.
+
+The connection's own thread answers syscalls, so a script that never reads from it still does not
+stall the device.
+
+## Migrating from the legacy package
+
+The legacy repository's `uclog` package uses the same import name. Uninstall it, or use a separate
+virtual environment.
+
+| Legacy | Now |
+|---|---|
+| `uclog.StreamClient(target, host, raw, stream=0, enc='utf8')` | `uclog.connect(host=..., device=...)` |
+| `sc.tx(obj)` with `enc='cbor'` | `dev.send(port, uclog.cbor.dumps(obj))`, or `dev.command(obj)` for request/reply |
+| `sc.tx(text)` with `enc='utf8'` | `dev.send(port, text)` |
+| `sc.rx(timeout)` | `dev.recv(port, timeout)`; `uclog.cbor.loads(...)` for CBOR |
+| `sc.txrx(obj)` | `dev.command(obj)` |
+| `enc='cbor,crc,cobs'` (legacy port-3 FW update) | `uclog fw-update` |
+| `--target /dev/tty...` (opens the port directly) | `device="serial:/dev/tty..."` (through a hub) |
+| `uclog-cli.py` | `examples/capture_logs.py`, or `uclog tui --plain` |
+| `logcmd.py` | `examples/terminal.py`, or `uclog term` |
+
+FW update from Python is out of scope for v1 (decision 30). Use `uclog fw-update`.
+
+## Development
+
+```sh
+cd python
+uv run --no-project --with pytest pytest          # or: pip install -e ".[test]" && pytest
+```
+
+The integration tests use `$UCLOG_HUB` or `native/target/{release,debug}/uclog-hub`, and the
+simulated `loopback:` device. Without either executable they are skipped.
+
+To build a **platform wheel** that bundles the hub:
+
+```sh
+UCLOG_HUB_BINARY=../native/target/release/uclog-hub UCLOG_WHEEL_PLAT=macosx_11_0_arm64 python -m build --wheel
+```

uclog-4/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uclog"
+version = "4"
+description = "ucLog for scripts: talk to devices through the ucLog hub and decode their logs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Unit Circle Inc." }]
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Embedded Systems",
+]
+
+[project.optional-dependencies]
+mdns = ["zeroconf>=0.38"]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+uclog = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

uclog-4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uclog-4/setup.py

@@ -0,0 +1,55 @@
+# © 2026 Unit Circle Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Platform wheels (plan 06 §2): with UCLOG_HUB_BINARY (the uclog-hub executable) and
+UCLOG_WHEEL_PLAT (a wheel platform tag such as manylinux_2_28_x86_64, macosx_11_0_arm64 or
+win_amd64), the wheel bundles uclog-hub as uclog/bin/uclog-hub and is tagged py3-none-<plat>.
+Without them it is the pure-Python py3-none-any wheel.
+"""
+
+import os
+import shutil
+
+from setuptools import Distribution, setup
+from setuptools.command.build_py import build_py
+
+try:
+  from setuptools.command.bdist_wheel import bdist_wheel
+except ImportError:  # setuptools < 70.1
+  from wheel.bdist_wheel import bdist_wheel
+
+HUB = os.environ.get('UCLOG_HUB_BINARY')
+PLAT = os.environ.get('UCLOG_WHEEL_PLAT')
+if HUB and not PLAT:
+  raise SystemExit('UCLOG_HUB_BINARY needs UCLOG_WHEEL_PLAT (the wheel platform tag)')
+
+
+class BuildPy(build_py):
+  def run(self):
+    super().run()
+    if HUB:
+      d = os.path.join(self.build_lib, 'uclog', 'bin')
+      os.makedirs(d, exist_ok=True)
+      name = 'uclog-hub.exe' if HUB.lower().endswith('.exe') else 'uclog-hub'
+      shutil.copy2(HUB, os.path.join(d, name))
+      os.chmod(os.path.join(d, name), 0o755)
+
+
+class BdistWheel(bdist_wheel):
+  def finalize_options(self):
+    super().finalize_options()
+    if HUB:
+      self.root_is_pure = False
+
+  def get_tag(self):
+    if HUB:
+      return 'py3', 'none', PLAT
+    return super().get_tag()
+
+
+class BinaryDistribution(Distribution):
+  def has_ext_modules(self):
+    return bool(HUB)  # platlib, at the wheel root
+
+
+setup(cmdclass={'build_py': BuildPy, 'bdist_wheel': BdistWheel}, distclass=BinaryDistribution)

uclog-4/src/uclog/__init__.py

@@ -0,0 +1,35 @@
+# © 2026 Unit Circle Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""ucLog for scripts: connect to a device through the ucLog hub, send and receive on any port,
+and decode logs.
+
+    import uclog
+
+    with uclog.connect(logdata="build/zephyr/zephyr.elf") as dev:
+        print(dev.device_info)
+        dev.send(61, b"version s\\r")
+        print(dev.recv(61, timeout=1.0))
+        for rec in dev.logs(timeout=5.0):
+            print(rec)
+
+All device I/O goes through the native hub (`uclog-hub`); a hub is started when none is running
+and stopped when the script exits.
+"""
+
+from . import aio, cbor, proto
+from .connection import Connection, connect
+from .errors import (ApprovalTimeoutError, ConnectionClosedError, DeviceNotRespondingError,
+                     HubBusyError, HubStartError, MultipleHubsError, NoHubError, UclogError)
+from .hub import DeviceInfo, HubInfo, list_devices, list_hubs, start_hub, stop_hub
+from .logdata import DecodeError, LogData, LogDataError, LogRecord
+from .resolver import Resolver
+
+__version__ = '4'
+
+__all__ = [
+  'connect', 'Connection', 'list_hubs', 'list_devices', 'start_hub', 'stop_hub', 'HubInfo',
+  'DeviceInfo', 'LogData', 'LogRecord', 'Resolver', 'DecodeError', 'LogDataError', 'UclogError',
+  'NoHubError', 'MultipleHubsError', 'HubBusyError', 'ApprovalTimeoutError',
+  'DeviceNotRespondingError', 'HubStartError', 'ConnectionClosedError', 'aio', 'cbor', 'proto',
+]

uclog-4/src/uclog/aio.py

@@ -0,0 +1,102 @@
+# © 2026 Unit Circle Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""asyncio API: the same calls as the sync one, awaited.
+
+    async with await uclog.aio.connect(logdata="build/zephyr/zephyr.elf") as dev:
+        await dev.send(61, b"version s\\r")
+        print(await dev.recv(61, timeout=1.0))
+        async for rec in dev.logs(timeout=5.0):
+            print(rec)
+
+The connection's I/O runs on its own threads (see `uclog.Connection`); waits run in the
+default executor so the event loop is never blocked.
+"""
+
+import asyncio
+import functools
+from typing import AsyncIterator, Optional
+
+from . import connection
+from .logdata import LogRecord
+
+__all__ = ['connect', 'Connection']
+
+
+async def _run(fn, *args, **kw):
+  loop = asyncio.get_running_loop()
+  return await loop.run_in_executor(None, functools.partial(fn, *args, **kw))
+
+
+class Connection:
+  """Async wrapper of `uclog.Connection`. `sync` is the wrapped connection."""
+
+  def __init__(self, sync: connection.Connection):
+    self.sync = sync
+
+  async def __aenter__(self):
+    return self
+
+  async def __aexit__(self, *exc):
+    await self.close()
+    return False
+
+  @property
+  def alive(self) -> bool:
+    return self.sync.alive
+
+  @property
+  def closed(self) -> bool:
+    return self.sync.closed
+
+  @property
+  def dropped(self):
+    return self.sync.dropped
+
+  @property
+  def notes(self):
+    return self.sync.notes
+
+  async def device_info(self, timeout: Optional[float] = None) -> Optional[dict]:
+    """The port-62 map. Without `timeout`, waits as long as the sync `device_info` property."""
+    return await _run(self.sync.wait_device_info,
+                      self.sync._info_timeout() if timeout is None else timeout)
+
+  async def send(self, port: int, data) -> None:
+    self.sync.send(port, data)
+
+  async def send_frame(self, payload: bytes) -> None:
+    self.sync.send_frame(payload)
+
+  async def recv(self, port: int, timeout: Optional[float] = None) -> Optional[bytes]:
+    return await _run(self.sync.recv, port, timeout)
+
+  async def console(self, timeout: Optional[float] = None):
+    return await _run(self.sync.console, timeout)
+
+  async def command(self, obj: dict, timeout: float = 2.0):
+    return await _run(self.sync.command, obj, timeout)
+
+  async def logs(self, timeout: Optional[float] = None, duration: Optional[float] = None) -> AsyncIterator[LogRecord]:
+    it = self.sync.logs(timeout, duration)
+    while True:
+      r = await _run(next, it, None)
+      if r is None:
+        return
+      yield r
+
+  async def frames(self, timeout: Optional[float] = None, duration: Optional[float] = None) -> AsyncIterator[bytes]:
+    it = self.sync.frames(timeout, duration)
+    while True:
+      r = await _run(next, it, None)
+      if r is None:
+        return
+      yield r
+
+  async def close(self) -> None:
+    await _run(self.sync.close)
+
+
+async def connect(*args, **kw) -> Connection:
+  """Same arguments as `uclog.connect()`."""
+  return Connection(await _run(connection.connect, *args, **kw))