oep-client-python 0.0.27__tar.gz → 0.0.28__tar.gz

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.0.28
+- (EN) `oep pins` suggests the lines it found as probe.config labels (`<slot>.nrst`, `<slot>.power_hi`, host-development-guide §8.1) and an output idle for the power channel, instead of a slot reset_channel (not adopted: oep-spec v1-open-proposals §10); `--save` writes the slot and the labels.
+- (JA) `oep pins` は見つけた線を probe.config の label（`<slot>.nrst`、`<slot>.power_hi`、host 開発ガイド §8.1）と、電源の channel の出力の idle として案内する（スロットの reset_channel は採らなかった: oep-spec v1-open-proposals §10）。`--save` はスロットと label を書く。
+- (EN) Idle modes 3 / 4 (oep-spec 5013ffb / 7b3c319; registry synced, hash 050ffee525722713: idle_mode `output_low` 3, `output_high` 4). `config.Idle` takes `output-low` / `output-high` (`output_low` / `output_high` too, normalised to the hyphen form like `pull-up`), and `oep config idle <probe> <ch> output-high` offers them. `config.find_line(hst_or_items, name, slot=None)` finds a target's labelled line (`nrst`, `power_hi`, `power_lo`, `config.LINE_NAMES`; host-development-guide §8.1): `<slot>.<name>` first, then the bare name only while the settings hold at most one slot; with several slots and no slot given, or one label on two channels, it raises `config.AmbiguousLine` listing the candidates; None when there is none. The fake: an output idle drives its level while the channel is free, refused unsupported on `Endpoint.input_only` channels; every release (plan_release, a channel leaving a replaced plan - it used to keep the old channels' gpio modes - the lease lapse, force) goes to the idle state, and a gpio channel in both the old and the new plan keeps its state and drive; a gpio line a plan takes keeps that state until its first set (a read sees the idle level); at boot the idle states are applied before the plans and the at-boot attach (they came after the attach).
+- (JA) idle の mode 3 / 4（oep-spec 5013ffb / 7b3c319。registry を写し直した、hash 050ffee525722713: idle_mode の `output_low` 3、`output_high` 4）。`config.Idle` が `output-low` / `output-high` を受ける（`output_low` / `output_high` も。`pull-up` と同じくハイフンの形にそろえる）。`oep config idle <probe> <ch> output-high` でも選べる。`config.find_line(hst_or_items, name, slot=None)` は target の label の付いた線（`nrst`、`power_hi`、`power_lo`、`config.LINE_NAMES`。host-development-guide §8.1）を探す: `<スロット>.<名前>` を先に、無ければ名前だけ（設定のスロットが 1 つ以下のときだけ）。スロットが 2 つ以上で slot を渡さないときと、1 つの label が 2 つの channel にあるときは、候補を並べた `config.AmbiguousLine` を上げる。無ければ None。fake: 出力の idle は channel が空いている間その level で駆動し、`Endpoint.input_only` の channel では unsupported で断る。解放はどの道でも（plan_release、置き換えた plan から外れる channel - これまでは古い channel の gpio の mode が残っていた - lease の失効、force）空きの状態に戻り、古い plan にも新しい plan にもある gpio の channel は状態と駆動を保つ。plan が取った gpio の線は最初の set までその状態を保つ（read は idle の level を見る）。起動では idle を plan と at boot の attach より先に掛ける（これまでは attach の後だった）。
+- (EN) `oep pins <probe> [--power CH] [--exclude CH,...] [--wire swio|rvswd|swd] [--steps ...] [--save] [--json]` (module `pins`, `PinFinder`): finds where a target is wired on a probe whose pins the host chooses. Steps: classify every gpio channel from 16 reads under pull-up, both pulls, then pull-down (floating / pulled-up / driven-high / driven-low / active; with `--power` the target is read switched off first and the channels that read otherwise "follow power"); hold each floating / pulled-up channel low (open drain) while an active channel is watched (the watch lasts 3 x the longest lull of the running activity, 0.3-1 s); scan the wire over the floating / pulled-up channels only (rvswd / swd: pairs, at most 600); attach (halt), name the family by target_id and read a CH32V00x's option bytes (NRST on or off; read only); confirm the reset line by attach under reset (dpc = reset vector); print a suggested slot (`reset_channel` as a comment while `config.Slot` has none) and write it only with `--save`. Driven / active channels are never driven, scanned or held, the power channel is touched only with `--power`, every plan is released at the end, the run stays under 60 s. A new gpio plan lets every pin of the old one go first (the power channel too), so with `--power` each new plan is followed by a clean power cycle. On the ESP32-P4 with a CH32V003 (power GPIO5): SWIO 19 and NRST 4 found untold in 7-8 s, 6 runs of 6; the idle-high UART (22 / 23) is classified driven and left alone, the app's output 21 active.
+- (JA) `oep pins <probe> [--power CH] [--exclude CH,...] [--wire swio|rvswd|swd] [--steps ...] [--save] [--json]`（モジュール `pins`、`PinFinder`）: ピンを host が選ぶ probe で、target がどこにつながっているかを探す。段: gpio のすべての channel を pull-up、両方の pull、pull-down の順に 16 回ずつ読んで分ける（floating / pulled-up / driven-high / driven-low / active。`--power` では先に target の電源を切って読み、違って読めた channel を「電源に従う」とする）。floating / pulled-up の channel を 1 本ずつオープンドレインで low に保ち、active の channel を見る（見る長さは走っている時の最長の静かな間の 3 倍、0.3〜1 秒）。floating / pulled-up の channel だけで線を scan する（rvswd / swd は組で 600 組まで）。attach（halt）して target_id で系統を見て、CH32V00x なら option bytes で NRST の有無を読む（読むだけ）。リセットをかけながらの attach（dpc = リセットのベクタ）でリセットの線を確かめる。スロットの行を勧め（`config.Slot` に無い間 `reset_channel` はコメント）、`--save` のときだけ書く。driven / active の channel は駆動も scan も保持もしない、電源の channel は `--power` のときだけ触る、最後に plan をすべて解く、全体は 60 秒以内。gpio の plan を新しくすると前の plan のピンが（電源の channel も）いったん離れるので、`--power` では新しい plan のたびにきれいに電源を入れ直す。ESP32-P4 と CH32V003（電源 GPIO5）で、SWIO 19 と NRST 4 を指定なしで 7〜8 秒で見つけた（6 回中 6 回）。idle-high の UART（22 / 23）は driven として触らず、アプリの出力 21 は active。
+- (EN) `targets`: what the host knows per target family in one table, `FAMILIES` (wire, target_id match on the WCH DMI 0x7F value, reset vector, an option-byte NRST reader, max_speed / idle_clock, notes): ch32v00x (swio, ids 0x002-0x007 in the top 12 bits, `v00x_nrst`: 0x1FFFF800 word0 USER bits[4:3] = RST_MODE, 11 = PD7 is a GPIO), ch32x035 (rvswd, 0x035, idle_clock high), ch32l103 (rvswd, 1 MHz, idle_clock low; id not recorded), ch32v203 (idle_clock low; id not recorded). `identify(target_id)`, `by_name()`, `describe_id()`. oep-spec docs/target-scan-notes.ja.md records the sources.
+- (JA) `targets`: host が target の系統ごとに知っていることを 1 つの表 `FAMILIES` に（線、WCH DMI 0x7F の値での target_id の照合、リセットのベクタ、NRST を option で読む関数、max_speed / idle_clock、注）: ch32v00x（swio、上位 12 ビットが 0x002〜0x007、`v00x_nrst`: 0x1FFFF800 の word0 の USER bits[4:3] = RST_MODE、11 = PD7 は GPIO）、ch32x035（rvswd、0x035、idle_clock high）、ch32l103（rvswd、1 MHz、idle_clock low。id は未記録）、ch32v203（idle_clock low。id は未記録）。`identify(target_id)`、`by_name()`、`describe_id()`。出典は oep-spec の docs/target-scan-notes.ja.md。
+- (EN) `riscv.Wire.find_reset_line(..., pins=None)`: it returned [] on the ESP32-P4 with the CH32V003's real NRST among the candidates. Root cause: it attached without pins; on a wire whose pins the host chooses (role_channels) such an attach only joins the wire's one live connection, and the first try's detach closed that connection, so every later attach was rejected unavailable - and a rejection was taken for "not a reset line" and skipped. Now `pins` is passed to every attach (None: the pins of the wire's one live connection), a connection that was there before the search is left open, only unsupported or an unavailable naming the channel skips it, any other rejection is raised. On the P4: [4] over 48 candidates with tries=3 in 4.2 s, with and without a plain attach first. Hold time is not the cause: an attach under reset through 4 stopped at dpc 0 with 1, 2, 5, 10 and 20 ms holds, 3 of 3 each (RST_MODE 10, the 12 ms window).
+- (JA) `riscv.Wire.find_reset_line(..., pins=None)`: ESP32-P4 と CH32V003 で、本物の NRST が候補にあるのに [] を返した。原因: pins を付けずに attach していた。ピンを host が選ぶ線（role_channels）では、pins の無い attach はその線の唯一の生きた接続に加わるだけで、1 回目の試しの detach がその接続を閉じた後は、どの attach も unavailable で断られ、断りを「リセットの線ではない」と読んで飛ばしていた。今は毎回の attach に `pins` を付け（None ならその線の唯一の生きた接続のピン）、探す前からあった接続は閉じない。飛ばすのは unsupported と、その channel を名指しした unavailable だけで、ほかの断りは例外にする。P4 で 48 候補、tries=3 で [4]（4.2 秒）。先に普通の attach をしてあってもなくても同じ。保持時間は原因ではない: 4 でリセットをかけながらの attach は 1、2、5、10、20 ms の保持でどれも 3 回中 3 回 dpc 0（RST_MODE 10、12 ms の窓）。
+- (EN) The fake: `Endpoint.gpio_world(channel, mode)` (a test hook: the level an input-mode read sees, from the lines outside) and `FakeTarget.reset_line` (an attach under reset through any other channel halts where the hart ran, off the vector). `tests/test_pins.py` runs `oep pins` against a P4-shaped profile with a V003-like world.
+- (JA) fake: `Endpoint.gpio_world(channel, mode)`（試験の hook: 入力の mode の読みが見る外の線のレベル）と `FakeTarget.reset_line`（ほかの channel でリセットをかけながら attach すると、hart は走っていた所で止まり、ベクタに来ない）。`tests/test_pins.py` が P4 の形の profile と V003 らしい外の線で `oep pins` を動かす。
+- (EN) Registry synced to oep-spec 75ca9ee (hash 3861100e11fb3b22): oep.fixture.i2c-target describe `max_stretch_us` (0x41, u32). The fake follows fixture §3 / §4 as 75ca9ee closed them: an i2c-target / spi-target plan holds each role exactly once on distinct channels (a missing role, a role twice or two roles on one channel -> malformed, before held_by_settings); the mode-1 wait survives a frame (armed stays 1 until the next arm_rx / reset / configure / plan release); an address-only write counts nothing in any mode; read_rx in state 0 is unavailable cause 6 on both targets; a 0-bit SPI transfer (`spi_transfer(..., bits=0)`, or empty MOSI) counts nothing and the arm keeps waiting, and the queued data is bits / 8 rounded up, capped at length. `p4-x035` declares max_stretch_us 100000 and stretch refuses more as unsupported (the fixed `endpoint.STRETCH_MAX_US` is gone); `esp32-v003` (no features bit1) declares none. `fixture.I2cTarget` gains `max_length`, `max_clock_hz`, `features`, `queue_depth` and `max_stretch_us` (None when not declared; features 0), `fixture.SpiTarget` the same but max_stretch_us, read once from describe. `tests/hw` i2c_target records `declared.max_stretch_us`.
+- (JA) registry を oep-spec 75ca9ee に合わせた（hash 3861100e11fb3b22）: oep.fixture.i2c-target の describe に `max_stretch_us`（0x41、u32）。fake を 75ca9ee で埋まった fixture §3 / §4 に合わせた: i2c-target / spi-target の plan は各 role をちょうど 1 つずつ別々の channel で持つ（role が欠ける、2 つある、2 つの role が同じ channel は malformed。held_by_settings より先）。mode 1 の待ちはフレームを受けても終わらない（次の arm_rx / reset / configure / plan を解くまで armed は 1）。アドレスだけの書き込みはどの mode でも何も数えない。state 0 の read_rx は両 target で unavailable cause 6。0 ビットの SPI 転送（`spi_transfer(..., bits=0)`、または MOSI が空）は何も数えず arm は待ち続ける。積む data は bits / 8 の切り上げで length で止める。`p4-x035` は max_stretch_us 100000 を宣言し、それを超える stretch は unsupported（固定の `endpoint.STRETCH_MAX_US` は無くした）。`esp32-v003`（features bit1 なし）は宣言しない。`fixture.I2cTarget` に `max_length`、`max_clock_hz`、`features`、`queue_depth`、`max_stretch_us`（宣言が無ければ None、features は 0）、`fixture.SpiTarget` に max_stretch_us 以外の同じものを足した（describe から 1 回読む）。`tests/hw` の i2c_target は `declared.max_stretch_us` を記録する。
+- (EN) `tests/hw` spi_target: with no controller wired, an arm must stay armed (0 transactions, 0 errors) and a second arm is refused unavailable, as fixture §4 says. The check was loosened for phantom CS-edge transactions the probe counted; oep-probe-arduino a3dcabd stopped counting a CS edge without SCK. ATOM with the probe at ac80e07: 12 passed.
+- (JA) `tests/hw` の spi_target: コントローラーをつないでいないとき、arm は armed のまま（transactions 0、errors 0）で、2 回目の arm は unavailable で断られること（fixture §4 のとおり）。probe が CS の縁だけで数えていた幻の転送のために緩めていた確かめを元に戻した（oep-probe-arduino a3dcabd で SCK の無い CS の縁を数えなくなった）。probe ac80e07 の ATOM で 12 passed。
+- (EN) The fake probe runs `oep.fixture.i2c-target` and `oep.fixture.spi-target` (oep-spec oep-if-fixture §3 / §4); it only declared them before, so `tests/hw` `i2c_target` / `spi_target` failed on `fake-esp32-v003` and now pass. The plan takes SDA / SCL and SCK / MOSI / MISO / CS with the gpio / uart checks, plus role_channels per role and an exact channel_group (core §7.4); configure / arm_rx / arm / preload_tx / read_rx (TLV ns) / status (lock-free) / reset / stretch (features bit1 only, else unknown_operation) with the refusals in core §4.3's order; a plan change puts the target back to state 0. Declared: `p4-x035` i2c max_length 128, max_clock_hz 1 MHz, features 0b11, queue_depth 8; spi max_length 64, 3 MHz, features 0b1 (LSB first), queue_depth 8. `esp32-v003` i2c 16, 100 kHz, features 0b01, queue_depth 4; spi (two channel_groups) 32, 3 MHz, features 0, queue_depth 4. No bus controller: test hooks `Endpoint.i2c_write` / `i2c_read` / `spi_transfer` run one transaction (queued, consumed, overflow, not armed - transactions and errors counted). `fake.with_stand_in(probe)` adds the fn with the stand-in operations the session tests used the esp32-v003 i2c-target for.
+- (JA) 偽の probe が `oep.fixture.i2c-target` と `oep.fixture.spi-target`（oep-spec oep-if-fixture §3 / §4）を動かす。これまでは宣言だけで、`fake-esp32-v003` の `tests/hw` の `i2c_target` / `spi_target` は落ちていた。今は通る。plan は SDA / SCL と SCK / MOSI / MISO / CS を、gpio / uart と同じ確かめに、role ごとの role_channels と channel_group の完全一致（core §7.4）を足して受ける。configure / arm_rx / arm / preload_tx / read_rx（TLV ns）/ status（ロック不要）/ reset / stretch（features bit1 のときだけ。ほかは unknown_operation）。断りは core §4.3 の順。plan が変わると target は state 0 に戻る。宣言: `p4-x035` の i2c は max_length 128、max_clock_hz 1 MHz、features 0b11、queue_depth 8。spi は 64、3 MHz、features 0b1（LSB 先）、queue_depth 8。`esp32-v003` の i2c は 16、100 kHz、features 0b01、queue_depth 4。spi（channel_group 2 つ）は 32、3 MHz、features 0、queue_depth 4。バスの controller は無い: 試験の hook `Endpoint.i2c_write` / `i2c_read` / `spi_transfer` が 1 回のトランザクションを起こす（積む、取り出す、あふれ、未 arm。transactions と errors を数える）。セッションの試験が esp32-v003 の i2c-target を代わりに使っていた仮の操作の fn は `fake.with_stand_in(probe)` が足す。
+- (EN) `tests/hw` covers the interfaces it did not yet, each skipping when the probe does not list it, after `uart` and before `port_speed`: `capture` (oep.fixture.logic: a one-shot at the lowest declared rate over 10 ms on the two free channels, pulled up then down through fixture gpio planned on the same pins - all ones, then all zeros; sample count, timing within the declared uncertainty, generation +1 per start), `capture_analog` (one-shot on a free ADC channel, widest frontend; the pull bands are judged only when the probe lets gpio share the pin), `capture_group` (logic + analog bound and started together, both read back, the tracks' offsets from the group's start_ns), `i2c_target` / `spi_target` (configure, status, a preloaded queue / an armed transaction, reset, release - no bus controller, so floating-line glitches are recorded, not judged), `console` (with `OEP_HW_TARGET`: open with mechanism dmseq on the wire connection, read 1 s, close). `OEP_HW_ANALOG`, `OEP_HW_I2C`, `OEP_HW_SPI` name channels. ATOM, firmware 0.0.27: logic 400 kHz w 8, 4000 / 4000 ones then 0 / 4000 on both pins, done 24 ms after start for a 10 ms window, 4 KB read in 0.38 s; analog 20 kHz s 16 b 12, the floating pin at 2.8 / 4095; the group's tracks start 25 µs (logic) and 516 µs (analog) after the group; the analog refuses to share its pin with gpio (unavailable, as oep-if-capture §1.2 allows) and an idle pull-up on it reads only 137 mV mean once the ADC owns the pad; the SPI target counts 1-2 phantom transactions on its floating SCK / CS right after an arm.
+- (JA) `tests/hw` に、まだ無かった interface の試験を足した（probe が list に出さなければ skip。`uart` の後、`port_speed` の前）: `capture`（oep.fixture.logic: 空き 2 チャネルで、同じピンに plan した fixture gpio で pull-up → pull-down し、宣言の最低のレートで 10 ms のワンショット。全部 1、次に全部 0。サンプル数、宣言の不確かさの内の時間、start ごとに世代 +1）、`capture_analog`（空きの ADC チャネルでいちばん広い frontend のワンショット。pull の帯は probe が gpio とピンを共有させるときだけ判定）、`capture_group`（ロジックとアナログを bind して一緒に start、両方読み出し、組の start_ns からの各トラックのずれ）、`i2c_target` / `spi_target`（configure、status、preload の列 / arm した転送、reset、release。バスに controller は無いので浮いた線のグリッチは記録して判定しない）、`console`（`OEP_HW_TARGET` のとき: 線の connection に mechanism dmseq で open、1 秒読む、close）。`OEP_HW_ANALOG`、`OEP_HW_I2C`、`OEP_HW_SPI` でチャネルを指定できる。ATOM、firmware 0.0.27: ロジック 400 kHz w 8、両ピンとも 4000 / 4000 が 1、次に 0 / 4000、10 ms の窓に対し start の 24 ms 後に done、4 KB の読み出しに 0.38 秒。アナログ 20 kHz s 16 b 12、浮いたピンは 2.8 / 4095。組のトラックは組の 25 µs（ロジック）と 516 µs（アナログ）後に始まる。アナログは gpio とのピンの共有を断り（unavailable。oep-if-capture §1.2 が許す）、その上の idle の pull-up は ADC がパッドを持つと平均 137 mV しか読めない。SPI の target は arm の直後、浮いた SCK / CS で 1〜2 の幻の転送を数える。
+- (EN) `tests/hw` port_speed: the run fails only when no candidate passes; a candidate that fails the guide's verdict is recorded (`passed_rates` / `failed_rates`). The ATOM's bridge puts 1500000 over the threshold in some runs (11-14 % on one flow against a 2-5 % baseline) while 500000 passes every time - a fact about that bridge, not about the probe or the client.
+- (JA) `tests/hw` の port_speed: 通る候補が 1 つも無いときだけ落とす。ガイドの判定に落ちた候補は記録に残す（`passed_rates` / `failed_rates`）。ATOM の変換は 1500000 が回によって閾値を超え（基準 2〜5 % に対し 1 つの流し方で 11〜14 %）、500000 は毎回通る。probe や client ではなく変換の性質。
+
 ## 0.0.27
 - (EN) `tests/hw` port_speed verdict follows the host guide §7.3.2: a one-at-a-time cell at a raised rate fails only when broken + lost ≥ 3 and its ratio is over max(2 × the boot-speed ratio of the same flow, 5 % `OEP_HW_ERROR_MAX`) - the absolute 1 % failed the CH340 jig on bursts the boot speed shows too. Results with the probe 5bafb92 (port_speed handshake per core §3.5, block length) on the ATOM, the V003 jig (SWIO) and the X035 jig (DFU, RVSWD): all pass.
 - (JA) `tests/hw` の port_speed の判定を host 開発ガイド §7.3.2 に合わせた: 上げた速さの 1 つずつの条件で、broken + lost が 3 以上かつ割合が max(起動時の速さの同じ流し方の割合 × 2, 5 %（`OEP_HW_ERROR_MAX`）) を超えたときだけ落とす（絶対の 1 % は、起動時の速さにもある CH340 のまとまった落ちで治具を落としていた）。probe 5bafb92（core §3.5 の握手、block 長）での結果: ATOM、V003 治具（SWIO）、X035 治具（DFU、RVSWD）すべて pass。

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.27
+Version: 0.0.28
 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
