Functions
	validate_lr1121_firmware_source (value, *, expect_loader=False)
	validate_checksum_md5 (value)
	_validate_lr1121_bootloader_block (config)
	validate_lr1121_firmware_update (config)
	_cached_http_fetch (cache_dir)
	_render_lr1121_image_header (image, array_name, words_name, version_name)
	_render_lr1121_firmware_header (image)
	_render_lr1121_bootloader_loader_header (image)
	create_lr1121_firmware_update (config, var)
	_create_lr1121_bootloader_update (bootloader_config, config, var, cache_dir)

Variables
	_LOGGER = logging.getLogger(__name__)
	LR1121_BOOTLOADER_SCHEMA
	LR1121_FIRMWARE_UPDATE_SCHEMA

Function Documentation

◆ _cached_http_fetch()

_cached_http_fetch ( cache_dir )

protected

Build a `fetch(url, expected_hash=None) -> bytes` callable for
lr1121_firmware.fetch_and_verify(), backed by an on-disk cache so repeat and offline builds
don't re-download the same source.

The cache key incorporates `expected_hash` (the MD5 fetch_and_verify() already resolved from
the `.md5` sidecar or `checksum_md5:` before calling this for the `.bin`) rather than being
`sha256(url)` alone. With the default `ref: HEAD` the URL never changes, so a plain
url-only key means a corrupt/truncated download poisons the cache permanently -- no config
change can ever invalidate it, since nothing about the request changes on retry. Folding the
expected hash in means correcting a wrong `checksum_md5:` (or a fixed upstream sidecar) misses
the poisoned entry and forces a fresh download. The `.md5` sidecar fetch itself has no
expected_hash to key on (chicken-and-egg -- it's what supplies one for the .bin) and is cached
under the URL alone; a corrupted sidecar is a much smaller/rarer risk than a corrupted 64+ KB
binary, and the cache directory below is a manual escape hatch either way.

Data that fails its own hash check is deliberately never written to the cache (verify-before-store):
a transient network corruption then simply retries cleanly on the next build, with no
config change needed at all.

Definition at line 181 of file lr1121_update_codegen.py.

◆ _create_lr1121_bootloader_update()

_create_lr1121_bootloader_update	(	bootloader_config,
		config,
		var,
		cache_dir )

protected

Fetch/verify the configured loader image, generate its header, set the build flag that
gates the bootloader-rewrite feature, and create the arming switch.

Mirrors create_lr1121_firmware_update() above -- same "block's presence is the build flag"
shape, one level down (ADR 0021). `target_version` is not passed to
fetch_and_verify(): the loader is not a "target" the way the transceiver image is, its version
is only ever compared for *equality* against the currently-running bootloader (Semtech's
rule), so there is nothing to override.

Definition at line 320 of file lr1121_update_codegen.py.

Here is the call graph for this function:

◆ _render_lr1121_bootloader_loader_header()

_render_lr1121_bootloader_loader_header ( image )

protected

Render the verified bootloader *loader* image as a C++ header (ADR 0021).

Definition at line 271 of file lr1121_update_codegen.py.

Here is the call graph for this function:

◆ _render_lr1121_firmware_header()

_render_lr1121_firmware_header ( image )

protected

Render the verified transceiver firmware image as a C++ header.

Definition at line 264 of file lr1121_update_codegen.py.

Here is the call graph for this function:

◆ _render_lr1121_image_header()

_render_lr1121_image_header	(	image,
		array_name,
		words_name,
		version_name )

protected

Render a verified firmware/loader image as a C++ header.

Each raw 4-byte chunk of the `.bin` is exactly one big-endian word as Semtech's own image
format already lays it out, so this only has to slice and format, not transform, the bytes.
`inline const` (not `constexpr`) for the array: it is never used in a constant expression, so
forcing constant-evaluation of up to ~61k elements would only cost compile time; `const` at
namespace scope still lands in `.rodata` (flash) on ESP32, not RAM. Shared by
_render_lr1121_firmware_header() (the transceiver image) and the bootloader loader image --
same shape, different symbol names so both headers can be included from the same translation
unit without colliding.

Definition at line 224 of file lr1121_update_codegen.py.

◆ _validate_lr1121_bootloader_block()

_validate_lr1121_bootloader_block ( config )

protected

Implement the build-time compatibility rule for the bootloader: sub-block (ADR 0021).

Classifies the *outer* source:'s target against LR1121_KNOWN_BOOTLOADER_REQUIREMENTS without
any network access (both source: filenames are already schema-validated shapes at this point,
so parsing them again here is free). Deliberately three-way, like the runtime compatibility
rule: an unrecognised target warns rather than errors, so the feature doesn't rot on Semtech's
next release (see lr1121_firmware.classify_bootloader_upgrade_class()'s doc comment).

Definition at line 108 of file lr1121_update_codegen.py.

◆ create_lr1121_firmware_update()

create_lr1121_firmware_update	(		config,
			var )

Fetch/verify the configured firmware image, generate its header, set the build flag that
gates the whole feature, and create the "Flash LR1121 Radio Firmware" button.

The block's mere presence in YAML is the build flag (ADR 0020) — there is no
separate enable switch, so entering/leaving flash mode is a recompile + OTA each way.

Definition at line 278 of file lr1121_update_codegen.py.

Here is the call graph for this function:

◆ validate_checksum_md5()

validate_checksum_md5 ( value )

Validate checksum_md5 as exactly 32 hex characters (MD5).

Definition at line 67 of file lr1121_update_codegen.py.

◆ validate_lr1121_firmware_source()

validate_lr1121_firmware_source	(		value,
		*	,
			expect_loader = False )

Validate the lr1121_firmware_update `source:` shorthand at schema time.

Checks the shape (github://owner/repo/path[@ref]) and the image class (transceiver vs.
loader vs. modem, by filename -- see lr1121_firmware.validate_image_class()). The network
fetch and MD5/image-content verification happen later, in to_code(), where a failure is
still a build-time error but one that needs the network anyway.
@param expect_loader True for the bootloader sub-block's `source:` (must be a loader image),
       False for the ordinary transceiver `source:` (must not be one).

Definition at line 48 of file lr1121_update_codegen.py.

◆ validate_lr1121_firmware_update()

validate_lr1121_firmware_update ( config )

Gate + inject the button ID for the optional lr1121_firmware_update: block.

Only runs when the block is present. Rejects configurations that can't reach the LR1121
bootloader at all (wrong radio_type, missing busy_pin) or that would silently invert the
bootloader-entry level (busy_pin inverted: true — bootloader entry drives BUSY to a physical
LOW; see radio_lr1121_firmware_updater.h). Also injects the flash button's companion ID at
validation time — see CONF_ACCEPT_FOREIGN_PAIRING_SWITCH_ID's comment (hub_names.py) for why that
can't wait until to_code(). The bootloader:-specific checks (C3-C5, and the companion arming
switch's ID) live in _validate_lr1121_bootloader_block() above, called at the end of this
function so config[CONF_ID] and the reachability checks are already settled.

Definition at line 148 of file lr1121_update_codegen.py.

Here is the call graph for this function:

Variable Documentation

◆ _LOGGER

home_io_control.lr1121_update_codegen._LOGGER = logging.getLogger(__name__)

protected

Definition at line 45 of file lr1121_update_codegen.py.

◆ LR1121_BOOTLOADER_SCHEMA

home_io_control.lr1121_update_codegen.LR1121_BOOTLOADER_SCHEMA

Initial value:

=  cv.Schema(
    {
        cv.Required(CONF_SOURCE): lambda value: validate_lr1121_firmware_source(value, expect_loader=True),
        cv.Optional(CONF_REF): cv.string_strict,
        cv.Optional(CONF_CHECKSUM_MD5): validate_checksum_md5,
    }
)

Definition at line 83 of file lr1121_update_codegen.py.

◆ LR1121_FIRMWARE_UPDATE_SCHEMA

home_io_control.lr1121_update_codegen.LR1121_FIRMWARE_UPDATE_SCHEMA

Initial value:

=  cv.Schema(
    {
        cv.Required(CONF_SOURCE): validate_lr1121_firmware_source,
        cv.Optional(CONF_REF): cv.string_strict,
        cv.Optional(CONF_CHECKSUM_MD5): validate_checksum_md5,
        # target_version exists solely as an escape hatch for a mirrored/renamed image whose
        # filename carries no version — NOT as a compatibility declaration. There is deliberately
        # no `requires_bootloader:` key: a user-declared compatibility claim is the wrong shape
        # for a safety check, since the build can derive it from the filename instead.
        cv.Optional(CONF_TARGET_VERSION): cv.hex_int,
        # Presence is the build flag for the bootloader-rewrite feature, exactly as the outer
        # block's presence already is for the transceiver-update feature -- see ADR 0021.
        cv.Optional(CONF_LR1121_BOOTLOADER): LR1121_BOOTLOADER_SCHEMA,
    }
)

Definition at line 91 of file lr1121_update_codegen.py.

Functions

Variables

Function Documentation

◆ _cached_http_fetch()

◆ _create_lr1121_bootloader_update()

◆ _render_lr1121_bootloader_loader_header()

◆ _render_lr1121_firmware_header()

◆ _render_lr1121_image_header()

◆ _validate_lr1121_bootloader_block()

◆ create_lr1121_firmware_update()

◆ validate_checksum_md5()

◆ validate_lr1121_firmware_source()

◆ validate_lr1121_firmware_update()

Variable Documentation

◆ _LOGGER

◆ LR1121_BOOTLOADER_SCHEMA

◆ LR1121_FIRMWARE_UPDATE_SCHEMA