oep-client-python 0.0.40__tar.gz → 0.0.41__tar.gz

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.0.41
+- (EN) Added: `oep_client.acquire`, one capture put together. A line is named by the probe's channel name (fn 0's channel_name, `GPIO47`) or a port's line label (`x035.swdio`), looked up on the session; a stream's length is `seconds` (as `LogicCapture.stream`). `capture_at(address, Request)` opens the probe, takes its lease, raises a UART link and lets it all go; `capture(hst, Request)` runs on a session the caller holds (with ProbeLog, the target's control). Modes oneshot / repeat / stream, logic and analog in a capture-group with a trigger on either track (capture §4.4), format 1 lines as their changes. The `Result` has the tick rate, the parts (`tick0`, `meta`: start_ns, start_uncertainty_ns, trigger_tick, ...), their channels as the probe gave them (`Bits`, `Changes`, `Analog`), the losses (any makes the capture a failure) and `meta["probe"]` (model, firmware, unit_id, `address` = the probe's place without the route, boot_id, clock, calibration, link). Moved from wireskein's oep source, which now writes this result as a file. numpy (extra `acquire`) puts streams and format 1 blocks together.
+- (JA) 追加: `oep_client.acquire`。1 回の取り込みを組み立てる。線は、プローブのチャンネルの名前（fn 0 の channel_name、`GPIO47`）か口の線の label（`x035.swdio`）で指し、セッションの上で番号に引く。ストリームの長さは `seconds`（`LogicCapture.stream` と同じ）。`capture_at(address, Request)` はプローブを開き、lease を取り、UART の速さを上げ、終わったら手放す。`capture(hst, Request)` は呼び手が持つセッションの上で動く（ProbeLog や target の操作と一緒に）。mode は oneshot / repeat / stream、ロジックとアナログを capture-group で一緒に、どちらのトラックの trigger も（capture §4.4）、形式 1 の線は変化で。`Result` は刻みの速さ、区間（`tick0`、`meta`: start_ns、start_uncertainty_ns、trigger_tick など）、プローブが渡したままのチャンネル（`Bits`、`Changes`、`Analog`）、欠落（1 つでもあれば失敗）、`meta["probe"]`（model、firmware、unit_id、`address` = 経路を除いたプローブの場所、boot_id、clock、calibration、link）を持つ。wireskein の oep の取り込みから移した（wireskein はこの結果をファイルに書く）。stream と形式 1 のブロックの組み立てに numpy（追加の依存 `acquire`）を使う。
+- (EN) Changed (breaking): a probe is named by its OEP address, `oep://<unit_id>[/<port>[/<target>]][?via=<route>]`
+  (oep-spec host guide §5.3; `link.parse_address`, `link.Address`, `hst.address`). Without via: its USB device (found by
+  its USB serial, any VID:PID: vendor bulk, then HID, then its one CDC port), else the TCP probe DNS-SD finds; via=usb /
+  bulk / hid / cdc / net keeps to that route, via=tcp:<host>:<port> and via=tty:<path> name it. On every route
+  describe's unit_id must be the one named. `tcp:UNIT_ID`, `usb:UNIT_ID` and `usb:VID:PID[:SERIAL]` are gone
+  (`oep://UNIT_ID?via=net`, `?via=usb`); a serial port path, `tcp://HOST[:PORT]` and a bare `usb` stay as short forms for a
+  probe whose unit_id is not known.
+- (JA) 変更（壊す変更）: probe は OEP のアドレス `oep://<unit_id>[/<port>[/<target>]][?via=<経路>]` で名指す（oep-spec の host
+  ガイド §5.3。`link.parse_address`、`link.Address`、`hst.address`）。via が無ければ USB のデバイス（USB の serial で探す。
+  VID:PID は問わない。vendor bulk、HID、ただ 1 つの CDC の順）、無ければ DNS-SD が見つけた TCP の probe。via=usb / bulk / hid / cdc /
+  net はその経路だけ、via=tcp:<host>:<port> と via=tty:<path> は経路を名指す。どの経路でも describe の unit_id が名指したものと
+  同じでなければならない。`tcp:UNIT_ID`、`usb:UNIT_ID`、`usb:VID:PID[:SERIAL]` は無くした（`oep://UNIT_ID?via=net`、`?via=usb`）。
+  unit_id を知らない probe には、シリアルの口の path、`tcp://HOST[:PORT]`、ただの `usb` を短い形として残す。
+- (EN) Changed: `virtual_bench_serve --pty` says so on stderr when it gets no inotify instance (a user's
+  fs.inotify.max_user_instances used up by editors and file watchers): it then cannot see the close of a host that ended
+  without closing the port, and the pty stays busy. The test of that case skips with this reason instead of failing.
+- (JA) 変更: `virtual_bench_serve --pty` は、inotify を作れないとき（エディタやファイルの見張りが、ユーザーの
+  fs.inotify.max_user_instances を使い切ったときなど）に、その旨を stderr に出す。このとき、口を閉じずに終わった host の
+  close が見えないので、pty は使用中のまま残る。その場合の試験は、落ちる代わりにこの理由で skip する。
+- (EN) Fixed: `oep pins`' map named pads another device moves as wired - an X035's PC16/PC17, held by a USB host,
+  "followed" different channels on every run. The map now reads the target's pads first with nothing driven and leaves
+  out those that move (a note names them), and a pad must follow its channel on 4 tries (was 2).
+- (JA) 修正: `oep pins` の map が、ほかの機器が動かすピンを「つながっている」としていた（USB ホストにつながる X035 の PC16/PC17 が、
+  走らせるたびに違うチャネルに追従した）。map は、まず何も駆動しないで target のピンを読み、動くピンを外す（note に出す）。チャネルに
+  追従するかは 4 回確かめる（前は 2 回）。
+
 ## 0.0.40
 - (EN) Labels may carry the target pin a line reaches (oep-spec host guide §5.3): `S.N@P`, and `S@P` for a line with no
   role. `settings.parse_label`, `pin_from_labels`, `label_text`, `pin_name`; `port_line` / `find_line` read `S.N@P` as

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.40
+Version: 0.0.41
 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
