oep-client-python 0.0.2__tar.gz → 0.0.3__tar.gz

{oep_client_python-0.0.2 → oep_client_python-0.0.3}/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.0.3
+- (EN) `oep_client.config` (oep.probe.config: slots, binds, plan / label / idle items, get / set / save / erase, the live slot and bind state) and the `oep config show | slot | bind | remove | save | erase` command. An English README.md, also the PyPI page.
+- (JA) `oep_client.config`（oep.probe.config: スロット、bind、plan / label / idle の項目、get / set / save / erase、スロットと bind の今の状態）と、`oep config show | slot | bind | remove | save | erase` の命令。英語の README.md（PyPI のページも）。
+
 ## 0.0.2
 - (EN) Breaking: the modules move from `oep_client.v1.*` to `oep_client.*` (`from oep_client import link`, `python -m oep_client`, `python -m oep_client.fake_serve`). The protocol revision stays in the registry and confirm.
 - (JA) 破壊的変更: モジュールを `oep_client.v1.*` から `oep_client.*` に移した（`from oep_client import link`、`python -m oep_client`、`python -m oep_client.fake_serve`）。プロトコルの revision は registry と confirm が持つ。

oep_client_python-0.0.3/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: oep-client-python
+Version: 0.0.3
+Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe
+Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
+Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python
+Author: TANAKA Masayuki
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyusb>=1.3
+Provides-Extra: hid
+Requires-Dist: hidapi>=0.14; extra == 'hid'
+Provides-Extra: usb-async
+Requires-Dist: libusb1>=3; extra == 'usb-async'
+Description-Content-Type: text/markdown
+
+# OEP Python client
+
+[日本語](README.ja.md)
+
+The host side of Open Embedded Probe (OEP). It speaks the v1 protocol of
+[oep-spec](https://github.com/Open-Embedded-Probe/oep-spec) (`docs/oep-core.ja.md` and the standard interfaces
+`docs/oep-if-*.ja.md`, a candidate being settled). The wire numbers come from `oep_client.registry`, a verbatim copy of
+oep-spec's generated `generated/oep-v1/oep_v1_registry.py`. This is an experimental stage: breaking changes are expected and
+no compatible API is promised. For a map of the specification, start with oep-spec's `docs/review-guide.ja.md`.
+
+It follows OEP's division of work: the knowledge of the target lives in the host. The probe knows only its wires and DMI /
+DP-AP transfers; the CH32 flash controller, the RAM loader, the RP2350 boot ROM, the Cortex-M debug registers and so on are
+here.
+
+```sh
+pip install oep-client-python     # PyPI (import oep_client); a checkout: pip install -e <checkout>
+uv run pytest                     # in a checkout
+```
+
+`import oep_client` is all it takes. The registry is copied from oep-spec with `tools/sync_registry.sh`. PyPI's
+`oep-client` is another project, so the distribution is named `oep-client-python`.
+
+Releases: run the GitHub Actions workflow Release (workflow_dispatch, version X.Y.Z or X.Y.ZbN). `tools/prepare_release.py`
+sets the version in pyproject.toml and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
+the tests and the build it commits, tags, makes the GitHub Release and publishes to PyPI (Trusted Publishing). Record changes
+under Unreleased in CHANGELOG.md, (EN) and (JA).
+
+## Modules (`oep_client`)
+
+| Module | Contents |
+|---|---|
+| `host` | requests and results, the session id and the lock, `call()` (raises unless it worked), pipelining, the errors (`OepError` / `Rejected` / `Failed`) |
+| `link` | transports: serial ports (always COBS + CRC as `0x00 <COBS> 0x00`, bytes outside frames skipped as noise, opened exclusively), USB vendor bulk / HID and TCP (length frames, the §5.1 resync); matching by corr and resending; `open_host(target)` |
+| `core` | interfaces by name (cached), confirm, the probe's describe (labels, the transport list), taking the lock (`take`), the pin plan, the `Interface` base |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`, `oep.target.riscv-dm`, finding the reset line, attach through GPIO |
+| `console` | `oep.target.console` (position streams) and `ConsoleIO`, read as bytes |
+| `fixture` | `oep.fixture.gpio` / `uart` (revision 1) |
+| `config` | `oep.probe.config` (slots, binds, plan / label / idle items, get / set / save / erase, the live slot and bind state) |
+| `capture` | `oep.fixture.capture` (revision 1, oep-spec oep-if-capture). Every segment read goes to the `Host.on_capture` callbacks as a `CaptureRecord` (the hook for run recorders; no wireskein dependency) |
+| `esp32_targets` | the custom interfaces `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target` (the ESP32 I2C / SPI targets of oep-probe-arduino) |
+| `decode` | decoding capture channels (I2C) |
+| `registry` | generated from oep-spec's number table (never edited; copied again from oep-spec) |
+| `arm` | `oep.wire.swd`, `oep.target.arm-adi`, MEM-AP, halting and calling functions on a Cortex-M |
+| `ch32_flash` | writing a CH32 (a RAM loader, page by page) |
+| `rp2350` | flash and reboot through the RP2350 boot ROM |
+| `uiapduino` | into and out of the UIAPduino bootloader |
+| `catalog` / `names` / `interfaces` / `dump` | the capability list and describe shapes, display |
+| `fake` / `endpoint` / `fake_serial` / `fake_serve` | the fake probe (below) |
+| `target` | one place to import the main ones from |
+
+## Example
+
+```python
+from oep_client import core, link, riscv, ch32_flash
+
+hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelined
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
+core.take(hst, 30000, owner="flash script")   # the only way in: force; else wait out the lease, name the holder
+wire = riscv.Wire(hst, "oep.wire.rvswd")
+conn, _ = wire.attach(halt=True)
+dm = riscv.RiscvDm(hst, conn)
+dm.reset_halt()
+result = ch32_flash.program(hst, dm, open("sketch.bin", "rb").read(), ch32_flash.PROFILES["x035"])
+dm.reset(confirm=True)
+wire.detach(conn)
+hst.end()
+```
+
+## The `oep` command
+
+```sh
+oep dump --port <probe>                      # what the probe offers (--fake p4-x035: no hardware)
+oep config show <probe>                      # the settings and the live slot / bind state
+oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
+oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
+oep config save <probe>                      # kept over a restart (also: remove, erase)
+```
+
+`<probe>` is a serial port, `tcp://HOST:PORT` or `usb[:VID:PID[:SERIAL]]`. A change takes the lock (owner "oep config") and
+ends the session after it; it takes effect at once and, after `save`, stays over a restart.
+
+A run on hardware: ArduinoCore-CH32's `tests/manual/oep_smoke/` (`oep_smoke.py`, `oep_probe_checks.py`).
+
+## The fake probe (a working spec)
+
+`endpoint.Endpoint` is a fake probe that answers as oep-spec says; ch32rv, this client and the probe firmware are checked
+against it (when the spec changes, this is brought in line before the firmware). `fake` holds example declarations (profiles
+`p4-x035`, `esp32-v003`, `p4-bench` = a made-up jig with three slots and two seats), `fake_serial` the byte side of a serial
+port (COBS candidates, raw bytes and binds, held during a session and resumed after it).
+
+Other programs' tests run `fake_serve` as a child process:
+
+```sh
+python -m oep_client.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
+    --console 'uptime %d\r\n' --every 100
+# first line: PTY /dev/pts/N (PORT n with --tcp 0); it ends when stdin closes
+```
+
+The pty is a serial port (the host opens it with TIOCEXCL); `--tcp PORT` is `--framing cobs` (a serial port) or
+`--framing length` (the vendor bulk / TCP form). Faults: `--drop N` (the N-th answer is not sent, once; the request did run,
+so a resend gets the remembered result), `--noise TEXT` (noise before every answer), `--corrupt N` (the N-th answer's CRC
+broken once). `--uart-plan` / `--uart-rx` give the first fixture UART a plan and RX bytes, `--run-hook` a host's own model of
+riscv-dm run. The rest: `--help`.

