Add shared-slot nRF52 bootloader updates

This commit is contained in:
mikecarper committed 2026-08-21 00:55:01 -07:00
1 parent b7c9e37d09
commit 3de5fddf47
43 files changed
+1647 -211

No files matched your search

+17 -11
View File
@@ -25,13 +25,13 @@ Uses the repo's Python venv (`meshcore/`). Dependencies: `detools` (delta), `cry
| `motalib.py` | Core logic: multihash, EndF, merkle tree+proofs, manifest/container build/parse/verify. The **reference implementation** of the spec and the unit-test oracle. Imported by everything below. |
| `pio_endf.py` | **PlatformIO post-build hook** (wired in `platformio.ini`) that injects the `EndF` self-identity trailer into the flashed firmware (`-D ENABLE_OTA`). |
| `gen_vectors.py` | Generates `test/test_ota/mota_vectors.h` - the cross-check vectors the native C++ tests run against. |
| `gen_targets.py` | Generates `src/helpers/ota/OtaTargets.h` - the `target_id -> env-name` table (every `ENABLE_OTA` env, resolved from `pio project config`). Shared by the firmware and `motatool` so a node can name a target seen over the air without sending the string. Regenerate when the OTA env set changes. |
| `gen_targets.py` | Generates `src/helpers/ota/OtaTargets.h` - the `target_id -> env-name` table (every resolved `ENABLE_OTA` env plus qualified build.sh-only release aliases). Shared by the firmware and `motatool` so a node can name a target seen over the air without sending the string. Regenerate when the OTA env or release-alias set changes. |
| `test_mota.py` | Unit tests for `motalib` (run directly or via pytest). |
## Tests
```bash
./meshcore/bin/python tools/mota/test_mota.py # EndF, merkle+proofs, v2 apps/v3 XIAO bootloader,
./meshcore/bin/python tools/mota/test_mota.py # EndF, merkle+proofs, v2 apps/v3 nRF52 bootloader,
# signing, tamper detection, approval enforcement
./meshcore/bin/python tools/mota/gen_vectors.py # regenerate the native-test cross-check vectors
./meshcore/bin/python tools/mota/gen_targets.py # regenerate src/helpers/ota/OtaTargets.h (needs `pio`)
@@ -52,19 +52,25 @@ firmware and matches a delta's `base_hash` against its own `EndF`. Wiring (handl
family derived from the environment name, and `fw_version` = parsed from `FIRMWARE_VERSION`. A node (and
`motatool`, reading the firmware's `EndF`) therefore auto-discovers identity without relying on filenames.
## Privileged XIAO bootloader reference builder
## Privileged nRF52 bootloader reference builder
Ordinary calls to `build_manifest()` continue to emit v2 application packages.
Passing `bootloader=True` is a deliberately narrow reference-only path: it
requires a nonzero version, a signed exact 40 KiB XIAO OTAFIX region, 1024-byte
blocks, full codec, zero base hash, a sane vector table, exact `XIAO_DFU`
embedded manifest/CRC/board identity, and an ABI-3 marker retaining QSPI plus
boot-update capabilities. It derives the signed `XIAO_BL_28860044` or
`XIAO_BL_28860045` hardware ID from the embedded board ID. Parsing and
`verify()` repeat those gates; magic literals that are not complete valid
structures are skipped.
requires a nonzero version, a signed exact 40 KiB OTAFIX region, 1024-byte
blocks, full codec, zero base hash, a sane vector table, an exact embedded
manifest/CRC identity, and an ABI-3 marker retaining the selected storage plus
boot-update capabilities. Deployed XIAO packages retain their
`XIAO_BL_28860044`/`XIAO_BL_28860045` IDs. Generic packages derive the padded
`NRF_BL_<BOARD_ID>_<DEVICE_NAME>` ID and collision-checked wire target from the
full embedded manifest pair. Parsing and `verify()` repeat those gates; magic
literals that are not complete valid structures are skipped.
Generic parsing remains available for candidate inspection, but the signing
builder accepts only identities in the qualified internal inventory plus the
two deployed XIAO identities. The test suite verifies those boot target IDs are
unique and disjoint from the generated application target table.
This library does not authorize a device update. A capable node will only arm
such a v3 package through the exact manual confirmation described in
[`docs/ota_nrf52_qspi.md`](../../docs/ota_nrf52_qspi.md#explicit-xiao-bootloader-updates-over-lora).
[`docs/ota_nrf52_bootloader_update.md`](../../docs/ota_nrf52_bootloader_update.md).
The ordinary `tools/lora_ota` runner rejects bootloader packages.
+22 -8
View File
@@ -1,10 +1,12 @@
#!/usr/bin/env python3
"""Generate src/helpers/ota/OtaTargets.h - the target_id -> env-name table for OTA-capable envs.
"""Generate src/helpers/ota/OtaTargets.h - the target_id -> env-name table for OTA-capable builds.
A target_id is sha2-256:4(pio_env_name); it travels in beacons / the .mota manifest as 4 bytes. This
table lets a node (and motatool) print the human-readable env name for a target seen over the air, WITHOUT
ever transmitting the string. The set of envs is resolved from PlatformIO (every env whose build_flags
include ENABLE_OTA and do not include DISABLE_LORA_OTA), so explicit size/safety exclusions stay out.
ever transmitting the string. The set is the union of PlatformIO environments whose resolved build flags
enable LoRa OTA and qualified release-only aliases composed by build.sh. Keeping those aliases in the
table prevents a valid release target from being displayed as unknown merely because it is not a literal
``[env:...]`` section.
Run: ./meshcore/bin/python tools/mota/gen_targets.py # resolves via `pio project config`
./meshcore/bin/python tools/mota/gen_targets.py cfg.json # or reuse a cached config dump (faster)
@@ -21,6 +23,7 @@ import motalib as ml
ROOT = Path(__file__).resolve().parents[2]
OUT = ROOT / "src" / "helpers" / "ota" / "OtaTargets.h"
INTERNAL_BOOTLOADER_TARGETS = ROOT / "tools" / "mota" / "nrf52_internal_bootloader_targets.txt"
def resolved_config():
@@ -46,14 +49,25 @@ def ota_envs(cfg):
return sorted(set(envs))
def release_aliases():
"""Return qualified build.sh aliases that carry their own OTA target ID."""
return sorted({
line.strip()
for line in INTERNAL_BOOTLOADER_TARGETS.read_text(encoding="utf-8").splitlines()
if line.strip() and not line.lstrip().startswith("#")
})
def main():
envs = ota_envs(resolved_config())
envs = sorted(set(ota_envs(resolved_config())) | set(release_aliases()))
rows = [(ml.target_id_for_env(e), e) for e in envs]
seen = {}
for tid, e in rows: # sha2-256:4 over ~300 names - verify no collisions
for tid, e in rows: # sha2-256:4 over all names - verify no collisions
if tid in seen and seen[tid] != e:
print(f"WARNING: target_id collision 0x{tid:08x}: {seen[tid]!r} vs {e!r}", file=sys.stderr)
raise RuntimeError(
f"target_id collision 0x{tid:08x}: {seen[tid]!r} vs {e!r}"
)
seen[tid] = e
rows.sort(key=lambda r: r[1].lower()) # by env name (readable, deterministic)
@@ -62,7 +76,7 @@ def main():
"#include <stdint.h>",
"",
"// AUTO-GENERATED by tools/mota/gen_targets.py - do not edit by hand.",
f"// {len(rows)} OTA-capable PlatformIO envs. Maps target_id (= sha2-256:4 of the env name, LE uint32)",
f"// {len(rows)} OTA-capable build targets. Maps target_id (= sha2-256:4 of the target name, LE uint32)",
"// to the human-readable env name, so a node/tool can name a target seen over the air WITHOUT",
"// transmitting the string in the .mota / LoRa protocol. Regenerate when the OTA env set changes.",
"// Size-constrained receivers can set OTA_TARGET_NAME_TABLE=0. They still match targets by ID;",
@@ -96,7 +110,7 @@ def main():
]
OUT.parent.mkdir(parents=True, exist_ok=True)
OUT.write_text("\n".join(out) + "\n")
print(f"wrote {OUT} ({len(rows)} OTA envs)")
print(f"wrote {OUT} ({len(rows)} OTA targets)")
if __name__ == "__main__":
+169 -42
View File
@@ -68,6 +68,8 @@ NRF52_EXTRAFS_START = 0x000D4000
NRF52_BOOT_SCRATCH_START = 0x000E0000
NRF52_BOOT_SCRATCH_END = 0x000EA000
NRF52_APP_END = 0x000ED000
NRF52_BOOT_CONTAINER_SIZE = 41330
NRF52_SHARED_BOOT_STAGE_START = 0x000E2000
NRF52_FLASH_PAGE = 4096
# A validated nRF52 firmware carries this record immediately before EndF. It lets an offline packager
@@ -90,8 +92,34 @@ XIAO_BOOT_MANIFEST_VERSION = 1
XIAO_BOOT_MANIFEST_SIZE = 44
XIAO_BOOT_DEVICE_NAME = b"XIAO_DFU".ljust(16, b"\0")
XIAO_BOOT_CAPS_MAGIC = b"MOTABLDR"
BOOT_STORAGE_STAGE_CEILING = 0x02
XIAO_BOOT_STORAGE_QSPI = 0x04
XIAO_BOOT_STORAGE_UPDATE = 0x08
BOOT_STORAGE_KNOWN = 0x0F
BOOT_STORAGE_QSPI_UPDATE = (BOOT_STORAGE_STAGE_CEILING | XIAO_BOOT_STORAGE_QSPI |
XIAO_BOOT_STORAGE_UPDATE)
BOOT_STORAGE_INTERNAL_UPDATE = BOOT_STORAGE_STAGE_CEILING | XIAO_BOOT_STORAGE_UPDATE
# Exact embedded manifests for the qualified shared-internal nRF52840
# bootloaders. Parsing/inspection remains generic, but package creation is
# deliberately limited to this collision-audited release inventory. Carrier
# aliases use the same installed bootloader identity and therefore do not add
# rows here.
INTERNAL_BOOTLOADER_IDENTITIES = (
(0x239A0071, "TOWER_V2_OTA"),
(0x239A0071, "T096_DFU"),
(0x239A0071, "T1_DFU"),
(0x239A0071, "T114_DFU"),
(0x239A0071, "MESH_POCKET_OTA"),
(0x239A00B3, "KeepteenLT1_OTA"),
(0x239A0029, "MX25_DFU"),
(0x239A00B3, "PROM_DFU"),
(0x28860057, "T1KE_DFU"),
(0x239A00DA, "TNM3_DFU"),
(0x239A0029, "3401_DFU"),
(0x239A0029, "4631_DFU"),
(0x239A0029, "RTAG_DFU"),
)
# MeshTower V2's SD-backed OTA target keeps the staged .mota off-chip, so the application may use the
# complete S140 v6 application region up to InternalFS instead of leaving room for internal staging.
@@ -222,7 +250,6 @@ class Nrf52Layout:
def bootloader_scratch(self) -> bool:
return bool(self.flags & NRF52_LAYOUT_FLAG_BOOTLOADER_SCRATCH)
def nrf52_stage_ceiling_for_layout(linked_app_end: int, uses_internal_extrafs: bool) -> int:
"""Select a safe staging ceiling from linker geometry and actual secondary-storage type."""
if uses_internal_extrafs:
@@ -235,7 +262,8 @@ def nrf52_stage_ceiling_for_layout(linked_app_end: int, uses_internal_extrafs: b
def build_nrf52_layout(layout: Nrf52Layout) -> bytes:
if layout.app_base not in (NRF52_APP_BASE_S140_V6, NRF52_APP_BASE_S140_V7):
raise ValueError(f"unsupported nRF52 app base 0x{layout.app_base:X}")
if layout.linked_app_end not in (NRF52_EXTRAFS_START, NRF52_BOOT_SCRATCH_START, NRF52_APP_END):
if layout.linked_app_end not in (NRF52_EXTRAFS_START,
NRF52_BOOT_SCRATCH_START, NRF52_APP_END):
raise ValueError(f"unsupported nRF52 linked app end 0x{layout.linked_app_end:X}")
if layout.stage_ceiling not in (NRF52_EXTRAFS_START, NRF52_APP_END):
raise ValueError(f"unsupported nRF52 staging ceiling 0x{layout.stage_ceiling:X}")
@@ -250,10 +278,12 @@ def build_nrf52_layout(layout: Nrf52Layout) -> bytes:
if layout.external_backed and layout.flags & NRF52_LAYOUT_FLAG_INTERNAL_EXTRAFS:
raise ValueError("nRF52 external staging cannot also reserve internal ExtraFS")
if layout.bootloader_scratch:
if not layout.qspi_backed or layout.sd_backed or layout.linked_app_end != NRF52_BOOT_SCRATCH_START:
raise ValueError("nRF52 bootloader scratch requires QSPI and linked app end 0xE0000")
qspi_shape = (layout.qspi_backed and not layout.sd_backed and
layout.linked_app_end == NRF52_BOOT_SCRATCH_START)
if not qspi_shape:
raise ValueError("nRF52 bootloader scratch requires the XIAO QSPI layout")
elif layout.linked_app_end == NRF52_BOOT_SCRATCH_START:
raise ValueError("nRF52 linked app end 0xE0000 requires the bootloader-scratch flag")
raise ValueError("reserved bootloader geometry requires the bootloader-scratch flag")
expected_ceiling = (NRF52_APP_END if layout.external_backed else
nrf52_stage_ceiling_for_layout(
layout.linked_app_end,
@@ -501,7 +531,7 @@ def xiao_bootloader_hw_id(board_id: int) -> str:
@dataclass(frozen=True)
class XiaoBootloaderIdentity:
class BootloaderIdentity:
manifest_offset: int
image_start: int
image_size: int
@@ -510,7 +540,73 @@ class XiaoBootloaderIdentity:
crc32: int
def _xiao_bootloader_vector_sane(image: bytes) -> bool:
XiaoBootloaderIdentity = BootloaderIdentity # compatibility for callers of the original reference API
def _bootloader_device_name(board_id: int, name_raw: bytes) -> Optional[str]:
if len(name_raw) != 16 or board_id in (0, 0xFFFFFFFF):
return None
if board_id in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE):
return "XIAO_DFU" if name_raw == XIAO_BOOT_DEVICE_NAME else None
try:
end = name_raw.index(0)
except ValueError:
return None
if end == 0 or end > 15 or any(name_raw[end:]) or any(b < 0x21 or b > 0x7E for b in name_raw[:end]):
return None
return name_raw[:end].decode("ascii", "strict")
def bootloader_hw_id(board_id: int, device_name: str) -> bytes:
name_raw = device_name.encode("ascii", "strict")
if len(name_raw) > 15 or _bootloader_device_name(board_id, name_raw.ljust(16, b"\0")) is None:
raise ValueError("invalid embedded bootloader board/name identity")
if board_id in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE):
return hw_id_bytes(xiao_bootloader_hw_id(board_id))
return hw_id_bytes(f"NRF_BL_{board_id:08X}_{device_name}")
def bootloader_target_id(board_id: int, device_name: str) -> int:
if board_id in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE):
return board_id
return int.from_bytes(sha256(bootloader_hw_id(board_id, device_name))[:4], "little")
def audit_bootloader_target_inventory(application_target_ids=()) -> dict:
"""Return target->identity after rejecting boot/app target collisions.
The generic image parser intentionally accepts future canonical embedded
identities for diagnostics. Only the curated identities below are allowed
to enter a newly built signed package, and release tests pass the generated
application target table here to keep the two wire namespaces disjoint.
"""
identities = (
(XIAO_BOOT_BOARD_ID_BASE, "XIAO_DFU"),
(XIAO_BOOT_BOARD_ID_SENSE, "XIAO_DFU"),
) + INTERNAL_BOOTLOADER_IDENTITIES
app_ids = set(application_target_ids)
targets = {}
for identity in identities:
target = bootloader_target_id(*identity)
if target in targets:
raise ValueError(
f"bootloader target collision 0x{target:08X}: "
f"{targets[target]!r} vs {identity!r}")
if target in app_ids:
raise ValueError(
f"bootloader target 0x{target:08X} collides with an application target")
targets[target] = identity
return targets
def bootloader_identity_is_buildable(board_id: int, device_name: str) -> bool:
return ((board_id, device_name) in INTERNAL_BOOTLOADER_IDENTITIES or
(board_id, device_name) in (
(XIAO_BOOT_BOARD_ID_BASE, "XIAO_DFU"),
(XIAO_BOOT_BOARD_ID_SENSE, "XIAO_DFU")))
def _bootloader_vector_sane(image: bytes) -> bool:
if len(image) < 8:
return False
sp, reset = struct.unpack_from("<II", image)
@@ -519,7 +615,7 @@ def _xiao_bootloader_vector_sane(image: bytes) -> bool:
and XIAO_BOOT_IMAGE_START <= entry < XIAO_BOOT_IMAGE_START + XIAO_BOOT_IMAGE_SIZE
def parse_xiao_bootloader_identity(image: bytes) -> Optional[XiaoBootloaderIdentity]:
def parse_bootloader_identity(image: bytes) -> Optional[BootloaderIdentity]:
"""Find exactly one CRC-valid embedded v1 manifest, continuing past invalid decoys."""
if len(image) != XIAO_BOOT_IMAGE_SIZE:
return None
@@ -531,56 +627,82 @@ def parse_xiao_bootloader_identity(image: bytes) -> Optional[XiaoBootloaderIdent
start, image_size, board_id = struct.unpack_from("<III", image, off + 12)
name_raw = image[off + 24:off + 40]
stored_crc = struct.unpack_from("<I", image, off + 40)[0]
device_name = _bootloader_device_name(board_id, name_raw)
if (version != XIAO_BOOT_MANIFEST_VERSION or size != XIAO_BOOT_MANIFEST_SIZE or
start != XIAO_BOOT_IMAGE_START or image_size != XIAO_BOOT_IMAGE_SIZE or
board_id not in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE) or
name_raw != XIAO_BOOT_DEVICE_NAME):
device_name is None):
continue
crc_image = bytearray(image)
crc_image[off + 40:off + 44] = b"\0" * 4
import zlib
if zlib.crc32(crc_image) & 0xFFFFFFFF != stored_crc:
continue
candidate = XiaoBootloaderIdentity(
off, start, image_size, board_id,
name_raw.split(b"\0", 1)[0].decode("ascii", "strict"), stored_crc)
candidate = BootloaderIdentity(off, start, image_size, board_id, device_name, stored_crc)
if found is not None:
return None
found = candidate
return found
def xiao_bootloader_caps_ok(image: bytes) -> bool:
"""Find a real capability marker; a bare MOTABLDR literal is skipped."""
# The structure is emitted with uint16_t fields, so only aligned candidates
# are valid. This also avoids accepting an incidental magic string embedded
# in instruction/literal data as the privileged continuity marker.
def parse_xiao_bootloader_identity(image: bytes) -> Optional[XiaoBootloaderIdentity]:
"""Compatibility wrapper restricted to the two deployed XIAO identities."""
identity = parse_bootloader_identity(image)
return identity if identity and identity.board_id in (
XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE) else None
def bootloader_caps_storage(image: bytes) -> Optional[int]:
"""Return the one exact supported self-update storage marker, or None."""
found = None
for off in range(0, len(image) - 16 + 1, 4):
if image[off:off + 8] != XIAO_BOOT_CAPS_MAGIC:
continue
abi, codecs = struct.unpack_from("<HH", image, off + 8)
storage = image[off + 12]
if (abi >= BOOT_FORMAT_VER and abi != 0xFFFF and
codecs & (1 << CODEC_FULL) and (storage & ~0x0F) == 0 and
storage & (XIAO_BOOT_STORAGE_QSPI | XIAO_BOOT_STORAGE_UPDATE) ==
(XIAO_BOOT_STORAGE_QSPI | XIAO_BOOT_STORAGE_UPDATE) and
image[off + 13:off + 16] == b"\0\0\0"):
return True
return False
if (abi < BOOT_FORMAT_VER or abi == 0xFFFF or not codecs & (1 << CODEC_FULL) or
storage & ~BOOT_STORAGE_KNOWN or image[off + 13:off + 16] != b"\0\0\0" or
storage not in (BOOT_STORAGE_QSPI_UPDATE, BOOT_STORAGE_INTERNAL_UPDATE)):
continue
if found is not None:
return None
found = storage
return found
def xiao_bootloader_caps_ok(image: bytes) -> bool:
return bootloader_caps_storage(image) == BOOT_STORAGE_QSPI_UPDATE
def validate_bootloader_image(image: bytes, target_id: Optional[int] = None,
signed_hw_id: Optional[bytes] = None) -> BootloaderIdentity:
if len(image) != XIAO_BOOT_IMAGE_SIZE:
raise ValueError(f"bootloader image must be exactly {XIAO_BOOT_IMAGE_SIZE} bytes")
if not _bootloader_vector_sane(image):
raise ValueError("bootloader vector table is invalid")
identity = parse_bootloader_identity(image)
if identity is None:
raise ValueError("bootloader embedded manifest/CRC is invalid or ambiguous")
expected_target = bootloader_target_id(identity.board_id, identity.device_name)
if target_id is not None and target_id != expected_target:
raise ValueError("bootloader target ID does not match embedded identity")
expected_hw = bootloader_hw_id(identity.board_id, identity.device_name)
if signed_hw_id is not None and bytes(signed_hw_id) != expected_hw:
raise ValueError("bootloader signed hw_id does not match embedded identity")
expected_storage = (BOOT_STORAGE_QSPI_UPDATE
if identity.board_id in (XIAO_BOOT_BOARD_ID_BASE,
XIAO_BOOT_BOARD_ID_SENSE)
else BOOT_STORAGE_INTERNAL_UPDATE)
if bootloader_caps_storage(image) != expected_storage:
raise ValueError(f"bootloader lacks exact ABI 3 self-update capabilities 0x{expected_storage:02X}")
return identity
def validate_xiao_bootloader_image(image: bytes, board_id: Optional[int] = None) -> XiaoBootloaderIdentity:
if len(image) != XIAO_BOOT_IMAGE_SIZE:
raise ValueError(f"bootloader image must be exactly {XIAO_BOOT_IMAGE_SIZE} bytes")
if not _xiao_bootloader_vector_sane(image):
raise ValueError("bootloader vector table is invalid")
identity = parse_xiao_bootloader_identity(image)
if identity is None:
raise ValueError("bootloader embedded manifest/CRC is invalid")
identity = validate_bootloader_image(image)
if identity.board_id not in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE):
raise ValueError("bootloader is not a deployed XIAO identity")
if board_id is not None and identity.board_id != board_id:
raise ValueError("bootloader embedded board ID does not match package target")
if not xiao_bootloader_caps_ok(image):
raise ValueError("bootloader lacks ABI 3 QSPI boot-update continuity capabilities")
return identity
@@ -601,16 +723,19 @@ def build_manifest(*, target_id: int, fw_version: int, image_size: int, payload:
assert (block_size & (block_size - 1)) == 0, "block_size must be a power of two"
leaves = leaf_hashes(payload, block_size)
if bootloader:
identity = validate_xiao_bootloader_image(payload, target_id)
identity = validate_bootloader_image(payload, target_id)
audit_bootloader_target_inventory()
if not bootloader_identity_is_buildable(identity.board_id, identity.device_name):
raise ValueError("bootloader embedded identity is not in the qualified build inventory")
if (fw_version == 0 or not is_full or codec_id != CODEC_FULL or
image_size != XIAO_BOOT_IMAGE_SIZE or
block_size != DEFAULT_BLOCK_SIZE or base_hash not in (None, b"\0" * 8)):
raise ValueError("bootloader package needs a nonzero version and a 40 KiB CODEC_FULL image with 1 KiB blocks")
if sign_priv is None:
raise ValueError("bootloader package must be signed")
expected_hw = xiao_bootloader_hw_id(identity.board_id)
if hw_id is not None and hw_id_bytes(hw_id) != hw_id_bytes(expected_hw):
raise ValueError("bootloader package hw_id must be canonical for its embedded board ID")
expected_hw = bootloader_hw_id(identity.board_id, identity.device_name)
if hw_id is not None and hw_id_bytes(hw_id) != expected_hw:
raise ValueError("bootloader package hw_id must be canonical for its embedded identity")
hw_id = expected_hw
m = Manifest(
format_ver=BOOT_FORMAT_VER if bootloader else APP_FORMAT_VER,
@@ -707,10 +832,12 @@ def parse_container(blob: bytes) -> Parsed:
if (m.fw_version == 0 or m.codec_id != CODEC_FULL or
m.image_size != XIAO_BOOT_IMAGE_SIZE or
m.payload_size != XIAO_BOOT_IMAGE_SIZE or
m.block_size_log2 != 10 or m.block_count != 40 or m.base_hash != b"\0" * 8 or
m.target_id not in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE) or
m.hw_id != hw_id_bytes(xiao_bootloader_hw_id(m.target_id))):
m.block_size_log2 != 10 or m.block_count != 40 or m.base_hash != b"\0" * 8):
raise ValueError("v3 bootloader manifest geometry/identity is invalid")
try:
validate_bootloader_image(payload, m.target_id, m.hw_id)
except (UnicodeDecodeError, ValueError) as exc:
raise ValueError(f"v3 bootloader image identity/capability is invalid: {exc}") from exc
return Parsed(manifest=m, payload=payload, total_size=total)
@@ -726,7 +853,7 @@ def verify(parsed: Parsed, *, expect_pub: Optional[bytes] = None,
if m.is_bootloader:
try:
validate_xiao_bootloader_image(payload, m.target_id)
validate_bootloader_image(payload, m.target_id, m.hw_id)
except (UnicodeDecodeError, ValueError) as exc:
problems.append(f"bootloader image contract: {exc}")
@@ -0,0 +1,27 @@
# Install-capable, internal-flash nRF52840 LoRa OTA targets whose exact OTAFIX
# manifest identity and shared ED000/E2000 runtime geometry are qualified. This file is the
# shared allowlist for build.sh release aliases and the subset that are also
# literal PlatformIO envs. Synthetic aliases are activated by build.sh.
# External QSPI/SD, internal ExtraFS, seeder-only, Ethernet, and full-sensor
# roles are intentionally absent.
Heltec_tower_v2_repeater_lora_ota_no_external_sensors
Heltec_t096_repeater_lora_ota_no_external_sensors
Heltec_t096_repeater_bridge_rs232_lora_ota_no_external_sensors
Heltec_t1_repeater_lora_ota_no_external_sensors
GAT562_30S_Mesh_Kit_repeater_lora_ota_no_external_sensors
Heltec_t114_without_display_repeater_lora_ota_no_external_sensors
Heltec_t114_repeater_lora_ota_no_external_sensors
Mesh_pocket_repeater_lora_ota_no_external_sensors
KeepteenLT1_repeater_lora_ota_no_external_sensors
Minewsemi_me25ls01_repeater_lora_ota_no_external_sensors
ProMicro_repeater_lora_ota_no_external_sensors
t1000e_repeater_lora_ota_no_external_sensors
ThinkNode_M3_repeater_lora_ota_no_external_sensors
RAK_3401_repeater_lora_ota_no_external_sensors
RAK_4631_repeater_lora_ota_no_external_sensors
RAK_4631_repeater_bridge_rs232_serial1_lora_ota_no_external_sensors
RAK_4631_repeater_bridge_rs232_serial2_lora_ota_no_external_sensors
GAT562_Mesh_Tracker_Pro_repeater_lora_ota_no_external_sensors
R1Neo_repeater_lora_ota_no_external_sensors
GAT562_Mesh_EVB_Pro_repeater_lora_ota_no_external_sensors
RAK_WisMesh_Tag_repeater_lora_ota_no_external_sensors
+9 -3
View File
@@ -179,23 +179,29 @@ def _append_endf_hex(source, target, env): # Intel-HEX path (nRF52: app f
and _builds_companion_radio())
sd_backed = _cppdef("OTA_SD_STORE") is not None
qspi_backed = _cppdef("OTA_QSPI_STORE") is not None
bootloader_update = _cppdef("OTA_QSPI_BOOTLOADER_UPDATE") is not None
qspi_bootloader_update = _cppdef("OTA_QSPI_BOOTLOADER_UPDATE") is not None
internal_bootloader_update = _cppdef("OTA_INTERNAL_BOOTLOADER_UPDATE") is not None
if sd_backed and qspi_backed:
raise RuntimeError("nRF52 build cannot enable both SD and QSPI OTA stores")
if qspi_backed and _cppdef("QSPIFLASH") is not None:
raise RuntimeError("raw QSPI OTA staging cannot share a chip with QSPIFLASH")
if bootloader_update:
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 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")
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 else 0) |
(ml.NRF52_LAYOUT_FLAG_INTERNAL_EXTRAFS if internal_extrafs else 0) |
(ml.NRF52_LAYOUT_FLAG_BOOTLOADER_SCRATCH if bootloader_update else 0))
(ml.NRF52_LAYOUT_FLAG_BOOTLOADER_SCRATCH if qspi_bootloader_update else 0))
layout = ml.Nrf52Layout(app_start, linked_app_end, stage_ceiling, layout_flags)
body = ml.ensure_nrf52_layout(raw_body, layout)
ident = _firmware_ident()
+139 -3
View File
@@ -13,6 +13,7 @@ import io
import os
import random
import struct
from pathlib import Path
import motalib as ml
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
@@ -40,8 +41,34 @@ def test_target_id_for_env():
assert ml.target_id_for_env("RAK_4631_repeater") != ml.target_id_for_env("RAK_4631_companion_radio_usb")
def test_internal_bootloader_target_wiring_is_central_and_not_duplicated():
root = Path(__file__).resolve().parents[2]
inventory = [
line.strip()
for line in (root / "tools/mota/nrf52_internal_bootloader_targets.txt")
.read_text(encoding="utf-8").splitlines()
if line.strip() and not line.lstrip().startswith("#")
]
assert len(inventory) == len(set(inventory))
assert len(inventory) == 21
target_header = (root / "src/helpers/ota/OtaTargets.h").read_text(encoding="utf-8")
for target in inventory:
assert f'"{target}"' in target_header
pio = (root / "platformio.ini").read_text(encoding="utf-8")
nrf52_base = pio.split("[nrf52_base]", 1)[1].split("\n[", 1)[0]
assert nrf52_base.count("pre:scripts/nrf52_internal_bootloader_link.py") == 1
build = (root / "build.sh").read_text(encoding="utf-8")
recipe = build.split("apply_nrf52_lora_ota_build_recipe()", 1)[1]
recipe = recipe.split("supports_nrf52_internal_bootloader_update()", 1)[0]
assert "scripts/nrf52_internal_bootloader_link.py" not in recipe
assert "export MESHCORE_NRF52_INTERNAL_BOOTLOADER_UPDATE=1" in recipe
def test_ota_target_generation_honors_explicit_disable():
from gen_targets import ota_envs
from gen_targets import ota_envs, release_aliases
cfg = [
["env:enabled", [["build_flags", ["-D ENABLE_OTA=1"]]]],
@@ -49,6 +76,7 @@ def test_ota_target_generation_honors_explicit_disable():
["env:unrelated", [["build_flags", ["-D NRF52_PLATFORM"]]]],
]
assert ota_envs(cfg) == ["enabled"]
assert "RAK_3401_repeater_lora_ota_no_external_sensors" in release_aliases()
def test_hardware_id_for_env():
@@ -150,6 +178,15 @@ def test_nrf52_layout_record_roundtrip_and_policy():
boot_qspi_image, _ = ml.ensure_endf(ml.ensure_nrf52_layout(_fw(8, 2048), boot_qspi))
assert ml.parse_nrf52_layout(boot_qspi_image) == boot_qspi
assert boot_qspi.bootloader_scratch
shared_internal = ml.Nrf52Layout(
ml.NRF52_APP_BASE_S140_V6, ml.NRF52_APP_END,
ml.NRF52_APP_END, 0)
shared_internal_image, _ = ml.ensure_endf(
ml.ensure_nrf52_layout(_fw(9, 2048), shared_internal))
assert ml.parse_nrf52_layout(shared_internal_image) == shared_internal
assert not shared_internal.bootloader_scratch
assert ((ml.NRF52_APP_END - ml.NRF52_BOOT_CONTAINER_SIZE) &
~(ml.NRF52_FLASH_PAGE - 1)) == ml.NRF52_SHARED_BOOT_STAGE_START
try:
ml.build_nrf52_layout(ml.Nrf52Layout(
ml.NRF52_APP_BASE_S140_V7, ml.NRF52_EXTRAFS_START,
@@ -160,6 +197,7 @@ def test_nrf52_layout_record_roundtrip_and_policy():
for flags in (
ml.NRF52_LAYOUT_FLAG_SD | ml.NRF52_LAYOUT_FLAG_QSPI,
ml.NRF52_LAYOUT_FLAG_QSPI | ml.NRF52_LAYOUT_FLAG_INTERNAL_EXTRAFS,
0x10,
):
try:
ml.build_nrf52_layout(ml.Nrf52Layout(
@@ -176,7 +214,7 @@ def _xiao_bootloader_image(board_id=ml.XIAO_BOOT_BOARD_ID_BASE):
struct.pack_into("<II", image, 0, 0x20040000, ml.XIAO_BOOT_IMAGE_START + 0x101)
struct.pack_into("<8sHHB3x", image, 0x80, ml.XIAO_BOOT_CAPS_MAGIC,
ml.BOOT_FORMAT_VER, 1 << ml.CODEC_FULL,
ml.XIAO_BOOT_STORAGE_QSPI | ml.XIAO_BOOT_STORAGE_UPDATE)
ml.BOOT_STORAGE_QSPI_UPDATE)
name = ml.XIAO_BOOT_DEVICE_NAME
struct.pack_into("<8sHHIII16sI", image, 0x100, ml.XIAO_BOOT_MANIFEST_MAGIC,
ml.XIAO_BOOT_MANIFEST_VERSION, ml.XIAO_BOOT_MANIFEST_SIZE,
@@ -186,6 +224,21 @@ def _xiao_bootloader_image(board_id=ml.XIAO_BOOT_BOARD_ID_BASE):
return bytes(image)
def _generic_bootloader_image(board_id=0x239A0029, device_name="3401_DFU"):
import zlib
image = bytearray(b"\xff" * ml.XIAO_BOOT_IMAGE_SIZE)
struct.pack_into("<II", image, 0, 0x20040000, ml.XIAO_BOOT_IMAGE_START + 0x101)
struct.pack_into("<8sHHB3x", image, 0x80, ml.XIAO_BOOT_CAPS_MAGIC,
ml.BOOT_FORMAT_VER, 1 << ml.CODEC_FULL,
ml.BOOT_STORAGE_INTERNAL_UPDATE)
name = device_name.encode("ascii").ljust(16, b"\0")
struct.pack_into("<8sHHIII16sI", image, 0x100, ml.XIAO_BOOT_MANIFEST_MAGIC,
ml.XIAO_BOOT_MANIFEST_VERSION, ml.XIAO_BOOT_MANIFEST_SIZE,
ml.XIAO_BOOT_IMAGE_START, ml.XIAO_BOOT_IMAGE_SIZE, board_id, name, 0)
struct.pack_into("<I", image, 0x100 + 40, zlib.crc32(image) & 0xFFFFFFFF)
return bytes(image)
def _xiao_manifest_crc(image, offset):
import zlib
trial = bytearray(image)
@@ -269,7 +322,7 @@ def test_xiao_bootloader_identity_skips_bad_decoy_and_rejects_two_valid_manifest
def test_xiao_bootloader_caps_rejects_malformed_or_unaligned_markers():
def caps(*, offset=0, abi=ml.BOOT_FORMAT_VER,
codecs=1 << ml.CODEC_FULL,
storage=ml.XIAO_BOOT_STORAGE_QSPI | ml.XIAO_BOOT_STORAGE_UPDATE,
storage=ml.BOOT_STORAGE_QSPI_UPDATE,
reserved=b"\0\0\0"):
image = bytearray(b"\xff" * 64)
struct.pack_into("<8sHHB3s", image, offset, ml.XIAO_BOOT_CAPS_MAGIC,
@@ -282,6 +335,11 @@ def test_xiao_bootloader_caps_rejects_malformed_or_unaligned_markers():
assert not ml.xiao_bootloader_caps_ok(caps(codecs=0))
assert not ml.xiao_bootloader_caps_ok(caps(storage=0x1C))
assert not ml.xiao_bootloader_caps_ok(caps(reserved=b"\0\x01\0"))
duplicate = bytearray(caps())
struct.pack_into("<8sHHB3s", duplicate, 24, ml.XIAO_BOOT_CAPS_MAGIC,
ml.BOOT_FORMAT_VER, 1 << ml.CODEC_FULL,
ml.BOOT_STORAGE_INTERNAL_UPDATE, b"\0\0\0")
assert ml.bootloader_caps_storage(bytes(duplicate)) is None
def test_bootloader_v3_build_parse_and_strict_contract():
@@ -323,6 +381,84 @@ def test_bootloader_v3_build_parse_and_strict_contract():
pass
def test_generic_internal_bootloader_build_parse_and_strict_contract():
priv = Ed25519PrivateKey.generate()
image = _generic_bootloader_image()
identity = ml.validate_bootloader_image(image)
assert identity.board_id == 0x239A0029 and identity.device_name == "3401_DFU"
target = ml.bootloader_target_id(identity.board_id, identity.device_name)
assert target == 0x23818A80
expected_hw = b"NRF_BL_239A0029_3401_DFU".ljust(32, b"\0")
assert ml.bootloader_hw_id(identity.board_id, identity.device_name) == expected_hw
manifest = ml.build_manifest(
target_id=target, fw_version=ml.pack_version("1.0.0"),
image_size=len(image), payload=image, block_size=1024,
image_hash=ml.mh32(image), codec_id=ml.CODEC_FULL, is_full=True,
sign_priv=priv, bootloader=True)
parsed = ml.parse_container(ml.build_container(manifest, image))
assert parsed.manifest.target_id == target
assert parsed.manifest.hw_id == expected_hw
assert ml.verify(parsed, expect_pub=priv.public_key().public_bytes_raw()) == []
wrong_target = target ^ 1
try:
ml.build_manifest(
target_id=wrong_target, fw_version=1, image_size=len(image), payload=image,
block_size=1024, image_hash=ml.mh32(image), codec_id=ml.CODEC_FULL,
is_full=True, sign_priv=priv, bootloader=True)
assert False, "generic bootloader raw/wrong target accepted"
except ValueError:
pass
def test_bootloader_build_inventory_is_unique_and_disjoint_from_app_targets():
import re
expected = {
(0x239A0071, "TOWER_V2_OTA"): 0x1150F50E,
(0x239A0071, "T096_DFU"): 0x42354C85,
(0x239A0071, "T1_DFU"): 0xFC556FFC,
(0x239A0071, "T114_DFU"): 0x0C3F2902,
(0x239A0071, "MESH_POCKET_OTA"): 0x059277F4,
(0x239A00B3, "KeepteenLT1_OTA"): 0xDB2E7B51,
(0x239A0029, "MX25_DFU"): 0x026AA982,
(0x239A00B3, "PROM_DFU"): 0xAF79E8CC,
(0x28860057, "T1KE_DFU"): 0xE6F5F03F,
(0x239A00DA, "TNM3_DFU"): 0x0CA41DB2,
(0x239A0029, "3401_DFU"): 0x23818A80,
(0x239A0029, "4631_DFU"): 0x2D0DF000,
(0x239A0029, "RTAG_DFU"): 0xC72E9C9C,
}
assert set(ml.INTERNAL_BOOTLOADER_IDENTITIES) == set(expected)
for identity, target in expected.items():
assert ml.bootloader_target_id(*identity) == target
root = Path(__file__).resolve().parents[2]
target_header = (root / "src/helpers/ota/OtaTargets.h").read_text(encoding="utf-8")
app_targets = {
int(value, 16)
for value in re.findall(r"\{ 0x([0-9a-fA-F]{8}),", target_header)
}
audited = ml.audit_bootloader_target_inventory(app_targets)
assert len(audited) == len(expected) + 2 # generic internal plus two legacy XIAOs
# Generic parsing remains useful for inspecting a future candidate, but a
# signing/build call fails closed until its exact identity is qualified.
image = _generic_bootloader_image(device_name="UNKNOWN_DFU")
identity = ml.validate_bootloader_image(image)
target = ml.bootloader_target_id(identity.board_id, identity.device_name)
priv = Ed25519PrivateKey.generate()
try:
ml.build_manifest(
target_id=target, fw_version=1, image_size=len(image), payload=image,
block_size=1024, image_hash=ml.mh32(image), codec_id=ml.CODEC_FULL,
is_full=True, sign_priv=priv, bootloader=True)
assert False, "unqualified generic bootloader package build accepted"
except ValueError:
pass
def test_bootloader_builder_rejects_wrong_identity_geometry_and_continuity():
priv = Ed25519PrivateKey.generate()
image = _xiao_bootloader_image()