@@ -15,6 +15,8 @@ Requires-Python: >=3.10
 Requires-Dist: pyserial>=3.5
 Requires-Dist: pyusb>=1.3
 Requires-Dist: tomli>=2; python_version < '3.11'
+Provides-Extra: acquire
+Requires-Dist: numpy>=2.0; extra == 'acquire'
 Provides-Extra: hid
 Requires-Dist: hidapi>=0.14; extra == 'hid'
 Provides-Extra: mdns
@@ -100,10 +102,11 @@ names starting with `_`, may change. Check probe/client compatibility using the
 from oep_client import core, link, riscv, ch32_flash
 
 hst = link.open_host("/dev/ttyACM0")   # pipelined
-# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the device whose USB serial it is;
-# describe's unit_id must match), "usb" (every device on the project's VID:PID 1209:4F45, each counted once: exactly
-# one -> vendor, then HID, else its CDC port; several -> link.SeveralProbes lists them, name one) /
-# "usb:VID:PID[:SERIAL]" (vendor, then HID). Each is probed first with a
+# an OEP address "oep://<unit id>[?via=usb|bulk|hid|cdc|net|tcp:HOST:PORT|tty:PATH]" (host guide §5.3; without via
+# its USB device, else the probe DNS-SD finds; describe's unit_id must match on any route), or, when the unit id is not
+# known, a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" (every device on the project's VID:PID
+# 1209:4F45, each counted once: exactly one -> vendor, then HID, else its CDC port; several -> link.SeveralProbes lists
+# them, name one). Each is probed first with a
 # confirm only (transports §3): no valid answer -> closed, link.NotOepProbe
 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")
