Refresh LoRa OTA guides for 1.18.0.1
This commit is contained in:
mikecarper committed
1 parent
86463059c1
commit
b9c0ede82a
18 files changed
+303
-178
No files matched your search
@@ -265,8 +265,9 @@ passed the combined flash/RAM qualification.
|
||||
ESP32 deliberately uses one TTY: Binary Companion and plaintext USB logging
|
||||
are mutually exclusive there. nRF52 retains its optional second CDC port.
|
||||
|
||||
The [OTAFIX 2.4.11 release](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.11)
|
||||
is the current bootloader reference, not an all-board qualification claim.
|
||||
The [OTAFIX 2.4.12 release](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12)
|
||||
is the bootloader reference for [firmware 1.18.0.1](releases/1.18.0.1.md),
|
||||
not an all-board qualification claim.
|
||||
Consult its exact-board manifest and unavailable-profile reasons. Internal
|
||||
application storage accepts exact-base in-place deltas that fit the workspace;
|
||||
full application packages need the matching external NOR or microSD profile.
|
||||
|
||||
@@ -6575,7 +6575,7 @@ The reader preserves a complete Adafruit/UF2 version string, including OTAFIX,
|
||||
preview, and vendor/build suffixes. Manufacturer two-component versions such as
|
||||
Seeed's `1.00` are preserved without inventing a patch number. If that string is
|
||||
absent or ambiguous, it uses the existing whole-image CRC and unique BLMF/BLM2
|
||||
validation to read the embedded OTAFIX version (for example, `> OTAFIX2.4.6`). Some current release
|
||||
validation to read the embedded OTAFIX version (for example, `> OTAFIX2.4.6`). Some older release
|
||||
images, including MeshTower V2 SD 2.4.6, omit the UF2 text entirely. As a last
|
||||
OTAFIX-specific fallback, it accepts one unambiguous standalone version token
|
||||
such as `v0.11.0-OTAFIX2.4.9` from only the first 40 KiB of the identified
|
||||
|
||||
@@ -4,6 +4,11 @@
|
||||
|
||||
# Full Companion
|
||||
|
||||
For **[1.18.0.1 USA Cascade](releases/1.18.0.1.md)**, download the exact
|
||||
Full Companion from the [firmware picker](firmware_picker.md). To use it as
|
||||
a source for updating repeaters, room servers or sensors, follow the
|
||||
[LoRa OTA automation guide](lora_ota_automation.md).
|
||||
|
||||
Configure message alerts with the [Companion notification builder](notifications.md).
|
||||
It generates CLI rules for contacts, rooms and channels, previews patterns, and
|
||||
can apply/test them over USB. Trusted contacts and rooms can send `!notify`
|
||||
@@ -303,10 +308,12 @@ Build by using one exact listed name:
|
||||
|
||||
```bash
|
||||
bash build.sh build-firmware heltec_v4_r8_companion_radio_full \
|
||||
--firmware-version v1.17.0
|
||||
--firmware-version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
|
||||
bash build.sh build-firmware RAK_4631_companion_radio_full \
|
||||
--firmware-version v1.17.0
|
||||
--firmware-version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
```
|
||||
|
||||
To build every canonical full Companion target, select the corresponding
|
||||
@@ -314,7 +321,8 @@ interactive menu item or run:
|
||||
|
||||
```bash
|
||||
bash build.sh build-full-companion-firmwares \
|
||||
--firmware-version v1.17.0
|
||||
--firmware-version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
```
|
||||
|
||||
Canonical Companion bulk builds also omit legacy `_ps` and `_femoff` aliases.
|
||||
|
||||
@@ -4,6 +4,12 @@
|
||||
|
||||
# ESP32 legacy-partition migration over USB, Wi-Fi or LoRa
|
||||
|
||||
For **[1.18.0.1 USA Cascade](releases/1.18.0.1.md)**, select the exact board
|
||||
and role in the [firmware picker](firmware_picker.md). Published migration
|
||||
packages are in the [update utilities release](https://github.com/mikecarper/MeshCore/releases/tag/utility-v1.18.0.1-halo-keymind-cascade-dev-03214a16).
|
||||
Follow the selected package's README; a normal app update does not need a
|
||||
partition migration when the installed layout already matches.
|
||||
|
||||
The partition-migration bridge lets a supported ESP32 node move from a small
|
||||
dual-OTA layout to a verified larger dual-OTA layout without cable flashing or
|
||||
a full-chip erase. It fits a legacy 1.25 MiB slot. The Wi-Fi version exposes an
|
||||
@@ -105,7 +111,7 @@ larger 4 MiB table. Ordinary repeater, room, Companion and KISS recipes retain
|
||||
sh scripts/build_esp32_partition_migration.sh \
|
||||
--board waveshare-s3-lr1121-observer-repeater \
|
||||
--board waveshare-s3-lr1121-observer-room-server \
|
||||
--version v1.18.0-test --radio-preset usa-cascadia --profile cascade --dry-run
|
||||
--version v1.18.0.1-halo-keymind-cascade-dev --radio-preset usa-cascade-fixed --profile cascade --dry-run
|
||||
```
|
||||
|
||||
Remove `--dry-run` only to build and verify the packages from a clean commit;
|
||||
@@ -152,14 +158,14 @@ non-interactively:
|
||||
|
||||
```bash
|
||||
sh scripts/build_esp32_partition_migration.sh --board heltec-v4 \
|
||||
--version v1.17.1.7-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascadia --profile cascade
|
||||
--version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
sh scripts/build_esp32_partition_migration.sh --all \
|
||||
--version v1.17.1.7-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascadia --profile cascade
|
||||
--version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
sh scripts/build_esp32_partition_migration.sh --role sensor \
|
||||
--version v1.17.1.7-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascadia --profile cascade
|
||||
--version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
```
|
||||
|
||||
`--all` creates one verified ZIP per listed board/role pair and a release
|
||||
@@ -173,8 +179,8 @@ The underlying Python recipe remains available:
|
||||
|
||||
```bash
|
||||
python3 -B scripts/build_esp32_partition_migration.py \
|
||||
--version v1.17.1.7-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascadia --profile cascade
|
||||
--version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
```
|
||||
|
||||
The default builds all configured board/role recipes. Add `--board heltec-v4`
|
||||
|
||||
+8
-6
@@ -4,12 +4,14 @@
|
||||
|
||||
# Frequently Asked Questions
|
||||
|
||||
For this fork's **1.17.1.5 USA Cascade** release, start with
|
||||
[feature switches by role](role_feature_switches.md) and the
|
||||
[USB web console](https://flasher.meshcore.io/console). For nRF52 OTAFIX use
|
||||
the exact board/storage build from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6);
|
||||
older bootloader links below provide upstream/background context.
|
||||
For this fork's **[1.18.0.1 USA Cascade release](releases/1.18.0.1.md)**, use
|
||||
the [firmware picker](firmware_picker.md) and [update guide](ota_user_guide.md).
|
||||
See [feature switches by role](role_feature_switches.md) for runtime controls
|
||||
and the [USB web console](https://flasher.meshcore.io/console) for CLI access.
|
||||
For nRF52 LoRa OTA, choose the exact board/storage build of
|
||||
[OTAFIX 2.4.12](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12)
|
||||
and follow the [bootloader guide](ota_nrf52_bootloader_update.md). Older
|
||||
bootloader links below provide upstream/background context.
|
||||
|
||||
A list of frequently-asked questions and answers for MeshCore
|
||||
|
||||
|
||||
@@ -220,9 +220,9 @@ Bluetooth DFU updates the Companion; the separate Bluetooth MOTA source
|
||||
service feeds packages to other mesh nodes.
|
||||
|
||||
For OTAFIX installations, use the exact board/storage profile from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6).
|
||||
It includes the Bluetooth reconnect fix from 2.4.5. Its release notes cover
|
||||
upgrades from older bootloaders, including the special UF2-drive precautions
|
||||
for version 2.4.3. The new 64 KiB retained-RAM staging feature applies to
|
||||
qualified internal-flash nRF52840 receivers; Full Companions continue to
|
||||
serve host-supplied packages without needing that receiver storage layout.
|
||||
[OTAFIX 2.4.12](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12).
|
||||
For **1.18.0.1**, follow the [LoRa OTA guide](ota_user_guide.md) and
|
||||
[bootloader instructions](ota_nrf52_bootloader_update.md). Retained-RAM
|
||||
staging applies to qualified internal-flash nRF52840 receivers; Full
|
||||
Companions continue to serve host-supplied packages without needing that
|
||||
receiver storage layout.
|
||||
@@ -4,6 +4,11 @@
|
||||
|
||||
# Heltec V4 legacy-partition migration over Wi-Fi
|
||||
|
||||
For **[1.18.0.1 USA Cascade](releases/1.18.0.1.md)**, choose the exact V4
|
||||
board and role in the [firmware picker](firmware_picker.md). Use its matching
|
||||
migration ZIP from the [update utilities release](https://github.com/mikecarper/MeshCore/releases/tag/utility-v1.18.0.1-halo-keymind-cascade-dev-03214a16)
|
||||
when the installed partition layout needs expansion.
|
||||
|
||||
Heltec V4/V4.3 OLED repeaters with their normal 16 MiB flash use the shared
|
||||
[ESP32 partition migration](esp32_wifi_partition_migration.md) bridge.
|
||||
It changes Arduino's old `default.csv` layout, with two 1.25 MiB OTA slots,
|
||||
@@ -13,8 +18,8 @@ Build the complete V4 package with the repeatable ESP32 recipe in WSL/Linux:
|
||||
|
||||
```bash
|
||||
python3 -B scripts/build_esp32_partition_migration.py \
|
||||
--board heltec-v4 --version v1.17.1.7-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascadia --profile cascade
|
||||
--board heltec-v4 --version v1.18.0.1-halo-keymind-cascade-dev \
|
||||
--radio-preset usa-cascade-fixed --profile cascade
|
||||
```
|
||||
|
||||
The ZIP contains the Wi-Fi bridge, LoRa bridge, and exact-target Full image.
|
||||
|
||||
+39
-22
@@ -4,14 +4,17 @@
|
||||
|
||||
# Scripted LoRa OTA from start to finish
|
||||
|
||||
For **1.17.1.5**, use the exact board/storage profile from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6)
|
||||
for nRF52 OTAFIX installations. New internal-flash hybrid receivers require
|
||||
its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own
|
||||
matching bootloader profiles. Earlier preview versions mentioned below
|
||||
describe compatibility/migration history, not the current recommended download.
|
||||
Full Companion is a MOTA source and normally updates itself over USB.
|
||||
|
||||
For **[1.18.0.1 USA Cascade](releases/1.18.0.1.md)**, download the exact board,
|
||||
role and storage profile from the [firmware picker](firmware_picker.md).
|
||||
For a new nRF52 installation, use the matching
|
||||
[OTAFIX 2.4.12](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12)
|
||||
bootloader. Supported Repeater and Room Server downloads also offer
|
||||
**with bootloader** application images; these check once after 70 seconds and
|
||||
can update a recognized compatible older bootloader. Read the
|
||||
[embedded bootloader guide](nrf52_embedded_bootloader.md) before choosing one.
|
||||
Ordinary application images preserve the installed bootloader. Full Companion
|
||||
is a mOTA source and normally updates itself over USB. Older versions below
|
||||
describe compatibility history.
|
||||
|
||||
The dedicated [RAK3401 chain report](research/rak3401_mota_chain.md) records the
|
||||
physical failures of withdrawn migrations and the physically qualified compact
|
||||
@@ -20,16 +23,18 @@ accepted bridge image by SHA-256.
|
||||
|
||||
[`tools/lora_ota/lora_ota.sh`](https://github.com/mikecarper/MeshCore/blob/keymindCascade/tools/lora_ota/lora_ota.sh) and
|
||||
[`tools/lora_ota/lora_ota.ps1`](https://github.com/mikecarper/MeshCore/blob/keymindCascade/tools/lora_ota/lora_ota.ps1) automate a
|
||||
MeshCore LoRa firmware update from a release `.zip` or ready `.mota`. They
|
||||
MeshCore LoRa firmware update from a firmware `.zip` or ready `.mota`. They
|
||||
identify the destination, validate the hardware and running firmware, prepare
|
||||
the right container, move the participating nodes to a temporary radio
|
||||
channel, serve and monitor the download, request installation, restore the
|
||||
controller, and check the rebooted node.
|
||||
|
||||
The script cannot install the destination's first OTA-capable firmware. It can
|
||||
The destination must already have working application OTA support; install its
|
||||
first compatible application and bootloader locally. The script can
|
||||
stage signed v3 bootloader containers with `--no-install`, but never sends the
|
||||
privileged bootloader install command. Invalid v2 containers carrying the
|
||||
bootloader flag remain rejected. Do the first nRF52 bootloader installation over USB.
|
||||
bootloader flag remain rejected. A **with bootloader** application is a separate
|
||||
case: its firmware performs the startup check after the application is installed.
|
||||
An already-capable, explicitly supported internal-flash, XIAO QSPI, or exact
|
||||
MeshTower V2 microSD repeater may later use the separate manual
|
||||
[`ota bootloader install`](ota_nrf52_bootloader_update.md) workflow.
|
||||
@@ -300,8 +305,10 @@ that was actually flashed. A matching filename or version alone is not enough.
|
||||
## 1. Install the host tools
|
||||
|
||||
Install Python 3.10 or newer, [Rust](https://rustup.rs/), Git, the official
|
||||
[`meshcore-cli`](https://github.com/meshcore-dev/meshcore-cli) **1.6.0 or newer**, and the official
|
||||
[`motatool`](https://github.com/vk496/motatool).
|
||||
[`meshcore-cli`](https://github.com/meshcore-dev/meshcore-cli) **1.6.0 or newer**, and the
|
||||
supported [`mikecarper/motatool`](https://github.com/mikecarper/motatool) fork.
|
||||
The commands below use the same pinned revision as the runner's repair path.
|
||||
Building it requires stable Cargo and rustc **1.86.0 or newer**.
|
||||
|
||||
For signed bootloader staging, see the automatic `cryptography` and
|
||||
bootloader-capable `motatool` repairs above. Pip is needed only when installing
|
||||
@@ -320,8 +327,8 @@ python3 -m pip install --user pipx
|
||||
python3 -m pipx ensurepath
|
||||
pipx install meshcore-cli
|
||||
|
||||
git clone https://github.com/vk496/motatool.git
|
||||
cargo install --path ./motatool
|
||||
cargo install --git https://github.com/mikecarper/motatool.git \
|
||||
--rev 8c38369e7d35ad50cf74261869676d52dd24adf7 --locked --bin motatool
|
||||
|
||||
meshcli -v
|
||||
motatool --version
|
||||
@@ -334,8 +341,8 @@ py -m pip install --user pipx
|
||||
py -m pipx ensurepath
|
||||
pipx install meshcore-cli
|
||||
|
||||
git clone https://github.com/vk496/motatool.git
|
||||
cargo install --path .\motatool
|
||||
cargo install --git https://github.com/mikecarper/motatool.git `
|
||||
--rev 8c38369e7d35ad50cf74261869676d52dd24adf7 --locked --bin motatool
|
||||
|
||||
meshcli -v
|
||||
motatool --version
|
||||
@@ -462,7 +469,7 @@ packages still require the independently checked `ota bootloader status` board,
|
||||
target, ABI, codec and storage identity; missing version text never bypasses
|
||||
package signature checks or the explicit bootloader-install workflow. The
|
||||
separate hardware-qualified `rak3401_mota_chain.py` retains its exact deployed
|
||||
version restriction; it is not a general OTAFIX 2.4.6 update runner.
|
||||
version restriction; it is not a general bootloader update runner.
|
||||
Current firmware also reports `maxblk:2048` near the front of both OTA replies.
|
||||
The runner treats a missing marker as the deployed 1 KiB receive limit, rejects
|
||||
a ready 2 KiB package for such a target before transfer, and passes the live
|
||||
@@ -534,7 +541,8 @@ RXPS improves receive performance per unit of radio-on time, so the runner
|
||||
keeps the destination's saved RXPS preference enabled whenever the selected
|
||||
fast tuple has a qualified timing window. Before changing any radio, it reads
|
||||
`ver` from the destination, controller, source, and every named relay. It treats
|
||||
v1.17.1.5 as the first forward contract in which every SF5-SF8 transmission,
|
||||
v1.17.1.5 as the historical compatibility boundary (also met by 1.18.0.1) in
|
||||
which every SF5-SF8 transmission,
|
||||
including a retry, uses the same tuple-selected physical preamble: normally 32
|
||||
symbols, 64 only when 32 cannot enable RXPS, and 128 only when neither 32 nor
|
||||
64 can. A saved RXPS level is also safely retuned after a radio change. An
|
||||
@@ -543,7 +551,7 @@ sends `set radio.rxps off` instead of assuming an ad-hoc build contains the
|
||||
timing fixes. Automation deliberately treats the version as a wire-format
|
||||
contract.
|
||||
|
||||
For the default SF5/BW250 tuple, the runner keeps destination RXPS on only when
|
||||
At SF5/BW250, the runner keeps destination RXPS on only when
|
||||
the destination and every possible sender are v1.17.1.5 or newer. It does not
|
||||
overwrite an existing level-based preference. Current firmware retunes that
|
||||
preference against the tuple-selected 64-symbol wire preamble; the qualified boundary is
|
||||
@@ -599,10 +607,14 @@ rejections are not replayed.
|
||||
|
||||
## 4. Run an ESP32 update
|
||||
|
||||
The ZIP can contain a compatible ready `.mota` or the exact board-and-role
|
||||
non-merged application `.bin`:
|
||||
Download the destination's exact 1.18.0.1 **app-only `.bin`** from the
|
||||
[firmware picker](firmware_picker.md). Put it in a ZIP for the runner; do not
|
||||
use the USB `-merged.bin`. The examples call the downloaded application
|
||||
`target-1.18.0.1.bin` and the ZIP `release.zip`; substitute your actual `.bin`
|
||||
filename when creating it. A separately prepared, verified `.mota` also works.
|
||||
|
||||
```bash
|
||||
python3 -m zipfile -c release.zip ./target-1.18.0.1.bin
|
||||
export MESHCORE_ADMIN_PASSWORD='target-admin-password'
|
||||
|
||||
./tools/lora_ota/lora_ota.sh ./release.zip "Roof ESP32" \
|
||||
@@ -624,6 +636,7 @@ unattended job, add `--yes`:
|
||||
PowerShell equivalents:
|
||||
|
||||
```powershell
|
||||
py -m zipfile -c release.zip .\target-1.18.0.1.bin
|
||||
$env:MESHCORE_ADMIN_PASSWORD = 'target-admin-password'
|
||||
|
||||
& .\tools\lora_ota\lora_ota.ps1 '.\release.zip' 'Roof ESP32' `
|
||||
@@ -643,6 +656,10 @@ lines and removes its protected temporary command file after each call.
|
||||
|
||||
## 5. Run an nRF52 update
|
||||
|
||||
Choose the destination's 1.18.0.1 package in the [firmware picker](firmware_picker.md).
|
||||
Use its exact Full or Reduced sensors profile and storage layout;
|
||||
`nrf52-new-release.zip` below means that downloaded package.
|
||||
|
||||
If the input ZIP already contains a compatible in-place delta `.mota`, no
|
||||
base argument is needed: its embedded base hash is compared with the live
|
||||
node. If the ZIP contains raw new firmware, supply the exact running image:
|
||||
|
||||
@@ -4,6 +4,12 @@
|
||||
|
||||
# Embedded nRF52 bootloader update
|
||||
|
||||
For **MeshCore 1.18.0.1**, select your exact board and Repeater or Room Server
|
||||
role in the [firmware picker](firmware_picker.md), then choose **OTAFIX 2.4.12
|
||||
bootloader included** where available. See the
|
||||
[release notes](releases/1.18.0.1.md) and [update guide](ota_user_guide.md) for
|
||||
the application downloads and installation route.
|
||||
|
||||
An opt-in Repeater or Room Server build can carry its application firmware and
|
||||
the exact board's [OTAFIX 2.4.12 bootloader](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12)
|
||||
in one application image. After installing that application, it checks the
|
||||
@@ -29,8 +35,9 @@ and Room Server variants for hardware in the pinned normal OTAFIX catalog:
|
||||
bash build.sh release-build --firmware-version v1.18.0.1-halo-keymind-cascade-dev
|
||||
```
|
||||
|
||||
The local release also includes the exact-board standalone OTAFIX 2.4.12
|
||||
UF2, SoftDevice/bootloader DFU ZIP, and SWD HEX downloads. These serve
|
||||
The 1.18.0.1 [update utilities](https://github.com/mikecarper/MeshCore/releases/tag/utility-v1.18.0.1-halo-keymind-cascade-dev-03214a16)
|
||||
also include the exact-board standalone OTAFIX 2.4.12 UF2,
|
||||
SoftDevice/bootloader DFU ZIP, and SWD HEX downloads. These serve
|
||||
Companion and Sensor installations as well as the infrastructure roles.
|
||||
Pending, blocked and retired bootloader profiles are excluded and identified
|
||||
in the catalog. A normal application image does not update its bootloader.
|
||||
|
||||
+34
-24
@@ -4,14 +4,17 @@
|
||||
|
||||
# Easy firmware updates over LoRa
|
||||
|
||||
For **1.17.1.5**, use the exact board/storage profile from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6)
|
||||
for nRF52 OTAFIX installations. New internal-flash hybrid receivers require
|
||||
its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own
|
||||
matching bootloader profiles. Earlier preview versions mentioned below
|
||||
describe compatibility/migration history, not the current recommended download.
|
||||
Full Companion is a MOTA source and normally updates itself over USB.
|
||||
|
||||
For **[1.18.0.1 USA Cascade](releases/1.18.0.1.md)**, choose the exact board,
|
||||
role and storage layout in the [firmware picker](firmware_picker.md).
|
||||
For a new nRF52 installation, use the matching
|
||||
[OTAFIX 2.4.12](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12)
|
||||
bootloader. Supported Repeater and Room Server downloads also offer
|
||||
**with bootloader** application images; these check once after 70 seconds and
|
||||
can update a recognized compatible older bootloader. Read the
|
||||
[embedded bootloader guide](nrf52_embedded_bootloader.md) before choosing one.
|
||||
Ordinary application images preserve the installed bootloader. Full Companion
|
||||
is a mOTA source and normally updates itself over USB. Older versions below
|
||||
describe compatibility history.
|
||||
|
||||
This guide shows the shortest manual path for sending firmware from a computer to a MeshCore node over
|
||||
LoRa. Choose the package type for the **destination** node:
|
||||
@@ -63,7 +66,8 @@ configurations. Confirm that it is permitted in your location and change it when
|
||||
|
||||
At SF5/BW250, an SX1262+TCXO destination can keep RXPS enabled only when it and
|
||||
every sender that can reach it (controller, source, and relays) follow the
|
||||
v1.17.1.5-or-newer adaptive-preamble contract. The qualified destination
|
||||
adaptive-preamble contract introduced in v1.17.1.5 and retained in 1.18.0.1.
|
||||
The qualified destination
|
||||
boundary is effective level 8, preamble 64 and `1252 / 6424 us`. For manual
|
||||
setup, save `set radio.rxps level 8 preamble 32` before entering TempRadio; the
|
||||
`32` is a conservative saved timing assumption and current firmware selects
|
||||
@@ -219,24 +223,28 @@ use `192.168.4.1:5001`. The TCP seeder auto-attaches; do not also run
|
||||
|
||||
## Install `motatool`
|
||||
|
||||
Install Rust if necessary, then install the standalone packaging and serving tool:
|
||||
Install stable Rust/Cargo **1.86.0 or newer** if needed, then install the
|
||||
supported [motatool fork](https://github.com/mikecarper/motatool) at the same
|
||||
revision used by the scripted updater:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/vk496/motatool
|
||||
cargo install --path ./motatool
|
||||
cargo install --git https://github.com/mikecarper/motatool.git \
|
||||
--rev 8c38369e7d35ad50cf74261869676d52dd24adf7 --locked --bin motatool
|
||||
```
|
||||
|
||||
## ESP32: package a full firmware image
|
||||
|
||||
The destination must be an OTA-capable ESP32 with an A/B partition table. Download or build the new
|
||||
non-merged `.bin` application for the destination's exact board **and role**. Do not use an ESP32
|
||||
The destination must be an OTA-capable ESP32 with an A/B partition table. Download the 1.18.0.1
|
||||
non-merged `.bin` application for the destination's exact board **and role** from the
|
||||
[firmware picker](firmware_picker.md), or build that image locally. Do not use an ESP32
|
||||
`-merged.bin` factory image.
|
||||
|
||||
Put the application firmware in a working directory, then build a full `.mota` container. For example:
|
||||
Put the application firmware in a working directory. In this example it is saved as
|
||||
`target-1.18.0.1.bin`; use your downloaded application's actual filename:
|
||||
|
||||
```bash
|
||||
mkdir -p ./motas
|
||||
motatool build --fw ./Heltec_v3_repeater-ota-v1.16.05.bin --out-dir ./motas
|
||||
motatool build --fw ./target-1.18.0.1.bin --out-dir ./motas
|
||||
motatool verify ./motas/*.mota
|
||||
```
|
||||
|
||||
@@ -252,9 +260,9 @@ Do not continue if `motatool verify` reports a failure.
|
||||
|
||||
This is a one-time prerequisite. Install the OTAFIX bootloader built for the destination's **exact board**
|
||||
from the
|
||||
[OTAFIX nRF52 bootloader releases](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases).
|
||||
Internal-staging delta updates require OTAFIX 2.4 or newer. External QSPI and SD staging require OTAFIX
|
||||
2.4.1 or newer and release notes that explicitly list the exact board and storage mode. Follow the release's
|
||||
[OTAFIX 2.4.12 release](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12).
|
||||
Match the board and internal, QSPI or SD storage mode exactly. The internal-flash profile must support
|
||||
the retained-RAM handoff used by current firmware. Follow the release's
|
||||
board-specific installation and erase instructions. If it does not contain the destination's exact board,
|
||||
this LoRa install path is not yet available for that board; never substitute a similar board's bootloader.
|
||||
|
||||
@@ -323,7 +331,7 @@ INA226, INA260, and INA3221 I2C voltage/current monitors remain supported despit
|
||||
That trim does not remove the SSD1306 OLED, autodiscovered I2C RTCs, or GPS-compatible RAK12500 I2C path.
|
||||
The `0x42` RAK12500/INA3221 addressing rule above still applies.
|
||||
If the device has a RAK15001 installed in sensor slot C and the matching
|
||||
RAK15001 OTAFIX bootloader, use
|
||||
RAK4631 adaptive OTAFIX 2.4.12 bootloader (`wiscore_rak4631_auto`), use
|
||||
`RAK_4631_repeater_rak15001_slot_c_lora_ota` instead. That target retains the
|
||||
full sensor/GPS set and can install either a full image or a delta from the
|
||||
external 2 MiB store.
|
||||
@@ -331,9 +339,11 @@ external 2 MiB store.
|
||||
With the separately wired Winbond breakout, use
|
||||
`RAK_4631_repeater_w25q16_lora_ota` for RAK4631 or
|
||||
`RAK_3401_repeater_rak13302_w25q16_lora_ota` for RAK3401 + RAK13302. Both
|
||||
require an `EF4015` 2 MiB device. As a one-time prerequisite, install
|
||||
`wiscore_rak4631_w25q16` for RAK4631 or
|
||||
`wiscore_rak3401_rak13302_w25q16` for RAK3401 + RAK13302. Wire CLK/MISO/MOSI
|
||||
require an `EF4015` 2 MiB device. Current OTAFIX 2.4.12 downloads use the
|
||||
adaptive `wiscore_rak4631_auto` profile for RAK4631 or
|
||||
`wiscore_rak3401_auto` for RAK3401 + RAK13302. Follow the
|
||||
[QSPI installation and identity-migration instructions](ota_nrf52_qspi.md#one-time-prerequisite)
|
||||
when replacing an older dedicated-storage bootloader. Wire CLK/MISO/MOSI
|
||||
to the RAK19007 IO connector pins 26/27/28, CS to J11 AIN1, and VCC/GND to J12
|
||||
VDD/GND. Fit an approximately 10 kOhm CS-to-VDD pull-up; never use VBAT. The
|
||||
SPI pins require underside taps or an interposer, but no sensor slot is
|
||||
@@ -344,7 +354,7 @@ before installing either image.
|
||||
For a build that uses only the 2.54 mm headers, use the unified
|
||||
`RAK_4631_repeater_unified_lora_ota` or
|
||||
`RAK_3401_repeater_unified_lora_ota` image with its matching compatible
|
||||
OTAFIX 2.4.10 bootloader. Wire `CLK` to J10 `TX1`, `DO` to J10 `RX1`, `DI` to
|
||||
OTAFIX 2.4.12 bootloader. Wire `CLK` to J10 `TX1`, `DO` to J10 `RX1`, `DI` to
|
||||
J11 `IO1`, and `CS` to J11 `AIN1`; keep the `CS` pull-up and J12 power wiring.
|
||||
This gives up UART1 GPS/PPS but leaves I2C sensors and the RAK3401 radio
|
||||
available. See the [header-only wiring table](ota_nrf52_qspi.md#header-only-w25q16-wiring-for-the-unified-rak-images).
|
||||
|
||||
@@ -4,6 +4,14 @@
|
||||
|
||||
# MeshTower V2 microSD LoRa OTA
|
||||
|
||||
For **MeshCore 1.18.0.1**, select **MeshTower V2 SD** in the
|
||||
[firmware picker](firmware_picker.md) and use its matching combined SD/internal
|
||||
[OTAFIX 2.4.12 bootloader](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12).
|
||||
The [update guide](ota_user_guide.md) covers the release downloads and normal
|
||||
LoRa transfer. A separate **bootloader included** application is available for
|
||||
compatible Repeater installations; see
|
||||
[automatic and manual activation](nrf52_embedded_bootloader.md#install-and-activate).
|
||||
|
||||
`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
|
||||
@@ -27,8 +35,8 @@ 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):
|
||||
published combined MeshTower SD/internal profile in OTAFIX 2.4.12
|
||||
(introduced in 2.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
|
||||
@@ -204,12 +212,14 @@ 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 historical diagnostics, 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.
|
||||
That CRC identifies the old 2.4.6 package, not the current 2.4.12 bootloader.
|
||||
|
||||
## SD card CLI
|
||||
|
||||
|
||||
@@ -4,22 +4,19 @@
|
||||
|
||||
# nRF52 bootloader updates over LoRa
|
||||
|
||||
For **MeshCore 1.18.0.1**, choose the exact board and storage layout in the
|
||||
[firmware picker](firmware_picker.md). The matching bootloader release is
|
||||
[OTAFIX 2.4.12](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12).
|
||||
Firmware and bootloader versions are separate. See the
|
||||
[1.18.0.1 update guide](ota_user_guide.md) for ordinary application updates.
|
||||
|
||||
For an application image that carries its own board-matched 2.4.12 replacement,
|
||||
see [embedded nRF52 bootloader updates](nrf52_embedded_bootloader.md). A separate
|
||||
`with-bootloader-2.4.12` image checks once after 70 seconds of startup and updates
|
||||
a recognized compatible older bootloader when radio and OTA activity are idle.
|
||||
The authenticated admin activation command remains available for manual retry.
|
||||
|
||||
For **1.17.1.5**, use the exact board/storage profile from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6)
|
||||
for nRF52 OTAFIX installations. New internal-flash hybrid receivers require
|
||||
its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own
|
||||
matching bootloader profiles. Earlier preview versions mentioned below
|
||||
describe compatibility/migration history, not the current recommended download.
|
||||
Full Companion is a MOTA source and normally updates itself over USB.
|
||||
|
||||
|
||||
Selected nRF52840 repeater LoRa-OTA builds can replace their matching OTAFIX
|
||||
Selected nRF52840 Repeater and Room Server 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. A stock bootloader must first
|
||||
be replaced with the exact ABI-3 self-update-capable OTAFIX build over USB/BLE
|
||||
@@ -34,11 +31,14 @@ MeshCore. This includes the MBR parameter page at `0xFE000`, so an application
|
||||
cannot initiate `COPY_BL` even after verifying a signed bootloader package.
|
||||
Hardware testing on a RAK3401 confirmed the MBR SVC enters a bus fault and
|
||||
leaves the installed bootloader unchanged. For new RAK installations use the
|
||||
normal [OTAFIX 2.4.10](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.10)
|
||||
compatible `*_auto` bootloader. Existing standard `3401_DFU` / `4631_DFU`
|
||||
devices can receive its signed bootloader `.mota` over LoRa. Devices already
|
||||
running `3401_AUTO_DFU` / `4631_AUTO_DFU` need the matching 2.4.10 recovery
|
||||
bridge installed locally before switching to the normal image.
|
||||
normal OTAFIX 2.4.12 `wiscore_rak3401_auto` or `wiscore_rak4631_auto` image.
|
||||
These retain the standard `3401_DFU` / `4631_DFU` identities. A compatible
|
||||
standard installation can receive the exact signed bootloader `.mota` over
|
||||
LoRa. Historical `3401_AUTO_DFU` / `4631_AUTO_DFU` and dedicated external-storage
|
||||
identities need the matching local recovery bridge before moving to the normal
|
||||
image; select it from the separate `OTAFIX-2.4.12-R_recovery.zip` and follow the
|
||||
release's recovery instructions. Recovery images are migration tools, not the
|
||||
normal download.
|
||||
|
||||
## Storage layouts
|
||||
|
||||
@@ -120,17 +120,16 @@ estimate is unsafe when a normally linked application may extend to
|
||||
## Internal-flash target inventory
|
||||
|
||||
The release builder consumes the allowlist in
|
||||
`tools/mota/nrf52_internal_bootloader_targets.txt`. Ten names are also literal
|
||||
PlatformIO environments and are enabled automatically when built directly.
|
||||
The other eleven are release aliases assembled from a base environment plus
|
||||
the lean OTA overlay; build them through `build.sh`, which passes the same
|
||||
allowlist decision to the common pre-build guard. These lean repeater/bridge
|
||||
targets have no OTA-owned SD/QSPI store and have an exact curated OTAFIX
|
||||
manifest identity:
|
||||
`tools/mota/nrf52_internal_bootloader_targets.txt`. It includes literal
|
||||
PlatformIO environments and release aliases; build aliases through `build.sh`
|
||||
so the common pre-build guard receives the same storage/layout decision.
|
||||
The inventory includes lean repeaters and bridges plus the explicitly listed
|
||||
adaptive RAK receiver roles. Their bootloader identities are listed below;
|
||||
use the picker for current application names and downloads.
|
||||
|
||||
| Build target(s) | Installed OTAFIX identity | Boot target ID |
|
||||
| --- | --- | ---: |
|
||||
| `Heltec_tower_v2_repeater_lora_ota_no_external_sensors` | `239A0071 / TOWER_V2_OTA` | `1150F50E` |
|
||||
| Historical internal-only MeshTower V2 layout; current releases use the combined SD target | `239A0071 / TOWER_V2_OTA` | `1150F50E` |
|
||||
| T096 lean repeater and RS232 bridge | `239A0071 / T096_DFU` | `42354C85` |
|
||||
| `Heltec_t1_repeater_lora_ota_no_external_sensors` | `239A0071 / T1_DFU` | `FC556FFC` |
|
||||
| T114 display and without-display lean repeaters | `239A0071 / T114_DFU` | `0C3F2902` |
|
||||
@@ -140,8 +139,8 @@ manifest identity:
|
||||
| `ProMicro_repeater_lora_ota_no_external_sensors` | `239A00B3 / PROM_DFU` | `AF79E8CC` |
|
||||
| `t1000e_repeater_lora_ota_no_external_sensors` | `28860057 / T1KE_DFU` | `E6F5F03F` |
|
||||
| `ThinkNode_M3_repeater_lora_ota_no_external_sensors` | `239A00DA / TNM3_DFU` | `0CA41DB2` |
|
||||
| `RAK_3401_repeater_lora_ota_no_external_sensors` | `239A0029 / 3401_DFU` | `23818A80` |
|
||||
| RAK4631 lean repeater and both lean RS232 bridges | `239A0029 / 4631_DFU` | `2D0DF000` |
|
||||
| RAK3401 reduced repeater and unified repeater | `239A0029 / 3401_DFU` | `23818A80` |
|
||||
| RAK4631 reduced/unified repeater, both reduced RS232 bridges, and listed reduced Room/Sensor roles | `239A0029 / 4631_DFU` | `2D0DF000` |
|
||||
| GAT562 30S/Tracker Pro/EVB Pro lean targets | `239A0029 / GAT562_DFU` | `D50D2D44` |
|
||||
| `R1Neo_repeater_lora_ota_no_external_sensors` | `239A0029 / 4631_DFU` | `2D0DF000` |
|
||||
| `RAK_WisMesh_Tag_repeater_lora_ota_no_external_sensors` | `239A0029 / RTAG_DFU` | `C72E9C9C` |
|
||||
@@ -205,13 +204,19 @@ cannot coexist on the same bus at those addresses. Leave RAK12500 at `0x42`,
|
||||
strap INA3221 A0 to SCL for `0x43`, and use firmware built with
|
||||
`-DTELEM_INA3221_ADDRESS=0x43` when both modules are installed.
|
||||
|
||||
The current MeshTower V2 release uses the combined SD/internal bootloader;
|
||||
an internal-only installation needs the local migration described in the
|
||||
[MeshTower SD guide](ota_meshtower_v2_sdcard.md). Sharing a board/name pair
|
||||
does not make incompatible storage layouts interchangeable.
|
||||
|
||||
Boards with onboard external flash are not silently redirected to internal
|
||||
staging. Mesh Solar, Nano G2 Ultra, T-Impulse Plus, ThinkNode M8, T-Echo
|
||||
Lite/Card, MeshTracker X1, and Wio WM1110 have board-specific QSPI hardware and
|
||||
need a separately matched QSPI path where available. Full Companions, other
|
||||
SD/QSPI/ExtraFS roles, Ethernet roles, source-only roles, and unqualified
|
||||
full-sensor roles are excluded from the internal-flash inventory. The exact
|
||||
MeshTower V2 SD role above is separately qualified for its SD path.
|
||||
SD/QSPI/ExtraFS roles, source-only roles, and unlisted full-sensor roles are
|
||||
excluded from the internal-flash inventory. The explicitly allowlisted RAK4631
|
||||
Ethernet Room role is an exception; the exact MeshTower V2 SD role above has
|
||||
its own SD path.
|
||||
|
||||
This internal layout is limited to nRF52840 devices with 1 MiB internal flash,
|
||||
the exact S140 v6/v7 map, and the 40 KiB boot region at
|
||||
|
||||
+53
-40
@@ -4,14 +4,13 @@
|
||||
|
||||
# nRF52 repeater LoRa OTA with external QSPI
|
||||
|
||||
For **1.17.1.5**, use the exact board/storage profile from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6)
|
||||
for nRF52 OTAFIX installations. New internal-flash hybrid receivers require
|
||||
its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own
|
||||
matching bootloader profiles. Earlier preview versions mentioned below
|
||||
describe compatibility/migration history, not the current recommended download.
|
||||
Full Companion is a MOTA source and normally updates itself over USB.
|
||||
|
||||
For **MeshCore 1.18.0.1**, use the [firmware picker](firmware_picker.md) to
|
||||
select the exact application and its matching
|
||||
[OTAFIX 2.4.12 bootloader](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12).
|
||||
The [update guide](ota_user_guide.md) covers the release downloads and transfer
|
||||
steps. Older profiles below describe existing installations and migration
|
||||
requirements. Full Companion can serve mOTA files; it normally updates itself
|
||||
over USB.
|
||||
|
||||
Selected nRF52840 repeater builds use their dedicated external QSPI NOR flash as
|
||||
a raw LoRa OTA staging device. This removes the internal-flash staging conflict:
|
||||
@@ -37,6 +36,16 @@ on these currently matched families:
|
||||
- Elecrow ThinkNode M1 and M6
|
||||
- Seeed Wio Tracker L1
|
||||
- Seeed SenseCAP Solar Node P1
|
||||
|
||||
### Existing dedicated RAK layouts
|
||||
|
||||
Current RAK installations use the board-specific adaptive OTAFIX 2.4.12 image
|
||||
and the matching firmware from the picker. The dedicated application and
|
||||
bootloader pairs below describe older storage identities. They are not separate
|
||||
normal OTAFIX 2.4.12 downloads. Moving one to the adaptive profile requires the
|
||||
matching local identity migration; do not substitute a current bootloader into
|
||||
an older pairing.
|
||||
|
||||
- RAK4631 with a RAK15001 in WisBlock sensor slot C, using the dedicated
|
||||
`RAK_4631_repeater_rak15001_slot_c_lora_ota` application and matching
|
||||
`wiscore_rak4631_board_rak15001_slot_c` OTAFIX bootloader
|
||||
@@ -46,6 +55,8 @@ on these currently matched families:
|
||||
breakout on RAK19007, using
|
||||
`RAK_3401_repeater_rak13302_w25q16_lora_ota`
|
||||
|
||||
### Other boards and roles
|
||||
|
||||
Heltec T114 is intentionally not in this list. Its public V1, V2.0, and V2.1
|
||||
schematics show U9 (MX25R1635F) as an optional QSPI footprint, so standard T114
|
||||
application and bootloader targets do not assume that external NOR is populated.
|
||||
@@ -154,7 +165,7 @@ bootloader pairs are not interchangeable.
|
||||
|
||||
### Header-only W25Q16 wiring for the unified RAK images
|
||||
|
||||
The unified RAK repeater images and matching OTAFIX 2.4.10 compatible bootloaders
|
||||
The unified RAK repeater images and matching OTAFIX 2.4.12 adaptive bootloaders
|
||||
also support a W25Q16 through the RAK19007 2.54 mm headers. This arrangement
|
||||
does not need an IO-connector interposer or underside SPI solder points:
|
||||
|
||||
@@ -178,24 +189,25 @@ expect the WisBlock SPI connector wiring and do not use this header mapping.
|
||||
|
||||
## One-time prerequisite
|
||||
|
||||
Install a QSPI-capable OTAFIX 2.4.1 preview.9 or newer bootloader for the exact
|
||||
board from the
|
||||
[OTAFIX releases](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases)
|
||||
before using LoRa OTA. The release notes must explicitly list that board's QSPI
|
||||
mode. Also install the SoftDevice version expected by that target. The
|
||||
application refuses the install handoff when the bootloader does not advertise
|
||||
For a new 1.18.0.1 installation, install the exact normal OTAFIX 2.4.12 profile
|
||||
shown by the [firmware picker](firmware_picker.md), with its required
|
||||
SoftDevice. QSPI support first appeared in earlier previews; a version number
|
||||
alone does not confirm the flash wiring or storage capability. The application
|
||||
refuses the install handoff when the bootloader does not advertise matching
|
||||
QSPI support.
|
||||
|
||||
For the external W25Q16 option, install the corresponding bootloader once
|
||||
before installing its MeshCore application: `wiscore_rak4631_w25q16`
|
||||
For an existing dedicated W25Q16 application, its original matched loader is
|
||||
`wiscore_rak4631_w25q16`
|
||||
(`DEVICE_NAME=4631_W25Q16_DFU`) for RAK4631, or
|
||||
`wiscore_rak3401_rak13302_w25q16` (`DEVICE_NAME=3401_W25Q16_DFU`) for RAK3401
|
||||
plus RAK13302. Use only a release that explicitly names that exact pairing. Do
|
||||
not substitute the RAK15001 bootloader or swap the two W25Q16 bootloaders
|
||||
merely because the base-board wiring is the same.
|
||||
plus RAK13302. Those names identify the historical pairing, not new normal
|
||||
2.4.12 downloads. Use the release's exact recovery bridge and a local migration
|
||||
when moving to the current adaptive firmware/bootloader pair. Do not substitute
|
||||
the RAK15001 bootloader or swap the two dedicated W25Q16 bootloaders merely
|
||||
because the base-board wiring is the same.
|
||||
|
||||
For the first migration from the ordinary `wiscore_rak4631_board` bootloader to
|
||||
`wiscore_rak4631_board_rak15001_slot_c`, use Nordic serial DFU or a compatible
|
||||
For a historical first migration from the ordinary `wiscore_rak4631_board`
|
||||
bootloader to `wiscore_rak4631_board_rak15001_slot_c`, use Nordic serial DFU or a compatible
|
||||
BLE DFU client with the exact slot-C OTAFIX **combined bootloader + SoftDevice
|
||||
DFU package** (or use SWD), then reinstall the slot-C MeshCore application. The
|
||||
release filename has this form:
|
||||
@@ -313,8 +325,9 @@ Bootloader delivery is available only when all of these are already true:
|
||||
This is not part of normal automation. Bootloader catalog rows are labelled
|
||||
`bootloader`; even a capable node never autofetches or autoinstalls them, and
|
||||
ordinary `ota install` rejects them in every application backend. The
|
||||
`tools/lora_ota` deployment runner also refuses v3 packages. Fetch and arm one
|
||||
only with the explicit flow:
|
||||
`tools/lora_ota` deployment runner accepts a verified v3 package only with
|
||||
`--no-install`; it transfers and verifies the package, then leaves activation
|
||||
to the explicit command below:
|
||||
|
||||
```text
|
||||
ota ls
|
||||
@@ -453,21 +466,22 @@ RAM use; an exFAT card is not a supported STORE volume. This restriction does
|
||||
not change the historical CACHE-only RAK15002 seeder or MeshTower SD profiles,
|
||||
which retain their existing `SdFs`/`FsFile` (FAT/exFAT) behavior.
|
||||
|
||||
### Future receiver loader prerequisite and update flow
|
||||
### Receiver bootloader prerequisite and update flow
|
||||
|
||||
The matching `wiscore_rak4631_auto` **all-in-one OTAFIX bootloader** is only a
|
||||
local candidate today: it is not released and has not been hardware-qualified.
|
||||
Do not provision it as an SD-apply upgrade. Until a released, qualified loader
|
||||
explicitly advertises the supplemental authenticated RAK15002-SD
|
||||
*application* capability, the receiver fails SD application apply closed and
|
||||
continues to use its qualified internal/NOR path when no card is selected.
|
||||
The normal OTAFIX 2.4.12 `wiscore_rak4631_auto` image includes the authenticated
|
||||
RAK15002 SD application handoff while preserving internal/NOR support. It is
|
||||
published, but **physical RAK15002 card, interruption and power-cut
|
||||
qualification is still pending**. Check the release's qualification limits
|
||||
before using this storage path.
|
||||
|
||||
Once such a loader is released, it must preserve the deployed internal/NOR
|
||||
capabilities while adding the separate SD application handoff record. A stock,
|
||||
older, or otherwise ordinary RAK4631 OTAFIX bootloader must refuse the SD
|
||||
handoff. Its first migration will need to be performed locally over USB/BLE DFU
|
||||
or SWD; it must not be bootstrapped from the SD card or with a LoRa bootloader
|
||||
package.
|
||||
The receiver requires the supplemental `MOTASDRA` application capability;
|
||||
neither the `auto` filename nor a version string is sufficient. A stock or
|
||||
older loader without that record refuses SD apply. Install the exact normal
|
||||
profile locally, or update an already compatible installation through the
|
||||
[signed bootloader path](ota_nrf52_bootloader_update.md). Historical
|
||||
`4631_AUTO_DFU` and dedicated external-storage identities require their matching
|
||||
local recovery bridge before moving to the normal `4631_DFU` image. The first
|
||||
SD-capable loader cannot be bootstrapped from the SD card.
|
||||
|
||||
The supplemental capability is application-only: an SD card never authorizes
|
||||
a bootloader update. Existing qualified internal bootloader-update behavior is
|
||||
@@ -475,8 +489,7 @@ separate and still applies only to its exact package and loader identity. The
|
||||
Full Companion's archive/source feature never installs firmware locally, so it
|
||||
does not need this SD-apply bootloader capability.
|
||||
|
||||
Only after that future matching loader is released, installed locally, and
|
||||
qualified may a receiver use the normal explicit application flow:
|
||||
With the matching capability confirmed, the explicit application flow is:
|
||||
|
||||
```text
|
||||
ota status
|
||||
@@ -489,7 +502,7 @@ ota install
|
||||
`ota cache` manages the card-backed archive/source (`ota cache off` stops new
|
||||
captures; retained files can still seed). `ota storage` and `ota self` report
|
||||
the selected backend and loader state, but they intentionally do not force a
|
||||
removable-media probe at startup. After the future loader is present, a
|
||||
removable-media probe at startup. With the matching loader present, a
|
||||
card-backed receiver reports `SD store` and `authenticated SD apply OK`; before
|
||||
then, a missing supplemental capability, unsigned application, incompatible
|
||||
media, or a busy store fails before reboot/approval.
|
||||
|
||||
@@ -4,6 +4,11 @@
|
||||
|
||||
# MeshCore OTA - `.mota` container & LoRa protocol
|
||||
|
||||
This reference covers **[firmware 1.18.0.1](releases/1.18.0.1.md)** and the
|
||||
matched [OTAFIX 2.4.12 bootloaders](ota_nrf52_bootloader_update.md). Firmware,
|
||||
bootloader and container-format versions are independent: application packages
|
||||
remain format 2; signed standalone bootloader packages use format 3.
|
||||
|
||||
This is the **single source of truth** for MeshCore's over-the-air firmware update system ("mOTA"). It is
|
||||
written for developers who want to implement an interoperable peer (server, fetcher, relay, or host tool)
|
||||
in another codebase or project. Everything below is implemented in this repository and covered by host,
|
||||
@@ -17,7 +22,7 @@ the authoritative reference for byte-level details.
|
||||
**Design goals**
|
||||
|
||||
- Distribute firmware over LoRa as a **self-verifying, resumable, single-source block transfer** that
|
||||
survives reboots and never auto-applies without explicit consent.
|
||||
survives reboots and installs manually or under an explicitly enabled trusted-update policy.
|
||||
- **Trustless mesh relay:** repeaters may forward packets while the source alone serves firmware data;
|
||||
integrity is content-addressed
|
||||
against a signed merkle root, so a relay need not be trusted and never needs the signing keys.
|
||||
@@ -41,7 +46,7 @@ the authoritative reference for byte-level details.
|
||||
| Staging stores | `OtaStore.h`, `OtaStoreFlashNrf52.*`, `OtaStoreFlashEsp32.*` |
|
||||
| Apply | `OtaApply.*`, bootloader `Adafruit_nRF52_Bootloader_OTAFIX` |
|
||||
| Device glue (CLI/context) | `OtaCli.cpp`, `OtaContext.h` |
|
||||
| Host tooling | [`motatool`](https://github.com/vk496/motatool) (standalone Rust CLI: build/verify/inspect/serve); `tools/mota/` (Python reference lib `motalib.py` + build/test glue) |
|
||||
| Host tooling | [`motatool`](https://github.com/mikecarper/motatool) (supported Rust CLI: build/verify/inspect/serve; [pinned setup](lora_ota_automation.md)); `tools/mota/` (Python reference lib `motalib.py` + build/test glue) |
|
||||
|
||||
---
|
||||
|
||||
@@ -886,7 +891,7 @@ A `MotaSource` is fed by a host that serves a folder over the device's **USB ser
|
||||
CLI uses - no extra hardware), on an ESP32 WiFi companion or FULL ESP32 role over **WiFi (TCP)**, or on an
|
||||
nRF52 Full Companion over an encrypted **BLE GATT** service. The
|
||||
host is the
|
||||
standalone Rust tool [`motatool`](https://github.com/vk496/motatool) (`motatool serve --serial <port>` /
|
||||
standalone Rust tool [`motatool`](https://github.com/mikecarper/motatool) (`motatool serve --serial <port>` /
|
||||
`--tcp <host[:port]>`, which also builds + verifies + inspects `.mota`). The device only emits request frames *while
|
||||
actively serving a fetch*, and reads the reply synchronously, so over the shared USB console binary frames
|
||||
coexist with the text CLI/logs (resync on magic + checksum). Little-endian, XOR-checksummed:
|
||||
|
||||
+45
-23
@@ -133,8 +133,8 @@ or a small delta, how many nodes have it, and how recently it was seen. For exam
|
||||
|
||||
```
|
||||
Updates 1/1 (2 src; refreshing):
|
||||
1) 838B8169 v1.2.3 delta [same target] 3n 5s
|
||||
2) BF0AB0C4 v1.2.0 full [unsupported] 1n 12s
|
||||
1) 838B8169 v1.18.0.1 delta [same target] 3n 5s
|
||||
2) BF0AB0C4 v1.18.0.1 full [unsupported] 1n 12s
|
||||
```
|
||||
|
||||
Each row shows the version, full-vs-delta, **whether it fits your node**, how many nodes have it, and how
|
||||
@@ -249,21 +249,31 @@ hash-valid EndF version. Manual `ota install` remains the deliberate equal-versi
|
||||
|
||||
After it reboots, run `ota status` to confirm the new version.
|
||||
|
||||
### Updating an nRF52 bootloader (advanced, explicit only)
|
||||
### Updating an nRF52 bootloader
|
||||
|
||||
This is available on specially marked no-external-flash nRF52840 lean
|
||||
repeater/bridge builds, on the legacy XIAO nRF52840/Sense raw-QSPI builds, and
|
||||
on the exact `Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors`
|
||||
microSD build,
|
||||
after a one-time exact-board ABI-3 OTAFIX installation over USB/BLE DFU or
|
||||
SWD. It is not the normal firmware update path. Check support first:
|
||||
For 1.18.0.1, the picker offers **with bootloader** Repeater and Room Server
|
||||
images carrying the matched OTAFIX 2.4.12 update. These check the installed
|
||||
bootloader after 70 seconds and update a supported older normal bootloader.
|
||||
Recovery and unrecognized bootloaders are excluded. See the
|
||||
[embedded bootloader guide](nrf52_embedded_bootloader.md) for the starting
|
||||
requirements, one-check-per-firmware behavior, and reboot-loop protection.
|
||||
|
||||
The separate signed `.mota` bootloader workflow below is manual. It does not
|
||||
use application autofetch or autoinstall settings.
|
||||
|
||||
#### Install a separately downloaded bootloader package
|
||||
|
||||
This requires a supported nRF52 application and an exact-board ABI-3 OTAFIX
|
||||
bootloader provisioned locally first. See the
|
||||
[supported bootloader-update profiles](ota_nrf52_bootloader_update.md) for
|
||||
internal, QSPI and MeshTower V2 microSD requirements. Check support first:
|
||||
|
||||
```text
|
||||
ota bootloader
|
||||
```
|
||||
|
||||
The reply must show a CRC-valid installed identity plus ABI 3 and the exact
|
||||
storage/boot-update capability bits for that build (`0x09` for MeshTower V2
|
||||
storage/boot-update capability bits for that build (for example, `0x09` for MeshTower V2
|
||||
microSD, `0x0A` for the shared internal store, or `0x0E` for XIAO raw QSPI). A bootloader package appears as
|
||||
`bootloader` in `ota ls`. It is never downloaded or installed automatically,
|
||||
even if both OTA automation settings are enabled. Use its stable ID explicitly:
|
||||
@@ -276,7 +286,8 @@ ota bootloader install <MID8> <HASH16>
|
||||
```
|
||||
|
||||
Copy both confirmation values exactly from the second `ota bootloader` reply.
|
||||
Ordinary `ota install` deliberately refuses this package. The privileged
|
||||
For an image carrying its own bootloader, `ota bootloader update` instead
|
||||
selects that embedded update. Ordinary `ota install` refuses the standalone 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, required `BLM2`/`SOFT` continuity metadata at canonical
|
||||
@@ -500,11 +511,13 @@ folder of firmware files to the mesh - without storing them itself. Useful for s
|
||||
remote area.
|
||||
|
||||
1. Put the firmware files (`.mota` files - see below) in a folder on the computer.
|
||||
2. Install the helper tool once - the standalone `motatool` CLI (<https://github.com/vk496/motatool>) -
|
||||
2. Install the supported [`motatool` fork](https://github.com/mikecarper/motatool) once
|
||||
(Rust 1.86 or newer and a native linker are required) -
|
||||
then point it at your node and the folder - over the node's **USB serial**, over **WiFi** if it is
|
||||
an ESP32 WiFi companion or FULL ESP32 node, or over encrypted **Bluetooth** if it is an nRF52 Full Companion:
|
||||
```
|
||||
git clone https://github.com/vk496/motatool && cargo install --path ./motatool
|
||||
cargo install --git https://github.com/mikecarper/motatool \
|
||||
--rev 8c38369e7d35ad50cf74261869676d52dd24adf7 --locked
|
||||
# over USB serial:
|
||||
motatool serve --dir ./my_firmware/ --serial /dev/ttyACM0 -v
|
||||
# ...or over WiFi: the seeder is on dedicated TCP port 5001:
|
||||
@@ -515,7 +528,7 @@ remote area.
|
||||
```
|
||||
It answers the node's requests; your node then advertises those updates to neighbours, who can
|
||||
`ota get` them like any other. (A WiFi node prints its IP + seeder port to the serial log on connect.
|
||||
Details: <https://github.com/vk496/motatool>.)
|
||||
Details: [scripted setup and tool checks](lora_ota_automation.md).)
|
||||
|
||||
Check the device's attach reply or run `ota folder`: `host=X/Y` means the firmware is advertising `X` of
|
||||
the `Y` valid entries reported by the host. Serve registries are deliberately RAM-bounded on smaller builds,
|
||||
@@ -599,9 +612,16 @@ receiving a full image.
|
||||
OTA distributes **`.mota`** files - a packaged, verifiable firmware image (full image or a small "delta"
|
||||
that only contains what changed). You get them by:
|
||||
|
||||
- **Downloading a build.** This fork publishes a rolling **`dev-latest`** release on GitHub with the
|
||||
current firmware for many boards, each accompanied by a `.full.mota` and a tiny `.delta.mota`. Grab the
|
||||
one for your board to test.
|
||||
- **Downloading 1.18.0.1.** Use the [firmware picker](firmware_picker.md) to
|
||||
select the exact board, role, sensor profile and storage layout. The
|
||||
[release notes](releases/1.18.0.1.md#choose-a-download) link all release parts.
|
||||
Give the selected application ZIP to the [scripted updater](lora_ota_automation.md),
|
||||
or serve a verified `.mota` already built for that receiver. If the download
|
||||
is an app-only `.bin`, first [package it](ota_easy.md#esp32-package-a-full-firmware-image)
|
||||
as a `.mota`, or put it in a ZIP for the script. ESP32 `-merged.bin` files are for USB
|
||||
installation, not LoRa OTA. Internal-only nRF52 receivers need an in-place
|
||||
delta built against their exact running firmware; a ready delta is not
|
||||
available for every installed version.
|
||||
- **Building your own** with the `mota` packaging tool - see [tools/mota/README.md](https://github.com/mikecarper/MeshCore/blob/keymindCascade/tools/mota/README.md)
|
||||
(this is for people distributing updates, not everyday operators).
|
||||
|
||||
@@ -707,7 +727,7 @@ flash consumes no WisBlock slot, so a supported GPS can remain in slot A.
|
||||
|
||||
The unified RAK repeater images additionally support a header-only W25Q16
|
||||
layout, using J10 `TX1`/`RX1` and J11 `IO1`/`AIN1`. This layout needs the
|
||||
matching compatible OTAFIX 2.4.10 bootloader and gives up UART1 GPS/PPS; I2C
|
||||
matching compatible OTAFIX 2.4.12 bootloader and gives up UART1 GPS/PPS; I2C
|
||||
sensors remain available. See the [pin table](ota_nrf52_qspi.md#header-only-w25q16-wiring-for-the-unified-rak-images).
|
||||
|
||||
Older full-sensor `RAK_4631_repeater` images exceeded the safe internal
|
||||
@@ -723,8 +743,10 @@ For the external Winbond breakout, use
|
||||
`RAK_4631_repeater_w25q16_lora_ota` on RAK4631 or
|
||||
`RAK_3401_repeater_rak13302_w25q16_lora_ota` on RAK3401 + RAK13302. They retain
|
||||
the full sensor/GPS recipe and require exactly a 2 MiB `EF4015` W25Q16 plus the
|
||||
bootloader for that same core/radio/flash combination. Install
|
||||
`wiscore_rak4631_w25q16` for RAK4631 or
|
||||
`wiscore_rak3401_rak13302_w25q16` for RAK3401 + RAK13302 as a one-time
|
||||
prerequisite. The physical wiring is shared, but the two firmware identities
|
||||
are deliberately different and cannot be substituted for one another.
|
||||
bootloader for that same core/radio/flash combination. Older installations used
|
||||
the dedicated `wiscore_rak4631_w25q16` or `wiscore_rak3401_rak13302_w25q16`
|
||||
bootloader. Current OTAFIX 2.4.12 uses the corresponding `wiscore_rak4631_auto`
|
||||
or `wiscore_rak3401_auto` profile. Follow the
|
||||
[QSPI installation and identity-migration instructions](ota_nrf52_qspi.md#one-time-prerequisite)
|
||||
when changing profiles. The shared wiring does not make the two firmware
|
||||
identities interchangeable.
|
||||
@@ -365,9 +365,11 @@ source commands and the bounded temporary radio setup.
|
||||
| Qualified LoRa OTA receiver | Follow [LoRa OTA directions](ota_easy.md) | Exact destination package, storage profile, and overlapping temporary radio windows |
|
||||
|
||||
For nRF52 OTAFIX installations use the exact board/storage build from
|
||||
[OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6).
|
||||
Its retained-RAM handoff is required by the new internal-flash hybrid receiver
|
||||
images. Full Companions are sources and remain normally USB-updated.
|
||||
[OTAFIX 2.4.12](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/v0.11.0-OTAFIX2.4.12).
|
||||
For **1.18.0.1**, follow the [update guide](ota_user_guide.md) and
|
||||
[bootloader instructions](ota_nrf52_bootloader_update.md). Its retained-RAM
|
||||
handoff is required by internal-flash hybrid receiver images. Full Companions
|
||||
are sources; their own updates use supported USB, Bluetooth DFU or WiFi methods.
|
||||
|
||||
The [complete infrastructure CLI](cli_commands.md), [role/build matrix](cli_build_matrix.md),
|
||||
and [Full Companion feature guide](full_companion_features.md) provide details.
|
||||
@@ -1,5 +1,11 @@
|
||||
# LoRa OTA tools
|
||||
|
||||
For **MeshCore 1.18.0.1**, choose the exact application package from the
|
||||
[firmware picker](../../docs/firmware_picker.md), then follow the
|
||||
[scripted update guide](../../docs/lora_ota_automation.md). Supported nRF52
|
||||
destinations use the matching OTAFIX 2.4.12 bootloader. Full Companion is a
|
||||
source for other nodes and normally updates itself over USB.
|
||||
|
||||
`lora_ota.py` is the existing Companion-based update runner. The separate
|
||||
`mota_kiss_direct.py` tool serves one verified `.mota` file through a **full KISS
|
||||
modem** on logical radio port `0` or `1`. It does not use the Companion raw-packet
|
||||
|
||||
@@ -5,10 +5,16 @@ spec ([`docs/ota_protocol.md`](../../docs/ota_protocol.md)) and the **build + te
|
||||
no longer a user-facing CLI.
|
||||
|
||||
> **Want to build / verify / inspect / serve `.mota` from the command line?** Use the standalone
|
||||
> [`motatool`](https://github.com/vk496/motatool) Rust CLI (its own repository). It supersedes the old
|
||||
> supported [`motatool` fork](https://github.com/mikecarper/motatool) Rust CLI
|
||||
> ([pinned installation](../../docs/lora_ota_automation.md)). It supersedes the old
|
||||
> `mota.py` / `mota_seeder.py` (now removed) and produces byte-identical containers. The files here are
|
||||
> the spec oracle and the firmware build/test glue.
|
||||
|
||||
For **firmware 1.18.0.1**, use the [firmware picker](../../docs/firmware_picker.md)
|
||||
and [OTA guide](../../docs/ota_user_guide.md). Its nRF52 bootloader release is
|
||||
OTAFIX 2.4.12; this does not change application format 2 or standalone
|
||||
bootloader format 3.
|
||||
|
||||
## Setup
|
||||
|
||||
Use one pipx-managed `detools` environment. `cryptography` (Ed25519) and
|
||||
|
||||
Reference in new issue
Block a user