Debug probe

A Binho debug probe (the Atira) is a different instrument from a host adapter, so it has its own classes: DebugProbe and its asyncio twin AsyncDebugProbe. A probe and a Supernova or Pulsar can be open in the same process. The probe needs firmware fw-atira v1.0 or newer (16-bit status); older images are refused at open().

The surface is the control plane, target power, SWD debug, target flash (1.9.0), the SPI controller and SPI NOR flash. RTT, SWO and UPDI are not in this release. examples/blocking_api/debugprobe/ has the runnable starting points: get_probe_info.py, debug_halt_and_read.py and flash_program_and_verify.py.

Discovery

pycosmicsdk.list_debug_probes() → list[DiscoveredDebugProbe]

Return every attached debug probe.

Returns:: One entry per probe, in enumeration order.

class pycosmicsdk.DiscoveredDebugProbe(path: str, serial_number: str)

Bases: object

One attached debug probe, as list_debug_probes() reports it.

path

The HID path, stable for the session.

Type:: str

serial_number

The USB serial number.

Type:: str

DebugProbe

Probe-wide calls live on the probe. Each function of the probe is a sub-object returned by a call, as on Device (dev.spi()): probe.power(), probe.uart(), probe.debug(), probe.spi() and probe.flash(). Firmware older than fw-atira v1.0 raises UnsupportedFirmwareError at open().

class pycosmicsdk.DebugProbe(facade: Any, info: DebugProbeInfo)

Bases: object

An open debug probe. Construct with open().

Thread-safe: a per-instance lock runs one call at a time, and close() waits for the call in flight.

classmethod open(*, serial: str | None = None, path: str | None = None, timeout_ms: int = 5000) → DebugProbe

Open a debug probe.

Parameters:

serial – USB serial to match; the first probe found when omitted.
path – HID path to open instead of matching a serial.
timeout_ms – Per-call response deadline.

Returns:

The open probe.

Raises:

UnsupportedFirmwareError – The probe answered, but its firmware predates fw-atira v1.0.
DeviceNotFoundError – No probe matched, another process holds it, or this user cannot open its HID node.

close() → None

Release the probe. Idempotent.

An SPI session this handle opened is released first, so the next process finds the pins free.

__enter__() → DebugProbe: Return self.

__exit__(exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) → None: Close the probe.

power() → TargetPower

Return the target rail: switch and readings.

Returns:: This probe’s power interface.

uart() → UartBridge

Return the UART bridge: port name and persisted line configuration.

Returns:: This probe’s UART bridge interface.

debug() → DebugTarget

Return the SWD debug session: run control, registers, memory, breakpoints.

Returns:: This probe’s debug interface.

spi() → DebugProbeSpi

Return the SPI controller, with the host adapters’ verbs.

Returns:: This probe’s SPI interface.

flash() → SpiFlash

Return the SPI NOR flash on the SPI pins.

Returns:: This probe’s flash interface.

target_flash() → TargetFlash

Return the target’s own flash, written through a CMSIS flash algorithm (.FLM).

Returns:: This probe’s target-flash interface.

property serial_number: str: USB serial of the open probe.

property last_firmware_status: int: Raw 16-bit firmware status of the most recent response.

set_timeout(timeout_ms: int) → None

Change the per-call response deadline.

Parameters:: timeout_ms – Deadline in milliseconds; -1 waits forever.

echo(data: bytes) → bytes

Round-trip data through the firmware.

Parameters:: data – Payload to echo.
Returns:: The bytes the firmware sent back.

property info: DebugProbeInfo

Firmware version, hardware variant and capability bits, cached at open().

Stable for the lifetime of the probe, even after close(). Use fetch_device_info() to issue a fresh firmware query.

fetch_device_info() → DebugProbeInfo

Issue a fresh device-info query and return the result.

Distinct from the info property, which returns the snapshot cached at open. No field changes while the probe stays connected.

Returns:: A freshly queried device info record.

settings() → DeviceSettings

Read the persisted settings record.

Returns:: The settings the probe boots with.

mode() → ProgMode | int

Read the persisted target protocol.

The live mode is info.active_mode; the two can differ.

Returns:: The persisted mode; a value newer than this package comes back as an int.

set_mode(mode: ProgMode) → None

Persist the target protocol. Nothing switches live.

Parameters:: mode – The protocol to boot with.
Raises:: ValidationError – If mode is not a ProgMode value; the firmware would store any byte.

swd_coexist_status() → SwdCoexistStatus

Report whether a host CMSIS-DAP session holds the SWD bus.

Returns:: The coexistence state.

pin_status() → PinStatus

Report which function holds the target pins.

Returns:: Pin class, holder bitmask and generation counter.

cdc1_config() → Cdc1Config

Read the CDC1 monitor-port configuration.

Returns:: Whether CDC1 is enabled, and its mode.

set_cdc1_config(config: Cdc1Config) → None

Persist the CDC1 monitor-port configuration.

A write that changes anything resets the probe about 100 ms later: this handle is dead afterwards, and the probe must be reopened.

Parameters:: config – The configuration to save.

enter_boot_mode() → None

Reboot into the bootloader and close this handle.

The probe drops off USB without answering; nothing more can be sent.

class pycosmicsdk.debugprobe.TargetPower(probe: DebugProbe)

Bases: _Part

The probe’s target rail (VDD_DUT) and its INA232 monitor.

