Add MeshTower SD bootloader updates over LoRa

This commit is contained in:
mikecarper committed 2026-08-21 09:55:15 -07:00
1 parent 9e4d246ac6
commit 3d78d9c846
26 files changed
+763 -114

No files matched your search

+9 -5
View File
@@ -58,17 +58,21 @@ 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 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
manifest/CRC identity, and an ABI-3 marker retaining both application codecs
(`FULL|INPLACE`, mask `0x0005`), the selected storage, and 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.
builder accepts only identities in the qualified inventory. That inventory
currently covers the shared-internal nRF52840 targets, the two deployed XIAO
raw-QSPI identities, and the exact MeshTower V2 identity whose candidate
marker may select either its internal (`0x0A`) or microSD (`0x09`) application
layout. 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
+26 -8
View File
@@ -92,13 +92,17 @@ 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_SD = 0x01
BOOT_STORAGE_STAGE_CEILING = 0x02
XIAO_BOOT_STORAGE_QSPI = 0x04
XIAO_BOOT_STORAGE_UPDATE = 0x08
BOOT_STORAGE_KNOWN = 0x0F
BOOT_STORAGE_SD_UPDATE = BOOT_STORAGE_SD | XIAO_BOOT_STORAGE_UPDATE
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
BOOT_REQUIRED_APP_CODEC_MASK = ((1 << CODEC_FULL) |
(1 << CODEC_DETOOLS_INPLACE))
# Exact embedded manifests for the qualified shared-internal nRF52840
# bootloaders. Parsing/inspection remains generic, but package creation is
@@ -121,6 +125,14 @@ INTERNAL_BOOTLOADER_IDENTITIES = (
(0x239A0029, "RTAG_DFU"),
)
# MeshTower V2 has both a lean internal-store application and an exact SD-store
# application. They intentionally retain the same embedded bootloader identity
# and signed wire target; the candidate capability marker selects the matching
# storage contract and is checked again by the device before approval.
SD_BOOTLOADER_IDENTITIES = (
(0x239A0071, "TOWER_V2_OTA"),
)
# 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.
# This is deliberately target-specific: other nRF52 OTA builds still need NRF52_INPLACE_MEMORY above.
@@ -659,9 +671,11 @@ def bootloader_caps_storage(image: bytes) -> Optional[int]:
continue
abi, codecs = struct.unpack_from("<HH", image, off + 8)
storage = image[off + 12]
if (abi < BOOT_FORMAT_VER or abi == 0xFFFF or not codecs & (1 << CODEC_FULL) or
if (abi < BOOT_FORMAT_VER or abi == 0xFFFF or
codecs & BOOT_REQUIRED_APP_CODEC_MASK != BOOT_REQUIRED_APP_CODEC_MASK 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)):
storage not in (BOOT_STORAGE_SD_UPDATE, BOOT_STORAGE_QSPI_UPDATE,
BOOT_STORAGE_INTERNAL_UPDATE)):
continue
if found is not None:
return None
@@ -688,12 +702,16 @@ def validate_bootloader_image(image: bytes, target_id: Optional[int] = None,
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}")
if identity.board_id in (XIAO_BOOT_BOARD_ID_BASE, XIAO_BOOT_BOARD_ID_SENSE):
expected_storage = (BOOT_STORAGE_QSPI_UPDATE,)
elif (identity.board_id, identity.device_name) in SD_BOOTLOADER_IDENTITIES:
expected_storage = (BOOT_STORAGE_INTERNAL_UPDATE, BOOT_STORAGE_SD_UPDATE)
else:
expected_storage = (BOOT_STORAGE_INTERNAL_UPDATE,)
actual_storage = bootloader_caps_storage(image)
if actual_storage not in expected_storage:
expected = "/".join(f"0x{value:02X}" for value in expected_storage)
raise ValueError(f"bootloader lacks exact ABI 3 self-update capabilities {expected}")
return identity
+8 -1
View File
@@ -181,6 +181,7 @@ def _append_endf_hex(source, target, env): # Intel-HEX path (nRF52: app f
qspi_backed = _cppdef("OTA_QSPI_STORE") 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
sd_bootloader_update = _cppdef("OTA_SD_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:
@@ -196,6 +197,11 @@ def _append_endf_hex(source, target, env): # Intel-HEX path (nRF52: app f
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) |
@@ -226,7 +232,8 @@ def _append_endf_hex(source, target, env): # Intel-HEX path (nRF52: app f
for i, b in enumerate(suffix):
ih[app_end + i] = b # write it right after the app's last byte
ih.write_hex_file(path)
print(f"EndF: appended to {os.path.basename(path)} at 0x{app_end:X} "
endf_address = app_start + len(body)
print(f"EndF: appended to {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})")
+38 -6
View File
@@ -213,7 +213,7 @@ def _xiao_bootloader_image(board_id=ml.XIAO_BOOT_BOARD_ID_BASE):
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_FORMAT_VER, ml.BOOT_REQUIRED_APP_CODEC_MASK,
ml.BOOT_STORAGE_QSPI_UPDATE)
name = ml.XIAO_BOOT_DEVICE_NAME
struct.pack_into("<8sHHIII16sI", image, 0x100, ml.XIAO_BOOT_MANIFEST_MAGIC,
@@ -224,13 +224,14 @@ 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"):
def _generic_bootloader_image(board_id=0x239A0029, device_name="3401_DFU",
storage=ml.BOOT_STORAGE_INTERNAL_UPDATE):
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)
ml.BOOT_FORMAT_VER, ml.BOOT_REQUIRED_APP_CODEC_MASK,
storage)
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,
@@ -321,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,
codecs=ml.BOOT_REQUIRED_APP_CODEC_MASK,
storage=ml.BOOT_STORAGE_QSPI_UPDATE,
reserved=b"\0\0\0"):
image = bytearray(b"\xff" * 64)
@@ -333,11 +334,12 @@ def test_xiao_bootloader_caps_rejects_malformed_or_unaligned_markers():
assert not ml.xiao_bootloader_caps_ok(caps(offset=1))
assert not ml.xiao_bootloader_caps_ok(caps(abi=0xFFFF))
assert not ml.xiao_bootloader_caps_ok(caps(codecs=0))
assert not ml.xiao_bootloader_caps_ok(caps(codecs=1 << ml.CODEC_FULL))
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_FORMAT_VER, ml.BOOT_REQUIRED_APP_CODEC_MASK,
ml.BOOT_STORAGE_INTERNAL_UPDATE, b"\0\0\0")
assert ml.bootloader_caps_storage(bytes(duplicate)) is None
@@ -412,6 +414,36 @@ def test_generic_internal_bootloader_build_parse_and_strict_contract():
pass
def test_meshtower_sd_bootloader_profile_builds_the_same_exact_identity():
priv = Ed25519PrivateKey.generate()
image = _generic_bootloader_image(
board_id=0x239A0071, device_name="TOWER_V2_OTA",
storage=ml.BOOT_STORAGE_SD_UPDATE)
identity = ml.validate_bootloader_image(image)
assert (identity.board_id, identity.device_name) in ml.SD_BOOTLOADER_IDENTITIES
assert ml.bootloader_caps_storage(image) == 0x09
target = ml.bootloader_target_id(identity.board_id, identity.device_name)
assert target == 0x1150F50E
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.hw_id == b"NRF_BL_239A0071_TOWER_V2_OTA".ljust(32, b"\0")
assert ml.verify(parsed, expect_pub=priv.public_key().public_bytes_raw()) == []
def test_meshtower_sd_bootloader_build_flag_is_exact_target_only():
root = Path(__file__).resolve().parents[2]
text = (root / "variants/heltec_tower_v2/platformio.ini").read_text(encoding="utf-8")
section = text.split(
"[env:Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors]", 1)[1]
section = section.split("[env:", 1)[0]
assert "-D OTA_SD_STORE=1" in section
assert "-D OTA_SD_BOOTLOADER_UPDATE=1" in section
def test_bootloader_build_inventory_is_unique_and_disjoint_from_app_targets():
import re