{oep_client_python-0.0.2 → oep_client_python-0.0.3}/README.ja.md

@@ -1,5 +1,7 @@
 # OEP Python client
 
+[English](README.md)
+
 Open Embedded Probe の host 側。v1（oep-spec の `docs/oep-core.ja.md` と `docs/oep-if-*.ja.md`、固める候補の形）を話す。番号は oep-spec の
 `generated/oep-v1/oep_v1_registry.py` をそのまま写した `oep_client.registry` から取る。破壊的変更を前提とする
 実験段階で、互換 API は約束しない。OEP を初めて読む人は oep-spec の `docs/review-guide.ja.md`（どこに何が書いてあるか）から。
@@ -29,6 +31,7 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 | `riscv` | `oep.wire.rvswd` / `oep.wire.swio`、`oep.target.riscv-dm`、リセット線の探索、GPIO 経由の attach |
 | `console` | `oep.target.console`（位置つきのストリーム）と、バイト列として読む `ConsoleIO` |
 | `fixture` | `oep.fixture.gpio` / `uart`（revision 1） |
+| `config` | `oep.probe.config`（スロット、bind、plan / label / idle の項目、get / set / save / erase、スロットと bind の今の状態） |
 | `capture` | `oep.fixture.capture`（revision 1、oep-spec の oep-if-capture）。読んだ区画は `Host.on_capture` の callback に `CaptureRecord` で渡る（記録の受け口。wireskein には依存しない） |
 | `esp32_targets` | 独自インターフェース `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target`（oep-probe-arduino の ESP32 の I2C / SPI の target） |
 | `decode` | キャプチャのチャネルの復号（I2C） |
@@ -59,7 +62,18 @@ wire.detach(conn)
 hst.end()
 ```
 
-能力の一覧は `uv run python -m oep_client dump --port <probe>`（`--fake p4-x035` でハードウェアなし）。
+## `oep` の命令
+
+```sh
+oep dump --port <probe>                      # 能力の一覧（--fake p4-x035 でハードウェアなし）
+oep config show <probe>                      # 設定とスロット / bind の今の状態
+oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
+oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
+oep config save <probe>                      # 再起動の後も残す（remove / erase もある）
+```
+
+`<probe>` はシリアルの口、`tcp://HOST:PORT`、`usb[:VID:PID[:SERIAL]]`。変更はロックを取り（owner "oep config"）、終わったら
+セッションを閉じる。変更はすぐ効き、`save` の後は再起動しても残る。
 実機での一通りの確認は ArduinoCore-CH32 の `tests/manual/oep_smoke/`（`oep_smoke.py`、`oep_probe_checks.py`）。
 
 ## 偽の probe（動く spec）

oep_client_python-0.0.3/README.md

