Reference Image Files

Reference: convert · ebl · gbl3 · gbl4 · ota · rps · postbuild

Command suites for building, converting, parsing and signing firmware image files. All methods return a dict. See Command-Reference for shared conventions.

Recurring signing/encryption parameters across these suites:

• sign_keyfile / keyfile — ECC-P256 PEM private key for signing.
• encrypt_keyfile — AES key file for encryption.
• verify_keyfile / verify_key — ECC-P256 PEM public key to verify a signature.
• extsign — produce an unsigned form for external signing; insert the signature later via the suite's sign/--signature.
• signature — a DER ECDSA signature file.

---

commander.convert — ConvertCommand

convert(infiles, outfile=None, address=None, patches=[], ranges=[], tokens=[], tokenfiles=[], tokengroup=None, tokendefs=None, secureboot=False, keyfile=None, crc=False, certificate=None, aeskey=None, include_sections=[], exclude_sections=[], extsign=False, signature=None, verify_key=None, **kwargs)

Convert or combine input files into one output; optionally set tokens and patch binary data.

• infiles — input file(s) to convert/combine.
• address — start address when a .bin is given.
• ranges — limit output to these memory ranges.
• secureboot — create a Secure Boot image (needs keyfile, signature, or extsign).
• crc — add a CRC32 for bootloader integrity (cannot combine with secureboot).
• certificate — certificate to append to a Secure Boot app.
• aeskey — AES key (util genkey --type aes-ccm) for bootloader app properties.

---

commander.ebl — EblCommand

Create/parse/inspect EBL files.

aat_usageinfo(**kwargs)

Display flash/RAM usage from AAT data (Zigbee/Thread; RAM for EM3xx only).

create(outfile, app=None, sign_keyfile=None, encrypt_keyfile=None, extsign=False, signature=None, verify_keyfile=None, **kwargs)

Create an EBL file from app.

keyconvert(infile, type=None, outfile=None, **kwargs)

Convert a PEM public key to a token file. Deprecated — use util keytotoken. type: aes-ccm or ecc-p256.

keygen(type, outfile=None, **kwargs)

Generate an encrypt/decrypt key or a signing key pair. Deprecated — use util genkey.

parse(infile, app=None, verify_keyfile=None, decrypt_keyfile=None, **kwargs)

Parse an EBL file; optionally write the app image to app.

print(filename, **kwargs)

Print information about an EBL file.

---

commander.gbl3 — Gbl3Command

Create/parse/sign GBL3 files.

aat_usageinfo(**kwargs)

As above (AAT flash/RAM usage).

create(outfile, app=None, bootloader=None, seupgrade=None, metadata=None, compress=None, certificate=None, include_sections=[], exclude_sections=[], seunencrypted=False, dep_app=None, dep_boot=None, dep_se=None, delta_app=None, sign_keyfile=None, encrypt_keyfile=None, extsign=False, signature=None, verify_keyfile=None, **kwargs)

Create a GBL3 file. Highlights: bootloader/seupgrade/metadata payloads, compress (lz4/lzma), seunencrypted (place SE upgrade outside the encrypted area), version dependencies (dep_app/dep_boot/dep_se), and delta upgrades (delta_app).

keyconvert(infile, type=None, outfile=None, **kwargs)

Convert a PEM public key to a token file. Deprecated — use util keytotoken.

keygen(type, outfile=None, **kwargs)

Generate a key. Deprecated — use util genkey.

parse(infile, app=None, bootloader=None, seupgrade=None, metadata=None, verify_keyfile=None, decrypt_keyfile=None, **kwargs)

Parse a GBL3 file; export images to the given files.

sign(infile, outfile, signature, verify_keyfile=None, **kwargs)

Sign a GBL3 file (e.g. an .extsign from create(extsign=True)) with an external signature.

---

commander.gbl4 — Gbl4Command

GBLv4 files.

create(outfile, config=None, data=[], seupgrade=None, encrypt_keyfile=None, compress=None, certificate=None, sign_keyfile=None, extsign=False, productid=None, bundleversion=None, minversion=None, **kwargs)

Create a GBLv4 file. config (a YAML) overrides the individual options if set. data may be repeated for multiple app/bootloader images. productid is a 128-bit hex vendor/product ID; bundleversion/minversion gate (partial) DFU.

createconfig(outfile, **kwargs)

Write a template config YAML for GBLv4 input.

info(filename, **kwargs)

Parse and show info about a GBLv4 file.

parse(infile, seupgrade=None, outfile=None, **kwargs)

Parse a GBLv4 file; export updates and/or the SE upgrade. Multiple updates get an index suffix (e.g. file_0.s37).

sign(infile, signature, outfile, verify_keyfile=None, **kwargs)

Sign a GBLv4 file using an external signature (DER ECDSA of the .manifest).

---

commander.ota — OtaCommand

Matter and Zigbee OTA files.

create(outfile, type=None, ...)

Create an OTA file. type is zigbee (default) or matter. The Matter and Zigbee paths use different parameter groups:

• Matter: input_files, vendorid, productid, swversion, swstring, min_sw, max_sw, releasenote, digest.
• Zigbee: upgrade_images, firmware_version, manufacturer_id, image_type, string, stack_version, credentials, destination, min_hw, max_hw, null_tag, manufacturer_tags.
• Both: certificate, sign, extsign.

parse(filename, type=None, outfile=None, **kwargs)

Parse an OTA file (type: matter/zigbee).

sign(filename, signature, outfile, curve, **kwargs)

Sign an OTA file with signature, using the named curve.

verify(filename, certificate, **kwargs)

Verify an OTA file against a certificate.

---

commander.rps — RpsCommand

RPS files (SiWx91x).

create(outfile, encrypt_key=None, mic_key=None, iv_file=None, sign_keyfile=None, sha=None, extsign=False, address=None, app=None, app_version=None, fw_info=None, include_sections=[], exclude_sections=[], map_file=None, combinedimage=False, key_type=None, new_key=None, prev_key=None, **kwargs)

Create an RPS file.

convert(outfile, encrypt_key=None, mic_key=None, iv_file=None, sign_keyfile=None, sha=None, extsign=False, app=None, nwpapp=None, app_version=None, fw_info=None, combinedimage=False, **kwargs)

Convert an application image to an RPS file. nwpapp adds an NWP application image.

load(filename, eraseapp=False, **kwargs)

Load an RPS file to the device. eraseapp=True erases the application first.

sign(filename, signature, outfile=None, **kwargs)

Sign an RPS file with an external signature.

---

commander.postbuild — PostbuildCommand

postbuild(filename, parameters=[], dryrun=False, **kwargs)

Run post-build tasks defined in a post-build YAML (.slpb) file.

• parameters: list[tuple[str, str]] — (name, value) overrides.
• dryrun=True resolves input filenames without running tasks.