oep-client-python 0.0.54__tar.gz → 0.0.55__tar.gz

{oep_client_python-0.0.54 → oep_client_python-0.0.55}/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 ## Unreleased
 
+## 0.0.55
+- (EN) The pytest plugin's `oep_host` (an OEP session on the DUT's probe, sharing its broker's lock; behind the
+  platform's own monitor it waits for the broker up to the ini `oep_broker_wait`, 10 s) and `oep_uart` (`open(baud)`:
+  an oep.fixture.uart on the port's `<port>.rx` / `<port>.tx`, a Dut-like channel with expect / expect_exact / write).
+  `link.open_host` reaches an `oep://` probe through its broker when one serves it (host guide §7.2) and its opens
+  carry `oep.probe.share` (`Host.open_extensions`); no session is kept then. `broker=False` opens the probe itself.
+  The `pytest` extra takes pexpect.
+- (JA) pytest のプラグインの `oep_host`（DUT のプローブとの OEP のセッション。broker のロックを分けてもらう。platform 自前のモニタの
+  ときは broker を ini の `oep_broker_wait`（10 秒）まで待つ）と `oep_uart`（`open(baud)`: 口の `<口>.rx` / `<口>.tx` の
+  oep.fixture.uart。expect / expect_exact / write を持つ Dut の形のチャンネル）。`link.open_host` は、broker が受け持つ `oep://` の
+  probe に broker 経由でつなぎ、open に `oep.probe.share` を付ける（`Host.open_extensions`。セッションは持ち越さない）。`broker=False`
+  で probe を直接開く。追加の依存 `pytest` に pexpect を足した。
+- (EN) `oep_client.pytest_plugin`, pytest-embedded-arduino-cli's OEP plugin, loaded by itself (`pytest11`) with the new
+  `pytest` extra (pytest-embedded-arduino-cli >= 1.12.0): the lock name `probe:<unit_id>` for every port and route of a
+  probe and for its own serial port; `port_memo` / `peer_port_memo(name)` / `port_memo_of(config, port)`, the port's
+  record by the ini `oep_memo_owner` - `.env`'s `OEP_PORT_MEMO_<unit_id>[_<PORT>]` whole, else the probe's
+  `<owner>/port/<port>`, else {} (a warning when both differ); the `oep://` pyserial console; an RP2040 board on
+  `oep://<probe>/<port>` written over SWD through the upload hook. Removed: `oep_client.pytest_rp2040_peer` (the
+  conftest line, the OpenOCD files, the `rp2040-swd:` lock key, `CH32RV`) and `rp2040_swd.write_openocd_hook`.
+  Guide: docs/pytest.md.
+- (JA) `oep_client.pytest_plugin`: pytest-embedded-arduino-cli の OEP のプラグイン。新しい追加の依存 `pytest`
+  （pytest-embedded-arduino-cli 1.12.0 以上）で自動で読み込まれる（`pytest11`）。プローブの口と経路と自身のシリアルの口のロックの名前
+  `probe:<unit_id>`。口の記録 `port_memo` / `peer_port_memo(name)` / `port_memo_of(config, port)`（ini の `oep_memo_owner`。`.env` の
+  `OEP_PORT_MEMO_<unit_id>[_<口>]` を丸ごと、無ければプローブの `<持ち主>/port/<口>`、無ければ {}。両方あって違えば警告）。pyserial の
+  `oep://` のコンソール。`oep://<probe>/<口>` の RP2040 のボードを、書き込みの hook で SWD で書く。消したもの: `oep_client.pytest_rp2040_peer`
+  （conftest の 1 行、OpenOCD のファイル、ロックの鍵 `rp2040-swd:`、`CH32RV`）と `rp2040_swd.write_openocd_hook`。ガイド: docs/pytest.ja.md。
+- (EN) Renamed: `oep_client.ota_broker` -> `oep_client.ide` (`python -m oep_client.ide`; its class `Server`): an IDE
+  server, not an OEP broker. `oep_client.rp2040_peer` -> `oep_client.rp2040_swd` (`python -m oep_client.rp2040_swd
+  flash|console`): an RP2040 over the probe's SWD, for any use. docs/swd: the IDE server, and §3.6 sharing the probe
+  through a broker by host guide §7.
+- (JA) 名前を変えた: `oep_client.ota_broker` → `oep_client.ide`（`python -m oep_client.ide`、クラスは `Server`）。OEP の broker
+  ではなく IDE のサーバーであるため。`oep_client.rp2040_peer` → `oep_client.rp2040_swd`（`python -m oep_client.rp2040_swd
+  flash|console`）。プローブの SWD の RP2040 を、用途によらず扱うもの。docs/swd: IDE のサーバーの呼び方と、§3.6 の broker との相乗り
+  （host ガイド §7）。
+- (EN) `oep_client.brokers`: finding the broker that serves a probe and sharing its lock, as OEP host guide §7.1 / §7.2
+  have it: `OEP_BROKER` (`<host>:<port>`), else the user's `oep/brokers/<unit_id>.json` (its tcp endpoints; fn 0's
+  describe must name the file's unit_id), else the probe itself; joined with `oep.probe.share`. `rp2040_peer` uses it
+  instead of running `ch32rv broker endpoint` (no ch32rv path, no `io.github.ch32-riscv-ug.share`). The virtual
+  bench's stand-in fn is named under this project (`io.github.open-embedded-probe.stand-in`).
+- (JA) `oep_client.brokers`: probe を受け持つ broker を見つけてロックを分けてもらう（OEP の host ガイド §7.1、§7.2）。`OEP_BROKER`
+  （`<host>:<port>`）、無ければ利用者の `oep/brokers/<unit_id>.json`（tcp の endpoints。fn 0 の describe の unit_id がファイルと同じこと
+  を確かめる）、無ければ probe を直接開く。相乗りは `oep.probe.share`。`rp2040_peer` は `ch32rv broker endpoint` を呼ばずにこれを使う
+  （ch32rv の場所も `io.github.ch32-riscv-ug.share` も要らない）。仮想ベンチの stand-in の fn の名前を、この project の名前空間に
+  （`io.github.open-embedded-probe.stand-in`）。
+- (EN) `oep_client.ota_broker`: the Arduino IDE's Upload button and its Debug for a board on an OEP probe, the core
+  unchanged. Each OEP port is announced as a network port (`_arduino._tcp` over mDNS, TXT board / auth_upload=no, one
+  LAN address) and the core's network upload (`espota.py`) is answered: the `.bin` checked by its MD5 and written over
+  SWD (`rp2040_peer.flash`; RP2040 boards), digits keeping espota waiting. `--gdb-port` adds
+  `oep_client.gdb_server` for it: GDB's remote protocol (M-profile target.xml, memory map, registers, memory, run /
+  stop / step, Ctrl-C, FPB breakpoints, `load` into flash as one image from the erase block, `monitor reset halt` /
+  `reset` / `halt` / `resume`), the IDE pointed at it by `debug_custom.json` (`servertype: external`). An upload while
+  gdb is connected is written within gdb's session. `--dry-run` writes nothing. Checked on a Pico: arduino-pico
+  6.3.1's own `espota.py`, `arduino-cli upload --protocol network` (73240 B in about 13 s), and cortex-debug's MI steps
+  through arduino-pico's gdb (load, a breakpoint at main, step, interrupt, reset; 9 s).
+  `virtual_bench_mdns.Announcement` takes the TXT's entries (`properties`). Guide: docs/swd.md.
+- (JA) `oep_client.ota_broker`: Arduino IDE の「書き込み」ボタンと「デバッグ」で、OEP のプローブにつないだボードを扱う。コアには手を
+  入れない。OEP の口をネットワークのポートとして名乗り（mDNS の `_arduino._tcp`、TXT は board と auth_upload=no など、アドレスは LAN の 1 つ）、
+  コアのネットワーク書き込み（`espota.py`）に答える: `.bin` を MD5 で確かめ、SWD で書く（`rp2040_peer.flash`。RP2040 のボード）。
+  書き込みの間は数字を送って espota を待たせる。`--gdb-port` でその口の `oep_client.gdb_server` も持つ: gdb のリモートプロトコル（M-profile の
+  target.xml、メモリマップ、レジスタ、メモリ、実行・停止・ステップ、Ctrl-C、FPB のブレークポイント、消去ブロックからの 1 つの像としての flash への
+  `load`、`monitor reset halt` / `reset` / `halt` / `resume`）。IDE は `debug_custom.json`（`servertype: external`）でそこへ向ける。gdb がつながって
+  いる間の書き込みは gdb のセッションの中で書く。`--dry-run` は書かない。Pico で確認: arduino-pico 6.3.1 の `espota.py`、
+  `arduino-cli upload --protocol network`（73240 B で約 13 秒）、arduino-pico の gdb で cortex-debug の MI の手順（load、main でのブレーク、
+  ステップ、一時停止、リセット。9 秒）。`virtual_bench_mdns.Announcement` は TXT の項目を受ける（`properties`）。ガイド: docs/swd.ja.md。
+
 ## 0.0.54
 - (EN) Jobs (oep::SimpleInterface::job, the probe's worker): `oep_client.call.call_wait(hst, interface, op, timeout=,
   wait=, **fields)` starts the job and reads its status op until it ends; it returns the status's fields (start_ns,

{oep_client_python-0.0.54 → oep_client_python-0.0.55}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.54
+Version: 0.0.55
 Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a virtual bench
 Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
 Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python
@@ -21,6 +21,9 @@ Provides-Extra: hid
 Requires-Dist: hidapi>=0.14; extra == 'hid'
 Provides-Extra: mdns
 Requires-Dist: zeroconf>=0.131; extra == 'mdns'
+Provides-Extra: pytest
+Requires-Dist: pexpect>=4.8; extra == 'pytest'
+Requires-Dist: pytest-embedded-arduino-cli>=1.12.0; extra == 'pytest'
 Provides-Extra: usb-async
 Requires-Dist: libusb1>=3; extra == 'usb-async'
 Description-Content-Type: text/markdown
@@ -89,6 +92,10 @@ names starting with `_`, may change. Check probe/client compatibility using the
 | `registry` | generated from oep-spec's number table (never edited; copied again from oep-spec). The public way to reach an interface by name is `registry.INTERFACES[name]` (`.revision`, `.op`, `.tlv`, `.enum`, e.g. `INTERFACES["oep.fixture.uart"].enum["role"]`); the module-level names (`FIXTURE_UART`, ...) are the same objects |
 | `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) |