fw-atira 1.0.x has one switch, set_output(). fw-atira 1.1 and newer split it into the signal voltage (I/O level plus on/off) and target power (header pin 1); each generation’s calls raise DEBUGPROBE_POWER_USE_* on the other, before anything is sent. Both are off after every boot.

reading() → PowerReading

Measure the target rail.

Not a way to tell a self-powered target on fw-atira 1.1 and newer: the reading lags 300-600 ms after a switch-off. Use signal_voltage_check() or signal_voltage_use_external().

Returns:: Voltage in mV, current in µA, power in mW.

monitor_active() → bool

Report whether the power-monitor chip answers.

This is monitor reachability, not whether the rail is on.

Returns:: True when a reading can be taken.

output() → bool

Report whether the target rail is switched on (fw-atira 1.0.x).

Returns:: True when the rail is on.
Raises:: FirmwareError – DEBUGPROBE_POWER_USE_SPLIT_CONTROLS on fw-atira 1.1 and newer.

set_output(on: bool) → None

Switch signal voltage and target power together (fw-atira 1.0.x).

Parameters:: on – True to power the target.
Raises:: FirmwareError – DEBUGPROBE_POWER_USE_SPLIT_CONTROLS on fw-atira 1.1 and newer.

signal_voltage_level() → int

Read the signal voltage set-point (fw-atira 1.1+); not a measurement.

Returns:: The level in mV.
Raises:: FirmwareError – DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x.

set_signal_voltage_level(millivolts: int) → None

Set the I/O level of every connector pin (fw-atira 1.1+).

Live when the signal voltage is on, stored for the next switch-on otherwise. A self-powered target needs its own level set before the signal voltage goes on.

Parameters:: millivolts – The level; the firmware owns the range (1200-5000 mV on Rev A/B).
Raises:: FirmwareError – FW_INVALID_PARAMETER outside the range, FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE on a fixed-level board, or DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x.

signal_voltage_enabled() → bool

Report whether the signal voltage is on (fw-atira 1.1+).

Returns:: True when it is on.
Raises:: FirmwareError – DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x.

set_signal_voltage_enabled(on: bool) → None

Switch the signal voltage (fw-atira 1.1+); off also switches target power off.

Parameters:: on – True to switch it on.
Raises:: FirmwareError – FW_UNHANDLED_ERROR when the rail did not reach power-good (rolled back to off), or DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x.

target_power_enabled() → bool

Report whether the probe feeds header pin 1 (fw-atira 1.1+).

Returns:: True when target power is on.
Raises:: FirmwareError – DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x.

set_target_power_enabled(on: bool) → None

Feed header pin 1 at the signal voltage (fw-atira 1.1+).

Decide whether the target powers itself with signal_voltage_check() first, never with one reading(), which lags after a switch-off.

Parameters:: on – True to power the target.
Raises:: FirmwareError – FW_INTERFACE_NOT_INITIALIZED while the signal voltage is off, FW_RESOURCE_BUSY while a supply is on pin 1 (self-powered; do not retry), FW_PIN1_OVERVOLTAGE above 5500 mV, or DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x.

signal_voltage_check() → SignalVoltageCheck

Compare the signal level against a fresh read of header pin 1; changes nothing.

With target power off, pin 1 is a self-powered target’s own supply: decide “self-powered” with this (or signal_voltage_use_external()), not with one reading(), which lags 300-600 ms after a switch-off. PIN1_OVERVOLTAGE is the one state that changes something: the probe switches its rails off. Needs fw-atira 1.1 or newer.

Returns:: The verdict, pin 1’s reading and the signal level, in mV.
Raises:: FirmwareError – DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x, refused before anything is sent.

signal_voltage_use_external() → int

Set the signal level to the self-powered target’s supply on pin 1 and switch it on.

Nothing is persisted. Needs fw-atira 1.1 or newer.

Returns:

The level set, in mV.

Raises:

SystemFirmwareError – FW_VOLTAGE_OUT_OF_RANGE: no usable supply on pin 1 (under 0.5 V, still falling, under about 1.59 V, or over 5000 mV).
FirmwareError – FW_RESOURCE_BUSY while target power is on, FW_PIN1_OVERVOLTAGE above 5500 mV, or DEBUGPROBE_POWER_USE_SET_OUTPUT on fw-atira 1.0.x (refused before anything is sent).

class pycosmicsdk.debugprobe.UartBridge(probe: DebugProbe)

Bases: _Part

The probe’s USB-to-UART bridge (CDC0).

property bridge_port: str: OS name of the bridge port; empty when not found.

config() → UartConfig

Read the bridge’s persisted line configuration.

Only flow_ctrl takes effect on current firmware; the line coding follows whatever the host sets on the CDC port.

Returns:: The persisted configuration.

configure(config: UartConfig) → None

Persist the bridge’s line configuration.

Parameters:: config – The configuration to save.

class pycosmicsdk.debugprobe.DebugTarget(probe: DebugProbe)

Bases: _Part

SWD debug session on the target: run control, registers, memory, breakpoints.

attach(*, under_reset: bool = False) → DebugState

Attach to the target over SWD.

Parameters:: under_reset – Hold nRESET while attaching, for a target that locks up SWD.
Returns:: The target’s state after attaching.

detach() → None: Release the target; it keeps running or stays halted as it was.

halt() → DebugState

Halt the core.

Returns:: The halted state, with pc.

run() → DebugState

Resume the core.

Returns:: The state after resuming.

step() → DebugState

Execute one instruction on a halted core.

Returns:: The halted state after the step.

state() → DebugState

Read whether the core is halted, where, and why.

Returns:: The current state.

