Harden signed SD and bootloader OTA

This commit is contained in:
mikecarper committed 2026-08-21 12:15:54 -07:00
1 parent 3d78d9c846
commit d9f5dfa8a2
29 files changed
+1846 -408

No files matched your search

+5
View File
@@ -69,6 +69,11 @@ while the same link carries framed folder requests. BLE remains available.
| nRF52 repeater, external QSPI | Full image or in-place delta | QSPI-aware exact-board OTAFIX bootloader and matched repeater build | Builds a full mOTA; adding `--base` requests a delta |
| MeshTower V2 nRF52, microSD | Full image or in-place delta | SD-aware exact-board OTAFIX bootloader and compatible card | Builds a full mOTA; adding `--base` requests a delta |
MeshTower V2 microSD application and bootloader containers require an Ed25519 signature from a key in the
device allowlist. Supply `--sign-key` when the runner must build a container, and install the BLM2-capable
SD-aware bootloader locally before attempting application or bootloader OTA. Preview.12 requires USB/BLE
DFU or SWD; see [MeshTower V2 microSD LoRa OTA](ota_meshtower_v2_sdcard.md).
The firmware inside a raw ZIP must have a valid MeshCore `EndF` trailer. An
ESP32 merged/factory image is not an application image and is rejected. A
generic vendor DFU ZIP may also be unusable if it does not contain the raw
+5
View File
@@ -18,6 +18,11 @@ Matched QSPI repeater targets and the MeshTower V2 microSD target can also insta
complete container stays off-chip. See [nRF52 repeater OTA with external QSPI](ota_nrf52_qspi.md) and
[MeshTower V2 microSD LoRa OTA](ota_meshtower_v2_sdcard.md).
MeshTower V2 microSD application and bootloader containers must be Ed25519-signed by a key in the device
allowlist; pass `--sign-key` when building one. Its BLM2-capable SD-aware bootloader is also required before
ordinary application or bootloader OTA can use the reset-retained authorization record. Upgrade preview.12
locally over USB/BLE DFU or SWD first; there is no raw-card compatibility handoff.
## Temporary OTA channel used in this guide
| Setting | Value |
+57 -33
View File
@@ -22,14 +22,16 @@ LoRa radio pinout.
## Card requirements
Use a FAT16, FAT32, or exFAT card with an MBR partition table whose first
partition starts after sector 1. This is the normal layout produced by most SD
formatters. GPT and unpartitioned "super-floppy" layouts are rejected.
Use a FAT16, FAT32, or exFAT card accepted by the bundled SdFat version. The
normal update path imposes no additional MBR/sector-1 layout requirement;
filesystem layouts SdFat cannot mount are still rejected. MeshCore creates
`/meshcore-ota.mota` as a contiguous file and passes its exact sector range to
OTAFIX in reset-retained MCU RAM.
MeshCore creates `/meshcore-ota.mota` as a contiguous file. Sector 1, which is
outside the partition, holds a checksummed bootloader handoff record. The
firmware validates this gap before writing it; an incompatible card layout
fails safely without modifying sector 1.
MeshCore never reads or writes raw sector 1 and does not infer ownership from
blank card sectors. Both application and bootloader OTA require a locally
provisioned BLM2-capable bootloader that understands the retained-RAM record.
Preview.12 must first be upgraded over USB/BLE DFU or SWD.
## Capacity and update types
@@ -43,7 +45,8 @@ For this S140 v6 target, the maximum application image including its `EndF`
trailer is `0xC7000` bytes (815,104 bytes). To package a full self-update:
```bash
motatool build --fw ./Heltec_tower_v2_sdcard-new.hex --out-dir ./motas
motatool build --fw ./Heltec_tower_v2_sdcard-new.hex \
--sign-key ./trusted-signer.key --out-dir ./motas
motatool verify ./motas/*.mota
```
@@ -57,19 +60,23 @@ motatool build \
--fw ./Heltec_tower_v2_sdcard-new.hex \
--patch-type in-place \
--inplace-memory 0xC7000 \
--sign-key ./trusted-signer.key \
--out-dir ./motas
motatool verify ./motas/*.mota
```
The download is resumable because the partial `.mota` stays on the card.
Once it reaches `ready`, `ota install` performs the final verification,
publishes the bootloader handoff, and reboots. Keep the card inserted through
the reboot and installation.
publishes a one-reset authorization record, and reboots. SD application
installation requires a valid signature from a key in the node's allowlist.
Keep the card inserted through the reboot and installation.
The SD-aware bootloader is mandatory. `ota install` refuses to reboot if the
bootloader capability marker does not advertise SD staging and the selected
codec. Existing `Heltec_tower_v2_repeater` firmware continues to use the
internal-flash delta path and is unchanged.
The BLM2 retained-auth SD-aware bootloader is mandatory for application OTA.
`ota install` refuses to reboot if its continuity metadata does not match the
running S140 family/FWID/application layout or if its capability marker does
not advertise SD staging and the selected codec. Existing
`Heltec_tower_v2_repeater` firmware continues to use the internal-flash delta
path and is unchanged.
## Signed bootloader update
@@ -78,14 +85,15 @@ It requires an already installed exact-board ABI-3 OTAFIX bootloader whose one
unambiguous capability marker is exactly `0x09` (`SD|BOOT_UPDATE`) and whose
codec mask is `0x0005` (`FULL|INPLACE`). Requiring both application codecs
prevents a bootloader self-update from disabling either normal SD application
path. It cannot bootstrap a stock or older bootloader; provision that
prerequisite once over USB/BLE DFU or SWD.
path. A stock bootloader still requires USB/BLE DFU or SWD. The sole remote
bootstrap is intentionally absent: preview.12 and any other legacy-v1 image
must be upgraded locally before either SD application or bootloader OTA.
The signed v3 container is exactly 41,330 bytes and carries a 40 KiB candidate
for the installed `239A0071 / TOWER_V2_OTA` identity (boot target `1150F50E`).
It uses the same contiguous `/meshcore-ota.mota` file and sector-1 handoff as an
application update. GPREGRET `0x6B` plus the distinct SD source marker `0x53`
selects the bootloader path; LoRa transport remains payload type `0x0C`.
It uses the same contiguous `/meshcore-ota.mota` file as an application update.
GPREGRET `0x6B` plus the distinct SD source marker `0x53` selects the bootloader
path; LoRa transport remains payload type `0x0C`.
The application linker still ends at `0xED000`, but OTAFIX needs
`0xE0000..0xEA000` as temporary scratch while replacing itself. Before a boot
@@ -102,17 +110,33 @@ EndF-inclusive running image and must end by `0xE0000`; an undersized or
oversized record refuses the operation and requires local DFU/SWD.
Because the card is removable, approval is bound to the exact bytes that were
authenticated. MeshCore verifies the signature and signer allowlist over one
exact local manifest copy, requires the streamed manifest on SD to remain
byte-identical, and verifies the complete payload against that manifest. It
then writes `APRV` and syncs the card. Before publishing the raw-sector
handoff, it writes and readback-verifies a temporary 64-byte `MOTASDBL` token
at `0xE0000` containing the exact container length and that signed manifest's
`image_hash`. OTAFIX requires the parsed SD manifest, streamed payload, and
final scratch image to match the same token. Replacing or changing the card
after verification can therefore only make the boot update fail; it cannot
authorize different bootloader bytes. The token page becomes the first
scratch page during a successful update and is not permanently reserved.
authenticated. For both fmt2 application and fmt3 bootloader packages,
MeshCore authenticates one exact signed manifest, requires every streamed
manifest byte to match it, and verifies the leaves, payload, and image. During
that same pass it hashes the entire container with only the mutable four-byte
`APRV` field normalized to zero. After writing and syncing `APRV`, MeshCore
publishes a 72-byte `MOTASDA2` record at reset-retained RAM address
`0x20006008`. The record binds package purpose/format, exact LBA range, card
size, container length, and that normalized SHA-256. OTAFIX consumes and clears
the record before reading the card; changing the card or file can only fail.
A power loss erases the authorization and also fails closed.
For fmt3, MeshCore additionally writes and readback-verifies the temporary
64-byte `MOTASDBL` token at `0xE0000`, binding the exact total and signed
manifest `image_hash`. OTAFIX requires the parsed manifest, streamed payload,
and final scratch image to match it. The token page becomes scratch during a
successful boot update and is not permanently reserved.
Every new candidate also carries a backward-compatible `BLM2`/`SOFT`
continuity extension next to its legacy embedded manifest. The complete
76-byte envelope is fixed at final raw-image offset `0x9FB4`; a relocated copy
is not a valid candidate. Its embedded
bootloader version must equal the outer package version, match the runtime
SoftDevice family/FWID, application base, and layout ABI, and be strictly newer
than an installed BLM2 version. Preview values use low bytes `1..254` and a
stable release uses `0xFF`; zero-preview and all-ones versions are invalid.
Remote bootloader rollback is not supported; use local DFU/SWD when rollback
or migration is intentional.
Bootloader packages are never autofetched or autoinstalled. Select and confirm
one exact package manually:
@@ -235,9 +259,9 @@ clean replacement instead of treating path existence as a valid cache hit.
To prepare and load the card:
1. Format it as described under [Card requirements](#card-requirements). The
easiest way to guarantee the expected layout is to insert it in the
repeater, run `set sdcard format`, power the repeater off, and then move the
card to the computer. Formatting destroys the existing card contents.
easiest route is to insert it in the repeater, run `set sdcard format`, power
the repeater off, and then move the card to the computer. Formatting destroys
the existing card contents.
2. Mount the card on the computer and create a directory named `mota` at the
filesystem root. Do not use a nested directory such as `/firmware/mota`.
3. Run `motatool verify FILE.mota` for every source file. Do not copy a file
+64 -24
View File
@@ -2,9 +2,10 @@
Selected nRF52840 repeater LoRa-OTA builds can replace their matching OTAFIX
bootloader without replacing the running application. This is a privileged
maintenance path, not a normal firmware update. It cannot bootstrap a stock or
older bootloader: install the exact ABI-3 self-update-capable OTAFIX build once
over USB/BLE DFU or SWD.
maintenance path, not a normal firmware update. A stock bootloader must first
be replaced with the exact ABI-3 self-update-capable OTAFIX build over USB/BLE
DFU or SWD. MeshTower SD also requires the BLM2 retained-auth version to be
provisioned locally before either application or bootloader OTA.
## Storage layouts
@@ -28,17 +29,29 @@ replace `0xF4000..0xFE000`. The application linker remains at `0xED000`; a
future application extending above `0xE0000` can still use application mOTA
but must update its bootloader through local DFU/SWD.
The removable SD authorization is fail-closed. MeshCore directly authenticates
one exact manifest, requires the streamed manifest on SD to remain
byte-identical, and verifies its complete payload. After writing and syncing
`APRV`, but before publishing the raw-sector handoff, it writes and
readback-verifies a 64-byte `MOTASDBL` token at `0xE0000`. The token contains
the exact container length and the authenticated signed manifest's
`image_hash`. OTAFIX requires that same hash in the parsed manifest, the
streamed raw payload, and the final scratch image. A card swap or mutation
after application verification therefore causes refusal rather than
authorizing different bytes; the token page is consumed as scratch during a
successful update and is not a permanent reservation.
The removable SD authorization is fail-closed for both application and
bootloader packages. MeshCore directly authenticates one exact signed
manifest, requires the streamed copy to remain byte-identical, verifies all
leaves/payload/image bytes, and computes a normalized full-container SHA-256 in
that same pass (`APRV` bytes are treated as zero). After syncing `APRV`, it
publishes a 72-byte `MOTASDA2` record in reset-retained RAM at `0x20006008`.
That record binds purpose/format, first LBA, sector count, total length, card
sector count, and the normalized digest. OTAFIX copies, validates, and clears
the record before SD access. A card swap/mutation or a power cycle therefore
fails closed; there is no general sector-1 ownership inference.
For fmt3, MeshCore also writes and readback-verifies a 64-byte `MOTASDBL` token
at `0xE0000`. That token contains the exact container length and the exact
authenticated signed manifest `image_hash`. OTAFIX requires the same hash in
the parsed manifest, streamed payload, and final scratch image. The page is
consumed as scratch during success and is not permanently reserved.
The first BLM2-capable MeshTower bootloader cannot be delivered to preview.12
through the retained-RAM protocol that preview.12 predates. MeshCore does not
write a raw-sector compatibility record because a blank sector is not proof of
ownership. Upgrade preview.12 through USB/BLE DFU or SWD. Both fmt2 application
and fmt3 bootloader OTA then require the installed BLM2 metadata to match the
live SoftDevice/application layout; neither MeshCore nor OTAFIX uses sector 1.
The internal path does not change the application linker or permanently set
aside separate app-OTA, boot-package, and scratch regions. The ordinary
@@ -105,6 +118,30 @@ duplicates and collisions with application target IDs. Generic image parsing
can inspect a future canonical identity, but signing/building a package fails
until that exact identity is in the qualified inventory.
## Embedded continuity and version policy
Every remotely supplied successor retains the legacy 44-byte CRC-valid `BLMF`
v1 record for identity continuity and diagnostics. Immediately after that
record is a 32-byte `BLM2`/`SOFT` extension. The complete 76-byte envelope is
fixed at the final raw-image offset `0x9FB4`; relocated candidates are refused,
while installed legacy-v1 discovery remains a generic diagnostic scan. The extension carries the actual packed
bootloader version, SoftDevice family and FWID, application base, layout ABI,
and zero compatibility/reserved fields; the legacy whole-image CRC covers the
extension too. Scanners first count CRC-valid 44-byte base manifests, then
interpret continuity only after one base identity remains. A malformed claimed
extension therefore cannot make a duplicate identity disappear, and a sole
half-present extension is rejected rather than treated as legacy.
MeshCore requires the candidate extension, exact equality between its embedded
version and the signed outer mOTA version, and exact agreement with the running
SoftDevice family/FWID/application layout. Qualified internal/QSPI paths may
bootstrap a CRC-valid installed legacy-v1 image once; the SD path never does
and requires local BLM2 provisioning. Once the installed bootloader has BLM2
metadata, the candidate version must be strictly greater. Preview low bytes are `1..254`, a
stable release uses `0xFF`, and low-byte zero or all-ones values are rejected.
There is no remote rollback/migration override; intentional rollback uses
USB/BLE DFU or SWD.
The `no_external_sensors` profiles omit optional/add-on sensor and GPS packages
to preserve flash headroom. Board-integrated GPS can be retained by a board's
recipe. The RAK3401 lean target specifically omits RAK12501/add-on GPS; use the
@@ -156,9 +193,12 @@ Before writing `APRV`, the application authenticates and authorizes the
package: exact v3 geometry, trusted Ed25519 signer, signed/embedded identity,
one unambiguous capability marker, embedded CRC, sane vectors, complete
Merkle/payload/image hashes, storage-specific safe live placement, and the
typed MID/hash confirmation. On SD, `APRV` and the internal signed-image-hash
token are synced and read back before the handoff becomes visible. OTAFIX consumes that application-written
authorization and then
typed MID/hash confirmation. The manifest root and target inside the received
manifest must also equal the MID/target that opened the fetch before any store
is allocated. On SD, `APRV`, the retained geometry/container authorization,
and the internal signed-image-hash token are published in that order before
the reset trigger. OTAFIX consumes that application-written authorization and
then
independently rechecks the safety/integrity subset: strict v3 structure,
canonical identity/capabilities, vectors, full payload SHA, embedded manifest
CRC, the applicable live `EndF`/bank-settings no-overlap geometry, the SD token
@@ -173,13 +213,13 @@ headroom is insufficient, an unsupported external/ExtraFS role owns the target,
the exact installed capability marker is absent or ambiguous, identity cannot be derived
unambiguously, or any package check fails. Before the storage-specific
scratch/copy step, the application and bootloader are unchanged. OTAFIX
consumes the trigger and, for internal/QSPI storage, clears approval before its
first scratch erase, so an interrupted operation cannot retry a partly
consumed package. The SD backend cannot rewrite raw card sectors: its `APRV`
and checksummed handoff may persist, but the one-shot GPREGRET trigger is
consumed before validation and they remain inert unless the running app again
authenticates and explicitly re-arms that package. Use USB/BLE DFU or SWD for
initial provisioning and local recovery.
consumes the trigger and authorization before its first destructive action, so
an interrupted operation cannot automatically retry a partly consumed
package. On SD, the retained-RAM authorization is zero-consumed before media
access; `APRV` and the fmt3 flash token may persist but are inert without a new
explicit authenticated re-arm and reset trigger. No SD raw-sector handoff is
created or consumed.
Use USB/BLE DFU or SWD for initial provisioning and local recovery.
For XIAO and ordinary external-QSPI details, see
[nRF52 repeater LoRa OTA with external QSPI](ota_nrf52_qspi.md).
+7 -3
View File
@@ -212,9 +212,13 @@ The final command must reproduce both the complete staged manifest ID and the
first eight bytes of its signed image hash. Before approval the application
again checks package/root/payload/image hashes, Ed25519 signature and trusted
allowlist, exact signed `XIAO_BL_...` ID, installed and incoming embedded
manifest/CRC/name/board identity, vector table, and ABI-3 QSPI+boot-update
continuity. A signed older bootloader that would remove remote update support
is refused.
manifest/CRC/name/board identity, vector table, ABI-3 QSPI+boot-update marker,
and the adjacent CRC-covered `BLM2`/`SOFT` continuity extension at the exact
final-image offset `0x9FB4`. The embedded
boot version must equal the signed outer package version, the SoftDevice
family/FWID/application base/layout ABI must match the running platform, and
a successor to installed BLM2 must be strictly newer. Low-byte-zero and
all-ones versions are invalid. Remote rollback is refused; use local DFU/SWD.
After the reply drains, GPREGRET `0x6B` and GPREGRET2 `0x51` enter the special
OTAFIX path. `APRV` carries the app's signature/allowlist and explicit operator
+44 -12
View File
@@ -271,14 +271,25 @@ A v3 bootloader package has a deliberately narrow, non-extensible profile:
- signed `hw_id` exactly `XIAO_BL_28860044`/`XIAO_BL_28860045` for deployed XIAO, or the zero-padded
32-byte `NRF_BL_<BOARD_ID>_<DEVICE_NAME>` for a generic target;
- a sane nRF52840 vector table, exactly one CRC-valid embedded manifest v1 with the exact board/name pair,
followed by the required CRC-covered `BLM2`/`SOFT` continuity extension (embedded boot version,
SoftDevice family/FWID, application base, and layout ABI), with that complete 76-byte envelope at the
canonical final-image offset `0x9FB4`,
and exactly one `MOTABLDR` marker advertising ABI >= 3, both application codecs (`FULL|INPLACE`, mask
`0x0005`), boot-update continuity, and the exact storage flags for the application layout (`0x09`
MeshTower V2 SD, `0x0E` XIAO QSPI, or `0x0A` shared internal staging).
The incoming embedded identity must exactly match the installed CRC-valid bootloader identity. Both scans
consider every aligned structurally valid candidate so magic bytes in a literal pool cannot shadow the real
manifest. A package must be signed by a key already in the device's trusted allowlist; unlike ordinary
manifest. Duplicate accounting counts each CRC-valid 44-byte base record before interpreting adjacent
continuity metadata, so a corrupt or half-present `BLM2` extension cannot hide a second identity; after
exactly one base record is selected, malformed claimed continuity fails closed. A package must be signed by
a key already in the device's trusted allowlist; unlike ordinary
application packages, there is no unsigned manual-install exception.
The signed outer `fw_version` must equal the embedded boot version. Qualified internal/QSPI targets may
bootstrap a CRC-valid legacy-v1 installed bootloader once; MeshTower SD instead requires local BLM2
provisioning because it has no safe legacy media handoff. After bootstrap every remote successor must be strictly newer and match the live
SoftDevice/application layout. Low-byte zero and all-ones boot versions are invalid. Remote rollback has no
override and must use local DFU/SWD.
---
@@ -360,7 +371,13 @@ There is no separate availability structure. **Block `i` is present <=> `leaves[
the staged container after a reboot - re-parse the stored manifest, recompute geometry, count present
blocks, continue fetching the holes (or jump straight to COMPLETE). The checkpoint cadence (persist progress
every N committed blocks) is runtime-tunable (`ota config checkpoint <N>`, 0 = only finalized containers
resume). Stores keep `leaves[]` in RAM until flush and never auto-GC, preserving resumable progress.
resume). Boot-time adoption is an automatic fetch decision: current `autofetch` must be enabled, the stored
target must equal the node target, policy `signed` requires the signed bit, and an enabled running-version
floor requires a strictly newer manifest. An explicit MID pull may deliberately resume an older or unsigned
package and keeps target `0` as a MID-only wildcard. Stores keep `leaves[]` in RAM until flush and never
auto-GC, preserving resumable progress. The debug/operator equivalent is `ota dev resume <MID8>`; after a
reboot the MID is mandatory, while a no-argument form may only reuse a still-active session MID. It never
uses the `nullptr` automatic-adoption path, so a malformed MID or no active MID fails closed.
**Flash-store note (RX-safe writes):** a flash page-erase halts the CPU (~85 ms on nRF52) and starves LoRa
RX, so the flash stores (`OtaStoreFlashNrf52`/`OtaStoreFlashEsp32`) **coalesce writes to the erase unit**
@@ -494,6 +511,11 @@ fetcher server (any node that has the mid)
when all blocks present: verify full merkle_root + image_hash -> COMPLETE
```
Before allocating or writing the selected store, the receiver parses the reassembled manifest and requires
its `merkle_root` to equal the requested/wire `manifest_id` and its `target_id` to equal the catalog or
explicit-pull target that opened the receive slot. The wire envelope and HAVE row are advisory; they cannot
label and stage a different manifest.
### 8.4 Message bodies (transfer)
All offsets after the 1-byte type. Encoders/decoders in `OtaProtocol.cpp`; constants in `OtaManager.h`.
@@ -630,8 +652,13 @@ transmission per hop.
independent of signature.
- **Signing & allowlist:** a node keeps a runtime allowlist of trusted Ed25519 signer pubkeys (none embedded
in firmware; `ota key add/list/rm`). A `.mota` is eligible for **auto-install** only if signed by an
allowlisted key, the signature verifies, and `image_hash` matches. Manual install permits unsigned packages,
allowlisted key, the signature verifies, `image_hash` matches, and its nonzero signed `fw_version` is
strictly greater than the running hash-valid EndF version. Both catalog admission and final automatic
apply enforce the version floor, so a lying HAVE row cannot bypass it. Manual `ota install` is the explicit
equal-version/rollback override and generally permits unsigned packages,
but a package that claims to be signed must have a valid signature from an allowlisted key or it is rejected.
The removable-SD target is stricter: every application install needs a valid allowlisted signature because
the app mints an authenticated one-reset media authorization for OTAFIX.
**Transfer needs no trust** - blocks are content-addressed against the manifest's merkle root.
- **Policies (persisted):** `autofetch` in {off, any, signed} (default off) gates automatic block fetching of
own-target adverts; `autoinstall` in {off, trusted} (default off) gates auto-apply of a COMPLETE signed +
@@ -783,7 +810,7 @@ ota qspi | storage QSPI nRF52 only: JEDEC/SR1/stage/latched stor
ota folder | fold [on|off] attach/detach an external .mota folder (host daemon) ; bare = list
ota config | cfg | set [autofetch|autoinstall|checkpoint] ... show/set persisted policy
ota key | keys [add|rm <hex>] trusted signer allowlist ; bare = list
ota dev ... bring-up helpers (stage/recv/serve/verify)
ota dev ... bring-up helpers (stage/recv/serve/resume <MID8>/verify)
```
---
@@ -840,22 +867,27 @@ ota dev ... bring-up helpers (stage/recv/serve/verify)
Internal-bootloader-self-update builds are a stricter exception: because their ordinary linker may extend
through `0xED000`, an absent/corrupt live `EndF` disables every internal staging pull before erase instead
of trusting the legacy 608 KiB estimate.
- **MeshTower V2 SD nRF52:** the application stores a contiguous `/meshcore-ota.mota` on microSD and
publishes its raw sector range in a checksummed handoff record outside the MBR partition. The matching
bootloader reads the card without mounting FAT, supports either a full image or an in-place delta,
- **MeshTower V2 SD nRF52:** the application stores a contiguous `/meshcore-ota.mota` on microSD. After
authenticating one exact signed manifest and verifying the leaves/payload/image, it hashes the exact full
container with only `APRV` normalized to zero and publishes a 72-byte reset-retained `MOTASDA2` record.
That record binds app-vs-boot purpose, format, raw sector range, total/card geometry, and normalized digest;
OTAFIX consumes and clears it before reading the card. There is no normal sector-1 handoff or additional
OTA-specific partition-layout requirement beyond what the bundled SdFat can mount. The matching
bootloader reads the authorized sectors without mounting FAT, supports either a full image or an in-place delta,
verifies the staged/full result hash, and never writes through `0xED000` where InternalFS begins. The
exact SD repeater also accepts a manually selected, signed v3 bootloader package when installed and
candidate markers are exactly `0x09` (`SD|BOOT_UPDATE`). MeshCore streams the same strict identity,
CRC, vector, signature, MID/hash-confirmation, and complete-image checks from the SD file. GPREGRET
`0x6B` plus GPREGRET2 `0x53` selects this privileged path. Both MeshCore and OTAFIX require a hash-valid
live `EndF` ending by `0xE0000`; when a nonzero boot-settings bank CRC is active, its recorded size must
also cover that complete live image and stop by `0xE0000`. MeshCore authenticates one exact manifest,
verifies the streamed SD copy is byte-identical, writes and syncs `APRV`, then writes a readback-checked
`MOTASDBL` token at `0xE0000` containing the exact total and signed `image_hash` before publishing the
raw-sector handoff. OTAFIX binds the parsed manifest, streamed payload, and final scratch image to that
also cover that complete live image and stop by `0xE0000`. For fmt3 MeshCore additionally writes a readback-checked
`MOTASDBL` token at `0xE0000` containing the exact total and signed `image_hash`. OTAFIX binds the parsed manifest,
streamed payload, and final scratch image to that
token, so a removable-media change can only fail closed. OTAFIX then uses `0xE0000..0xEA000` as temporary scratch; the normal
application linker remains at `0xED000` and ordinary application updates do not inherit this scratch
headroom restriction.
headroom restriction. Both fmt2 application apply and fmt3 bootloader apply require installed BLM2
continuity matching the live S140 FWID/application layout. Preview.12 must be upgraded locally over
USB/BLE DFU or SWD. MeshCore never writes a raw sector-1 handoff.
- **Matched external-QSPI nRF52 repeaters:** the application reserves the board's dedicated QSPI NOR as a
raw store beginning at offset zero. It obtains a 1-16 MiB capacity from JEDEC, checkpoints payload before
leaf metadata, and verifies each erased/programmed page. GPREGRET2 `0x51` selects QSPI only when the
+36 -14
View File
@@ -211,8 +211,11 @@ ota install
The node verifies the firmware one last time, and if everything checks out it installs it and **reboots
into the new version**. If the check fails, it tells you why and does **not** install. Unsigned images
install only through this explicit command. A signed image whose signer is not in the device allowlist is
rejected; trusted signed images can auto-install only when that policy is enabled.
normally install only through this explicit command. The MeshTower V2 SD target is stricter and requires an
allowlisted signature even for a manual application install, because it authorizes removable-media bytes for
the bootloader. A signed image whose signer is not in the device allowlist is rejected; trusted signed images
can auto-install only when that policy is enabled and the signed version is strictly newer than the running
hash-valid EndF version. Manual `ota install` remains the deliberate equal-version/rollback override.
After it reboots, run `ota status` to confirm the new version.
@@ -246,10 +249,13 @@ Copy both confirmation values exactly from the second `ota bootloader` reply.
Ordinary `ota install` deliberately refuses this package. The privileged
command requires an exact 40 KiB candidate payload in the fixed 41,330-byte
container, a valid exact embedded identity/CRC and vector table, continued
boot-update support, and a valid signature from a key already in `ota key`'s
trusted allowlist. It preserves the running application while OTAFIX replaces
itself; `blup:C8` in post-reboot `ota status` means success. Any node lacking
this command or those capabilities must update its bootloader locally instead.
boot-update support, required `BLM2`/`SOFT` continuity metadata at canonical
raw-image offset `0x9FB4`, a boot version
that exactly matches the package and is newer than installed BLM2, and a valid
signature from a key already in `ota key`'s trusted allowlist. It preserves the
running application while OTAFIX replaces itself; `blup:C8` in post-reboot
`ota status` means success. Remote rollback is refused. Any node lacking this
command or those capabilities must update its bootloader locally instead.
On an internal-flash target, the package shares the ordinary store below
`0xED000` and bottom-aligns at `0xE2000`; there is no separate reserved scratch
@@ -260,9 +266,14 @@ On the MeshTower V2 SD target, the application linker remains at `0xED000`, but
bootloader replacement needs temporary scratch beginning at `0xE0000`. A
hash-valid live `EndF` must therefore prove the complete current image ends by
`0xE0000`. A CRC-bound boot-settings bank must cover that complete image while
also ending by `0xE0000`. MeshCore binds approval to the exact authenticated
signed image hash in an internal token before handing the removable SD card to
OTAFIX, so a later card change fails instead of authorizing different bytes.
also ending by `0xE0000`. MeshCore binds both application and bootloader SD
approval to purpose, exact raw geometry, and a normalized SHA-256 in a
reset-retained `MOTASDA2` record. Boot updates also bind the exact authenticated
signed image hash in the E0000 token. OTAFIX consumes the retained record before
media access, so a later card change or power cycle fails instead of authorizing
different bytes. MeshCore never claims or writes raw sector 1. Both application
and bootloader OTA wait until a matching BLM2 bootloader has been provisioned
locally; preview.12 requires USB/BLE DFU or SWD first.
Larger applications can continue to use normal application mOTA;
only bootloader self-update is refused.
See [the nRF52 bootloader-update guide](ota_nrf52_bootloader_update.md) for the
@@ -309,7 +320,7 @@ ota config autofetch any # auto-DOWNLOAD any compatible update for this n
ota config autofetch signed # auto-download only signed updates
ota config autofetch off # back to manual (default)
ota config autoinstall trusted # auto-INSTALL a downloaded update IF it's signed by a key you trust
ota config autoinstall trusted # auto-INSTALL only a trusted signed version newer than the running EndF
ota config autoinstall off # never auto-install (default)
ota config advert 1440 # re-advertise every N minutes while temp radio is running
@@ -321,8 +332,18 @@ ota config hops 0 # only exchange OTA with directly-connected node
ota config # show the current settings
```
These policies also govern automatic adoption of an interrupted staged download after reboot. `off` leaves
it untouched, `signed` requires the stored manifest's signed flag, and automatic resume requires the stored
target to match this node and its version to be newer than the running valid EndF. Reissuing an explicit
`ota pull <MID8>` remains the deliberate override for an older or unsigned partial.
For bring-up/debugging, `ota dev resume <MID8>` performs the same explicit MID-bound re-adoption without
starting a new network fetch. After reboot it requires the MID; bare `ota dev resume` is accepted only while
an active/requested session MID still exists, and malformed or missing identifiers are rejected.
Recommended for most people: leave both **off** and update by hand. Use `autoinstall trusted` only once
you've added the signer's key (next section) and you trust them to push updates unattended.
you've added the signer's key (next section) and you trust them to push updates unattended. Automatic
admission and final apply both reject zero, equal, or older signed versions; a dishonest catalog version
cannot bypass the manifest check. Use manual `ota pull` plus `ota install` for an intentional rollback.
The MeshTower V2 SD OTA target has a separate, default-on **archive** policy. It saves all mOTAs it sees
to the SD card so the repeater can seed them later; this does not install them and does not change the
@@ -345,9 +366,10 @@ ota key list # show trusted signers
ota key rm <public-key-hex> # stop trusting one
```
Only updates signed by a trusted key are eligible for auto-install. Manual `ota install` permits an unsigned
package after all integrity, hardware, base, and bootloader checks pass. A signed package whose signer is not
in the device allowlist is rejected rather than silently treated as unsigned.
Only strictly newer updates signed by a trusted key are eligible for auto-install. Manual `ota install`
permits an unsigned package after all integrity, hardware, base, and bootloader checks pass, except on the
MeshTower V2 removable-SD path where all application installs must be signed and allowlisted. A signed
package whose signer is not in the device allowlist is rejected rather than silently treated as unsigned.
---