+| `pytest_plugin` | pytest-embedded-arduino-cli's OEP plugin, loaded by itself with the `pytest` extra: the probe's lock `probe:<unit_id>`, the port's record `port_memo` (`.env`'s `OEP_PORT_MEMO_*`, else the probe's memo), the `oep://` console, an RP2040 board's upload over SWD, the session `oep_host` and the UART `oep_uart` ([docs/pytest.md](docs/pytest.md)) |
+| `brokers` | finding the broker that serves a probe (`OEP_BROKER`, the user's `oep/brokers/<unit_id>.json`) and sharing its lock with `oep.probe.share` (OEP host guide §7) |
+| `ide` | the Arduino IDE's network upload, received and written through an OEP probe; a GDB server too ([docs/swd.md](docs/swd.md)) |
+| `gdb_server` | GDB's remote protocol for a Cortex-M on an OEP probe's SWD (registers, memory, run / stop / step, FPB breakpoints, load into flash) |
 | `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 |
@@ -117,6 +124,11 @@ wire.detach(conn)
 hst.end()
 ```
 
+## Writing and debugging an SWD board
+
+An Arm board on an OEP probe's SWD (an RP2040 for now) is written, run and inspected from the Arduino IDE's Upload and
+Debug, or from an OEP host directly: see [docs/swd.md](docs/swd.md).
+
 ## USB access on Linux (udev)
 
 A probe enumerates with the project's USB VID:PID `1209:4F45` (transports §3). Opening its vendor bulk (libusb) or its HID

{oep_client_python-0.0.54 → oep_client_python-0.0.55}/README.ja.md

@@ -56,6 +56,10 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 | `registry` | oep-spec の番号の表から生成したモジュール（編集しない。oep-spec から写し直す）。名前からインターフェースの番号を引く公開の入口は `registry.INTERFACES[name]`（`.revision`、`.op`、`.tlv`、`.enum`。例 `INTERFACES["oep.fixture.uart"].enum["role"]`）。`FIXTURE_UART` などのモジュールの名前は同じもの |
 | `arm` | `oep.wire.swd`、`oep.target.arm-adi`、MEM-AP、Cortex-M の停止と関数呼び出し |
 | `ch32_flash` | CH32 の書き込み（RAM ローダー、ページ単位の書き直し） |
+| `pytest_plugin` | pytest-embedded-arduino-cli の OEP のプラグイン。`pytest` の追加の依存で自動で読み込まれる。プローブのロック `probe:<unit_id>`、口の記録 `port_memo`（`.env` の `OEP_PORT_MEMO_*`、無ければプローブのメモ欄）、`oep://` のコンソール、RP2040 のボードの SWD での書き込み、セッション `oep_host` と UART `oep_uart`（[docs/pytest.ja.md](docs/pytest.ja.md)） |
+| `brokers` | probe を受け持つ broker を見つけ（`OEP_BROKER`、利用者の `oep/brokers/<unit_id>.json`）、`oep.probe.share` でロックを分けてもらう（OEP の host ガイド §7） |
+| `ide` | Arduino IDE のネットワーク書き込みを受けて、OEP のプローブ越しに書く。gdb サーバーも持つ（[docs/swd.ja.md](docs/swd.ja.md)） |
+| `gdb_server` | OEP の SWD の Cortex-M に gdb のリモートプロトコルで答える（レジスタ、メモリ、実行・停止・ステップ、FPB のブレークポイント、flash への load） |
 | `rp2350` | RP2350 の boot ROM 経由の flash と reboot |
 | `uiapduino` | UIAPduino のブートローダへの出入り |
 | `catalog` / `names` / `interfaces` / `dump` | 能力の一覧と describe の形、表示 |
@@ -84,6 +88,11 @@ wire.detach(conn)
 hst.end()
 ```
 
+## SWD のボードを書く・デバッグする
+
+OEP のプローブの SWD につないだ Arm のボード（今は RP2040）を、Arduino IDE の「書き込み」と「デバッグ」から、または OEP のホストから
+直接、書いて動かして調べます。手順は [docs/swd.ja.md](docs/swd.ja.md) にあります。
+
 ## Linux での USB の権限（udev）
 
 probe はプロジェクトの USB の VID:PID `1209:4F45`（transports §3）で列挙される。その vendor bulk（libusb）や HID（hidraw）を

{oep_client_python-0.0.54 → oep_client_python-0.0.55}/README.md

@@ -62,6 +62,10 @@ names starting with `_`, may change. Check probe/client compatibility using the
 | `registry` | generated from oep-spec's number table (never edited; copied again from oep-spec). The public way to reach an interface by name is `registry.INTERFACES[name]` (`.revision`, `.op`, `.tlv`, `.enum`, e.g. `INTERFACES["oep.fixture.uart"].enum["role"]`); the module-level names (`FIXTURE_UART`, ...) are the same objects |
 | `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) |