reset(kind: DebugResetKind = DebugResetKind.SYSTEM) → DebugState

Reset the target.

Parameters:: kind – SYSTEM (SYSRESETREQ), CORE (ARMv7-M only) or HARDWARE (nRESET).
Returns:: The state after the reset.

read_register(reg: int) → int

Read a core register of the halted core.

Parameters:: reg – DCRSR register number (0-12 = r0-r12, 13 = sp, 14 = lr, 15 = pc).
Returns:: The register value.

write_register(reg: int, value: int) → None

Write a core register of the halted core.

Parameters:

reg – DCRSR register number.
value – The 32-bit value.

read_memory(address: int, length: int) → bytes

Read target memory.

Parameters:

address – Start address.
length – Number of bytes.

Returns:

The bytes read.

write_memory(address: int, data: bytes) → None

Write target memory. RAM only: flash is written by a flash algorithm.

Parameters:

address – Start address.
data – Bytes to write.

set_breakpoint(address: int) → int

Arm a hardware (FPB) breakpoint.

Parameters:: address – Instruction address.
Returns:: The comparator id, for clear_breakpoint().

clear_breakpoint(breakpoint_id: int) → None

Disarm a breakpoint.

Parameters:: breakpoint_id – The id set_breakpoint() returned.

breakpoints() → list[DebugBreakpoint]

List the armed breakpoints.

Returns:: One entry per armed comparator.

call_function(call: DebugCall) → int

Run a routine already in target memory and return its r0.

call.return_addr must already hold a breakpoint instruction.

Parameters:: call – Entry point, return trap, stack, and up to four arguments.
Returns:: r0 when the routine returned to the trap.

class pycosmicsdk.debugprobe.DebugProbeSpi(probe: DebugProbe)

Bases: _Part

SPI controller on the probe, with SpiController’s verbs.

initialize(*, bit_order: SpiBitOrder, mode: SpiMode, data_width: SpiDataWidth, chip_select: SpiChipSelect, chip_select_polarity: SpiChipSelectPolarity, frequency_hz: int) → DebugProbeSpi

Open the SPI controller session and return self for chaining.

Parameters:

bit_order – Whether each frame goes out most- or least-significant bit first.
mode – Clock polarity and phase pair.
data_width – Frame size, 8 or 16 bits.
chip_select – The routed line is board-specific: CS_2 (J4 pin 9) on Atira Rev A/B.
chip_select_polarity – Active-low or active-high chip select.
frequency_hz – SCK in Hz; Rev A/B refuses above 8 MHz.

Returns:

This interface, to allow chaining.

configure(*, bit_order: SpiBitOrder, mode: SpiMode, data_width: SpiDataWidth, chip_select: SpiChipSelect, chip_select_polarity: SpiChipSelectPolarity, frequency_hz: int) → None

Reconfigure the open session; refused while chip select is held.

Parameters:

bit_order – New frame bit order.
mode – New clock polarity and phase pair.
data_width – New frame size.
chip_select – New chip-select line.
chip_select_polarity – New chip-select polarity.
frequency_hz – New SCK in Hz.

release() → None

Close the SPI session, releasing a held chip select. Idempotent.

DebugProbe.close() also releases a session this handle opened.

parameters() → SpiParameters

Read the open session’s parameters.

Returns:: The parameters, typed.

status() → SpiSessionStatus

Read the session state and the live hash and list limits.

Returns:: The status; answers without an open session.

transfer(data: bytes) → bytes

Clock data out on MOSI and return what came back on MISO.

One full-duplex exchange under one chip-select envelope. To read a reply, pad data and slice the reply out of the result.

Parameters:: data – Frames to transmit, at most SPI_MAX_TRANSFER_LENGTH bytes.
Returns:: The frames received while data was clocked out.

transfer_chunk(tx: bytes, length: int, *, assert_cs: bool = False, release_cs: bool = False) → bytes

Clock one report (at most 58 bytes) inside a caller-managed CS envelope.

Parameters:

tx – At most 56 bytes to send; dummy zeros follow up to length.
length – Bytes to clock.
assert_cs – Assert chip select before clocking.
release_cs – Release chip select after clocking.

Returns:

Every clocked byte.

release_chip_select() → None: End a held chip-select envelope without clocking.

hash_start(algorithm: SpiHashAlgorithm = SpiHashAlgorithm.CRC32) → None

Reset the probe’s running hash.

Parameters:: algorithm – Hash algorithm.

hash_update(n: int) → None

Clock n dummy bytes into the running hash, inside the held envelope.

Parameters:: n – Bytes, at most status().hash_max_chunk.

hash_finish() → bytes

Collect the digest and clear the running hash.

Returns:: The digest bytes.

transfer_list(entries: list[SpiListEntry]) → SpiListResult

Run a transaction list on the probe.

Parameters:: entries – Transfers and polls, in order; flags takes SpiListFlag.
Returns:: How far the list ran, and the replies.

class pycosmicsdk.debugprobe.SpiFlash(probe: DebugProbe)

Bases: _Part

SPI NOR flash on the probe’s SPI pins; needs an open SPI session.

property last_transport: SpiTransport | None: Transport the last program() used (BULK or HID); None before one.

detect(override: FlashParams | None = None) → FlashParams

Identify the part (JEDEC id, then SFDP).

Parameters:: override – Parameters that win after the liveness check.
Returns:: The detected part’s parameters.

parameters() → FlashParams

Read the detected part’s parameters.

Returns:: The parameters from the last detect.

