Session API

Session is the primary entry point for all interaction with OpenOCD. It manages the connection lifecycle and provides lazy access to every subsystem (target, memory, registers, flash, JTAG, breakpoints, RTT, SVD, transport).

SyncSession is the synchronous counterpart for use outside async contexts.

Session (async)

Constructor

Session.__init__(connection: TclRpcConnection, process: OpenOCDProcess | None = None)

You rarely call this directly. Use the factory methods connect() or start() instead.

Parameter	Type	Description
connection	TclRpcConnection	An established TCL RPC connection
process	OpenOCDProcess | None	Optional managed subprocess (closed on close())

Factory methods

Session.connect()

@classmethod
async def connect(
    host: str = "localhost",
    port: int = 6666,
    timeout: float = 10.0,
) -> Session

Connect to an already-running OpenOCD instance.

Parameter	Type	Default	Description
host	str	"localhost"	OpenOCD host address
port	int	6666	TCL RPC port
timeout	float	10.0	Connection timeout in seconds

Returns: Session

Raises: ConnectionError, TimeoutError

async with await Session.connect() as session:
    state = await session.target.state()

Session.start()

@classmethod
async def start(
    config: str | Path,
    *,
    tcl_port: int = 6666,
    openocd_bin: str | None = None,
    timeout: float = 10.0,
    extra_args: list[str] | None = None,
) -> Session

Spawn an OpenOCD process with the given configuration, wait for it to become ready, then connect.

Parameter	Type	Default	Description
config	str | Path	(required)	Config file path or -f/-c flags string
tcl_port	int	6666	TCL RPC port for the spawned process
openocd_bin	str | None	None	Custom OpenOCD binary path (auto-detected if None)
timeout	float	10.0	Seconds to wait for OpenOCD readiness
extra_args	list[str] | None	None	Additional CLI arguments

Returns: Session

Raises: ProcessError, ConnectionError, TimeoutError

async with await Session.start("interface/cmsis-dap.cfg -f target/stm32f1x.cfg") as session:
    await session.target.halt()

The config parameter accepts several formats:

• File path: "board/stm32f1discovery.cfg"
• Flag string: "-f interface/cmsis-dap.cfg -f target/stm32f1x.cfg"
• List form: ["-f", "interface/cmsis-dap.cfg", "-f", "target/stm32f1x.cfg"]

Session.connect_sync()

@classmethod
def connect_sync(
    host: str = "localhost",
    port: int = 6666,
    **kwargs,
) -> SyncSession

Synchronous version of connect(). Returns a SyncSession.

Raises: RuntimeError if called from inside a running async event loop.

with Session.connect_sync() as session:
    state = session.target.state()

Session.start_sync()

@classmethod
def start_sync(config: str | Path, **kwargs) -> SyncSession

Synchronous version of start(). Returns a SyncSession.

Context manager

Session implements __aenter__ and __aexit__. On exit, it calls close().

async with await Session.connect() as session:
    # session is open here
    pass
# session.close() called automatically

Methods

close()

async def close() -> None

Close the TCP connection and stop the OpenOCD subprocess if one was spawned via start().

command()

async def command(cmd: str) -> str

Send a raw OpenOCD command string and return the response. This is the escape hatch for commands not covered by the typed subsystem APIs.

Parameter	Type	Description
cmd	str	Any valid OpenOCD command

Returns: The raw response string from OpenOCD.

resp = await session.command("version")
print(resp)

on_halt()

def on_halt(callback: Callable[[str], None]) -> None

Register a callback that fires when a notification containing “halted” is received.

on_reset()

def on_reset(callback: Callable[[str], None]) -> None

Register a callback that fires when a notification containing “reset” is received.

Properties (lazy subsystems)

Each property instantiates its subsystem on first access. All subsystems share the same underlying connection.

Property	Async Type	Description
target	Target	Halt, resume, step, reset, state queries
memory	Memory	Read/write target memory at various widths
registers	Registers	Read/write CPU registers
flash	Flash	Flash bank enumeration, programming, erase, verify
jtag	JTAGController	JTAG scan chain, IR/DR scan, boundary scan
breakpoints	BreakpointManager	Set/remove breakpoints and watchpoints
rtt	RTTManager	SEGGER RTT channel read/write
svd	SVDManager	SVD file loading, register decoding
transport	Transport	Transport and adapter queries

---

SyncSession

Wraps an async Session for synchronous use. Every method runs through loop.run_until_complete() on an internally managed event loop.

Context manager

with Session.connect_sync() as session:
    print(session.target.state())

Calls close() on exit.

Methods

command()

def command(cmd: str) -> str

Synchronous version of Session.command().

Properties (lazy sync subsystems)

Property	Sync Type	Description
target	SyncTarget	Halt, resume, step, reset, state
memory	SyncMemory	Read/write memory
registers	SyncRegisters	Read/write registers
flash	SyncFlash	Flash operations
jtag	SyncJTAGController	JTAG operations
breakpoints	SyncBreakpointManager	Breakpoints and watchpoints
svd	SyncSVDManager	SVD loading and decoding

Caution

The sync API must never be called from inside a running async event loop. Doing so raises RuntimeError with a clear message. If you are in an async context, use the async Session directly.