Add guarded nRF52 OTA rescue and SF5 test mode

This commit is contained in:
mikecarper committed 2026-08-13 09:31:26 -07:00
1 parent 710a6e02c5
commit 4a3d86ef98
14 files changed
+225 -47

No files matched your search

+2
View File
@@ -168,6 +168,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
| LoRa OTA | [`ota ls`; `ota neighbors`; `ota nbrs`; `ota updates`; `ota n`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes |
| LoRa OTA | [`ota get`; `ota pull`; `ota download`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build; nRF52 installs in-place deltas | No | No | Yes |
| LoRa OTA | [`ota install`; `ota apply`; `ota applydelta`](ota_protocol.md#11-cli-surface-otaclicpp) | Compatible bootloader and completed update | No | No | Yes |
| LoRa OTA | [`ota rescue install <base_hash16>`](ota_protocol.md#12-apply--bootloader-contract) | Internal-flash nRF52 LoRa OTA build with failed app-side EndF validation | No | No | Feature |
| LoRa OTA | [`ota cancel`; `ota drop`; `ota stop`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes |
| LoRa OTA | [`ota announce`; `ota adv`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes |
| LoRa OTA | [`ota self`; `ota id`](ota_protocol.md#11-cli-surface-otaclicpp) | Firmware with EndF trailer | No | No | Yes |
@@ -324,6 +325,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
| LoRa OTA | [`ota ls`; `ota neighbors`; `ota nbrs`; `ota updates`; `ota n`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes | No | No | Yes | Yes |
| LoRa OTA | [`ota get`; `ota pull`; `ota download`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes | No | No | Yes | Yes |
| LoRa OTA | [`ota install`; `ota apply`; `ota applydelta`](ota_protocol.md#11-cli-surface-otaclicpp) | Compatible completed update | No | No | Yes | No | No | Yes | Yes |
| LoRa OTA | [`ota rescue install <base_hash16>`](ota_protocol.md#12-apply--bootloader-contract) | Internal-flash nRF52 LoRa OTA build with failed app-side EndF validation | No | No | Feature | No | No | No | No |
| LoRa OTA | [`ota cancel`; `ota drop`; `ota stop`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes | No | No | Yes | Yes |
| LoRa OTA | [`ota announce`; `ota adv`](ota_protocol.md#11-cli-surface-otaclicpp) | LoRa OTA build | No | No | Yes | No | No | Yes | Yes |
| LoRa OTA | [`ota self`; `ota id`](ota_protocol.md#11-cli-surface-otaclicpp) | Firmware with EndF trailer | No | No | Yes | No | No | Yes | Yes |
+2 -2
View File
@@ -237,7 +237,7 @@ nc 192.168.1.50 5002
```
```text
tempradio 909.950,250,7,5,120
tempradio 909.950,250,5,5,120
ota status
```
@@ -260,7 +260,7 @@ picocom -b 115200 \
```
```text
tempradio 909.950,250,7,5,120
tempradio 909.950,250,5,5,120
+++MESHCORE-TERM-STOP
```
+5 -7
View File
@@ -179,15 +179,13 @@ and codec mask against the selected package.
The default TempRadio tuple is:
```text
909.950,250,7,5,120
909.950,250,5,5,120
```
The 250 kHz bandwidth, SF7, and CR5 combination is supported by every current
sub-GHz radio family used in USB Companion builds, including older SX127x
controllers (which do not support SF5). The frequency is only a North American
example: choose a legal frequency supported by every participating radio and
appropriate to your location. Pass the complete replacement tuple with
`--temp-radio`.
The test default is 250 kHz bandwidth, SF5, and CR5. The frequency is only a
North American example: choose a legal frequency supported by every
participating radio and appropriate to your location. Older radios that do not
support SF5 require a complete replacement tuple passed with `--temp-radio`.
## 4. Run an ESP32 update
+10
View File
@@ -679,6 +679,7 @@ ota status | st (or bare `ota`) plain-language: running fw, the one fetch ses
ota ls | neighbors | nbrs | updates | n [page] paged updates (queries sources; rows arrive async via OTA_HAVE)
ota get | pull | download <#|mid8> fetch a chosen mOTA (manual; works regardless of autofetch)
ota install | apply | applydelta verify + approve + (ESP32) apply / (nRF52) reboot-to-bootloader
ota rescue install <base_hash16> internal-flash nRF52 only: recover from failed app-side EndF validation
ota cancel | drop | stop drop the current fetch session (frees the slot)
ota announce | adv serve self + send a beacon now
ota self | id print this firmware's EndF (body/image size, base_hash)
@@ -702,6 +703,15 @@ ota dev ... bring-up helpers (stage/recv/serve/verify)
2. re-checks `TRAILER`, `image_hash`, `approval == "APRV"`, and that the delta's `base_hash` equals the
running firmware's `EndF.body_hash` (recomputed by scanning for `EndF` - never trust `bank_0_size`),
3. applies the in-place codec over the app region and boots only if the result hashes to `image_hash`.
- **nRF52 EndF rescue:** `ota rescue install <base_hash16>` is a pre-provisioned recovery path for an
internal-flash nRF52 application that still runs but cannot validate its own EndF identity. It refuses
when normal EndF validation succeeds, requires the operator hash to exactly equal the staged delta's
`base_hash`, requires the package `target_id` to match and its `hw_id` to pass the normal hardware gate,
and retains the normal payload and signature/allowlist gates. Approval only delegates the base decision:
OTAFIX independently
locates the physical EndF, hashes the running app, and compares that value with the package before its
first app write. A physically absent/corrupt EndF or wrong base therefore returns to the unchanged app;
it still requires USB recovery if that app does not already contain this command.
- **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,
+13
View File
@@ -178,6 +178,18 @@ After it reboots, run `ota status` to confirm the new version.
### 5. If something goes wrong
- A download that stalls or gets interrupted just **resumes** later, or you can `ota cancel` and try again.
- An internal-flash **nRF52** that still runs but reports `no EndF` can use the pre-provisioned rescue path
if its physical EndF is intact and only app-side validation is failing. Fetch the exact in-place delta,
obtain its 16-hex-digit `base_hash` from the package metadata, then run:
```text
ota rescue install <base_hash16>
```
This is not a force option. It refuses a normally valid EndF, a different package hash, hardware or
target mismatch, corrupt payload, and invalid/untrusted signatures. The bootloader independently hashes
the running app and rejects a wrong base before writing the app. If the physical EndF is absent or this
command was not already in the running firmware, recover over USB.
- If an **install** fails, the node won't boot a broken image - it lands in **recovery mode**:
- **nRF52:** it appears as a USB drive; drag a known-good firmware `.uf2` for that exact board onto it
to recover.
@@ -301,6 +313,7 @@ that only contains what changed). You get them by:
| Download update #1 for installation | `ota get 1 flash` |
| Cancel a download | `ota cancel` |
| Install a finished download | `ota install` |
| Recover app-side `no EndF` on internal nRF52 | `ota rescue install <base_hash16>` |
| Turn on auto-download | `ota config autofetch any` |
| Turn on auto-install (trusted only) | `ota config autoinstall trusted` |
| Trust a signer | `ota key add <hex>` |
+1 -1
View File
@@ -155,7 +155,7 @@ The tested Heltec key is
Change the IP address for a different deployment.
The source, controller, destination, and every intermediate relay must support
the temporary tuple `909.950,250,7,5`. Confirm that this frequency and
the temporary tuple `909.950,250,5,5`. Confirm that this frequency and
bandwidth are legal at the deployment location. All nodes return to their
ordinary radio after each step.