Add a guided USB-to-LoRa updater for repeaters and companions
This commit is contained in:
1 parent
c313658b88
commit
4afad09048
21 files changed
+5082
No files matched your search
@@ -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).
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
Reference in new issue
Block a user