Python API Overview

Python API Overview

PyCommander's Python API is layered. From lowest to highest level:

1. Commander — a 1:1 mirror of the Simplicity Commander CLI. Each command suite is a sub-object and each method returns the raw command 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.

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

from pycommander import Commander, Adapter, Target, AemStream

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, set CTUNE, provision keys, lock/unlock, region config	Target
Continuously read current/voltage/power	AemStream

The high-level classes are built on top of Commander — you can always drop down a level when you need an option the helpers don't expose.

Connecting to an adapter

Every entry-point class accepts the same connection parameters. Provide at most one of these to select the adapter (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).

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, the following optional parameters map directly to Commander's debug options and are applied to the 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 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.

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.