Add MeshTower V2 SD-backed LoRa OTA

This commit is contained in:
mikecarper committed 2026-08-03 12:49:36 -07:00
1 parent 9b8c68d926
commit 4ed3307c6c
24 files changed
+833 -37

No files matched your search

+1
View File
@@ -8,6 +8,7 @@ Below are a few quick start guides.
- [CLI Commands](./cli_commands.md)
- [CLI Availability by Firmware Build](./cli_build_matrix.md)
- [Easy LoRa OTA: ESP32 full images and nRF52 deltas](./ota_easy.md)
- [MeshTower V2 microSD self-updates](./ota_meshtower_v2_sdcard.md)
- [GPS Tracking](./gps_tracking.md)
- [Companion Protocol](./companion_protocol.md)
- [Packet Format](./packet_format.md)
+6 -3
View File
@@ -7,9 +7,11 @@ LoRa. Choose the package type for the **destination** node:
| --- | --- | --- | --- |
| ESP32 | Full firmware | New non-merged application `.bin` | ESP32 A/B firmware slots |
| nRF52 | In-place delta | Exact running `firmware.hex` and new `firmware.hex` | Exact-board OTAFIX bootloader |
| MeshTower V2 SD target | Full firmware or in-place delta | New `firmware.hex`; a delta also needs the exact running `firmware.hex` | Matching SD-aware OTAFIX bootloader |
An nRF52 node cannot install an ESP32-style full-image container. It deliberately accepts only an in-place
delta built against its exact running firmware.
A normal nRF52 target cannot install a full-image container. It deliberately accepts only an in-place
delta built against its exact running firmware. The MeshTower V2 microSD target is the exception because
it stages the complete container off-chip; see [MeshTower V2 microSD LoRa OTA](ota_meshtower_v2_sdcard.md).
## Temporary OTA channel used in this guide
@@ -298,7 +300,8 @@ ota status
If it is the source or destination, install a supported `-ota-` build over WiFi or USB first. An intermediate
repeater does not need the OTA CLI and can relay opaquely while its matching `tempradio` window is active.
- **The update is marked `[other hw]`:** it is for a different board or firmware role. Do not install it.
- **An nRF52 node does not list a full update:** this is intentional. nRF52 accepts only an in-place delta.
- **An nRF52 node does not list a full update:** this is intentional for internal-flash targets. The
MeshTower V2 microSD target accepts full images with its matching SD-aware bootloader.
- **nRF52 reports no bootloader apply support:** install the exact-board in-place-delta OTAFIX bootloader
before trying LoRa OTA.
- **nRF52 reports a base mismatch:** the file passed to `--base` is not the exact application running on
+71
View File
@@ -0,0 +1,71 @@
# MeshTower V2 microSD LoRa OTA
The `Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors` target uses the MeshTower V2 onboard
microSD socket as persistent storage for its own LoRa OTA downloads. It accepts
both full `.mota` images and in-place delta `.mota` images. After verification,
the matching SD-aware OTAFIX bootloader reads the staged file from the card and
programs the nRF52840 application region.
The pin assignment follows the
[Heltec MeshTower V2 partial reference circuit](https://resource.heltec.cn/download/MeshTower-V2/schematic/MeshTower_V2_Partial_Reference_Circuit.pdf):
| Signal | nRF52840 pin | Arduino pin number |
|---|---:|---:|
| SD CS | P1.00 | 32 |
| SD MOSI | P1.01 | 33 |
| SD SCK | P0.06 | 6 |
| SD MISO | P0.26 | 26 |
The SD socket uses its own SPI peripheral, so card traffic does not change the
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.
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.
## Capacity and update types
The card removes the internal-flash staging limit. The `.mota` container may be
much larger than the old internal staging gap, and either a full image or an
in-place delta may be downloaded. The installed firmware itself must still fit
the nRF52840 application region below InternalFS (ending at `0xED000`); SD
storage does not increase the MCU's executable flash.
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 verify ./motas/*.mota
```
A delta uses the exact installed image as its base. The normal `0x98000`
workspace remains compatible. If either image is larger than that legacy
limit, build the patch with the SD target's larger workspace:
```bash
motatool build \
--base ./Heltec_tower_v2_sdcard-running.hex \
--fw ./Heltec_tower_v2_sdcard-new.hex \
--patch-type in-place \
--inplace-memory 0xC7000 \
--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.
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.
+10 -5
View File
@@ -254,7 +254,7 @@ cover `approval` or `leaves[]`:
| `codec_id` | Meaning | Used by |
|---|---|---|
| 0 | full / raw | PAYLOAD = reconstructed image (`BODY||EndF`). ESP32 A/B only. |
| 0 | full / raw | PAYLOAD = reconstructed image (`BODY||EndF`). ESP32 A/B or the SD-backed MeshTower V2 target. |
| 1 | detools **sequential** | random read of base + sequential write of result -> ESP32 A->B inactive slot. |
| 2 | detools **in-place** | bounded scratch; rewrites the app region in place -> nRF52 single-slot. |
@@ -263,10 +263,11 @@ delta only if `base_hash` matches its own `EndF.body_hash`. After applying, the
(sha2-256:32) to `image_hash` before it is booted - the hard security gate.
**A fetcher only requests firmware it can apply.** Each node declares the codec(s) it can apply
(`set_apply_codec`/`set_apply_codec2`): ESP32 accepts `full` + `sequential` (+ `in-place`), while nRF52
accepts only `in-place` because its single slot cannot stage a full application image. A `.mota` with an
unsupported codec is rejected at discovery time, before any blocks are requested. A manual pull to an
external folder may accept other codecs because that path captures bytes and never installs them.
(`set_apply_codec`/`set_apply_codec2`): ESP32 accepts `full` + `sequential` (+ `in-place`). Normal nRF52
targets accept only `in-place` because internal flash cannot stage a full application image. The
MeshTower V2 SD target accepts `full` + `in-place` because the card holds the container. A `.mota` with
an unsupported codec is rejected at discovery time, before any blocks are requested. A manual pull to
an external folder may accept other codecs because that path captures bytes and never installs them.
Compression is internal to the detools patch and must be supported by the applier. Patches are produced by
**detools 0.53.0** (`tools/mota` -> `detools.create_patch`) and decoded on-device by detools' embeddable C
@@ -670,6 +671,10 @@ 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`.
- **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,
verifies the staged/full result hash, and never writes through `0xED000` where InternalFS begins.
The signature proves author authenticity; `approval` proves local owner consent - both required to apply.