From 9ed0c548207a670c9b44b14102a9b7acf9048a65 Mon Sep 17 00:00:00 2001 From: mikecarper Date: Tue, 21 Jul 2026 13:51:48 -0700 Subject: [PATCH] Gate and label LoRa OTA builds --- build.sh | 6 ++++ docs/ota_easy.md | 17 ++++++----- docs/ota_user_guide.md | 23 +++++++++++---- src/helpers/CommonCLI.cpp | 61 ++++++++++++++++++++++++++++++--------- src/helpers/CommonCLI.h | 3 ++ 5 files changed, 84 insertions(+), 26 deletions(-) diff --git a/build.sh b/build.sh index b1ce554e0..31cfc44d3 100755 --- a/build.sh +++ b/build.sh @@ -1738,6 +1738,12 @@ get_firmware_filename() { filename_infix="logging" fi + # Make LoRa-OTA artifacts as obvious as logging artifacts without changing + # the PlatformIO environment name or the stable MOTA target identity. + if [ -z "$filename_infix" ] && is_lora_ota_build "$env_name"; then + filename_infix="ota" + fi + if [ -n "$filename_infix" ]; then echo "${env_name}-${filename_infix}-${firmware_version_string}" else diff --git a/docs/ota_easy.md b/docs/ota_easy.md index 23fb9f761..9d7157699 100644 --- a/docs/ota_easy.md +++ b/docs/ota_easy.md @@ -16,7 +16,7 @@ delta built against its exact running firmware. | Setting | Value | | --- | --- | | Center frequency | 909.950 MHz | -| Bandwidth | 125 kHz | +| Bandwidth | 250 kHz | | Spreading factor | SF5 | | Coding rate used in this guide | CR5 | | Example window | 120 minutes | @@ -24,7 +24,7 @@ delta built against its exact running firmware. The copy/paste command is: ```text -tempradio 909.950,125,5,5,120 +tempradio 909.950,250,5,5,120 ``` The fourth value is the transmit coding rate. This guide uses CR5, but the participating nodes' coding rates @@ -38,8 +38,9 @@ location and change it when necessary. Both paths require: -- Standard, non-logging Keymind OTA firmware on the source, destination, and intermediate nodes. Logging - and MQTT builds do not include LoRa OTA; use WiFi or USB to update those. +- An OTA-enabled repeater build whose artifact filename contains `-ota-` on the source, destination, and + every intermediate node. The `-ota-` stamp confirms that LoRa OTA is compiled into the build. Logging, + MQTT, and untagged builds cannot perform LoRa OTA; use WiFi or USB to replace them first. - A source node connected to the computer by USB serial. - Overlapping `tempradio` windows on the source, destination, and every repeater needed between them. @@ -65,7 +66,7 @@ Put the application firmware in a working directory, then build a full `.mota` c ```bash mkdir -p ./motas -motatool build --fw ./Heltec_v3_repeater-v1.16.05.bin --out-dir ./motas +motatool build --fw ./Heltec_v3_repeater-ota-v1.16.05.bin --out-dir ./motas motatool verify ./motas/*.mota ``` @@ -164,7 +165,7 @@ check fails. On the source node, destination node, and every intermediate repeater, run: ```text -tempradio 909.950,125,5,5,120 +tempradio 909.950,250,5,5,120 ``` All participating nodes must use the same frequency, bandwidth, and spreading factor. Their time windows must @@ -241,7 +242,9 @@ 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. + has an active `tempradio 909.950,250,5,5,120` window. +- **The CLI says LoRa OTA is not included:** that firmware does not contain the LoRa OTA feature. + `tempradio` cannot enable it; install a supported `-ota-` repeater build over WiFi or USB first. - **The update is marked `[other hw]`:** it is for a different board or firmware role. Do not install it. - **An nRF52 node does not list a full update:** this is intentional. nRF52 accepts only an in-place delta. - **nRF52 reports no bootloader apply support:** install the exact-board in-place-delta OTAFIX bootloader diff --git a/docs/ota_user_guide.md b/docs/ota_user_guide.md index 6fbd5a4d6..7abcf7d72 100644 --- a/docs/ota_user_guide.md +++ b/docs/ota_user_guide.md @@ -4,15 +4,26 @@ This guide is for **node operators**: how to update your MeshCore device's firmw plain language. No cables, no programmer — your node can download a new firmware from a neighbour and install it. (For the technical wire format, see [the OTA protocol spec](ota_protocol.md).) -LoRa OTA is present only in standard, non-logging Keymind repeater, room-server, and sensor firmware. MQTT -bridge, logging, and roles without `tempradio` support exclude it. +LoRa OTA is present only in supported Keymind repeater build artifacts whose filename contains `-ota-`. +Use an `-ota-` build on the source, receiver, and every intermediate repeater. MQTT bridge, logging, +untagged, companion, room-server, sensor, and roles without `tempradio` support exclude LoRa OTA. OTA radio traffic is accepted, generated, and relayed only while `tempradio` is actually running on that node. Every source, receiver, and intermediate repeater must therefore have an overlapping temporary-radio window. -> **Is my node supported?** LoRa OTA firmware is available for supported **ESP32** boards and nRF52 -> repeater targets. Every nRF52 installation requires the OTAFIX bootloader built for that exact board; -> having an OTA-capable application image alone is not enough. Check the bootloader release for an exact -> board match before attempting an update. +The recommended temporary OTA settings use 250 kHz bandwidth, SF5, CR5, and a 120-minute window. For a +North American node currently configured for 909.950 MHz, run this on every participating node: + +```text +tempradio 909.950,250,5,5,120 +``` + +Use the node's current permitted regional frequency in place of `909.950` when necessary. + +> **Is my node supported?** Choose a supported repeater artifact carrying the `-ota-` filename stamp. +> LoRa OTA firmware is available for supported **ESP32** boards and nRF52 repeater targets. Every nRF52 +> installation also requires the OTAFIX bootloader built for that exact board; having an OTA-capable +> application image alone is not enough. Check the bootloader release for an exact board match before +> attempting an update. The following nRF52 repeater targets gained firmware-side LoRa OTA support in this release without losing their normal external-sensor support: diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index 584c6768b..e1984096f 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -67,6 +67,34 @@ static uint32_t _atoi(const char* sp) { return n; } +#if defined(ENABLE_OTA) +static bool commandTokenMatches(const char* command, const char* token) { + const size_t len = strlen(token); + return strncmp(command, token, len) == 0 && (command[len] == 0 || command[len] == ' '); +} + +static bool otaCommandNeedsTempRadio(const char* command) { + const char* action = command + 3; + while (*action == ' ') action++; + + return commandTokenMatches(action, "neighbors") + || commandTokenMatches(action, "nbrs") + || commandTokenMatches(action, "updates") + || commandTokenMatches(action, "ls") + || commandTokenMatches(action, "n") + || commandTokenMatches(action, "pull") + || commandTokenMatches(action, "get") + || commandTokenMatches(action, "download") + || commandTokenMatches(action, "announce") + || commandTokenMatches(action, "adv") + || commandTokenMatches(action, "folder on") + || commandTokenMatches(action, "folder off") + || commandTokenMatches(action, "fold on") + || commandTokenMatches(action, "fold off") + || commandTokenMatches(action, "dev announce"); +} +#endif + static bool parseRecentRepeaterGet(const char* config, int& page) { if (strncmp(config, "recent.repeater", 15) != 0) { return false; @@ -1945,20 +1973,27 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re sprintf(reply, "%s", _board->getManufacturerName()); #if defined(ENABLE_OTA) } else if (memcmp(command, "ota", 3) == 0 && (command[3] == 0 || command[3] == ' ')) { - mesh::ota::handle_ota_command(command, reply, *_board); - if (mesh::ota::ota_ctx().config_dirty) { // a policy/key changed via the CLI -> persist it - mesh::ota::OtaContext& c = mesh::ota::ota_ctx(); - _prefs->ota_autofetch = c.manager.autofetch(); - _prefs->ota_checkpoint_blocks = c.manager.checkpoint_blocks(); - _prefs->ota_advert_interval = c.manager.advert_mins(); - _prefs->ota_max_hops = c.manager.max_hops(); - _prefs->ota_autoinstall = c.autoinstall; - _prefs->ota_signer_count = c.allow.count(); - for (uint8_t i = 0; i < c.allow.count() && i < MAX_OTA_SIGNERS; i++) - memcpy(_prefs->ota_signers[i], c.allow.get(i), 32); - _callbacks->savePrefs(); - c.config_dirty = false; + if (!_callbacks->isTempRadioActive() && otaCommandNeedsTempRadio(command)) { + strcpy(reply, "LoRa OTA needs temp radio on every node. Run: tempradio 909.950,250,5,5,120"); + } else { + mesh::ota::handle_ota_command(command, reply, *_board); + if (mesh::ota::ota_ctx().config_dirty) { // a policy/key changed via the CLI -> persist it + mesh::ota::OtaContext& c = mesh::ota::ota_ctx(); + _prefs->ota_autofetch = c.manager.autofetch(); + _prefs->ota_checkpoint_blocks = c.manager.checkpoint_blocks(); + _prefs->ota_advert_interval = c.manager.advert_mins(); + _prefs->ota_max_hops = c.manager.max_hops(); + _prefs->ota_autoinstall = c.autoinstall; + _prefs->ota_signer_count = c.allow.count(); + for (uint8_t i = 0; i < c.allow.count() && i < MAX_OTA_SIGNERS; i++) + memcpy(_prefs->ota_signers[i], c.allow.get(i), 32); + _callbacks->savePrefs(); + c.config_dirty = false; + } } +#else + } else if (memcmp(command, "ota", 3) == 0 && (command[3] == 0 || command[3] == ' ')) { + strcpy(reply, "LoRa OTA is not included in this build; tempradio cannot enable it. Use an OTA-enabled repeater firmware"); #endif } else if (memcmp(command, "sensor get ", 11) == 0) { const char* key = command + 11; diff --git a/src/helpers/CommonCLI.h b/src/helpers/CommonCLI.h index 0bcc68787..ad0a07ef9 100644 --- a/src/helpers/CommonCLI.h +++ b/src/helpers/CommonCLI.h @@ -397,6 +397,9 @@ public: virtual void saveIdentity(const mesh::LocalIdentity& new_id) = 0; virtual void clearStats() = 0; virtual void applyTempRadioParams(float freq, float bw, uint8_t sf, uint8_t cr, int timeout_mins) = 0; +#if defined(ENABLE_OTA) + virtual bool isTempRadioActive() const { return false; } +#endif virtual void addScheduledRadioParams(bool temporary, float freq, float bw, uint8_t sf, uint8_t cr, uint32_t start_time, uint32_t end_time, char* reply) { (void)temporary;