release() → None: Forget the detected part; the SPI session stays open.

read(address: int, length: int, progress: Callable[[int, int], None] | None = None) → bytes

Read flash.

Parameters:

address – Start address.
length – Bytes to read.
progress – Optional progress callback.

Returns:

The bytes read.

erase_sector(address: int) → None

Erase one sector.

Parameters:: address – Sector-aligned address.

erase(address: int, length: int, progress: Callable[[int, int], None] | None = None) → None

Erase every sector overlapping [address, address + length).

Parameters:

address – Start address.
length – Bytes to cover.
progress – Optional progress callback.

erase_chip() → None: Erase the whole part.

program(address: int, data: bytes, *, transport: SpiTransport = SpiTransport.AUTO, progress: Callable[[int, int], None] | None = None) → None

Program flash. Erase is not implied.

Parameters:

address – Start address.
data – Bytes to program.
transport – AUTO uses the bulk interface when it opens, else HID; BULK requires it; HID never uses it.
progress – Optional progress callback.

Raises:

CapabilityError – transport is BULK and the bulk interface is unavailable.

verify(address: int, data: bytes, *, method: FlashVerifyMethod = FlashVerifyMethod.READBACK, progress: Callable[[int, int], None] | None = None) → FlashCheck

Compare flash against data.

Parameters:

address – Start address.
data – Expected bytes.
method – READBACK reads the span back and compares on the host; HASH compares a CRC-32 computed on the probe and reads back only to locate a mismatch.
progress – Optional progress callback.

Returns:

Whether the span matched, and the first differing address if not.

blank_check(address: int, length: int) → FlashCheck

Check that a span is all 0xFF.

Parameters:

address – Start address.
length – Bytes to check.

Returns:

Whether the span is blank, and the first non-blank address if not.

hash(address: int, length: int, progress: Callable[[int, int], None] | None = None) → int

Compute a span’s CRC-32 on the probe.

Parameters:

address – Start address.
length – Bytes to hash.
progress – Optional progress callback.

Returns:

The CRC-32 (zlib’s).

bulk_available() → bool

Report whether the SPI bulk interface can be opened from this host.

Returns:: True when program() can use it.

last_bulk_stats() → SpiFlashBulkStats

Read the counters from the last bulk program.

Returns:: Pages, bounded polls and extra lists.

class pycosmicsdk.debugprobe.TargetFlash(probe: DebugProbe)

Bases: _Part

The target’s own flash, programmed by a CMSIS flash algorithm over the debug session.

Needs an attached session (DebugTarget.attach()). Every operation resets and halts the target before and after, success or failure, and leaves it halted: call DebugTarget.run() to start it. One algorithm per probe, held host-side.

load_algorithm(flm: bytes | str | PathLike[str], *, ram: tuple[int, int]) → TargetFlashInfo

Parse and validate a .FLM against a RAM window; touches nothing on the target.

Replaces any algorithm loaded before.

Parameters:

flm – The .FLM bytes, or a path to the file.
ram – (start, size) of target RAM the algorithm, its stack and one page buffer run in.

Returns:

The algorithm’s flash description.

info() → TargetFlashInfo

Read the loaded algorithm’s flash description.

Returns:: The description from the last load_algorithm().

unload_algorithm() → None: Drop the loaded algorithm. Idempotent.

static list_pack_devices(pack: bytes | str | PathLike[str]) → list[TargetFlashPackDevice]

List every device a CMSIS-Pack names, with whether it can be flashed.

Host-side: needs no open probe and touches no target. Devices come in the pack’s order, each with its orderable variant names.

Parameters:: pack – The .pack bytes, or a path to the file.
Returns:: One entry per device; empty for a pack that lists none.
Raises:: DebugError – DEBUGPROBE_TFLASH_BAD_PACK: not a pack the SDK can read.

load_pack_device(pack: bytes | str | PathLike[str], device: str, *, confirmed_connect_steps: Sequence[str]) → TargetFlashInfo

Load the flash algorithm a pack names for one of its devices.

Takes the place of load_algorithm(), with the RAM window from the pack. confirmed_connect_steps has no default on purpose: pass the device’s connect_steps exactly as listed once the user has accepted that the SDK skips them, or an empty list for a FLASHABLE device.

Parameters:

pack – The .pack bytes, or a path to the file.
device – A device name from list_pack_devices() (not a variant).
confirmed_connect_steps – The connect steps the user confirmed.

Returns:

The loaded algorithm’s flash description.

Raises:

DebugError – DEBUGPROBE_TFLASH_BAD_PACK, _PACK_NO_DEVICE, _PACK_UNSUPPORTED, _PACK_NEEDS_CONFIRM (nothing loaded, a previous algorithm stays), _BAD_ALGORITHM or _RAM_WINDOW.

erase(address: int, length: int, progress: Callable[[int, int], bool | None] | None = None) → None

Erase every sector overlapping [address, address + length).

Bytes of those sectors outside the range are lost.

Parameters:

address – Start address.
length – Bytes to cover.
progress – Optional progress callback; can cancel.

erase_chip(progress: Callable[[int, int], bool | None] | None = None) → None

Erase the whole flash region.

Uses the algorithm’s chip erase when it has one (info().has_erase_chip), else erases every sector.

Parameters:: progress – Optional progress callback; can cancel.

program(address: int, data: bytes, progress: Callable[[int, int], bool | None] | None = None) → None

Program data at address. Erase is not implied.

Parameters:

address – Start address.
data – Bytes to program.
progress – Optional progress callback; can cancel.

