Add a guided USB-to-LoRa updater for repeaters and companions

This commit is contained in:
mikecarper committed 2026-10-26 19:46:05 -07:00
1 parent c313658b88
commit 4afad09048
21 files changed
+5082

No files matched your search

+3
View File
@@ -4,6 +4,9 @@
# Scripted LoRa OTA from start to finish
For a guided zero-hop update through one USB Repeater or Full Companion,
use the [Python updater](ota_wizard.md).
For a manual example using a Pi-connected repeater and the app's admin console,
see [Station G2 to Ikoka Stick](ota_station_g2_to_ikoka_stick.md).
+3
View File
@@ -4,6 +4,9 @@
# Easy firmware updates over LoRa
For automatic board detection, firmware preparation, installation, and
settings recovery through one USB radio, use the [guided Python updater](ota_wizard.md).
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
+3
View File
@@ -4,6 +4,9 @@
# LoRa OTA example: Station G2 on a Pi to an Ikoka Stick
For the automatic version using only the Pi's USB-connected source radio,
start with the [guided LoRa updater](ota_wizard.md).
Update the Ikoka Stick's bootloader to **OTAFIX 2.4.12**, then install
**1.18.0.1 Full Repeater** firmware. The Station G2 stays connected to the Pi
by USB and serves the files. Use the app's authenticated Repeater Admin console for the Ikoka
+174
View File
@@ -0,0 +1,174 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/ota_wizard/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# Guided LoRa updates
Run one Python command to update a directly reachable Repeater or Room Server.
The wizard identifies the board, chooses compatible firmware, prepares the
transfer, installs it, checks the result, and restores the original radio,
RX power-saving, and OTA settings. On supported nRF52 boards it also checks
for a newer compatible signed bootloader and includes that update in the plan.
## Connect a source radio
Use either connection:
| Computer connection | Source radio | Destination |
| --- | --- | --- |
| Raspberry Pi → USB | ESP32 Repeater with OTA and `ota.peer` support | Repeater or Room Server |
| Computer or Pi → USB | Full Companion with USB OTA source and direct admin support | Repeater or Room Server |
A **Station G2 Repeater connected to a Pi** can manage and serve an update to
an **Ikoka Stick Repeater** through that single USB connection. It does not
need a second local radio or the phone app. Install a source firmware build
containing `ota.peer` first; older Repeater firmware cannot manage the remote
node through USB. Check with `ota.peer status` in its USB console.
The Full Companion source also needs a current build containing the wizard's
direct admin guard. An older Full Companion may serve OTA files but cannot
provide this guarded admin connection; the wizard will ask for a source
firmware upgrade instead of proceeding with that connection.
The source and destination must already use the same main-channel settings
and hear each other directly. The destination needs working LoRa OTA support
and its admin password. A stock nRF52 bootloader may need a matching local
installation before it can accept remote updates.
The wizard sends discovery, admin commands, and OTA traffic directly with no
relay hops. An older destination may put its first login reply in a flood
envelope; the wizard accepts it only if it arrives with zero hops, establishes
a direct return route, then requires a fresh direct identity check.
Close other apps using the USB port before starting.
## Start
From the MeshCore checkout:
```bash
python3 tools/lora_ota/ota_wizard.py
```
On Windows, use `py` in place of `python3`. The first run installs USB and
verification dependencies in a private Python environment. On Raspberry Pi OS,
install `python3-venv` if Python reports that it is missing.
The wizard selects the USB radio and destination automatically when there is
only one of each. Otherwise, choose from the displayed list. Enter the
destination admin password once, choose firmware, then review the plan and
press Enter to start. Password entry is hidden and passwords are never saved.
Firmware choices are:
- **Published GitHub firmware:** the default, matched to the exact board and
role. A running version that is already current is left in place.
- **Custom firmware file:** an application DFU ZIP, BIN, HEX, full mOTA, or a
prepared update bundle.
- **Build custom Full firmware from source:** offered on a computer. This
needs the firmware build tools and Bash; it is not offered by default on
a Pi. The generated version is newer than the detected installed version.
The displayed plan includes package sizes, firmware version, and any
bootloader or trusted update signer being installed. After a reboot, the
wizard checks the running firmware hash and version, or the bootloader's
identity and version, before reporting success.
## Differential or full updates
The wizard looks for the **exact running firmware** in its cache and published
GitHub assets. It uses a differential package when it has a compatible builder,
can match that exact base, and the resulting package is smaller. A file with
the same version label but a different body hash is not a usable base.
On a computer, the differential builder can be prepared automatically with a
compatible Rust toolchain. On a Pi without a builder, the default is a full
update made by Python without compiling. This requires destination storage
that supports full updates, such as the Ikoka Stick's QSPI flash.
An internal-flash nRF52 destination that requires differential installation
cannot use that full fallback. Prepare its bundle on a computer instead:
1. On the Pi, inspect the connected radios:
```bash
python3 tools/lora_ota/ota_wizard.py --check
```
Copy the JSON file shown after **Preparation request:** to the computer.
It contains public board information and the exact running firmware hash,
without the admin password.
2. On the computer, prepare the update using the request, new firmware, and
the exact firmware currently running on the destination:
```bash
python3 tools/lora_ota/ota_wizard.py --prepare-only \
--request DEVICE.json --firmware NEW_FIRMWARE.zip \
--base RUNNING_FIRMWARE.zip --output update.ota.zip
```
No radio is opened. If the compatible differential builder and all input
files are already present, this also works without network access. Add
`--motatool /path/to/motatool` to use an existing builder.
3. Copy `update.ota.zip` back to the Pi and run:
```bash
python3 tools/lora_ota/ota_wizard.py --firmware update.ota.zip
```
The live destination is checked again before installation. A changed base
hash or a different board stops the differential update.
For an offline full bundle on a destination that supports it, add `--full`
to the preparation command. This path needs neither the differential builder
nor USB dependencies.
## Useful options
| Option | Purpose |
| --- | --- |
| `--check` | Authenticate and inspect OTA support without downloading or installing firmware |
| `--port /dev/ttyUSB0` | Choose a USB port; Windows example: `--port COM5` |
| `--mode repeater` or `--mode companion` | Select the source type if automatic detection is unsuitable |
| `--target PUBLIC_KEY` | Choose a destination by its full 64-character key; it must still answer direct discovery |
| `--firmware FILE` | Use a local firmware image or prepared bundle |
| `--base FILE` | Supply the exact running firmware for differential preparation |
| `--full` | Choose a full application transfer when the destination supports it |
| `--build` | Build custom Full firmware from this checkout |
| `--version 1.18.0.3-custom` | Set the custom build version; it must be newer than the running version |
| `--no-bootloader` | Update application firmware only |
| `--cache DIRECTORY` | Choose where packages, public requests, and recovery records are saved |
| `--yes` | Accept the displayed plan; required choices and credentials must still be supplied |
For unattended use, provide `MESHCORE_ADMIN_PASSWORD` in the process environment
and pass the port, source type, and target key. The wizard does not write that
password into its preferences, recovery records, or custom build environment.
## If the connection is interrupted
Keep the same source radio connected and run the wizard again. It checks the
saved source and destination public keys before restoring settings from an
unfinished update. To restore settings and exit:
```bash
python3 tools/lora_ota/ota_wizard.py --recover --target PUBLIC_KEY
```
Keep the recovery record until the wizard reports that restoration is
complete. A lost install reply is followed by a running-image check; the
wizard does not blindly repeat an install command. Temporary radio windows
use the existing main-channel settings, so an interrupted process does not
leave the destination on a separate update frequency.
The cache is normally `~/.cache/meshcore/ota` on Linux,
`~/Library/Caches/MeshCore/ota` on macOS, or `%LOCALAPPDATA%\MeshCore\ota` on
Windows. It contains firmware, public preparation records, selected board
keys, and restoration settings. Trusted signer keys added for an update remain
installed on the destination.
For the individual commands and a manual board-by-board example, see
[Station G2 to Ikoka Stick](ota_station_g2_to_ikoka_stick.md). For routed
updates and explicit multi-node setup, use the
[scripted LoRa OTA guide](lora_ota_automation.md).