Metadata-Version: 2.4
Name: openocd-python
Version: 2026.2.12
Summary: Typed, async-first Python bindings for the full OpenOCD command surface
Project-URL: Homepage, https://git.supported.systems/ryan/openocd-python
Project-URL: Issues, https://git.supported.systems/ryan/openocd-python/issues
Author-email: Ryan Malloy <ryan@supported.systems>
License-Expression: MIT
License-File: LICENSE
Keywords: debugging,embedded,hardware,jtag,openocd,swd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cmsis-svd>=0.4
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# openocd-python

Typed, async-first Python bindings for the full OpenOCD command surface.

## Install

```bash
pip install openocd-python
```

## Quick Start

```python
from openocd import Session

# Connect to a running OpenOCD instance
async with Session.connect() as ocd:
    state = await ocd.target.halt()
    pc = await ocd.registers.pc()
    mem = await ocd.memory.read_u32(0x08000000, 4)
    print(f"PC: {pc:#x}")

# Or spawn OpenOCD and connect
async with Session.start("interface/cmsis-dap.cfg -f target/stm32f1x.cfg") as ocd:
    await ocd.target.halt()
    regs = await ocd.registers.read_all()

# Synchronous API available too
with Session.start_sync("interface/cmsis-dap.cfg") as ocd:
    ocd.target.halt()
    print(f"PC: {ocd.registers.pc():#x}")
```

## Features

- **Async-first** with sync wrappers for every method
- **Typed returns** — dataclasses, not raw strings
- **Full OpenOCD surface**: target control, memory, registers, flash, JTAG, breakpoints, RTT
- **SVD decoding** — read a peripheral register and get named bitfields
- **Process management** — spawn and manage OpenOCD subprocesses
- **Dual transport** — TCL RPC (primary) and telnet (fallback)

## Requirements

- Python 3.11+
- OpenOCD installed and on PATH (or pass `openocd_bin=`)