verify(address: int, data: bytes, progress: Callable[[int, int], bool | None] | None = None) → FlashCheck

Read flash back with the core halted and compare against data.

Parameters:

address – Start address.
data – Expected bytes.
progress – Optional progress callback; can cancel.

Returns:

Whether the span matched, and the first differing address if not.

write(address: int, data: bytes, *, verify: bool = True, progress: Callable[[int, int], bool | None] | None = None) → None

Erase the touched sectors, program, and optionally verify, in one algorithm session.

last_report() says how far it got, success or not.

Parameters:

address – First byte to write.
data – The image.
verify – Read back and compare after programming.
progress – Optional progress callback; can cancel.

Raises:

TargetFlashVerifyError – The readback differed; first_mismatch is the first differing address. verify() returns this as a result instead, since comparing is all it does.

last_report() → TargetFlashReport

Read what the last operation did, success or not.

Returns:: Whether the target was touched, the range actually erased, the failing routine and its r0, whether the final reset held, and the pack connect steps that were skipped.

AsyncDebugProbe

Every call runs the blocking method in the default executor, one at a time per probe: the SDK’s debug and flash calls have no non-blocking form. The sub-objects mirror the blocking ones (AsyncTargetPower, AsyncDebugTarget, …).

class pycosmicsdk.AsyncDebugProbe(probe: DebugProbe)

Bases: object

An open debug probe for asyncio code. Construct with open().

classmethod open(*, serial: str | None = None, path: str | None = None, timeout_ms: int = 5000) → _Opener

Open a debug probe; await the result or use it with async with.

Parameters:

serial – USB serial to match; the first probe found when omitted.
path – HID path to open instead of matching a serial.
timeout_ms – Per-call response deadline.

Returns:

An opener that connects on await or async with.

async close() → None: Release the probe. Idempotent.

power() → AsyncTargetPower: Async DebugProbe.power().

uart() → AsyncUartBridge: Async DebugProbe.uart().

debug() → AsyncDebugTarget: Async DebugProbe.debug().

spi() → AsyncDebugProbeSpi: Async DebugProbe.spi().

flash() → AsyncSpiFlash: Async DebugProbe.flash().

target_flash() → AsyncTargetFlash: Async DebugProbe.target_flash().

property serial_number: str: DebugProbe.serial_number; local state, so no executor hop.

property last_firmware_status: int: DebugProbe.last_firmware_status; local state, so no executor hop.

set_timeout(timeout_ms: int) → None: DebugProbe.set_timeout(); a local setting, so no executor hop.

async echo(data: bytes) → bytes: Async DebugProbe.echo().

property info: DebugProbeInfo: DebugProbe.info; cached at open, so no executor hop.

async fetch_device_info() → DebugProbeInfo: Async DebugProbe.fetch_device_info().

async settings() → DeviceSettings: Async DebugProbe.settings().

async mode() → ProgMode | int: Async DebugProbe.mode().

async set_mode(mode: ProgMode) → None: Async DebugProbe.set_mode().

async swd_coexist_status() → SwdCoexistStatus: Async DebugProbe.swd_coexist_status().

async pin_status() → PinStatus: Async DebugProbe.pin_status().

async cdc1_config() → Cdc1Config: Async DebugProbe.cdc1_config().

async set_cdc1_config(config: Cdc1Config) → None: Async DebugProbe.set_cdc1_config().

async enter_boot_mode() → None: Async DebugProbe.enter_boot_mode().

class pycosmicsdk.debugprobe_async.AsyncTargetPower(probe: AsyncDebugProbe)

Bases: _AsyncPart

Asyncio twin of TargetPower.

async reading() → PowerReading: Async reading().

async monitor_active() → bool: Async monitor_active().

async output() → bool: Async output().

async set_output(on: bool) → None: Async set_output().

async signal_voltage_level() → int: Async signal_voltage_level().

async set_signal_voltage_level(millivolts: int) → None: Async set_signal_voltage_level().

async signal_voltage_enabled() → bool: Async signal_voltage_enabled().

async set_signal_voltage_enabled(on: bool) → None: Async set_signal_voltage_enabled().

async target_power_enabled() → bool: Async target_power_enabled().

async set_target_power_enabled(on: bool) → None: Async set_target_power_enabled().

async signal_voltage_check() → SignalVoltageCheck: Async signal_voltage_check().

async signal_voltage_use_external() → int: Async signal_voltage_use_external().

class pycosmicsdk.debugprobe_async.AsyncUartBridge(probe: AsyncDebugProbe)

Bases: _AsyncPart

Asyncio twin of UartBridge.

property bridge_port: str: bridge_port; no executor hop.

async config() → UartConfig: Async config().

async configure(config: UartConfig) → None: Async configure().

class pycosmicsdk.debugprobe_async.AsyncDebugTarget(probe: AsyncDebugProbe)

Bases: _AsyncPart

Asyncio twin of DebugTarget.

async attach(*, under_reset: bool = False) → DebugState: Async attach().

async detach() → None: Async detach().

async halt() → DebugState: Async halt().

async run() → DebugState: Async run().

async step() → DebugState: Async step().

async state() → DebugState: Async state().

async reset(kind: DebugResetKind = DebugResetKind.SYSTEM) → DebugState: Async reset().

async read_register(reg: int) → int: Async read_register().

async write_register(reg: int, value: int) → None: Async write_register().

async read_memory(address: int, length: int) → bytes: Async read_memory().

async write_memory(address: int, data: bytes) → None: Async write_memory().

