A parser for the EBL and GBL (v3 and v4) firmware image formats used by the Silicon Labs Gecko bootloader.
Images are parsed into structured tags, and round-trip byte-for-byte: anything the library reads it can write back unchanged, including the trailing data that some vendors append after the end tag.
pip install pygblThe base install is pure Python and covers parsing, serializing, building images from ELFs, and LZMA. Signing, encryption and LZ4 need optional dependencies:
pip install pygbl[crypto] # signing and encryption
pip install pygbl[lz4] # LZ4 compression
pip install pygbl[all]Calling those features without their dependency raises MissingDependencyError.
Parse an image and inspect its tags:
import pathlib
from pygbl import GBL3ApplicationInfo, parse_firmware_image
data = pathlib.Path("ncp-uart-hw.gbl").read_bytes()
image = parse_firmware_image(data)
for tag in image.tags:
print(tag)
print(image.get_first_tag(GBL3ApplicationInfo).version)
print(image.get_metadata()) # opaque bytes, the schema is vendor defined
assert image.serialize() == dataModify an image. Tags are frozen dataclasses, so dataclasses.replace works, and
regenerate_crc fixes up the end tag afterwards:
import dataclasses
from pygbl import GBL3End, GBL3Metadata
modified = dataclasses.replace(
image,
tags=[t for t in image.tags if not isinstance(t, GBL3End)]
+ [GBL3Metadata(metadata=b'{"fw_type": "zigbee_ncp"}')],
).regenerate_crc()Compress, encrypt and sign, in the order the bootloader expects:
from cryptography.hazmat.primitives.serialization import load_pem_private_key
from pygbl import GBL3Compression
private_key = load_pem_private_key(
pathlib.Path("vendor_sign.key").read_bytes(), password=None
)
key = bytes.fromhex("7F8FE53979B31BC556FCB131AFF42414")
sealed = image.compress(GBL3Compression.LZMA).encrypt(key).sign(private_key)
pathlib.Path("signed.gbl").write_bytes(sealed.serialize(block_size=4))And unwrap it again:
assert sealed.verify_signature(private_key.public_key())
assert sealed.decrypt(key).decompress().serialize() == image.serialize()Images can be built straight from a linked ELF, without commander. Program data comes
from the loadable segments (keyed by physical address, since initialized data is
stored in flash but linked at its RAM address) and the application info tag is read
from the SDK's application_properties_t struct:
from pygbl import build_application_gbl3, build_bootloader_gbl3
with open("zigbee_ncp.out", "rb") as f:
image = build_application_gbl3(f, metadata=b'{"fw_type": "zigbee_ncp"}')
with open("bootloader.out", "rb") as f:
bootloader = build_bootloader_gbl3(f)Both reproduce commander gbl create byte-for-byte. Bootloader payloads carry a CRC32
of themselves, which build_bootloader_gbl3 appends for you.
Series 3 parts use GBLv4, a different format that nests tags inside a signed manifest
and can bundle several updates in one file. parse_firmware_image recognizes it by its
magic and returns a GBL4Image, which round-trips byte-for-byte like the rest:
from pygbl import GBL4Image, GBL4MemorySectionInfo, GBL4UpdateMemorySection
image = parse_firmware_image(pathlib.Path("light-simg301.gbl4").read_bytes())
assert isinstance(image, GBL4Image)
assert image.serialize() == data
# `get_tags` searches the whole tree, at any depth
for update in image.get_tags(GBL4UpdateMemorySection):
print(f"{update.target_address:#010x} {update.plain_image_size} bytes")
for info in image.get_tags(GBL4MemorySectionInfo):
print(info.compression_scheme, info.encryption_scheme, info.nonce.hex())Reading and writing are supported; building a v4 image from an ELF is not, the ELF helpers are GBLv3 only.
EBL images, used by older EM3xx parts, work the same way:
from pygbl import EBLEraseProgram, parse_firmware_image
image = parse_firmware_image(pathlib.Path("ncp-uart-sw.ebl").read_bytes())
for tag in image.get_tags(EBLEraseProgram):
print(f"{tag.address:#010x} {len(tag.data)} bytes")A GBL can contain a bootloader, an application, or both. Combined images can be split apart and recombined, which is useful because some bootloaders cannot flash a combined image in one pass:
bootloader, application = combined.split_bootloader_app()
recombined = application.combine_bootloader_app(bootloader)