""" PlatformIO post-build extra-script: append the MeshCore ``EndF`` trailer to the firmware image so a running node can self-locate its size/identity (docs/ota_protocol.md Section 2). Wire it (ONLY for OTA-enabled builds) from a variant/env, e.g.: extra_scripts = ${nrf52_base.extra_scripts} post:tools/mota/pio_endf.py and define ``-D ENABLE_OTA=1``. With ENABLE_OTA unset this script is a no-op, so it is safe to leave wired everywhere. The byte logic is the same `motalib.ensure_endf` exercised by `endf.py` and the unit tests. ESP32 / RP2040 emit ${PROGNAME}.bin (the raw app image) -> EndF appended to the .bin. nRF52 emits ${PROGNAME}.hex (the app, for DFU/UF2) -> EndF appended into the .hex right after the app's last byte (so the downstream .uf2 / DFU .zip carry it). Both feed the same on-device EndF scan. """ Import("env") # noqa: F821 (injected by PlatformIO/SCons) import os import sys sys.path.insert(0, os.path.join(env["PROJECT_DIR"], "tools", "mota")) # noqa: F821 import motalib as ml def _apply_forced_lora_ota_overlay() -> None: """Resolve a legacy trailing ``-UENABLE_OTA`` for release overlays. A few feature-rich nRF52 repeater environments are intentionally non-OTA and carry a final compiler undefine. PlatformIO can remove normal ``-D`` entries through ``build_unflags``, but it leaves that ``-U`` after all newly supplied defines. The release builder opts into this correction only when it is deliberately producing the complete OTA variant. """ if os.environ.get("MESHCORE_FORCE_LORA_OTA") != "1": return import re defines = [] enable_seen = False for item in env.get("CPPDEFINES", []): # noqa: F821 name = item[0] if isinstance(item, (list, tuple)) else item if name == "DISABLE_LORA_OTA": continue if name == "ENABLE_OTA": if enable_seen: continue enable_seen = True defines.append(item) if not enable_seen: defines.append(("ENABLE_OTA", 1)) env.Replace(CPPDEFINES=defines) # noqa: F821 cppdef_flags = str(env.get("_CPPDEFFLAGS", "")) # noqa: F821 cppdef_flags = re.sub(r"(?:^|\s)-U\s*ENABLE_OTA(?=\s|$)", " ", cppdef_flags) env.Replace(_CPPDEFFLAGS=" ".join(cppdef_flags.split())) # noqa: F821 print("LoRa OTA overlay: removed legacy -UENABLE_OTA and enabled the OTA command surface") def _ota_enabled() -> bool: disabled = False enabled = False for d in env.get("CPPDEFINES", []): # noqa: F821 name = d[0] if isinstance(d, (list, tuple)) else d if name == "DISABLE_LORA_OTA": disabled = True if name == "ENABLE_OTA": enabled = True return enabled and not disabled def _is_nrf52() -> bool: for d in env.get("CPPDEFINES", []): # noqa: F821 name = d[0] if isinstance(d, (list, tuple)) else d if name == "NRF52_PLATFORM": return True return False def _cppdef(name): # value of a -D= build flag, or None value = None for d in env.get("CPPDEFINES", []): # noqa: F821 if isinstance(d, (list, tuple)) and d and d[0] == name: value = str(d[1]) if len(d) > 1 else "" elif d == name: value = "" # Ordered build overlays have the same last-define-wins semantics as GCC. return value def _normalized_linker_path(value, project_dir): """Resolve one SCons linker-path value without guessing among candidates.""" if isinstance(value, (list, tuple)): if len(value) != 1: return "" value = value[0] if hasattr(value, "get_abspath"): value = value.get_abspath() raw = str(value or "").strip().strip('"').strip("'") if not raw: return "" if not os.path.isabs(raw): raw = os.path.join(str(project_dir), raw) return os.path.normcase(os.path.abspath(raw)) def _validate_nrf52_hybrid_profile(app_start, linked_app_end, hybrid_ram, internal_bootloader_update, active_linker, configured_linker, project_dir): """Fail closed unless both macros and the dedicated SRAM linker agree.""" if hybrid_ram != internal_bootloader_update: raise RuntimeError( "nRF52 hybrid RAM staging and internal bootloader update must be enabled together") if not hybrid_ram: return suffix_by_base = { ml.NRF52_APP_BASE_S140_V6: "v6", ml.NRF52_APP_BASE_S140_V7: "v7", } suffix = suffix_by_base.get(app_start) if suffix is None or linked_app_end != ml.NRF52_APP_END: raise RuntimeError( "nRF52 hybrid RAM staging requires the exact S140 v6/v7 0xED000 profile") expected = os.path.join( str(project_dir), "boards", f"nrf52840_s140_{suffix}_mota64.ld") expected = _normalized_linker_path(expected, project_dir) if not expected or not os.path.isfile(expected): raise RuntimeError("nRF52 hybrid RAM linker is missing") for label, value in (("active", active_linker), ("configured", configured_linker)): actual = _normalized_linker_path(value, project_dir) if actual != expected: shown = str(value or "none") raise RuntimeError( f"nRF52 hybrid RAM staging requires {expected}; " f"{label} linker is {shown}") def _board_maximum_size(build_env): """Return PlatformIO's resolved application-size limit, including per-env overrides.""" try: value = build_env.BoardConfig().get("upload.maximum_size") size = int(str(value), 0) return size if size > 0 else None except (AttributeError, TypeError, ValueError): return None def _validate_nrf52_legacy_sd_profile(app_start, linked_app_end, active_linker, configured_linker, project_dir): """Legacy adaptive SD still needs its exact retained-authorization map.""" if app_start != ml.NRF52_APP_BASE_S140_V6 or linked_app_end != ml.NRF52_APP_END: raise RuntimeError("legacy RAK SD OTA requires the exact S140 v6 0xED000 profile") expected = _normalized_linker_path( os.path.join(str(project_dir), "boards", "nrf52840_s140_v6_sd_ota.ld"), project_dir) if not os.path.isfile(expected): raise RuntimeError("legacy RAK SD authorization linker is missing") for label, value in (("active", active_linker), ("configured", configured_linker)): if _normalized_linker_path(value, project_dir) != expected: raise RuntimeError(f"legacy RAK SD OTA requires {expected}; " f"{label} linker is {value or 'none'}") def _source_filter_text(): """Resolved source-filter text for detecting code that is actually part of this environment.""" srcf = "" for getter in (lambda: env.GetProjectOption("build_src_filter", ""), # noqa: F821 lambda: env.GetProjectOption("src_filter", ""), # noqa: F821 lambda: env.get("SRC_FILTER", "")): # noqa: F821 try: value = getter() srcf += " " + (" ".join(map(str, value)) if isinstance(value, (list, tuple)) else str(value)) except Exception: pass return srcf def _builds_companion_radio() -> bool: return "examples/companion_radio" in _source_filter_text().replace("\\", "/") def _version_from_headers(): """FIRMWARE_VERSION is a header ``#define`` in the example (upstream MeshCore convention), not a -D, so _cppdef() can't see it and the EndF version would otherwise default to 0. Read it from the source WITHOUT changing where MeshCore authors it: prefer the example this env actually builds (from build_src_filter), else fall back to the repo-wide value when it's unambiguous. Purely additive - no MeshCore file changes, and a -D override (checked first in _firmware_ident) still wins for release builds.""" import re, glob proj = env["PROJECT_DIR"] # noqa: F821 pat = re.compile(r'#\s*define\s+FIRMWARE_VERSION\s+"([^"]+)"') def scan(paths): # {version_string: first_path_seen} vals = {} for p in paths: try: with open(p, encoding="utf-8", errors="ignore") as f: for line in f: mm = pat.search(line) if mm: vals.setdefault(mm.group(1), p) except OSError: pass return vals # 1) restrict to the example(s) this env compiles (build_src_filter -> examples/) srcf = _source_filter_text() ex_dirs = set(re.findall(r"examples[/\\]([A-Za-z0-9_]+)", srcf)) hdrs = [] for d in ex_dirs: hdrs += glob.glob(os.path.join(proj, "examples", d, "*.h")) vals = scan(hdrs) if len(vals) == 1: return next(iter(vals)) # 2) fall back to the repo-wide value; use it only if all examples agree (they do today: v1.17.0) vals = scan(glob.glob(os.path.join(proj, "examples", "*", "*.h"))) return next(iter(vals)) if len(vals) == 1 else "" def _firmware_ident(): """Self-describing identity to embed in EndF (docs/ota_protocol.md Section 2): target_id is computed from the PlatformIO env name (so it's correct even without build.sh's -D MOTA_TARGET_ID), hw_id from MOTA_HW_ID, fw_version from FIRMWARE_VERSION (a -D if set, else the example's header #define).""" import re target_define = (_cppdef("MOTA_TARGET_ID") or "").strip() try: target_id = int(target_define, 0) if target_define else ml.target_id_for_env(env["PIOENV"]) # noqa: F821 except ValueError: target_id = ml.target_id_for_env(env["PIOENV"]) # noqa: F821 hw_id = (_cppdef("MOTA_HW_ID") or "").replace("\\", "").strip().strip('"').strip("'") if not hw_id: hw_id = ml.hardware_id_for_env(env["PIOENV"]) # noqa: F821 ver_s = (_cppdef("FIRMWARE_VERSION") or "").replace("\\", "").strip().strip('"').strip("'") if not ver_s: # not a -D -> read the header MeshCore ships ver_s = _version_from_headers() m = re.search(r"(\d+)\.(\d+)(?:\.(\d+))?(?:\.(\d+))?", ver_s) fw_version = ml.pack_version( f"{m.group(1)}.{m.group(2)}.{m.group(3) or 0}.{m.group(4) or 0}" ) if m else 0 return ml.FwIdent(fw_version=fw_version, target_id=target_id, hw_id=hw_id) def _append_endf(source, target, env): # raw .bin path (ESP32 / RP2040) path = str(target[0]) with open(path, "rb") as f: data = f.read() body = ml.parse_endf(data)[0] if ml.has_endf(data) else data ident = _firmware_ident() out, h8 = ml.ensure_endf(body, ident) if out != data: with open(path, "wb") as f: f.write(out) print(f"EndF: stamped {os.path.basename(path)} (body_len={len(body)} body_hash={h8.hex()} " f"target={ident.target_id:#010x} hw='{ident.hw_id}' fw={ident.fw_version:#010x})") else: print(f"EndF: already present in {os.path.basename(path)} (no change)") def _append_endf_hex(source, target, env): # Intel-HEX path (nRF52: app for DFU/UF2) from intelhex import IntelHex path = str(target[0]) ih = IntelHex(path) segs = ih.segments() if not segs: print("EndF: empty .hex, skipping"); return app_start, app_end = segs[0] # first (lowest) segment = the application image raw_body = bytes(ih.tobinarray(start=app_start, size=app_end - app_start)) # A valid trailer can still carry a previous build's identity/layout. Strip # it in memory, but retain the original segment bounds for replacement. # Never skip the current link/profile/size checks on an incremental build. endf_free_body = ml.parse_endf(raw_body)[0] if ml.has_endf(raw_body) else raw_body app_region_size = _board_maximum_size(env) if app_region_size is None: raise RuntimeError("nRF52 linked application region is unavailable") linked_app_end = app_start + app_region_size internal_extrafs = (_cppdef("EXTRAFS") is not None and _cppdef("QSPIFLASH") is None and _builds_companion_radio()) sd_enabled = _cppdef("OTA_SD_STORE") is not None qspi_backed = _cppdef("OTA_QSPI_STORE") is not None auto_store = _cppdef("OTA_RAK_AUTO_STORE") is not None seeder_only = _cppdef("OTA_SEEDER_ONLY") is not None optional_rak_sd = _cppdef("OTA_RAK15002_SD_STORE") is not None if optional_rak_sd and (not sd_enabled or _cppdef("RAK_4631") is None or not (auto_store or (seeder_only and _builds_companion_radio()))): raise RuntimeError("optional RAK15002 SD requires an exact RAK4631 adaptive receiver or source-only Companion") # Optional SD does not change the frozen application flash layout: normal # receivers retain AUTO+HYBRID, explicit legacy receivers use AUTO without # hybrid RAM, and Full Companion retains ExtraFS. # The runtime selects SD only after validating its separate loader ABI. sd_backed = sd_enabled and not optional_rak_sd qspi_bootloader_update = _cppdef("OTA_QSPI_BOOTLOADER_UPDATE") is not None hybrid_ram = _cppdef("OTA_HYBRID_RAM_STORE") is not None internal_bootloader_update = _cppdef("OTA_INTERNAL_BOOTLOADER_UPDATE") is not None sd_bootloader_update = _cppdef("OTA_SD_BOOTLOADER_UPDATE") is not None board = env.BoardConfig() _validate_nrf52_hybrid_profile( app_start, linked_app_end, hybrid_ram, internal_bootloader_update, env.get("LDSCRIPT_PATH", ""), board.get("build.ldscript", ""), env["PROJECT_DIR"]) if sd_backed and qspi_backed: raise RuntimeError("nRF52 build cannot enable both SD and QSPI OTA stores") if auto_store: if not qspi_backed or _cppdef("OTA_FLASH_STORE") is None: raise RuntimeError("RAK adaptive OTA requires both stores and retained-RAM internal support") if os.environ.get("MESHCORE_NRF52_LEGACY_FLASH_OTA") == "1": if (not optional_rak_sd or seeder_only or _builds_companion_radio() or hybrid_ram or internal_bootloader_update): raise RuntimeError("legacy adaptive SD OTA requires a receiver without hybrid RAM or bootloader self-update") _validate_nrf52_legacy_sd_profile( app_start, linked_app_end, env.get("LDSCRIPT_PATH", ""), board.get("build.ldscript", ""), env["PROJECT_DIR"]) elif not hybrid_ram or not internal_bootloader_update: raise RuntimeError("RAK adaptive OTA requires both stores and retained-RAM internal support") if qspi_backed and _cppdef("QSPIFLASH") is not None: raise RuntimeError("raw QSPI OTA staging cannot share a chip with QSPIFLASH") if qspi_bootloader_update: xiao_module = _cppdef("XIAO_NRF52") is not None or _cppdef("IKOKA_NRF52") is not None if not qspi_backed or sd_backed or not xiao_module: raise RuntimeError("bootloader update requires a XIAO nRF52840 raw-QSPI OTA build") if linked_app_end != ml.NRF52_BOOT_SCRATCH_START: raise RuntimeError("bootloader-update build must link exactly below scratch at 0xE0000") if internal_bootloader_update: if sd_backed or (qspi_backed and not auto_store) or _cppdef("QSPIFLASH") is not None or internal_extrafs: raise RuntimeError("internal bootloader update cannot use SD/QSPI/ExtraFS") if linked_app_end != ml.NRF52_APP_END: raise RuntimeError("shared-slot bootloader update requires the normal 0xED000 linker ceiling") if sd_bootloader_update: if not sd_backed or qspi_backed or internal_extrafs or _cppdef("QSPIFLASH") is not None: raise RuntimeError("SD bootloader update requires the dedicated nRF52 SD OTA store") if linked_app_end != ml.NRF52_APP_END: raise RuntimeError("SD bootloader update requires the normal 0xED000 linker ceiling") stage_ceiling = (ml.NRF52_APP_END if (sd_backed or qspi_backed) else ml.nrf52_stage_ceiling_for_layout(linked_app_end, internal_extrafs)) layout_flags = ((ml.NRF52_LAYOUT_FLAG_SD if sd_backed else 0) | (ml.NRF52_LAYOUT_FLAG_QSPI if qspi_backed and not auto_store else 0) | (ml.NRF52_LAYOUT_FLAG_INTERNAL_EXTRAFS if internal_extrafs else 0) | (ml.NRF52_LAYOUT_FLAG_BOOTLOADER_SCRATCH if qspi_bootloader_update else 0) | (ml.NRF52_LAYOUT_FLAG_HYBRID_RAM if hybrid_ram else 0) | (ml.NRF52_LAYOUT_FLAG_AUTO_STORE if auto_store else 0)) layout = ml.Nrf52Layout(app_start, linked_app_end, stage_ceiling, layout_flags) body = ml.ensure_nrf52_layout(endf_free_body, layout) ident = _firmware_ident() out, h8 = ml.ensure_endf(body, ident) if seeder_only: # A source-only full Companion never stages or applies an update to # itself, so it does not need to fit in OTAFIX's in-place workspace. # It must still fit the board/env's resolved flash application region. image_limit = app_region_size limit_name = "application" else: # Dynamic in-place patches carry their own memory_size and are checked against the staged # container before approval. The firmware itself only needs to remain inside both its linked # application region and the selected filesystem-safe ceiling. image_limit = min(linked_app_end, stage_ceiling) - app_start limit_name = "nRF52 OTA application" if image_limit is not None and len(out) > image_limit: raise RuntimeError(f"nRF52 OTA image is {len(out)} bytes; {limit_name} limit is " f"{image_limit} bytes") new_app_end = app_start + len(out) if len(segs) > 1 and new_app_end >= segs[1][0]: # Even exact adjacency would merge the next segment into the app on # the next read, hiding the trailer beneath unrelated trailing bytes. raise RuntimeError("nRF52 layout/EndF would reach a separate HEX segment") if out == raw_body: print(f"EndF: already present in {os.path.basename(path)} (no change)"); return # Replace, do not append after the old EndF. A restamp normally keeps the # same length; an older EndF without a layout record grows by 24 bytes. # Delete only the original application segment; UICR, other segments and # Intel HEX start-address metadata remain owned by the existing image. for address in range(app_start, app_end): del ih[address] ih.frombytes(out, offset=app_start) ih.write_hex_file(path) endf_address = app_start + len(body) print(f"EndF: stamped {os.path.basename(path)} at 0x{endf_address:X} " f"(app=0x{app_start:X}.. body_len={len(body)} body_hash={h8.hex()} " f"stage=0x{stage_ceiling:X} " f"target={ident.target_id:#010x} hw='{ident.hw_id}' fw={ident.fw_version:#010x})") _apply_forced_lora_ota_overlay() if _ota_enabled(): if _is_nrf52(): env.AddPostAction("$BUILD_DIR/${PROGNAME}.hex", _append_endf_hex) # noqa: F821 else: env.AddPostAction("$BUILD_DIR/${PROGNAME}.bin", _append_endf) # noqa: F821 else: print("EndF: ENABLE_OTA not defined; skipping trailer injection")