OEP Python client

日本語

The host side of Open Embedded Probe (OEP). It speaks the v1 protocol of oep-spec (docs/oep-core.ja.md and the standard interfaces docs/oep-if-*.ja.md, a candidate being settled). The wire numbers come from oep_client.registry, a verbatim copy of oep-spec's generated generated/oep-v1/oep_v1_registry.py. This is an experimental stage: breaking changes are expected and no compatible API is promised. For a map of the specification, start with oep-spec's docs/review-guide.ja.md.

It follows OEP's division of work: the knowledge of the target lives in the host. The probe knows only its wires and DMI / DP-AP transfers; the CH32 flash controller, the RAM loader, the RP2350 boot ROM, the Cortex-M debug registers and so on are here.

pip install oep-client-python     # PyPI (import oep_client); a checkout: pip install -e <checkout>
uv run pytest                     # in a checkout

import oep_client is all it takes. The registry is copied from oep-spec with tools/sync_registry.sh. PyPI's oep-client is another project, so the distribution is named oep-client-python.

Releases: run the GitHub Actions workflow Release (workflow_dispatch, version X.Y.Z or X.Y.ZbN). tools/prepare_release.py sets the version in pyproject.toml, uv.lock and oep_client.__version__ and turns CHANGELOG.md's Unreleased into that version; after the tests and the build it commits, tags, makes the GitHub Release and publishes to PyPI (Trusted Publishing). Record changes under Unreleased in CHANGELOG.md, (EN) and (JA).

Modules (oep_client)

The modules below are the public API; import them directly (from oep_client import riscv). Anything not listed, and names starting with _, may change. A probe firmware and this client go together by version: OpenEmbeddedProbe X.Y.Z with oep-client-python X.Y.Z (until the v1 freeze every release may break the wire; the versions move together).

Example

from oep_client import core, link, riscv, ch32_flash

hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelined
# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the probe whose USB serial it is),
# "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
core.take(hst, 30000, owner="flash script")   # the only way in: force; else wait out the lease, name the holder
wire = riscv.Wire(hst, "oep.wire.rvswd")
conn, _ = wire.attach(halt=True)
dm = riscv.RiscvDm(hst, conn)
dm.reset_halt()
result = ch32_flash.program(hst, dm, open("sketch.bin", "rb").read(), ch32_flash.PROFILES["x035"])
dm.reset(confirm=True)
wire.detach(conn)
hst.end()

The oep command

oep dump --port <probe>                      # what the probe offers (--fake p4-x035: no hardware)
oep config show <probe>                      # the settings, the declarations and the live state
oep config state <probe>                     # the live slot / bind / storage state alone (lock-free, for polling)
oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
oep config 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)

<probe> is a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]. A change takes the lock (owner "oep config") and ends the session after it; it takes effect at once and, after save, stays over a restart.

A run on hardware: ArduinoCore-CH32's tests/manual/oep_smoke/ (oep_smoke.py, oep_probe_checks.py).

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 run its UART bridge faster than the boot speed (115200) for one session. Nothing changes unless the host asks:

hst = link.open_host("/dev/ttyUSB0", port_speed=[1500000, 921600, 500000])   # takes the lock, keeps the session open
print(hst.link.speed.to_text())             # every rate tried: actual, in / out KB/s, broken frames, the one in force
# or, in a session already taken: report = link.raise_speed(hst, [1500000, 921600], verify_bytes=32768, verify_s=1.0)

Each rate in order: try (answered at the speed now, then the probe switches) -> the host switches -> a verify both ways with max_frame-sized frames (link_source / link_sink, pipelined) for verify_bytes or verify_s, counting broken frames and measuring KB/s each way -> commit when nothing broke, else revert and back to the boot speed, confirmed there (a probe whose revert was lost waits out its verify_ms). The first rate that passes is kept; a rate the probe's UART cannot make is skipped. Which rates pass depends on the bridge chip and its driver (an FTDI took only 3 MHz / n, a CH340 921600 but not 1500000 towards the host: oep-spec docs/uart-speed-negotiation.ja.md), so the host chooses them. The report (link.speed: rate, chosen, in_kb_s / out_kb_s, trials) is there to budget a capture or a write.

The probe goes back to the boot speed by itself when the session ends (end, a lapse, a force), when frames break or the line goes quiet (idle_ms, at most port_speed_idle_max_ms = 3 s; a host that died leaves the rate no longer than that): while raised the link sends a keepalive before a request when it has been quiet for 1 s, and hst.link.keep_alive() does the same for a caller that sits idle for long; opening a serial port retries its first confirm for about 4 s to wait out a rate left over. The link follows an end at once, and a request that goes unanswered at a raised rate (its resend too) takes the link back to the boot speed, confirmed, and goes once more there - it never wedges. A probe without the feature answers not supported and stays at its speed. Behind a broker (TCP) the broker does this, not the client. Serial ports are also opened in the driver's low-latency mode where it has one (an FTDI's latency timer 16 -> 1 ms tripled a UART bridge's throughput). open_host(..., baud=) names the boot speed when the board's profile is not 115200.

The fake probe (a working spec)

endpoint.Endpoint is a fake probe that answers as oep-spec says (2026-10-01: every answer carries the length of its data or list, TLVs may follow anything, rejected expired after a lapse, one resource number space, describe = declarations and state for the rest, capture generations); ch32rv, this client and the probe firmware are checked against it (when the spec changes, this is brought in line before the firmware). fake holds example declarations (profiles p4-x035, esp32-v003, p4-bench = a made-up jig with three slots and two seats, rp2350-pins = a wire whose pins the host chooses), fake_serial the byte side of a serial port (COBS candidates, raw bytes and binds, held during a session and resumed after it).

fake_capture is oep.fixture.logic (logic): one-shot, repeat (segments with the clock at the actual rate, a ring, release) and streaming (data pushes while subscribed), level / edge triggers with a pretrigger, and events. What it captures is known: sample i is the counter i, channel k its bit k (a square wave of period 2^(k+1) samples), in the layout the profile allows (p4-x035: w 1-16 as the P4's PARLIO, three channels in w 4; esp32-v003: w 8 as the classic ESP32's sampler, one-shot only). A capture only listens, so it may be planned on pins other interfaces hold. p4-x035 also has oep.fixture.analog (4 channels of the P4's ADC1 on GPIO16-23: an even channel k a square wave, an odd one a sine, of period 64 (k // 2 + 1) samples, 12-bit values in 16-bit slots; ESP32-style frontends; a made-up two-point calibration and a 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.

Other programs' tests run fake_serve as a child process:

python -m oep_client.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
    --console 'uptime %d\r\n' --every 100
# first line: PTY /dev/pts/N (PORT n with --tcp 0); it ends when stdin closes

The pty is a serial port (the host opens it with TIOCEXCL); --tcp PORT is --framing cobs (a serial port) or --framing length (the vendor bulk / TCP form). Faults: --drop N (the N-th answer is not sent, once; the request did run, so a resend gets the remembered result), --noise TEXT (noise before every answer), --corrupt N (the N-th answer's CRC broken once). --uart-plan / --uart-rx give the first fixture UART a plan and RX bytes, --run-hook a host's own model of riscv-dm run, --capture-slipped flags bit2 on every capture segment. port_speed: esp32-v003 has it (--no-port-speed turns it off), and --broken-rate RATE[:MIN_SIZE][:in|out] makes a rate break frames (in process, fake_serial.FakeSerialStream also garbles everything while the host's own rate differs from the probe's). Events and data pushes go out on the pty and on TCP (both framings). The rest: --help.