@@ -0,0 +1,103 @@
+# OEP Python client
+
+[日本語](README.ja.md)
+
+The host side of Open Embedded Probe (OEP). It speaks the v1 protocol of
+[oep-spec](https://github.com/Open-Embedded-Probe/oep-spec) (`docs/oep-core.ja.md` and the standard interfaces
+`docs/oep-if-*.ja.md`, a candidate being settled). The wire numbers come from `oep_client.registry`, a verbatim copy of
+oep-spec's generated `generated/oep-v1/oep_v1_registry.py`. This is an experimental stage: breaking changes are expected and
+no compatible API is promised. For a map of the specification, start with oep-spec's `docs/review-guide.ja.md`.
+
+It follows OEP's division of work: the knowledge of the target lives in the host. The probe knows only its wires and DMI /
+DP-AP transfers; the CH32 flash controller, the RAM loader, the RP2350 boot ROM, the Cortex-M debug registers and so on are
+here.
+
+```sh
+pip install oep-client-python     # PyPI (import oep_client); a checkout: pip install -e <checkout>
+uv run pytest                     # in a checkout
+```
+
+`import oep_client` is all it takes. The registry is copied from oep-spec with `tools/sync_registry.sh`. PyPI's
+`oep-client` is another project, so the distribution is named `oep-client-python`.
+
+Releases: run the GitHub Actions workflow Release (workflow_dispatch, version X.Y.Z or X.Y.ZbN). `tools/prepare_release.py`
+sets the version in pyproject.toml and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
+the tests and the build it commits, tags, makes the GitHub Release and publishes to PyPI (Trusted Publishing). Record changes
+under Unreleased in CHANGELOG.md, (EN) and (JA).
+
+## Modules (`oep_client`)
+
+| Module | Contents |
+|---|---|
+| `host` | requests and results, the session id and the lock, `call()` (raises unless it worked), pipelining, the errors (`OepError` / `Rejected` / `Failed`) |
+| `link` | transports: serial ports (always COBS + CRC as `0x00 <COBS> 0x00`, bytes outside frames skipped as noise, opened exclusively), USB vendor bulk / HID and TCP (length frames, the §5.1 resync); matching by corr and resending; `open_host(target)` |
+| `core` | interfaces by name (cached), confirm, the probe's describe (labels, the transport list), taking the lock (`take`), the pin plan, the `Interface` base |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`, `oep.target.riscv-dm`, finding the reset line, attach through GPIO |
+| `console` | `oep.target.console` (position streams) and `ConsoleIO`, read as bytes |
+| `fixture` | `oep.fixture.gpio` / `uart` (revision 1) |
+| `config` | `oep.probe.config` (slots, binds, plan / label / idle items, get / set / save / erase, the live slot and bind state) |
+| `capture` | `oep.fixture.capture` (revision 1, oep-spec oep-if-capture). Every segment read goes to the `Host.on_capture` callbacks as a `CaptureRecord` (the hook for run recorders; no wireskein dependency) |
+| `esp32_targets` | the custom interfaces `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target` (the ESP32 I2C / SPI targets of oep-probe-arduino) |
+| `decode` | decoding capture channels (I2C) |
+| `registry` | generated from oep-spec's number table (never edited; copied again from oep-spec) |
+| `arm` | `oep.wire.swd`, `oep.target.arm-adi`, MEM-AP, halting and calling functions on a Cortex-M |
+| `ch32_flash` | writing a CH32 (a RAM loader, page by page) |
+| `rp2350` | flash and reboot through the RP2350 boot ROM |
+| `uiapduino` | into and out of the UIAPduino bootloader |
+| `catalog` / `names` / `interfaces` / `dump` | the capability list and describe shapes, display |
+| `fake` / `endpoint` / `fake_serial` / `fake_serve` | the fake probe (below) |
+| `target` | one place to import the main ones from |
+
+## Example
+
+```python
+from oep_client import core, link, riscv, ch32_flash
+
+hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelined
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
+core.take(hst, 30000, owner="flash script")   # the only way in: force; else wait out the lease, name the holder
+wire = riscv.Wire(hst, "oep.wire.rvswd")
+conn, _ = wire.attach(halt=True)
+dm = riscv.RiscvDm(hst, conn)
+dm.reset_halt()
+result = ch32_flash.program(hst, dm, open("sketch.bin", "rb").read(), ch32_flash.PROFILES["x035"])
+dm.reset(confirm=True)
+wire.detach(conn)
+hst.end()
+```
+
+## The `oep` command
+
+```sh
+oep dump --port <probe>                      # what the probe offers (--fake p4-x035: no hardware)
+oep config show <probe>                      # the settings and the live slot / bind state
+oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
+oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
+oep config save <probe>                      # kept over a restart (also: remove, erase)
+```
+
+`<probe>` is a serial port, `tcp://HOST:PORT` or `usb[:VID:PID[:SERIAL]]`. A change takes the lock (owner "oep config") and
+ends the session after it; it takes effect at once and, after `save`, stays over a restart.
+
+A run on hardware: ArduinoCore-CH32's `tests/manual/oep_smoke/` (`oep_smoke.py`, `oep_probe_checks.py`).
+
+## The fake probe (a working spec)
+
+`endpoint.Endpoint` is a fake probe that answers as oep-spec says; ch32rv, this client and the probe firmware are checked
+against it (when the spec changes, this is brought in line before the firmware). `fake` holds example declarations (profiles
+`p4-x035`, `esp32-v003`, `p4-bench` = a made-up jig with three slots and two seats), `fake_serial` the byte side of a serial
+port (COBS candidates, raw bytes and binds, held during a session and resumed after it).
+
+Other programs' tests run `fake_serve` as a child process:
+
+```sh
+python -m oep_client.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
+    --console 'uptime %d\r\n' --every 100
+# first line: PTY /dev/pts/N (PORT n with --tcp 0); it ends when stdin closes
+```
+
+The pty is a serial port (the host opens it with TIOCEXCL); `--tcp PORT` is `--framing cobs` (a serial port) or
+`--framing length` (the vendor bulk / TCP form). Faults: `--drop N` (the N-th answer is not sent, once; the request did run,
+so a resend gets the remembered result), `--noise TEXT` (noise before every answer), `--corrupt N` (the N-th answer's CRC
+broken once). `--uart-plan` / `--uart-rx` give the first fixture UART a plan and RX bytes, `--run-hook` a host's own model of
+riscv-dm run. The rest: `--help`.

{oep_client_python-0.0.2 → oep_client_python-0.0.3}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.2"
+version = "0.0.3"
 description = "Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe"