async set_breakpoint(address: int) → int: Async set_breakpoint().

async clear_breakpoint(breakpoint_id: int) → None: Async clear_breakpoint().

async breakpoints() → list[DebugBreakpoint]: Async breakpoints().

async call_function(call: DebugCall) → int: Async call_function().

class pycosmicsdk.debugprobe_async.AsyncDebugProbeSpi(probe: AsyncDebugProbe)

Bases: _AsyncPart

Asyncio twin of DebugProbeSpi.

async initialize(*, bit_order: SpiBitOrder, mode: SpiMode, data_width: SpiDataWidth, chip_select: SpiChipSelect, chip_select_polarity: SpiChipSelectPolarity, frequency_hz: int) → AsyncDebugProbeSpi: Async initialize(); returns self.

async configure(*, bit_order: SpiBitOrder, mode: SpiMode, data_width: SpiDataWidth, chip_select: SpiChipSelect, chip_select_polarity: SpiChipSelectPolarity, frequency_hz: int) → None: Async configure().

async release() → None: Async release().

async parameters() → SpiParameters: Async parameters().

async status() → SpiSessionStatus: Async status().

async transfer(data: bytes) → bytes: Async transfer().

async transfer_chunk(tx: bytes, length: int, *, assert_cs: bool = False, release_cs: bool = False) → bytes: Async transfer_chunk().

async release_chip_select() → None: Async release_chip_select().

async hash_start(algorithm: SpiHashAlgorithm = SpiHashAlgorithm.CRC32) → None: Async hash_start().

async hash_update(n: int) → None: Async hash_update().

async hash_finish() → bytes: Async hash_finish().

async transfer_list(entries: list[SpiListEntry]) → SpiListResult: Async transfer_list().

class pycosmicsdk.debugprobe_async.AsyncSpiFlash(probe: AsyncDebugProbe)

Bases: _AsyncPart

Asyncio twin of SpiFlash.

property last_transport: SpiTransport | None: last_transport; no executor hop.

async detect(override: FlashParams | None = None) → FlashParams: Async detect().

async parameters() → FlashParams: Async parameters().

async release() → None: Async release().

async read(address: int, length: int, progress: Callable[[int, int], None] | None = None) → bytes: Async read().

async erase_sector(address: int) → None: Async erase_sector().

async erase(address: int, length: int, progress: Callable[[int, int], None] | None = None) → None: Async erase().

async erase_chip() → None: Async erase_chip().

async program(address: int, data: bytes, *, transport: SpiTransport = SpiTransport.AUTO, progress: Callable[[int, int], None] | None = None) → None: Async program().

async verify(address: int, data: bytes, *, method: FlashVerifyMethod = FlashVerifyMethod.READBACK, progress: Callable[[int, int], None] | None = None) → FlashCheck: Async verify().

async blank_check(address: int, length: int) → FlashCheck: Async blank_check().

async hash(address: int, length: int, progress: Callable[[int, int], None] | None = None) → int: Async hash().

async bulk_available() → bool: Async bulk_available().

async last_bulk_stats() → SpiFlashBulkStats: Async last_bulk_stats().

class pycosmicsdk.debugprobe_async.AsyncTargetFlash(probe: AsyncDebugProbe)

Bases: _AsyncPart

Asyncio twin of TargetFlash.

The progress callback runs on the executor thread.

async load_algorithm(flm: bytes | str | PathLike[str], *, ram: tuple[int, int]) → TargetFlashInfo: Async load_algorithm().

async info() → TargetFlashInfo: Async info().

async unload_algorithm() → None: Async unload_algorithm().

async static list_pack_devices(pack: bytes | str | PathLike[str]) → list[TargetFlashPackDevice]: Async list_pack_devices(), off the loop.

async load_pack_device(pack: bytes | str | PathLike[str], device: str, *, confirmed_connect_steps: Sequence[str]) → TargetFlashInfo: Async load_pack_device().

async erase_chip(progress: Callable[[int, int], bool | None] | None = None) → None: Async erase_chip().

async erase(address: int, length: int, progress: Callable[[int, int], bool | None] | None = None) → None: Async erase().

async program(address: int, data: bytes, progress: Callable[[int, int], bool | None] | None = None) → None: Async program().

async verify(address: int, data: bytes, progress: Callable[[int, int], bool | None] | None = None) → FlashCheck: Async verify().

async write(address: int, data: bytes, *, verify: bool = True, progress: Callable[[int, int], bool | None] | None = None) → None: Async write().

async last_report() → TargetFlashReport: Async last_report().

Enums and results

class pycosmicsdk.ProgMode(*values)

Bases: IntEnum

The protocol a debug probe is configured for (persisted, not live).

IDLE: No target protocol selected.

SWD_ACTIVE: SWD (CMSIS-DAP).

JTAG_ACTIVE: JTAG.

ICSP_ACTIVE: ICSP.

UPDI_ACTIVE: UPDI.

SWO_ACTIVE: SWO capture.

SPI_ACTIVE: SPI controller.

class pycosmicsdk.FlashVerifyMethod(*values)

Bases: StrEnum

How pycosmicsdk.debugprobe.SpiFlash.verify() compares flash against the expected bytes.

READBACK: Read the span back over USB and compare on the host.

HASH: Compare a CRC-32 computed on the probe; reads back to the host only on a mismatch, to locate it.

class pycosmicsdk.FlashCheck(passed: bool, first_mismatch: int | None)

Bases: object

Outcome of a flash verify or blank check.

