# MeshTower V2 microSD LoRa OTA `Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors` is the one canonical MeshTower V2 repeater target. Its SD OTA target ID `0A9DBBF0`, hardware ID `Heltec_tower_v2`, application layout, and artifact names remain unchanged. The required Full and Reduced sensor choices use that same target. Existing SD users need no configuration change. The build aliases `Heltec_tower_v2_repeater` and `Heltec_tower_v2_repeater_lora_ota_no_external_sensors` resolve to this primary target. An installed internal-only image has a different OTA identity and bootloader/layout contract: migrate it once with the matching combined OTAFIX profile and application over local USB/BLE DFU or SWD. An alias does not make that migration a same-target LoRa update. ## Automatic storage selection The onboard microSD socket remains primary. A mountable card accepts full application images, in-place application deltas, and explicitly selected signed v3 bootloader packages. After verification, the SD-aware OTAFIX bootloader reads the staged file and programs the application or bootloader. With a missing or unmountable card, the same application can select internal flash for signed application in-place deltas only. The signer must be trusted by the node, as on the SD application path. This fallback requires the published combined MeshTower SD/internal profile in [OTAFIX 2.4.11](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.11): the privileged storage profile must remain exactly `09` (`SD|BOOT_UPDATE`), with a separate positive `MOTASTOR` optional-application storage record of `02` (`STAGE_CEILING`). A missing record or an internal-only bootloader does not authorize fallback. Full images, bootloader packages, SD archiving, and automatic own-image offering remain unavailable on internal storage. Selection is deferred until OTA use so card probing does not delay USB setup. The selected backend stays pinned through the transfer, including a paused or failed transfer. Removing a card produces a storage failure; it does not move the partial download into internal flash. Use `ota cancel` before selecting storage again after changing the card. The fallback uses internal flash only; it does not reserve or use the 64 KiB `APPHYBRID` retained-RAM arena. 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 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 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 When SD is selected, 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 \ --sign ./trusted-signer.key --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 \ --sign ./trusted-signer.key \ --out-dir ./motas motatool verify ./motas/*.mota ``` The internal fallback has a smaller flash staging gap and in-place workspace. A delta generated for the larger SD workspace can be rejected even though it updates the same application and target. Keep a usable card inserted for that package, or generate an exact-base delta that fits the fallback's available workspace and staging capacity. The firmware refuses an oversized package; it does not switch backends during its download. An SD download is resumable because the partial `.mota` stays on the card. Once it reaches `ready`, `ota install` performs the final verification, 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 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. Earlier internal-only MeshTower firmware retains its old identity until the deliberate local migration described above. ## Signed bootloader update Only the canonical SD target with SD selected exposes a usable privileged LoRa bootloader-update path. Internal application fallback does not stage bootloader packages. 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. 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 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 package can be downloaded or approved, MeshCore requires a hash-valid live `EndF` proving the complete running image ends by `0xE0000`; OTAFIX repeats that no-overlap check before its first erase. An application extending above that boundary can still receive normal FULL or delta application updates from SD, but its bootloader must be updated locally. MeshCore also checks the live boot settings before touching that scratch page. Erased settings and a valid-app record with CRC disabled are allowed. When a nonzero bank CRC is active, its recorded `bank_0_size` must cover the complete 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. 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: ```text ota ls ota pull flash # wait for ota status to report the bootloader download ready ota bootloader ota bootloader install ``` Copy the MID and first 16 image-hash hex digits from `ota bootloader`. Ordinary `ota install` rejects this package, and the bootloader command rejects an application package. Keep the SD card inserted through the reboot. A later `ota status` value of `blup:C8` reports a successful bootloader replacement. After reboot, `ota bootloader` displays the installed board identity, CRC and capabilities. Its `mid` and `hash` fields describe a **currently staged download**, not the installed bootloader, so `staged:none mid=- hash=-` is not an install failure. `blrc:00` means no retained apply result is available; it does not by itself prove either success or failure. Older MeshCore application firmware can report `get bootloader.ver` as `unknown` for OTAFIX 2.4.6 because this bootloader image omits the legacy `UF2 Bootloader` text. The updated getter also reads the CRC-validated BLM2 version. For the official signed **MeshTower V2 SD 2.4.6** `.mota`, the installed identity is `TOWER_V2_OTA`, CRC `5DACDB3D`, ABI `3`, and capabilities `09`. Compare the exact board/storage package when interpreting these values; the non-SD image differs. ## SD card CLI The SD-backed target provides these CLI commands: ```text set sdcard format [--force] set sdcard erase [--force] get sdcard get sdcard * get sdcard format get sdcard erase get sdcard free get sdcard ls get sdcard ls 2 get sdcard dir 3 ``` `format` creates a new FAT16, FAT32, or exFAT filesystem according to card size. `erase` first uses the card's raw media erase command and then formats it, so a successful erase finishes with a usable filesystem. Both operations destroy all data on the card and cancel a staged SD OTA download. If the internal fallback slot is occupied, card maintenance is refused until an explicit `ota cancel`; it does not abandon an internal download to format SD. The firmware records successful format and erase completion times in RAM. Repeating the same operation within five minutes is rejected unless `--force` is present. Format and erase have independent cooldowns. Because erase also formats the card, a successful erase updates both timestamps. The timestamps reset when the device reboots. The `get sdcard` age queries report how long ago each operation completed. `get sdcard free` reports used and free filesystem space in human-readable binary units. `get sdcard ls` and `get sdcard dir` recursively list files on the card, two files per page. A bare command shows page 1; append a positive page number to move through the remaining results. Each row includes the path and a compact file size. The header reports the selected page, total pages, and total files. ## Persistent OTA archive and seeder With SD selected, automatic OTA archiving is on by default. While the temporary OTA radio is active, the node requests full catalogs from seeders and saves every complete mOTA it discovers, including firmware for other hardware targets and codecs that this node cannot install. Archive downloads use the same per-block Merkle proof checks as an install download, but archived images are never selected for local installation. Completed containers are stored as `/mota/.mota`. An interrupted download remains `/mota/.part` and resumes when that mOTA is seen again. Completed files survive reboot, are enumerated on the first archive access or TempRadio window, and are advertised and served directly from SD. The SD target supports the protocol maximum served set: its own running firmware plus up to 254 archived mOTAs. Automatic capture preserves an 8 MiB free-space reserve for manual `/meshcore-ota.mota` installation staging. It stops starting new archive files when the next file would cross that reserve. Archive allocation first tries the fast contiguous path and then falls back to an ordinary fragmented FAT file; only the bootloader staging file requires contiguous sectors. ### Preload many mOTAs from a computer You can populate the archive much faster on a computer than over LoRa. Use only complete, verified `.mota` containers. Do not copy firmware `.bin`, `.hex`, `.zip`, or `.part` files into the archive. Install the standalone [`motatool`](https://github.com/vk496/motatool) first if it is not already available: ```bash git clone https://github.com/vk496/motatool.git cargo install --path ./motatool ``` The on-card filename is part of the archive index and has a strict format: ```text /mota/.mota ``` `` is the eight-hex-digit value printed by `motatool inspect`. It is also the mOTA's four-byte manifest ID. The extension must be lowercase, the file must be directly inside `/mota`, and descriptive release filenames are not indexed. For example, if inspection reports: ```text merkle_root : ABCD1234 ``` copy that container to: ```text /mota/abcd1234.mota ``` If two containers have the same Merkle root, they have the same protocol ID and cannot both be present. Keep only the intended one. The current SD seeder can index up to 254 archived files. A served file must use a logical block size of at most 1024 bytes and contain at most 2048 blocks; check `block_size` and `block_count` in `motatool inspect` when importing unusually large images. Files outside that serve geometry are not counted or advertised. If a malformed `/mota/.mota` conflicts with a newly discovered valid image, the repeater preserves the malformed file as `.bad` through `.bad9` and downloads a 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 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 that reports `FAIL`. 4. Run `motatool inspect FILE.mota`, read its `merkle_root`, and copy the file to `/mota/.mota` on the card. 5. Flush pending writes, safely eject the card, power the repeater off, insert the card, and boot `Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors`. On Linux or macOS, this Bash example verifies and imports every `.mota` from `./motas`. Replace the example mount path before running it: ```bash card_mount=/media/YOU/MESHCORE mkdir -p "$card_mount/mota" shopt -s nullglob for image in ./motas/*.mota; do motatool verify "$image" || exit 1 mid=$(motatool inspect "$image" | awk '$1 == "merkle_root" { print tolower($3) }') if [[ ! $mid =~ ^[0-9a-f]{8}$ ]]; then echo "Could not read the Merkle root from: $image" >&2 exit 1 fi destination="$card_mount/mota/$mid.mota" if [[ -e $destination ]]; then cmp -s "$image" "$destination" || { echo "Different containers have the same ID: $mid" >&2 exit 1 } else cp "$image" "$destination" fi done sync ``` On Windows, create `E:\mota`, inspect each source with `motatool inspect`, and rename it to the reported lowercase root in the same way. Safely eject the drive after all copies finish. After boot, scan the archive and confirm the card contents from the repeater console: ```text get sdcard ls get sdcard ls 2 ota cache ota folder ``` `ota cache` should report the imported count. `ota folder` reports the current served count; once OTA serving starts in TempRadio, that set also includes the repeater's running firmware. If the files appear in `get sdcard ls` but not in the served count, check their exact names, run `motatool verify` again, and inspect their block geometry. It is fine to run `ota cache off` for a curated, read-mostly archive: that disables capture of new mOTAs but continues serving every valid file already on the card. ### Serve the preloaded archive over TempRadio LoRa OTA traffic exists only during an active temporary-radio window. The SD repeater, each receiving node, and every intermediate repeater in the path need overlapping windows on the same temporary channel. Use a frequency permitted for the node's configured region. This North American example uses the recommended fast OTA settings and a 120-minute window: ```text tempradio 909.950,250,5,5,120 ``` Start the farthest receiving node first, then intermediate repeaters, and the SD source last so their windows overlap for as long as possible. Before or during the source window, `ota cache` makes the source scan and attach the SD archive. Entry into TempRadio automatically triggers an OTA advertisement burst; `ota announce` can send another advertisement immediately. On a receiving OTA-capable node, allow a few seconds for catalog exchange, then run: ```text ota ls ota ls 2 ota get flash ota status ``` Use `ota ls 2`, `ota ls 3`, and so on when the source advertises more than the two rows that fit in one remote CLI reply. Each row includes a stable eight-hex-digit manifest ID. Use that ID instead of a list number, because asynchronous catalog refreshes can reorder rows between the list and pull commands. A receiver retains the complete protocol catalog and verifies every transferred block. It still applies its normal target, hardware, codec, signature, and installation checks. The SD repeater may advertise images for many hardware families; it never installs those archive files merely because it serves them. When a temporary window expires or a node reboots, it returns to its saved radio settings and OTA transfer stops. The archive remains on the card. Start another set of overlapping `tempradio` windows to resume an interrupted download, or use synchronized `tempradioat` entries for a scheduled window. Archive capture is lower priority than operator work. An explicit `ota pull` to install storage or a host folder immediately takes the single receive slot; the archive partial is checkpointed and resumes later. Existing cached files can still answer peer requests while another archive file is downloading. Use these commands to inspect or control automatic capture: ```text ota cache ota cache on ota cache off ota config cache on ota config cache off ``` The on/off choice is saved on the SD card. Turning capture off stops new downloads but keeps serving files already cached. Formatting or erasing the card removes both the archive and its off marker, so a newly formatted card returns to the default-on setting. `ota config sdseed on|off` is also accepted as an alias.