-readme = "README.ja.md"
+readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
 authors = [
@@ -35,7 +35,7 @@ Repository = "https://github.com/Open-Embedded-Probe/oep-client-python"
 packages = ["src/oep_client"]
 
 [tool.hatch.build.targets.sdist]
-only-include = ["src/oep_client", "tests", "README.ja.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+only-include = ["src/oep_client", "tests", "README.md", "README.ja.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
 
 [dependency-groups]
 dev = ["pytest>=8"]

{oep_client_python-0.0.2 → oep_client_python-0.0.3}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.2"
+__version__ = "0.0.3"

oep_client_python-0.0.3/src/oep_client/__main__.py

@@ -0,0 +1,217 @@
+"""The oep command: what a probe offers (dump) and its settings (config).
+
+  oep dump --port /run/board-identify/by-id/<probe>        oep dump --fake p4-x035 --prefix oep.target --json
+  oep config show <probe>
+  oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
+  oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
+  oep config remove <probe> bind 1        oep config save <probe>        oep config erase <probe>
+
+<probe>: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]. A change takes the lock (owner "oep config") and
+ends the session after it; it takes effect at once, and stays over a restart only after `save` (or --save).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import json
+import struct
+
+from . import catalog, config, core, dump, fake, host, link
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="oep", description="Open Embedded Probe: what a probe offers, its settings")
+    sub = parser.add_subparsers(dest="command", required=True)
+    _config_parser(sub)
+    d = sub.add_parser("dump", help="list and describe every interface a probe offers")
+    src = d.add_mutually_exclusive_group(required=True)
+    src.add_argument("--fake", choices=sorted(fake.PROFILES), help="in-process example probe")
+    src.add_argument("--port", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID] (lock-free reads only)")
+    d.add_argument("--prefix", default="", help="only names under this namespace (label boundaries)")
+    d.add_argument("--exact", action="store_true", help="the prefix is a whole name")
+    d.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+    if args.command == "config":
+        return _config(args)
+
+    if args.fake:
+        call = fake.PROFILES[args.fake]().call
+    else:
+        hst = link.open_host(args.port)
+        call = lambda fn, op, payload: hst.request(fn, op, payload, locked=False).payload   # noqa: E731
+    caps = dump.collect(call, args.prefix, args.exact)
+    sys.stdout.write(dump.to_json(caps) + "\n" if args.json else dump.to_text(caps))
+    return 0
+
+
+# ---- oep config ----------------------------------------------------------------------------------------------------
+
+def _config_parser(sub) -> None:
+    c = sub.add_parser("config", help="the probe's settings (oep.probe.config): slots, binds, save")
+    cs = c.add_subparsers(dest="action", required=True)
+    show = cs.add_parser("show", help="the settings and the live slot / bind state")
+    show.add_argument("probe")
+    show.add_argument("--json", action="store_true")
+    slot = cs.add_parser("slot", help="register a slot (a place a target is wired to)")
+    slot.add_argument("probe")
+    slot.add_argument("--slot", type=int, default=0, help="the slot number (default 0)")
+    slot.add_argument("--name", required=True, help="1-32 of a-z 0-9 - _ (the oep://<probe>/<name> address)")
+    slot.add_argument("--wire", default="rvswd", help="rvswd or swio (or an fn)")
+    slot.add_argument("--pins", help="swdio,swclk (one pin on swio); default: the wire's only pin set")
+    slot.add_argument("--attach", choices=sorted(config.ATTACH), default="host")
+    slot.add_argument("--retry", type=int, default=0, help="at-boot: try again every N s while absent (0: never)")
+    slot.add_argument("--mechanism", choices=sorted(config.MECHANISM), default="dmseq")
+    slot.add_argument("--lock", help="MASK:VALUE (hex u32) the target_id (WCH DMI 0x7F) must match, e.g. ffffff0f:035e0600")
+    slot.add_argument("--save", action="store_true", help="save after the change")
+    bind = cs.add_parser("bind", help="what a serial port carries")
+    bind.add_argument("probe")
+    bind.add_argument("--port", type=int, required=True, help="the serial port (its transport index, see show)")
+    bind.add_argument("--mode", choices=sorted(config.MODE), default="last-reset")
+    bind.add_argument("--stream", action="append", required=True, help="slot:NAME, slot:N or uart:FN (repeatable)")
+    bind.add_argument("--select", type=int, default=0, help="manual: the stream it carries (index in --stream)")
+    bind.add_argument("--save", action="store_true")
+    rm = cs.add_parser("remove", help="remove one item: slot N, bind PORT, plan FN, label CH, idle CH")
+    rm.add_argument("probe")
+    rm.add_argument("kind", choices=["slot", "bind", "plan", "label", "idle"])
+    rm.add_argument("key", type=int)
+    rm.add_argument("--save", action="store_true")
+    for name in ("save", "erase"):
+        cs.add_parser(name, help=f"{name} the stored settings").add_argument("probe")
+
+
+def _pins(hst, fn: int, text: str | None, wire: str) -> tuple[int, int]:
+    if text:
+        parts = [int(x, 0) for x in text.split(",")]
+        return (parts[0], parts[1] if len(parts) > 1 else 0xFFFF)
+    groups = []
+    for tag, v in core.describe(hst, fn):
+        if tag & 0x7F == catalog.CHANNEL_GROUP:
+            roles = {v[1 + 3 * i]: struct.unpack_from("<H", v, 2 + 3 * i)[0] for i in range((len(v) - 1) // 3)}
+            groups.append((roles.get(1, 0xFFFF), roles.get(2, 0xFFFF)))
+    if len(groups) != 1:
+        raise SystemExit(f"{wire}: {len(groups)} pin sets on this probe - name one with --pins")
+    return groups[0]
+
+
+def _wire_fn(hst, wire: str) -> int:
+    return int(wire) if wire.isdigit() else core.find(hst, wire if wire.startswith("oep.") else f"oep.wire.{wire}")
+
+
+def _stream(spec: str, slots: dict[str, int]) -> tuple[str, int]:
+    kind, _, key = spec.partition(":")
+    if kind not in config.STREAM or not key:
+        raise SystemExit(f"--stream {spec}: want slot:NAME, slot:N or uart:FN")
+    if kind == "slot" and not key.isdigit():
+        if key not in slots:
+            raise SystemExit(f"--stream {spec}: no slot named {key} (see oep config show)")
+        return kind, slots[key]
+    return kind, int(key)
+
+
+def _change(hst, cfg, items, save: bool) -> None:
+    core.take(hst, 3000, owner="oep config")
+    try:
+        h = cfg.set(items)
+        print(f"set: hash 0x{h:08x}")
+        if save:
+            print(f"saved: hash 0x{cfg.save():08x}")
+    finally:
+        hst.end()
+
+
+def _config(args) -> int:
+    hst = link.open_host(args.probe)
+    try:
+        cfg = config.ProbeConfig(hst)
+        if args.action == "show":
+            return _show(hst, cfg, args.json)
+        if args.action == "slot":
+            fn = _wire_fn(hst, args.wire)
+            lock = None
+            if args.lock:
+                mask, _, value = args.lock.partition(":")
+                lock = (1, struct.pack("<I", int(mask, 16)), struct.pack("<I", int(value, 16)))
+            it = config.Slot(args.slot, fn, _pins(hst, fn, args.pins, args.wire), args.name, args.attach, args.retry,
+                             args.mechanism, lock)
+            _change(hst, cfg, [it], args.save)
+        elif args.action == "bind":
+            slots = {it.name: it.slot for it in cfg.items() if isinstance(it, config.Slot)}
+            it = config.Bind(args.port, args.mode, [_stream(s, slots) for s in args.stream], args.select)
+            _change(hst, cfg, [it], args.save)
+        elif args.action == "remove":
+            _change(hst, cfg, [config.remove(args.kind, args.key)], args.save)
+        else:
+            core.take(hst, 3000, owner="oep config")
+            try:
+                if args.action == "save":
+                    print(f"saved: hash 0x{cfg.save():08x}")
+                else:
+                    cfg.erase()
+                    print("erased (the settings now in effect stay until the probe restarts)")
+            finally:
+                hst.end()
+        return 0
+    except host.Rejected as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 2
+    finally:
+        hst.link.close()
+
+
+def _show(hst, cfg, as_json: bool) -> int:
+    h, _ = cfg.get()
+    items = cfg.items()
+    st = cfg.state()
+    kinds = {i: _name(k) for i, k, _ in core.transports(hst)}
+    if as_json:
+        def plain(o):
+            return {k: (v.hex() if isinstance(v, bytes) else v) for k, v in vars(o).items()} if hasattr(o, "__dict__") \
+                else list(o)
+        out = {"hash": h, "items": [dict(type=type(i).__name__, **plain(i)) if hasattr(i, "__dict__") else plain(i)
+                                     for i in items],
+               "state": {**{k: v for k, v in vars(st).items() if k not in ("slots", "binds")},
+                         "slots": [plain(s) for s in st.slots], "binds": [plain(b) for b in st.binds]},
+               "transports": kinds}
+        print(json.dumps(out, indent=2, default=lambda o: o.hex() if isinstance(o, bytes) else str(o)))
+        return 0
+    print(f"storage: {st.storage} ({st.storage_bytes} bytes), saved hash 0x{st.saved_hash:08x}; now 0x{h:08x}")
+    print("transports: " + ", ".join(f"{i} {k}" for i, k in kinds.items()))
+    by_slot = {s.slot: s for s in st.slots}
+    print(f"slots (up to {st.slots_max}):")
+    for it in items:
+        if isinstance(it, config.Slot):
+            s = by_slot.get(it.slot)
+            pins = f"{it.pins[0]}" if it.pins[1] == 0xFFFF else f"{it.pins[0]},{it.pins[1]}"
+            retry = f" retry {it.retry_s} s" if it.attach == "at-boot" else ""
+            lock = (f" lock {int.from_bytes(it.lock[1], 'little'):08x}:{int.from_bytes(it.lock[2], 'little'):08x}"
+                    if it.lock else "")
+            live = ""
+            if s:
+                tried = "never tried" if s.last_try_ms is None else f"tried {s.last_try_ms} ms ago"
+                tid = f" target_id {s.target_id[::-1].hex()}" if s.target_id else ""
+                live = f"  -> {s.state}" + (f" (connection {s.connection})" if s.connection else f" ({tried})") + tid
+            print(f"  {it.slot} {it.name}: fn {it.wire_fn} pins {pins} {it.attach}{retry} {it.mechanism}{lock}{live}")
+    by_port = {b.port: b for b in st.binds}
+    print(f"binds (modes: {', '.join(st.bind_modes) or '-'}):")
+    names = {it.slot: it.name for it in items if isinstance(it, config.Slot)}
+    for it in items:
+        if isinstance(it, config.Bind):
+            b = by_port.get(it.port)
+            streams = ", ".join(f"slot:{names.get(i, i)}" if k == "slot" else f"{k}:{i}" for k, i in it.streams)
+            sel = f" selected {it.selected}" if it.mode == "manual" else ""
+            live = f"  -> {b.flow}" + (f", carrying {b.selected}" if b and b.selected is not None else "") if b else ""
+            print(f"  port {it.port} ({kinds.get(it.port, '?')}): {it.mode} [{streams}]{sel}{live}")
+    for it in items:
+        if not isinstance(it, (config.Slot, config.Bind)):
+            print(f"  {it}")
+    return 0
+
+
+def _name(kind: int) -> str:
+    return {v: k for k, v in core.TRANSPORT_KIND.items()}.get(kind, str(kind))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oep_client_python-0.0.3/src/oep_client/config.py

@@ -0,0 +1,228 @@
+"""oep.probe.config revision 1 (oep-spec docs/oep-if-probe-config.ja.md): the probe's settings - plan, labels, idle
+pins, slots, binds - read and set as items, saved when the host says so, and the live slot / bind state.
+
+    cfg = config.ProbeConfig(hst)
+    cfg.set([config.Slot(0, wire_fn, (2, 54), "x035", attach="at-boot", retry_s=1, mechanism="dmseq"),
+             config.Bind(1, "last-reset", [("slot", 0)])])
+    cfg.save()
+    cfg.items(), cfg.state()
+
+An item goes as its TLV; one with only its key removes the item of that key (`config.remove`). A set replaces the keys it
+carries and keeps the others; the probe checks the whole and changes nothing on a refusal.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+
+from . import catalog, core, message as m, registry as reg
+from .core import Interface
+
+_CFG = reg.PROBE_CONFIG
+ITEM = _CFG.tlv["item"]
+DESCRIBE = _CFG.tlv["describe"]
+ATTACH = {k.replace("_", "-"): v for k, v in _CFG.enum["slot_attach"].items()}
+MODE = {k.replace("_", "-"): v for k, v in _CFG.enum["bind_mode"].items()}
+STREAM = {"slot": _CFG.enum["bind_stream"]["slot_console"], "uart": _CFG.enum["bind_stream"]["fixture_uart"]}
+MECHANISM = {k: v for k, v in reg.TARGET_CONSOLE.enum["mechanism"].items()}
+SLOT_STATE = {v: k.replace("_", "-") for k, v in _CFG.enum["slot_state"].items()}
+BIND_FLOW = {v: k for k, v in _CFG.enum["bind_flow"].items()}
+IDLE = {k.replace("_", "-"): v for k, v in _CFG.enum["idle_mode"].items()}
+STORAGE_STATE = {v: k for k, v in _CFG.enum["storage_state"].items()}
+
+
+def _name(table: dict[str, int], value: int) -> str:
+    return next((k for k, v in table.items() if v == value), str(value))
+
+
+@dataclass
+class Plan:
+    fn: int
+    role: int
+    channel: int
+    TAG = ITEM["plan"]
+
+    def value(self) -> bytes:
+        return struct.pack("<HBH", self.fn, self.role, self.channel)
+
+
+@dataclass
+class Label:
+    channel: int
+    text: str
+    TAG = ITEM["label"]
+
+    def value(self) -> bytes:
+        return struct.pack("<H", self.channel) + self.text.encode()
+
+
+@dataclass
+class Idle:
+    channel: int
+    mode: str = "pull-up"          # hi-z, pull-up, pull-down
+    TAG = ITEM["idle"]
+
+    def value(self) -> bytes:
+        return struct.pack("<HB", self.channel, IDLE[self.mode])
+
+
+@dataclass
+class Slot:
+    """A place a target is wired to (probe.config §1.1). pins: (swdio, swclk), swclk 0xFFFF on one wire (swio).
+    lock: (scheme, mask, value) - the target_id a connection must show, e.g. (1, mask u32 LE, value u32 LE)."""
+    slot: int
+    wire_fn: int
+    pins: tuple[int, int]
+    name: str
+    attach: str = "host"           # host, at-boot
+    retry_s: int = 0               # at-boot: try again every retry_s while the target is not there (0: never)
+    mechanism: str = "dmseq"       # sdi, dmdata, dmseq
+    lock: tuple[int, bytes, bytes] | None = None
+    TAG = ITEM["slot"]
+
+    def value(self) -> bytes:
+        name = self.name.encode()
+        v = struct.pack("<BHHHBHBB", self.slot, self.wire_fn, *self.pins, ATTACH[self.attach],
+                        self.retry_s if self.attach == "at-boot" else 0, MECHANISM[self.mechanism], len(name)) + name
+        if self.lock is None:
+            return v + b"\x00"
+        scheme, mask, value = self.lock
+        if len(mask) != len(value) or not mask:
+            raise ValueError("a lock's mask and value have the same length, at least 1 byte")
+        return v + bytes([scheme]) + mask + value
+
+
+@dataclass
+class Bind:
+    """What serial port `port` (the describe transport index) carries (probe.config §1.2). streams: ("slot", n) or
+    ("uart", fn); selected: manual's choice (an index into streams)."""
+    port: int
+    mode: str = "last-reset"       # last-reset, manual, mixed
+    streams: list[tuple[str, int]] = field(default_factory=list)
+    selected: int = 0
+    TAG = ITEM["bind"]
+
+    def value(self) -> bytes:
+        v = struct.pack("<BBBB", self.port, MODE[self.mode], self.selected if self.mode == "manual" else 0,
+                        len(self.streams))
+        return v + b"".join(struct.pack("<BH", STREAM[kind], i) for kind, i in self.streams)
+
+
+def item(it) -> bytes:
+    return m.tlv(it.TAG, it.value())
+
+
+def remove(kind: str, key: int) -> bytes:
+    """The item that removes the item of this key: kind plan (key fn), label / idle (channel), slot, bind (port)."""
+    tag = ITEM[kind]
+    return m.tlv(tag, bytes([key]) if kind in ("slot", "bind") else struct.pack("<H", key))
+
+
+def decode(tag: int, v: bytes):
+    """One item as one of the classes above (an unknown tag: (tag, value))."""
+    if tag == ITEM["plan"] and len(v) == 5:
+        return Plan(*struct.unpack("<HBH", v))
+    if tag == ITEM["label"] and len(v) >= 2:
+        return Label(struct.unpack_from("<H", v)[0], v[2:].decode("utf-8", "replace"))
+    if tag == ITEM["idle"] and len(v) == 3:
+        return Idle(struct.unpack_from("<H", v)[0], _name(IDLE, v[2]))
+    if tag == ITEM["slot"] and len(v) >= 13:
+        n, wire_fn, swdio, swclk, attach, retry_s, mech, name_len = struct.unpack_from("<BHHHBHBB", v)
+        name = v[12:12 + name_len].decode("ascii", "replace")
+        rest = v[12 + name_len:]
+        lock = None
+        if rest and rest[0]:
+            half = (len(rest) - 1) // 2
+            lock = (rest[0], rest[1:1 + half], rest[1 + half:])
+        return Slot(n, wire_fn, (swdio, swclk), name, _name(ATTACH, attach), retry_s, _name(MECHANISM, mech), lock)
+    if tag == ITEM["bind"] and len(v) >= 4:
+        port, mode, selected, n = struct.unpack_from("<BBBB", v)
+        streams = [(_name(STREAM, v[4 + 3 * k]), struct.unpack_from("<H", v, 5 + 3 * k)[0]) for k in range(n)]
+        return Bind(port, _name(MODE, mode), streams, selected)
+    return (tag, v)
+
+
+@dataclass
+class SlotState:
+    slot: int
+    state: str                     # connected, absent, lock-mismatch, no-target-id
+    connection: int
+    last_try_ms: int | None        # since the last automatic attach (None: never tried)
+    target_id: bytes | None
+
+
+@dataclass
+class BindState:
+    port: int
+    mode: str
+    selected: int | None           # None in mixed
+    flow: str                      # idle, streaming, held
+
+
+@dataclass
+class State:
+    storage_bytes: int = 0
+    storage: str = "none"          # none, applied, unreadable
+    saved_hash: int = 0
+    items: list[int] = field(default_factory=list)
+    slots_max: int = 0
+    bind_modes: list[str] = field(default_factory=list)
+    slots: list[SlotState] = field(default_factory=list)
+    binds: list[BindState] = field(default_factory=list)
+
+
+class ProbeConfig(Interface):
+    NAME = "oep.probe.config"
+    REVISION = 1
+    GET, SET, SAVE, ERASE = (_CFG.op[k] for k in ("get", "set", "save", "erase"))
+
+    def get(self) -> tuple[int, list[tuple[int, bytes]]]:
+        """-> (hash, the items as (tag, value) in the canonical order), paged. No lock."""
+        out, h = [], 0
+        while True:
+            p = self._call(self.GET, struct.pack("<H", len(out)), locked=False).payload
+            more, h = struct.unpack_from("<BI", p)
+            page = catalog.split_tlv(p[5:])
+            out += page
+            if not more or not page:
+                return h, out
+
+    def items(self) -> list:
+        """The current settings, decoded (Plan, Label, Idle, Slot, Bind)."""
+        return [decode(t, v) for t, v in self.get()[1]]
+
+    def set(self, items: list) -> int:
+        """Items (objects of the classes above, or item TLV bytes such as remove()) -> the new hash. Needs the lock."""
+        body = b"".join(it if isinstance(it, (bytes, bytearray)) else item(it) for it in items)
+        return struct.unpack("<I", self._call(self.SET, body).payload[:4])[0]
+
+    def save(self) -> int:
+        return struct.unpack("<I", self._call(self.SAVE).payload[:4])[0]
+
+    def erase(self) -> None:
+        self._call(self.ERASE)
+
+    def state(self) -> State:
+        """storage, the items taken, slots_max, bind modes, and the live slot_state / bind_state (lock-free)."""
+        st = State()
+        for tag, v in core.describe(self.host, self.fn):
+            tag &= 0x7F
+            if tag == DESCRIBE["storage"] and len(v) >= 9:
+                st.storage_bytes, state, st.saved_hash = struct.unpack_from("<IBI", v)
+                st.storage = STORAGE_STATE.get(state, str(state))
+            elif tag == DESCRIBE["items"]:
+                st.items = list(v)
+            elif tag == DESCRIBE["slots_max"] and v:
+                st.slots_max = v[0]
+            elif tag == DESCRIBE["bind_modes"] and v:
+                st.bind_modes = [name for name, bit in MODE.items() if v[0] >> bit & 1]
+            elif tag == DESCRIBE["slot_state"] and len(v) >= 10:
+                n, state, conn, age, _scheme, tlen = struct.unpack_from("<BBHIBB", v)
+                st.slots.append(SlotState(n, SLOT_STATE.get(state, str(state)), conn,
+                                          None if age == 0xFFFFFFFF else age, bytes(v[10:10 + tlen]) or None))
+            elif tag == DESCRIBE["bind_state"] and len(v) >= 4:
+                port, mode, sel, flow = v[:4]
+                st.binds.append(BindState(port, _name(MODE, mode), None if sel == 0xFF else sel,
+                                          BIND_FLOW.get(flow, str(flow))))
+        return st

{oep_client_python-0.0.2 → oep_client_python-0.0.3}/src/oep_client/endpoint.py

@@ -207,6 +207,7 @@ class SlotRuntime:
     last_try_ms: int | None = None
     evicted: bool = False                              # the seat rule closed its connection: no retry until a new cue
     mismatch_tid: int | None = None                    # what the last automatic attach saw when the lock did not match
+    no_tid: bool = False                               # ... or it saw no target_id to check a lock against
 
 
 @dataclass
@@ -1295,11 +1296,13 @@ class Endpoint:
                 return
             tg.havereset = False
         c = self.conns[cid]
-        if self._lock_ok(s, c.tid) is True:
+        ok = self._lock_ok(s, c.tid)
+        rt.no_tid = ok is None
+        if ok is True:
             c.users.add(("slot", n))
             rt.mismatch_tid = None
         else:
-            rt.mismatch_tid = c.tid                                # found, wrong chip: let go of it
+            rt.mismatch_tid = c.tid                                # found, wrong chip (or no id): let go of it
             if not c.users:
                 self._close_conn(cid, MARK["detach"])
 
@@ -1347,7 +1350,8 @@ class Endpoint:
             state = SLOT_STATE["connected"] if ok else (SLOT_STATE["no_target_id"] if ok is None
                                                         else SLOT_STATE["lock_mismatch"])
         else:
-            state = SLOT_STATE["lock_mismatch"] if rt.mismatch_tid is not None else SLOT_STATE["absent"]
+            state = (SLOT_STATE["no_target_id"] if rt.no_tid else
+                     SLOT_STATE["lock_mismatch"] if rt.mismatch_tid is not None else SLOT_STATE["absent"])
         age = NEVER if rt.last_try_ms is None else min(NEVER - 1, self.now() - rt.last_try_ms)
         raw = b"" if tid is None else struct.pack("<I", tid)
         return struct.pack("<BBHIBB", n, state, cid or 0, age, 1 if raw else 0, len(raw)) + raw

oep_client_python-0.0.3/tests/test_config.py

@@ -0,0 +1,67 @@
+"""oep.probe.config from the client (oep_client.config) and the `oep config` command, against the fake probe."""
+
+import struct
+
+from oep_client import __main__ as cli, config, endpoint, fake, host as h
+
+
+class Clock:
+    t = 0
+
+    def __call__(self):
+        return self.t
+
+
+def open_bench():
+    ep = endpoint.Endpoint(fake.p4_bench(), Clock())
+    hst = h.Host(lambda b: ep.handle(b, 1))                         # over vendor bulk
+    hst.open(3000)
+    return ep, hst
+
+
+def test_slots_and_binds_round_trip_and_show_their_state():
+    ep, hst = open_bench()
+    cfg = config.ProbeConfig(hst)
+    pair = ep.pairs[1][0]
+    ep.targets[(1, pair)].target_id = 0x035E0601
+    lock = (1, struct.pack("<I", 0xFFFFFF0F), struct.pack("<I", 0x035E0601 & 0xFFFFFF0F))
+    cfg.set([config.Slot(0, 1, pair, "x035", "at-boot", 1, "dmseq", lock),
+             config.Bind(3, "manual", [("slot", 0), ("uart", 5)], selected=0)])
+    items = cfg.items()
+    assert [type(i).__name__ for i in items] == ["Slot", "Bind"]
+    assert items[0].name == "x035" and items[0].lock == lock and items[1].streams == [("slot", 0), ("uart", 5)]
+    st = cfg.state()
+    assert st.slots_max == 4 and st.bind_modes == ["last-reset", "manual", "mixed"]
+    assert st.slots[0].state == "connected" and st.slots[0].target_id == struct.pack("<I", 0x035E0601)
+    assert st.binds[0].port == 3 and st.binds[0].flow == "streaming"
+    saved = cfg.save()
+    assert cfg.state().saved_hash == saved and cfg.state().storage == "applied"
+    cfg.set([config.remove("bind", 3)])
+    assert [type(i).__name__ for i in cfg.items()] == ["Slot"]
+
+
+def test_a_refused_set_changes_nothing():
+    ep, hst = open_bench()
+    cfg = config.ProbeConfig(hst)
+    before = cfg.get()[0]
+    try:
+        cfg.set([config.Bind(1, "last-reset", [("slot", 0)])])    # port 1 is vendor bulk, and slot 0 is not there
+    except h.Rejected:
+        pass
+    assert cfg.get()[0] == before
+
+
+def test_the_command(capsys, monkeypatch):
+    ep, hst = open_bench()
+
+    class FakeLink:
+        def close(self):
+            pass
+    hst.link = FakeLink()
+    hst.end()                                                       # the command takes the lock itself
+    monkeypatch.setattr(cli.link, "open_host", lambda target: hst)
+    assert cli.main(["config", "slot", "x", "--name", "x035", "--pins", "2,3", "--attach", "at-boot", "--retry", "1"]) == 0
+    assert cli.main(["config", "bind", "x", "--port", "0", "--mode", "last-reset", "--stream", "slot:x035"]) == 0
+    assert cli.main(["config", "show", "x"]) == 0
+    out = capsys.readouterr().out
+    assert "0 x035: fn 1 pins 2,3 at-boot retry 1 s dmseq" in out and "port 0 (usb_serial_jtag): last-reset [slot:x035]" in out

oep_client_python-0.0.2/PKG-INFO

@@ -1,106 +0,0 @@
-Metadata-Version: 2.5
-Name: oep-client-python
-Version: 0.0.2
-Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe
-Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
-Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python
-Author: TANAKA Masayuki
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Embedded Systems
-Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
-Requires-Dist: pyserial>=3.5
-Requires-Dist: pyusb>=1.3
-Provides-Extra: hid
-Requires-Dist: hidapi>=0.14; extra == 'hid'
-Provides-Extra: usb-async
-Requires-Dist: libusb1>=3; extra == 'usb-async'
-Description-Content-Type: text/markdown
-
-# OEP Python client
-
-Open Embedded Probe の host 側。v1（oep-spec の `docs/oep-core.ja.md` と `docs/oep-if-*.ja.md`、固める候補の形）を話す。番号は oep-spec の
-`generated/oep-v1/oep_v1_registry.py` をそのまま写した `oep_client.registry` から取る。破壊的変更を前提とする
-実験段階で、互換 API は約束しない。OEP を初めて読む人は oep-spec の `docs/review-guide.ja.md`（どこに何が書いてあるか）から。
-
-target の知識は host にある、という OEP の分担に従う。probe は線と DMI / DP・AP の転送しか知らず、CH32 の flash
-コントローラ、RAM ローダー、RP2350 の boot ROM、Cortex-M の debug レジスタなどはここに置く。
-
-```sh
-pip install oep-client-python     # PyPI (import oep_client); a checkout: pip install -e <checkout>
-uv run pytest                                                            # in a checkout
-```
-
-`import oep_client` だけで使える（`sys.path` に `src/` を足す使い方は不要になった）。番号の表は `tools/sync_registry.sh` で
-oep-spec から写す。PyPI の `oep-client` は別のプロジェクトなので、配布名は `oep-client-python`。
-
-リリースは GitHub Actions の Release（workflow_dispatch、version = X.Y.Z か X.Y.ZbN）: `tools/prepare_release.py` が
-pyproject.toml と `oep_client.__version__` を書き換え、CHANGELOG.md の Unreleased をその版にし、試験と build の後に commit と tag、
-GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md の Unreleased に (EN) / (JA) で書き足しておく。
-
-## モジュール（`oep_client`）
-
-| モジュール | 中身 |
-|---|---|
-| `host` | 要求と結果、session_id とロック、`call()`（失敗なら例外）、pipeline、エラーの階層（`OepError` / `Rejected` / `Failed`） |
-| `link` | transport: シリアルの口（常に COBS + CRC、`0x00 <COBS> 0x00`、フレームの外は雑音として捨てる、排他で開く）、USB vendor bulk / HID と TCP（長さつきフレーム、§5.1 の立て直し）、corr による照合と送り直し、`open_host(target)` |
-| `core` | インターフェースを名前で探す（キャッシュつき）、confirm、probe の describe（ラベル、transport の一覧）、ロックの取り方（`take`）、ピンの割り当て（plan）、`Interface` の土台 |
-| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`、`oep.target.riscv-dm`、リセット線の探索、GPIO 経由の attach |
-| `console` | `oep.target.console`（位置つきのストリーム）と、バイト列として読む `ConsoleIO` |
-| `fixture` | `oep.fixture.gpio` / `uart`（revision 1） |
-| `capture` | `oep.fixture.capture`（revision 1、oep-spec の oep-if-capture）。読んだ区画は `Host.on_capture` の callback に `CaptureRecord` で渡る（記録の受け口。wireskein には依存しない） |
-| `esp32_targets` | 独自インターフェース `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target`（oep-probe-arduino の ESP32 の I2C / SPI の target） |
-| `decode` | キャプチャのチャネルの復号（I2C） |
-| `registry` | oep-spec の番号の表から生成したモジュール（編集しない。oep-spec から写し直す） |
-| `arm` | `oep.wire.swd`、`oep.target.arm-adi`、MEM-AP、Cortex-M の停止と関数呼び出し |
-| `ch32_flash` | CH32 の書き込み（RAM ローダー、ページ単位の書き直し） |
-| `rp2350` | RP2350 の boot ROM 経由の flash と reboot |
-| `uiapduino` | UIAPduino のブートローダへの出入り |
-| `catalog` / `names` / `interfaces` / `dump` | 能力の一覧と describe の形、表示 |
-| `fake` / `endpoint` / `fake_serial` / `fake_serve` | 偽の probe（下の「偽の probe」） |
-| `target` | 上の主なものを 1 か所から import する入口（最初の版に合わせて書いた呼び出し側のため） |
-
-## 使い方の例
-
-```python
-from oep_client import core, link, riscv, ch32_flash
-
-hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelining つき
-# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
-core.take(hst, 30000, owner="flash script")   # the only way in: force; else wait out the lease, name the holder
-wire = riscv.Wire(hst, "oep.wire.rvswd")
-conn, _ = wire.attach(halt=True)
-dm = riscv.RiscvDm(hst, conn)
-dm.reset_halt()
-result = ch32_flash.program(hst, dm, open("sketch.bin", "rb").read(), ch32_flash.PROFILES["x035"])
-dm.reset(confirm=True)
-wire.detach(conn)
-hst.end()
-```
-
-能力の一覧は `uv run python -m oep_client dump --port <probe>`（`--fake p4-x035` でハードウェアなし）。
-実機での一通りの確認は ArduinoCore-CH32 の `tests/manual/oep_smoke/`（`oep_smoke.py`、`oep_probe_checks.py`）。
-
-## 偽の probe（動く spec）
-
-`endpoint.Endpoint` は oep-spec の規範どおりに答える偽の probe で、ch32rv・この client・probe の firmware を突き合わせる
-「動く spec」として使う（spec が変わったら、probe の firmware より先にここを合わせる）。`fake` は宣言の例（profile:
-`p4-x035`、`esp32-v003`、`p4-bench` = スロット 3 か所と席 2 つの架空の治具）、`fake_serial` はシリアルの口のバイトの側（COBS の
-候補、生のバイトと bind、セッション中の停止と再開）。
-
-外のプログラムの試験には `fake_serve` を子プロセスで使う:
-
-```sh
-uv run python -m oep_client.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
-    --console 'uptime %d\r\n' --every 100
-# 最初の行: PTY /dev/pts/N（--tcp 0 なら PORT n）。stdin を閉じると終わる
-```
-
-pty がシリアルの口（host が TIOCEXCL を掛けて開く）、`--tcp PORT` は `--framing cobs`（シリアルの口）か `--framing length`
-（vendor bulk / TCP の形）。故障の注入は `--drop N`（N 番目の答えを 1 回出さない。要求は実行済みなので送り直しは覚えた答えを
-受ける）、`--noise TEXT`（答えの前に雑音）、`--corrupt N`（N 番目の答えの CRC を 1 回壊す）。ほかは `--help`。
-
-v0 の client（`oep_client.v0`）は 2026-09-26 に消した（git の履歴に残る）。v0 を話す probe はもう無い。

oep_client_python-0.0.2/src/oep_client/__main__.py

@@ -1,40 +0,0 @@
-"""Draft OEP capability discovery by name, on an in-process fake or a v1 draft probe.
-
-  uv run python -m oep_client dump --port /run/board-identify/by-id/<probe>
-  uv run python -m oep_client dump --fake p4-x035
-  uv run python -m oep_client dump --fake esp32-v003 --prefix oep.fixture
-  uv run python -m oep_client dump --fake p4-x035 --prefix oep.target --json
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-
-from . import dump, fake, host, link
-
-
-def main(argv=None) -> int:
-    parser = argparse.ArgumentParser(description="OEP capability discovery (draft)")
-    sub = parser.add_subparsers(dest="command", required=True)
-    d = sub.add_parser("dump", help="list and describe every interface a probe offers")
-    src = d.add_mutually_exclusive_group(required=True)
-    src.add_argument("--fake", choices=sorted(fake.PROFILES), help="in-process example probe")
-    src.add_argument("--port", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID] (lock-free reads only)")
-    d.add_argument("--prefix", default="", help="only names under this namespace (label boundaries)")
-    d.add_argument("--exact", action="store_true", help="the prefix is a whole name")
-    d.add_argument("--json", action="store_true", help="machine-readable output")
-    args = parser.parse_args(argv)
-
-    if args.fake:
-        call = fake.PROFILES[args.fake]().call
-    else:
-        hst = link.open_host(args.port)
-        call = lambda fn, op, payload: hst.request(fn, op, payload, locked=False).payload   # noqa: E731
-    caps = dump.collect(call, args.prefix, args.exact)
-    sys.stdout.write(dump.to_json(caps) + "\n" if args.json else dump.to_text(caps))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())