Skip to content

Target Class

Jump to bottom
Espen Hovland edited this page Jun 5, 2026 · 2 revisions

Target class

Target is a high-level interface for the target device — the Silicon Labs MCU/SoC behind the adapter. It works with any supported debug adapter (Silicon Labs or generic J-Link). It covers flashing, erasing, CTUNE, flash protection, security/Secure Engine, key provisioning, and Series 3 code-region configuration.

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.flashApplication(filenames=[Path("firmware.hex")], masserase=True, verify=True)

Construction

Target(part_number: str, commander: CommanderBase)
  • part_number — the device part number (e.g. "EFR32MG24"); applied as --device to the underlying commands.
  • commander — a Commander/CommanderBase providing the connection.

When you build an Adapter with a target_device, a Target is created automatically and attached as adapter.target.

Return conventions. Look-ups return a typed dataclass (see Data-Types) or None on failure. Actions return bool. Methods that take file paths raise FileNotFoundError if a file is missing, and some raise ValueError for invalid arguments — all before Commander is invoked.

⚠️ Several security operations write to OTP memory or permanently change device lifecycle state. These are flagged below and typically gated behind a confirm argument. They cannot be undone.

Device info & reset

info() -> TargetInfo | None

Return a TargetInfo (part number, die revision, production version, flash/SRAM size, unique ID), or None.

reset() -> bool

Reset the target device.

Erasing

masserase() -> bool

Mass-erase the device, clearing the main flash.

pageerase(ranges=[], regions=[]) -> bool

Erase selected flash pages.

  • ranges: list[tuple[int|str, int|str]] — (start, end) ranges; extended to page boundaries.
  • regions: list[str] — named memory regions (@region).

Flashing

flashApplication(filenames, address=None, include_sections=[], exclude_sections=[], treat_as_binary=False, masserase=False, force=False, reset=True, halt=False, close=True, verify=True) -> bool

Flash one or more images (.bin, .s37, .hex, .gbl, .rps) and handle the flash/verify/reset steps.

  • filenames: list[Path] — files to flash (must exist).
  • address: int — flash address; ignored for .hex/.s37.
  • include_sections / exclude_sections — ELF sections to include/exclude.
  • treat_as_binary — treat files as flat binaries regardless of extension.
  • masserase — mass-erase before flashing.
  • force — force the flash.
  • reset — reset after flashing (default True).
  • halt — halt the device after flashing.
  • close — close code regions after flashing (Series 3 only).
  • verify — verify flash contents afterward (default True).
target.flashApplication(filenames=[Path("firmware.hex")], masserase=True, verify=True)

flashRamCode(filenames, address=None, include_sections=[], exclude_sections=[], vtor=None, force=False, halt=False) -> bool

Flash code into RAM (no reset). vtor sets the vector table address (ignored for .hex/.s37).

flashPatches(patches, force=False, reset=True, halt=False) -> bool

Apply memory patches.

  • patches: list[tuple[int|str, int|str, int|str|None]] — (address, data[, length]) entries.

CTUNE (crystal tuning)

getCTUNE() -> CtuneValue | None

Read the CTUNE values present on the device as a CtuneValue — from the Device Info page (di), the board EEPROM (board), and the MFG token (token).

setCTUNE(value=None, force=False) -> bool

Write the CTUNE token.

  • If value is None, the value is taken from the board EEPROM (auto-set).
  • If value is an int, that value is written.
  • force writes even when the desired value is already configured. Without force, the method short-circuits to True if the token already matches.
ctune = target.getCTUNE()
target.setCTUNE(ctune.board)   # copy board value into the token
target.setCTUNE(0xA8)          # set an explicit value

Flash protection

enableWriteProtection(ranges=[], regions=[]) -> bool

Write-protect the given ranges and/or regions. At least one must be specified (otherwise ValueError).

enableReadProtection(ranges=[], regions=[]) -> bool

Read-protect the given ranges and/or regions. At least one must be specified.

disableWriteProtection() -> bool

Disable write protection across the entire flash.

disableReadProtection() -> bool

Disable read protection across the entire flash.

target.enableWriteProtection(ranges=[(0x00000000, 0x00008000)])
target.disableWriteProtection()

Security status

getSecurityStatus(show_trustzone_status=False, allow_reset=True) -> SecurityStatus | None

Return a SecurityStatus describing boot status, installed keys, debug-lock / device-erase / secure-boot / secure-debug-unlock state, SE firmware version, tamper state, and (optionally) TrustZone config/state. Returns None on failure.

Secure debug lock / unlock

enableSecureDebugUnlock(allow_reset=True) -> bool

Enable secure debug unlock.

disableSecureDebugUnlock(confirm=False, allow_reset=True) -> bool

Disable secure debug unlock.

⚠️ If device erase is disabled and the device is locked, debug access becomes permanently disabled. Pass confirm=True to proceed without the prompt.

lockDebugAccess(trustzone=None, allow_reset=True, disable_device_erase=False, confirm=False) -> bool

