151 lines
5.6 KiB
Markdown
151 lines
5.6 KiB
Markdown
# Easy full-firmware update over LoRa
|
|
|
|
This guide shows the shortest manual path for sending a **full firmware image** from a computer to a
|
|
MeshCore node over LoRa. It uses this temporary OTA channel:
|
|
|
|
| Setting | Value |
|
|
| --- | --- |
|
|
| Center frequency | 909.950 MHz |
|
|
| Bandwidth | 125 kHz |
|
|
| Spreading factor | SF5 |
|
|
| Example coding rate | CR5 |
|
|
| Example window | 120 minutes |
|
|
|
|
The copy/paste command is:
|
|
|
|
```text
|
|
tempradio 909.950,125,5,5,120
|
|
```
|
|
|
|
The fourth value is the transmit coding rate. This example uses CR5, but LoRa OTA does not require CR5.
|
|
|
|
`tempradio` is not saved and the node returns to its normal radio settings when the window ends or the node
|
|
reboots. This frequency is intended for North American configurations. Confirm that it is permitted in your
|
|
location and change it when necessary.
|
|
|
|
## Before you start
|
|
|
|
You need:
|
|
|
|
- A standard, non-logging Keymind OTA build on the source and destination nodes. Logging and MQTT builds do
|
|
not include LoRa OTA. Use the WiFi or USB connection to update those.
|
|
- An OTA-capable destination. ESP32 boards use their A/B firmware slots. nRF52 nodes also need the
|
|
MeshCore OTAFIX bootloader.
|
|
- The new, non-merged application firmware for the destination's exact board **and role**. Use `.bin` for
|
|
ESP32 or `.hex` for nRF52; do not package an ESP32 `-merged.bin` factory image.
|
|
- A source node connected to the computer by USB serial.
|
|
- Overlapping `tempradio` windows on the source, destination, and every repeater needed between them.
|
|
|
|
LoRa OTA packets are generated, received, and relayed only while `tempradio` is active. If any required
|
|
window closes, the transfer stops making progress and can resume during a later overlapping window.
|
|
|
|
## 1. Install `motatool`
|
|
|
|
Install Rust if necessary, then install the standalone packaging and serving tool:
|
|
|
|
```bash
|
|
git clone https://github.com/vk496/motatool
|
|
cargo install --path ./motatool
|
|
```
|
|
|
|
## 2. Package the full firmware
|
|
|
|
Put the application firmware in a working directory, then build a full `.mota` container. For example:
|
|
|
|
```bash
|
|
mkdir -p ./motas
|
|
motatool build --fw ./Heltec_v3_repeater-v1.16.05.bin --out-dir ./motas
|
|
motatool verify ./motas/*.mota
|
|
```
|
|
|
|
Replace the example filename with the firmware for the destination's exact target. With no `--base`
|
|
argument, `motatool build` creates a full-image update. The firmware must contain its MeshCore `EndF`
|
|
identity trailer so `motatool` and the destination can verify the target, hardware, and version.
|
|
|
|
Do not continue if `motatool verify` reports a failure.
|
|
|
|
## 3. Start the temporary OTA channel
|
|
|
|
On the source node, destination node, and every intermediate repeater, run:
|
|
|
|
```text
|
|
tempradio 909.950,125,5,5,120
|
|
```
|
|
|
|
All participating nodes must use the same frequency, bandwidth, and spreading factor. Their time windows must
|
|
overlap. Start with the farthest hop (the destination) and work back toward the source when using `tempradio`.
|
|
|
|
If you administer the destination over LoRa, the controller used to send later `ota` commands must also be
|
|
able to communicate on this temporary channel. For unattended nodes, use synchronized `tempradioat` entries
|
|
instead of manually starting the windows. Ensure the nodes' clocks are set before using `tempradioat`.
|
|
|
|
## 4. Serve the update from the computer
|
|
|
|
Close any serial terminal using the source node's USB port, find its device name, and start the server:
|
|
|
|
```bash
|
|
motatool serve --dir ./motas --serial /dev/ttyACM0 -v
|
|
```
|
|
|
|
Replace `/dev/ttyACM0` with the source node's serial device. `motatool` attaches the folder to the source
|
|
node, and the source advertises the full update over LoRa while its temporary-radio window is active.
|
|
|
|
Leave this command running until the destination finishes downloading.
|
|
|
|
## 5. Find and download the update
|
|
|
|
On the destination node, check its state and ask for nearby updates:
|
|
|
|
```text
|
|
ota status
|
|
ota ls
|
|
```
|
|
|
|
Discovery is asynchronous. Wait a few seconds and run `ota ls` again if the list is initially empty. Find
|
|
the entry marked `[yours]` and `full`, then use its displayed number. If it is entry 1, run:
|
|
|
|
```text
|
|
ota pull 1 flash
|
|
```
|
|
|
|
Monitor the transfer:
|
|
|
|
```text
|
|
ota status
|
|
```
|
|
|
|
The update is ready when the status says `ready to install`. OTA is deliberately the lowest-priority mesh
|
|
traffic, so a busy channel can make a full-image transfer take longer than the example window. If necessary,
|
|
start another overlapping `tempradio` window; the download resumes rather than starting over.
|
|
|
|
## 6. Verify and install
|
|
|
|
Once the destination reports `ready to install`, run:
|
|
|
|
```text
|
|
ota install
|
|
```
|
|
|
|
The destination verifies the complete firmware again before approving it. If verification succeeds, it
|
|
reboots and applies the update. If verification fails, it keeps the current firmware and reports an error.
|
|
|
|
After the node returns, reconnect on its normal radio channel and confirm:
|
|
|
|
```text
|
|
ota status
|
|
```
|
|
|
|
## Quick troubleshooting
|
|
|
|
- **Nothing appears in `ota ls`:** confirm that `motatool serve` is still running and every required node
|
|
has an active `tempradio 909.950,125,5,5,120` window.
|
|
- **The update is marked `[other hw]`:** it is for a different board or firmware role. Do not install it.
|
|
- **The download stalls:** check the source, destination, and intermediate repeaters. Restart matching,
|
|
overlapping temporary-radio windows if one expired.
|
|
- **The serial port is busy:** close the serial terminal before starting `motatool serve`.
|
|
- **The destination rejects the package:** verify that you used the non-merged application image with the
|
|
`EndF` trailer and that `motatool verify` succeeds.
|
|
|
|
For additional commands and safety details, see [the full OTA user guide](ota_user_guide.md). For protocol
|
|
and container internals, see [the OTA protocol specification](ota_protocol.md).
|