diff --git a/docs/index.md b/docs/index.md index ddad15e26..2bc0f937a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,7 @@ Below are a few quick start guides. - [Frequently Asked Questions](./faq.md) - [CLI Commands](./cli_commands.md) +- [Easy Full-Firmware Update over LoRa](./ota_easy.md) - [GPS Tracking](./gps_tracking.md) - [Companion Protocol](./companion_protocol.md) - [Packet Format](./packet_format.md) diff --git a/docs/ota_easy.md b/docs/ota_easy.md new file mode 100644 index 000000000..041a565df --- /dev/null +++ b/docs/ota_easy.md @@ -0,0 +1,149 @@ +# 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 | +| Coding rate | CR5 | +| Example window | 120 minutes | + +The copy/paste command is: + +```text +tempradio 909.950,125,5,5,120 +``` + +`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 exactly the same frequency, bandwidth, spreading factor, and coding rate. +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).