@@ -150,9 +153,9 @@ oep find [--timeout 2] [--json] [--no-verify]  # probes announcing _oep._tcp (ea
 oep linktest <probe> ...                     # --timeout: 0.3 s an answer by default, 3 s over TCP
 ```
 
-`<probe>` is a serial port, `tcp://HOST:PORT`, `tcp://HOST` (the port DNS-SD finds for that host), `tcp:UNIT_ID` (the
-probe DNS-SD finds by its TXT unit_id; describe's unit_id must say the same, else it is closed) or
-`usb[:VID:PID[:SERIAL]]`. A change takes the lock (owner "oep settings") and
+`<probe>` is an OEP address `oep://UNIT_ID[?via=route]` (oep-spec host guide §5.3; without via its USB device, else the
+probe DNS-SD finds; on any route describe's unit_id must say the same, else it is closed) or, when the unit_id is not
+known, a serial port, `tcp://HOST:PORT`, `tcp://HOST` (the port DNS-SD finds for that host) or `usb` (the only probe). A change takes the lock (owner "oep settings") and
 ends the session after it; it takes effect at once and, after `save`, stays over a restart.
 
 ### A host run again: the kept session id
@@ -185,7 +188,7 @@ A probe that serves OEP over TCP is found by DNS-SD (its network settings are th
   (`discovery.verify`, all at once, 1 s per answer, `--verify-timeout`): a TCP connection, confirm (an `OEP!` answer)
   and fn 0's describe, whose unit_id must be the TXT unit_id - no session is opened. One that fails is dropped with a
   warning on stderr naming its endpoint and what it said; `--no-verify` lists every instance as announced.
-  `discovery.find_unit` (and so `tcp:UNIT_ID`) verifies the same way and passes over an instance it cannot verify;
+  `discovery.find_unit` (and so `oep://UNIT_ID?via=net`) verifies the same way and passes over an instance it cannot verify;
   `open_host` then checks confirm and describe's unit_id again on the link it opens. The port
   is always the SRV record's (none is fixed - the reference probe's 7450 is an example). With python-zeroconf installed
   (`pip install 'oep-client-python[mdns]'`) it browses with it (every interface: InterfaceChoice.All), else with a
@@ -194,7 +197,7 @@ A probe that serves OEP over TCP is found by DNS-SD (its network settings are th
   installed, else each interface's address on Linux, else the host name's addresses) - one send leaves by one
   interface only, on Windows often a virtual adapter's, and a probe on another adapter never hears it. mDNS stays on the local link: from WSL 2's
   default NAT network, a VM or across a router nothing is found - name the probe as `tcp://HOST:PORT`.
-- `tcp:UNIT_ID` opens the probe DNS-SD finds by that unit_id and checks describe's (UnitIdMismatch, closed, otherwise);
+- `oep://UNIT_ID?via=net` opens the probe DNS-SD finds by that unit_id and checks describe's (UnitIdMismatch, closed, otherwise);
   after a restart it browses again (the address may change). TCP has no authentication: use it on a trusted network or
   a tunnel (transports §1).
 - `oep linktest` waits 3 s an answer over TCP (0.3 s elsewhere): Wi-Fi retransmissions stall answers for 1-4 s now and
@@ -495,6 +498,6 @@ The query's multicast loops back to this host on the interface it left by, and t
 every interface. A host with no multicast route needs `--announce-on 127.0.0.1` and the query sent with
 IP_MULTICAST_IF 127.0.0.1. A different `--unit-id` per job keeps parallel jobs apart (the port is in the instance
 name too). A container or VM answers only on its own network. tests/test_virtual_bench_announce.py does this with
-`oep find`, `discovery.find_unit` and `tcp:UNIT_ID` (both engines) - with in-process responders announcing a non-OEP
+`oep find`, `discovery.find_unit` and `oep://UNIT_ID?via=net` (both engines) - with in-process responders announcing a non-OEP
 TCP service and a wrong TXT unit_id beside it, which the verify drops - skipped where multicast does not loop back.
 

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/README.ja.md

@@ -69,10 +69,11 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 from oep_client import core, link, riscv, ch32_flash
 
 hst = link.open_host("/dev/ttyACM0")   # pipelining つき
-# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the device whose USB serial it is;
-# describe's unit_id must match), "usb" (every device on the project's VID:PID 1209:4F45, each counted once: exactly
-# one -> vendor, then HID, else its CDC port; several -> link.SeveralProbes lists them, name one) /
-# "usb:VID:PID[:SERIAL]" (vendor, then HID). Each is probed first with a
+# an OEP address "oep://<unit id>[?via=usb|bulk|hid|cdc|net|tcp:HOST:PORT|tty:PATH]" (host guide §5.3; without via
+# its USB device, else the probe DNS-SD finds; describe's unit_id must match on any route), or, when the unit id is not
+# known, a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" (every device on the project's VID:PID
+# 1209:4F45, each counted once: exactly one -> vendor, then HID, else its CDC port; several -> link.SeveralProbes lists
+# them, name one). Each is probed first with a
 # confirm only (transports §3): no valid answer -> closed, link.NotOepProbe
 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")
@@ -118,8 +119,9 @@ oep find [--timeout 2] [--json] [--no-verify]  # _oep._tcp を広告する probe
 oep linktest <probe> ...                     # --timeout: 既定は応答 1 つに 0.3 秒、TCP では 3 秒
 ```
 
-`<probe>` はシリアルの口、`tcp://HOST:PORT`、`tcp://HOST`（その host に DNS-SD が見つけた port）、`tcp:UNIT_ID`（TXT の unit_id で
-DNS-SD が見つけた probe。describe の unit_id が同じでなければ閉じる）、`usb[:VID:PID[:SERIAL]]`。変更はロックを取り（owner "oep settings"）、終わったら
+`<probe>` は OEP のアドレス `oep://UNIT_ID[?via=経路]`（oep-spec の host ガイド §5.3。via が無ければ USB のデバイス、無ければ
+DNS-SD が見つけた probe。どの経路でも describe の unit_id が同じでなければ閉じる）。unit_id を知らないときは、シリアルの口、
+`tcp://HOST:PORT`、`tcp://HOST`（その host に DNS-SD が見つけた port）、`usb`（ただ 1 つの probe）でもよい。変更はロックを取り（owner "oep settings"）、終わったら
 セッションを閉じる。変更はすぐ効き、`save` の後は再起動しても残る。
 
 ### 走り直す host: 残したセッションの id
@@ -150,7 +152,7 @@ TCP で OEP を運ぶ probe は DNS-SD で見つける（ネットワークの
   `oep` は登録した名前ではないので、別のサービスが `_oep._tcp` を広告しうる: どの instance もまず確かめる（`discovery.verify`、
   すべて同時に、答え 1 つあたり 1 秒、`--verify-timeout`）。TCP でつなぎ、confirm（`OEP!` の答え）と fn 0 の describe を送り、
   describe の unit_id が TXT の unit_id と同じものだけを残す。session は開かない。確かめられないものは、その接続先と言ったことを
-  stderr に警告して外す。`--no-verify` は広告されたものをすべてそのまま並べる。`discovery.find_unit`（つまり `tcp:UNIT_ID`）も
+  stderr に警告して外す。`--no-verify` は広告されたものをすべてそのまま並べる。`discovery.find_unit`（つまり `oep://UNIT_ID?via=net`）も
   同じく確かめ、確かめられない instance は飛ばす。そのあと `open_host` は開いた経路で confirm と describe の unit_id をもう一度
   確かめる。port はいつも SRV
   のもの（決まった port は無い。参照の probe の 7450 は例）。python-zeroconf があれば（`pip install 'oep-client-python[mdns]'`）それで、
@@ -159,7 +161,7 @@ TCP で OEP を運ぶ probe は DNS-SD で見つける（ネットワークの
   アドレスごとに IP_MULTICAST_IF。`discovery.interface_addresses`: ifaddr があればそれ、無ければ Linux は各インターフェースのアドレス、
   ほかは host 名のアドレス）。一度の送信は 1 つのインターフェースからしか出ず（Windows ではよく仮想アダプタ）、別のアダプタの probe には届かない。mDNS は同じリンクの
   中だけ: WSL 2 の既定の NAT、VM、ルーターの向こうからは見つからない。そのときは `tcp://HOST:PORT` で名指す。
-- `tcp:UNIT_ID` はその unit_id で DNS-SD が見つけた probe を開き、describe の unit_id を確かめる（違えば UnitIdMismatch で閉じる）。
+- `oep://UNIT_ID?via=net` はその unit_id で DNS-SD が見つけた probe を開き、describe の unit_id を確かめる（違えば UnitIdMismatch で閉じる）。
   再起動の後は browse し直す（アドレスは変わりうる）。TCP に認証は無い: 信頼するネットワークかトンネルの中で使う（transports §1）。
 - `oep linktest` は TCP では応答を 3 秒待つ（ほかは 0.3 秒）: Wi-Fi の再送でときどき 1〜4 秒止まり、それでも答えは来る。
 
@@ -409,7 +411,7 @@ python -m oep_client.virtual_bench_serve --tcp 0 --announce --profile esp32-v003
 問い合わせの multicast は出ていったインターフェースでこの host に戻り、応答器はすべてのインターフェースで group に入っている。
 multicast の経路が無い host では `--announce-on 127.0.0.1` にし、問い合わせを IP_MULTICAST_IF 127.0.0.1 で送る。並んで動く job は
 `--unit-id` を変えれば分かれる（instance の名前にも port が入る）。コンテナや VM は自分のネットワークの中でだけ答える。
-tests/test_virtual_bench_announce.py がこれを `oep find`、`discovery.find_unit`、`tcp:UNIT_ID`（両方の engine）で試す（同じ process の responder が、OEP でない TCP の
+tests/test_virtual_bench_announce.py がこれを `oep find`、`discovery.find_unit`、`oep://UNIT_ID?via=net`（両方の engine）で試す（同じ process の responder が、OEP でない TCP の
 サービスと違う TXT の unit_id を並べて広告し、確かめでそれが外れることも見る）。multicast が
 戻らない所では skip する。
 

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/README.md

@@ -75,10 +75,11 @@ names starting with `_`, may change. Check probe/client compatibility using the
 from oep_client import core, link, riscv, ch32_flash
 
 hst = link.open_host("/dev/ttyACM0")   # pipelined
-# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the device whose USB serial it is;
-# describe's unit_id must match), "usb" (every device on the project's VID:PID 1209:4F45, each counted once: exactly
-# one -> vendor, then HID, else its CDC port; several -> link.SeveralProbes lists them, name one) /
-# "usb:VID:PID[:SERIAL]" (vendor, then HID). Each is probed first with a
+# an OEP address "oep://<unit id>[?via=usb|bulk|hid|cdc|net|tcp:HOST:PORT|tty:PATH]" (host guide §5.3; without via
+# its USB device, else the probe DNS-SD finds; describe's unit_id must match on any route), or, when the unit id is not
+# known, a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" (every device on the project's VID:PID
+# 1209:4F45, each counted once: exactly one -> vendor, then HID, else its CDC port; several -> link.SeveralProbes lists
+# them, name one). Each is probed first with a
 # confirm only (transports §3): no valid answer -> closed, link.NotOepProbe
 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")
@@ -125,9 +126,9 @@ oep find [--timeout 2] [--json] [--no-verify]  # probes announcing _oep._tcp (ea
 oep linktest <probe> ...                     # --timeout: 0.3 s an answer by default, 3 s over TCP
 ```
 
-`<probe>` is a serial port, `tcp://HOST:PORT`, `tcp://HOST` (the port DNS-SD finds for that host), `tcp:UNIT_ID` (the
-probe DNS-SD finds by its TXT unit_id; describe's unit_id must say the same, else it is closed) or
-`usb[:VID:PID[:SERIAL]]`. A change takes the lock (owner "oep settings") and
+`<probe>` is an OEP address `oep://UNIT_ID[?via=route]` (oep-spec host guide §5.3; without via its USB device, else the
+probe DNS-SD finds; on any route describe's unit_id must say the same, else it is closed) or, when the unit_id is not
+known, a serial port, `tcp://HOST:PORT`, `tcp://HOST` (the port DNS-SD finds for that host) or `usb` (the only probe). A change takes the lock (owner "oep settings") and
 ends the session after it; it takes effect at once and, after `save`, stays over a restart.
 
 ### A host run again: the kept session id
@@ -160,7 +161,7 @@ A probe that serves OEP over TCP is found by DNS-SD (its network settings are th
   (`discovery.verify`, all at once, 1 s per answer, `--verify-timeout`): a TCP connection, confirm (an `OEP!` answer)
   and fn 0's describe, whose unit_id must be the TXT unit_id - no session is opened. One that fails is dropped with a
   warning on stderr naming its endpoint and what it said; `--no-verify` lists every instance as announced.
-  `discovery.find_unit` (and so `tcp:UNIT_ID`) verifies the same way and passes over an instance it cannot verify;
+  `discovery.find_unit` (and so `oep://UNIT_ID?via=net`) verifies the same way and passes over an instance it cannot verify;
   `open_host` then checks confirm and describe's unit_id again on the link it opens. The port
   is always the SRV record's (none is fixed - the reference probe's 7450 is an example). With python-zeroconf installed
   (`pip install 'oep-client-python[mdns]'`) it browses with it (every interface: InterfaceChoice.All), else with a
@@ -169,7 +170,7 @@ A probe that serves OEP over TCP is found by DNS-SD (its network settings are th
   installed, else each interface's address on Linux, else the host name's addresses) - one send leaves by one
   interface only, on Windows often a virtual adapter's, and a probe on another adapter never hears it. mDNS stays on the local link: from WSL 2's
   default NAT network, a VM or across a router nothing is found - name the probe as `tcp://HOST:PORT`.
-- `tcp:UNIT_ID` opens the probe DNS-SD finds by that unit_id and checks describe's (UnitIdMismatch, closed, otherwise);
+- `oep://UNIT_ID?via=net` opens the probe DNS-SD finds by that unit_id and checks describe's (UnitIdMismatch, closed, otherwise);
   after a restart it browses again (the address may change). TCP has no authentication: use it on a trusted network or
   a tunnel (transports §1).
 - `oep linktest` waits 3 s an answer over TCP (0.3 s elsewhere): Wi-Fi retransmissions stall answers for 1-4 s now and
@@ -470,6 +471,6 @@ The query's multicast loops back to this host on the interface it left by, and t
 every interface. A host with no multicast route needs `--announce-on 127.0.0.1` and the query sent with
 IP_MULTICAST_IF 127.0.0.1. A different `--unit-id` per job keeps parallel jobs apart (the port is in the instance
 name too). A container or VM answers only on its own network. tests/test_virtual_bench_announce.py does this with
-`oep find`, `discovery.find_unit` and `tcp:UNIT_ID` (both engines) - with in-process responders announcing a non-OEP
+`oep find`, `discovery.find_unit` and `oep://UNIT_ID?via=net` (both engines) - with in-process responders announcing a non-OEP
 TCP service and a wrong TXT unit_id beside it, which the verify drops - skipped where multicast does not loop back.
 

oep_client_python-0.0.41/docs/spec-follow-notes.ja.md

@@ -0,0 +1,10 @@
+# 仕様追従で見つけた実装上の負担
+
+実装を oep-spec に追従させるときに、実装がかなり不便だと分かった仕様の規則を記録する。仕様の見直しの材料であり、規範ではない。
+仕様に入ったもの、取り下げたものは消し、今開いているものだけを置く。単に作業量が多いだけのもの、実装側の設計で解消できるものは載せない。
+
+| # | 条項 | 不便な点 | 影響 | 代案 |
+|---|---|---|---|---|
+| 1 | core §2.3（後に来た同じ tag も検証の対象） | 要求の中で、繰り返さない既知の tag が 2 回来たとき、使わない 2 つ目以降の値まで、値域と対応の有無を op ごとに検証しなければならない。共通の TLV 読み取りは長さしか見られないので、検証を副作用のある処理から分け、同じ検証をすべてのコピーへ当てる作りが要る | probe（各 op）、仮想ベンチ | 要求の中の、繰り返さない既知の tag の重複を malformed にする（critical の bit を除いた番号で判定する。繰り返す tag と未知の tag は対象外）。今は有効な重複を新たに断る変更になる |
+| 2 | core §2.2 / §2.3（応答・出来事・データの読み手の規則） | 送る側に「繰り返さない tag を応答で 2 度送らない」の義務が無いので、host は応答の TLV を読むすべての所で、最初のコピーを使い、長さの違う値を壊れたものとして扱う防御を持つ。Python は `catalog.first_value` / `first_fixed` に集めた | host、検査器 | probe は、応答・出来事・データで、繰り返さない tag を 2 度送らないと定め、検査器で確かめる。読み手の規則は変えない（要求の側の #1 とは別に書く） |
+| 3 | console §2、core §9（stream はセッションのもので、セッションの終わりで解放する） | 1 回の実行ごとにセッションを開いて閉じる host（`oep` の各コマンド、試験のプロセス）は、コマンドの間に target が出した出力（起動直後の行など）を拾えない。console の素通し（core §13 の項目）は、セッションの無い間の出力をシリアルの口へ流すが、次のセッションで読み返すことはできない | host（CLI、試験） | セッションの無い間も受け続け、次のセッションで読める「保持の stream」を任意の機能として定める。閉じた stream の番号を使い回さない規則（core §9）とは別の資源にする |

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/docs/testing-policy.ja.md

@@ -211,9 +211,9 @@ log、readback、waveform、capture layout/rate、時刻不確かさ、双方の
 
 ## 11. 調査した正本と実装
 
-- [OEP 適合](https://github.com/Open-Embedded-Probe/oep-spec/blob/main/docs/conformance.ja.md)、[debug wire と connection](https://github.com/Open-Embedded-Probe/oep-spec/blob/main/interfaces/oep-if-debug.ja.md)、[probe config](https://github.com/Open-Embedded-Probe/oep-spec/blob/main/interfaces/oep-if-probe-config.ja.md)。規範の正本は oep-spec に置き、この方針では新しい通信規則を定義しない。
+- [OEP 適合](https://github.com/Open-Embedded-Probe/oep-spec/blob/main/docs/conformance.ja.md)、[debug wire と connection](https://github.com/Open-Embedded-Probe/oep-spec/blob/main/interfaces/oep-if-debug.ja.md)、[設定（core §13）](https://github.com/Open-Embedded-Probe/oep-spec/blob/main/docs/oep-core.ja.md#13-設定任意)。規範の正本は oep-spec に置き、この方針では新しい通信規則を定義しない。
 - [Python の pins 探索](https://github.com/Open-Embedded-Probe/oep-client-python/blob/main/src/oep_client/pins.py)、[実機試験](https://github.com/Open-Embedded-Probe/oep-client-python/blob/main/tests/hw/README.ja.md)、[個体表](https://github.com/Open-Embedded-Probe/oep-client-python/blob/main/tests/hw/boards.py)。
-- [probe DebugPort](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/src/OepTarget.h)、[Config](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/src/OepConfig.h)、[実装制約](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/docs/implementation-limits.ja.md)、[C++ 単体試験](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/tests/host/run.sh)、[CI](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/.github/workflows/tests.yml)。
+- [probe DebugPort](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/src/OepTarget.h)、[Settings](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/src/OepSettings.h)、[実装制約](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/docs/implementation-limits.ja.md)、[C++ 単体試験](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/tests/host/run.sh)、[CI](https://github.com/Open-Embedded-Probe/oep-probe-arduino/blob/main/.github/workflows/tests.yml)。
 - [ch32rv の OEP と broker](https://github.com/ch32-riscv-ug/ch32rv/blob/main/docs/oep-host.ja.md)、[仮想 OEP](https://github.com/ch32-riscv-ug/ch32rv/blob/main/crates/oep/tests/virtual_bench.rs)、[仮想環境取得](https://github.com/ch32-riscv-ug/ch32rv/blob/main/crates/oep/tests/virtual_bench/uv.rs)、[flash E2E](https://github.com/ch32-riscv-ug/ch32rv/blob/main/cli/tests/oep_flash.rs)、[monitor E2E](https://github.com/ch32-riscv-ug/ch32rv/blob/main/cli/tests/oep_monitor.rs)。
 - [ArduinoCore の計画](https://github.com/ch32-riscv-ug/ArduinoCore-CH32RV/blob/main/tests/TEST_PLAN.ja.md)、[実装との照合](https://github.com/ch32-riscv-ug/ArduinoCore-CH32RV/blob/main/docs/test-coverage.ja.md)、[現在の構成 loader](https://github.com/ch32-riscv-ug/ArduinoCore-CH32RV/blob/main/tests/harness/bench.py)、[TinyUSB の現状](https://github.com/ch32-riscv-ug/ArduinoCore-CH32RV/blob/main/libraries/TinyUSB/README.ja.md)。
 - [pytest Arduino 基礎](https://github.com/tanakamasayuki/pytest-embedded-arduino-cli/blob/main/TESTING_BASICS.ja.md)、[詳細と peer の原則](https://github.com/tanakamasayuki/pytest-embedded-arduino-cli/blob/main/TESTING_ADVANCED.ja.md)、[peer lifecycle の例](https://github.com/tanakamasayuki/pytest-embedded-arduino-cli/blob/main/examples/12_peer_host_core/README.ja.md)。

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.40"
+version = "0.0.41"
 description = "Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a virtual bench"
 readme = "README.md"
 license = "MIT"
@@ -24,6 +24,7 @@ dependencies = ["pyserial>=3.5", "pyusb>=1.3", "tomli>=2; python_version < '3.11
 usb-async = ["libusb1>=3"]   # queued asynchronous IN transfers: streaming near the USB HS ceiling
 hid = ["hidapi>=0.14"]      # the vendor HID way in through the OS HID driver (Windows without WinUSB, Linux hidraw)
 mdns = ["zeroconf>=0.131"]   # DNS-SD browsing through python-zeroconf (oep find, tcp:UNIT_ID); without it a minimal query of its own
+acquire = ["numpy>=2.0"]   # acquire: streams and capture format 1 blocks put together at once
 
 [project.scripts]
 oep = "oep_client.__main__:main"

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.40"
+__version__ = "0.0.41"

{oep_client_python-0.0.40 → oep_client_python-0.0.41}/src/oep_client/__main__.py

@@ -20,8 +20,8 @@
                                            host's time - the reading with the shortest round trip of n)
   oep restart <probe> [--reopen-s S]      (oep.probe.restart: the probe restarts; waits until it is back, its new boot_id)
 
-<probe>: a serial port, tcp://HOST[:PORT] (no port: the one DNS-SD finds), tcp:UNIT_ID (found by DNS-SD) or
-usb[:VID:PID[:SERIAL]]. A change takes the lock (owner "oep settings") and
+<probe>: an OEP address, oep://UNIT_ID[?via=usb|bulk|hid|cdc|net|tcp:HOST:PORT|tty:PATH] (host guide §5.3), or, for a
+probe whose unit_id is not known, a serial port, tcp://HOST[:PORT] (no port: the one DNS-SD finds) or usb (the only one). A change takes the lock (owner "oep settings") and
 ends the session after it; it takes effect at once, and stays over a restart only after `save` (or --save).
 """
 
@@ -47,7 +47,7 @@ def _open_host(target: str, **kw):
         return link.open_host(target, **kw)
     except (OSError, ValueError, ImportError, host.OepError) as e:
         why = " ".join(str(e).split()).rstrip(".") or type(e).__name__
-        hint = f" Hint: {USB_HINT}." if isinstance(e, FileNotFoundError) and (target == "usb" or target.startswith("usb:")) \
+        hint = f" Hint: {USB_HINT}." if isinstance(e, FileNotFoundError) and (target == "usb" or target.lower().startswith("oep://")) \
             else ""
         raise SystemExit(f"oep: cannot open {target}: {why}.{hint}") from None
 
@@ -81,7 +81,7 @@ def main(argv=None) -> int:
     sp.add_argument("--baud", type=int, default=link.BASE_BAUD, help="the boot speed (default 115200)")
     sp.add_argument("--json", action="store_true")
     lt = sub.add_parser("linktest", help="measure the link: traffic patterns at rates the host asks for, what breaks")
-    lt.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID]")
+    lt.add_argument("probe", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb")
     lt.add_argument("--rates", default="", help="comma-separated rates to switch to with port_speed and measure at "
                     "(each on its own; 0 or 'now' = the speed in force). Default: only the speed in force")
     lt.add_argument("--patterns", default="in,out,duplex", help="in (probe->host), out (host->probe), duplex")
@@ -96,7 +96,7 @@ def main(argv=None) -> int:
     lt.add_argument("--json", action="store_true", help="one JSON object per cell")
     pn = sub.add_parser("pins", help="find where a target is wired: classify the channels, scan the wire, find the "
                         "reset line, suggest labels (writes nothing without --save)")
-    pn.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]")
+    pn.add_argument("probe", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb")
     pn.add_argument("--power", type=int, help="the gpio channel that powers the target: switched off, then on, to "
                     "see which channels follow it (never touched without this)")
     pn.add_argument("--exclude", default="", help="channels never to read, scan or hold, comma-separated")
@@ -116,11 +116,11 @@ def main(argv=None) -> int:
                     "<name>.swio), <name>.nrst, <name>.power_hi; the probe is then opened as oep://<unit_id>/<name>")
     pn.add_argument("--json", action="store_true", help="the report as JSON (the steps' lines go to stderr)")
     ck = sub.add_parser("clock", help="the probe's clock (fn 0 clock, core §7.6) against this host's: lock-free")
-    ck.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]")
+    ck.add_argument("probe", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb")
     ck.add_argument("-n", type=int, default=8, help="readings; the one with the shortest round trip is kept (default 8)")
     ck.add_argument("--json", action="store_true")
     rs = sub.add_parser("restart", help="restart the probe (oep.probe.restart, optional) and wait until it is back")
-    rs.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]")
+    rs.add_argument("probe", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb")
     rs.add_argument("--force", action="store_true", help="take the lock from its holder")
     rs.add_argument("--reopen-s", type=float, default=0.0, metavar="S",
                     help="when the probe is not back within its restart_max_ms, open it again for up to S more seconds "
@@ -138,7 +138,7 @@ def main(argv=None) -> int:
     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("--virtual", choices=sorted(virtual_bench.PROFILES), help="an in-process virtual bench (no hardware)")
-    src.add_argument("--port", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID] (lock-free reads only)")
+    src.add_argument("--port", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb (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")