Python API Overview

Python API Overview

PyCommander's Python API includes a command layer, task-oriented helpers, and live streams:

1. Commander — a low-level wrapper for supported Simplicity Commander commands. Command suites are sub-objects; command methods return output as a dict (as if you had run the CLI with --json).
2. Adapter — task-oriented helpers for Silicon Labs adapters (kit/debugger).
3. Target — task-oriented helpers for the target device (MCU/SoC).
4. AemStream — a Pythonic, unbounded stream of energy measurements.
5. Console streams — SwoConsoleStream, RttConsoleStream, VcomConsoleStream, and VuartConsoleStream capture target console output.

All are importable straight from the flavor-aware top-level package:

from pycommander import (
    Commander, Adapter, Target, AemStream,
    SwoConsoleStream, RttConsoleStream, VcomConsoleStream, VuartConsoleStream,
)

Typed return values live in the pycommander_core.types module, and exceptions in pycommander_core.errors. See Data-Types and Error-Handling.

Import source. from pycommander import ... resolves to the GUI flavor if installed, otherwise the CLI flavor. You can also import explicitly from pycommander_cli or pycommander_gui; the classes are identical apart from which Commander executable they run. See Architecture-and-Packages.

Choosing a layer

You want to…	Use
Run an arbitrary CLI command and read its JSON	Commander
Configure VCOM / supply voltage / read kit info / analyze energy	Adapter
Flash, erase, read memory, set CTUNE, provision keys, lock/unlock, region config	Target
Continuously read current/voltage/power	AemStream
Continuously read SWO, RTT, VCOM, or VUART output	The matching console stream class

The high-level helpers and streams use Commander internally. For options they do not expose, use the lower-level API or the pycommander CLI.

Connecting to an adapter

Commander and Adapter accept these adapter selectors. Provide at most one (passing more than one raises ValueError):

Parameter	Selects the adapter by	CLI equivalent
serial_number	J-Link serial number	--serialno
ip_address	network address	--ip
serial_port	serial port	--identifybyserialport

If you provide none, Commander uses its default selection (e.g. the only connected adapter).

AemStream, SwoConsoleStream, RttConsoleStream, and VcomConsoleStream accept serial_number or ip_address. VuartConsoleStream requires ip_address; it does not accept a serial number. See Console-Streams for the exact constructors. Target takes a Commander object rather than selecting an adapter itself.

from pycommander import Commander

by_serial = Commander(serial_number="440055955")
by_ip     = Commander(ip_address="192.168.1.42")
by_port   = Commander(serial_port="/dev/tty.usbmodem1234")

Selecting the target device

Pass target_device (the part number, e.g. "EFR32MG24") to apply --device to commands that need it. On Adapter, providing target_device also auto-creates a Target and attaches it as adapter.target.

Debug interface options

For advanced debug setups, Commander and Adapter accept the following optional parameters. They map directly to Commander's debug options and are applied to commands that support them:

Parameter	CLI equivalent	Meaning
debug_speed	--speed	Debug clock speed
debug_tif	--tif	Target interface (e.g. SWD/JTAG)
debug_irpre	--irpre	IR pre value (JTAG chain)
debug_drpre	--drpre	DR pre value (JTAG chain)

Logging and the executable path

Two more Commander constructor options are commonly useful:

• log_file_path — a pathlib.Path; when set, every Commander invocation is appended to this file with a timestamp. See Logging.
• executable_path — a pathlib.Path to a specific Commander executable, bypassing the bundled one. Useful for testing against a particular Commander build.

from pathlib import Path
from pycommander import Commander

commander = Commander(
    serial_number="440055955",
    target_device="EFR32MG24",
    log_file_path=Path("pycommander.log"),
)

Per-call overrides

Most Commander command methods accept **kwargs that let you override connection/debug/device options for a single call without rebuilding the object. Recognized keys include serial_number, ip_address, serial_port, debug_speed, debug_tif, debug_irpre, debug_drpre, target_device, force, and devicexml.

commander = Commander()  # no fixed adapter
commander.device.info(serial_number="440055955", target_device="EFR32MG24")
commander.device.info(serial_number="440055956", target_device="EFR32FG28")

Working with multiple kits

Create one entry-point object per kit. They are independent:

from pycommander import Adapter

serial_numbers = ["440055955", "440055956", "440055957"]
adapters = [Adapter(serial_number=sn, target_device="EFR32MG24") for sn in serial_numbers]
for adapter in adapters:
    print(adapter.info())

What gets returned

• Commander methods return a dict — the parsed JSON output of the underlying command (typically containing a success flag and a result object). For non-JSON output, see runCommand on the Commander-Class.
• Adapter / Target methods return typed dataclasses from Data-Types, or simple bool/None values for actions and look-ups that can fail. By convention, a query that fails returns None, and an action returns True/False. Target.readmem returns a bytearray, or None if the read failed.

Error handling in one paragraph

A failed Commander invocation raises one of PyCommanderInputError, PyCommanderRuntimeError, or the base PyCommanderError. A timeout raises TimeoutError. Argument validation in the helpers raises ValueError / FileNotFoundError before Commander is even invoked. Full details and examples: Error-Handling.