oep-client-python 0.0.1__py3-none-any.whl

oep_client/v1/usb_stream.py

@@ -0,0 +1,209 @@
+"""A USB vendor bulk endpoint pair shaped like the part of a pyserial port the v1 link uses (read with a timeout,
+in_waiting, write, reset_input_buffer), so length-prefixed frames run over it unchanged. pyusb is imported only here.
+
+IN is drained on a thread: a bulk write blocks until the device takes the data, and the device stops taking data
+once its answers fill its FIFO and nobody reads them (E160).
+
+Each IN read asks for READ_SIZE bytes. A read completes when that much has arrived or a short packet ends the
+transfer; if its timeout hits first, pyusb raises and the bytes already received are lost. Under a continuous stream
+(12.5 MB/s, 2026-09-25) a 64 KiB read waited for more than its 50 ms and dropped whole answers, so reads stay small."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+
+class UsbBulkStream:
+    READ_SIZE = 16384
+
+    def __init__(self, device, endpoint_in, endpoint_out, interface: int):
+        self.device, self.ep_in, self.ep_out, self.interface = device, endpoint_in, endpoint_out, interface
+        self.timeout = 0.05
+        self._buffer = bytearray()
+        self._cond = threading.Condition()
+        self._closed = False
+        self._reader = threading.Thread(target=self._drain, daemon=True)
+        self._reader.start()
+
+    @classmethod
+    def open(cls, vid: int, pid: int, serial: str | None = None) -> "UsbBulkStream":
+        import usb.core
+        import usb.util
+        match = (lambda d: usb.util.get_string(d, d.iSerialNumber).lower() == serial.lower()) if serial else None
+        dev = usb.core.find(idVendor=vid, idProduct=pid, custom_match=match)
+        if dev is None:
+            raise FileNotFoundError(f"no USB device {vid:04x}:{pid:04x}" + (f" serial {serial}" if serial else ""))
+        cfg = dev.get_active_configuration()
+        for intf in cfg:
+            eps = [e for e in intf if usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK]
+            ins = [e for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN]
+            outs = [e for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT]
+            if ins and outs:
+                usb.util.claim_interface(dev, intf.bInterfaceNumber)
+                return cls(dev, ins[0], outs[0], intf.bInterfaceNumber)
+        raise FileNotFoundError("no bulk IN/OUT pair on the device")
+
+    def _drain(self) -> None:
+        import usb.core
+        while not self._closed:
+            try:
+                data = self.ep_in.read(self.READ_SIZE, timeout=200)
+            except usb.core.USBTimeoutError:
+                continue
+            except usb.core.USBError:
+                if self._closed:
+                    return
+                time.sleep(0.01)
+                continue
+            if len(data):
+                with self._cond:
+                    self._buffer += bytes(data)
+                    self._cond.notify_all()
+
+    @property
+    def in_waiting(self) -> int:
+        with self._cond:
+            return len(self._buffer)
+
+    def read(self, n: int = 1) -> bytes:
+        deadline = time.monotonic() + (self.timeout or 0)
+        with self._cond:
+            while not self._buffer:
+                left = deadline - time.monotonic()
+                if left <= 0:
+                    return b""
+                self._cond.wait(left)
+            out = bytes(self._buffer[:n])
+            del self._buffer[:n]
+            return out
+
+    def write(self, data: bytes) -> int:
+        n = self.ep_out.write(data, timeout=2000)
+        if data and len(data) % self.ep_out.wMaxPacketSize == 0:   # a zero-length packet ends the probe's transfer
+            self.ep_out.write(b"", timeout=2000)
+        return n
+
+    def reset_input_buffer(self) -> None:
+        with self._cond:
+            self._buffer.clear()
+
+    def close(self) -> None:
+        import usb.util
+        self._closed = True
+        self._reader.join(timeout=0.5)
+        usb.util.release_interface(self.device, self.interface)
+        usb.util.dispose_resources(self.device)
+
+
+class UsbAsyncStream:
+    """The same shape as UsbBulkStream on python-libusb1 (`usb1`): IN runs as DEPTH asynchronous transfers of URB_SIZE
+    kept queued by an event thread, so a continuous stream near the HS ceiling (wch-protocols E116: 1 MiB x 8 reaches
+    ~47 MB/s over usbipd; 64 KiB x 32 carried 2 x 160 Msps here) is taken without gaps. A transfer completes when full or on a short packet; the probe ends a
+    transfer whose length is a whole number of packets with a zero-length packet, so small answers never wait."""
+
+    # 64 KiB x 32: a probe streaming whole-packet frames (16 KiB) completes a read every four frames, so the latency at
+    # a low rate stays short (1 MiB reads waited 0.8 s at 1.25 MB/s), and 2 MiB stay queued for the host's hiccups
+    URB_SIZE = 64 * 1024
+    DEPTH = 32
+
+    def __init__(self, context, handle, endpoint_in: int, endpoint_out: int, interface: int):
+        import usb1
+        self._usb1 = usb1
+        self.context, self.handle, self.ep_in, self.ep_out, self.interface = context, handle, endpoint_in, endpoint_out, interface
+        self.timeout = 0.05
+        self._buffer = bytearray()
+        self._cond = threading.Condition()
+        self._closed = False
+        self._transfers = []
+        for _ in range(self.DEPTH):
+            t = handle.getTransfer()
+            t.setBulk(endpoint_in, self.URB_SIZE, callback=self._done, timeout=0)
+            t.submit()
+            self._transfers.append(t)
+        self._events = threading.Thread(target=self._run, daemon=True)
+        self._events.start()
+
+    @classmethod
+    def open(cls, vid: int, pid: int, serial: str | None = None) -> "UsbAsyncStream":
+        import usb1
+        context = usb1.USBContext()
+        context.open()
+        for dev in context.getDeviceIterator(skip_on_error=True):
+            if dev.getVendorID() != vid or dev.getProductID() != pid:
+                continue
+            handle = dev.open()
+            if serial and (handle.getSerialNumber() or "").lower() != serial.lower():
+                handle.close()
+                continue
+            for setting in dev.iterSettings():
+                eps = [(e.getAddress(), e.getAttributes()) for e in setting]
+                ins = [a for a, attr in eps if attr & 3 == 2 and a & 0x80]
+                outs = [a for a, attr in eps if attr & 3 == 2 and not a & 0x80]
+                if ins and outs:
+                    handle.claimInterface(setting.getNumber())
+                    return cls(context, handle, ins[0], outs[0], setting.getNumber())
+            handle.close()
+        context.close()
+        raise FileNotFoundError(f"no USB device {vid:04x}:{pid:04x}" + (f" serial {serial}" if serial else ""))
+
+    def _done(self, transfer) -> None:
+        usb1 = self._usb1
+        status = transfer.getStatus()
+        if status == usb1.TRANSFER_COMPLETED:
+            n = transfer.getActualLength()
+            if n:
+                data = transfer.getBuffer()[:n]
+                with self._cond:
+                    self._buffer += data
+                    self._cond.notify_all()
+        if not self._closed and status in (usb1.TRANSFER_COMPLETED, usb1.TRANSFER_TIMED_OUT):
+            transfer.submit()
+
+    def _run(self) -> None:
+        while not self._closed:
+            try:
+                self.context.handleEventsTimeout(0.1)
+            except self._usb1.USBErrorInterrupted:
+                continue
+
+    @property
+    def in_waiting(self) -> int:
+        with self._cond:
+            return len(self._buffer)
+
+    def read(self, n: int = 1) -> bytes:
+        deadline = time.monotonic() + (self.timeout or 0)
+        with self._cond:
+            while not self._buffer:
+                left = deadline - time.monotonic()
+                if left <= 0:
+                    return b""
+                self._cond.wait(left)
+            out = bytes(self._buffer[:n])
+            del self._buffer[:n]
+            return out
+
+    def write(self, data: bytes) -> int:
+        n = self.handle.bulkWrite(self.ep_out, data, timeout=2000)
+        if data and len(data) % 512 == 0:   # end the probe's receive transfer (a probe reading large transfers needs it)
+            self.handle.bulkWrite(self.ep_out, b"", timeout=2000)
+        return n
+
+    def reset_input_buffer(self) -> None:
+        with self._cond:
+            self._buffer.clear()
+
+    def close(self) -> None:
+        self._closed = True
+        for t in self._transfers:
+            try:
+                t.cancel()
+            except self._usb1.USBError:
+                pass
+        self._events.join(timeout=0.5)
+        try:
+            self.handle.releaseInterface(self.interface)
+        finally:
+            self.handle.close()
+            self.context.close()

oep_client_python-0.0.1.dist-info/METADATA

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

oep_client_python-0.0.1.dist-info/RECORD

@@ -0,0 +1,36 @@
+oep_client/__init__.py,sha256=f5QEx-7qtfSSRnMCtAflZ2y0GvfX6lXa_AVjdc4SQfg,166
+oep_client/v1/__init__.py,sha256=Aghb5g5wouqnDIUFv9S4dkimnzs5YZcWx9gzgxi7GPM,90
+oep_client/v1/__main__.py,sha256=CytzDl1qI-sqXPS5ZqtvV07Riz2agQ7uK-Hlwmyz8fw,1747
+oep_client/v1/arm.py,sha256=JLyUhLSPcmsk73schZcaJYoOKuHzrvnU8kPmfrEvVuo,12331
+oep_client/v1/capture.py,sha256=RZgDnWqr8Aqy49U7PqQpnKIQEL18djVuDJFydxrmv-c,17996
+oep_client/v1/catalog.py,sha256=EqAQnSgHFxGbCO2GQ_Ee-uheJKbBBUUpL1-0qHfNMXU,6574
+oep_client/v1/ch32_flash.py,sha256=Fc-6jEj15cQtMSKmfC5dmDetMXJ8hAdAuJ9d9odwrsA,12651
+oep_client/v1/cobs.py,sha256=hqddQI_X7rsBvBvcP_MBE3bXPyB13-Azjqp_9JfdQ1g,2288
+oep_client/v1/console.py,sha256=YYcuc9Qxe3kihla8wynYbDaLVr7wBLEvswrM-cMK3Tk,6859
+oep_client/v1/core.py,sha256=z0-mplQVLOmPyXj1lHc-U7HYl3Gd6o-b5YJhpQTvqKU,8789
+oep_client/v1/decode.py,sha256=M-bRARrA2qGZLoJn0BdXeTb4WjL_2Hb2nk_g1IGXIw4,2382
+oep_client/v1/dump.py,sha256=GAnmu2abuDmGmbWcbbEfC3EUuPp5Hady9vQVNcQ-724,6743
+oep_client/v1/endpoint.py,sha256=ay767evyw0QgM6oXOUcl94b_wxTHtXHxsc8sAUMi6u0,72014
+oep_client/v1/esp32_targets.py,sha256=b8tNH-nb2KC-XgNfWg5l3TO0cyhZOF-gJajaVxNVSGQ,4988
+oep_client/v1/fake.py,sha256=UzpB-A42Ma2QqJj0l-JmwCJkMn6DPVHHN77fcemT59U,13104
+oep_client/v1/fake_serial.py,sha256=6fhtrit9kWix-D83yYfUKFLHJ11pEiMDrlKNeJKvCfU,4314
+oep_client/v1/fake_serve.py,sha256=B93k_fV0j0KpO8Qtyx8dQfffxn2EeRsURsdX_ScKEP0,12423
+oep_client/v1/fixture.py,sha256=653hCD-Iz0Lfs8dT4Hdg3QyubbbOGs1_xjq_3nb8foU,5564
+oep_client/v1/frames.py,sha256=xjgjnXmXUqNJZ5m0h91r4Cy48WoVK1mEMW4gRg-mlMI,3991
+oep_client/v1/hid_stream.py,sha256=99Dsm4Io1keukuETG_UNqjBGiVYZZeb__Pv4ytaKg9k,10695
+oep_client/v1/host.py,sha256=Y5oqE-pw5Ja9cG1dzdy8svIEgR4Kqhki0wuyrpP_xH8,15563
+oep_client/v1/interfaces.py,sha256=P4ehrIj4j-9eg4NjaVdV15pawI2vOqucJwVklSdR-As,5472
+oep_client/v1/link.py,sha256=J9VtBWfTgNoIgUQuj8SsH9hHesQM2uEN545IoxKVS8E,19406
+oep_client/v1/message.py,sha256=MEM1UT6KFM7AsT56jvBLt_FJK_6SJ7O_nGAiipW0_zo,9912
+oep_client/v1/names.py,sha256=ztCZFWs__aR-a5G14TnJP-Q4YfLhbyrzvOVOMJuG93k,3653
+oep_client/v1/registry.py,sha256=nRM-sQiAMs1OzuSZIajdsBfdFckYo3OfwgmcLkHzxqw,9867
+oep_client/v1/riscv.py,sha256=E0_C-4mBsrp9FUoZpMiqSH9e8sC8Q4EO5HRjFKE6_pc,21392
+oep_client/v1/rp2350.py,sha256=7OMyj270k3AY1e3-ljicPwOjf9jOlokbT6QNkA0b0yY,4227
+oep_client/v1/target.py,sha256=R8BvYfFfYNhZF0MysJkNb8b69YgBlmeGXNX8ReZIe5k,1068
+oep_client/v1/uiapduino.py,sha256=IEPG3LbZPksi8g3wmAf6T0CRWSfYKW1_qrH_GBVQdxY,6090
+oep_client/v1/usb_stream.py,sha256=1nvuRNLQkpp8054eG-JutBKh9y0F_8PHGDAfG0ZSbaY,8819
+oep_client_python-0.0.1.dist-info/METADATA,sha256=PdTZlP4XrPcU_zZZZYofEqST_flj7AeoXHWF9iC06LQ,7312
+oep_client_python-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+oep_client_python-0.0.1.dist-info/entry_points.txt,sha256=F9_WK-5S92fBuWSeCR0GXzmA5OXY6y0xvYpHseqY2R8,52
+oep_client_python-0.0.1.dist-info/licenses/LICENSE,sha256=ntlalztb3L1OaNAxmQdHlubu5fVhjMc9oRZi3PeQhXg,1076
+oep_client_python-0.0.1.dist-info/RECORD,,

oep_client_python-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

oep_client_python-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oep = oep_client.v1.__main__:main

oep_client_python-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Embedded Probe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.