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

oep_client_python-0.0.3/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog / 変更履歴
+
+## 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 が持つ。
+- (EN) `fake_serve --uart-plan` puts the first fixture UART's RX / TX plan in at boot (as a saved config), and `--uart-rx TEXT` feeds its RX every `--every` ms once configured.
+- (JA) `fake_serve --uart-plan` で最初の fixture UART の RX / TX の plan を起動時に入れる（保存した設定として）。`--uart-rx TEXT` で、configure の後、その RX に `--every` ms ごとに文字を入れる。
+
+## 0.0.1
+- (EN) First beta on PyPI (`pip install oep-client-python`, imported as `oep_client`). OEP v1 host: serial ports always COBS with the probe's raw bytes skipped as noise and opened exclusively (TIOCEXCL), USB vendor bulk / HID and TCP (a broker) with length frames, all under one `Host` (`link.open_host(target)`); the session rules (owner, resend with the same corr, `core.take` for the lock); the standard interfaces; `Host.on_capture` for run recorders; a fake probe (`oep_client.v1.endpoint`) and `python -m oep_client.v1.fake_serve` (pty / TCP) as the working spec for other hosts' tests.
+- (JA) PyPI での最初のβ版（`pip install oep-client-python`、import は `oep_client`）。OEP v1 の host: シリアルの口は常に COBS（probe の生のバイトは雑音として捨てる、排他で開く TIOCEXCL）、USB の vendor bulk / HID と TCP（ブローカー）は長さつきのフレームで、どれも同じ `Host`（`link.open_host(target)`）。セッションの規則（owner、同じ corr での送り直し、ロックの取り方 `core.take`）、標準インターフェース、記録の受け口 `Host.on_capture`。ほかの host の試験のための「動く spec」として、偽の probe（`oep_client.v1.endpoint`）と `python -m oep_client.v1.fake_serve`（pty / TCP）。

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.1 → oep_client_python-0.0.3}/README.ja.md

@@ -1,7 +1,9 @@
 # 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.v1.registry` から取る。破壊的変更を前提とする
+`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
@@ -12,14 +14,14 @@ pip install oep-client-python     # PyPI (import oep_client); a checkout: pip in
 uv run pytest                                                            # in a checkout
 ```
 
-`import oep_client.v1` だけで使える（`sys.path` に `src/` を足す使い方は不要になった）。番号の表は `tools/sync_registry.sh` で
+`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.v1`）
+## モジュール（`oep_client`）
 
 | モジュール | 中身 |
 |---|---|
@@ -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） |
@@ -44,7 +47,7 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 ## 使い方の例
 
 ```python
-from oep_client.v1 import core, link, riscv, ch32_flash
+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)
@@ -59,7 +62,18 @@ wire.detach(conn)
 hst.end()
 ```
 
-能力の一覧は `uv run python -m oep_client.v1 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）
@@ -72,7 +86,7 @@ hst.end()
 外のプログラムの試験には `fake_serve` を子プロセスで使う:
 
 ```sh
-uv run python -m oep_client.v1.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
+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 を閉じると終わる
 ```

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.1 → oep_client_python-0.0.3}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.1"
+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 = [
@@ -25,7 +25,7 @@ usb-async = ["libusb1>=3"]   # queued asynchronous IN transfers: streaming near
 hid = ["hidapi>=0.14"]      # the vendor HID way in through the OS HID driver (Windows without WinUSB, Linux hidraw)
 
 [project.scripts]
-oep = "oep_client.v1.__main__:main"
+oep = "oep_client.__main__:main"
 
 [project.urls]
 Homepage = "https://github.com/Open-Embedded-Probe/oep-client-python"
@@ -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.3/src/oep_client/__init__.py

@@ -0,0 +1,5 @@
+"""Open Embedded Probe (OEP) host client. `oep_client` speaks the v1 protocol (oep-spec docs/oep-core.ja.md)."""
+
+__all__ = ["__version__"]
+
+__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())