Getting Started

Getting Started

This page walks you through your first interactions with PyCommander, both from the command line and from Python. If you have not installed it yet, start with Installation.

Most examples use a serial (J-Link) number to select the adapter. You can also connect by IP address or serial port — see Python-API-Overview for the full set of connection options.

1. Confirm everything works

pycommander --version

You should see the PyCommander version followed by the embedded Simplicity Commander version information.

2. Run a command from the terminal

The pycommander command is a drop-in replacement for the Simplicity Commander CLI — anything the CLI can do, pycommander can do, with identical output:

pycommander device info --device EFR32MG24 --serialno 440055955
pycommander flash firmware.hex --device EFR32FG28 --serialno 440055956

More on the terminal experience in Command-Line-Interface.

3. Drive Commander from Python

The Python API offers three layers of abstraction. Pick the one that matches how close to the metal you want to be.

The Commander class — mirror the CLI

Commander mirrors the CLI surface 1:1. Methods take the same arguments as the CLI commands and return a dict (equivalent to running the CLI with --json).

from pathlib import Path
from pycommander import Commander

commander = Commander(serial_number="440055955")

commander.device.info(target_device="EFR32MG24")
commander.flash.flash(filenames=[Path("firmware.hex")])

Full details: Commander-Class.

The Adapter class — work with Silicon Labs adapters

Adapter provides convenience methods for common adapter tasks: VCOM setup, supply voltage, energy analysis, and more. It also gives you access to the underlying Commander and an optional Target.

from pycommander import Adapter
from pycommander_core.types import VcomHandshake

adapter = Adapter(serial_number="440055955")
print(adapter.info())

adapter.setVoltage(voltage=1.8)
adapter.setVcomConfig(baudrate=115200, handshake=VcomHandshake.RTSCTS)

result = adapter.analyzeEnergyUsage(duration_s=10, cluster_states=True, detect_period=True)
print(result.clustering.unique_states)
print(result.signal_characteristics.min_current_ma)
print(result.signal_characteristics.max_current_ma)

Full details: Adapter-Class.

The Target class — work with the device

Target provides convenience methods for the target device: flashing, erasing, CTUNE, security, key provisioning, and more.

from pathlib import Path
from pycommander import Commander, Target

commander = Commander(serial_number="440055955")
target = Target(part_number="EFR32MG24", commander=commander)
print(target.info())

target.setCTUNE(value=0xa8)
target.flashApplication(filenames=[Path("firmware.hex")], masserase=True, verify=True)
target.enableWriteProtection(ranges=[(0x00000000, 0x00008000), (0x0000A000, 0x0000C000)])

Full details: Target-Class.

4. A complete kit session

A Adapter with a target_device represents a complete Silicon Labs kit (adapter + radio board). The Target is created for you and attached as adapter.target:

from pathlib import Path
from pycommander import Adapter
from pycommander_core.types import AdapterInfo, AdapterVoltageInfo, VcomHandshake, CtuneValue

adapter = Adapter(serial_number="440055955", target_device="EFR32MG24")

# Adapter-level tasks
adapter_info: AdapterInfo = adapter.info()
voltage_info: AdapterVoltageInfo | None = adapter.getVoltage()
adapter.setVcomConfig(115200, VcomHandshake.RTSCTS, True)

# Target-level tasks via adapter.target
ctune: CtuneValue = adapter.target.getCTUNE()
adapter.target.setCTUNE(ctune.board)
adapter.target.flashApplication(filenames=[Path("firmware.hex")])

5. Handle failures and keep a log

Failed Commander invocations raise typed exceptions, and you can record every invocation to a log file:

from pathlib import Path
from pycommander import Adapter, Commander
from pycommander_core.errors import PyCommanderError, PyCommanderRuntimeError

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

try:
    adapter.target.flashApplication(filenames=[Path("firmware.hex")])
except PyCommanderRuntimeError as e:
    print(f"Commander failed at runtime: {e}")
except PyCommanderError as e:
    print(f"Other Commander error: {e}")

Learn more in Error-Handling and Logging.

Next steps

• Python-API-Overview — the design of the API and the shared connection/debug options.
• Command-Reference — look up any of the ~20 Commander command suites.
• AEM-and-Energy-Measurement — stream and analyze energy data.