Lock the debug interface via the Secure Engine.

  • trustzone — a 4-bit string (each char "0"/"1"); invalid values raise ValueError.
  • disable_device_erase — also disable device erase (requires confirm=True).

⚠️ Disabling device erase is permanent and irreversible.

unlockDebugAccess(allow_reset=True, certificate_file=None, certificate_private_key=None, certificate_public_key=None, certificate_signature=None, command_key=None, command_signature=None, authorization=None, unlock_param=None) -> bool

Unlock the debug interface via the Secure Engine, supplying the relevant certificate/signature/authorization material.

Keys: GBL decryption, signing, command

generateGblDecryptionKey(outfile: Path) -> bool

Generate an AES-CCM GBL decryption key and write it to outfile.

writeGblDecryptionKey(key_file: Path, confirm=False) -> bool

Write a GBL decryption key to OTP memory.

⚠️ Permanent. Pass confirm=True to proceed without the prompt.

generateSigningKeys(pubkey_file, privkey_file, tokenfile=None) -> bool

Generate an ECC-P256 signing key pair; optionally also write the public key to a token file.

readPublicSigningKey() -> bytes | None

Read the public signing key from the device (or None).

writePublicSigningKey(key_file: Path, confirm=False) -> bool

Write a public signing key to OTP memory. Raises RuntimeError if one already exists.

⚠️ Permanent.

generateCommandKeys(pubkey_file, privkey_file, tokenfile=None) -> bool

Generate an ECC-P256 command key pair; optionally write the public key to a token file.

readPublicCommandKey() -> bytes | None

Read the public command key from the device (or None).

writePublicCommandKey(key_file: Path, confirm=False) -> bool

Write a public command key to OTP memory. Raises RuntimeError if one already exists.

⚠️ Permanent.

Manufacturing / static tokens

writeManufacturingTokens(tokenfiles=[], tokens=[], tokengroup=None, tokendefs=None, securerange=None) -> bool

Write manufacturing tokens. Series 1 and 2 only. Token files must exist.

  • tokens: list[tuple[str, str]] — (TOKEN_NAME, value) entries.

writeStaticTokens(tokenfiles=[], tokens=[], tokengroup=None, tokendefs=None, securerange=None) -> bool

Write static tokens. Series 3 only. (Same parameters; delegates to the same Commander operation.)

For lower-level token read/erase/header operations, see the tokens command reference.

Code & data regions (Series 3 only)

readRegionConfig(allow_reset=True) -> RegionConfig | None

Read the device's region configuration as a RegionConfig (code_regions + data_region), or None.

readRegionConfigToFile(outfile: Path, allow_reset=True) -> bool

Read the region configuration and write it to a file.

writeRegionConfig(config: RegionConfig, allow_reset=True, force=False) -> bool

Write a region configuration. Without force, the method first reads the existing config and skips the write (returning True) if it already matches. Invalid protection modes raise ValueError.

writeRegionConfigFromFile(config_file: Path, allow_reset=True, force=False) -> bool

Write a region configuration from a YAML file. The file must exist and contain a regions list, each with size_kb and a valid protection_mode; otherwise ValueError / FileNotFoundError.

closeCodeRegion(index: int, code_version=None, allow_reset=True, force=False) -> bool

Close a code region by index. code_version (if given) must be a 32-bit unsigned integer. An out-of-range index raises ValueError. Without force, an already-closed region returns True.

Region CodeRegionConfig entries carry a CodeRegionProtectionMode (ENCRYPTED_AND_AUTHENTICATED, ENCRYPTED, NONE).

Security configuration

generateSecurityConfig(outfile=None, device_serial_number=None) -> bool

Generate a security configuration. If outfile is None, the config is written to this computer's security store; otherwise to the file.

readSecurityConfig() -> dict | None

Read the security configuration from the device as a dict, or None.

writeSecurityConfig(config_file=None, allow_reset=True, confirm=False) -> bool

Write a security configuration. If config_file is None, it is taken from this computer's security store for the device.

⚠️ Permanent. Pass confirm=True to proceed without the prompt.

Secure Engine firmware (Series 3 only)

provisionSeFirmware(sefw_file: Path, allow_reset=True) -> bool

Provision the Secure Engine firmware from a file (must exist).

upgradeSeFirmware(sefw_file=None, address=None, allow_reset=True, confirm=False) -> bool

Upgrade the Secure Engine firmware. If sefw_file is None, the bundled SE firmware is used. confirm=True is only required when the supplied address is in RAM.

checkSeFirmwareUpgrade(allow_reset=True) -> SeFirmwareInfo | None

Check whether a newer SE firmware is available; returns a SeFirmwareInfo (current_version, latest_version, upgrade_available), or None.

See also

PyCommander · GitHub · Simplicity Commander docs · Licensed under the Silicon Labs MSLA

PyCommander

Home

Getting started

Using PyCommander

Topics

Command reference

Contributing

Clone this wiki locally