@@ -59,7 +59,9 @@ oep-client-python X.Y.Z (until the v1 freeze every release may break the wire; t
 | `host` | requests and results, the session id and the lock, `call()` (raises unless it worked), pipelining, the errors (`OepError` / `Rejected` / `Failed`; `Expired` when the lease lapsed - the session is never re-opened behind the caller's back, `Host.epoch` moves) |
 | `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 (with the probe's `boot_id`), the probe's describe (declarations only, cached per boot: labels, the transport list, `max_op_ms`), taking the lock (`take`), the pin plan, the `Interface` base |
-| `riscv` | `oep.wire.rvswd` / `oep.wire.swio` (scan, attach - `max_speed` always sent, `reset=(channel, hold_ms)` for an attach under reset -, detach, connections), `oep.target.riscv-dm` (answers count their values; `RunResult.not_halted`), finding the reset line, attach through GPIO |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio` (scan, attach - `max_speed` always sent, `reset=(channel, hold_ms)` for an attach under reset -, detach, connections), `oep.target.riscv-dm` (answers count their values; `RunResult.not_halted`), finding the reset line (`find_reset_line(candidates, pins=...)`), attach through GPIO |
+| `targets` | what the host knows per target family, in one table (`FAMILIES`: wire, target_id match, reset vector, option-byte NRST reader, max_speed / idle_clock); `identify(target_id)` |
+| `pins` | `oep pins`: classify the channels, hold-low search, scan, identify, confirm the reset line, suggest a slot (`PinFinder`) |
 | `console` | `oep.target.console` (position streams: read answers carry their length, marks are `time_ns`, the lock-free `streams()` list) and `ConsoleIO`, read as bytes |
 | `fixture` | `oep.fixture.gpio` / `uart` (its stream is the plan's; `status()`) / `i2c-target` / `spi-target` (revision 1) |
 | `config` | `oep.probe.config` (slots, binds, plan / label / idle / uart items, get / set / unset / save / erase; `describe()` = the declarations, `state()` = the live storage / slot / bind state; `hash_of(items)` = the probe's hash) |
@@ -103,6 +105,7 @@ oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
 oep config uart <probe> oep.fixture.uart 115200 --format 8N1   # applied whenever that UART's plan has RX or TX
 oep config save <probe>                      # kept over a restart (also: remove = unset, erase)
 oep speed <probe> 1500000,921600,500000      # port_speed: try faster rates on a UART bridge, print the report (below)
+oep pins <probe> --power 5 --wire swio       # where the target is wired: debug pins, reset line, a slot (below)
 ```
 
 `<probe>` is a serial port, `tcp://HOST:PORT` or `usb[:VID:PID[:SERIAL]]`. A change takes the lock (owner "oep config") and
@@ -110,6 +113,60 @@ ends the session after it; it takes effect at once and, after `save`, stays over
 
 A run on hardware: ArduinoCore-CH32's `tests/manual/oep_smoke/` (`oep_smoke.py`, `oep_probe_checks.py`).
 
+## Finding the pins (`oep pins`)
+
+`oep pins <probe> [--power CH] [--exclude CH,...] [--wire swio|rvswd|swd] [--steps ...] [--save] [--json]` finds where a
+target is wired to a probe whose pins the host chooses. Each step says what it did; the whole run stays under a minute and
+every plan is released at the end. The procedure and its reasons are in oep-spec's host development guide (「ピンの探し方
+（参考）」); what each target family needs is in one table, `targets.FAMILIES` (wire, reset vector, the option-byte reader
+for the reset line, max_speed / idle_clock), which oep-spec `docs/target-scan-notes.ja.md` records the sources of.
+
+1. **classify**: every channel `oep.fixture.gpio` allows is read 16 times under pull-up, both pulls, then pull-down:
+   floating, pulled-up (both pulls still read 1: a weak pull-up such as a reset line's), driven-high / driven-low (the same
+   level under both pulls: push-pull or a strong pull - an idle-high UART line looks like this), active (changes between
+   reads). With `--power CH` the target is first read switched off: the channels that read otherwise follow its power.
+   These are candidates only.
+2. **hold**: each floating / pulled-up channel is held low (open drain) while an active channel is watched; a channel
+   that stops it is a reset-line candidate.
+3. **scan**: the wire over the floating / pulled-up channels (rvswd / swd: pairs, at most 600) - never over a driven or
+   active channel, the power channel or `--exclude`.
+4. **identify**: attach (halt) on what answered; the target_id names the family; a CH32V00x's option bytes say whether
+   NRST exists (read only, never written); then resume.
+5. **reset**: attach under reset through each candidate - the real line stops the hart at the reset vector.
+6. **slot**: a suggested `oep config slot` line (the reset channel as a comment while `config.Slot` has no
+   `reset_channel`); `--save` writes it (set + save). Nothing is written without `--save`.
+
+Safety: a driven or active channel is never driven, scanned or held; the power channel is touched only with `--power`;
+holding low is open drain only. A new gpio plan lets every pin of the old one go first - the power channel too - so with
+`--power` each new plan is followed by a clean power cycle (`power_cycles` in the report).
+
+ESP32-P4 with a CH32V003 (power on GPIO5), 2026-10-02:
+
+```
+$ oep pins /run/board-identify/by-id/esp32-series-30eda0ea068b --power 5 --wire swio
+power: channel 5 low 300 ms (target off: read), then high 400 ms before the reads
+classify: 52 channels, 16 reads each under pull-up, both pulls, pull-down
+  floating     0-3,6,9-20,26-34,36-50,52-54
+  pulled-up    4
+  driven-high  7-8,22-23,35  (never scanned or held)
+  driven-low   51  (never scanned or held)
+  active       21  (21: 8 changes under pull-up)
+  follow power 4,6,9-11,13,15-16,19-23,32-33  (read otherwise with the target off: wired to it; candidates only)
+reset line (hold low): 45 candidates, each held low (open drain) up to 390 ms while watching 21 (105 changes in 1.0 s running, longest lull 130 ms)
+  hold 4 low: 21 stopped
+  45 held in 3.4 s: stopped by 4
+scan swio: 45 channels (0-4,6,9-20,26-34,36-50,52-54; not 7-8,21-23,35,51: driven / active) in 0.14 s -> 19
+attach swio 19: target_id 00310510 (WCH DMI 0x7F) -> ch32v00x, halted at dpc 0x108
+  option bytes (read only): RST_MODE 10 (USER 0xf7): NRST on PD7, 12 ms ignore window
+  attach under reset through 4 (held 20 ms): dpc 0x0 -> the reset line
+slot: oep config slot ... --name ch32v00x --wire swio --pins 19   (not written; --save writes it)
+  # reset_channel 4 (probe.config §1.1; this client's slot has no reset_channel yet: name it in the attach's reset TLV)
+released every plan (channel 5 is back to its idle state: the target is powered only while something drives it)
+done in 7.3 s
+```
+
+22 / 23 are the target's UART (idle high: driven, so neither scanned nor held); 21 is an output its app toggles.
+
 ## A faster UART bridge (port_speed, opt-in)
 
 A probe whose describe declares `port_speed` (oep-core §3.5; the classic ESP32 reference firmware does) lets the host
@@ -173,6 +230,11 @@ period 64 (k // 2 + 1) samples, 12-bit values in 16-bit slots; ESP32-style front
 Vrefint) and `oep.fixture.capture-group` binding the logic and the analog: started together, the analog 5 us later
 (+-2 us), the trigger of one marked on both. Times are ns on the probe's one clock.
 
+`oep.fixture.i2c-target` and `oep.fixture.spi-target` (`p4-x035`, `esp32-v003`) take their roles from the plan (SDA / SCL;
+SCK / MOSI / MISO / CS - on `esp32-v003` one of two fixed channel_groups exactly) and answer every op of fixture §3 / §4.
+There is no bus controller: an arm stays armed and nothing is received until a test calls a hook on the endpoint
+(`i2c_write` / `i2c_read` / `spi_transfer`: one transaction on the bus).
+
 Other programs' tests run `fake_serve` as a child process:
 
 ```sh

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/README.ja.md

@@ -33,7 +33,9 @@ X.Y.Z（v1 の凍結までは、どのリリースも wire を壊しうるので
 | `host` | 要求と結果、session_id とロック、`call()`（失敗なら例外）、pipeline、エラーの階層（`OepError` / `Rejected` / `Failed`。lease 切れなら `Expired`。黙って open し直さず、`Host.epoch` が進む） |
 | `link` | transport: シリアルの口（常に COBS + CRC、`0x00 <COBS> 0x00`、フレームの外は雑音として捨てる、排他で開く）、USB vendor bulk / HID と TCP（長さつきフレーム、§5.1 の立て直し）、corr による照合と送り直し、`open_host(target)` |
 | `core` | インターフェースを名前で探す（キャッシュつき）、confirm（probe の `boot_id` つき）、probe の describe（宣言だけ。起動の間 cache: ラベル、transport の一覧、`max_op_ms`）、ロックの取り方（`take`）、ピンの割り当て（plan）、`Interface` の土台 |
-| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`（scan、attach: `max_speed` は常に送る、`reset=(channel, hold_ms)` でリセットをかけながら attach、detach、connections）、`oep.target.riscv-dm`（応答は値の数を持つ。`RunResult.not_halted`）、リセット線の探索、GPIO 経由の attach |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`（scan、attach: `max_speed` は常に送る、`reset=(channel, hold_ms)` でリセットをかけながら attach、detach、connections）、`oep.target.riscv-dm`（応答は値の数を持つ。`RunResult.not_halted`）、リセット線の探索（`find_reset_line(candidates, pins=...)`）、GPIO 経由の attach |
+| `targets` | host が target の系統ごとに知っていることを 1 つの表に（`FAMILIES`: 線、target_id の照合、リセットのベクタ、NRST を option で読む関数、max_speed / idle_clock）。`identify(target_id)` |
+| `pins` | `oep pins`: channel の分類、low に保つ探索、scan、識別、リセットの線の確かめ、スロットの提案（`PinFinder`） |
 | `console` | `oep.target.console`（位置つきのストリーム: read の応答は長さを持ち、マークは `time_ns`、ロック不要の `streams()`）と、バイト列として読む `ConsoleIO` |
 | `fixture` | `oep.fixture.gpio` / `uart`（ストリームは plan が作る。`status()`）/ `i2c-target` / `spi-target`（revision 1） |
 | `config` | `oep.probe.config`（スロット、bind、plan / label / idle / uart の項目、get / set / unset / save / erase。`describe()` = 宣言、`state()` = 保存・スロット・bind の今の状態、`hash_of(items)` = probe と同じ hash） |
@@ -77,12 +79,67 @@ oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
 oep config uart <probe> oep.fixture.uart 115200 --format 8N1   # その UART の plan に RX / TX が付くたびに掛かる
 oep config save <probe>                      # 再起動の後も残す（remove = unset、erase もある）
 oep speed <probe> [--candidates 921600,500000] [--verify [--flows out:2]]  # port_speed: 速い速さを試し、結果を出す（下）
+oep pins <probe> --power 5 --wire swio       # target のつながり方: debug のピン、リセットの線、スロット（下）
 ```
 
 `<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`）。
 
+## ピンを探す（`oep pins`）
+
+`oep pins <probe> [--power CH] [--exclude CH,...] [--wire swio|rvswd|swd] [--steps ...] [--save] [--json]` は、ピンを host
+が選ぶ probe で、target がどこにつながっているかを探します。各段は何をしたかを出し、全体は 1 分以内に終わり、最後に plan を
+すべて解きます。手順とその理由は oep-spec の host 開発ガイド（「ピンの探し方（参考）」）にあります。target の系統ごとに要る
+こと（線、リセットのベクタ、リセットの線の有無を読む option の読み方、max_speed / idle_clock）は 1 つの表 `targets.FAMILIES`
+にまとめ、その出典は oep-spec の `docs/target-scan-notes.ja.md` に記録します。
+
+1. **classify**: `oep.fixture.gpio` が許すすべての channel を、pull-up、両方の pull、pull-down の順に 16 回ずつ読む: floating、
+   pulled-up（両方の pull でも 1: リセットの線のような弱い pull-up）、driven-high / driven-low（どちらの pull でも同じレベル:
+   push-pull か強い pull。idle-high の UART の線はこう見える）、active（読むたびに変わる）。`--power CH` では先に target の
+   電源を切って読み、違って読めた channel が電源に従う。どれも候補を出すだけ。
+2. **hold**: floating / pulled-up の channel を 1 本ずつオープンドレインで low に保ち、active の channel を見る。止まれば
+   リセットの線の候補。
+3. **scan**: floating / pulled-up の channel で線を scan する（rvswd / swd は組で、600 組まで）。driven / active の channel、
+   電源の channel、`--exclude` は scan しない。
+4. **identify**: 答えた線に attach（halt）し、target_id で系統を見る。CH32V00x は option bytes で NRST の有無を見る（読むだけ、
+   書かない）。その後 resume。
+5. **reset**: 候補ごとにリセットをかけながら attach する。本物の線なら hart はリセットのベクタで止まる。
+6. **slot**: `oep config slot` の行を勧める（`config.Slot` に `reset_channel` が無い間、リセットの channel はコメント）。
+   `--save` で書く（set + save）。`--save` が無ければ何も書かない。
+
+安全: driven / active の channel は駆動も scan も保持もしない。電源の channel は `--power` のときだけ触る。low に保つのは
+オープンドレインだけ。gpio の plan を新しくすると、probe は前の plan のピンを（電源の channel も）いったん離すので、`--power`
+では新しい plan のたびにきれいに電源を入れ直す（報告の `power_cycles`）。
+
+ESP32-P4 と CH32V003（電源は GPIO5）、2026-10-02:
+
+```
+$ oep pins /run/board-identify/by-id/esp32-series-30eda0ea068b --power 5 --wire swio
+power: channel 5 low 300 ms (target off: read), then high 400 ms before the reads
+classify: 52 channels, 16 reads each under pull-up, both pulls, pull-down
+  floating     0-3,6,9-20,26-34,36-50,52-54
+  pulled-up    4
+  driven-high  7-8,22-23,35  (never scanned or held)
+  driven-low   51  (never scanned or held)
+  active       21  (21: 8 changes under pull-up)
+  follow power 4,6,9-11,13,15-16,19-23,32-33  (read otherwise with the target off: wired to it; candidates only)
+reset line (hold low): 45 candidates, each held low (open drain) up to 390 ms while watching 21 (105 changes in 1.0 s running, longest lull 130 ms)
+  hold 4 low: 21 stopped
+  45 held in 3.4 s: stopped by 4
+scan swio: 45 channels (0-4,6,9-20,26-34,36-50,52-54; not 7-8,21-23,35,51: driven / active) in 0.14 s -> 19
+attach swio 19: target_id 00310510 (WCH DMI 0x7F) -> ch32v00x, halted at dpc 0x108
+  option bytes (read only): RST_MODE 10 (USER 0xf7): NRST on PD7, 12 ms ignore window
+  attach under reset through 4 (held 20 ms): dpc 0x0 -> the reset line
+slot: oep config slot ... --name ch32v00x --wire swio --pins 19   (not written; --save writes it)
+  # reset_channel 4 (probe.config §1.1; this client's slot has no reset_channel yet: name it in the attach's reset TLV)
+released every plan (channel 5 is back to its idle state: the target is powered only while something drives it)
+done in 7.3 s
+```
+
+19 が SWIO、4 が NRST（hold で 21 が止まり、リセットをかけながらの attach で dpc 0）。22 / 23 は target の UART（idle high
+なので driven として scan も保持もしない）、21 はアプリが動かす出力。
+
 ## UART bridge を速くする（port_speed、使うときだけ）
 
 describe に `port_speed` を宣言する probe（oep-core §3.5。参照の classic ESP32 の firmware は宣言する）では、host は 1 つのセッションの
@@ -138,6 +195,10 @@ PARLIO と同じ w 1〜16、3 本なら w 4。`esp32-v003`: classic ESP32 の sa
 frontend、作り物の 2 点の較正と Vrefint）と、ロジックとアナログを束ねる `oep.fixture.capture-group` もある（一緒に始まり、
 アナログは 5 µs 遅れ（±2 µs）、片方のトリガが両方に印される）。時刻は probe の 1 本の時計の ns。
 
+`oep.fixture.i2c-target` と `oep.fixture.spi-target`（`p4-x035`、`esp32-v003`）は plan で役割を受け（SDA / SCL、SCK / MOSI / MISO / CS。
+`esp32-v003` の SPI は 2 つの channel_group のどれかに完全に一致）、fixture §3 / §4 の op にすべて答える。バスの controller は無い:
+試験が endpoint の hook（`i2c_write` / `i2c_read` / `spi_transfer`: バス上の 1 回のトランザクション）を呼ぶまで、arm は待ったままで何も受けない。
+
 外のプログラムの試験には `fake_serve` を子プロセスで使う:
 
 ```sh

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/README.md

@@ -37,7 +37,9 @@ oep-client-python X.Y.Z (until the v1 freeze every release may break the wire; t
 | `host` | requests and results, the session id and the lock, `call()` (raises unless it worked), pipelining, the errors (`OepError` / `Rejected` / `Failed`; `Expired` when the lease lapsed - the session is never re-opened behind the caller's back, `Host.epoch` moves) |
 | `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 (with the probe's `boot_id`), the probe's describe (declarations only, cached per boot: labels, the transport list, `max_op_ms`), taking the lock (`take`), the pin plan, the `Interface` base |
-| `riscv` | `oep.wire.rvswd` / `oep.wire.swio` (scan, attach - `max_speed` always sent, `reset=(channel, hold_ms)` for an attach under reset -, detach, connections), `oep.target.riscv-dm` (answers count their values; `RunResult.not_halted`), finding the reset line, attach through GPIO |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio` (scan, attach - `max_speed` always sent, `reset=(channel, hold_ms)` for an attach under reset -, detach, connections), `oep.target.riscv-dm` (answers count their values; `RunResult.not_halted`), finding the reset line (`find_reset_line(candidates, pins=...)`), attach through GPIO |
+| `targets` | what the host knows per target family, in one table (`FAMILIES`: wire, target_id match, reset vector, option-byte NRST reader, max_speed / idle_clock); `identify(target_id)` |
+| `pins` | `oep pins`: classify the channels, hold-low search, scan, identify, confirm the reset line, suggest a slot (`PinFinder`) |
 | `console` | `oep.target.console` (position streams: read answers carry their length, marks are `time_ns`, the lock-free `streams()` list) and `ConsoleIO`, read as bytes |
 | `fixture` | `oep.fixture.gpio` / `uart` (its stream is the plan's; `status()`) / `i2c-target` / `spi-target` (revision 1) |
 | `config` | `oep.probe.config` (slots, binds, plan / label / idle / uart items, get / set / unset / save / erase; `describe()` = the declarations, `state()` = the live storage / slot / bind state; `hash_of(items)` = the probe's hash) |
@@ -81,6 +83,7 @@ oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
 oep config uart <probe> oep.fixture.uart 115200 --format 8N1   # applied whenever that UART's plan has RX or TX
 oep config save <probe>                      # kept over a restart (also: remove = unset, erase)
 oep speed <probe> 1500000,921600,500000      # port_speed: try faster rates on a UART bridge, print the report (below)
+oep pins <probe> --power 5 --wire swio       # where the target is wired: debug pins, reset line, a slot (below)
 ```
 
 `<probe>` is a serial port, `tcp://HOST:PORT` or `usb[:VID:PID[:SERIAL]]`. A change takes the lock (owner "oep config") and
@@ -88,6 +91,60 @@ ends the session after it; it takes effect at once and, after `save`, stays over
 
 A run on hardware: ArduinoCore-CH32's `tests/manual/oep_smoke/` (`oep_smoke.py`, `oep_probe_checks.py`).
 
+## Finding the pins (`oep pins`)
+
+`oep pins <probe> [--power CH] [--exclude CH,...] [--wire swio|rvswd|swd] [--steps ...] [--save] [--json]` finds where a
+target is wired to a probe whose pins the host chooses. Each step says what it did; the whole run stays under a minute and
+every plan is released at the end. The procedure and its reasons are in oep-spec's host development guide (「ピンの探し方
+（参考）」); what each target family needs is in one table, `targets.FAMILIES` (wire, reset vector, the option-byte reader
+for the reset line, max_speed / idle_clock), which oep-spec `docs/target-scan-notes.ja.md` records the sources of.
+
+1. **classify**: every channel `oep.fixture.gpio` allows is read 16 times under pull-up, both pulls, then pull-down:
+   floating, pulled-up (both pulls still read 1: a weak pull-up such as a reset line's), driven-high / driven-low (the same
+   level under both pulls: push-pull or a strong pull - an idle-high UART line looks like this), active (changes between
+   reads). With `--power CH` the target is first read switched off: the channels that read otherwise follow its power.
+   These are candidates only.
+2. **hold**: each floating / pulled-up channel is held low (open drain) while an active channel is watched; a channel
+   that stops it is a reset-line candidate.
+3. **scan**: the wire over the floating / pulled-up channels (rvswd / swd: pairs, at most 600) - never over a driven or
+   active channel, the power channel or `--exclude`.
+4. **identify**: attach (halt) on what answered; the target_id names the family; a CH32V00x's option bytes say whether
+   NRST exists (read only, never written); then resume.
+5. **reset**: attach under reset through each candidate - the real line stops the hart at the reset vector.
+6. **slot**: a suggested `oep config slot` line (the reset channel as a comment while `config.Slot` has no
+   `reset_channel`); `--save` writes it (set + save). Nothing is written without `--save`.
+
+Safety: a driven or active channel is never driven, scanned or held; the power channel is touched only with `--power`;
+holding low is open drain only. A new gpio plan lets every pin of the old one go first - the power channel too - so with
+`--power` each new plan is followed by a clean power cycle (`power_cycles` in the report).
+
+ESP32-P4 with a CH32V003 (power on GPIO5), 2026-10-02:
+
+```
+$ oep pins /run/board-identify/by-id/esp32-series-30eda0ea068b --power 5 --wire swio
+power: channel 5 low 300 ms (target off: read), then high 400 ms before the reads
+classify: 52 channels, 16 reads each under pull-up, both pulls, pull-down
+  floating     0-3,6,9-20,26-34,36-50,52-54
+  pulled-up    4
+  driven-high  7-8,22-23,35  (never scanned or held)
+  driven-low   51  (never scanned or held)
+  active       21  (21: 8 changes under pull-up)
+  follow power 4,6,9-11,13,15-16,19-23,32-33  (read otherwise with the target off: wired to it; candidates only)
+reset line (hold low): 45 candidates, each held low (open drain) up to 390 ms while watching 21 (105 changes in 1.0 s running, longest lull 130 ms)
+  hold 4 low: 21 stopped
+  45 held in 3.4 s: stopped by 4
+scan swio: 45 channels (0-4,6,9-20,26-34,36-50,52-54; not 7-8,21-23,35,51: driven / active) in 0.14 s -> 19
+attach swio 19: target_id 00310510 (WCH DMI 0x7F) -> ch32v00x, halted at dpc 0x108
+  option bytes (read only): RST_MODE 10 (USER 0xf7): NRST on PD7, 12 ms ignore window
+  attach under reset through 4 (held 20 ms): dpc 0x0 -> the reset line
+slot: oep config slot ... --name ch32v00x --wire swio --pins 19   (not written; --save writes it)
+  # reset_channel 4 (probe.config §1.1; this client's slot has no reset_channel yet: name it in the attach's reset TLV)
+released every plan (channel 5 is back to its idle state: the target is powered only while something drives it)
+done in 7.3 s
+```
+
+22 / 23 are the target's UART (idle high: driven, so neither scanned nor held); 21 is an output its app toggles.
+
 ## A faster UART bridge (port_speed, opt-in)
 
 A probe whose describe declares `port_speed` (oep-core §3.5; the classic ESP32 reference firmware does) lets the host
@@ -151,6 +208,11 @@ period 64 (k // 2 + 1) samples, 12-bit values in 16-bit slots; ESP32-style front
 Vrefint) and `oep.fixture.capture-group` binding the logic and the analog: started together, the analog 5 us later
 (+-2 us), the trigger of one marked on both. Times are ns on the probe's one clock.
 
+`oep.fixture.i2c-target` and `oep.fixture.spi-target` (`p4-x035`, `esp32-v003`) take their roles from the plan (SDA / SCL;
+SCK / MOSI / MISO / CS - on `esp32-v003` one of two fixed channel_groups exactly) and answer every op of fixture §3 / §4.
+There is no bus controller: an arm stays armed and nothing is received until a test calls a hook on the endpoint
+(`i2c_write` / `i2c_read` / `spi_transfer`: one transaction on the bus).
+
 Other programs' tests run `fake_serve` as a child process:
 
 ```sh

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.27"
+version = "0.0.28"
 description = "Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe"
 readme = "README.md"
 license = "MIT"

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.27"
+__version__ = "0.0.28"

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/src/oep_client/__main__.py

@@ -12,6 +12,8 @@
   oep speed <probe> [--candidates 921600,500000] [--verify [--flows in:2,out:2]] (port_speed, core §3.5 and the host
                                            guide §7: try the candidates in order on a UART bridge, report)
   oep linktest <probe> --rates now,921600 --patterns in,out,duplex --inflight 1,2 --sizes 128,496 --frames 300
+  oep pins <probe> --power 5 --wire swio  (find the target's debug pins and reset line: classify the channels, scan,
+                                           identify, hold-low + attach under reset; prints a slot, --save writes it)
 
 <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).
@@ -63,6 +65,19 @@ def main(argv=None) -> int:
     lt.add_argument("--baud", type=int, default=link.BASE_BAUD, help="the boot speed to open at (default 115200)")
     lt.add_argument("--low-latency", choices=("on", "off"), default="on", help="the serial driver's low-latency mode")
     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 a slot (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("--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")
+    pn.add_argument("--wire", choices=("swio", "rvswd", "swd"), default="swio")
+    pn.add_argument("--steps", default="classify,hold,scan,identify,reset,slot",
+                    help="the steps to run, comma-separated (default all: classify, hold, scan, identify, reset, slot)")
+    pn.add_argument("--save", action="store_true", help="write the suggested slot (config set, then save)")
+    pn.add_argument("--slot", type=int, default=0, help="--save: the slot number (default 0)")
+    pn.add_argument("--name", help="--save: the slot's name (default: the target family, else 'target')")
+    pn.add_argument("--json", action="store_true", help="the report as JSON (the steps' lines go to stderr)")
     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")
@@ -77,6 +92,8 @@ def main(argv=None) -> int:
         return _speed(args)
     if args.command == "linktest":
         return _linktest(args)
+    if args.command == "pins":
+        return _pins_cmd(args)
 
     if args.fake:
         call = fake.PROFILES[args.fake]().call
@@ -88,6 +105,33 @@ def main(argv=None) -> int:
     return 0
 
 
+# ---- oep pins -----------------------------------------------------------------------------------------------------
+
+def _pins_cmd(args) -> int:
+    from . import pins
+    exclude = [int(x, 0) for x in args.exclude.replace(" ", "").split(",") if x]
+    say = (lambda t: print(t, file=sys.stderr, flush=True)) if args.json else (lambda t: print(t, flush=True))  # noqa: E731
+    hst = link.open_host(args.probe)
+    try:
+        core.take(hst, 10000, owner="oep pins")
+        finder = pins.PinFinder(hst, wire=args.wire, power=args.power, exclude=exclude, say=say, probe=args.probe,
+                                save=args.save, slot=args.slot, name=args.name)
+        report = finder.run(steps=tuple(s for s in args.steps.split(",") if s))
+        say(f"done in {report.elapsed_s:.1f} s")
+        if args.json:
+            print(json.dumps(report.as_dict(), indent=2))
+        try:
+            hst.end()
+        except host.OepError:
+            pass
+    except host.Rejected as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 2
+    finally:
+        hst.link.close()
+    return 0 if report.found else 1
+
+
 # ---- oep linktest -------------------------------------------------------------------------------------------------
 
 def _linktest(args) -> int:

{oep_client_python-0.0.27 → oep_client_python-0.0.28}/src/oep_client/config.py

@@ -73,14 +73,23 @@ class Label:
 
 @dataclass(kw_only=True)
 class Idle:
+    """The state of a channel no plan or connection uses (probe.config §1): at boot and after every release. mode:
+    hi-z, pull-up, pull-down, output-low, output-high (output_low / output_high too). An output mode keeps driving that
+    level while the channel is free - a target's power switch kept on - and a gpio plan that takes the channel keeps
+    it until its first set (fixture §1); a probe that cannot drive the channel refuses it unsupported."""
     channel: int
-    mode: str = "pull-up"          # hi-z, pull-up, pull-down
+    mode: str = "pull-up"          # hi-z, pull-up, pull-down, output-low, output-high
     TAG = ITEM["idle"]
 
+    def __post_init__(self):
+        self.mode = self.mode.replace("_", "-")
+
     def key(self) -> tuple:
         return (self.channel,)
 
     def value(self) -> bytes:
+        if self.mode not in IDLE:
+            raise ValueError(f"idle mode {self.mode!r}: one of {', '.join(IDLE)}")
         return struct.pack("<HB", self.channel, IDLE[self.mode])
 
 
@@ -395,3 +404,50 @@ class ProbeConfig(Interface):
                 return st
             first_slot += n_slots
             first_bind += n_binds
+
+
+# The label names of a target's power and reset lines (host-development-guide §8.1): `nrst` its reset, `power_hi` high
+# powers it, `power_lo` low powers it. On a probe with several slots they are `<slot name>.<name>`.
+LINE_NAMES = ("nrst", "power_hi", "power_lo")
+
+
+class AmbiguousLine(LookupError):
+    """find_line could not tell which channel is meant; `candidates` holds (label text, channel)."""
+
+    def __init__(self, message: str, candidates: list[tuple[str, int]]):
+        super().__init__(message)
+        self.candidates = candidates
+
+
+def find_line(hst_or_items, name: str, slot: int | str | None = None) -> int | None:
+    """The channel labelled for `name` (nrst, power_hi, power_lo: host-development-guide §8.1), or None when there is
+    none. hst_or_items: a Host (its settings are read: `ProbeConfig.items()`, no lock) or the decoded items. slot: the
+    slot's name or number; None picks the probe's one slot.
+
+    `<slot>.<name>` first, then the bare `name` - the bare name only when the settings hold at most one slot (a bare
+    name is for a one-slot probe). With several slots and no `slot`, or two channels with the same label, it raises
+    AmbiguousLine listing the candidates."""
+    items = hst_or_items if isinstance(hst_or_items, (list, tuple)) else ProbeConfig(hst_or_items).items()
+    labels = [(it.text, it.channel) for it in items if isinstance(it, Label)]
+    slots = [it for it in items if isinstance(it, Slot)]
+    if isinstance(slot, int):
+        named = [s.name for s in slots if s.slot == slot]
+        if not named:
+            raise LookupError(f"no slot {slot} in the probe's settings")
+        slot = named[0]
+    if slot is None and len(slots) > 1:
+        candidates = sorted((t, c) for t, c in labels if t == name or t.endswith("." + name))
+        if candidates:
+            listed = ", ".join(f"{t} (channel {c})" for t, c in candidates)
+            raise AmbiguousLine(f"{name}: {len(slots)} slots and no slot given; candidates: {listed}", candidates)
+        return None
+    if slot is None and slots:
+        slot = slots[0].name
+    texts = ([f"{slot}.{name}"] if slot is not None else []) + ([name] if len(slots) <= 1 else [])
+    for text in texts:
+        found = sorted(c for t, c in labels if t == text)
+        if len(found) > 1:
+            raise AmbiguousLine(f"{text}: on {len(found)} channels", [(text, c) for c in found])
+        if found:
+            return found[0]
+    return None