passed

True when the span matched.

Type:: bool

first_mismatch

First differing address; None when passed.

Type:: int | None

class pycosmicsdk.debugprobe.SpiHashAlgorithm(*values)

Bases: IntEnum

Running-hash algorithm of DebugProbeSpi.hash_start().

CRC32: CRC-32, zlib’s polynomial and output.

class pycosmicsdk.debugprobe.SpiListFlag(*values)

Bases: IntFlag

Flags of one SpiListEntry.

CS_ASSERT: Assert chip select before this entry.

CS_RELEASE: Release chip select after this entry.

POLL: Repeat the entry until its SpiPoll condition holds.

DISCARD_RX: Do not return this entry’s received bytes.

class pycosmicsdk.debugprobe.SpiParameters(bit_order: SpiBitOrder, mode: SpiMode, data_width: SpiDataWidth, chip_select: SpiChipSelect, chip_select_polarity: SpiChipSelectPolarity, frequency_hz: int)

Bases: object

Parameters of the open SPI session.

bit_order

Frame bit order.

Type:: pycosmicsdk._cpp._pycosmicsdk_cpp.SpiBitOrder

mode

Clock polarity and phase pair.

Type:: pycosmicsdk._cpp._pycosmicsdk_cpp.SpiMode

data_width

Frame size.

Type:: pycosmicsdk._cpp._pycosmicsdk_cpp.SpiDataWidth

chip_select

Chip-select line.

Type:: pycosmicsdk._cpp._pycosmicsdk_cpp.SpiChipSelect

chip_select_polarity

Chip-select polarity.

Type:: pycosmicsdk._cpp._pycosmicsdk_cpp.SpiChipSelectPolarity

frequency_hz

SCK frequency in Hz.

Type:: int

class pycosmicsdk.debugprobe.SpiSessionStatus(active: bool, cs_held: bool, parameters: SpiParameters | None, features: int, hash_max_chunk: int, hash_running: bool, list_max_entries: int, poll_max_iterations: int, poll_max_us: int)

Bases: object

SPI session state and the probe’s live hash and list limits.

active

Whether a session is open.

Type:: bool

cs_held

Whether chip select is held between calls.

Type:: bool

parameters

The session’s parameters; None without an open session.

Type:: pycosmicsdk.debugprobe.SpiParameters | None

features

Firmware feature bits.

Type:: int

hash_max_chunk

Largest DebugProbeSpi.hash_update().

Type:: int

hash_running

Whether a running hash is open.

Type:: bool

list_max_entries

Largest DebugProbeSpi.transfer_list().

Type:: int

poll_max_iterations

Poll iteration bound.

Type:: int

poll_max_us

Poll time bound in microseconds.

Type:: int

Data types

Records the probe methods return or take, bound from the SDK. PowerReading is in mV, µA and mW.

class pycosmicsdk.debugprobe.DebugProbeInfo(fw_major: int, fw_minor: int, fw_patch: int, hw_variant: int, capabilities: int, active_mode: ProgMode | int, num_uart_ports: int)

Bases: object

Firmware version, hardware variant and capability bits of a debug probe.

fw_major

Firmware major version.

Type:: int

fw_minor

Firmware minor version.

Type:: int

fw_patch

Firmware patch version.

Type:: int

hw_variant

Hardware variant.

Type:: int

capabilities

Capability bits, e.g. CAP_STATUS16.

Type:: int

active_mode

The live target protocol; a value newer than this package is an int.

Type:: pycosmicsdk.debugprobe.ProgMode | int

num_uart_ports

Number of UART bridge ports.

Type:: int

fw_major: int

fw_minor: int

fw_patch: int

hw_variant: int

capabilities: int

active_mode: ProgMode | int

num_uart_ports: int

class pycosmicsdk.debugprobe.DeviceSettings(*args, **kwargs)

Bases: object

property cdc1_enabled: (self) -> bool

property cdc1_mode: (self) -> int

property target_power_en: (self) -> bool

property target_protocol: (self) -> int

property uart_baud: (self) -> int

property uart_data_bits: (self) -> int

property uart_flow_ctrl: (self) -> int

property uart_parity: (self) -> int

property uart_stop_bits: (self) -> int

class pycosmicsdk.debugprobe.UartConfig(*args, **kwargs)

Bases: object

property baud: (self) -> int

property data_bits: (self) -> int

property flow_ctrl: (self) -> int

property parity: (self) -> int

property stop_bits: (self) -> int

class pycosmicsdk.debugprobe.Cdc1Config(*args, **kwargs)

Bases: object

property enabled: (self) -> bool

property mode: (self) -> int

class pycosmicsdk.debugprobe.PinStatus(*args, **kwargs)

Bases: object

property capture_uart: (self) -> int | None

property generation: (self) -> int

property holders: (self) -> int

property pin_class: (self) -> int

property refcount: (self) -> int

class pycosmicsdk.debugprobe.SwdCoexistStatus(*args, **kwargs)

Bases: object

property deferring: (self) -> bool

property host_armed: (self) -> bool

property ms_since_host_transfer: (self) -> int

property swd_holders: (self) -> int

class pycosmicsdk.debugprobe.PowerReading(*args, **kwargs)

Bases: object

property current_ua: (self) -> int

property power_mw: (self) -> int

property voltage_mv: (self) -> int

class pycosmicsdk.debugprobe.SignalVoltageCheck(*args, **kwargs)

Bases: object

property level_mv: (self) -> int

