Transport and Adapter

The Transport subsystem provides access to the debug transport layer — the physical protocol used to communicate between the debug adapter and the target. OpenOCD supports several transports including JTAG, SWD, and SWIM, used with adapter hardware like CMSIS-DAP, ST-Link, and J-Link probes.

Access it through the session:

session.transport

Querying the active transport

select() returns the name of the currently active transport as a string.

Async

import asyncio
from openocd import Session

async def main():
    async with await Session.connect() as session:
        transport = await session.transport.select()
        print(f"Active transport: {transport}")
        # Typical output: "swd" or "jtag"

asyncio.run(main())

Sync

from openocd import Session

with Session.connect_sync() as session:
    transport = session.command("transport select").strip()
    print(f"Active transport: {transport}")

Common return values:

Value	Protocol
"jtag"	IEEE 1149.1 JTAG
"swd"	ARM Serial Wire Debug
"swim"	STM8 Single Wire Interface Module

Listing available transports

list() returns all transports supported by the current adapter configuration.

Async

async with await Session.connect() as session:
    available = await session.transport.list()
    print(f"Available transports: {', '.join(available)}")

Sync

with Session.connect_sync() as session:
    response = session.command("transport list").strip()
    print(f"Available transports: {response}")

A CMSIS-DAP adapter typically supports both ["jtag", "swd"], while an ST-Link V2 may report ["hla_swd"].

Identifying the adapter

adapter_info() returns a description of the connected debug adapter. It tries the adapter name command first (OpenOCD 0.12+) and falls back to adapter info for older versions.

async with await Session.connect() as session:
    info = await session.transport.adapter_info()
    print(f"Adapter: {info}")
    # Example: "cmsis-dap" or "st-link"

Adapter clock speed

adapter_speed(khz=None) gets or sets the debug adapter clock frequency in kHz. When called without arguments it returns the current speed. When called with a value it sets the speed and returns the new value.

Async

async with await Session.connect() as session:
    # Query current speed
    current = await session.transport.adapter_speed()
    print(f"Current speed: {current} kHz")

    # Set to 4 MHz
    new_speed = await session.transport.adapter_speed(4000)
    print(f"Speed set to: {new_speed} kHz")

Sync

with Session.connect_sync() as session:
    current = session.command("adapter speed").strip()
    print(f"Current speed: {current}")

    session.command("adapter speed 4000")
    print("Speed set to 4000 kHz")

Tip

Start with a lower clock speed (1000 kHz or less) when bringing up a new board, then increase once communication is stable. Maximum speed depends on the adapter, target, and board layout. CMSIS-DAP adapters typically support up to 10 MHz on SWD.

Caution

Changing the adapter speed while the target is actively being debugged can cause communication errors. Set the speed before performing debug operations, ideally during initial configuration.

Common adapter interfaces

Adapter	Typical Transports	Notes
CMSIS-DAP	JTAG, SWD	Open standard, wide device support
ST-Link	SWD (HLA)	ST Microelectronics probes
J-Link	JTAG, SWD	SEGGER probes, high performance
FTDI	JTAG, SWD	FT2232-based adapters
Raspberry Pi GPIO	JTAG, SWD	Direct bitbang via GPIO pins

Error handling

Transport and adapter operations raise OpenOCDError on failure.

from openocd import OpenOCDError

try:
    speed = await session.transport.adapter_speed(99999)
except OpenOCDError as e:
    print(f"Speed setting failed: {e}")

Method reference

Method	Return Type	Description
select()	str	Get the active transport name
list()	list[str]	List available transports
adapter_info()	str	Get adapter description string
adapter_speed(khz=None)	int	Get or set adapter speed in kHz