cable-station 0.1.0__py3-none-any.whl

cable_station/__init__.py

@@ -0,0 +1,3 @@
+"""cable-station: read USB-C cable e-markers with a POWER-Z KM003C or a Mac, record each cable, and print a wrap-flag."""
+
+__version__ = "0.1.0"

cable_station/cli.py

@@ -0,0 +1,182 @@
+"""The `cable-station` command.
+
+Subcommands:
+  station            the full-screen station (default when no subcommand is given)
+  snapshot [--json]  what every USB-C port of this Mac sees right now: chip, link, partner
+  decode LOG         decode a `km003c pd capture --raw` log and print the cable's e-marker fields
+  print ID           reprint the flag of a recorded cable (--dry-run renders without printing)
+  doctor             check the tools and folders the station needs
+  config             print the settings in force and where they came from
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from . import __version__, config, records
+from . import tester_capture as em
+
+
+def cmd_station(s: config.Settings, a) -> int:
+    from .station import CableStation
+    if a.hours:
+        s.capture_hours = a.hours
+    if a.connector:
+        s.connector = a.connector
+    CableStation(s).run()
+    return 0
+
+
+def cmd_snapshot(s: config.Settings, a) -> int:
+    if not config.is_macos():
+        print("snapshot reads the Mac's port registry (ioreg) and needs macOS.", file=sys.stderr)
+        return 2
+    from . import mac_reader
+    ports = mac_reader.read_ports()
+    if a.json:
+        out = {}
+        for p, st in sorted(ports.items()):
+            d = asdict(st)
+            d["link_class"], d["link"] = st.link()
+            if st.emarker:
+                d["emarker"]["label_lines"] = list(st.emarker.label_lines())
+                d["emarker"]["watts"] = st.emarker.watts
+            out[p] = d
+        print(json.dumps(out, indent=2, default=str))
+    else:
+        for p, st in sorted(ports.items()):
+            print(st.summary())
+    if a.read_test:
+        from . import throughput
+        vol = Path("/Volumes") / a.read_test if not a.read_test.startswith("/") else Path(a.read_test)
+        if not vol.is_dir():
+            print(f"volume {vol} is not mounted", file=sys.stderr)
+            return 2
+        res = throughput.read_throughput(vol, a.seconds)
+        if res is None:
+            print(f"no files of 256 MB or more on {vol} to read")
+        else:
+            print(f"read test (experimental): {res[0]:,.0f} MB/s over {res[1] / 1e6:,.0f} MB from {vol}")
+    return 0
+
+
+def cmd_decode(s: config.Settings, a) -> int:
+    text = Path(a.log).read_text(errors="replace")
+    res = em.decode(text)
+    if not res:
+        print("no cable Discover Identity ACK on SOP' found in the capture", file=sys.stderr)
+        return 1
+    if a.json:
+        print(json.dumps(res, indent=2))
+    else:
+        for r in res:
+            print(em.format_result(r))
+            print()
+    return 0
+
+
+def cmd_print(s: config.Settings, a) -> int:
+    from .station import Printer
+    store = records.Store(s.data_dir)
+    rec = store.get(a.id if a.id.startswith("C") else f"C{a.id}")
+    if rec is None:
+        print(f"no record {a.id} in {s.data_dir}", file=sys.stderr)
+        return 1
+    s.ensure_dirs()
+    line1, line2 = rec["data_label"], rec["power_label"].split(" · #")[0]
+    printer = Printer(s)
+    png, desc = printer.render(rec["id"], line1, line2, rec.get("label_note", ""))
+    print(f"{rec['id']}: {line1} / {line2} · #{rec['id'][1:]}  ->  {png} ({desc})")
+    if a.preview:
+        printer.open_preview(png)
+    if not a.render_only:
+        print(printer.print(rec["id"], line1, line2, rec.get("label_note", ""), dry_run=a.dry_run))
+    return 0
+
+
+def cmd_doctor(s: config.Settings, a) -> int:
+    ok = True
+
+    def row(label, good, detail):
+        nonlocal ok
+        ok = ok and (good is not False)
+        mark = {True: "ok  ", False: "MISSING", None: "info"}[good]
+        print(f"{mark:8}{label:28}{detail}")
+
+    row("config file", True if Path(s.source).is_file() else None, s.source if s.source != "defaults" else f"none (defaults in force; create {config.config_path()})")
+    row("data dir (records)", s.data_dir.is_dir() or None, f"{s.data_dir}  ({len(records.Store(s.data_dir).read_all()) if s.data_dir.is_dir() else 0} cables)" if s.data_dir.is_dir() else f"{s.data_dir}  (created on first run)")
+    row("state dir", s.state_dir.is_dir() or None, str(s.state_dir))
+    km = shutil.which(s.km003c) or (s.km003c if Path(s.km003c).is_file() else None)
+    row("km003c CLI (tester path)", bool(km), km or f"{s.km003c} not on PATH: build okhsunrog/km003c-rs (see README); modes 2 and 3 still work")
+    pt = shutil.which("ptouch-label")
+    row("ptouch-label (printing)", bool(pt), pt or "not on PATH: `uv tool install git+https://github.com/johntrandall/ptouch-label`; flags still render to the state dir")
+    row("printer model", True, f"{s.printer_model}, {s.tape_mm} mm tape")
+    if config.is_macos():
+        from . import mac_reader
+        row("tester on USB", mac_reader.tester_present() or None, "a POWER-Z device is on the USB tree" if mac_reader.tester_present() else "no POWER-Z device seen on USB (plug the tester's PC port into this Mac for mode 1)")
+        try:
+            ports = mac_reader.read_ports()
+            row("Mac port registry", True, f"{len(ports)} USB-C ports readable (modes 2 and 3)")
+        except Exception as e:
+            row("Mac port registry", False, f"ioreg failed: {e}")
+    else:
+        row("Mac port registry", None, "not macOS: modes 2 and 3 (the Mac reader) are unavailable; the tester path and records work")
+    row("partners", True, ", ".join(f"{k}: {', '.join(v) or 'any device'}" for k, v in s.partners.items()))
+    print("\nall required tools present" if ok else "\nsomething is missing; the lines marked MISSING say what to install")
+    return 0 if ok else 1
+
+
+def cmd_config(s: config.Settings, a) -> int:
+    d = asdict(s)
+    d["data_dir"], d["state_dir"] = str(s.data_dir), str(s.state_dir)
+    d["config_path"] = str(config.config_path())
+    print(json.dumps(d, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="cable-station", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version=f"cable-station {__version__}")
+    ap.add_argument("--config", help="settings file (default ~/.config/cable-station/config.toml)")
+    sub = ap.add_subparsers(dest="cmd")
+    p = sub.add_parser("station", help="the full-screen station (default)")
+    p.add_argument("--hours", type=float, help="length of one tester capture before it restarts")
+    p.add_argument("--connector", help='connector type recorded for new cables, e.g. "USB-C to USB-C"')
+    p.set_defaults(func=cmd_station)
+    p = sub.add_parser("snapshot", help="what every USB-C port sees right now (macOS)")
+    p.add_argument("--json", action="store_true")
+    p.add_argument("--read-test", metavar="VOLUME", help="experimental: also read files from this mounted volume and report MB/s")
+    p.add_argument("--seconds", type=float, default=8.0)
+    p.set_defaults(func=cmd_snapshot)
+    p = sub.add_parser("decode", help="decode a `km003c pd capture --raw` log")
+    p.add_argument("log")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_decode)
+    p = sub.add_parser("print", help="reprint a recorded cable's flag")
+    p.add_argument("id", help="C17 or 17")
+    p.add_argument("--dry-run", action="store_true", help="pass --dry-run to ptouch-label")
+    p.add_argument("--render-only", action="store_true", help="render the PNG, do not call ptouch-label")
+    p.add_argument("--preview", action="store_true", help="open the rendered PNG")
+    p.set_defaults(func=cmd_print)
+    p = sub.add_parser("doctor", help="check tools and folders")
+    p.set_defaults(func=cmd_doctor)
+    p = sub.add_parser("config", help="print the settings in force")
+    p.set_defaults(func=cmd_config)
+    return ap
+
+
+def main(argv=None) -> int:
+    ap = build_parser()
+    a = ap.parse_args(sys.argv[1:] if argv is None else argv)
+    s = config.load(Path(a.config).expanduser() if a.config else None)
+    if a.cmd is None:   # bare `cable-station` opens the station
+        return cmd_station(s, argparse.Namespace(hours=None, connector=None))
+    return a.func(s, a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cable_station/config.py

@@ -0,0 +1,124 @@
+"""Settings for cable-station: a TOML file plus environment variables.
+
+Resolution order for every setting: environment variable, then the config file, then the default.
+The config file is `~/.config/cable-station/config.toml` (override the path with `CABLE_STATION_CONFIG`).
+Nothing site-specific is hard-coded here: printer, partner device names, and the data folder all come
+from the file or the environment.
+
+Example `config.toml`:
+
+    data_dir = "~/cable-station/cables"        # one Markdown note per cable, plus the Obsidian Base
+    state_dir = "~/.local/state/cable-station"  # log, per-cable captures, rendered flag previews
+    printer_model = "PT-P950NW"                 # ptouch-label --model
+    tape_mm = 9                                 # tape loaded in the printer: 6, 9, 12, 18 or 24
+    km003c = "km003c"                           # the km003c CLI (name on PATH or a full path)
+    capture_hours = 3                           # how long one tester capture runs before it restarts
+    connector = "USB-C to USB-C"
+
+    [partners]
+    drive = ["Envoy", "Sabrent"]                # drive-mode partner names as macOS reports them (empty: any device)
+    dock = ["TS5"]                              # dock-mode partner names
+"""
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ENV_PREFIX = "CABLE_STATION_"
+
+
+def _env(name: str) -> str | None:
+    v = os.environ.get(ENV_PREFIX + name)
+    return v if v else None
+
+
+def config_path() -> Path:
+    return Path(_env("CONFIG") or "~/.config/cable-station/config.toml").expanduser()
+
+
+@dataclass
+class Settings:
+    data_dir: Path = Path("~/cable-station/cables").expanduser()
+    state_dir: Path = Path("~/.local/state/cable-station").expanduser()
+    printer_model: str = "PT-P950NW"
+    tape_mm: int = 9
+    km003c: str = "km003c"
+    capture_hours: float = 3.0
+    connector: str = "USB-C to USB-C"
+    # Vertical calibration offset of the printer, in mm: ink pushed off the band by this shift is clipped
+    # by ptouch-label (it shrinks the label), so the renderer keeps all ink inside the reachable rows.
+    vertical_offset_mm: float = 1.45
+    # Partner device names (as macOS reports them) that modes 2 and 3 watch for; empty means any device.
+    partners: dict[str, list[str]] = field(default_factory=lambda: {"drive": [], "dock": []})
+    source: str = "defaults"
+
+    @property
+    def captures_dir(self) -> Path:
+        return self.state_dir / "captures"
+
+    @property
+    def previews_dir(self) -> Path:
+        return self.state_dir / "previews"
+
+    @property
+    def log_path(self) -> Path:
+        return self.state_dir / "cable_watch.log"
+
+    def ensure_dirs(self) -> None:
+        for d in (self.data_dir, self.state_dir, self.captures_dir, self.previews_dir):
+            d.mkdir(parents=True, exist_ok=True)
+
+
+def load(path: Path | None = None) -> Settings:
+    """Settings from the environment, the TOML file, and the defaults, in that order of precedence."""
+    s = Settings()
+    p = path or config_path()
+    file: dict = {}
+    if p.is_file():
+        with open(p, "rb") as f:
+            file = tomllib.load(f)
+        s.source = str(p)
+    if "data_dir" in file:
+        s.data_dir = Path(file["data_dir"]).expanduser()
+    if "state_dir" in file:
+        s.state_dir = Path(file["state_dir"]).expanduser()
+    for key in ("printer_model", "km003c", "connector"):
+        if key in file:
+            setattr(s, key, str(file[key]))
+    if s.km003c.startswith("~"):
+        s.km003c = str(Path(s.km003c).expanduser())
+    if "tape_mm" in file:
+        s.tape_mm = int(file["tape_mm"])
+    if "capture_hours" in file:
+        s.capture_hours = float(file["capture_hours"])
+    if "vertical_offset_mm" in file:
+        s.vertical_offset_mm = float(file["vertical_offset_mm"])
+    if isinstance(file.get("partners"), dict):
+        s.partners = {k: [str(x) for x in v] for k, v in file["partners"].items()}
+    # Environment overrides.
+    if _env("DATA"):
+        s.data_dir = Path(_env("DATA")).expanduser()
+    if _env("STATE"):
+        s.state_dir = Path(_env("STATE")).expanduser()
+    if _env("PRINTER"):
+        s.printer_model = _env("PRINTER")
+    if _env("TAPE"):
+        s.tape_mm = int(_env("TAPE"))
+    if _env("KM003C"):
+        s.km003c = _env("KM003C")
+    if _env("CONNECTOR"):
+        s.connector = _env("CONNECTOR")
+    if _env("CAPTURE_HOURS"):
+        s.capture_hours = float(_env("CAPTURE_HOURS"))
+    if _env("DRIVE_PARTNERS"):
+        s.partners["drive"] = [x.strip() for x in _env("DRIVE_PARTNERS").split(",") if x.strip()]
+    if _env("DOCK_PARTNERS"):
+        s.partners["dock"] = [x.strip() for x in _env("DOCK_PARTNERS").split(",") if x.strip()]
+    return s
+
+
+def is_macos() -> bool:
+    return sys.platform == "darwin"

cable_station/flag.py

@@ -0,0 +1,125 @@
+"""Render a two-line USB cable wrap-flag as a PNG for `ptouch-label --image`.
+
+A wrap-flag is one strip whose middle wraps around the cable and whose two ends stick together as a flag.
+The same two lines are printed on each end so both flag faces read correctly. Line 2 ends with the cable's
+number as " · #N" in the same type as the specs; the middle dot alone is the separator.
+
+The reachable-band rule: the printer may print with a vertical calibration offset (1.45 mm on one PT-P950NW).
+`ptouch-label` shrinks any label whose ink would be pushed off the band by that shift, so every row of ink,
+including the fold line, stays inside H - 2 * offset rows. The tests check this.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+DPI = 360
+PRINTABLE_PX = {6: 64, 9: 106, 12: 150, 18: 234, 24: 320}  # printable rows per tape width (PT-P950NW family)
+FONT_CANDIDATES = [
+    ("/System/Library/Fonts/HelveticaNeue.ttc", 1),                        # macOS, bold face
+    ("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 0),           # Debian and Ubuntu
+    ("/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf", 0),                    # Fedora
+    ("/usr/share/fonts/TTF/DejaVuSans-Bold.ttf", 0),                       # Arch
+]
+MIN_FONT = 30   # the reachable band (64 px at 9 mm under a 1.45 mm offset) caps two lines near 30 px; longer flags only help width
+
+
+def mm(v: float) -> int:
+    return round(v / 25.4 * DPI)
+
+
+def _font_file() -> tuple[str, int] | None:
+    for path, index in FONT_CANDIDATES:
+        if Path(path).exists():
+            return path, index
+    return None
+
+
+def load_font(size: int):
+    f = _font_file()
+    if f is None:
+        return ImageFont.load_default(size=size)
+    return ImageFont.truetype(f[0], size, index=f[1])
+
+
+def fit_font(draw, lines, max_w, max_h):
+    size = 200
+    while size > 8:
+        f = load_font(size)
+        widths = [draw.textbbox((0, 0), t.replace("\u26a1", "MM"), font=f)[2] for t in lines]
+        heights = [draw.textbbox((0, 0), t, font=f)[3] - draw.textbbox((0, 0), t, font=f)[1] for t in lines]
+        if max(widths) <= max_w and sum(heights) + (len(lines) - 1) * size * 0.15 <= max_h:
+            return f
+        size -= 2
+    return load_font(8)
+
+
+def render(out, line1: str, line2: str, tape: int = 9, length: int = 70, wrap: int = 20, pad: float = 1.5,
+           cable_id: str | None = None, vertical_offset_mm: float = 1.45) -> str:
+    """Render the flag to `out` and return a one-line description of its geometry."""
+    H = PRINTABLE_PX[tape]
+    id_text = f" · #{cable_id.lstrip('C#')}" if cable_id else ""
+    lines = [line1, line2 + id_text]
+    reach = H - 2 * (mm(vertical_offset_mm) + 1)   # the rows the shifted band can still print
+    while True:      # grow the flag, 10 mm at a time up to 130 mm, until the text fits at a readable size
+        W = mm(length)
+        face_w = (W - mm(wrap)) // 2
+        img = Image.new("L", (W, H), 255)
+        d = ImageDraw.Draw(img)
+        font = fit_font(d, lines, face_w - mm(pad) * 2, reach)
+        if font.size >= MIN_FONT or length >= 130:
+            break
+        length += 10
+    id_font = font  # same weight and size as the specs; the separator alone marks it
+    gap = font.size * 0.08
+    boxes = [d.textbbox((0, 0), line1.replace("\u26a1", "MM"), font=font), d.textbbox((0, 0), line2, font=font)]
+    id_w = (d.textlength(" · ", font=font) + d.textlength(id_text[3:], font=id_font)) if id_text else 0
+    total_h = sum(b[3] - b[1] for b in boxes) + gap
+
+    def draw_with_bolt(x, y_top, text, f, box):
+        """Draw text; a \u26a1 in it becomes a drawn lightning bolt (the label font has no such glyph).
+        The bolt spans exactly the text's ink height (box), so it never leaves the reachable band."""
+        parts = text.split("\u26a1")
+        for i, part in enumerate(parts):
+            if i:
+                h = box[3] - box[1]
+                w = h * 0.72
+                bx, by = x, y_top + box[1]
+                pts = [(bx + w * 0.70, by), (bx + w * 0.05, by + h * 0.58), (bx + w * 0.42, by + h * 0.58),
+                       (bx + w * 0.25, by + h), (bx + w * 0.95, by + h * 0.38), (bx + w * 0.55, by + h * 0.38), (bx + w * 0.80, by)]
+                d.polygon(pts, fill=0)
+                x += w + f.size * 0.10
+            d.text((x, y_top), part, font=f, fill=0)
+            x += d.textlength(part, font=f)
+
+    for face_x in (0, W - face_w):
+        y = (H - total_h) / 2
+        b = boxes[0]
+        draw_with_bolt(face_x + (face_w - (b[2] - b[0])) / 2 - b[0], y - b[1], line1, font, b)
+        y += (b[3] - b[1]) + gap
+        b = boxes[1]
+        w2 = (b[2] - b[0]) + id_w
+        x = face_x + (face_w - w2) / 2 - b[0]
+        baseline = y - b[1] + font.getmetrics()[0]
+        d.text((x, baseline), line2, font=font, fill=0, anchor="ls")
+        if id_text:
+            sep = " · "
+            d.text((x + (b[2] - b[0]), baseline), sep, font=font, fill=0, anchor="ls")
+            d.text((x + (b[2] - b[0]) + d.textlength(sep, font=font), baseline), id_text[len(sep):], font=id_font, fill=0, anchor="ls")
+    # Fold line: a dotted vertical line at the exact centre of the wrap zone, kept clear of the tape edges.
+    cx = W // 2
+    margin = mm(vertical_offset_mm) + 2
+    for y in range(margin, H - margin, 6):
+        d.line([(cx, y), (cx, min(H - margin - 1, y + 2))], fill=0, width=2)
+    img.save(out)
+    return f"{W}x{H}px, tape {tape} mm, {length} mm long, font {font.size}px, faces {face_w / DPI * 25.4:.0f} mm, wrap {wrap} mm"
+
+
+def ink_rows(path) -> tuple[int, int]:
+    """(first, last) row that carries ink in a rendered flag; used to check the reachable-band rule."""
+    img = Image.open(path).convert("L")
+    w, h = img.size
+    px = img.load()
+    rows = [y for y in range(h) if any(px[x, y] < 128 for x in range(w))]
+    return (rows[0], rows[-1]) if rows else (-1, -1)

cable_station/mac_reader.py

@@ -0,0 +1,200 @@
+"""Read a USB-C cable's e-marker and trained link from the Mac's own port registry (macOS only).
+
+The Mac's port controller runs the PD Discover Identity itself and macOS exposes the cable's VDOs under
+`Port-USB-C@N / CC / SOP'` (IOObjectClass IOPortTransportComponentCCUSBPDSOPp). So with a partner device
+on the far end, the Mac reads the chip the way the tester does, and also reports the link that trained
+(USB2, USB3, CIO/Thunderbolt). Verified on an M3 Max MacBook Pro running macOS 15.
+
+API: read_ports() -> {port_number: PortState}; parse_ports(plist_bytes) does the same from a saved
+`ioreg -a -l -r -n Port-USB-C` plist (used by the tests). PortState.emarker is an EMarker or None (no chip
+answered on SOP'); PortState.link() -> (class, label) for the trained link.
+"""
+from __future__ import annotations
+
+import json
+import plistlib
+import subprocess
+from dataclasses import dataclass, field
+
+SPEED_LABEL = {0: "USB 2.0 480M", 1: "USB 3.2 5G", 2: "USB4 20G · USB 3.2 10G", 3: "USB4 ≥40G · USB 3.2 10G", 4: "USB4 80G · USB 3.2 10G"}
+LATENCY_M = {1: "~1 m", 2: "~2 m", 3: "~3 m", 4: "~4 m", 5: "~5 m", 6: "~6 m", 7: "~7 m", 8: ">7 m"}
+MAX_VBUS_V = {0: 20, 1: 30, 2: 40, 3: 50}
+
+
+@dataclass
+class EMarker:
+    vendor_id: int
+    product_id: int
+    xid: int
+    kind: str                 # passive | active | other
+    speed_code: int
+    current_a: int
+    max_vbus_v: int | None
+    epr: bool
+    length: str
+    cable_vdo: int
+    raw_vdos: list[str]
+
+    @property
+    def watts(self) -> int:
+        return 240 if (self.epr and self.current_a >= 5) else 20 * self.current_a
+
+    def label_lines(self) -> tuple[str, str]:
+        line1 = SPEED_LABEL.get(self.speed_code, f"speed code {self.speed_code}") + (" Active" if self.kind == "active" else "")
+        line2 = f"{self.watts}W {self.current_a}A" + (" EPR" if self.epr else "")
+        return line1, line2
+
+    def as_reading(self) -> dict:
+        """The same dict shape tester_capture.decode() returns, so records.from_decode() takes either."""
+        line1, line2 = self.label_lines()
+        return {"product_type": f"{self.kind} cable", "vendor_id": f"0x{self.vendor_id:04X}", "xid": f"0x{self.xid:08X}",
+                "product_id": f"0x{self.product_id:04X}", "cable_vdo": f"0x{self.cable_vdo:08X}", "speed": SPEED_LABEL.get(self.speed_code, f"speed code {self.speed_code}"),
+                "current": f"{self.current_a}A", "max_vbus": f"{self.max_vbus_v}V" if self.max_vbus_v else "", "epr": self.epr,
+                "active": self.kind == "active", "label_line1": line1, "label_line2": line2}
+
+
+def decode_emarker(meta: dict, spec_revision: int | None) -> EMarker | None:
+    vdos = [int.from_bytes(b, "little") for b in meta.get("VDOs", [])]
+    if len(vdos) < 4:
+        return None
+    id_header, cert, product, cable = vdos[0], vdos[1], vdos[2], vdos[3]
+    kind = {3: "passive", 4: "active"}.get((id_header >> 27) & 7, "other")
+    pd3 = (spec_revision or 0) >= 3
+    return EMarker(vendor_id=id_header & 0xFFFF, product_id=(product >> 16) & 0xFFFF, xid=cert, kind=kind,
+                   speed_code=cable & 7, current_a={1: 3, 2: 5}.get((cable >> 5) & 3, 3),
+                   max_vbus_v=MAX_VBUS_V[(cable >> 9) & 3] if pd3 else None,
+                   epr=bool((cable >> 17) & 1) if pd3 else False,   # PD 3.1 passive cable VDO bit 17, EPR Mode Capable
+                   length=LATENCY_M.get((cable >> 13) & 0xF, "?"), cable_vdo=cable, raw_vdos=[f"0x{v:08x}" for v in vdos])
+
+
+@dataclass
+class PortState:
+    port: int
+    connected: bool = False
+    transports_active: list = field(default_factory=list)
+    partner_vid: int | None = None
+    emarker: EMarker | None = None
+    usb2_rate: str | None = None
+    usb2_product: str | None = None
+    usb3_rate: str | None = None
+    usb3_product: str | None = None
+    cio_active: bool = False
+    cio_device: str | None = None
+    cio_cable_speed: int | None = None
+    tb_speed: str | None = None
+    dp_rate: str | None = None
+
+    def devices(self) -> str:
+        return " / ".join(x for x in (self.cio_device, self.usb3_product, self.usb2_product) if x) or "nothing"
+
+    def link(self) -> tuple[str, str]:
+        """(class, text) of the link that trained through this cable."""
+        if self.cio_active:
+            g = (self.tb_speed or "").replace("Up to ", "")
+            cls = "tb40" if "40" in g else ("tb20" if "20" in g else "tb")
+            return cls, f"Thunderbolt/USB4 {g or 'link'}"
+        if self.usb3_rate:
+            return ("usb10" if "10" in self.usb3_rate else "usb5"), f"USB3 {self.usb3_rate}"
+        if self.usb2_rate:
+            return "usb2", f"USB2 {self.usb2_rate}"
+        if self.dp_rate:
+            return "dp", f"DisplayPort {self.dp_rate}"
+        return "none", "no link"
+
+    def summary(self) -> str:
+        e = self.emarker
+        chip = (f"chip vendor 0x{e.vendor_id:04X} product 0x{e.product_id:04X} {e.kind} {e.label_lines()} VDO 0x{e.cable_vdo:08X}"
+                if e else "no e-marker answered")
+        return f"port {self.port}: connected {self.connected} · {self.devices()} · link {self.link()[1]} · {chip}"
+
+
+def _walk(node, out):
+    out.append(node)
+    for c in node.get("IORegistryEntryChildren", []):
+        _walk(c, out)
+
+
+def parse_ports(raw: bytes) -> dict[int, PortState]:
+    """Parse the output of `ioreg -a -l -r -n Port-USB-C`."""
+    roots = plistlib.loads(raw) if raw.strip() else []
+    ports: dict[int, PortState] = {}
+    for root in roots:
+        num = root.get("PortNumber")
+        if num is None:
+            continue
+        nodes: list[dict] = []
+        _walk(root, nodes)
+        st = PortState(port=num, connected=bool(root.get("ConnectionActive")), transports_active=list(root.get("TransportsActive", [])))
+        for n in nodes:
+            cls = n.get("IOObjectClass", "")
+            desc = n.get("TransportDescription") or n.get("Description") or ""
+            if cls == "IOPortTransportComponentCCUSBPDSOPp":
+                st.emarker = decode_emarker(n.get("Metadata", {}), n.get("Specification Revision"))
+            elif cls == "IOPortTransportComponentCCUSBPDSOP":
+                st.partner_vid = n.get("Vendor ID")
+            elif cls == "IOPortTransportStateUSB2" and n.get("Active"):
+                st.usb2_rate, st.usb2_product = n.get("DataRateDescription"), n.get("Product")
+            elif cls == "IOPortTransportStateUSB3" and n.get("Active"):
+                st.usb3_rate, st.usb3_product = n.get("DataRateDescription"), n.get("Product")
+            elif cls == "IOPortTransportStateCIO" and n.get("Active"):
+                st.cio_active, st.cio_device, st.cio_cable_speed = True, n.get("Device Model Name") or n.get("Device Vendor Name"), n.get("CableSpeed")
+            elif cls == "IOPortTransportStateDisplayPort" and n.get("Active") and "/CIO/" not in desc:
+                st.dp_rate = n.get("LinkRateDescription")
+        ports[num] = st
+    return ports
+
+
+def add_thunderbolt_speeds(ports: dict[int, PortState]) -> None:
+    """Fill tb_speed from `system_profiler SPThunderboltDataType` (the trained Thunderbolt rate per receptacle)."""
+    try:
+        out = subprocess.run(["system_profiler", "-json", "SPThunderboltDataType"], capture_output=True, check=True, timeout=20).stdout
+        for bus in json.loads(out).get("SPThunderboltDataType", []):
+            rec = bus.get("receptacle_1_tag", {})
+            try:
+                num = int(rec.get("receptacle_id_key", ""))
+            except ValueError:
+                continue
+            if num in ports and rec.get("receptacle_status_key") == "receptacle_connected":
+                ports[num].tb_speed = rec.get("current_speed_key")
+    except Exception:
+        pass
+
+
+def read_ports() -> dict[int, PortState]:
+    raw = subprocess.run(["ioreg", "-a", "-l", "-r", "-n", "Port-USB-C"], capture_output=True, check=True, timeout=60).stdout
+    ports = parse_ports(raw)
+    add_thunderbolt_speeds(ports)
+    return ports
+
+
+def usb_devices() -> dict:
+    """{location_id: (name, speed_text, [disks])} for every device on the Mac's USB tree right now."""
+    try:
+        out = subprocess.run(["system_profiler", "SPUSBDataType", "-json"], capture_output=True, text=True, timeout=20).stdout
+        tree = json.loads(out).get("SPUSBDataType", [])
+    except Exception:
+        return {}
+    found: dict = {}
+    speeds = {"low_speed": "1.5 Mb/s", "full_speed": "12 Mb/s", "high_speed": "480 Mb/s", "super_speed": "5 Gb/s",
+              "super_speed_plus": "10 Gb/s", "super_speed_plus_20": "20 Gb/s", "super_speed_plus_40": "40 Gb/s"}
+
+    def walk(items):
+        for it in items:
+            if "location_id" in it:
+                disks = [m.get("bsd_name") for m in it.get("Media", []) if m.get("bsd_name")]
+                speed = speeds.get(it.get("device_speed", ""), it.get("device_speed", it.get("speed", "")))
+                found[it["location_id"]] = (it.get("_name", "?"), speed, disks)
+            walk(it.get("_items", []))
+    walk(tree)
+    return found
+
+
+def tester_present() -> bool:
+    """Is a POWER-Z tester on the host's USB tree? (macOS: system_profiler; elsewhere: assume yes.)"""
+    try:
+        import sys
+        if sys.platform != "darwin":
+            return True
+        return any(any(k in v[0].upper() for k in ("POWER-Z", "POWER_Z", "POWERZ", "KM003C", "CHARGERLAB")) for v in usb_devices().values())
+    except Exception:
+        return True