u2xbar 0.1.0__tar.gz

u2xbar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mete Balci
+
+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.

u2xbar-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: u2xbar
+Version: 0.1.0
+Summary: Control tool and library for the u2xbar USB crossbar
+Author: Mete Balci
+License-Expression: MIT
+Project-URL: Repository, https://github.com/metebalci/u2xbar-sw
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Dynamic: license-file
+
+# u2xbar
+
+Control tool and Python library for u2xbar, a USB 2.0 crossbar that connects
+USB devices to computers under program control. The tool speaks the unit's
+control protocol (`docs/protocol.md` in the u2xbar-sw repository) on its
+control port, a USB CDC ACM serial port.
+
+## Terms
+
+- A host port is where a computer connects.
+- A device port is where a peripheral connects.
+- A hub port is a downstream port of one of the unit's internal hubs. Hub
+  port p leads to device port p.
+- A connection is a device port assigned to a host port.
+- The control port is the unit's own USB port for the control protocol.
+
+## Install
+
+```
+pip install u2xbar
+```
+
+It needs Python 3.10 or later and pyserial. On Linux, the user needs access to
+the control port (usually the group `dialout`).
+
+## Finding a unit
+
+The tool looks for a serial port with USB ID 16C0:27DD whose serial number
+starts with `u2xbar.metebalci.com:`. The part after the colon is the unit's
+unique ID. With several units, `--serial <unique ID>` chooses one. `--port
+<path>` uses that port and skips the search; it also works on the firmware's
+debug console.
+
+## Command line
+
+The commands follow the protocol:
+
+```
+u2xbar version
+u2xbar list
+u2xbar connect 3 2            # device port 3 to host port 2
+u2xbar disconnect 3           # or: disconnect all
+u2xbar dev 3 vbus off         # dev <d> vbus|data on|off, dev <d> host <h>|none
+u2xbar host 1 detach          # host <h> vbus|data on|off, attach, detach
+u2xbar hub 1 boost 0,2,2,2,2  # or: hub <h> boost <p>|up|all <0-3>, reset, regs
+u2xbar param discharge_ms 30
+u2xbar events on
+u2xbar reset
+u2xbar dfu                    # sends the command only; see "Firmware update"
+```
+
+The tool adds:
+
+- `status [--watch] [--interval S] [--count N]` reads the whole state.
+- `measure [--interval S] [--count N] [--csv]` reads the sensors; the CSV has
+  a time column in UTC.
+- `raw <line>` sends one protocol line and prints the reply.
+- `shell` sends the lines you type and prints replies and events.
+- `run <script>` runs a file of protocol lines (or `-` for stdin). `#` starts
+  a comment, and `sleep <seconds>` waits on the computer. The whole script is
+  checked before the first line is sent. The run stops at the first `err`
+  unless `--keep-going` is given.
+- `topo` (Linux) shows where each host port's hub and the device on each
+  device port sit in this computer's USB tree: bus path, VID:PID, speed and
+  product. It finds the hubs by their serial number `<unique ID>-H<h>`.
+
+`--json` prints records as JSON, one document per line. Events go to stderr,
+except in `shell` and `run`.
+
+Exit codes: 0 ok, 1 the unit answered `err` or a test failed, 2 usage error,
+3 no unit, an I/O error (the port, a timeout, or a reply that breaks the
+protocol), or a test that cannot start.
+
+## Firmware update
+
+```
+u2xbar dfu --image u2xbar.bin [--dfu-util PATH] [--wait S]
+```
+
+The tool reads the unit's `version`, sends `dfu`, and waits for the STM32
+system bootloader (USB 0483:DF11) to appear in sysfs (Linux). It then runs
+
+```
+dfu-util -d 0483:df11 -p <bus path> -a 0 -s 0x08000000:leave -D u2xbar.bin
+```
+
+with the bus path of the bootloader that appeared, so another board in DFU
+mode is left alone. When dfu-util is done, the tool waits for the unit to come
+back on its control port (found by its unique ID, or at `--port`) and prints
+its `version`. dfu-util is a separate program; the tool checks that it exists
+before it sends `dfu`. `--wait` (10 s) bounds each of the two waits.
+
+## Acceptance tests
+
+The tests check a unit on this computer (Linux). Each host port to be tested
+must be connected to this computer, so that `topo` finds its hub.
+
+```
+u2xbar test enum [--hosts H,...] [--devices D,...] [--timeout S]
+                 [--allow-full-speed D,...] [--no-kernel-log]
+u2xbar test moves --count N --seed S [--hosts H,...] [--devices D,...] [--timeout S]
+u2xbar test read --device /dev/sdX --size GB [--baseline MB/s] [--margin PERCENT] [--force]
+```
+
+`test enum` and `test moves` start with a first pass: every selected device
+port is connected to the first selected host port, and the device that
+appears on each hub port is recorded. A device is known by its VID:PID and
+serial number, or, without a serial number, by its VID:PID and hub port. A
+device port whose device does not enumerate (`ufp=1` and no USB device) is
+reported.
+
+- `test enum` connects each device to each selected host port, one at a
+  time. Each step passes if the device appears on that host port's hub at its
+  hub port within `--timeout` (5 s), at 480M (or 12M on the device ports
+  named in `--allow-full-speed`), on no other hub, is gone after the
+  disconnect, and the kernel log has no new USB error (priority err or worse
+  from `usb`, `hub` or a host controller driver). The kernel log is read from
+  `/dev/kmsg` or, without the right to read it, from `journalctl -k`;
+  `--no-kernel-log` skips the check. The tool prints a table and the
+  failures.
+- `test moves` makes N random moves (`connect d h` to another host port) of
+  the device ports that have devices. After each move the same device must
+  appear on the new host port within `--timeout` and on no other host port.
+  The moves depend only on the seed and the ports, so a run can be repeated.
+  The tool prints each move, a summary (moves, failures, retries, the slowest
+  arrival) and every failure. A failed step or move does not stop either
+  test; the exit code is 1 at the end.
+- `test read` reads the first `--size` GB (10^9 bytes) of a block device in
+  4 MiB reads, with `O_DIRECT` where the file system allows it and otherwise
+  with the page cache dropped through `posix_fadvise`, and prints the rate in
+  MB/s (10^6 bytes per second). With `--baseline`, the rate measured through
+  a direct cable, it passes if it is at most `--margin` (3 %) slower. It only
+  reads, and it refuses a device that is mounted (or one of its partitions)
+  unless `--force` is given. It needs no unit.
+
+A full-speed device that comes up as low speed or not at all gets one retry
+(disconnect and connect again), which is counted and reported: the USB2517
+can detect a full-speed device as low speed when the port reset comes early
+in a frame (errata DS80000628A, Module 4). In `test enum` this holds for the
+device ports in `--allow-full-speed`.
+
+`--timeout` of a test is the time a device may take to appear or go; the
+time per protocol command is set with `--timeout` before the word `test`.
+`--poll` (0.05 s) is the time between scans of the USB tree.
+
+## Library
+
+```python
+from u2xbar import Unit
+
+with Unit() as unit:              # or Unit(serial="..."), Unit(port="/dev/ttyACM0")
+    print(unit.version())
+    unit.connect(3, 2)
+    for port in unit.list():
+        print(port.port, port.host, port.vbus, port.data)
+    print(unit.measure().i5_ma)
+```
+
+Each protocol command has a method, and `command(line)` sends any line.
+Results are dataclasses; a value the unit gives as `-` is `None`. An `err`
+reply raises `UnitError`, which carries the code. Events go to the
+`on_event` callback, or wait for `poll_events()`.
+
+## Tests
+
+```
+uv venv <venv>
+VIRTUAL_ENV=<venv> uv pip install -e . --group test
+<venv>/bin/python -m pytest
+```
+
+The tests run the tool against a fake unit on a pseudo-terminal and need no
+hardware. For the acceptance tests, a fake world ties the fake unit's
+connection commands to a fake sysfs tree, with devices that are slow, come up
+as low speed, appear on the wrong hub, stay behind, or never appear; a fake
+kernel log, a file as the block device, and a fake dfu-util complete it. One
+test reads this computer's kernel log and sysfs; it runs only with
+`U2XBAR_REAL_SYSTEM=1`.
+
+### Integration tests
+
+The integration tests (`tests/test_sim_integration.py`) run the tool against
+the firmware simulator `u2xbar-sim` (`sim/` in the u2xbar-sw repository): the
+firmware's core and protocol on the board model of its PC tests, served on a
+pseudo-terminal in real time. They run only when `U2XBAR_SIM` names the
+simulator binary:
+
+```
+cmake -S ../sim -B <build> -G Ninja
+cmake --build <build>
+U2XBAR_SIM=<build>/u2xbar-sim <venv>/bin/python -m pytest tests/test_sim_integration.py
+```
+
+Each test starts its own simulator, with its pty file in the test's
+temporary directory, and stops it at the end, also when the test fails. A
+test drives the simulated unit through the command line (`python -m u2xbar
+--port <pty>`, one process per command) or through `Unit`; most tests run
+both ways. The simulator's `state` query checks the simulated hardware: for
+example, that a connected device port's switch selects the hub of its host
+port and that its VBUS is on, or that the discharge FET comes on only after
+VBUS went off. Injections change the simulated world: a device attached, a
+fault that lasts past `fault_off_ms`, a computer that removes VBUS, the 5 V
+rail, a chip that does not answer. The tests cover every command, the
+parameters and their bounds, the error codes `syntax`, `range`, `state` and
+`hw` (the simulator cannot make an I2C transfer time out), events, `run`,
+`raw`, `shell`, `measure --csv`, `--json` and the exit codes. A hardware-rule
+violation of the board model fails the test.
+
+`scripts/check.sh` in the repository builds the simulator and runs these
+tests with the other checks.
+
+## How it was written
+
+The code and documentation are written with
+[Claude Code](https://claude.com/claude-code), using Anthropic's Claude Opus
+5.5 model.

u2xbar-0.1.0/README.md

@@ -0,0 +1,216 @@
+# u2xbar
+
+Control tool and Python library for u2xbar, a USB 2.0 crossbar that connects
+USB devices to computers under program control. The tool speaks the unit's
+control protocol (`docs/protocol.md` in the u2xbar-sw repository) on its
+control port, a USB CDC ACM serial port.
+
+## Terms
+
+- A host port is where a computer connects.
+- A device port is where a peripheral connects.
+- A hub port is a downstream port of one of the unit's internal hubs. Hub
+  port p leads to device port p.
+- A connection is a device port assigned to a host port.
+- The control port is the unit's own USB port for the control protocol.
+
+## Install
+
+```
+pip install u2xbar
+```
+
+It needs Python 3.10 or later and pyserial. On Linux, the user needs access to
+the control port (usually the group `dialout`).
+
+## Finding a unit
+
+The tool looks for a serial port with USB ID 16C0:27DD whose serial number
+starts with `u2xbar.metebalci.com:`. The part after the colon is the unit's
+unique ID. With several units, `--serial <unique ID>` chooses one. `--port
+<path>` uses that port and skips the search; it also works on the firmware's
+debug console.
+
+## Command line
+
+The commands follow the protocol:
+
+```
+u2xbar version
+u2xbar list
+u2xbar connect 3 2            # device port 3 to host port 2
+u2xbar disconnect 3           # or: disconnect all
+u2xbar dev 3 vbus off         # dev <d> vbus|data on|off, dev <d> host <h>|none
+u2xbar host 1 detach          # host <h> vbus|data on|off, attach, detach
+u2xbar hub 1 boost 0,2,2,2,2  # or: hub <h> boost <p>|up|all <0-3>, reset, regs
+u2xbar param discharge_ms 30
+u2xbar events on
+u2xbar reset
+u2xbar dfu                    # sends the command only; see "Firmware update"
+```
+
+The tool adds:
+
+- `status [--watch] [--interval S] [--count N]` reads the whole state.
+- `measure [--interval S] [--count N] [--csv]` reads the sensors; the CSV has
+  a time column in UTC.
+- `raw <line>` sends one protocol line and prints the reply.
+- `shell` sends the lines you type and prints replies and events.
+- `run <script>` runs a file of protocol lines (or `-` for stdin). `#` starts
+  a comment, and `sleep <seconds>` waits on the computer. The whole script is
+  checked before the first line is sent. The run stops at the first `err`
+  unless `--keep-going` is given.
+- `topo` (Linux) shows where each host port's hub and the device on each
+  device port sit in this computer's USB tree: bus path, VID:PID, speed and
+  product. It finds the hubs by their serial number `<unique ID>-H<h>`.
+
+`--json` prints records as JSON, one document per line. Events go to stderr,
+except in `shell` and `run`.
+
+Exit codes: 0 ok, 1 the unit answered `err` or a test failed, 2 usage error,
+3 no unit, an I/O error (the port, a timeout, or a reply that breaks the
+protocol), or a test that cannot start.
+
+## Firmware update
+
+```
+u2xbar dfu --image u2xbar.bin [--dfu-util PATH] [--wait S]
+```
+
+The tool reads the unit's `version`, sends `dfu`, and waits for the STM32
+system bootloader (USB 0483:DF11) to appear in sysfs (Linux). It then runs
+
+```
+dfu-util -d 0483:df11 -p <bus path> -a 0 -s 0x08000000:leave -D u2xbar.bin
+```
+
+with the bus path of the bootloader that appeared, so another board in DFU
+mode is left alone. When dfu-util is done, the tool waits for the unit to come
+back on its control port (found by its unique ID, or at `--port`) and prints
+its `version`. dfu-util is a separate program; the tool checks that it exists
+before it sends `dfu`. `--wait` (10 s) bounds each of the two waits.
+
+## Acceptance tests
+
+The tests check a unit on this computer (Linux). Each host port to be tested
+must be connected to this computer, so that `topo` finds its hub.
+
+```
+u2xbar test enum [--hosts H,...] [--devices D,...] [--timeout S]
+                 [--allow-full-speed D,...] [--no-kernel-log]
+u2xbar test moves --count N --seed S [--hosts H,...] [--devices D,...] [--timeout S]
+u2xbar test read --device /dev/sdX --size GB [--baseline MB/s] [--margin PERCENT] [--force]
+```
+
+`test enum` and `test moves` start with a first pass: every selected device
+port is connected to the first selected host port, and the device that
+appears on each hub port is recorded. A device is known by its VID:PID and
+serial number, or, without a serial number, by its VID:PID and hub port. A
+device port whose device does not enumerate (`ufp=1` and no USB device) is
+reported.
+
+- `test enum` connects each device to each selected host port, one at a
+  time. Each step passes if the device appears on that host port's hub at its
+  hub port within `--timeout` (5 s), at 480M (or 12M on the device ports
+  named in `--allow-full-speed`), on no other hub, is gone after the
+  disconnect, and the kernel log has no new USB error (priority err or worse
+  from `usb`, `hub` or a host controller driver). The kernel log is read from
+  `/dev/kmsg` or, without the right to read it, from `journalctl -k`;
+  `--no-kernel-log` skips the check. The tool prints a table and the
+  failures.
+- `test moves` makes N random moves (`connect d h` to another host port) of
+  the device ports that have devices. After each move the same device must
+  appear on the new host port within `--timeout` and on no other host port.
+  The moves depend only on the seed and the ports, so a run can be repeated.
+  The tool prints each move, a summary (moves, failures, retries, the slowest
+  arrival) and every failure. A failed step or move does not stop either
+  test; the exit code is 1 at the end.
+- `test read` reads the first `--size` GB (10^9 bytes) of a block device in
+  4 MiB reads, with `O_DIRECT` where the file system allows it and otherwise
+  with the page cache dropped through `posix_fadvise`, and prints the rate in
+  MB/s (10^6 bytes per second). With `--baseline`, the rate measured through
+  a direct cable, it passes if it is at most `--margin` (3 %) slower. It only
+  reads, and it refuses a device that is mounted (or one of its partitions)
+  unless `--force` is given. It needs no unit.
+
+A full-speed device that comes up as low speed or not at all gets one retry
+(disconnect and connect again), which is counted and reported: the USB2517
+can detect a full-speed device as low speed when the port reset comes early
+in a frame (errata DS80000628A, Module 4). In `test enum` this holds for the
+device ports in `--allow-full-speed`.
+
+`--timeout` of a test is the time a device may take to appear or go; the
+time per protocol command is set with `--timeout` before the word `test`.
+`--poll` (0.05 s) is the time between scans of the USB tree.
+
+## Library
+
+```python
+from u2xbar import Unit
+
+with Unit() as unit:              # or Unit(serial="..."), Unit(port="/dev/ttyACM0")
+    print(unit.version())
+    unit.connect(3, 2)
+    for port in unit.list():
+        print(port.port, port.host, port.vbus, port.data)
+    print(unit.measure().i5_ma)
+```
+
+Each protocol command has a method, and `command(line)` sends any line.
+Results are dataclasses; a value the unit gives as `-` is `None`. An `err`
+reply raises `UnitError`, which carries the code. Events go to the
+`on_event` callback, or wait for `poll_events()`.
+
+## Tests
+
+```
+uv venv <venv>
+VIRTUAL_ENV=<venv> uv pip install -e . --group test
+<venv>/bin/python -m pytest
+```
+
+The tests run the tool against a fake unit on a pseudo-terminal and need no
+hardware. For the acceptance tests, a fake world ties the fake unit's
+connection commands to a fake sysfs tree, with devices that are slow, come up
+as low speed, appear on the wrong hub, stay behind, or never appear; a fake
+kernel log, a file as the block device, and a fake dfu-util complete it. One
+test reads this computer's kernel log and sysfs; it runs only with
+`U2XBAR_REAL_SYSTEM=1`.
+
+### Integration tests
+
+The integration tests (`tests/test_sim_integration.py`) run the tool against
+the firmware simulator `u2xbar-sim` (`sim/` in the u2xbar-sw repository): the
+firmware's core and protocol on the board model of its PC tests, served on a
+pseudo-terminal in real time. They run only when `U2XBAR_SIM` names the
+simulator binary:
+
+```
+cmake -S ../sim -B <build> -G Ninja
+cmake --build <build>
+U2XBAR_SIM=<build>/u2xbar-sim <venv>/bin/python -m pytest tests/test_sim_integration.py
+```
+
+Each test starts its own simulator, with its pty file in the test's
+temporary directory, and stops it at the end, also when the test fails. A
+test drives the simulated unit through the command line (`python -m u2xbar
+--port <pty>`, one process per command) or through `Unit`; most tests run
+both ways. The simulator's `state` query checks the simulated hardware: for
+example, that a connected device port's switch selects the hub of its host
+port and that its VBUS is on, or that the discharge FET comes on only after
+VBUS went off. Injections change the simulated world: a device attached, a
+fault that lasts past `fault_off_ms`, a computer that removes VBUS, the 5 V
+rail, a chip that does not answer. The tests cover every command, the
+parameters and their bounds, the error codes `syntax`, `range`, `state` and
+`hw` (the simulator cannot make an I2C transfer time out), events, `run`,
+`raw`, `shell`, `measure --csv`, `--json` and the exit codes. A hardware-rule
+violation of the board model fails the test.
+
+`scripts/check.sh` in the repository builds the simulator and runs these
+tests with the other checks.
+
+## How it was written
+
+The code and documentation are written with
+[Claude Code](https://claude.com/claude-code), using Anthropic's Claude Opus
+5.5 model.

u2xbar-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Mete Balci
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "u2xbar"
+version = "0.1.0"
+description = "Control tool and library for the u2xbar USB crossbar"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mete Balci" }]
+requires-python = ">=3.10"
+dependencies = ["pyserial>=3.5"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Hardware :: Universal Serial Bus (USB)",
+]
+
+[project.urls]
+Repository = "https://github.com/metebalci/u2xbar-sw"
+
+[project.scripts]
+u2xbar = "u2xbar.cli:run"
+
+[dependency-groups]
+test = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

u2xbar-0.1.0/setup.cfg

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

u2xbar-0.1.0/src/u2xbar/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Mete Balci
+
+"""Control tool and library for the u2xbar USB crossbar."""
+
+from .discovery import FoundUnit, find_unit, list_units
+from .errors import (
+    NoUnitError, ProtocolError, RequestError, SeveralUnitsError, U2xbarError, UnitError,
+    UnitTimeout,
+)
+from .protocol import Client, Event, Record
+from .records import (
+    DevPort, HostDetach, HostPort, HubBoost, Measurement, Param, RegBlock, Status,
+    UnitInfo, Version,
+)
+from .unit import Unit
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client", "DevPort", "Event", "FoundUnit", "HostDetach", "HostPort", "HubBoost",
+    "Measurement", "NoUnitError", "Param", "ProtocolError", "Record", "RegBlock",
+    "RequestError", "SeveralUnitsError", "Status", "U2xbarError", "Unit", "UnitError",
+    "UnitInfo", "UnitTimeout", "Version", "find_unit", "list_units",
+]

u2xbar-0.1.0/src/u2xbar/__main__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Mete Balci
+
+from .cli import run
+
+run()