+| `pytest_plugin` | pytest-embedded-arduino-cli's OEP plugin, loaded by itself with the `pytest` extra: the probe's lock `probe:<unit_id>`, the port's record `port_memo` (`.env`'s `OEP_PORT_MEMO_*`, else the probe's memo), the `oep://` console, an RP2040 board's upload over SWD, the session `oep_host` and the UART `oep_uart` ([docs/pytest.md](docs/pytest.md)) |
+| `brokers` | finding the broker that serves a probe (`OEP_BROKER`, the user's `oep/brokers/<unit_id>.json`) and sharing its lock with `oep.probe.share` (OEP host guide §7) |
+| `ide` | the Arduino IDE's network upload, received and written through an OEP probe; a GDB server too ([docs/swd.md](docs/swd.md)) |
+| `gdb_server` | GDB's remote protocol for a Cortex-M on an OEP probe's SWD (registers, memory, run / stop / step, FPB breakpoints, load into flash) |
 | `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 |
@@ -90,6 +94,11 @@ wire.detach(conn)
 hst.end()
 ```
 
+## Writing and debugging an SWD board
+
+An Arm board on an OEP probe's SWD (an RP2040 for now) is written, run and inspected from the Arduino IDE's Upload and
+Debug, or from an OEP host directly: see [docs/swd.md](docs/swd.md).
+
 ## USB access on Linux (udev)
 
 A probe enumerates with the project's USB VID:PID `1209:4F45` (transports §3). Opening its vendor bulk (libusb) or its HID

oep_client_python-0.0.55/docs/pytest.ja.md

@@ -0,0 +1,97 @@
+# pytest（pytest-embedded-arduino-cli）で OEP を使う
+
+[English](pytest.md)
+
+OEP のプローブとその先のボードを、[pytest-embedded-arduino-cli](https://github.com/tanakamasayuki/pytest-embedded-arduino-cli) の試験で使います。
+oep-client-python を `pytest` の追加の依存つきで入れると、プラグイン `oep_client.pytest_plugin` が自動で読み込まれます。conftest.py は要りません。
+
+```
+pip install "oep-client-python[pytest]"
+```
+
+プラグインが動くのは、試験のポートが OEP のプローブのときと、試験がプラグインの fixture を使うときだけです。
+
+## 1. ポート
+
+ポートは、pytest-embedded-arduino-cli のガイドのとおり `.env` に書きます。
+
+```sh
+# tests/.env
+TEST_SERIAL_PORT_X035C8T6_S3=oep://30eda0e31108/x035c8t6-s3
+TEST_SERIAL_PORT_PEER_PICO=oep://80f1b2d835d6/rp2040-x035
+```
+
+アドレスは `oep://<unit_id>/<口>` です（口はプローブのラベル `<口>.<線>` の前半。OEP の host ガイド §5.3）。
+
+## 2. ロック
+
+プローブは 1 台に 1 つのロックを持ちます（OEP の core §6.1）。プラグインは、pytest-embedded-arduino-cli のロックの名前を
+`probe:<unit_id>` にします。同じプローブの口と経路（`?via=...`）は、どれも同じ名前になります。プローブ自身の USB シリアルの口も同じです。
+
+- 1 つの試験の中で、DUT と相手が同じプローブに載っていても、ロックは 1 つを共有します。
+- 別の試験は、そのプローブが空くまで待ちます。
+
+## 3. 口の記録
+
+その口の先に何がつながっているか（部品、相手の種類、ボードの不良など）を、試験の引数 `port_memo` で読みます。記録の形は、記録の持ち主
+（試験のプロジェクト）が決めます。持ち主の名前は ini に書きます。
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+oep_memo_owner = "io.github.example.mylib"
+```
+
+```python
+def test_eth(dut, port_memo):
+    if port_memo.get("parts", {}).get("eth", {}).get("to") != "lan":
+        pytest.skip("eth is not wired on this port")
+```
+
+次の順に 1 つだけ使います。
+
+1. `.env` の `OEP_PORT_MEMO_<unit_id>_<口>`（口の無いプローブは `OEP_PORT_MEMO_<unit_id>`。大文字で、`-` は `_`）。JSON のオブジェクト
+   1 つを、一重引用符で囲んで書きます。丸ごと使い、メモ欄と項目ごとに混ぜません。
+2. プローブのメモ欄の `<持ち主>/port/<口>`（oep-if-memo §4）。
+3. どちらも無ければ `{}`。
+
+両方あって中身が違えば、警告を出します（メモ欄を直すか、`.env` の変数を消します）。相手の口の記録は `peer_port_memo("<名前>")` です。
+メモ欄を持たないプローブ（ほかのプラグインが `probe:<id>` の名前を返す WCH-Link など）は、`.env` だけを使います。
+
+```sh
+# tests/.env
+OEP_PORT_MEMO_BC5F4B9807F7='{"parts": {"eth": {"to": "lan"}}}'
+```
+
+メモ欄に書くのは pytest の外の道具です（`oep_client.memo` の `Memo.write` を使う道具など）。
+
+## 4. コンソール
+
+pyserial は `oep://...` を開けます（`oep_client.pyserial`）。RP2040 のボードでは、SWD で読む SEGGER RTT がコンソールになります
+（[swd.ja.md](swd.ja.md) §3.2）。スケッチは RTT を使います。
+
+## 5. 書き込み
+
+ポートが `oep://<unit_id>/<口>` で、プロファイルが RP2040 のボード（fqbn が `rp2040:`）のとき、プラグインがビルドの ELF をプローブの SWD で書きます
+（pytest-embedded-arduino-cli の書き込みの hook）。arduino-pico の書き込みの方式は問いません。それ以外は arduino-cli の書き込みのままです。
+
+## 6. セッションと UART
+
+試験の引数 `oep_host` は、DUT のポートの先のプローブとの OEP のセッションです（`oep_host.host` が Host、`oep_host.touch()` が lease を保つ）。
+60 秒より長く黙ると、セッションを失います。
+
+`oep_uart.open(baud)` は、口のラベル `<口>.rx` / `<口>.tx`（OEP の host ガイド §5.3）の線に `oep.fixture.uart` を割り当て、`expect`、
+`expect_exact`、`write` を持つチャンネルを返します（`dut` と同じ pexpect の形。既定の待ち時間は 30 秒）。
+
+```python
+def test_uart(dut, oep_uart):
+    ch = oep_uart.open(115200)
+    ch.write("ping\n")
+    ch.expect("pong")
+```
+
+## 7. ほかの道具との相乗り
+
+同じプローブを broker（OEP の host ガイド §7）が受け持っているときは、そのロックを分けてもらいます（`oep_client.brokers`）。
+DUT のコンソールが platform 自前のモニタを通るとき（pytest-embedded-arduino-cli がポートを包むとき）は、そのモニタがプローブを持ち、
+少し遅れて broker を公開します。`oep_host` は、それを ini の `oep_broker_wait` 秒（既定 10）まで待ちます。

oep_client_python-0.0.55/docs/pytest.md

@@ -0,0 +1,101 @@
+# OEP in pytest (pytest-embedded-arduino-cli)
+
+[日本語](pytest.ja.md)
+
+OEP probes and the boards behind them in [pytest-embedded-arduino-cli](https://github.com/tanakamasayuki/pytest-embedded-arduino-cli)
+tests. Installed with its `pytest` extra, oep-client-python's plugin `oep_client.pytest_plugin` loads by itself; no
+conftest.py is needed.
+
+```
+pip install "oep-client-python[pytest]"
+```
+
+The plugin acts only when a test's port is an OEP probe, or when a test asks for its fixtures.
+
+## 1. Ports
+
+Ports go in `.env`, as pytest-embedded-arduino-cli's guide has it.
+
+```sh
+# tests/.env
+TEST_SERIAL_PORT_X035C8T6_S3=oep://30eda0e31108/x035c8t6-s3
+TEST_SERIAL_PORT_PEER_PICO=oep://80f1b2d835d6/rp2040-x035
+```
+
+The address is `oep://<unit_id>/<port>` (the port is the first half of the probe's labels `<port>.<line>`, OEP host
+guide §5.3).
+
+## 2. The lock
+
+A probe has one lock (OEP core §6.1). The plugin names pytest-embedded-arduino-cli's lock `probe:<unit_id>`: every
+port and route (`?via=...`) of one probe has that name, and so has the probe's own USB serial port.
+
+- In one test, a DUT and a peer on the same probe share the one lock.
+- Another test waits until the probe is free.
+
+## 3. The port's record
+
+What is wired to a port (parts, the kind of its peer, the board's defects) is read with the test argument `port_memo`.
+The record's shape is its owner's (the test's project); the owner's name goes in the ini.
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+oep_memo_owner = "io.github.example.mylib"
+```
+
+```python
+def test_eth(dut, port_memo):
+    if port_memo.get("parts", {}).get("eth", {}).get("to") != "lan":
+        pytest.skip("eth is not wired on this port")
+```
+
+The first of these is used:
+
+1. `.env`'s `OEP_PORT_MEMO_<unit_id>_<PORT>` (`OEP_PORT_MEMO_<unit_id>` for a probe without ports; upper case, `-` as
+   `_`): one JSON object in single quotes, used whole, never mixed with the memo member by member.
+2. The probe's memo object `<owner>/port/<port>` (oep-if-memo §4).
+3. `{}`.
+
+When both are there and differ, a warning (correct the memo or drop the variable). A peer's record is
+`peer_port_memo("<name>")`. A probe without a memo area (a WCH-Link another plugin names `probe:<id>`) has `.env` only.
+
+```sh
+# tests/.env
+OEP_PORT_MEMO_BC5F4B9807F7='{"parts": {"eth": {"to": "lan"}}}'
+```
+
+The memo is written by tools outside pytest (ones using `oep_client.memo`'s `Memo.write`).
+
+## 4. The console
+
+pyserial opens `oep://...` (`oep_client.pyserial`). For an RP2040 board it is the SEGGER RTT read over SWD
+([swd.md](swd.md) §3.2); the sketch uses RTT.
+
+## 5. The upload
+
+For a port `oep://<unit_id>/<port>` whose profile is an RP2040 board (fqbn `rp2040:`), the plugin writes the build's
+ELF over the probe's SWD (pytest-embedded-arduino-cli's upload hook), whatever arduino-pico's upload method is.
+Anything else is arduino-cli's upload.
+
+## 6. The session and the UART
+
+The test argument `oep_host` is an OEP session on the probe behind the DUT's port (`oep_host.host` is the Host,
+`oep_host.touch()` keeps the lease); quiet for longer than 60 s, it loses the session.
+
+`oep_uart.open(baud)` plans an `oep.fixture.uart` onto the port's lines labelled `<port>.rx` / `<port>.tx` (OEP host
+guide §5.3) and returns a channel with `expect`, `expect_exact` and `write` (pexpect, like `dut`; 30 s by default).
+
+```python
+def test_uart(dut, oep_uart):
+    ch = oep_uart.open(115200)
+    ch.write("ping\n")
+    ch.expect("pong")
+```
+
+## 7. Sharing with other tools
+
+When a broker (OEP host guide §7) serves the probe, the plugin shares its lock (`oep_client.brokers`). When the DUT's
+console runs through the platform's own monitor (pytest-embedded-arduino-cli wraps the port), that monitor holds the
+probe and publishes its broker a moment later; `oep_host` waits for it up to the ini value `oep_broker_wait` seconds
+(default 10).

oep_client_python-0.0.55/docs/swd.ja.md

@@ -0,0 +1,173 @@
+# SWD のボードを書く・デバッグする
+
+[English](swd.md)
+
+OEP のプローブの SWD につないだ Arm のボードを、書いて、動かして、止めて調べます。道は 2 つです。
+
+- **Arduino IDE から**: 「書き込み」ボタンと「デバッグ」ボタン。コアにも IDE の設定にも手を入れません。IDE のサーバーを 1 つ起動しておき、デバッグにはスケッチのフォルダに `debug_custom.json` を置きます。
+- **OEP のホストから直接**: コマンド、gdb、pytest、Python。
+
+対象は RP2040 のボード（Raspberry Pi Pico など、arduino-pico）のコア 0 です。
+
+## 1. つなぐ
+
+- 線は SWDIO、SWCLK、GND の 3 本です。ボードの電源はボード側で用意します。
+- プローブの 2 本の channel に、口の名前を付けたラベル `<口>.swdio` と `<口>.swclk` を付けます。以後、ボードは `oep://<unit id>/<口>` で指します。
+
+  ```
+  oep settings set oep://<unit id> core channel.GPIO28.label=pico.swdio channel.GPIO27.label=pico.swclk --save
+  ```
+
+  どの channel につながったか分からなければ、`oep pins` で探せます（README の「ピンを探す」）。
+- コンソールに UART を使うなら、ボードの TX をプローブの空いている channel につなぎます（3.4）。
+
+## 2. Arduino IDE から
+
+### 2.1 IDE のサーバーを起動する
+
+```
+pip install oep-client-python
+python -m oep_client.ide oep://<unit id>/pico=rpipico --gdb-port 3333
+```
+
+- `=rpipico` は IDE に見せるボードの名前です（省くと `rpipico`）。口はいくつでも並べられます。口ごとに、ネットワークのポートが 1 つと、
+  gdb のポートが 1 つ（`--gdb-port` から順に）できます。
+- IDE のサーバーは、書き込みが来たときと gdb がつながっている間だけプローブを使います。ほかの時間は、ほかの道具がそのプローブを使えます。
+- 起動の行に、口ごとの名前、UDP のポート、gdb のポートが出ます。
+
+### 2.2 書き込む
+
+1. IDE でボード（Raspberry Pi Pico など）を選びます。
+2. 「ツール > ポート」で、ネットワークのポート `oep-<unit id>-<口> at <アドレス>` を選びます。IDE のサーバーを起動してから一覧に出るまで、数秒
+   かかることがあります。
+3. 「書き込み」を押します。パスワードを聞かれたら、空のまま OK します。
+
+IDE のサーバーは、IDE が送る `.bin` を MD5 で確かめてから SWD で書き、読み返して確かめ、ボードを起動し直します。
+
+仕組み: IDE のサーバーは口ごとに mDNS の `_arduino._tcp` を名乗り（TXT は `board`、`auth_upload=no`、`tcp_check=no`、`ssh_upload=no`）、
+コアのネットワーク書き込み（arduino-pico の `tools/espota.py`）の受け手になります。名乗るアドレスは 1 つで、LAN のものです（`--interface` で
+選べます）。
+
+### 2.3 デバッグする
+
+スケッチのフォルダに `debug_custom.json` を置き、IDE のデバッグをIDE のサーバーの gdb サーバーへ向けます。
+
+```json
+[
+  {
+    "configId": "rp2040:rp2040:rpipico",
+    "servertype": "external",
+    "gdbTarget": "localhost:3333"
+  }
+]
+```
+
+- ファイルは配列です。`configId` は、IDE が作るデバッグの設定の `configId` と同じ文字列にします。ボードの FQBN で、ボードのメニューを既定
+  から変えていればその値も付きます。合わない要素は黙って無視されるので、IDE が一度デバッグを始めた後にスケッチのフォルダの
+  `.theia/launch.json` に書く値を写すのが確実です。
+- 「デバッグ」を押すと、IDE はスケッチを書き込み（gdb の `load`）、コアをリセットして止め、`main` で止まります。ブレークポイント、ステップ、
+  一時停止、変数とレジスタの表示が使えます。
+- gdb サーバーは 127.0.0.1 だけで待ちます。IDE はIDE のサーバーと同じ PC で動かします。
+- デバッグの間に「書き込み」を押しても、gdb は切れません。IDE のサーバーは gdb のセッションの中で書き、コアだけをリセットして走らせます。
+
+### 2.4 コンソール
+
+ボードの UART を、プローブの USB シリアル（CDC）にそのまま流す設定を入れ、IDE のシリアルモニタでプローブのポートを開きます。
+
+```
+oep settings set oep://<unit id> oep.fixture.uart/0 passthrough.cdc0.rx=GPIO12 passthrough.cdc0.baud=115200 --save
+```
+
+- `GPIO12` はボードの TX をつないだ channel、`cdc0` はプローブの 1 つ目の CDC です（経路の名前は oep-spec core §13.3）。
+- 設定はセッションに関係なく効き、`--save` で起動し直しても残ります。
+
+### 2.5 できないこと
+
+- コア 1 は扱いません（コア 0 だけ）。
+- ハードウェアのブレークポイントは 4 つまでです（RP2040 の FPB）。flash の中のブレークポイントは、gdb が自動でハードウェアのものにします。
+- ウォッチポイントはありません。
+
+## 3. OEP のホストから直接
+
+### 3.1 書く
+
+```
+python -m oep_client.rp2040_swd flash oep://<unit id>/pico sketch.ino.elf
+```
+
+ELF（flash の中の読み込む部分を並べる）か `.bin`（0x10000000 からの flash の中身）を書き、読み返して確かめ、ボードを起動し直します。
+
+### 3.2 コンソール（SEGGER RTT）
+
+UART の線が無くても、ボードの RAM の RTT のリングを SWD で読めます（スケッチが RTT を使うとき）。
+
+```
+python -m oep_client.rp2040_swd console oep://<unit id>/pico 10       # 10 秒の間、出力を表示する
+```
+
+pyserial からは、`oep_client.pyserial` を登録すると `oep://` を開けます。
+
+```python
+import serial
+serial.protocol_handler_packages.append("oep_client.pyserial")
+port = serial.serial_for_url("oep://<unit id>/pico")
+```
+
+### 3.3 gdb で
+
+IDE のサーバーの gdb サーバーに、コアに付いてくる gdb（arduino-pico なら `arm-none-eabi-gdb`）でつなぎます。書き込みの受け手が要らなければ、
+IDE のサーバーをこの用途だけに起動しても同じです。
+
+```
+arm-none-eabi-gdb sketch.ino.elf
+(gdb) target extended-remote 127.0.0.1:3333
+(gdb) monitor reset halt
+(gdb) load
+(gdb) monitor reset halt
+(gdb) break loop
+(gdb) continue
+```
+
+| monitor のコマンド | 動き |
+|---|---|
+| `reset halt`（`reset init`） | コアをリセットし、最初の命令で止める |
+| `reset`（`reset run`） | コアをリセットして走らせる |
+| `halt` | 止める |
+| `resume`（`go`） | 走らせる |
+
+gdb のつながっている間、IDE のサーバーはプローブのロックを持ち、5 秒ごとに keepalive を送ります。
+
+### 3.4 pytest（pytest-embedded-arduino-cli）
+
+試験の DUT や相手の Pico は、プラグイン `oep_client.pytest_plugin` が SWD で書き、RTT をコンソールにします。ポートは `.env` の
+`TEST_SERIAL_PORT_*=oep://<unit id>/<口>` です。詳しくは [pytest.ja.md](pytest.ja.md) にあります。
+
+### 3.5 Python から
+
+```python
+from oep_client import arm, link, rp2040
+
+hst = link.open_host("oep://<unit id>")
+hst.open(60000, owner="my-tool")
+wire = arm.SwdWire(hst)
+conn, dpidr, _ = wire.attach(targetsel=rp2040.TARGETSEL_CORE0, pins=(28, 27))   # SWDIO、SWCLK の channel
+adi = arm.ArmAdi(hst, conn)
+adi.power_up()
+mem = arm.MemAp(adi, 0)
+core = rp2040.core_of(mem)
+core.halt()
+print(hex(core.reg(15)))      # PC
+core.resume()
+wire.detach(conn)
+hst.end()
+hst.link.close()
+```
+
+- `oep_client.arm`: `SwdWire`（`oep.wire.swd`）、`ArmAdi`（`oep.target.arm-adi`）、`MemAp`、`CortexM`（停止、レジスタ、関数の呼び出し）。
+- `oep_client.rp2040`: boot ROM での flash の書き込み（`program_and_verify`）と再起動。
+
+### 3.6 ほかの道具とプローブを分ける
+
+同じプローブを broker（OEP の host ガイド §7）が受け持っているときは、`rp2040_swd` と IDE のサーバーはそのロックを分けてもらいます
+（`oep_client.brokers`: 環境変数 `OEP_BROKER`、利用者の `oep/brokers/<unit_id>.json`、相乗りの拡張 `oep.probe.share`）。broker が
+いなければ、プローブを直接開きます。