property state: (self) -> pycosmicsdk._cpp._pycosmicsdk_cpp_debugprobe.SignalVoltageState

property target_mv: (self) -> int

class pycosmicsdk.debugprobe.TargetFlashInfo(*args, **kwargs)

Bases: object

property device_name: (self) -> str

property erase_sector_timeout_ms: (self) -> int

property erased_value: (self) -> int

property flash_base: (self) -> int

property flash_size: (self) -> int

property has_erase_chip: (self) -> bool

property has_verify: (self) -> bool

property page_size: (self) -> int

property program_page_timeout_ms: (self) -> int

property sector_count: (self) -> int

class pycosmicsdk.debugprobe.TargetFlashReport(*args, **kwargs)

Bases: object

property bytes_programmed: (self) -> int

property connect_steps_skipped: (self) -> list[str]

property elapsed_ms: (self) -> int

property erased_addr: (self) -> int

property erased_bytes: (self) -> int

property failed_r0: (self) -> int

property failed_routine: (self) -> pycosmicsdk._cpp._pycosmicsdk_cpp_debugprobe.TargetFlashRoutine

property final_reset_ok: (self) -> bool

property first_mismatch: (self) -> int

property sectors_erased: (self) -> int

property target_touched: (self) -> bool

property verify_mismatch: (self) -> bool

class pycosmicsdk.debugprobe.TargetFlashPackDevice(*args, **kwargs)

Bases: object

property connect_steps: (self) -> list[str]

property family: (self) -> str

property flash_base: (self) -> int

property flash_size: (self) -> int

property multi_core: (self) -> bool

property name: (self) -> str

property reason: (self) -> str

property support: (self) -> pycosmicsdk._cpp._pycosmicsdk_cpp_debugprobe.TargetFlashPackSupport

property variants: (self) -> list[str]

property vendor: (self) -> str

class pycosmicsdk.debugprobe.SignalVoltageState(*values)

Bases: Enum

NO_SUPPLY = 0

MATCH = 1

SIGNAL_HIGHER = 2

SIGNAL_LOWER = 3

ATIRA_POWERED = 4

BACK_POWERED = 5

PIN1_OVERVOLTAGE = 6

class pycosmicsdk.debugprobe.TargetFlashRoutine(*values)

Bases: Enum

NONE = 0

INIT = 1

UNINIT = 2

ERASE_SECTOR = 3

PROGRAM_PAGE = 4

LOAD = 5

ERASE_CHIP = 6

class pycosmicsdk.debugprobe.TargetFlashPackSupport(*values)

Bases: Enum

FLASHABLE = 0

NEEDS_CONNECT_STEPS = 1

NOT_SUPPORTED = 2

class pycosmicsdk.debugprobe.DebugState(*args, **kwargs)

Bases: object

property attached: (self) -> bool

property halted: (self) -> bool

property pc: (self) -> int

property stop_reason: (self) -> pycosmicsdk._cpp._pycosmicsdk_cpp_debugprobe.DebugStopReason

class pycosmicsdk.debugprobe.DebugStopReason(*values)

Bases: Enum

RUNNING = 0

REQUEST = 1

BREAKPOINT = 2

WATCHPOINT = 3

STEP = 4

RESET = 5

class pycosmicsdk.debugprobe.DebugResetKind(*values)

Bases: Enum

SYSTEM = 0

CORE = 1

HARDWARE = 2

class pycosmicsdk.debugprobe.DebugBreakpoint(*args, **kwargs)

Bases: object

property addr: (self) -> int

property id: (self) -> int

class pycosmicsdk.debugprobe.DebugCall(*args, **kwargs)

Bases: object

property args: (self) -> list[int]

property entry: (self) -> int

property poll_rounds: (self) -> int

property return_addr: (self) -> int

property stack_pointer: (self) -> int

property static_base: (self) -> int

class pycosmicsdk.debugprobe.SpiPoll(*args, **kwargs)

Bases: object

property mask: (self) -> int

property max_iterations: (self) -> int

property max_us: (self) -> int

property offset: (self) -> int

property value: (self) -> int

class pycosmicsdk.debugprobe.SpiListEntry(*args, **kwargs)

Bases: object

property flags: (self) -> int

property payload: (self) -> bytes

property poll: (self) -> pycosmicsdk._cpp._pycosmicsdk_cpp_debugprobe.SpiPoll | None

property transfer_len: (self) -> int

class pycosmicsdk.debugprobe.SpiListResult(*args, **kwargs)

Bases: object

property entries_executed: (self) -> int

property outcome: (self) -> int

property poll_iterations: (self) -> int

property replies: (self) -> list[bytes]

property rx: (self) -> bytes

class pycosmicsdk.debugprobe.FlashParams(*args, **kwargs)

Bases: object

property address_bytes: (self) -> int

property capacity: (self) -> int

property chip_erase_op: (self) -> int

property erase_types: (self) -> list[pycosmicsdk._cpp._pycosmicsdk_cpp_debugprobe.FlashEraseType]

property name: (self) -> str

property page_size: (self) -> int

property program_op: (self) -> int

property read_op: (self) -> int

property sector_erase_op: (self) -> int

property sector_size: (self) -> int

class pycosmicsdk.debugprobe.FlashEraseType(*args, **kwargs)

Bases: object

property opcode: (self) -> int

property size: (self) -> int

class pycosmicsdk.debugprobe.SpiFlashBulkStats(*args, **kwargs)

Bases: object

property bounded_polls: (self) -> int

property extra_lists: (self) -> int

property pages: (self) -> int