From d4ab2c8835e4540cb54b1c7bf5c5b6e35bd754ca Mon Sep 17 00:00:00 2001
From: mikecarper <mikecarper@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:32:14 +0000
Subject: [PATCH] deploy: d66b9336a96453f9ae496fe178a822a362fd8207

---
 radio_chirp_math_validation/index.html   |  5 ++-
 radio_dwell_policy_validation/index.html |  3 ++
 radio_profiles/index.html                | 54 +++++++++++++++---------
 search/search_index.json                 |  2 +-
 4 files changed, 41 insertions(+), 23 deletions(-)

diff --git a/radio_chirp_math_validation/index.html b/radio_chirp_math_validation/index.html
index aeafb303a..e6e4aaae4 100644
--- a/radio_chirp_math_validation/index.html
+++ b/radio_chirp_math_validation/index.html
@@ -3042,11 +3042,14 @@
 <h1 id="shared-radioradio2-chirp-timing-and-preamble-warnings">Shared radio/radio2 chirp timing and preamble warnings</h1>
 <p>Historical validation record: the nominal 600 us policy described below has
 been replaced by the activation self-test and 10% guarded measured budget.
+The later automatic policy also removed the pair-specific 88-symbol SF8/500
+floor and the fixed 300 us loop allowance; the older calculations below remain
+as test history.
 See <a href="../radio_profiles/#preamble">radio profiles</a> for
 current behavior.</p>
 <p>Implemented in the <code>keymindCascade</code> working tree, 2026-09-14. The initial
 4.1/4000-us implementation record below is retained as history; the
-<a href="#automatic-46-chirp--300-us-policy-update">4.6/300-us policy update</a> is now current.
+<a href="#automatic-46-chirp--300-us-policy-update">4.6/300-us policy update</a> was a prior stage.
 No radios were flashed or RF experiments started for either function-only change.</p>
 <h2 id="initial-implementation-scope">Initial implementation scope</h2>
 <ul>
diff --git a/radio_dwell_policy_validation/index.html b/radio_dwell_policy_validation/index.html
index c2598331d..58476c374 100644
--- a/radio_dwell_policy_validation/index.html
+++ b/radio_dwell_policy_validation/index.html
@@ -2998,6 +2998,9 @@
 <h1 id="automatic-dwell-policy-46-chirps-on-both-profiles">Automatic dwell policy: 4.6 chirps on both profiles</h1>
 <p>Historical validation record: the nominal 600 us switch allowance below has
 been replaced by the activation self-test and a 10% guarded measured budget.
+The current automatic policy also removed the fixed 300 us loop allowance and
+the pair-specific SF8/500 88-symbol floor. Values below are retained as bench
+history, not current automatic defaults.
 See <a href="../radio_profiles/#preamble">radio profiles</a> for current behavior.</p>
 <p>The shared <code>RadioProfiles</code> function uses a 4.6-symbol minimum for both logical
 profiles of one physical transceiver, rounded upward to a whole microsecond.
diff --git a/radio_profiles/index.html b/radio_profiles/index.html
index 8d5099959..cb72c0518 100644
--- a/radio_profiles/index.html
+++ b/radio_profiles/index.html
@@ -3543,9 +3543,11 @@ profile</strong>, then spends the remaining budgeted time on the faster profile,
 also with a <strong>4.6-symbol floor</strong>. Slower
 means a longer LoRa symbol (<code>2^SF / bandwidth</code>), regardless of profile number.
 The slower preamble sets the return deadline. The calculation allows two slow
-visits within that preamble, reserving the self-tested switch time per hop and 0.3 ms of main-loop
-margin. Fast-channel transmit preambles include sixteen acquisition symbols.
-For a primary SF7 / 62.5 kHz profile with a <em>measured</em> 600 us guarded switch allowance:</p>
+visits within that preamble, reserving the self-tested, 10%-guarded switch time
+per hop. There is no extra fixed main-loop allowance. Fast-channel transmit
+preambles include sixteen acquisition symbols.
+For a primary SF7 / 62.5 kHz profile with a 763 us measured maximum switch
+(840 us after the 10% guard, from the BLE-on T1000-E trial):</p>
 <table>
 <thead>
 <tr>
@@ -3564,7 +3566,7 @@ For a primary SF7 / 62.5 kHz profile with a <em>measured</em> 600 us guarded swi
 </tr>
 <tr>
 <td>SF8 / 500 kHz</td>
-<td style="text-align: right;">88</td>
+<td style="text-align: right;">40</td>
 <td style="text-align: right;">64</td>
 <td style="text-align: right;">32</td>
 </tr>
@@ -3577,18 +3579,17 @@ For a primary SF7 / 62.5 kHz profile with a <em>measured</em> 600 us guarded swi
 </tbody>
 </table>
 <p>With preamble 32 on that slower profile, its visit is 9.421 ms and the faster
-visit is 21.847 ms, plus the actual switching time. Increasing the slow preamble
+visit is 21.667 ms, plus the actual switching time. Increasing the slow preamble
 also increases the time available on the fast channel. If the symbols are equal
 in length, the primary profile goes first. Detected packets hold the current
 channel until reception finishes.</p>
-<p>The SF8 / 500 kHz value also retains the measured 88-symbol floor from the
-production V4/XIAO tests, where 72 and 80 each missed a packet.
-The explicit values come from the
-<a href="../radio_profiles_validation/">production validation</a>: the final fast-channel
-attempts each received 50/50 packets at 4.8 slow symbols. Automatic values use
-the switching and loop-jitter allowances below.
+<p>The SF8 / 500 kHz value is calculated from the same formula as every other
+profile; the older pair-specific 88-symbol floor has been removed. The explicit
+values come from <a href="../radio_profiles_validation/">historical production validation</a>:
+the final fast-channel attempts each received 50/50 packets at 4.8 slow symbols.
+Automatic values use the measured switch allowance below.
 Those explicit-preamble tests used the older 4.8-symbol policy; they do not
-validate the new 4.6-symbol slow dwell / 0.3 ms reserve. The
+validate the newer 4.6-symbol slow dwell. The
 <a href="../radio_dwell_policy_validation/#hardware-context">4.6/0.3 ms two-profile bench</a> received 197/200
 at SF7/62.5 + SF8/500 with explicit 32-symbol preambles. The newer four-channel
 5.1/6.1/7.7 tests also had misses, so this is a timing policy, not a claim of zero packet loss.
@@ -3601,10 +3602,22 @@ receiver's setting does not lengthen packets sent by other nodes.</p>
 <p><code>get radio2.timing</code> (alias <code>get radio.timing</code>) reports the active pair in
 <code>radio,radio2</code> order: dwell in chirps, recommended preambles in symbols, and
 the switching/loop allowances. Before calibration it reports <code>timing self-test
-pending</code> and the provisional preambles. For SF7/62.5 on <code>radio</code> and SF7/500 on
-<code>radio2</code> after a 600 us guarded measurement:</p>
-<pre><code class="language-text">&gt; chirps=4.60,85.34; need=32,64; switch=600us; loop=300us (estimate); test=4/4,4/4 ready; WARN recommended preamble: radio2=64
+pending</code> and the provisional preambles. On the T1000-E, the Full Companion now
+uses RTC2 for both retune timing and scan visits (about 31 us resolution).
+Previously, the nRF52 <code>micros()</code> fallback counted 1,024 Hz RTOS ticks: a real
+sub-millisecond retune could be reported as exactly 977 us, and two ticks as
+1,953 us. Those old numbers are timer artifacts, not measured RF costs.
+For SF7/62.5 on <code>radio</code> and SF8/500 on <code>radio2</code>, one live BLE-on read returned:</p>
+<pre><code class="language-text">&gt; chirps=4.60,42.84; need=32,40; switch=706us; loop=0us; test=4/4,4/4 ready; WARN recommended preamble: radio2=40
 </code></pre>
+<p>Later good hops in another BLE-on trial raised the measured maximum to 763 us
+(840 us with the 10% guard); the recommendation stayed at 40 symbols.</p>
+<p>The measured switch duration is wall time, so an interrupt during the hop is
+included. Bluetooth's SoftDevice may still preempt application code; this
+clock correction does not stop it. Ordinary Companion/USB work in the main
+loop does not run inside the synchronous retune, but it can delay when the
+next scan visit begins. The zero fixed loop allowance is not a guarantee of
+lossless reception under arbitrary application load.</p>
 <p><code>WARN recommended preamble</code> identifies <strong>each</strong> profile whose recommendation
 exceeds the standard 32 symbols or its explicitly selected value. For example,
 with SF7/62.5 on the primary profile, <code>set radio2 910.5,500,7,5,rx,32</code>
@@ -3637,14 +3650,13 @@ Using microseconds throughout:</p>
 slow = profile with the longer T (radio wins ties)
 L[slow] = max(requested_visit_us[slow], ceil(4.6 * T[slow]))
 L[fast] = max(requested_visit_us[fast], ceil(4.6 * T[fast]))
-O    = 2 * switch_us + loop_margin_us
+O    = 2 * switch_us
 C    = L[radio] + L[radio2] + O
 
 P[slow] = round_up_to_8(max(32, 2 * C / T[slow]))
 P[fast] = round_up_to_8(max(32, (L[slow] + O) / T[fast] + 16))
 </code></pre>
-<p>The previous SF8/500 versus SF7/62.5 measured 88-symbol floor remains in force.
-Automatic selection uses the minimum visits to choose a preamble, then allocates
+<p>Automatic selection uses the minimum visits to choose a preamble, then allocates
 the fast visit from half the slow preamble's duration. Diagnostics feed the
 actual allocated visits back into the same function, including longer visits
 caused by an explicit slow preamble. Too-short slow preambles that cannot fit
@@ -3655,10 +3667,10 @@ fast_dwell = max(ceil(4.6 * T[fast]),
                  floor(P_configured[slow] * T[slow] / 2 - slow_dwell - O))
 </code></pre>
 <p>For the tested SF7/62.5 + SF8/500 pair with slow preamble 32, this yields
-9,421 us slow and 21,847 us fast (42.67 fast chirps). Swapping <code>radio</code> and
-<code>radio2</code> swaps the allocations automatically. The 0.3 ms reserve is not a sleep.</p>
+9,421 us slow and 21,197 us fast (41.40 fast chirps) with the 1,075 us guarded
+switch allowance above. Swapping <code>radio</code> and <code>radio2</code> swaps the allocations automatically.</p>
 <p>Production scheduling and automatic preambles use the <strong>self-tested maximum
-successful switch plus 10%</strong>, together with 300 us per cycle. Subsequent
+successful switch plus 10%</strong>, without an additional fixed loop allowance. Subsequent
 successful hops can only raise that allowance until the next profile change.
 The measured recommendation is rounded up to eight symbols and capped at 128
 for automatic settings. The calculator and warnings retain the <em>uncapped</em>
diff --git a/search/search_index.json b/search/search_index.json
index a4b5886d6..92b4b0c67 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Introduction","text":"<p>Welcome to the MeshCore documentation.</p> <p>Below are a few quick start guides.</p> <ul> <li>1.17.1.5 Markdown audit</li> <li>1.17.1.5 USA Cascade release</li> <li>Feature switches by role: Companion, Repeater, Room Server, Sensor</li> <li>USB web console</li> <li>Full Companion feature switches</li> <li>Frequently Asked Questions</li> <li>Firmware Picker</li> <li>Temporary Radio Test Command Generator</li> <li>CLI Commands</li> <li>LoRa CLI Host Service</li> <li>Filter Policy Playground</li> <li>Telemetry Decoder</li> <li>Management Report Decoder</li> <li>CLI Availability by Firmware Build</li> <li>Classic ESP32 image memory budget</li> <li>Full Companion contact caches and capacity trials</li> <li>Easy LoRa OTA: ESP32 and nRF52 firmware updates</li> <li>Scripted LoRa OTA: Bash and PowerShell</li> <li>nRF52 repeater OTA with external QSPI</li> <li>nRF52 bootloader updates over LoRa</li> <li>MeshTower V2 microSD self-updates</li> <li>GPS Tracking</li> <li>Companion Protocol</li> <li>Companion Offline Message Queue</li> <li>Full Companion: ESP32 and nRF52</li> <li>Full Companion USB CLI and binary switcher</li> <li>Packet Format</li> <li>QR Codes</li> </ul> <p>If you find a mistake in any of our documentation, or find something is missing, please feel free to open a pull request for us to review.</p> <ul> <li>Documentation Source</li> </ul>"},{"location":"WiFi/","title":"WiFi and MQTT by Firmware Type","text":"<p>MeshCore itself does not require WiFi or the internet. LoRa packet exchange, repeating, room servers, companions, and sensors can all operate without either. WiFi is added by particular ESP32 firmware targets for one or more of these purposes:</p> <ul> <li>a TCP connection between a WiFi companion and a phone or computer;</li> <li>the WebConfig browser interface;</li> <li>MQTT uplinking from the radio to internet or LAN brokers;</li> <li>WiFi-assisted OTA services on builds that include them;</li> <li>ESP-NOW bridging, which uses the ESP32's 2.4 GHz radio but is not a connection   to a WiFi access point.</li> </ul> <p>The firmware role and the build profile are separate choices. USB logging does not itself provide MQTT. MQTT-capable Full Companions include that feature without <code>mqtt</code> in their filename; check the artifact capability manifest. See feature switches by role for the different Companion and infrastructure controls and the USB web console.</p>"},{"location":"WiFi/#quick-reference","title":"Quick reference","text":"Firmware target or role Infrastructure WiFi MQTT What WiFi does <code>*_repeater</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_repeater_observer_mqtt</code> Yes Yes Uplinks heard and selected transmitted LoRa packets; repeating remains enabled by default <code>*_room_server</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_room_server_observer_mqtt</code> Yes Yes Runs the room server and uplinks radio traffic <code>*_companion_radio_wifi</code> Yes No Exposes the MeshCore companion protocol on TCP port 5000 <code>*_companion_radio_wifi_mqtt</code> Yes Yes Runs both the TCP companion interface and the MQTT uplink <code>*_companion_radio_full*</code> ESP32, subject to board/transport selection Where compiled on ESP32 Includes supported USB/wireless transports; configure MQTT through WebConfig Dedicated USB, BLE, or serial companion (not Full) No No Uses the transport named by the target instead <code>*_repeater_bridge_espnow</code> Build-dependent on ESP32 No Uses ESP-NOW for its bridge; <code>bridge.format wrapped|raw</code> selects legacy bridge framing or primary-ESP-NOW compatibility; a FULL build also exposes the TCP 5001 LoRa-OTA seeder whenever WiFi is usable RS232 bridge No No Bridges through a serial interface Ethernet repeater/room server No WiFi No Uses wired Ethernet for its role-specific network interface <code>*_sensor</code> Build-dependent on ESP32 No A FULL ESP32 sensor can expose the TCP 5001 LoRa-OTA seeder through its browser-OTA setup AP Terminal-chat or KISS modem No in current targets No Uses LoRa and its role-specific local interface <code>*_lora_ota_no_external_sensors</code> On demand on ESP32 No Lean LoRa-OTA repeater image; ESP32 builds retain the compact <code>start ota</code> browser uploader <p>Direct on-device WiFi and MQTT are currently ESP32 features. nRF52, STM32, and the currently enabled RP2040 targets do not run this MQTT bridge. An nRF52 connected to a Raspberry Pi can still be logged or uplinked by software on the Pi, but that is a separate host-side bridge rather than MQTT running in the radio firmware.</p>"},{"location":"WiFi/#how-the-mqtt-bridge-works","title":"How the MQTT bridge works","text":"<p>The MQTT bridge is an outbound observer. It does not subscribe to MQTT topics and does not inject broker messages into LoRa.</p> <p>For a received packet, the flow is:</p> <pre><code>LoRa radio -&gt; successful packet parse -&gt; MQTT capture queue -&gt; broker slots\n                                  \\----&gt; normal MeshCore filtering/handling\n</code></pre> <p>Packets transmitted by the node can also be queued according to <code>mqtt.tx</code>. Receive capture happens before the packet is passed to the normal MeshCore flood filters and forwarding decision. A packet may therefore be observed on MQTT even when a later scope, path, region, duplicate, or repeat rule prevents the node from forwarding it over LoRa.</p> <p>On infrastructure observer builds, MQTT publication and LoRa repetition are separate:</p> <ul> <li><code>set repeat on|off</code> controls whether an observer repeats eligible LoRa   packets;</li> <li><code>set mqtt.enabled on|off</code> starts or stops MQTT and preserves broker settings;</li> <li><code>set mqtt.rx on|off</code> controls uplinking of received packets;</li> <li><code>set mqtt.tx off|advert|on</code> controls uplinking of transmitted packets.</li> </ul> <p>Fresh MQTT observer settings are:</p> <ul> <li>bridge and repeating enabled;</li> <li>received packet uplinking enabled;</li> <li>transmitted packet uplinking set to <code>advert</code>, meaning only the node's own   adverts are included;</li> <li>packet and status publishing enabled;</li> <li>raw publishing disabled;</li> <li>slot 1 set to <code>analyzer-us</code>;</li> <li>slot 2 set to <code>analyzer-eu</code>;</li> <li>slots 3 through 6 disabled;</li> <li>WiFi modem power saving set to <code>min</code> in the Cascade profile and <code>none</code> in   target-default builds;</li> <li>WiFi SSID and IATA code empty.</li> </ul> <p>Up to six broker configurations can be saved. The number that can be active at once depends on the target and available memory. A non-PSRAM ESP32 should normally use no more than two TLS/WSS brokers; some classic ESP32 targets are reliable with only one. Excess configured slots remain saved but show as inactive in <code>get mqtt.status</code>.</p> <p>The bridge has a bounded packet queue for broker or WiFi outages and reconnects automatically. A non-PSRAM build holds 6 packets and a PSRAM build holds 50. When the queue is full, the oldest item is replaced; after five minutes with no broker connected, stale queued packets are flushed. MQTT packet delivery is best effort rather than durable storage. Each enabled slot publishes independently, so one failed broker does not intentionally stop the other slots.</p> <p>See MQTT_IMPLEMENTATION.md for the complete preset list, custom broker configuration, topic formats, authentication, diagnostics, and memory limits.</p>"},{"location":"WiFi/#mqtt-observer-setup","title":"MQTT observer setup","text":"<p>Most full-size ESP32 MQTT observer builds have the shared WebConfig portal. On a fresh device with no saved SSID:</p> <ol> <li>Join the open <code>MeshCore-Setup-XXXX</code> access point.</li> <li>If the captive page does not open, browse to <code>http://192.168.4.1/</code>.</li> <li>Enter WiFi, radio, identity, and MQTT settings.</li> <li>Select Save &amp; Reboot.</li> <li>After reboot, check <code>get wifi.status</code> and <code>get mqtt.status</code>.</li> </ol> <p>The setup AP is unauthenticated unless the firmware was built with <code>WEBCONFIG_AP_PASSWORD</code>. It uses plain HTTP, so provision it in a trusted location. When WebConfig is running on the normal LAN, repeater and room-server builds require the node's admin password.</p> <p>On an expanded FULL profile with no saved SSID, this automatic setup AP has an absolute 30-minute window. Browser activity or a phone left associated with the AP does not extend it. If no SSID has been saved when the window expires, WebConfig closes and the ESP32 WiFi radio remains off automatically for the remainder of that boot. A reboot or power cycle starts a new 30-minute setup window; the timeout is deliberately not written to preferences. An administrator can still override the automatic cutoff with an explicit <code>start webconfig</code> command.</p> <p>Once an SSID is saved, the provisioning cutoff no longer applies. When WiFi is selected by <code>logging.output wifi|both</code>, the station stays enabled and keeps trying the saved network indefinitely: ESP automatic reconnect remains on and the explicit fallback advances through 15, 30, 60, 120, then 300-second retry intervals, remaining at five minutes until it reconnects. MQTT broker retries use their own backoff; a repeatedly failing broker eventually receives one probe every 30 minutes. Selecting <code>logging.output off|usb</code> keeps the MQTT bridge off, so saved credentials alone do not force WiFi on unless WebConfig is also enabled explicitly.</p> <p>The equivalent MQTT observer CLI setup is:</p> <pre><code>set wifi.ssid Your WiFi Name\nset wifi.pwd Your WiFi Password\nset mqtt.iata SEA\nset name MyObserver\nreboot\n</code></pre> <p>The SSID and password values are the rest of the command line. Spaces are allowed and quotes must not be added. SSIDs may contain at most 31 characters and passwords at most 63. Leave the password value empty for an open network.</p> <p>Useful checks are:</p> <pre><code>get wifi.ssid\nget wifi.status\nget wifi.powersave\nget wifi.cli\nget mqtt.enabled\nget mqtt.rx\nget mqtt.tx\nget mqtt.status\nget mqtt1.diag\nget mqtt2.diag\n</code></pre> <p>To change a configured observer through WebConfig without leaving the portal enabled after every reboot:</p> <pre><code>start webconfig\n</code></pre> <p>This uses the LAN when WiFi is connected. To force the setup AP, the MQTT bridge must release WiFi first:</p> <pre><code>set mqtt.enabled off\nstart webconfig ap\n</code></pre> <p>After provisioning, use Save &amp; Reboot, or stop the temporary portal and restart the bridge:</p> <pre><code>stop webconfig\nset mqtt.enabled on\n</code></pre> <p>Current MQTT observer artifacts use the expanded FULL partition profile so WebConfig and the complete role CLI are retained. Install the matching merged image over USB once when moving a device from the legacy partition layout.</p>"},{"location":"WiFi/#wifi-companion-setup","title":"WiFi companion setup","text":"<p>A <code>*_companion_radio_wifi</code> build replaces the BLE or USB companion link with the MeshCore companion protocol over TCP port 5000. The phone or computer must be able to reach the device on the same LAN.</p> <p>Most ESP32 <code>*_companion_radio_full</code> targets keep all three Companion links at once: USB, BLE, and TCP port 5000. The two SenseCAP Indicator Full targets are the exception: USB remains available, while a saved next-boot selector starts exactly one secondary wireless Companion transport, either BLE or infrastructure WiFi/TCP. On the ESP-NOW Indicator, this selector never stops the primary ESP-NOW mesh radio. Full ESP32 images also provide a source-only LoRa mOTA service on ports 5001 and 5002 whenever their WiFi transport is active. See the full Companion guide for its build, terminal mode, and complete update-source workflow.</p> <p>The LilyGo T-Beam 1W Full Companion maps one press of the physical <code>BOOT</code> button (GPIO0) to a persistent WiFi on/off toggle. Turning WiFi off closes WebConfig, Companion TCP, mOTA, and MQTT network services while USB, BLE, the display, GPS, and LoRa remain available. Another BOOT press turns WiFi back on even after reboot. WiFi/WebConfig starts first; BLE starts two seconds later so the ESP32-S3 can reserve the setup server's internal heap before both radios run together.</p> <p>The companion loads runtime credentials saved in NVS. A non-placeholder compile-time <code>WIFI_SSID</code>/<code>WIFI_PWD</code> can be used as a first-boot fallback, but saved credentials take priority. With no credentials, its WebConfig portal starts in setup-AP mode. With credentials, the WebUI is enabled by default on the station IP.</p> <p>Full Companion can also be provisioned from its USB terminal or TCP port 5002:</p> <pre><code>get wifi.ssid\nget wifi.status\nset wifi.ssid SlowFi\nset wifi.pwd your-password\n</code></pre> <p>Credential writes are persisted immediately. After the reply has drained, the Companion restarts its WiFi station with the saved pair. A port-5002 client is expected to disconnect and can reconnect at the new LAN IP. USB masks the password as it is entered; <code>get wifi.pwd</code> is intentionally unavailable. The standalone credential store accepts an empty password, ordinary passphrases up to 63 characters, or an exact 64-character hexadecimal WPA/WPA2 PSK. A non-hexadecimal 64-character value and every longer value are rejected.</p> <p>After the saved station first connects following boot, every ESP32 WiFi Companion requests a fresh UTC time from NTP. A verified reply updates both the MeshCore clock and any detected hardware RTC; the next explicit refresh is due 24 hours after that success. A failed request times out without blocking the radio loop and retries after five minutes. While WiFi is disconnected or only the setup AP is available, the request waits for a station connection. Builds with a configured MQTT bridge use its boot-and-daily NTP owner instead, so two firmware services never reconfigure the ESP32 SNTP client at the same time. A later WiFi reconnect does not add another successful-sync request; it preserves the existing 24-hour deadline. Until a fresh internet reply succeeds, LoRa clock consensus remains available as the fallback.</p> <p>On Full Companion targets whose primary mesh radio is ESP-NOW, ESP-NOW, the setup AP, and the infrastructure-WiFi station must share one 2.4 GHz channel. The persisted channel defaults to 1 and can be inspected or changed from the text terminal:</p> <pre><code>get espnow.channel\nset espnow.channel 6\nreboot\n</code></pre> <p>Valid values are 1 through 13; use only a channel permitted in your region and supported by the router. <code>set espnow.channel</code> saves the new value but does not move the running radio; reboot the node to apply it. Every primary ESP-NOW node that should communicate with it must use the same channel, and the configured router's 2.4 GHz radio must be fixed to that channel as well. A router left on automatic channel selection can move the infrastructure connection away from the ESP-NOW mesh.</p> <p><code>espnow.channel</code> configures the node's primary ESP-NOW mesh radio. It is distinct from <code>bridge.channel</code>, which applies only to the separate ESP-NOW bridge feature. WiFi power saving does not let ESP-NOW and infrastructure WiFi operate on different channels. On an ESP32 Full build whose primary radio is ESP-NOW, <code>wifi.powersave max</code> is unavailable because a station using maximum modem sleep can miss ESP-NOW broadcasts; use <code>min</code> for coexistence. The primary mesh transport holds the driver's RF wake reference continuously, so <code>min</code> does not suspend its ESP-NOW receiver.</p> <p>ESP-NOW compatibility also depends on the bytes and PHY used above the common Espressif transport. The historical <code>*_repeater_bridge_espnow</code> firmware wraps each MeshCore packet with a magic value, checksum, and secret-based XOR, while <code>Generic_ESPNOW</code> and <code>SenseCapIndicator-ESPNow</code> send the serialized MeshCore packet directly using the ESP-NOW LR PHY. Updated bridge firmware can select either behavior without changing the board target:</p> <pre><code>get bridge.format\nset bridge.channel 1\nset bridge.format raw\n</code></pre> <p>On a Heltec V4, the ordinary <code>companion_radio_full</code> image remains a LoRa-primary Companion and does not instantiate this bridge. Select and flash the existing <code>heltec_v4_repeater_bridge_espnow</code> role before using these commands. Treat that Companion-to-repeater change as a role/partition migration: back up the node and use the exact V4 merged install artifact.</p> <p><code>wrapped</code> remains the default and interoperates with existing bridge nodes that use the same channel and <code>bridge.secret</code>. <code>raw</code> interoperates with primary-ESP-NOW nodes and other raw bridges; it requires channel 1-13, enables LR reception, forces LR transmission, and ignores <code>bridge.secret</code>. Receive parsing is strict to the selected format, so migrate peers deliberately rather than expecting one bridge to accept both. Match <code>bridge.channel</code> on the LoRa gateway to the primary nodes' <code>espnow.channel</code>; a primary-node channel change takes effect after its reboot.</p> <p>Raw mode retains MeshCore's normal packet parsing, authentication/encryption, and the bridge's duplicate suppression, but it does not provide the wrapper's secret-based network isolation. That XOR wrapper is itself only lightweight isolation, not cryptographic security. Multiple LoRa/ESP-NOW gateways covering the same nodes can temporarily amplify duplicates, even though seen-packet tracking prevents an individual bridge from immediately echoing a packet back.</p> <p>If the configured network remains unavailable for two minutes, the companion opens its setup AP so the credentials can be repaired. It continues retrying the saved network. WiFi modem sleep has its own persisted <code>wifi.powersave</code> setting and is independent of the Companion device power-saving setting. The WiFi card in Companion WebConfig exposes <code>none</code>, <code>min</code>, and <code>max</code>. Fresh Cascade-profile builds select <code>min</code>; target-default builds select <code>none</code>. A saved setting takes precedence after an upgrade.</p> <p>WiFi-only Companions can use all three modes. A Full Companion that runs WiFi and BLE simultaneously requires at least minimum modem sleep. It reports <code>min</code> when an old or target-default <code>none</code> value is found and rejects a new <code>none</code> selection. When ESP-NOW is also the primary mesh radio, <code>max</code> is unavailable: the access point does not buffer ESP-NOW broadcasts for a sleeping station, so maximum modem sleep can lose them. Firmware caps a previously saved <code>max</code> value to and reports it as <code>min</code>, and rejects a new <code>max</code> selection.</p> <p>The SenseCAP Indicator Full targets select BLE or infrastructure WiFi instead of running both. On a WiFi-selected boot, the LoRa layout accepts <code>none|min|max</code>, while the ESP-NOW layout accepts <code>none|min</code> and still rejects <code>max</code>. On a BLE-selected boot infrastructure WiFi is off; the LoRa layout accepts <code>min|max</code> for the saved WiFi setting, while ESP-NOW + BLE requires <code>min</code>. Device power saving remains independent of this modem policy.</p> <p>WiFi companions do not have the repeater/room-server admin CLI password model, so their LAN WebConfig page is intentionally unauthenticated. Use them only on a trusted LAN.</p> <p>The WebConfig Advanced card exposes device power saving on WiFi Companion, repeater, and room-server builds. It also exposes RX power saving on radio chips that support receive duty cycling. RXPS can select continuous receive, levels 1-10, automatic or explicit 16/32-symbol timing assumptions, or manual receive/sleep windows. The timing assumption does not change the radio's actual wire preamble. The WebConfig WiFi card exposes WiFi modem power saving. All three settings are persisted across reboots.</p> <p>The three settings are independent. A WiFi Companion keeps its transports available while device power saving reduces CPU and GPS idle power. An infrastructure node can sleep when device power saving is enabled, so its WiFi services may be temporarily unavailable. RXPS only duty-cycles the LoRa receiver. Fresh Cascade-profile builds default to device power saving on, RXPS on at level 8 with a 16-symbol preamble, and WiFi modem power saving at <code>min</code> on every build that includes ESP32 WiFi. The RXPS preamble value is a saved timing assumption, not the wire length: starting with v1.17.1.5, SF5-SF8 packets normally use a 32-symbol physical preamble. Firmware selects 64 for the whole SF/BW tuple only when 32 cannot enable RXPS at any level and 64 can (SF5/BW250 and SF6/BW500), then 128 only when neither shorter length works (SF5/BW500).</p> <p>When <code>ENABLE_OTA</code> is included, a WiFi companion also listens on:</p> <ul> <li>TCP 5001 for the OTA folder seeder used by <code>motatool serve --tcp</code>;</li> <li>TCP 5002 for a text management console.</li> </ul> <p>These ports do not replace the companion protocol on TCP 5000. On a <code>companion_radio_full</code> build, port 5002 is the same role-specific text terminal available over USB, including chat, remote administration, radio and power settings, WiFi/WebConfig management, <code>tempradio</code>, and the source-only <code>ota</code> commands. Other OTA-enabled Companion builds expose the same local maintenance commands as binary command <code>0x42</code>, plus <code>ota ...</code> commands. LoRa staging and installation on the Full Companion itself remain disabled.</p> <p>Port 5002 is plaintext and has no independent login gate. Use it only on a trusted LAN or temporary setup network, especially when entering a remote-node admin password with the terminal's <code>login</code> command.</p> <p>FULL ESP32 builds share the port 5001 folder seeder. It starts whenever that role has a usable WiFi station or setup access point and stops when WiFi stops. For example, a FULL repeater can run <code>start webconfig</code> to join its saved network, then accept:</p> <pre><code>motatool serve --dir ./motas --tcp &lt;repeater-ip&gt;:5001 -v\n</code></pre> <p>The TCP connection supplies <code>.mota</code> files for the node to advertise and relay over LoRa; it is not a raw <code>.bin</code> uploader. <code>start ota</code> continues to provide the direct browser uploader on HTTP port 80. A FULL role without WebConfig but with browser OTA support can use the <code>MeshCore-OTA</code> access point raised by <code>start ota</code>; its seeder address is <code>192.168.4.1:5001</code>.</p> <p>Only one external folder link can be active. A TCP client is rejected while <code>ota folder on</code> is using USB serial, and disconnecting <code>motatool</code> automatically removes the TCP folder. Port 5001 has no login layer, so expose it only on a trusted LAN or temporary setup network. Firmware target and hash checks still apply at the receiving node, along with its configured signature/trust policy.</p> <p>When the shared seeder is running, <code>get wifi.status</code> appends its live state:</p> <pre><code>OTA TCP 5001: listening\nOTA TCP 5001: client connected\n</code></pre> <p>The first state means WiFi is usable and the node is waiting for <code>motatool serve --tcp</code>. The second means a <code>motatool</code> folder is currently attached and available for LoRa OTA service.</p>"},{"location":"WiFi/#wifi-companion-with-mqtt","title":"WiFi companion with MQTT","text":"<p>A <code>*_companion_radio_wifi_mqtt</code> build combines both systems:</p> <ul> <li>the companion protocol remains available to the phone/computer on TCP 5000;</li> <li>the same WiFi station connection is shared with the MQTT bridge;</li> <li>received and selected transmitted LoRa packets can be published to the   configured MQTT slots.</li> </ul> <p>The companion owns WiFi connection and recovery in this build. The MQTT bridge waits for that connection rather than creating a second one. Stopping MQTT does not disable the TCP companion service.</p> <p>MQTT-capable Full Companions also combine these services. The WebConfig page contains MQTT settings, and the USB/TCP and browser terminals accept the same <code>mqtt.*</code> settings as infrastructure for shared features. Use <code>set mqtt.enabled on|off</code> to control MQTT without discarding broker settings. Use <code>set logging.output off|usb|wifi|both</code> to select both outputs together.</p>"},{"location":"WiFi/#webconfig-without-mqtt","title":"WebConfig without MQTT","text":"<p>Full-size ESP32 repeater and room-server builds can include WebConfig even when MQTT is absent. The portal then shows node, radio, and WiFi-related controls but removes the MQTT wizard step and MQTT tab.</p> <p>In this case WebConfig owns WiFi only while it is needed. Stopping the portal disconnects WiFi and turns the WiFi radio off. There is no persistent MQTT connection keeping WiFi active.</p> <p>Unified FULL USB + WiFi and FULL logging-fallback repeater/room-server builds both provide these CLI controls and status checks. The unified profile includes the MQTT bridge; the fallback is used only where no matching MQTT environment exists:</p> <pre><code>get wifi.ssid\nget wifi.status\nget wifi.powersave\nget wifi.cli\nget webui\nset wifi.ssid SlowFi\nset wifi.pwd your-password\nset wifi.powersave none\nset wifi.cli on\n</code></pre> <p><code>get wifi.status</code> distinguishes an unconfigured node, an inactive WiFi radio, a station connection attempt, the setup AP, a connection failure, and a working LAN connection. For a LAN connection it reports the SSID, IP address, and RSSI. If the shared OTA seeder is active, the same reply also reports whether TCP port 5001 is listening or has a <code>motatool</code> client attached. <code>get wifi.powersave</code> reports the saved standalone WebConfig setting as <code>none</code>, <code>min</code>, or <code>max</code>. An inactive status is normal when <code>webui</code> is off: run <code>start webconfig</code> to connect temporarily. Standalone credentials can be changed through WebConfig or with the listed CLI commands. Changing the SSID or password stops an active WebConfig session; start it again to connect with the new values. Use <code>set wifi.pwd</code> with no value for an open network. <code>get wifi.pwd</code> returns the saved password on a local connection; LoRa callers cannot read it. Standalone WiFi accepts ordinary passphrases up to 63 characters and exact 64-character hexadecimal WPA/WPA2 PSKs; other 64-character values and all longer values are rejected. MQTT observer WiFi passwords remain limited to 63 characters by their fixed persisted layout.</p> <p><code>get webui</code> starts with the saved boot setting, then reports the current session. For example, <code>&gt; off, http://192.168.1.130/</code> means automatic WebConfig startup is saved as off, but a temporary session started by <code>start webconfig</code> is currently active at that URL.</p>"},{"location":"WiFi/#webconfig-cli-terminal","title":"WebConfig CLI terminal","text":"<p>The terminal defaults to on. Enable or disable it from an existing admin CLI:</p> <pre><code>set wifi.cli on\nset wifi.cli off\nget wifi.cli\n</code></pre> <p>The saved <code>on</code> setting becomes active only when the WiFi station client is connected and WebConfig is running in LAN mode. It is never exposed on the open setup access point. When active, the WebConfig page has a CLI tab. Repeater and room-server commands use their local CLI after admin authentication. The browser can run <code>get password</code>, <code>get prv.key</code>, <code>erase</code>, <code>set freq</code>, <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code>, and explicit WiFi/MQTT credential getters. It also streams <code>get acl</code> and raw <code>log</code> dumps back to the browser. Log reads pause for slow clients and resume as output is read, using a fixed 160-byte file chunk. A dump snapshots the file length, so live logging cannot extend it indefinitely. The browser keeps the complete requested dump, including files larger than 64 KiB.</p> <p>Companion uses the same complete terminal as USB and Full Companion TCP port 5002, including <code>card</code>, <code>import meshcore://...</code>, <code>list</code>, <code>to</code>, messages, remote login, and delayed replies. It uses the Companion's trusted LAN. See Companion browser terminal for contact import, terminal ownership, and disconnect behavior.</p> <p>Type a command at the prompt, or paste multiple lines and confirm the sequence. Blank lines and comments are ignored. The device reports the supported batch limit. The browser sends each line after the previous command finishes and continues polling for incoming text after the sequence. <code>help</code> lists the device's actual terminal commands; Tab completes command names and settings.</p> <p>The up/down arrow keys recall commands entered during the current browser session. Commands available in the terminal still depend on the firmware role and build profile. Commands such as <code>stop webconfig</code>, <code>set wifi.cli off</code>, WiFi credential changes, and reboot operations stop the remaining block and can disconnect the page before it receives their final reply.</p>"},{"location":"WiFi/#build-profiles","title":"Build profiles","text":"<p><code>build.sh</code> produces several profiles. A profile changes the features compiled into a selected target; it does not change that target into another firmware role.</p> <p>This fork defaults every <code>build.sh</code> target to the USA Cascadia radio preset and the Cascade firmware profile. The script resolves the live <code>USA/Canada</code> entry by name, so its changing number in the downloaded menu does not affect builds. If the preset service is unavailable, it falls back to <code>910.525 MHz / BW62.5 / SF7 / CR5</code>. Use <code>--radio-preset target --profile default</code> only when a build intentionally needs the target's original radio and profile defaults. <code>--radio-preset usa-cascadia</code> is the stable explicit name; legacy numbered choices remain accepted but their meaning can change when the service reorders or adds presets.</p> Build profile WiFi/MQTT behavior Standard Uses the selected target's role. Where USB is a safe plaintext console, the same artifact embeds debug/packet logging behind persistent <code>get/set usb.logging</code>. Ordinary legacy-slot ESP32 repeater/room-server artifacts omit WebConfig when needed to fit. ESP32 MQTT observer and ESP-NOW bridge targets are automatically promoted to FULL; WiFi-companion targets keep their companion partition profile. Legacy logging No separate artifact is emitted; USB logging is part of the ordinary image. Logging output itself is not a direct MQTT uplink. MQTT Builds explicit MQTT observer or WiFi-companion-MQTT targets with USB packet logging off. Non-companion ESP32 MQTT observers always use FULL expanded partitions. FULL ESP32 USB + WiFi Uses the board's MQTT target with USB packet logging and direct WiFi MQTT together, expanded dual-OTA partitions, up to 254 neighbors, LoRa OTA, and full-size ESP32 features such as WebConfig where supported. <code>get/set logging.output off\\|usb\\|wifi\\|both</code> persists the active paths. Classic T-Beam MQTT observers retain their 50-entry table because their persistent discovery state exhausts internal DRAM at 254. FULL ESP32 logging fallback Uses the board's non-MQTT target only when no matching WiFi MQTT environment exists. It keeps debug and packet logging, expanded dual-OTA partitions, up to 254 neighbors, and LoRa OTA. Persistent <code>usb.logging off</code> also provides normal output-off operation, so ESP-NOW FULL roles need no second non-logging image. LoRa-OTA no-external-sensors A lean repeater image with no MQTT; ESP32 builds retain the compact on-demand browser WiFi uploader and up to 254 neighbors, subject to target RAM limits. <p>Repeater profiles use up to 254 neighbors. Selected Generic E22, Heltec V2, Meshadventurer, T-Beam OTA/MQTT, and TLora MQTT profiles use 50 to preserve internal-DRAM reserves. Consult the artifact capability manifest and ESP32 memory budget for the exact target.</p> <p>The interactive Option 1 FULL everything choice and the standalone FULL command select the unified USB + WiFi image when a matching MQTT target exists; otherwise they select the logging fallback. The build matrix no longer emits any separate standard logging image, or a non-MQTT FULL twin for a role covered by the unified image. Expanded Full infrastructure profiles include LoRa OTA, WebConfig where supported, up to 254 neighbors, and expanded dual-OTA partitions. Target-specific internal-DRAM limits still apply.</p> <p>FULL images change the ESP32 partition layout. Flash the matching <code>*-merged.bin</code> once when installing that layout. A partition-layout change can invalidate NVS, including saved WiFi, MQTT, name, and admin settings. Later updates using the same layout normally preserve them.</p>"},{"location":"WiFi/#wifi-power-behavior","title":"WiFi power behavior","text":"<p>MQTT observers and FULL standalone ESP32 repeater/room-server builds support:</p> <pre><code>set wifi.powersave none\nset wifi.powersave min\nset wifi.powersave max\n</code></pre> <p>Fresh Cascade-profile builds default to <code>min</code>; target-default builds use <code>none</code>, which gives the most predictable MQTT and radio performance at the highest power use. <code>min</code> and <code>max</code> reduce power but may add latency or reduce reliability on busy nodes. A saved operator setting takes precedence on an upgrade. ESP32 WiFi Companions expose the same values in their WebConfig WiFi card and USB text terminal. Full Companion also accepts the text commands from TCP port 5002. The normal binary Companion protocol can read or write the setting over USB, BLE, or TCP port 5000 without entering terminal mode. A Full Companion that runs BLE and infrastructure WiFi simultaneously rejects <code>none</code> because coexistence requires WiFi modem sleep. An ESP32 Full Companion whose primary mesh radio is ESP-NOW also rejects <code>max</code>; maximum modem sleep can cause the station to miss ESP-NOW broadcasts because the access point does not buffer them. A previously saved <code>max</code> value is capped to and reported as <code>min</code>. The SenseCAP Indicator exception uses the active-mode rules above rather than assuming BLE and infrastructure WiFi are active together. ESP-NOW and infrastructure WiFi still must use the same fixed channel.</p> <p>MQTT observer targets normally limit ESP32 WiFi transmit power to 11 dBm unless the board configuration overrides <code>MQTT_WIFI_TX_POWER</code>. This setting affects WiFi only, not LoRa transmit power.</p>"},{"location":"WiFi/#recognizing-the-wrong-firmware","title":"Recognizing the wrong firmware","text":"<p><code>get wifi.status</code>, <code>get wifi.ssid</code>, <code>get wifi.powersave</code>, and <code>get wifi.cli</code> are available on MQTT observers and on FULL non-MQTT repeater/room-server builds with WebConfig. ESP32 WiFi Companions also expose all four commands, credential setters, and <code>start webconfig [ap]</code> through their USB text terminal. Their browser CLI defaults to on in station/LAN mode. Full Companion also exposes its complete role-specific text terminal on TCP port 5002, including chat and streaming commands. MQTT commands such as <code>get mqtt.status</code> and <code>set mqtt1.preset ...</code> require MQTT code in the image, on Companion or infrastructure. Unknown settings return <code>Error: unknown setting: &lt;name&gt;</code>. Older firmware that used the discontinued compact CLI can instead report <code>Unsupported in this firmware</code> when a command was cut for space.</p> <p>Check the complete firmware filename and role. In particular:</p> <ul> <li><code>logging</code> does not mean MQTT;</li> <li><code>ota</code> does not mean MQTT;</li> <li><code>companion_radio_wifi</code> does not mean MQTT;</li> <li><code>observer_mqtt</code> and <code>wifi_mqtt</code> identify explicit MQTT targets, but Full   Companion can include MQTT without either marker; inspect its capabilities.</li> </ul> <p>Rolling firmware back does not restore settings erased by a full flash or a partition-table change. If the correct MQTT target still has no configuration, provision WiFi and MQTT again.</p>"},{"location":"WiFi/#troubleshooting","title":"Troubleshooting","text":"<p>For an MQTT observer:</p> <pre><code>get wifi.status\nget mqtt.enabled\nget mqtt.status\nget mqtt1.diag\nget mqtt2.diag\n</code></pre> <p>Common causes are:</p> <ul> <li>no saved SSID or a changed password;</li> <li>blank/invalid IATA for a preset that requires it;</li> <li>the bridge disabled;</li> <li>all MQTT slots disabled;</li> <li>too many TLS/WSS slots for the available internal memory;</li> <li>WiFi power saving being too aggressive;</li> <li>the wrong firmware role or an older compact-CLI build without WebConfig.</li> </ul> <p>For a WiFi companion, find its station IP in the router, connect the client to TCP port 5000, and use the open <code>MeshCore-Setup-XXXX</code> AP at <code>http://192.168.4.1/</code> if it cannot join the saved network. Current firmware normalizes both ESP32 WiFi interfaces to standard b/g/n before advertising the setup AP. Full Companion targets whose primary mesh radio is ESP-NOW use b/g/n+LR instead and keep the setup AP, infrastructure station, and mesh on the persisted <code>espnow.channel</code> (channel 1 by default). Their configured 2.4 GHz router and every other primary ESP-NOW node must use that same channel. MQTT-capable Companions also accept <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, and <code>get mqtt.status</code> in their USB/TCP and browser terminals. Extended slot and NTP diagnostics remain infrastructure features.</p>"},{"location":"cad_scan_validation/","title":"SX1262 channel-scanning hardware results","text":"<p>Hardware test on September 12, 2026 (America/Los_Angeles). Heltec V4 transmitter; XIAO ESP32-S3 with Wio SX1262 receiver. Both used standalone diagnostic firmware.</p> <p>The best tested scan setting was four channels with four-symbol RX-preamble windows. Three-symbol windows were unreliable even in the single-channel re-arm control. In the longer four-symbol runs, four channels received 80/80 packets, five received 79/80, and six received 52/60. These are measured limits of this implementation and test setup, not universal SX1262 channel-count limits.</p>"},{"location":"cad_scan_validation/#configuration-and-counting","title":"Configuration and counting","text":"<p>SF5, 125 kHz, coding rate 4/5, explicit header, payload CRC, and 32 preamble symbols. The programmed preamble is 8.192 ms. Channels start at 909.5 MHz and increase in 1 MHz steps; tests use the first N channels, up to 920.5 MHz. Test packets are transmitted individually with varied timing relative to the scanner. There are no overlapping transmitters in this experiment.</p> <p>A success requires a CRC-valid packet with the expected sequence, channel, length, and test payload. Every included transmission has its own successful transmitter acknowledgement; delayed serial acknowledgements are recovered by sequence, without retransmitting. The one exploratory RX scan trial with shifted acknowledgements is excluded.</p>"},{"location":"cad_scan_validation/#completed-trials","title":"Completed trials","text":"Trial Method/window Channels Payload bytes Received / sent Mean complete scan baseline-fixed Fixed-channel RX 4 64 16 / 16 \u2014 cad-standard CAD + software RX 4 64 7 / 32 14.469 ms cad-auto CAD + automatic RX 4 64 16 / 32 14.468 ms rxfast-4 rxfast 4 4 64 32 / 32 6.100 ms rxfast-4-maxpayload rxfast 4 4 255 35 / 35 6.098 ms matrix-cad1-1 cad 1 1 64 7 / 8 2.643 ms matrix-cad1-10 cad 1 10 64 2 / 20 28.389 ms matrix-cad1-11 cad 1 11 64 5 / 22 31.297 ms matrix-cad1-12 cad 1 12 64 3 / 24 34.145 ms matrix-cad2-10 cad 2 10 64 3 / 40 31.040 ms matrix-fixed-12 Fixed-channel RX 12 64 24 / 24 \u2014 matrix-rx1-10 rxfast 1 10 64 0 / 20 7.555 ms matrix-rx1-11 rxfast 1 11 64 0 / 22 8.316 ms matrix-rx1-12 rxfast 1 12 64 0 / 24 9.072 ms matrix-rx2-10 rxfast 2 10 64 0 / 40 10.133 ms matrix-rx3-7 rxfast 3 7 64 2 / 35 8.892 ms matrix-rx3-8 rxfast 3 8 64 1 / 40 10.160 ms matrix-rx4-5 rxfast 4 5 64 39 / 40 7.630 ms boundary-rx3-1 rxfast 3 1 64 4 / 24 1.268 ms boundary-rx3-4 rxfast 3 4 64 2 / 24 5.080 ms boundary-rx3-5 rxfast 3 5 64 0 / 25 6.350 ms boundary-rx3-6 rxfast 3 6 64 2 / 30 7.621 ms boundary-rx4-4 rxfast 4 4 64 80 / 80 6.104 ms boundary-rx4-5 rxfast 4 5 64 79 / 80 7.630 ms boundary-rx4-6 rxfast 4 6 64 52 / 60 9.158 ms <p><code>rxfast N</code> means a continuous-RX preamble observation window of N symbols, with minimal reconfiguration between frequencies. It is not CAD. <code>cad N</code> uses the SX1262 CAD detector with N symbols and automatic handoff to RX. CAD has no three-symbol mode.</p> <p>Scan times describe uninterrupted sweeps. When reception starts, the radio stays on that frequency through the packet and cannot hear packets on the other frequencies. Serial status requests can add occasional timing outliers.</p> <p>The maximum-payload trial ended after 35 confirmed transmissions when a serial acknowledgement was delayed. Its last TX acknowledgement and matching RX were subsequently recovered from the serial logs; all 35 were received. It is not a completed 64-packet trial.</p>"},{"location":"cad_scan_validation/#interpretation-and-limits","title":"Interpretation and limits","text":"<p>The initial four-channel fast-RX test received 32/32 64-byte packets and 35/35 255-byte packets. That is a successful strong-signal bench result, not a guarantee of zero loss. Ordinary four-symbol CAD took approximately 14.47 ms to cover four frequencies and was unreliable with an 8.192 ms preamble.</p> <p>Reducing the observation window also reduces the time available for the modem to recognize a preamble. Dividing preamble duration by scan duration alone overestimates the number of usable channels. One- and two-symbol RX windows produced no preamble detections in the tested high-channel-count cases.</p> <p>The three-symbol single-channel control repeatedly re-arms RX, just as a scan would, and received only 4/24 packets. It is distinct from continuous fixed-channel reception, which passed its baseline. This isolates a detection-window limitation even without a long multi-channel sweep.</p> <p>CAD detection peak 18 and minimum 10 were held constant. These are the datasheet four-symbol SF5 thresholds; the one- and two-symbol CAD tests do not establish optimized thresholds or weak-signal sensitivity. CAD activity followed by no decoded packet can be a late packet detection, not necessarily a noise false positive.</p> <p>Received signals were strong. These tests do not establish weak-signal range, adjacent-channel rejection, simultaneous-packet capacity, production firmware scheduling performance, power consumption, FCC compliance, or months of uptime.</p>"},{"location":"cad_scan_validation/#reproduction-and-evidence","title":"Reproduction and evidence","text":"<p>See the test harness. Compact validated results, timing counters, and final firmware/source hashes are in cad_scan_results.json. Detailed sequence-level logs and private lab transport helpers are retained locally under <code>out/cad-scan/</code>.</p>"},{"location":"carrier_wave/","title":"Carrier-wave RF checks","text":"<p><code>cw</code> and <code>cw2</code> transmit a continuous, unmodulated carrier at the selected profile's frequency and the configured TX power. They are available in the shared ASCII CLI on SX1276-family, SX1262-family, and LR1110 builds, including repeaters, Companions, room servers, and sensors that use that CLI.</p> Command Action <code>cw on</code> Use the active primary frequency for 10 seconds. <code>cw on 2.5</code> Use the active primary frequency for 2.5 seconds. <code>cw2 on 0.75</code> Use the active second profile for 0.75 seconds. <code>cw off</code> or <code>cw2 off</code> Stop the carrier immediately. Either name stops it. <code>get cw</code> or <code>get cw2</code> Show which carrier is active and its remaining seconds. <p><code>set cw ...</code> and <code>set cw2 ...</code> are also accepted. Durations range from 0.001 to 60 seconds, rounded to milliseconds. The deadline runs in the main loop, so it is not a precision pulse generator or a hardware cutoff.</p> <p><code>cw2</code> requires an active <code>radio2</code> or <code>tempradio2</code> profile in <code>rxtx</code> mode. An <code>rx</code> or disabled second profile cannot transmit a carrier. <code>cw</code> uses <code>tempradio</code> when that is the current primary profile. There is one physical transmitter: a carrier uses one profile at a time and ignores the cross-TX setting. Stop it before selecting the other carrier. Repeating <code>on</code> on the same profile restarts the duration.</p> <p>Packet transmission, reception, profile scanning, CAD, and receive recovery checks pause during the carrier. The firmware keeps the MCU awake to service the deadline, controls the board's external amplifier, and resumes normal reception and profile scanning afterward. It rejects entry during a packet or a busy radio. Profile retuning waits until the carrier stops; replacement or expiry of the active second profile stops its carrier. Nothing about CW is saved across reboot.</p> <p>The normal <code>set tx &lt;dBm&gt;</code> command also works during CW for meter sweeps. It keeps the board's power limits and PA calibration, resumes the carrier after changing power, and does not extend the CW timeout. TX power retains its usual saved behavior. SX1276 temporarily uses FSK with zero frequency deviation, then rebuilds the LoRa configuration before resuming reception.</p> <p>Use the local USB or BLE console for immediate replies and manual stopping. An on-air CLI reply must wait until the carrier ends because LoRa packets cannot transmit during the test.</p> <p>A second radio on the same frequency can detect the carrier using instantaneous RSSI. Compare readings before, during, and after transmission; CAD and packet counters are not carrier detectors. This confirms RF activity, not calibrated output power, frequency accuracy, antenna match, or SWR. Afterward, exchange ordinary LoRa packets to verify both RX and TX recovery.</p> <p>The reproducible bench witness is <code>tools/hil/cw_observer.cpp</code>, built with <code>tools/hil/cw_observer.ini</code> on a separate RAK4631. It never transmits on its own. See the hardware validation for measured results, reproduction steps, and the tested preamble settings.</p>"},{"location":"carrier_wave_validation/","title":"CW and CW2 validation","text":"<p>Tested on the MercerWoodMesh lab Pi on September 14, 2026 (Pacific), using base commit <code>9241ccc253ad2f8ac2c9a2fe756f59ba2f52505d</code> plus the CW changes. Test images are marked <code>v1.17.1.6-cw-test-9241ccc2</code>; they are development images.</p> <p>A separate RAK4631 sampled instantaneous RSSI every approximately 10 ms. The transmitting boards ran the Full V4 repeater and Full T1000-E Companion builds. Both were configured for \u22129 dBm chip TX power, with profiles at 909.5 and 919.5 MHz, BW125, SF7, CR5, and 32-symbol preambles.</p> Check V4 / SX1262 T1000-E / LR1110 <code>cw on 0.25</code> measured duration 0.25 s 0.25 s <code>cw on 1.25</code> measured duration 1.25 s 1.25 s Manual stop approximately 1 s into a 5 s request 1.01 s 1.01 s <code>cw on 1.25</code> after enabling RXPS 1.26 s 1.25 s <code>cw2 on 1.25</code> on the second frequency 1.25 s 1.25 s Primary-frequency RSSI change while CW2 transmits 0 dB 0 dB Paired RX and TX recovery checks 5/5 passed 5/5 passed <p>The observer saw roughly \u221256 to \u221257 dBm during V4 carriers and \u221267 to \u221271 dBm during T1000-E carriers, against a \u2212112 to \u2212113 dBm baseline. Readings returned to baseline after timeout and manual stop. These are received signal readings, not calibrated transmitter output measurements.</p> <p>RX recovery used CRC-valid LoRa test payloads and the DUT's receive counter. TX recovery used each DUT's MeshCore advertisement, received with valid CRC by the observer. Both DUTs finished in RX, with CW and radio2 disabled and no outbound packet pending. The observer has no autonomous transmission.</p>"},{"location":"carrier_wave_validation/#software-checks","title":"Software checks","text":"<ul> <li>1,436 native tests passed, including new checks that CW holds queued packets,   services its deadline, and prevents transmission in the same loop where a   received command starts CW.</li> <li>Compiled production-method tests cover fractional input, malformed durations,   bounds, timer rollover, busy/IRQ rejection, RXPS cleanup, board TX/RX callbacks,   profile selection and replacement, failed TX entry, stop retries, and failed   RX restart. An ESP32 sleep test covers a carrier with USB disconnected.</li> <li>Full V4 repeater, Full T1000-E Companion, and ordinary STM32   <code>RAK_3x72_companion_radio_usb</code> builds passed. The STM32 build is a compilation   check, not an RF test of that board.</li> <li>An additional existing OTA sleep test still expects the old   <code>ota::ota_ctx().apply_pending</code> spelling. It fails against unchanged HEAD   <code>src/Mesh.cpp</code> and test-file contents; the actual implementation uses   <code>ota_context_if_active()</code>. This is separate from the CW changes.</li> </ul>"},{"location":"carrier_wave_validation/#sx1276-follow-up","title":"SX1276 follow-up","text":"<p>The SX1276 carrier feature from PR #11 is included alongside SX1262 and LR1110 support. It switches to FSK with zero deviation, applies the board's calibrated TX power, and rebuilds the runtime LoRa configuration when stopped. External-PA settings pass through the same DAC/drive-power mapping used for packets, including RFO selection.</p> <p>The normal TX power command can adjust a running carrier for meter sweeps. RadioLib's SX1276 power setter enters standby, so the carrier is restarted afterward without extending the deadline. Failed power changes stop the carrier and restore the previous cached power.</p> <p>Follow-up checks use base <code>9dd9881d520b4b791600a00fff1f8e1436921054</code> plus the SX1276 changes. Production-method regression tests cover both profiles, zero deviation, external-PA calibration, RFO, power sweeps, timeout, failed FSK entry, failed restoration, retry guards, and return to LoRa. The native CW paths and existing radio/profile/sleep/PA checks pass as well. Both <code>GEPRC_Linkflow_900_repeater</code> (external PA) and <code>Heltec_v2_companion_radio_usb</code> firmware builds pass, including size checks.</p> <p>SX1276 RF output has not been measured in this follow-up. The physical RF results above apply to SX1262 and LR1110.</p>"},{"location":"carrier_wave_validation/#bench-qualifications","title":"Bench qualifications","text":"<p>The first CW2 request arrived before radio2's existing delayed activation. The harness now polls <code>get radio2.status</code> for the active mode before testing.</p> <p>An initial V4 dual-profile packet probe used a 120-symbol preamble against 32-symbol profiles. A comparison around another CW2 burst received 0/8 before and 1/8 afterward with that mismatched probe, versus 8/8 before and 8/8 afterward with a matching 32-symbol probe. The configured preamble also sets the driver's preamble-detection hold timeout, so a much longer incoming preamble can outlast that hold and be interrupted by scanning. The final dual-profile recovery checks use matched preambles. This finding does not establish general packet-loss performance for every scan combination.</p> <p>These checks establish RF activity, selected-frequency behavior, and recovery on the tested boards. They do not measure spectral purity, frequency error, SWR, calibrated power, or months of uptime. Carrier timeouts are serviced by the main loop and depend on that loop remaining responsive.</p>"},{"location":"carrier_wave_validation/#reproduction","title":"Reproduction","text":"<p>Append <code>tools/hil/cw_observer.ini</code> to <code>extra_configs</code> in <code>platformio.local.ini</code>, preserving existing entries, and build <code>pio run -e cw_observer_rak4631</code>. Flash that application onto a separate lab RAK4631. Do not run PlatformIO concurrently with another build or upload in the checkout.</p> <p>Configure the lab DUT's primary profile as above, disable radio2, set TX power to \u22129 dBm, and reboot to apply saved primary settings. Then run:</p> <pre><code>python3 tools/hil/carrier_wave.py --dut /dev/serial/by-id/DUT \\\n  --observer /dev/serial/by-id/OBSERVER --role repeater --output cw-results.json\n</code></pre> <p>Use <code>--role companion</code> for the T1000-E. The harness changes lab radio2/RXPS settings and emits short RF bursts and packet probes. It is for test boards.</p> <p>Compact evidence: carrier_wave_results.json. Command guide: carrier-wave RF checks.</p>"},{"location":"cli_build_matrix/","title":"CLI Availability by Firmware Build","text":"<p>MeshCore command availability is determined in three layers:</p> <ol> <li>Role - repeater, room server, sensor, companion, bridge, or KISS modem.</li> <li>Build profile - standard, logging, OTA, or FULL.</li> <li>Compiled hardware features - WiFi, MQTT, GPS, external sensors, PSRAM,    Ethernet, and similar optional support.</li> </ol> <p>The complete command descriptions are in CLI Commands. This page describes the commands intentionally omitted or limited by build profile. The CLI Command Availability Matrix expands this summary into separate nRF52 and ESP32 command tables.</p>"},{"location":"cli_build_matrix/#selecting-a-build-profile","title":"Selecting a build profile","text":"<p>The runtime settings profile and the feature profile are separate switches:</p> <pre><code>bash build.sh build-firmware RAK_3401_repeater \\\n  --profile cascade \\\n  --build-profile auto\n</code></pre> <p><code>--profile default|cascade</code> selects saved-setting defaults. It does not select which code is linked. <code>--build-profile auto|standard|full</code> controls features and partition policy:</p> Selection Behavior <code>auto</code> For one explicit target, pass 1 builds the complete supported LoRa-OTA-capable recipe. ESP32 boards with a qualified expanded profile use it; other standalone repeaters and room servers attempt the complete recipe in their current application region. Other roles keep every capability declared by their resolved PlatformIO recipe, including LoRa OTA, and fail instead of silently removing one that does not fit. A measured repeater or room-server flash/partition overflow starts the standard <code>no_external_sensors</code> LoRa OTA pass. Internal-flash nRF52 repeaters and room servers publish that reduced pass even when the complete image fits, because the smaller running image leaves more room to stage a delta; matched QSPI/SD roles do not need the redundant artifact. Compiler errors and missing-capability checks never trigger or conceal a reduced build. Canonical bulk commands keep their established standard partition contract. <code>standard</code> Immediately uses the deployed/portable partition contract and its documented reductions. This is useful when the operator already knows the expanded or complete image is unsuitable. <code>full</code> Requires a qualified ESP32 expanded-partition target (or an explicitly named Full Companion). Install a matching merged image when this changes the partition table. <p>Successful builds also emit <code>&lt;firmware&gt;.capabilities.json</code>. The sidecar records the effective profile, logical OTA target, actual PlatformIO base, artifact name target, promised capabilities, and every reduction selected by the script. The build fails if a promised linked marker is absent. Current invariants include <code>retry.preset</code> for repeater/room-server roles, WebConfig for the Indicator and ESP32 Full Companion, TempRadio/OTA controls for install-capable Companions, host-mOTA controls for Full Companion, and the advanced flood-rule engine for Full room servers. Resume mode will not accept an old or failed artifact without a verified sidecar.</p> <p>For a single ESP32 repeater or room-server target, <code>auto</code> selects its matching combined Full MQTT/USB/WiFi image when that image covers the plain Full recipe. The direct observer and Full-matrix paths use the same <code>full-usb-wifi-ota</code> artifact and runtime output controls. Plain Full T-Beam SX1262/SX1276 profiles and the TLora V2 repeater remain alternatives because their MQTT siblings have lower routing-table capacities.</p> <p>Standard and reduced OTA images, including images that fit the 1.25 MiB portable application slot, remain available and remain in the standard matrix pass. Select <code>--build-profile standard</code> to retain the original target and partition contract. Moving from a plain target to its MQTT sibling changes the LoRa OTA target identity; existing nodes need an appropriate wired migration. For the normal-role partition migrations, the matrix also publishes a canonical Full image under the normal target identity. Install its matching merged image over USB once; mOTA rejects the incompatible partition signature until that migration is complete, then later Full updates use the normal target ID. The portable image remains available while deployed nodes move.</p> <p>Legacy supported ESP32 Wi-Fi repeaters can use the Wi-Fi partition migration bridge to preserve their identity and install an expanded Full image without a USB flash. The default <code>cascade</code> settings profile enables device and LoRa RX power saving; saved preferences take precedence, and active USB/network services can prevent device sleep. <code>--profile default</code> instead uses the upstream power-saving defaults.</p>"},{"location":"cli_build_matrix/#role-comes-first","title":"Role comes first","text":"Role Text administration CLI Repeater Full repeater administration surface, subject to the profile differences below Room server Room-server administration surface, subject to the profile differences below Sensor Sensor command surface; it does not acquire the repeater administration tree Full, serial, Ethernet, USB, BLE, or WiFi companion Uses the companion protocol; Full combines every qualified transport for that exact board KISS modem Uses the KISS/TNC frame interface, not the repeater text CLI Bridge Uses its base role plus commands for the bridge transport compiled into that target <p>A command belonging to a different role is not considered a profile cut. For example, adding FULL features to a sensor does not turn it into a repeater administrator.</p> <p>Repeater profiles use up to 254 neighbor entries. Measured internal-DRAM limits reduce selected Generic E22, Heltec V2, Meshadventurer, T-Beam OTA/MQTT, and TLora MQTT profiles to 50. Check the artifact capability manifest and ESP32 memory budget for the exact target.</p> <p>See local maintenance commands for USB, BLE/binary Companion, TCP/Ethernet, and browser CLI privileges. A direct connection can access local diagnostics and explicit credential getters; relaying a command over LoRa keeps its remote restrictions.</p>"},{"location":"cli_build_matrix/#profile-matrix","title":"Profile matrix","text":"Build/profile Command availability Standard non-MQTT repeater or room server Keeps the normal role CLI and, where USB is a safe plaintext console, embeds debug/packet logging behind persistent <code>get/set usb.logging</code>. The explicitly selected portable policy can omit WebConfig and browser WiFi OTA, so those commands are unavailable and the omission is recorded in the capability manifest. Legacy standard logging No longer emitted separately. Its behavior is compiled into the ordinary artifact. Size-constrained STM32 targets embed packet logging without verbose <code>MESH_DEBUG</code>. LoRa-OTA (<code>-ota-</code>) LoRa OTA adds the <code>ota ...</code> commands; it does not otherwise reduce the role CLI. ESP32 <code>no_external_sensors</code> artifacts retain the compact browser WiFi uploader, the complete CLI, and up to 254 neighbors, subject to recorded internal-DRAM reductions. Internal-flash nRF52 repeater/room-server auto pair <code>full-ota</code> retains the board's external-sensor drivers; <code>reduced-ota</code> omits the declared optional sensors to leave additional internal-flash staging room. RAK3401 and RAK4631 reduced builds retain INA219, INA226, INA260, and INA3221 I2C voltage/current monitors at a measured cost below 5 KiB. Both artifacts carry the same stable OTA target identity and are checked for <code>ota ...</code> and <code>retry.preset</code>; RAK artifacts also verify the retained monitor drivers. ESP32 MQTT observer or ESP-NOW bridge Always uses the expanded FULL partition profile. The build never substitutes a reduced CLI to fit the legacy application slot. FULL ESP32 USB + WiFi Uses the matching MQTT target with packet logging on, verbose debug off, and the complete command surface supported by that role and hardware. <code>get/set logging.output off\\|usb\\|wifi\\|both</code> selects and persists the active output paths. FULL ESP32 logging fallback Uses the matching non-MQTT target only when no WiFi MQTT sibling exists, with debug and packet logging enabled and the complete command surface supported by that role and hardware. Its persistent USB gate also covers output-off operation, avoiding a second FULL ESP-NOW image. nRF52 dual-CDC Full Companion Fresh installs expose only interface <code>00</code>; it starts as an ASCII terminal and automatically hands a complete <code>&lt;</code> frame to framed Companion. The same interface also carries exclusive serial mOTA traffic. Enabling logging and rebooting adds interface <code>02</code> for plaintext logs. BLE and source-only LoRa OTA remain available. <code>get/set usb.logging</code> persistently controls whether the logging interface is present. ESP32 single-TTY Full Companion Every ESP32 Full image starts with the ASCII terminal on its one USB TTY and automatically hands a complete <code>&lt;</code> frame to framed Companion. On 1.17.1.5, run <code>set powersaving off</code> first. <code>set usb.logging on</code> switches that TTY to an input-capable plaintext logging terminal and makes framed Companion unavailable on USB; <code>set usb.logging off</code> stops logging but leaves the TTY in normal ASCII mode. The terminal stop token or a valid incoming framed probe then performs the ordinary switch to Binary Companion. A saved logging-on setting starts directly in that logging terminal and disables automatic frame detection. BLE, WiFi, and source-only LoRa OTA remain available. ESP32 Full uses Arduino-ESP32 2.x where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but still expose only one TTY. <code>no_external_sensors</code> Trims selected optional environmental/ranging drivers and their settings; it does not remove generic I2C, core repeater discovery, routing, or runtime RS-232 commands. RAK3401 and RAK4631 profiles retain the four common INA I2C voltage/current monitors. GPS-preserving RAK nRF52 OTA profiles retain their GPS commands and provider; RAK4631 defaults the bridge to UART 2 because RAK12501/L76K GPS uses UART 1. Legacy target suffixes remain stable for OTA identity compatibility. <p>The four retained INA drivers are entries in the optional environmental-sensor table, not the complete set of RAK I2C consumers. Compatible reduced profiles also retain the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 I2C GPS as separate board peripherals. RAK12501/L76K GPS uses UART Serial1. The explicit RAK4631 Serial1 bridge omits the combined GPS provider, including the otherwise non-UART RAK12500 path.</p> <p>The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>. To use both devices on one bus, leave RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>.</p> <p><code>logging</code>, <code>OTA</code>, and <code>FULL</code> describe independent build features in historical filenames. Current standard artifacts use no <code>-logging-</code> infix because their USB logging is runtime controlled.</p>"},{"location":"cli_build_matrix/#canonical-bulk-build-policy","title":"Canonical bulk-build policy","text":"<p>Bulk and release-matrix commands omit legacy names whose behavior is already available from a canonical image:</p> <ul> <li>Companion <code>_ps</code> names are replaced by the ordinary Companion image plus the   persisted <code>set powersaving on|off</code> setting.</li> <li>Companion <code>_femoff</code> names are replaced by the matching controllable-FEM   image plus <code>radio.fem.rxgain on|off</code>. The old names remain explicit build   targets for compatibility.</li> <li><code>Station_G2_logging_*</code> and <code>Station_G3_ESP32_logging_*</code> hardware names are   replaced by their ordinary Station target. G2 boosted receive gain is the   persisted <code>radio.rxgain on|off</code> setting; the G3 alias changed only the   advertised default name.</li> <li> <p>When a board has a Full Companion, that one artifact replaces its   separate USB, BLE, ordinary WiFi, hardware-serial, Ethernet Companion, and   USB packet-logging Companion artifacts.   It provides BLE and source-only LoRa OTA; ESP32 also provides ordinary WiFi.   nRF52 keeps framed traffic on interface <code>00</code> and can add logging on interface   <code>02</code> after a reboot. Every ESP32 Full build instead switches its one USB TTY   into an input-capable logging terminal. Turning logging off restores the   normal ASCII terminal; the usual stop token or a valid framed probe then   switches it to Binary Companion.   Its LoRa OTA support is source-only: it can serve a host file to another node   but has no staging store and cannot update itself over LoRa.   Installing an ESP32 Full Companion may require one merged-image erase/flash   to adopt its expanded partition table. Once migrated, later Full Companion   releases use normal app updates. The transport-specific non-Full images stay   available as explicit build targets, but are not canonical release artifacts   when the qualified Full image fits.</p> </li> <li> <p>Standalone Terminal Chat is omitted when the same exact hardware has either   Full Companion or a USB Companion, because their local text terminal supplies   the same role. Heltec E290 and T190 similarly publish one combined USB + BLE   Companion. RAK4631 repeater and room-server Ethernet builds stay separate;   only the RAK4631 Ethernet Companion is folded into Full Companion.</p> </li> <li>Matching RS-232 bridge roles are compiled into the normal repeater and   selected at runtime with <code>bridge.enabled</code>, <code>bridge.baud</code>, and <code>bridge.uart</code>.   Historical bridge names remain directly buildable but are omitted from bulk   releases. Wio-E5 remains separate because its normal image has only 916   bytes free, while the combined image exceeds the fixed 240 KiB application   partition by 2,192 bytes.</li> </ul> <p>The old aliases still work with <code>build-firmware</code> and <code>build-matching-firmwares</code>. Dedicated LoRa OTA repeater images are not collapsed; they retain their exact storage, bootloader, role, and target identity contracts. Companion boards keep transport-specific canonical images only when no exact Full recipe has passed the combined flash/RAM qualification. ESP32 deliberately uses one TTY: Binary Companion and plaintext USB logging are mutually exclusive there. nRF52 retains its optional second CDC port.</p>"},{"location":"cli_build_matrix/#complete-cli-policy","title":"Complete CLI policy","text":"<p>The compact ESP32 CLI has been removed. <code>retry.preset</code> is a checked invariant for every repeater and room-server artifact, not a FULL-only command. MQTT observers and ESP-NOW bridges are automatically promoted to FULL builds with expanded partitions rather than dropping administration commands. This keeps <code>tempradio</code>, LoRa OTA, power saving, RXPS, logging, statistics, sensor, ACL, routing, and advanced radio commands whenever the role and compiled hardware support them.</p> <p>Some commands still have hardware or feature limits. MQTT neighbor-table publishing and <code>discover.scopes</code> require the compiled <code>WITH_MQTT_NEIGHBORS</code> feature. PSRAM boards enable it automatically, and selected non-PSRAM variants opt in with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>. <code>discover.neighbors</code> does not require MQTT or PSRAM.</p>"},{"location":"cli_build_matrix/#discovery-invariant","title":"Discovery invariant","text":"<p><code>discover.neighbors</code> sends the zero-hop node-discovery request used to refresh the repeater neighbor table. It is available in every repeater build profile, including standard, logging, OTA, unified FULL, and FULL logging-fallback builds.</p> <p>The exact command is:</p> <pre><code>discover.neighbors\n</code></pre> <p>It accepts no options and returns:</p> <pre><code>OK - Discover sent\n</code></pre> <p>Some MQTT room-server targets also expose the command as part of their compiled neighbor-table feature. It is not a cross-role guarantee: companion, KISS, sensor, and ordinary room-server firmware use different interfaces or do not maintain the repeater administrator neighbor table.</p>"},{"location":"cli_build_matrix/#feature-dependent-commands","title":"Feature-dependent commands","text":"<p>Even in a FULL build, a command can be unavailable when its underlying feature does not exist on that target:</p> <ul> <li>WebConfig and the <code>wifi.ssid</code>, <code>wifi.status</code>, and <code>wifi.powersave</code> command   family require an ESP32 WebConfig build. FULL standalone repeater and   room-server builds support the corresponding WiFi setters and status   commands. ESP32 WiFi Companions with WebConfig expose WiFi credentials,   connection status, WebConfig, and power-save controls from their USB   text terminal as well as power saving through WebConfig and the binary   protocol. All ESP32 WiFi Companions with WebConfig also expose the browser   CLI tab and <code>wifi.cli</code> switch, enabled by default in station/LAN mode. Older   Companion firmware needs an update to support it. Full Companion additionally   exposes its complete chat and streaming text terminal on TCP port 5002.</li> <li>MQTT commands require an MQTT observer target.</li> <li><code>discover.scopes</code> requires an MQTT observer with compiled neighbor support;   it does not independently require PSRAM or the FULL parser.</li> <li>GPS and external-sensor commands require their drivers and pins.</li> <li>Ethernet and bridge commands require the corresponding transport.</li> <li>LoRa OTA commands require an artifact with OTA enabled.</li> <li><code>uf2reset</code> applies only to nRF52.</li> </ul> <p>When diagnosing an unavailable command, check the role first, then the filename profile, then the target's compiled hardware features and its adjacent <code>.capabilities.json</code> file. A current artifact that promises the command but does not contain its linked marker is rejected during the build.</p>"},{"location":"cli_command_availability/","title":"CLI Command Availability Matrix","text":"<p>This page is the command-by-command companion to CLI Availability by Firmware Build. Each command name links to its detailed documentation.</p> <p>The tables cover the text administration CLI used by repeater, room-server, sensor, and bridge firmware. Full Companion also has its own ASCII USB/TCP terminal; see feature switches by role. Companion apps use the companion protocol, KISS firmware uses framed KISS/TNC commands, and terminal-chat firmware has its own interface, so those build roles are not represented in the main matrices. The Companion section below lists its framed maintenance commands. Infrastructure <code>get password</code> is available locally in every profile; LoRa requests cannot read it. <code>get acl</code> and stored packet <code>log</code> are infrastructure features, not Companion contact or live USB-logging commands.</p> <p>Build columns mean:</p> <ul> <li>Standard - the ordinary non-MQTT artifact, without an explicit <code>ota</code>   filename marker. Safe plaintext-USB roles embed runtime USB logging.</li> <li>Logging - the legacy <code>-logging-</code> profile, now represented by the same   ordinary artifact and retained as a comparison column only.</li> <li>LoRa OTA - the explicit <code>-ota-</code> repeater or repeater-bridge artifact. A   legacy <code>no_external_sensors</code> profile trims selected optional environmental   and ranging drivers; it does not disable the generic I2C bus or unrelated   board-integrated peripherals. Reduced RAK3401 and RAK4631 profiles retain   INA219/INA226/INA260/INA3221 as voltage/current entries in the optional sensor   table. The SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS are   separate I2C peripherals in compatible recipes. RAK12501/L76K GPS instead   uses UART Serial1. The plain RAK profiles and RAK4631 Serial2 bridge retain   the combined GPS provider; the explicit RAK4631 Serial1 bridge omits that   provider, including RAK12500, because the bridge owns the RAK12501 UART.</li> <li>FULL unified - the expanded-partition ESP32 artifact with LoRa OTA, the   complete parser, USB packet logging, and direct WiFi MQTT. Its saved output   mode can be off, USB, WiFi, or both. MQTT observers use this profile.</li> <li>FULL fallback - the expanded-partition ESP32 non-MQTT artifact used only   where there is no MQTT sibling. It has the complete parser and a saved   USB-logging on/off gate. ESP-NOW bridges use this profile.</li> </ul> <p>The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>; they cannot coexist on one bus at those addresses. Leave RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both are installed.</p> <p>Cell values mean:</p> <ul> <li>Yes - the parser includes the command. The Scope column still applies.</li> <li>No - the profile does not expose the command.</li> <li>Feature - available only when the target compiles the feature or hardware   named in Scope.</li> <li>Local - a direct USB, BLE/binary Companion, TCP/Ethernet, or LAN browser   connection, when that transport and command exist on the role; unavailable   over LoRa.</li> <li>Manifest - available only when the MQTT target defines   <code>OTA_MANIFEST_BASE</code>.</li> <li>Limited - the family exists, but the limitation in Scope applies.</li> </ul> <p>Runtime state can still make an included command fail. Examples include no GPS fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without <code>.mota</code> apply support.</p>"},{"location":"cli_command_availability/#companion-framed-cli","title":"Companion framed CLI","text":"<p>Companion builds are not represented by the role/profile matrices below. Their local terminal and command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>) expose these settings over the normal binary USB, BLE, or TCP connection:</p> Command Availability <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code> Local terminal and binary command <code>0x42</code> <code>erase</code> Local terminal and binary command <code>0x42</code>; reboot after erasing stored settings <code>set freq &lt;MHz&gt;</code> Local terminal, binary command <code>0x42</code>, and authorized LoRa CLI; reboot to apply <code>get prv.key</code> Local terminal and binary command <code>0x42</code>; requires private key export enabled <code>get password</code> Reports that Companion has no admin password; infrastructure returns its password locally <code>get wifi.pwd</code>, <code>get mqttN.password</code>, <code>get mqttN.token</code> Local terminal and binary command <code>0x42</code>; corresponding WiFi/MQTT feature required <code>board</code> Every Companion text terminal and command <code>0x42</code> <code>version</code> Every Companion text terminal and protocol-v14 command <code>0x42</code>; returns the untruncated build identity <code>get storage.layout</code> Every Companion text terminal and command <code>0x42</code>; reports the running platform's storage layout <code>memory</code> ESP32 Full Companion text terminal and command <code>0x42</code> <code>get/set radio.rxgain</code> Companion with a supported radio <code>get/set radio.fem.rxgain</code> Companion on a board with controllable LoRa FEM LNA <code>get/set wifi.powersave</code> ESP32 WiFi Companion; active transport constraints still apply <code>get/set bluetooth.name</code> Companion firmware <code>get/set bluetooth.mac</code> Every Companion build with Bluetooth <code>get/set display.touch</code> Touchscreen Companions using the shared UI; text terminal and framed CLI; off after reboot <code>get/set display.inbox</code> Shared Companion UI; <code>history</code> (default), <code>pending</code>, or <code>unread</code>; saved across reboot <code>uf2reset</code> Every nRF52 Companion text terminal and local command <code>0x42</code>; local only <p>Deprecated binary aliases remain receive-only for older clients; new clients should use command <code>0x42</code>. See Companion radio binary protocol.</p>"},{"location":"cli_command_availability/#nrf52","title":"nRF52","text":"Area Command Scope Standard Logging LoRa OTA Operational <code>reboot</code> All text CLI roles Yes Yes Yes Operational <code>poweroff</code>; <code>shutdown</code> Board power-off support Yes Yes Yes Operational <code>uf2reset</code> Local connection; supported UF2 boards Local Local Local Operational <code>clkreboot</code> All text CLI roles Yes Yes Yes Operational <code>clock sync</code> All text CLI roles Yes Yes Yes Operational <code>clock</code> All text CLI roles Yes Yes Yes Operational <code>time &lt;epoch_seconds&gt;</code> Clock only moves forward Yes Yes Yes Operational <code>advert</code> Advert-capable role Yes Yes Yes Operational <code>advert.zerohop</code> Advert-capable role Yes Yes Yes Operational <code>erase</code> Local connection Local Local Local Information <code>ver</code> All text CLI roles Yes Yes Yes Information <code>board</code> All text CLI roles Yes Yes Yes Diagnostics <code>get storage.layout</code> Internal layout and configured QSPI or SD storage Yes Yes Yes Diagnostics <code>memory</code> ESP32 only No No No Diagnostics <code>sensor</code> Hardware wiring summary Yes Yes Yes Diagnostics <code>powerlog</code> Reset, shutdown, and boot-voltage summary Yes Yes Yes Neighbors <code>neighbors</code> Role with a neighbor table Yes Yes Yes Neighbors <code>neighbor.remove [pubkey_prefix]</code> Role with a mutable neighbor table; omit prefix to clear all Yes Yes Yes Neighbors <code>discover.neighbors</code> Repeater; some MQTT room servers Yes Yes Yes Neighbors <code>discover.scopes</code> MQTT observer with compiled neighbor support No No No Statistics <code>clear stats</code> All full-parser text CLI roles Yes Yes Yes Statistics <code>stats-core</code> Local connection Local Local Local Statistics <code>stats-radio</code> Local connection Local Local Local Statistics <code>stats-radio-diag</code> Local connection Local Local Local Statistics <code>stats-packets</code> Local connection Local Local Local Statistics <code>get telemetry.temp/volt/volt.i2c</code>; optional GPS history Non-STM32 repeater or room server; I2C command requires a detected voltage monitor; GPS requires a provider; remote access requires administrator Yes Yes Yes Statistics <code>set telemetry.gps</code>; <code>get/set/send telemetry.tx</code> Non-STM32 repeater; GPS setting requires a provider; remote access requires administrator Yes Yes Yes Logging <code>log start</code>; <code>log stop</code>; <code>log erase</code> Storage-backed roles retain data; other roles can return empty data Yes Yes Yes Logging <code>log</code> Local connection Local Local Local Logging <code>get/set usb.logging</code>; unified FULL <code>get/set logging.output</code> Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; nRF52 Full Companion can add a reboot-controlled second CDC Yes Yes No Radio <code>get radio</code>; <code>set radio ...</code> All text CLI roles Yes Yes Yes Radio <code>get tx</code>; <code>set tx &lt;dbm&gt;</code> Board TX-power limits apply Yes Yes Yes Radio <code>tempradio ...</code>; <code>normalradio</code> Full parser Yes Yes Yes Radio <code>get/set/del radioat</code>; <code>get/set/del tempradioat</code> Full parser Yes Yes Yes Radio <code>get freq</code>; <code>set freq &lt;mhz&gt;</code> Local or authorized LoRa CLI Yes Yes Yes Radio <code>get/set radio.rxgain</code> Supported radio Feature Feature Feature Radio <code>get/set radio.fem.rxgain</code> Controllable LoRa FEM Feature Feature Feature Radio <code>get/set radio.fem.txgain</code> Controllable LoRa FEM Feature Feature Feature Radio <code>get/set radio.rxps</code>; <code>get rxps.wd</code> RX power-saving support Feature Feature Feature System <code>get/set name</code> All text CLI roles Yes Yes Yes System <code>get/set lat</code> All text CLI roles Yes Yes Yes System <code>get/set lon</code> All text CLI roles Yes Yes Yes System <code>get/set prv.key</code> <code>get</code> requires a local connection Yes Yes Yes System <code>get password</code>; <code>password &lt;new_password&gt;</code> <code>get</code> requires a local connection; setter requires administrator Yes Yes Yes System <code>get/set guest.password</code> Role with guest administration Yes Yes Yes System <code>get/set owner.info</code> All text CLI roles Yes Yes Yes System <code>get/set adc.multiplier</code> Board ADC override support Feature Feature Feature System <code>send text.flood &lt;message&gt;</code> Repeater Yes Yes Yes System <code>host &lt;text&gt;</code>; <code>get host</code> Repeater with host bridge; <code>host</code> requires a remote administrator and a USB/MQTT service Yes Yes Yes System <code>get/set battery.alert</code>; <code>get battery.alert.region</code> Repeater Yes Yes Yes System <code>get/set battery.alert.low</code>; <code>get/set battery.alert.critical</code> Repeater Yes Yes Yes System <code>get/set rx.watchdog</code> Repeater Yes Yes Yes System <code>get/set system.watchdog</code> nRF52 Yes Yes Yes System <code>get public.key</code> All text CLI roles Yes Yes Yes System <code>get role</code> All text CLI roles Yes Yes Yes System <code>get powersaving</code>; <code>set powersaving on/off</code> Supported repeater board Feature Feature Feature System <code>get/set reboot.interval</code> Full parser Yes Yes Yes Clock sync <code>get/set clock.sync.*</code>; <code>clock.sync.mesh now</code> Repeater, sensor, and room server; <code>clock.sync.internet</code> needs MQTT repeater Yes Yes Yes Routing <code>get/set repeat</code> Forwarding-capable role Yes Yes Yes Routing <code>get/set path.hash.mode</code> Role that supports path-hash selection Yes Yes Yes Routing <code>get/set loop.detect</code> Repeater Yes Yes Yes Routing <code>get/set txdelay</code> All text CLI roles, including bridges Yes Yes Yes Routing <code>get/set direct.txdelay</code> Full parser Yes Yes Yes Routing <code>get/set rxdelay</code> All text CLI roles, including bridges Yes Yes Yes Routing <code>get/set dutycycle</code> Full parser Yes Yes Yes Routing <code>get/set af</code> Full parser Yes Yes Yes Routing <code>get/set int.thresh</code> All text CLI roles Yes Yes Yes Routing <code>get/set cad</code> Radio CAD support Feature Feature Feature Routing <code>get/set agc.reset.interval</code> All text CLI roles Yes Yes Yes Routing <code>get/set radio.watchdog</code> MQTT observer No No No Routing <code>get/set multi.acks</code> Full parser Yes Yes Yes Routing <code>get/set flood.advert.interval</code> Repeater Yes Yes Yes Routing <code>get/set advert.interval</code> Advert-capable role Yes Yes Yes Routing <code>get/set flood.max</code> Repeater Yes Yes Yes Routing <code>get/set flood.max.unscoped</code> Repeater Yes Yes Yes Routing <code>get/set flood.max.advert</code> Repeater Yes Yes Yes Routing <code>get/set flood.channel.data</code>; <code>get/set flood.channel.data.hops</code> Repeater Yes Yes Yes Routing <code>get/set/del flood.channel.scope*</code> Repeater Yes Yes Yes Routing <code>get/set/del flood.channel.scope.require*</code> Repeater Yes Yes Yes Routing <code>get/set/del flood.rule*</code>; <code>get/set/del flood.filter*</code>; <code>get/set/del flood.filter.blacklist*</code> Repeater; <code>flood.rule</code>/<code>flood.filter</code> also on FULL ESP32 room server (no blacklist) Yes Yes Yes Routing <code>get/set/del flood.moderation*</code> Repeater Yes Yes Yes Routing <code>get/set outpath</code> Repeater remote-client context Yes Yes Yes Routing <code>get/set altpath</code> Repeater remote-client context Yes Yes Yes ACL <code>setperm &lt;pubkey&gt; &lt;permissions&gt;</code> Repeater, room server, or sensor Yes Yes Yes ACL <code>get acl [page]</code> Repeater, room server, or sensor; admin over LoRa Yes Yes Yes ACL <code>get/set allow.read.only</code> Room server Yes Yes No Regions <code>region load</code>; <code>region save</code> Role with region storage Yes Yes Yes Regions <code>region allowf</code>; <code>region denyf</code> Role with region storage Yes Yes Yes Regions <code>region get</code>; <code>region list</code>; <code>region</code> Role with region storage Yes Yes Yes Regions <code>region home</code>; <code>region default</code> Role with region storage Yes Yes Yes Regions <code>region put</code>; <code>region def</code>; <code>region remove</code> Role with region storage Yes Yes Yes Retry <code>get/set direct.retry</code>; <code>get/set direct.retry.heard</code> Role with basic retry support Yes Yes Yes Retry <code>get/set retry.preset</code> Role with retry support Yes Yes Yes Retry <code>get/set flood.retry.count</code>; <code>get/set flood.retry.path</code>; <code>get/set flood.retry.group.path</code> Repeater Yes Yes Yes Retry <code>get/set flood.retry.advert</code>; <code>get/set flood.retry.prefixes</code>; <code>get/set flood.retry.ignore</code> Repeater Yes Yes Yes Retry <code>get/set flood.retry.bridge</code>; <code>get/set flood.retry.bucket</code> Repeater bridge retry support Feature Feature Feature Retry <code>get/set direct.retry.count</code>; <code>get/set direct.retry.base</code>; <code>get/set direct.retry.step</code> Role with retry support Yes Yes Yes Retry <code>get/set direct.retry.margin</code>; <code>get/set direct.retry.cr</code> Role with retry support Yes Yes Yes Retry <code>get/set/clear recent.repeater</code>; <code>get recent.repeaters</code> Repeater Yes Yes Yes GPS <code>get gps</code>; <code>set gps on/off</code> Compiled GPS Feature Feature Feature GPS <code>gps sync</code> Compiled GPS Feature Feature Feature GPS <code>gps setloc</code> Compiled GPS Feature Feature Feature GPS <code>gps advert [none/share/prefs]</code> Compiled GPS Feature Feature Feature Sensors <code>get/set telemetry.access</code> Sensor-capable role Feature Feature Limited Sensors <code>sensor list [start]</code> Compiled sensor manager; reduced OTA trims target-selected optional environmental/ranging drivers Feature Feature Limited Sensors <code>sensor get</code>; <code>sensor set</code> Compiled sensor setting; reduced OTA trims target-selected optional environmental/ranging drivers Feature Feature Limited Sensors <code>io [r/s/t]&lt;hex&gt;</code> Simple sensor role with board GPIO support Feature Feature No Bridge <code>get bridge.type</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.enabled</code>; <code>get bridge.running</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.delay</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.source</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.baud</code> RS-232 bridge Feature Feature Feature Bridge <code>get/set bridge.uart</code> RS-232 bridge Feature Feature Feature Bridge <code>get/set bridge.channel</code> ESP-NOW is ESP32 only No No No Bridge <code>get/set bridge.format</code> ESP-NOW bridge No No No Bridge <code>get/set bridge.secret</code> ESP-NOW is ESP32 only No No No Board <code>get bootloader.ver</code> nRF52 bootloader metadata Yes Yes Yes Board <code>get pwrmgt.support</code>; <code>get pwrmgt.source</code>; <code>get pwrmgt.bootreason</code>; <code>get pwrmgt.bootmv</code> Board power-management implementation Feature Feature Feature Ethernet <code>eth.status</code> Ethernet target Feature Feature No Browser OTA <code>start ota [ap]</code>; <code>stop ota</code> ESP32 browser uploader No No No WebConfig <code>start webconfig [ap]</code>; <code>stop webconfig</code>; <code>get/set webui</code> ESP32 WebConfig No No No WiFi <code>get/set wifi.ssid</code>; <code>set wifi.pwd</code>; <code>get wifi.status</code>; <code>get/set wifi.powersave</code> ESP32 WiFi No No No WiFi <code>get/set wifi.cli</code> ESP32 WebConfig No No No LoRa OTA <code>ota help</code>; <code>ota ?</code>; <code>ota h</code> LoRa OTA build No No Yes LoRa OTA <code>ota</code>; <code>ota status</code>; <code>ota st</code> LoRa OTA build No No Yes LoRa OTA <code>ota stats</code> LoRa OTA build No No Yes LoRa OTA <code>ota ls</code>; <code>ota neighbors</code>; <code>ota nbrs</code>; <code>ota updates</code>; <code>ota n</code> LoRa OTA build No No Yes LoRa OTA <code>ota get</code>; <code>ota pull</code>; <code>ota download</code> LoRa OTA build; internal-store nRF52 installs in-place deltas, while matched SD/QSPI nRF52 also accepts full images No No Yes LoRa OTA <code>ota install</code>; <code>ota apply</code>; <code>ota applydelta</code> Compatible bootloader and completed update No No Yes LoRa OTA <code>ota rescue install &lt;base_hash16&gt;</code> Legacy internal-flash nRF52 LoRa OTA build with failed app-side EndF validation; shared bootloader-update builds require valid EndF No No Feature LoRa OTA <code>ota bootloader</code>; <code>ota bootloader install &lt;MID8&gt; &lt;HASH16&gt;</code> Allowlisted internal-flash, XIAO-QSPI, or exact MeshTower V2 microSD nRF52 repeater with ABI-3 exact-board OTAFIX No No Feature LoRa OTA <code>ota cancel</code>; <code>ota drop</code>; <code>ota stop</code> LoRa OTA build No No Yes LoRa OTA <code>ota announce</code>; <code>ota adv</code> LoRa OTA build No No Yes LoRa OTA <code>ota self</code>; <code>ota id</code> Firmware with EndF trailer No No Yes LoRa OTA <code>ota qspi</code>; <code>ota storage</code> nRF52 build with raw-QSPI OTA staging Feature Feature Feature LoRa OTA <code>ota folder</code>; <code>ota fold</code> <code>on</code> needs compiled folder transport No No Feature LoRa OTA <code>ota config</code>; <code>ota cfg</code>; <code>ota set</code> LoRa OTA build No No Yes LoRa OTA <code>ota key</code>; <code>ota keys</code> LoRa OTA build No No Yes LoRa OTA <code>ota dev ...</code> Developer diagnostics No No Yes MQTT <code>get/set mqttN.preset</code> MQTT observer No No No MQTT <code>get/set mqttN.server</code>; <code>get/set mqttN.port</code>; <code>get/set mqttN.username</code>; <code>get/set mqttN.password</code> MQTT observer No No No MQTT <code>get/set mqttN.token</code>; <code>get/set mqttN.topic</code>; <code>get/set mqttN.audience</code> MQTT observer No No No MQTT <code>get mqttN.diag</code> MQTT observer No No No MQTT <code>get/set mqtt.origin</code>; <code>get/set mqtt.iata</code>; <code>get mqtt.presets</code> MQTT observer No No No MQTT <code>get mqtt.stats</code> MQTT observer No No No MQTT <code>get/set mqtt.status</code>; <code>get/set mqtt.packets</code>; <code>get/set mqtt.raw</code>; <code>get/set mqtt.interval</code> MQTT observer No No No MQTT <code>get/set mqtt.rx</code>; <code>get/set mqtt.tx</code> MQTT observer No No No MQTT <code>get/set mqtt.neighbors</code>; <code>get/set mqtt.neighbors.interval</code> MQTT observer with compiled neighbor support No No No MQTT <code>get/set mqtt.ntp</code> MQTT observer No No No MQTT <code>get mqtt.ntp.diag</code> Full MQTT observer No No No MQTT <code>get/set timezone</code>; <code>get/set timezone.offset</code> MQTT observer No No No MQTT <code>get/set mqtt.analyzer.us</code>; <code>get/set mqtt.analyzer.eu</code> Legacy MQTT aliases No No No MQTT <code>get/set mqtt.owner</code>; <code>get/set mqtt.email</code> MQTT observer; <code>get</code> requires a local connection No No No MQTT <code>get mqtt.config.valid</code> MQTT observer No No No SNMP <code>get/set snmp</code>; <code>get/set snmp.community</code> MQTT target compiled with SNMP No No No Alerts <code>get/set alert</code>; <code>get/set alert.psk</code>; <code>get/set alert.hashtag</code>; <code>get/set alert.region</code>; <code>get/set alert.wifi</code>; <code>get/set alert.mqtt</code>; <code>get/set alert.interval</code> MQTT observer No No No Alerts <code>alert test [message]</code> MQTT observer with configured alert channel No No No TLS <code>tls.bundletest &lt;host&gt;</code> MQTT target with embedded certificate bundle No No No Manifest OTA <code>ota check</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No Manifest OTA <code>ota update</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No"},{"location":"cli_command_availability/#esp32","title":"ESP32","text":"Area Command Scope Standard Logging LoRa OTA FULL unified FULL fallback Operational <code>reboot</code> All text CLI roles Yes Yes Yes Yes Yes Operational <code>poweroff</code>; <code>shutdown</code> Board power-off support Yes Yes Yes Yes Yes Operational <code>uf2reset</code> nRF52 only No No No No No Operational <code>clkreboot</code> Full parser Yes Yes Yes Yes Yes Operational <code>clock sync</code> All text CLI roles Yes Yes Yes Yes Yes Operational <code>clock</code> All text CLI roles Yes Yes Yes Yes Yes Operational <code>time &lt;epoch_seconds&gt;</code> Clock only moves forward Yes Yes Yes Yes Yes Operational <code>advert</code> Advert-capable role Yes Yes Yes Yes Yes Operational <code>advert.zerohop</code> Advert-capable role Yes Yes Yes Yes Yes Operational <code>erase</code> Local connection Local Local Local Local Local Display <code>get/set display.mode</code>; <code>display.timeout</code>; <code>display.usb.mode</code>; <code>display.usb.timeout</code> Display-equipped roles; pairing modes require BLE Companion Feature Feature Feature Feature Feature Display <code>get/set display.flip</code> MQTT observer with supported display driver No No No Feature No Information <code>ver</code> All text CLI roles Yes Yes Yes Yes Yes Information <code>board</code> All text CLI roles Yes Yes Yes Yes Yes Diagnostics <code>get storage.layout</code> Detected flash size and live partition table Yes Yes Yes Yes Yes Diagnostics <code>memory</code> ESP32 heap and PSRAM summary Yes Yes Yes Yes Yes Diagnostics <code>sensor</code> Hardware wiring summary Yes Yes Yes Yes Yes Diagnostics <code>powerlog</code> Reset-reason summary Yes Yes Yes Yes Yes Neighbors <code>neighbors</code> Role with a neighbor table Yes Yes Yes Yes Yes Neighbors <code>neighbor.remove [pubkey_prefix]</code> Role with a mutable neighbor table; omit prefix to clear all Yes Yes Yes Yes Yes Neighbors <code>discover.neighbors</code> Repeater; some MQTT room servers Yes Yes Yes Yes Yes Neighbors <code>discover.scopes</code> MQTT observer with compiled neighbor support No No No Feature No Statistics <code>clear stats</code> Full parser Yes Yes Yes Yes Yes Statistics <code>stats-core</code> Local connection Local Local Local Local Local Statistics <code>stats-radio</code> Local connection Local Local Local Local Local Statistics <code>stats-radio-diag</code> Local connection Local Local Local Local Local Statistics <code>stats-packets</code> Local connection Local Local Local Local Local Statistics <code>get telemetry.temp/volt/volt.i2c</code>; optional GPS history Non-STM32 repeater or room server; I2C command requires a detected voltage monitor; GPS requires a provider; remote access requires administrator Yes Yes Yes Yes Yes Statistics <code>set telemetry.gps</code>; <code>get/set/send telemetry.tx</code> Non-STM32 repeater; GPS setting requires a provider; remote access requires administrator Yes Yes Yes Yes Yes Logging <code>log start</code>; <code>log stop</code>; <code>log erase</code> Storage-backed roles retain data Yes Yes Yes Yes Yes Logging <code>log</code> Local connection Local Local Local Local Local Logging <code>get/set usb.logging</code>; unified FULL <code>get/set logging.output</code> Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; every ESP32 Full Companion uses an input-capable single-TTY logging terminal with framed USB Companion disabled while logging Yes Yes No No Yes Radio <code>get radio</code>; <code>set radio ...</code> All text CLI roles Yes Yes Yes Yes Yes Radio <code>get tx</code>; <code>set tx &lt;dbm&gt;</code> Board TX-power limits apply Yes Yes Yes Yes Yes Radio <code>tempradio ...</code>; <code>normalradio</code> Full parser Yes Yes Yes Yes Yes Radio <code>get/set/del radioat</code>; <code>get/set/del tempradioat</code> Full parser Yes Yes Yes Yes Yes Radio <code>get freq</code>; <code>set freq &lt;mhz&gt;</code> Local or authorized LoRa CLI Yes Yes Yes Yes Yes Radio <code>get/set radio.rxgain</code> Supported radio Feature Feature Feature Feature Feature Radio <code>get/set espnow.channel</code> Primary ESP-NOW mesh radio Feature Feature Feature Feature Feature Radio <code>get/set radio.fem.rxgain</code> Controllable LoRa FEM Feature Feature Feature Feature Feature Radio <code>get/set radio.fem.txgain</code> Controllable LoRa FEM Feature Feature Feature Feature Feature Radio <code>get/set radio.rxps</code>; <code>get rxps.wd</code> Full parser and RX power-saving support Feature Feature Feature Feature Feature System <code>get/set name</code> All full-parser text CLI roles Yes Yes Yes Yes Yes System <code>get/set lat</code> All full-parser text CLI roles Yes Yes Yes Yes Yes System <code>get/set lon</code> All full-parser text CLI roles Yes Yes Yes Yes Yes System <code>get/set prv.key</code> <code>get</code> requires a local connection Yes Yes Yes Yes Yes System <code>get password</code>; <code>password &lt;new_password&gt;</code> <code>get</code> requires a local connection; setter requires administrator Yes Yes Yes Yes Yes System <code>get/set guest.password</code> Role with guest administration Yes Yes Yes Yes Yes System <code>get/set owner.info</code> Full parser Yes Yes Yes Yes Yes System <code>get/set adc.multiplier</code> Board ADC override support Feature Feature Feature Feature Feature System <code>send text.flood &lt;message&gt;</code> Repeater Yes Yes Yes Yes Yes System <code>host &lt;text&gt;</code>; <code>get host</code> Repeater with host bridge; <code>host</code> requires a remote administrator and a USB/MQTT service Yes Yes Yes Yes Yes System <code>get/set battery.alert</code>; <code>get battery.alert.region</code> Repeater Yes Yes Yes Yes Yes System <code>get/set battery.alert.low</code>; <code>get/set battery.alert.critical</code> Repeater Yes Yes Yes Yes Yes System <code>get/set rx.watchdog</code> Repeater Yes Yes Yes Yes Yes System <code>get/set system.watchdog</code> nRF52 only No No No No No System <code>get public.key</code> Full parser Yes Yes Yes Yes Yes System <code>get role</code> All text CLI roles Yes Yes Yes Yes Yes System <code>get powersaving</code>; <code>set powersaving on/off</code> Supported repeater board Feature Feature Feature Feature Feature System <code>get/set reboot.interval</code> Full parser Yes Yes Yes Yes Yes Clock sync <code>get/set clock.sync.*</code>; <code>clock.sync.mesh now</code> Repeater, sensor, and room server; <code>clock.sync.internet</code> needs MQTT repeater Yes Yes Yes Yes Yes Routing <code>get/set repeat</code> Forwarding-capable role Yes Yes Yes Yes Yes Routing <code>get/set path.hash.mode</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set loop.detect</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set txdelay</code> All text CLI roles, including bridges Yes Yes Yes Yes Yes Routing <code>get/set direct.txdelay</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set rxdelay</code> All text CLI roles, including bridges Yes Yes Yes Yes Yes Routing <code>get/set dutycycle</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set af</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set int.thresh</code> All text CLI roles Yes Yes Yes Yes Yes Routing <code>get/set cad</code> Radio CAD support Feature Feature Feature Feature Feature Routing <code>get/set agc.reset.interval</code> All text CLI roles Yes Yes Yes Yes Yes Routing <code>get/set radio.watchdog</code> MQTT observer No No No Yes No Routing <code>get/set multi.acks</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set flood.advert.interval</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set advert.interval</code> Full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.max</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.max.unscoped</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.max.advert</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.channel.data</code>; <code>get/set flood.channel.data.hops</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set/del flood.channel.scope*</code> Repeater role handler Yes Yes Yes Yes Yes Routing <code>get/set/del flood.channel.scope.require*</code> Repeater role handler Yes Yes Yes Yes Yes Routing <code>get/set/del flood.rule*</code>; <code>get/set/del flood.filter*</code>; <code>get/set/del flood.filter.blacklist*</code> Repeater role handler; <code>flood.rule</code>/<code>flood.filter</code> also on FULL ESP32 room server (no blacklist) Yes Yes Yes Yes Yes Routing <code>get/set/del flood.moderation*</code> Repeater role handler Yes Yes Yes Yes Yes Routing <code>get/set outpath</code> Repeater remote-client context Yes Yes Yes Yes Yes Routing <code>get/set altpath</code> Repeater remote-client context Yes Yes Yes Yes Yes ACL <code>setperm &lt;pubkey&gt; &lt;permissions&gt;</code> Repeater, room server, or sensor Yes Yes Yes Yes Yes ACL <code>get acl [page]</code> Repeater, room server, or sensor; admin over LoRa Yes Yes Yes Yes Yes ACL <code>get/set allow.read.only</code> Room server Yes Yes No Yes Yes Regions <code>region load</code>; <code>region save</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region allowf</code>; <code>region denyf</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region get</code>; <code>region list</code>; <code>region</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region home</code>; <code>region default</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region put</code>; <code>region def</code>; <code>region remove</code> Role with region storage Yes Yes Yes Yes Yes Retry <code>get/set direct.retry</code>; <code>get/set direct.retry.heard</code> Role with basic retry support Yes Yes Yes Yes Yes Retry <code>get/set retry.preset</code> Role with retry support Yes Yes Yes Yes Yes Retry <code>get/set flood.retry.count</code>; <code>get/set flood.retry.path</code>; <code>get/set flood.retry.group.path</code> Repeater Yes Yes Yes Yes Yes Retry <code>get/set flood.retry.advert</code>; <code>get/set flood.retry.prefixes</code>; <code>get/set flood.retry.ignore</code> Repeater Yes Yes Yes Yes Yes Retry <code>get/set flood.retry.bridge</code>; <code>get/set flood.retry.bucket</code> Repeater bridge retry support Feature Feature Feature Feature Feature Retry <code>get/set direct.retry.count</code>; <code>get/set direct.retry.base</code>; <code>get/set direct.retry.step</code> Role with retry support Yes Yes Yes Yes Yes Retry <code>get/set direct.retry.margin</code>; <code>get/set direct.retry.cr</code> Role with retry support Yes Yes Yes Yes Yes Retry <code>get/set/clear recent.repeater</code>; <code>get recent.repeaters</code> Repeater Yes Yes Yes Yes Yes GPS <code>get gps</code>; <code>set gps on/off</code> Compiled onboard GPS Feature Feature Feature Feature Feature GPS <code>gps sync</code> Compiled onboard GPS Feature Feature Feature Feature Feature GPS <code>gps setloc</code> Compiled onboard GPS Feature Feature Feature Feature Feature GPS <code>gps advert [none/share/prefs]</code> Compiled onboard GPS Feature Feature Feature Feature Feature Sensors <code>get/set telemetry.access</code> Sensor-capable full parser Feature Feature Limited Feature Feature Sensors <code>sensor list [start]</code> Compiled sensor manager; <code>no_external_sensors</code> trims target-selected environmental/ranging drivers, not generic I2C Feature Feature Limited Feature Feature Sensors <code>sensor get</code>; <code>sensor set</code> Compiled sensor setting; <code>no_external_sensors</code> trims target-selected environmental/ranging drivers, not generic I2C Feature Feature Limited Feature Feature Sensors <code>io [r/s/t]&lt;hex&gt;</code> Simple sensor role with board GPIO support Feature Feature No No Feature Bridge <code>get bridge.type</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.enabled</code>; <code>get bridge.running</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.delay</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.source</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.baud</code> RS-232 bridge Feature Feature Feature No Feature Bridge <code>get/set bridge.uart</code> RS-232 bridge Feature Feature Feature No Feature Bridge <code>get/set bridge.channel</code> ESP-NOW bridge No No No Feature Feature Bridge <code>get/set bridge.format</code> ESP-NOW bridge No No No Feature Feature Bridge <code>get/set bridge.secret</code> ESP-NOW bridge No No No Feature Feature Board <code>get bootloader.ver</code> nRF52 only No No No No No Board <code>get pwrmgt.support</code>; <code>get pwrmgt.source</code>; <code>get pwrmgt.bootreason</code>; <code>get pwrmgt.bootmv</code> nRF52 only No No No No No Ethernet <code>eth.status</code> Ethernet target Feature Feature No No Feature Browser OTA <code>start ota [ap]</code>; <code>stop ota</code> Compiled browser uploader No No Yes Feature Feature WebConfig <code>start webconfig [ap]</code>; <code>stop webconfig</code>; <code>get/set webui</code> Compiled WebConfig No No No Feature Feature WiFi <code>get/set wifi.ssid</code>; <code>set wifi.pwd</code>; <code>get wifi.status</code>; <code>get/set wifi.powersave</code> MQTT WiFi, or standalone FULL WebConfig; standalone has no <code>get wifi.pwd</code> No No No Yes Feature WiFi <code>get/set wifi.cli</code> Compiled WebConfig No No No Feature Feature LoRa OTA <code>ota help</code>; <code>ota ?</code>; <code>ota h</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota</code>; <code>ota status</code>; <code>ota st</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota stats</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota ls</code>; <code>ota neighbors</code>; <code>ota nbrs</code>; <code>ota updates</code>; <code>ota n</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota get</code>; <code>ota pull</code>; <code>ota download</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota install</code>; <code>ota apply</code>; <code>ota applydelta</code> Compatible completed update No No Yes Yes Yes LoRa OTA <code>ota rescue install &lt;base_hash16&gt;</code> Legacy internal-flash nRF52 LoRa OTA build with failed app-side EndF validation; shared bootloader-update builds require valid EndF No No Feature No No LoRa OTA <code>ota bootloader</code>; <code>ota bootloader install &lt;MID8&gt; &lt;HASH16&gt;</code> Allowlisted nRF52 internal/QSPI repeater feature No No No No No LoRa OTA <code>ota cancel</code>; <code>ota drop</code>; <code>ota stop</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota announce</code>; <code>ota adv</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota self</code>; <code>ota id</code> Firmware with EndF trailer No No Yes Yes Yes LoRa OTA <code>ota qspi</code>; <code>ota storage</code> nRF52 build with raw-QSPI OTA staging No No No No No LoRa OTA <code>ota folder</code>; <code>ota fold</code> <code>on</code> needs compiled serial or TCP folder transport No No Feature Feature Feature LoRa OTA <code>ota config</code>; <code>ota cfg</code>; <code>ota set</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota key</code>; <code>ota keys</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota dev ...</code> Developer diagnostics No No Yes Yes Yes MQTT <code>get/set mqttN.preset</code> MQTT observer No No No Yes No MQTT <code>get/set mqttN.server</code>; <code>get/set mqttN.port</code>; <code>get/set mqttN.username</code>; <code>get/set mqttN.password</code> MQTT observer No No No Yes No MQTT <code>get/set mqttN.token</code>; <code>get/set mqttN.topic</code>; <code>get/set mqttN.audience</code> MQTT observer No No No Yes No MQTT <code>get mqttN.diag</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.origin</code>; <code>get/set mqtt.iata</code>; <code>get mqtt.presets</code> MQTT observer No No No Yes No MQTT <code>get mqtt.stats</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.status</code>; <code>get/set mqtt.packets</code>; <code>get/set mqtt.raw</code>; <code>get/set mqtt.interval</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.rx</code>; <code>get/set mqtt.tx</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.neighbors</code>; <code>get/set mqtt.neighbors.interval</code> MQTT observer with compiled neighbor support No No No Feature No MQTT <code>get/set mqtt.ntp</code> MQTT observer No No No Yes No MQTT <code>get mqtt.ntp.diag</code> MQTT observer No No No Yes No MQTT <code>get/set timezone</code>; <code>get/set timezone.offset</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.analyzer.us</code>; <code>get/set mqtt.analyzer.eu</code> Legacy MQTT aliases No No No Yes No MQTT <code>get/set mqtt.owner</code>; <code>get/set mqtt.email</code> MQTT observer; <code>get</code> requires a local connection No No No Yes No MQTT <code>get mqtt.config.valid</code> MQTT observer No No No Yes No SNMP <code>get/set snmp</code>; <code>get/set snmp.community</code> MQTT target compiled with SNMP No No No Feature No Alerts <code>get/set alert</code>; <code>get/set alert.psk</code>; <code>get/set alert.hashtag</code>; <code>get/set alert.region</code>; <code>get/set alert.wifi</code>; <code>get/set alert.mqtt</code>; <code>get/set alert.interval</code> MQTT observer No No No Yes No Alerts <code>alert test [message]</code> MQTT observer with configured alert channel No No No Yes No TLS <code>tls.bundletest &lt;host&gt;</code> MQTT target with embedded certificate bundle No No No Feature No Manifest OTA <code>ota check</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No Manifest No Manifest OTA <code>ota update</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No Manifest No"},{"location":"cli_command_availability/#supplemental-command-notes","title":"Supplemental command notes","text":"<p>These short entries cover implemented commands that do not yet have their own section in the primary command reference.</p>"},{"location":"cli_command_availability/#memory","title":"<code>memory</code>","text":"<p>ESP32 only. Prints free heap, minimum heap, largest allocation, queue depth, internal heap, and PSRAM totals.</p>"},{"location":"cli_command_availability/#sensor-hardware-summary","title":"<code>sensor</code> hardware summary","text":"<p>Prints the configured I2C pins and GPS serial pins. This is a wiring/build diagnostic, distinct from <code>sensor list</code>, <code>sensor get</code>, and <code>sensor set</code>.</p>"},{"location":"cli_command_availability/#powerlog","title":"<code>powerlog</code>","text":"<p>Prints the last reset reason. nRF52 also prints the captured shutdown reason and boot voltage.</p>"},{"location":"cli_command_availability/#stats-radio-diag","title":"<code>stats-radio-diag</code>","text":"<p>Local-serial diagnostic that prints the extended radio diagnostic counters.</p> <p></p>"},{"location":"cli_command_availability/#radiorxps-and-rxpswd","title":"<code>radio.rxps</code> and <code>rxps.wd</code>","text":"<p><code>get radio.rxps</code> reports RX power-saving state and timing. <code>set radio.rxps ...</code> changes that configuration. <code>get rxps.wd</code> reports the soft and hard RX power-saving watchdog counters.</p> <p></p>"},{"location":"cli_command_availability/#rebootinterval","title":"<code>reboot.interval</code>","text":"<p><code>get reboot.interval</code> shows the scheduled reboot interval. Use <code>set reboot.interval &lt;hours&gt;</code> for 1-255 hours, or <code>set reboot.interval 0</code> to disable it.</p> <p></p>"},{"location":"cli_command_availability/#sensor-io","title":"Sensor <code>io</code>","text":"<p>The simple-sensor role exposes its board GPIO word as hexadecimal. <code>io</code> reads it; <code>io &lt;hex&gt;</code> replaces it; and <code>io r&lt;hex&gt;</code>, <code>io s&lt;hex&gt;</code>, or <code>io t&lt;hex&gt;</code> clear, set, or toggle selected bits.</p> <p></p>"},{"location":"cli_command_availability/#get-mqttndiag","title":"<code>get mqttN.diag</code>","text":"<p>Prints the runtime diagnostic summary for MQTT slot N, including its connection state and failure history.</p> <p></p>"},{"location":"cli_command_availability/#get-mqttstats","title":"<code>get mqtt.stats</code>","text":"<p>Prints the MQTT bridge runtime statistics summary.</p> <p></p>"},{"location":"cli_command_availability/#get-mqttconfigvalid","title":"<code>get mqtt.config.valid</code>","text":"<p>Reports whether the saved MQTT configuration has the minimum values needed to run.</p> <p></p>"},{"location":"cli_command_availability/#tlsbundletest","title":"<code>tls.bundletest</code>","text":"<p><code>tls.bundletest &lt;host[:port]|url&gt;</code> tests the embedded TLS certificate bundle against a remote host without changing the MQTT configuration.</p> <p></p>"},{"location":"cli_command_availability/#manifest-ota-check-and-ota-update","title":"Manifest <code>ota check</code> and <code>ota update</code>","text":"<p>On MQTT targets with <code>OTA_MANIFEST_BASE</code>, <code>ota check</code> fetches and checks the target manifest. <code>ota update</code> downloads and applies the compatible update selected by that manifest.</p>"},{"location":"cli_commands/","title":"CLI Commands","text":"<p>See two LoRa profiles for <code>radio2</code>, <code>tempradio2</code>, scheduling, RX-only mode, cross-transmission policy, and optional radio preambles.</p> <p>See carrier-wave RF checks for <code>cw on [seconds]</code>, <code>cw2 on [seconds]</code>, and stopping a carrier with <code>off</code>.</p> <p>For copy/paste on/off recipes and the differences from Full Companion, see feature switches by role. The USB web console opens the default ASCII terminal at 115200 baud; it does not require on-device WebConfig or WiFi.</p> <p>This document provides an overview of CLI commands that can be sent to MeshCore Repeaters, Room Servers and Sensors.</p> <p>See CLI Availability by Firmware Build for the role and profile matrix. Commands depend on compiled features; some portable builds omit WebConfig while retaining the complete role CLI and compact WiFi updater.</p> <p>See CLI Command Availability Matrix for the command-by-command nRF52 and ESP32 build tables.</p> <p>The first word of a command is case-insensitive, so <code>set</code>, <code>Set</code>, and <code>SET</code> are equivalent, as are <code>get</code>, <code>Get</code>, and the other command verbs. The case of arguments such as node names, passwords, and keys is left unchanged.</p> <p>Repeater retries carrying the same logical request ID and original command bytes reuse the cached result, even when command parsing trims whitespace or splits arguments in place. Changing the timestamp alone does not execute the operation again. Normal authentication and stale-request checks still apply. Deferred commands and host-service replies remain bound to the full authenticated public key, even if permission changes move ACL entries. Removing or revoking the requester cancels pending execution; a running <code>setperm</code> can still acknowledge its own completed change to the original sender.</p> <p>Use the site search or your browser's Find command with everyday wording such as tx retries, retry attempts, serial logging, or tx power. Search terms below are alternative wording to help find a command, not additional CLI aliases. Enter the syntax shown under Usage; supported command aliases are listed there explicitly.</p>"},{"location":"cli_commands/#navigation","title":"Navigation","text":"<ul> <li>Operational</li> <li>Neighbors</li> <li>Statistics</li> <li>Logging</li> <li>Information</li> <li>Configuration</li> <li>Radio</li> <li>System<ul> <li>GPIO</li> </ul> </li> <li>Routing</li> <li>Flood Rules</li> <li>Group Text Moderation</li> <li>ACL</li> <li>Region Management<ul> <li>Region Examples</li> </ul> </li> <li>GPS</li> <li>Sensors</li> <li>Bridge</li> <li>Ethernet</li> </ul>"},{"location":"cli_commands/#operational","title":"Operational","text":""},{"location":"cli_commands/#reboot-the-node","title":"Reboot the node","text":"<p>Search terms: restart, restart node, reboot device.</p> <p>Usage:  - <code>reboot</code></p> <p>Note: No reply is sent.</p>"},{"location":"cli_commands/#power-off-the-node","title":"Power-off the node","text":"<p>Search terms: turn off device, shut down, power off.</p> <p>Usage: - <code>poweroff</code>, or - <code>shutdown</code></p> <p>Note: No reply is sent.</p>"},{"location":"cli_commands/#enter-the-uf2-bootloader-nrf52-only","title":"Enter the UF2 bootloader (nRF52 only)","text":"<p>Search terms: bootloader mode, USB firmware update, UF2 mode.</p> <p>Usage: - <code>uf2reset</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p>Note: Reboots directly into the UF2 bootloader on supported nRF52 boards. This includes the Repeater, Room Server, Sensor, Companion, and Terminal Chat local serial command surfaces. It is never accepted as a remote mesh command.</p>"},{"location":"cli_commands/#reset-the-clock-and-reboot","title":"Reset the clock and reboot","text":"<p>Usage: - <code>clkreboot</code></p> <p>Note: No reply is sent.</p>"},{"location":"cli_commands/#sync-the-clock-with-the-remote-device","title":"Sync the clock with the remote device","text":"<p>Usage:  - <code>clock sync</code></p>"},{"location":"cli_commands/#display-current-time-in-utc","title":"Display current time in UTC","text":"<p>Usage: - <code>clock</code></p>"},{"location":"cli_commands/#set-the-time-to-a-specific-timestamp","title":"Set the time to a specific timestamp","text":"<p>Usage:  - <code>time &lt;epoch_seconds&gt;</code></p> <p>Parameters: - <code>epoch_seconds</code>: Unix epoch time</p>"},{"location":"cli_commands/#send-a-flood-advert","title":"Send a flood advert","text":"<p>Usage:  - <code>advert</code></p>"},{"location":"cli_commands/#send-a-zero-hop-advert","title":"Send a zero-hop advert","text":"<p>Usage: - <code>advert.zerohop</code></p>"},{"location":"cli_commands/#ask-a-usb-connected-host-service-over-lora-repeater-only","title":"Ask a USB-connected host service over LoRa (Repeater Only)","text":"<p>Usage:</p> <ul> <li><code>host &lt;text&gt;</code> - authenticated remote administrator only</li> <li><code>get host</code> - show bridge state and byte limits</li> </ul> <p><code>host</code> hands one remote LoRa CLI request to a service on the repeater's USB host and returns that service's reply over LoRa. It does not execute the text inside the firmware. The service has 4 seconds to prove the exact request is still pending, then 6 seconds to execute and reply. A second remote command receives busy while either phase is pending.</p> <p>Request text is limited to 155 UTF-8 bytes, or 152 bytes when a companion uses its legacy three-byte correlation prefix. The complete LoRa reply is limited to 162 bytes. USB records use Base64URL text, a random 64-bit nonce, and the repeater identity's Ed25519 signature. Before executing anything, the service must return a random one-time challenge and receive the repeater's signed live proof. This avoids any dependency on repeater/Pi clock agreement. Every <code>host.reply</code> USB command must carry the matching request ID and nonce; it is not accepted from LoRa or the Ethernet CLI.</p> <p>The included Raspberry Pi endpoint supports exact commands for <code>help</code>, <code>cpu-temp</code>, <code>hostname</code>, <code>uptime</code>, <code>load</code>, <code>memory</code>, <code>disk-free</code>, and <code>clock status</code>. It also provides strictly validated <code>clock sync</code> and <code>clock set &lt;unix_epoch&gt;</code> recovery actions, opt-in <code>network restart</code> and <code>reboot</code> actions, <code>action status &lt;operation_id&gt;</code>, and <code>run &lt;alias&gt; [arguments]</code> for locally allowlisted executables with typed arguments. Clock changes and host recovery actions are disabled by default, arbitrary executables are never accepted, and no action uses a shell. Clock set accepts only canonical unsigned decimal epochs from 2020 through 2099; a root-owned Unix-socket service revalidates the request and authenticates the local service account with <code>SO_PEERCRED</code> before changing system time. Network restart and reboot use a separate root-owned Unix-socket broker with fixed systemd units; installing clock control does not grant those actions. The endpoint never uses <code>sudo</code> for privileged host actions. See LoRa CLI host service for the complete <code>meshcoretomqtt</code> setup and security model.</p>"},{"location":"cli_commands/#lora-ota-speed","title":"LoRa OTA speed","text":"<pre><code>get ota.speed\nset ota.speed &lt;0.05..3&gt;\n</code></pre> <p><code>1</code> preserves the current OTA timing. Values below <code>1</code> slow OTA traffic; values above <code>1</code> shorten adjustable delays. For example, <code>0.5</code> doubles those delays and <code>3</code> divides them by three. Decimal values such as <code>.05</code> work. <code>ota config speed &lt;factor&gt;</code> is an equivalent setter, and <code>ota config</code> shows the value. The setting is saved and can be changed during a transfer.</p> <p>Apply it on the source, destination, and relays. It controls all LoRa OTA packet types on both profiles, relay timing, discovery, and OTA adverts. Slower settings extend recovery waits and space queued OTA packets while allowing ordinary traffic through. Faster settings retain the physical retry allowance and the configured airtime budget, so throughput is not guaranteed to rise in direct proportion. Proof turnaround keeps its physical allowance. Ordinary messages, node adverts, and local staged-image verification keep their timing. Available in OTA-enabled builds for all roles, including Companions. See the OTA guide.</p>"},{"location":"cli_commands/#start-or-stop-an-over-the-air-ota-firmware-update","title":"Start or stop an Over-The-Air (OTA) firmware update","text":"<p>Search terms: WiFi OTA, wireless firmware update, OTA uploader, update firmware.</p> <p>Usage: - <code>start ota</code> - <code>start ota ap</code> - <code>stop ota</code></p> <p>On nRF52, <code>start ota</code> invokes Bluetooth DFU with the matching bootloader and application DFU ZIP. The WiFi/AP instructions below apply to ESP32.</p> <p>On ESP32, <code>start ota</code> serves the web upload page on the station IP when connected to WiFi; otherwise it raises the <code>MeshCore-OTA</code> access point. <code>start ota ap</code> always raises the access point, which is useful when the normal network uses client isolation.</p> <p>On an ESP32 build with WebConfig, the manual OTA uploader and WebConfig both use HTTP port 80 and cannot run together. Stop WebConfig before <code>start ota</code>, or stop OTA before <code>start webconfig</code>.</p> <p>FULL ESP32 builds also expose the <code>.mota</code> folder seeder on TCP port 5001 whenever WiFi is usable. This listener is independent of port 80, so a host can run <code>motatool serve --dir ./motas --tcp &lt;node-ip&gt;:5001</code> while WebConfig is active. The TCP connection auto-attaches and detaches the folder; do not run <code>ota folder on</code> at the same time because that command selects the USB-serial folder transport.</p>"},{"location":"cli_commands/#browser-configuration-portal-esp32-repeater-and-room-server","title":"Browser configuration portal (ESP32 repeater and room server)","text":"<p>Search terms: web UI, web interface, WiFi settings page, configuration website, WebConfig.</p> <p>Usage:</p> <ul> <li><code>start webconfig</code></li> <li><code>start webconfig ap</code></li> <li><code>stop webconfig</code></li> <li><code>set webui on</code></li> <li><code>set webui off</code></li> <li><code>get webui</code></li> <li><code>get wifi.ssid</code></li> <li><code>get wifi.pwd</code></li> <li><code>get wifi.status</code></li> <li><code>get wifi.powersave</code></li> <li><code>get wifi.cli</code></li> <li><code>set wifi.ssid &lt;network name&gt;</code></li> <li><code>set wifi.pwd [password]</code></li> <li><code>set wifi.powersave &lt;none|min|max&gt;</code></li> <li><code>set wifi.cli &lt;on|off&gt;</code></li> </ul> <p><code>set webui on</code> is the persistent master switch. It starts the portal now and again after future reboots; <code>set webui off</code> closes it and disables that boot start. <code>get webui</code> reports the saved on/off state plus whether the portal is inactive, joining WiFi, serving a setup AP, or serving a LAN URL. The default is <code>off</code> on repeater and room-server builds. On display-equipped repeaters, an otherwise-unused triple click toggles the same saved setting. Consequently, <code>&gt; off, http://192.168.1.130/</code> means the saved boot setting is off while a temporary WebConfig session is currently active at that URL.</p> <p><code>start webconfig</code> is a temporary start that does not change the saved switch. It serves the shared WiFi, radio, flood, loop, and status page and reports its URL. MQTT builds also show the MQTT tab and wizard step; non-MQTT builds remove them entirely. Sign in with the node's admin password. If the node has no saved WiFi SSID, the command starts the open <code>MeshCore-Setup-XXXX</code> captive AP at http://192.168.4.1/ instead.</p> <p><code>start webconfig ap</code> forces captive-AP mode. It will not interrupt an active MQTT bridge, so run <code>set mqtt.enabled off</code> first. Use <code>stop webconfig</code> to close either mode for the current boot. (<code>stop webconfig</code> does not change a saved <code>webui on</code>.) LAN mode otherwise remains active until reboot. On expanded FULL builds, an unconfigured automatic setup AP receives one absolute 30-minute window per boot, then powers WiFi off even if a client remains attached; rebooting starts a new automatic window. An administrator can explicitly run <code>start webconfig</code> again without rebooting. Once an SSID is saved, the cutoff no longer applies and the selected WiFi/MQTT mode keeps reconnecting. Other setup sessions retain their profile's idle timeout.</p> <p>Every ESP32 build with WebConfig supports the browser command terminal, including WiFi Companion and Full Companion. Companions use their complete USB/TCP terminal on the trusted LAN, including contact import, chat, recipient selection, and delayed replies. Repeater and Room Server use their local CLI after admin authentication.</p> <p>To add a Companion contact, run <code>import meshcore://&lt;full-contact-card-data&gt;</code>, then <code>list</code> to confirm it appears. Get the complete card with <code>card</code> on the other Companion. A public key alone is insufficient. See the terminal command guide for <code>to</code>, <code>send</code>, <code>login</code>, and <code>cmd</code> examples and session ownership.</p> <p>The saved <code>wifi.cli</code> setting defaults to <code>on</code>. Use <code>set wifi.cli off</code> to disable the CLI tab. <code>get wifi.cli</code> reports <code>off</code>, <code>on, waiting for WiFi client</code>, or <code>on, active</code>. The saved setting becomes active only in station/LAN mode while the WiFi client is connected. It is deliberately unavailable on the open setup access point. The tab displays each reply in the browser, including local diagnostics, <code>get password</code>, private-key and WiFi/MQTT credential reads, and <code>erase</code>. Infrastructure <code>get acl</code> and raw <code>log</code> stream to the requesting browser, with backpressure for slow clients. These maintenance commands retain their LoRa restrictions. <code>set freq</code> works both here and through authorized LoRa CLI. The bounded <code>/api/cli</code> endpoint accepts local maintenance commands; use <code>/api/terminal</code> for complete ACL and log listings. Select Command block to paste up to 100 commands with one command per line. Blank lines are ignored, and every nonblank line must fit the normal 159-byte CLI command limit. The browser sends the lines sequentially and waits for each reply before sending the next line. The queue exists only in that browser page; closing it stops any commands that have not yet been sent. A lost connection also stops the remaining block.</p> <p>Up/down arrow keys recall commands from the current browser session in single-command mode. A command that stops WebConfig, changes its WiFi connection, disables <code>wifi.cli</code>, or reboots the node stops the remaining block and can close the page before its reply is collected.</p> <p>On unified FULL USB + WiFi and FULL logging-fallback ESP32 repeater/room-server builds, <code>get wifi.ssid</code> reports the saved standalone WebConfig network and <code>get wifi.status</code> reports whether WiFi is unconfigured, off, connecting, running the setup AP, failed, or connected. A connected result includes the SSID, LAN IP, and RSSI. When the shared OTA seeder is running, the reply appends <code>OTA TCP 5001: listening</code> or <code>OTA TCP 5001: client connected</code>. WiFi being off is normal while WebConfig is inactive; run <code>start webconfig</code> when a temporary connection is wanted. <code>get wifi.powersave</code> reports the saved standalone setting as <code>none</code>, <code>min</code>, or <code>max</code>. Fresh Cascade-profile builds default to <code>min</code>; target-default builds use <code>none</code>. A saved setting takes precedence after an upgrade.</p> <p>The WiFi <code>set</code> commands work on MQTT observers and on FULL standalone ESP32 repeater/room-server builds. On a standalone build, changing the SSID or password stops an active WebConfig session; run <code>start webconfig</code> again to use the new credentials. <code>set wifi.pwd</code> with no value selects an open network. Standalone WiFi also accepts an exact 64-character hexadecimal WPA/WPA2 PSK; ordinary passphrases remain limited to 63 characters. Other 64-character values and all longer values are rejected. MQTT observer WiFi passwords retain their fixed 63-character limit. Power-save changes are applied immediately when WiFi is running and otherwise take effect on the next connection. <code>get wifi.pwd</code> returns the saved password on a local connection. It remains unavailable or masked over LoRa, and the configuration form continues to mask stored secrets.</p> <p>ESP32 WiFi Companion WebConfig exposes the same <code>wifi.powersave</code> values in its WiFi card. Every ESP32 WiFi Companion with WebConfig exposes the standalone <code>wifi.ssid</code>, <code>wifi.status</code>, <code>wifi.powersave</code>, <code>wifi.cli</code>, and WebConfig command families through its USB text terminal. Full Companion exposes the same role-specific terminal on TCP port 5002. Credential writes reply before restarting the WiFi station, so a TCP client should expect to reconnect at the new address; USB password input is masked. Binary Companion clients can use USB, BLE, or TCP port 5000 without the terminal-start token: send command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>) followed by the same CLI text, such as <code>get wifi.powersave</code>, <code>get wifi.pwd</code>, <code>stats-core</code>, or <code>set wifi.powersave min</code>. See local maintenance commands for the complete access rules. WiFi-only Companions accept all three modes. A Full Companion that runs BLE and infrastructure WiFi simultaneously rejects <code>none</code> because coexistence requires modem sleep. Companion device power saving and LoRa <code>radio.rxps</code> remain independent. On an ESP32 Full Companion whose primary mesh radio is ESP-NOW, <code>max</code> is also unavailable: a station using maximum modem sleep can miss ESP-NOW broadcasts, which the access point does not buffer for it. A previously saved conflicting value is capped to and reported as <code>min</code>, and a new conflicting selection is rejected. The primary mesh radio also holds the ESP-IDF WiFi wake reference continuously so unsolicited ESP-NOW frames remain receivable; selecting <code>min</code> does not put that primary receiver to sleep.</p> <p>SenseCAP Indicator Full is the exclusive-secondary exception. On a WiFi-selected boot, LoRa accepts <code>none|min|max</code> and ESP-NOW accepts <code>none|min</code>. On a BLE-selected boot infrastructure WiFi is not started; LoRa accepts <code>min|max</code> for the saved WiFi setting, while ESP-NOW + BLE requires <code>min</code>. USB and the primary LoRa or ESP-NOW radio remain available in every mode.</p>"},{"location":"cli_commands/#view-or-change-the-primary-esp-nowwifi-channel","title":"View or change the primary ESP-NOW/WiFi channel","text":"<p>Usage:</p> <ul> <li><code>get espnow.channel</code></li> <li><code>set espnow.channel &lt;channel&gt;</code></li> </ul> <p>Parameters:</p> <ul> <li><code>channel</code>: Shared 2.4 GHz WiFi channel from <code>1</code> through <code>13</code>; choose one   permitted in your region and supported by the router.</li> </ul> <p>Default: <code>1</code></p> <p>This command is available when ESP-NOW is the node's primary mesh radio. The setting is persisted. A <code>set</code> reply reports that reboot is required; until reboot, the running ESP-NOW radio remains on its previous channel. On builds that also provide ordinary WiFi, its station and setup AP share that channel.</p> <p>After reboot, ESP-NOW, the setup AP, and the infrastructure-WiFi station use the selected channel. Every primary ESP-NOW node that must communicate with this node, plus the configured router's 2.4 GHz radio, must use the same fixed channel. WiFi power saving does not allow the transports to use different channels. On an ESP32 Full build with primary ESP-NOW, <code>wifi.powersave max</code> is unavailable because maximum modem sleep can miss ESP-NOW broadcasts; use <code>min</code> for coexistence. The firmware keeps the primary ESP-NOW receiver awake while still using the <code>min</code> WiFi/Bluetooth coexistence policy.</p> <p><code>espnow.channel</code> is the channel of the primary ESP-NOW mesh transport. It is separate from <code>bridge.channel</code>, which configures only an ESP-NOW bridge on a firmware role whose primary mesh radio is LoRa.</p> <p>The browser portal is not compiled into the two 4 MB <code>LilyGo_TLora_V2_1_1_6_*_observer_mqtt</code> targets because it does not fit while retaining the two app slots required for LoRa OTA. Their normal CLI settings remain available.</p>"},{"location":"cli_commands/#erasefactory-reset","title":"Erase/Factory Reset","text":"<p>Search terms: factory defaults, reset settings, erase configuration.</p> <p>Usage: - <code>erase</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p>Warning: This is destructive!</p>"},{"location":"cli_commands/#neighbors-repeater-only","title":"Neighbors (Repeater Only)","text":""},{"location":"cli_commands/#list-nearby-neighbors","title":"List nearby neighbors","text":"<p>Search terms: nearby nodes, neighbor list, neighbour list.</p> <p>Usage:  - <code>neighbors</code></p> <p>Note: The output of this command is limited to the 8 most recent adverts.</p> <p>Note: Each line is encoded as <code>{pubkey-prefix}:{timestamp}:{snr*4}</code></p>"},{"location":"cli_commands/#remove-a-neighbor","title":"Remove a neighbor","text":"<p>Usage:  - <code>neighbor.remove &lt;pubkey_prefix&gt;</code> - <code>neighbor.remove</code> \u2014 remove all neighbors</p> <p>Parameters:  - <code>pubkey_prefix</code>: An even-length hexadecimal prefix (up to the full 64-character   public key). All neighbors matching it are removed. Invalid keys are rejected.</p> <p>Omitting the prefix clears the table. An empty or whitespace-only prefix is also accepted for compatibility with the mobile app's Remove All Neighbors action. Newly heard zero-hop adverts can populate the table again.</p>"},{"location":"cli_commands/#discover-zero-hop-neighbors","title":"Discover zero hop neighbors","text":"<p>Usage:  - <code>discover.neighbors</code></p> <p>This command is available in every repeater build profile, including portable MQTT, standard, logging, OTA, unified FULL, and FULL logging-fallback artifacts. It does not require MQTT or PSRAM.</p>"},{"location":"cli_commands/#discover-neighbor-scopes-mqtt-observer-neighbors-feature","title":"Discover neighbor scopes (MQTT observer, neighbors feature)","text":"<p>Refreshes the zero-hop neighbor table, then queries each neighbor for its region scopes and publishes the assembled table to the MQTT <code>neighbors</code> topic once.</p> <p>Usage: - <code>discover.scopes</code></p> <p>Note: Requires an MQTT observer build with the neighbors feature compiled in (all PSRAM boards, plus non-PSRAM boards built with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>). Elsewhere it replies <code>Err - neighbors not enabled in this build</code>. If a <code>discover.neighbors</code> refresh is already in flight, the scope pass is queued behind it.</p>"},{"location":"cli_commands/#statistics","title":"Statistics","text":""},{"location":"cli_commands/#list-rate-limited-flood-adverts","title":"List Rate-Limited Flood Adverts","text":"<p>Usage: <code>get flood.advert [page]</code> or <code>get flood.advert key &lt;index&gt;</code></p> <p>Lists tracked advert origins currently subject to a forwarding limit. Page 1 is the default, with three entries per page so replies fit both USB and admin LoRa CLI. Each row shows its index, the first 12 public-key hex characters, the limit reason, and the minimum wait before another new advert can pass the automatic limiter. Ordinary forwarding filters still apply.</p> <pre><code>get flood.advert\nget flood.advert 2\nget flood.advert key 1\n</code></pre> <p>Reasons are <code>quota</code> (the prefix's three-hour forwarding allowance is spent), <code>history</code> (distinct receive history is full), and <code>bad</code> (the full key is under the stricter one-advert-per-12-hours rule). A <code>bad</code> key remains listed when <code>wait=0s</code>: one forward is eligible, but its seven-day recovery is not complete. If several limits apply, <code>bad</code> takes precedence over <code>history</code>, then <code>quota</code>; the displayed wait accounts for all applicable limits.</p> <p>The <code>key</code> form returns the complete 64-hex public key, reason, wait, shared prefix forwarding count/quota, shortest received hop count, and remaining bad-list recovery time. Different full keys with the same 12-hex prefix remain separate entries. Indices refer to the current live list and can change as history expires; read the full key before using a targeted clear.</p> <p>Queries do not clear history, spend quota, or refresh abuse/recovery timers. Elapsed history expires normally. Origins rejected only because every table slot protects abuse history are not retained and cannot be enumerated. Available on repeaters, room servers, and forwarding sensors through their ordinary local/admin CLI. Companions do not have this table.</p>"},{"location":"cli_commands/#clear-automatic-flood-advert-history","title":"Clear Automatic Flood Advert History","text":"<p>Usage: <code>clear flood.advert all</code> or <code>clear flood.advert &lt;64-hex-full-public-key&gt;</code></p> <p>Clears automatic advert forwarding quotas, first strikes, and seven-day bad-list history for all keys or one exact full key. Available on repeaters, room servers, and forwarding sensors through their ordinary local/admin CLI (including admin LoRa CLI). A missing selector, a key prefix, or a malformed key is rejected. It does not change saved settings or manual flood rules. Reboot also clears this RAM-only history. See automatic advert limits.</p>"},{"location":"cli_commands/#clear-stats","title":"Clear Stats","text":"<p>Usage: <code>clear stats</code></p> <p></p>"},{"location":"cli_commands/#system-stats-battery-uptime-queue-length-and-debug-flags","title":"System Stats - Battery, Uptime, Queue Length and Debug Flags","text":"<p>Usage:  - <code>stats-core</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p></p>"},{"location":"cli_commands/#radio-stats-noise-floor-last-rssisnr-airtime-receive-errors","title":"Radio Stats - Noise floor, Last RSSI/SNR, Airtime, Receive errors","text":"<p>Search terms: signal strength, signal quality, RSSI, SNR, radio noise.</p> <p>Usage: <code>stats-radio</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p></p>"},{"location":"cli_commands/#packet-stats-packet-counters-received-sent","title":"Packet stats - Packet counters: Received, Sent","text":"<p>Usage: <code>stats-packets</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p></p>"},{"location":"cli_commands/#read-repeater-and-room-server-telemetry-history","title":"Read repeater and room-server telemetry history","text":"<p>Repeater and room-server firmware record one UTC-aligned sample every 30 minutes. Temperature and battery voltage retain 336 samples (seven rolling days). Each detected INA219, INA226, INA260, or INA3221 voltage channel retains 192 samples (four rolling days). GPS-capable builds retain three GPS days by default; repeaters request a seven-day default at startup. Builds without a GPS provider omit the GPS history commands to conserve flash. All history and any runtime retention change are held in RAM and reset after a reboot.</p> <p>The feature is omitted from flash-constrained STM32 repeater and room images.</p> <p>Usage:</p> <ul> <li><code>get telemetry.temp [page]</code></li> <li><code>get telemetry.volt [page]</code></li> <li><code>get telemetry.volt.i2c [channel [page]]</code></li> <li><code>get telemetry.gps [page]</code></li> <li><code>set telemetry.gps &lt;days&gt;</code></li> <li><code>get telemetry.tx</code></li> <li><code>set telemetry.tx &lt;off|direct|path&gt;</code></li> <li><code>set telemetry.tx schedule &lt;off|1-30d&gt;</code></li> <li><code>send telemetry.tx now</code></li> <li><code>get data.tx</code></li> <li><code>get data.tx path</code></li> <li><code>set data.tx path &lt;direct|none|path&gt;</code></li> <li><code>get data.tx region</code></li> <li><code>set data.tx region &lt;auto|default|none|name&gt;</code></li> </ul> <p>Parameters:</p> <ul> <li><code>page</code>: Page <code>1</code> is always newest. Temperature and voltage pages each hold   24 hours and accept <code>1</code>-<code>7</code>. GPS pages each hold 12 hours and accept <code>1</code>   through twice the current GPS retention in days. Omitting the page selects   page <code>1</code>.</li> <li><code>channel</code>: Cayenne LPP channel assigned to an external voltage monitor.   <code>get telemetry.volt.i2c</code> lists channels that have at least one non-zero   sample. Supplying a channel returns 48 points (24 hours) per page; pages   <code>1</code>-<code>4</code> cover all four days. A detected input whose complete retained history   is zero is treated as disconnected and is omitted until it reports a   non-zero voltage. An INA3221 contributes three consecutive entries, in   hardware-input order. If it is the only detected external sensor these are   normally LPP channels <code>2</code>, <code>3</code>, and <code>4</code>; always use the no-argument command   as the authoritative list because earlier detected sensors shift the LPP   numbers.</li> <li><code>days</code>: Requested GPS retention from <code>1</code> through <code>30</code> days. Retention above   three days uses heap memory. The allocator reduces the requested value as   needed to leave at least 2048 bytes free and replies with the days and pages   actually available. For example, a request can return   <code>OK - telemetry.gps days=18 pages=36 requested=30</code>.</li> <li><code>direct</code>: Set the shared <code>data.tx</code> path to zero-hop and, in the legacy   combined command, enable the telemetry schedule.</li> <li><code>path</code>: A comma-separated direct route using the same one-, two-, or   three-byte hop hashes accepted by <code>set outpath</code>.</li> <li><code>schedule</code>: Automatic interval in whole days. Automatic transmission is off   on a fresh install. The retained cadence defaults to <code>2d</code>; <code>off</code> retains the   shared route for manual test sends.</li> </ul> <p>Local serial and remote administrator CLI sessions can read the history on both roles. Collection uses the MCU temperature, battery voltage, external I2C voltage monitors, and an already-valid onboard GPS fix. It does not wake GPS, so an off, sleeping, or unfixed GPS produces a missing location sample without changing its power-saving schedule.</p> <p>External voltage history allocates 360 bytes for each detected monitor channel (1,080 bytes for all three INA3221 inputs). The allocation reserves all detected inputs so a sensor connected later can start recording, but all-zero inputs are omitted from command replies and LoRa transmission.</p> <p>Replies contain <code>&gt;</code> followed by standard padded Base64. After decoding, all multi-byte integers are little-endian. Packed fields are written most significant bit first, oldest sample first.</p> <p>Use the browser-based Telemetry history decoder to turn a reply into a timestamped table or downloadable CSV without uploading the data.</p> <p><code>telemetry.tx</code> is disabled by default. Its enabled state and cadence are stored separately from the shared <code>data.tx</code> path and region. <code>data.tx</code> defaults to zero-hop <code>direct</code> plus <code>region=auto</code>, but it does not enable telemetry or any other producer. For compatibility, <code>set telemetry.tx direct|path</code> updates the shared path and enables the default <code>2d</code> schedule; new configuration should use <code>set data.tx path ...</code> followed by <code>set telemetry.tx schedule ...</code>. An automatic run waits until 165 half-hour positions are available, then sends one maximum-size temperature packet, one maximum-size battery-voltage packet, and up to three <code>IVB1</code> packets for every populated I2C voltage channel. GPS is never included in this raw transmission. The history remains boot-local, so the first scheduled run after a reboot needs about 82.5 hours to fill. On the default two-day interval, each 82.5-hour temperature or battery packet overlaps its predecessor by 34.5 hours. Packets are paced two seconds apart. A queue failure is retried after 30 minutes only for the packet that did not queue; successfully queued packets are not duplicated.</p> <p><code>send telemetry.tx now</code> is an administrator-only test action. It queues temperature and battery-voltage snapshots plus the available I2C voltage chunks over the configured path. It uses all currently available base positions up to 165 and all available I2C positions up to 192 per populated channel. It works while the schedule is off and does not move the next scheduled send time. RAW_CUSTOM direct packets do not enter the normal encrypted direct-message retry mechanism.</p> <p>Full snapshots are 184-byte RAW_CUSTOM payloads. Manual tests can be shorter while history fills. Both formats are binary, not Base64 and not encrypted:</p> Bytes Meaning <code>0</code>-<code>3</code> ASCII magic <code>TTB1</code> for temperature or <code>TVB1</code> for voltage <code>4</code>-<code>11</code> First eight bytes of the repeater public key <code>12</code>-<code>15</code> First sample UTC epoch, unsigned 32-bit little-endian <code>16</code>-<code>17</code> Sample interval in minutes, unsigned 16-bit little-endian (<code>30</code>) <code>18</code> Sample count (<code>1</code>-<code>165</code>) <code>19</code> onward Oldest-to-newest encoded samples for the selected series <p>Temperature codes reserve <code>0</code> for no reading, <code>1</code> for below <code>-50 C</code>, and <code>2</code> for above <code>+77 C</code>. Codes <code>3</code> through <code>130</code> represent exact whole degrees from <code>-50 C</code> through <code>+77 C</code>; decode them as <code>code - 53</code>. Voltage codes use the same encoding as the paged voltage payload documented below.</p> <p>External voltage snapshots use a separate packed layout. A full four-day channel takes three 140-byte <code>IVB1</code> payloads of 64 points each:</p> Bytes Meaning <code>0</code>-<code>3</code> ASCII magic <code>IVB1</code> <code>4</code>-<code>11</code> First eight bytes of the source public key <code>12</code>-<code>15</code> First sample UTC epoch, unsigned 32-bit little-endian <code>16</code>-<code>17</code> Sample interval in minutes, unsigned 16-bit little-endian (<code>30</code>) <code>18</code> Cayenne LPP voltage channel <code>19</code> Sample count (<code>1</code>-<code>64</code>) <code>20</code> onward Oldest-to-newest packed 15-bit voltage codes <p>Code <code>0</code> means missing or disconnected. Codes <code>1</code>-<code>32767</code> represent <code>0.02 V</code> through <code>655.34 V</code> in <code>0.02 V</code> steps; decode millivolts as <code>code * 20</code>.</p> <p>Match bytes <code>4</code>-<code>11</code> to the first 16 hex characters of the repeater public key shown by its advert or <code>get public.key</code>. This compact identifier is useful for association but is not authenticated and can be spoofed. An MQTT observer can upload the received raw packet to LetsMesh Analyzer <code>/packets</code>; its packet hex contains the direct-route header and path followed by this payload.</p> <p>Temperature payload (<code>0x11</code>, 61 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x11</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>48</code>) <code>7</code>-<code>18</code> 48 packed 2-bit temperature statuses <code>19</code>-<code>60</code> 48 packed 7-bit temperatures <p>Temperature status codes are <code>0</code> none, <code>1</code> value, <code>2</code> below range, and <code>3</code> above range. For status <code>1</code>, the 7-bit temperature is an exact whole-degree integer from <code>-50 C</code> through <code>+77 C</code>; decode it as <code>code - 50</code>. Low values use code <code>0</code>, and high values use code <code>127</code>. The separate status map is required because 7 bits contain exactly 128 codes, leaving no spare code for none, low, or high when the complete range is represented at 1 C resolution. No fractional temperature is stored or transmitted.</p> <p>Voltage payload (<code>0x12</code>, 55 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x12</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>48</code>) <code>7</code>-<code>54</code> 48 8-bit voltage codes <p>Voltage codes reserve <code>0</code> for no reading, <code>1</code> for below <code>1.88 V</code>, and <code>255</code> for above <code>4.40 V</code>. Codes <code>2</code>-<code>254</code> represent <code>1.88 V</code> through <code>4.40 V</code> in <code>0.01 V</code> steps; decode millivolts as <code>1880 + (code - 2) * 10</code>.</p> <p>External I2C voltage payload (<code>0x14</code>, 98 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x14</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>48</code>) <code>7</code> Cayenne LPP voltage channel <code>8</code>-<code>97</code> 48 packed 15-bit voltage codes <p>The codes have the same <code>0.02 V</code> through <code>655.34 V</code> meaning as <code>IVB1</code>.</p> <p>GPS payload (<code>0x13</code>, 101 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x13</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>24</code>) <code>7</code>-<code>10</code> Page origin latitude in signed degrees times <code>10^7</code> <code>11</code>-<code>14</code> Page origin longitude in signed degrees times <code>10^7</code> <code>15</code> Origin sample index, or <code>255</code> when the page has no GPS fix <code>16</code> Flags; bit 0 means at least one differential was clipped <code>17</code>-<code>100</code> 24 records: signed 14-bit north then signed 14-bit east <p>GPS differentials use signed 14-bit two's-complement values at 10-meter resolution and are applied to the preceding decoded valid point. The origin sample begins at the header coordinates. A no-fix slot encodes <code>0,0</code> and does not advance the reference; a stationary valid fix also quantizes to <code>0,0</code>. When a page has no fixes, its origin is <code>0,0</code>, origin index is <code>255</code>, and all differentials are <code>0,0</code>. Values outside <code>-8192</code> through <code>8191</code> are clipped and set flag bit 0.</p>"},{"location":"cli_commands/#set-companion-tx-routing-per-contact-or-channel","title":"Set Companion TX routing per contact or channel","text":"<pre><code>set tx.user \"Alice Jones\" radio2\nget tx.user \"Alice Jones\"\nset tx.channel 0 both\nget tx.channel 0\nset tx.channel #wardriving radio\n</code></pre> <p>Both command families accept <code>auto</code>, <code>radio</code>, <code>radio2</code>, <code>both</code>, or <code>off</code>. <code>auto</code> uses the global crossing rules. Explicit choices override <code>radio2.cross</code>, but radio2 must still be enabled in <code>rxtx</code> to transmit there. <code>radio2</code> never falls back to the primary profile; <code>both</code> uses whichever of its selected profiles can transmit. Set a target back to <code>auto</code> to remove its override.</p> <p>Use an exact contact/channel name, a zero-based channel index, or <code>key:&lt;12-64 hex digits&gt;</code> for a unique contact public-key prefix. Duplicate names/prefixes are rejected. <code>get tx.user</code> and <code>get tx.channel</code> show override counts; queries with a target show its saved choice and current effective profile selection. Choices are saved with the contact/channel and work for phone-app and terminal messages. A contact's <code>off</code> setting also blocks its ACKs and addressed responses.</p> <p>See Companion routing details and examples for temporary profiles, persistence, and the traffic covered by each setting.</p>"},{"location":"cli_commands/#set-repeater-room-server-and-sensor-reply-profiles","title":"Set repeater, room-server, and sensor reply profiles","text":"<pre><code>get tx.reply\nset tx.reply both\nset tx.reply both force\nset tx.reply radio\nset tx.reply auto\n</code></pre> <p>Persistent choices: <code>auto</code>, <code>radio</code>, <code>radio2</code>, <code>both</code> (default), and <code>off</code>. Explicit choices override <code>radio2.cross</code> for local replies, including CLI, ACKs, telemetry, room subscription posts, and served LoRa OTA responses. Append <code>force</code> to <code>both</code> or <code>radio2</code> to permit reply TX on an active RX-only second profile. It never enables a disabled profile or ordinary forwarding. Omitting <code>force</code> removes that override. <code>off</code> suppresses remote replies too.</p> <p>See reply routing and OTA examples for temporary profiles, receive-only exceptions, and queued reply handling.</p>"},{"location":"cli_commands/#set-companion-display-rotation","title":"Set Companion display rotation","text":"<p>SSD1306 Full Companion builds support a persisted runtime orientation:</p> <pre><code>get display.rotation\nset display.rotation 0\nset display.rotation 90\nset display.rotation 180\nset display.rotation 270\n</code></pre> <p>The values are clockwise degrees. <code>0</code> clears the override and restores the board's compiled default. Unsupported display drivers return an error.</p>"},{"location":"cli_commands/#show-touchscreen-touch-areas","title":"Show touchscreen touch areas","text":"<p>All touchscreen Companion builds using the shared touch UI support temporary diagnostic outlines, including both SenseCAP Indicator rendering sizes:</p> <pre><code>get display.touch\nset display.touch on\nset display.touch off\n</code></pre> <p>The default is off at every boot. Enabling wakes the display without selecting anything. Dotted yellow borders mark the actual scaled tap targets; the area under a held finger turns green and returns to yellow on release. Disabling removes the borders on the next redraw. Pairing screens suppress the overlay while they consume navigation. This option does not change the font, touch calibration, navigation actions, or saved settings, and is not persisted.</p> <p>Use the text terminal or Companion framed CLI (<code>0x42</code>) through an available USB, BLE, or TCP connection. Non-touchscreen, missing-display, and legacy UI builds report <code>Error: touchscreen diagnostics unsupported</code>. No Indicator-only build flag is needed.</p>"},{"location":"cli_commands/#set-display-modes-and-timeouts","title":"Set display modes and timeouts","text":"<p>Display-equipped Companions, repeaters, room servers, and sensors have four saved settings. The WebConfig Display card exposes the same controls:</p> Setting CLI Default Battery mode <code>get/set display.mode</code> <code>button-pairing</code> on BLE Companions; <code>button</code> elsewhere Battery timeout, seconds <code>get/set display.timeout</code> <code>15</code> USB mode <code>get/set display.usb.mode</code> Same as battery mode USB timeout, seconds <code>get/set display.usb.timeout</code> <code>15</code> <p>Modes are <code>off</code>, <code>on</code>, <code>button</code>, <code>pairing</code>, <code>button-pairing</code>, and <code>automatic</code>. Pairing modes are available only on builds supporting BLE pairing.</p> <ul> <li><code>off</code>: stays dark, including boot and pairing.</li> <li><code>on</code>: stays on while the device is awake.</li> <li><code>button</code>: a physical button, keyboard/navigation input, or supported touch   wakes the display and restarts the timeout.</li> <li><code>pairing</code>: wakes only for an actual BLE PIN request, until pairing ends or   expires. The inactivity timeout does not shorten the pairing prompt.</li> <li><code>button-pairing</code>: combines the button and pairing behaviors.</li> <li><code>automatic</code>: shows startup briefly (at most four seconds), and wakes for   messages while the app is disconnected. An app connection blanks the screen;   buttons and pairing requests can still wake it. Disconnecting alone does not   wake it. Network traffic and screen redraws do not extend the timeout.</li> </ul> <p>Timeouts are whole seconds from <code>1</code> to <code>3600</code>. Use mode <code>on</code> for a permanent display rather than timeout <code>0</code>. The timeout is retained but unused in <code>off</code>, <code>on</code>, and <code>pairing</code> modes. Settings apply immediately, including while blanked; changing power source applies the other profile without carrying over a wake from the previous profile. Settings survive reboot and filesystem-preserving updates in <code>/display_prefs</code>; erasing the filesystem restores the defaults. An existing observer timeout that differs from its old 60-second default is migrated once to both power profiles; an old zero timeout becomes mode <code>on</code>.</p> <pre><code>set display.mode button-pairing\nset display.timeout 15\nset display.usb.mode on\nset display.usb.timeout 60\n</code></pre> <p>USB profile selection uses the board's external-power detector, with USB-host detection as a fallback. VBUS-capable boards detect chargers without a data connection. Heltec V4 R8 uses either a detected USB host or a calibrated battery voltage above 4.21 V. The voltage estimate is checked every five seconds and clears at 4.20 V or below; host detection takes effect immediately. This estimate can miss a charger while the battery is low, depends on ADC calibration, and cannot distinguish USB from solar charging. Other boards without a power detector may require a USB host to recognize USB power. Wi-Fi/MQTT connection or BLE pairing is not evidence of USB power. E-paper panels can retain their last image when powered off.</p>"},{"location":"cli_commands/#set-companion-inbox-behavior","title":"Set Companion inbox behavior","text":"<p>The shared Companion UI (including T114 and R8) defaults to History: the last 32 received text previews remain available on the radio after an app downloads them. Pending separately counts frames waiting for the app, including non-text frames. Downloading a frame clears it from Pending; it does not mean someone read it. The phone's delivery queue is independent of the 32-entry preview history and is never drained by reading on the radio.</p> <pre><code>get display.inbox\nset display.inbox history\nset display.inbox pending\nset display.inbox unread\n</code></pre> Mode Display behavior <code>history</code> (default) Shows HISTORY with the retained preview count, plus Pending. Downloaded previews remain browseable. <code>pending</code> Shows INBOX with the app queue count and limits the reader to previews still waiting for the app. Non-text frames count toward Pending but have no text preview. <code>unread</code> Shows UNREAD with the number of retained previews not yet displayed on the radio, plus Pending. Opening a preview on a lit display marks it read; app downloads do not. Read previews remain browseable. <p>All modes retain up to 32 previews internally; switching from <code>pending</code> back to <code>history</code> makes retained downloaded previews visible again. Evicted or rejected queue entries are not shown as pending. Previews and local read state are in RAM and reset on reboot. The mode applies immediately and survives reboot in <code>/display_prefs</code>; existing version-1 display settings load with <code>history</code> as the default. Legacy and tiny Companion UIs report <code>Error: inbox modes unsupported</code>.</p> <p>Incoming messages automatically open their preview only when no client is connected. While connected, new messages neither select another page nor move the preview being read; history stays accessible by button or touch. The home screen identifies connected USB and Bluetooth clients (or both), and TCP, Ethernet, or serial clients where supported. Actual BLE pairing prompts retain priority over connection status.</p>"},{"location":"cli_commands/#set-mqtt-observer-display-flip","title":"Set MQTT observer display flip","text":"<p>Supported observer displays, including the R8 OLED and ST7789 panels, can also be turned 180 degrees relative to their compiled orientation:</p> <pre><code>get display.flip\nset display.flip off\nset display.flip on\n</code></pre> <p><code>0</code> and <code>1</code> are accepted aliases for <code>off</code> and <code>on</code>. This is intentionally different from Full Companion <code>display.rotation</code>: observer <code>display.flip</code> is a relative 180-degree mounting choice and cannot switch between portrait and landscape. The value is harmless on an observer display driver that does not support flipping.</p> <p>Flip survives reboot and firmware updates that preserve the filesystem; erasing flash restores the <code>off</code> default. The boot log reports the saved flip state on display-enabled observer builds.</p>"},{"location":"cli_commands/#logging","title":"Logging","text":"<p>Builds compiled with <code>MESH_PACKET_LOGGING</code> emit one <code>RAW:</code> line for every received radio frame. Serial output uses backpressure: if a connected host temporarily stops reading, packet processing waits for USB transmit space instead of silently omitting the record. A disconnected host cannot retain an unbounded capture, so logging deployments should keep the reader attached and draining the serial port.</p> <p>Every valid received frame also emits the decoded RX summary, including signal, timing, hash, type, route, and payload information. Frames that cannot be decoded still emit their <code>RAW:</code> line. Transmitted packets emit the decoded TX summary.</p> <p>Ordinary non-OTA artifacts compile packet logging into the canonical image and control its live USB output at runtime; no separate <code>-logging-</code> artifact is emitted. Use the separately named <code>-ota-</code> artifact when LoRa OTA is required. A <code>-full-usb-wifi-ota-</code> artifact combines USB packet logging, direct WiFi MQTT, LoRa OTA, and the expanded FULL feature set. A <code>-full-logging-ota-</code> artifact is emitted only when that hardware/role has no matching WiFi MQTT environment.</p>"},{"location":"cli_commands/#control-live-usb-logging","title":"Control live USB logging","text":"<p>Search terms: serial logging, USB debug log, enable logging, disable logging, debug output.</p> <p>Usage:</p> <pre><code>get usb.logging\nset usb.logging on\nset usb.logging off\nset usb.logging on reboot\nset usb.logging off reboot\n</code></pre> <p>ESP32 1.17.1.5 USB logging procedure: disable device sleep before enabling the log stream, using separate text commands:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>Verify with <code>get powersaving</code> (expect <code>off</code>) and <code>get usb.logging</code> (expect <code>on</code>). Both settings are saved; disabling logging later does not restore power saving. This works around the released USB sleep bug. nRF52 does not need this ESP32 workaround.</p> <p>These commands are compiled into ordinary USB-loggable artifacts and every Full Companion. They control live USB debug and packet output. CommonCLI roles save the setting in <code>/com_prefs</code>, so it survives reboot; their first boot defaults to on. Full Companion and ordinary USB Companion start off on a fresh installation so diagnostics cannot corrupt framed traffic.</p> <p>On Full Companion these lines belong to its text terminal, not <code>meshcli</code>'s Binary <code>get/set</code> parameter namespace. Open interface <code>00</code>, send <code>+++MESHCORE-TERM-START</code>, and then issue the command. Running <code>meshcli ... get usb.logging</code> directly can instead return <code>Unknown var usb.logging</code> because that is a different protocol operation.</p> <p>nRF52 Full Companion defaults logging to off and enumerates only USB interface <code>00</code>, which carries Companion, terminal, and serial mOTA traffic. Enabling logging adds interface <code>02</code>, its dedicated plaintext logging port, on the next boot. Disabling it removes interface <code>02</code> on the next boot. A command without the optional <code>reboot</code> argument saves the choice and reports that a reboot is required when the USB interface count must change. The exact <code>set usb.logging on reboot</code> and <code>set usb.logging off reboot</code> forms save the choice, send their reply, and reboot one second later only when needed.</p> <p>On every ESP32 Full Companion, enter the USB text terminal and use <code>set usb.logging on</code> (preceded by <code>set powersaving off</code> on 1.17.1.5) to turn that TTY into a logging-repeater-style plaintext stream. Framed Binary Companion is unavailable on USB while logging is on. The TTY remains an input-capable CLI, so <code>set usb.logging off</code> works on the same TTY. After its reply, logging stops and the TTY remains in the normal ASCII terminal, just as it does after a fresh Full installation. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch it to Binary Companion. No reboot is needed because the USB interface count does not change.</p> <p>Turning USB logging off does not disable CLI replies. nRF52 keeps Companion frames active on interface <code>00</code>; ESP32 resumes the ordinary ASCII/Binary switcher after the logging terminal turns logging off. This setting does not change the node-storage capture controlled by <code>log start</code> and <code>log stop</code>.</p> <p>Companion, Repeater, Room Server, and Sensor builds with both MQTT and USB logging provide the same saved selector for both output paths:</p> <pre><code>get logging.output\nset logging.output off\nset logging.output usb\nset logging.output wifi\nset logging.output both\n</code></pre> <p><code>usb</code> emits <code>RAW:</code> packets for a USB-connected service such as meshcoretomqtt. <code>wifi</code> enables the direct MQTT bridge configured by the <code>wifi.*</code> and <code>mqtt.*</code> commands. <code>both</code> intentionally duplicates the radio stream to both consumers; do not point both consumers at the same broker unless the downstream setup deduplicates messages. Fresh unified Full infrastructure installs start in <code>both</code> mode; Full Companion starts with USB logging off. To change only MQTT, use <code>set mqtt.enabled on|off</code>; <code>get mqtt.enabled</code> checks the saved switch and <code>get mqtt.running</code> checks whether the MQTT service is running. Turning MQTT off preserves all broker slots and credentials.</p> <p>On 1.17.1.5 ESP32, run <code>set powersaving off</code> before selecting <code>set logging.output usb</code> or <code>set logging.output both</code>, since those modes enable USB logging. WiFi/MQTT-only logging does not need this workaround while the Repeater/Room Server MQTT bridge is running; the released code already blocks device sleep in that state. Check <code>get mqtt.running</code>, not only <code>get mqtt.enabled</code>. WiFi modem power saving is a separate setting.</p>"},{"location":"cli_commands/#begin-capture-of-rx-log-to-node-storage","title":"Begin capture of rx log to node storage","text":"<p>Search terms: save logs, record received packets, RX logging, stored packet log.</p> <p>Usage: <code>log start</code></p>"},{"location":"cli_commands/#end-capture-of-rx-log-to-node-storage","title":"End capture of rx log to node storage","text":"<p>Usage: <code>log stop</code></p>"},{"location":"cli_commands/#erase-captured-log","title":"Erase captured log","text":"<p>Usage: <code>log erase</code></p> <p></p>"},{"location":"cli_commands/#print-the-captured-log-to-the-requesting-terminal","title":"Print the captured log to the requesting terminal","text":"<p>Usage: <code>log</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p>"},{"location":"cli_commands/#info","title":"Info","text":""},{"location":"cli_commands/#get-the-version","title":"Get the Version","text":"<p>Usage: <code>ver</code></p> <p>On Full Companion, the Binary device-info frame retains its legacy fixed-width version field. Use <code>version</code> in the text terminal, or send <code>version</code> through Binary protocol command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>), to read the complete untruncated firmware string together with protocol and build date.</p>"},{"location":"cli_commands/#show-the-hardware-name","title":"Show the hardware name","text":"<p>Usage: <code>board</code></p>"},{"location":"cli_commands/#show-the-storage-layout","title":"Show the storage layout","text":"<p>Usage: <code>get storage.layout</code></p> <p>Reports a compact, read-only summary of the storage compiled into the running firmware:</p> <ul> <li>ESP32 reports the detected internal flash size and the live partition table.   Partition addresses after <code>@</code> are hexadecimal, sizes after <code>+</code> are KiB, and   <code>*</code> marks the running application. <code>...</code> means later entries did not fit in   the CLI reply.</li> <li>nRF52 reports the physical internal flash size, linked application range,   InternalFS range, and any configured external store. Raw QSPI OTA storage   includes its detected size and JEDEC ID; SD storage includes total, used, and   free space.</li> <li>RP2040 and STM32 report their fixed internal flash and filesystem geometry.</li> </ul> <p>The command does not write, format, or resize storage. A raw-QSPI or SD build may briefly probe, wake, or mount its configured external storage to read its capacity. Remote use follows the existing administrator-command permissions.</p>"},{"location":"cli_commands/#configuration","title":"Configuration","text":""},{"location":"cli_commands/#radio","title":"Radio","text":""},{"location":"cli_commands/#view-or-change-this-nodes-radio-parameters","title":"View or change this node's radio parameters","text":"<p>Usage: - <code>get radio</code> - <code>set radio &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;</code></p> <p>Parameters: - <code>freq</code>: Frequency in MHz - <code>bw</code>: Bandwidth in kHz. Most targets allow <code>7.8</code>, <code>10.4</code>, <code>15.6</code>, <code>20.8</code>, <code>31.25</code>, <code>41.7</code>, <code>62.5</code>, <code>125</code>, <code>250</code>, <code>500</code>. LR1110 targets allow <code>62.5</code>, <code>125</code>, <code>250</code>, <code>500</code>. - <code>sf</code>: Spreading factor (5-12) - <code>cr</code>: Coding rate (5-8)</p> <p>Set by build flag: <code>LORA_FREQ</code>, <code>LORA_BW</code>, <code>LORA_SF</code>, <code>LORA_CR</code></p> <p>Default: <code>869.618,62.5,8,5</code></p> <p>Note: Requires reboot to apply. If RXPS is enabled and the saved minimum level/preamble cannot safely cover the new radio timing, the command reply reports the effective level and preamble, or <code>RXPS continuous-fast</code> when no level through 10 is safe. Slower settings recalculate from the saved RXPS minimum and return to it exactly when it is safe.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-transmit-power","title":"View or change this node's transmit power","text":"<p>Search terms: tx power, transmit strength, radio output power, dBm.</p> <p>Usage: - <code>get tx</code> - <code>set tx &lt;dbm&gt;</code></p> <p>Parameters: - <code>dbm</code>: Requested radio-chip power in dBm. The valid range depends on the   radio family, selected PA path, and any board-specific external-PA limit.</p> <p>Set by build flag: <code>LORA_TX_POWER</code></p> <p>Default: Varies by board</p> <p>Notes: This setting only controls the power level of the LoRa chip. Some nodes have an additional power amplifier stage which increases the total output. Refer to the node's manual for the correct setting to use. Setting a value too high may violate the laws in your country.</p> <p>The command strictly rejects malformed values and saves the new preference only after the active radio driver accepts it. On LR2021, the chip range is <code>-9</code> to <code>22</code> dBm below 1500 MHz and <code>-19</code> to <code>12</code> dBm above 1500 MHz. A lower board-specific external-PA limit still takes precedence. A saved profile is clamped to the applicable limit when its frequency changes; temporary radio settings use a safe effective power without replacing the saved preference.</p>"},{"location":"cli_commands/#change-the-radio-parameters-for-a-set-duration","title":"Change the radio parameters for a set duration","text":"<p>Usage:  - <code>tempradio &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;timeout_mins&gt;</code> - <code>normalradio</code></p> <p>Parameters: - <code>freq</code>: Frequency in MHz (150-2500) - <code>bw</code>: Bandwidth in kHz (same allowed values as <code>set radio</code>) - <code>sf</code>: Spreading factor (5-12) - <code>cr</code>: Coding rate (5-8) - <code>timeout_mins</code>: Duration in minutes (must be &gt; 0)</p> <p>Notes: - <code>tempradio</code> is not saved to preferences and clears on reboot. - On repeaters, remote <code>tempradio</code> and <code>normalradio</code> wait for their exact reply   copies to finish, with at least one transmitted. This also covers the <code>set</code>   alias, case-insensitive verbs, and client correlation prefixes. Failed replies   cancel an unconfirmed temporary handoff; hard lease expiry still takes priority. - <code>normalradio</code> cancels pending and active temporary-radio windows, then   restores the saved radio tuple after its CLI reply has drained on the   current channel. Permanent <code>radioat</code> entries are not removed. - On repeaters, the reply includes total minutes plus <code>NdNhNm</code> (days, hours,   minutes) and the watchdog policy for that session. For example:</p> <pre><code>OK - temp params for 1440 mins (1d0h0m); rx.watchdog=12hours\nOK - temp params for 3075 mins (2d3h15m); rx.watchdog=12hours\nOK - temp params for 180 mins (0d3h0m); rx.watchdog=off (temp&lt;12hours)\n</code></pre> <p>Repeater timing overrides apply only while a temporary window is running:</p> Temporary duration No-RX reboot watchdog Flood advert interval Direct/local advert interval Up to and including 3 hours Off Saved normal interval 1 hour More than 3, less than 12 hours Off 3 hours 1 hour 12 hours or longer 12 hours 3 hours 1 hour <p>The duration is the requested window length, not the decreasing time remaining. The first temporary adverts are scheduled from successful radio activation; hourly local adverts still run when a flood advert is also due. <code>get advert.interval</code> and <code>get flood.advert.interval</code> report the effective intervals. The web configuration form continues to show and edit the saved normal advert settings. These include any changes made during a temporary session. Expiry, cancellation, reboot, or power loss removes the temporary overrides. Normal mode uses the saved advert intervals and the 24-hour watchdog policy. An explicitly saved normal-mode <code>rx.watchdog off</code> remains off outside temporary sessions.</p>"},{"location":"cli_commands/#schedule-radio-parameter-changes","title":"Schedule radio parameter changes","text":"<p>Usage: - <code>set radioat &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;start_time&gt;</code> - <code>get radioat [n|all]</code> - <code>del radioat [n|all]</code> - <code>set tempradioat &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;start_time&gt;,&lt;end_time&gt;</code> - <code>get tempradioat [n|all]</code> - <code>del tempradioat [n|all]</code></p> <p>Parameters: - <code>freq</code>: Frequency in MHz (150-2500) - <code>bw</code>: Bandwidth in kHz (same allowed values as <code>set radio</code>) - <code>sf</code>: Spreading factor (5-12) - <code>cr</code>: Coding rate (5-8) - <code>start_time</code>: UTC Unix epoch seconds, or <code>+N</code> for N whole minutes from now - <code>end_time</code>: UTC Unix epoch seconds, or <code>+N</code> for N whole minutes from now - <code>n</code>: Scheduled entry number from <code>get radioat</code> or <code>get tempradioat</code></p> <p>Notes: - Both relative endpoints use the same command-time snapshot of the node clock.   For example, <code>set tempradioat 910.5,500,8,5,+5,+15</code> starts in 5 minutes   and reverts in 15 minutes (10 minutes active). <code>set radioat 910.5,500,8,5,+5</code>   schedules a saved change in 5 minutes. Bare numbers remain absolute timestamps;   absolute and relative endpoints can be mixed. Relative offsets must be positive.   The existing scheduler and clock behavior are unchanged. - <code>get radioat</code> and <code>get tempradioat</code> list all entries when <code>n</code> is omitted. - <code>del radioat</code> and <code>del tempradioat</code> delete all entries when <code>n</code> is omitted. - Each queue supports 3 entries. Scheduled entries are not saved across reboot. - <code>radioat</code> saves the new radio preferences when it fires. <code>tempradioat</code> applies temporarily, then reverts to the saved radio preferences. - <code>tempradioat</code> uses the repeater timing table above, with duration calculated   from <code>end_time - start_time</code>. Its acceptance reply includes total minutes, <code>NdNhNm</code>,   and the planned <code>rx.watchdog</code> setting. Queuing a future entry does not change   the running watchdog or advert intervals; the overrides start only after   the temporary radio parameters are successfully applied. If restoration   needs retries after expiry, the timing overrides still end with the window. - A successful scheduling reply notes any RXPS effective-level/preamble change   required by the scheduled tuple. <code>RXPS continuous-fast</code> means the tuple is   accepted but will use continuous receive because no safe duty-cycle level is   available. Returning to slower settings recalculates from the saved RXPS   minimum.</p> <p>With the measured RXPS model and the default 1600 us TCXO startup delay (2600 us total transition), a requested minimum level 1 gives:</p> SF BW (kHz) Wire preamble Effective timing preamble Effective RXPS level RX / sleep 7 500 32 32 2 5594 / 3022 us 6 250 32 32 2 5844 / 3022 us 5 125 32 32 2 5844 / 3022 us 5 250 64 64 1 3829 / 5100 us 6 500 64 64 1 3829 / 5100 us 5 500 128 128 1 2563 / 6647 us 5 62.5 32 16 6 11922 / 2975 us <p>These values include the actual transmitted preamble, explicit header, and a one-symbol timer margin. SF5/SF6 need two more sync symbols than SF7, so their receive windows differ even when symbol duration and sleep time match.</p> <p>The wire preamble remains compatible with the existing Cascade convention: 32 symbols at SF5-SF8, extended to 64 for SF5/BW250 and SF6/BW500, or 128 for SF5/BW500; SF9-SF12 use 16. Local RXPS settings and oscillator delays never change the sender's preamble choice. The receiver may use a shorter catch assumption, but its header timeout covers the full transmitted preamble.</p> <p>Automatic adjustment stops at guarded level 8. If no guarded timing fits, the radio receives continuously until the tuple changes. For example, a board configured with the previous 5000 us TCXO delay uses continuous RX at SF7/BW500; it cannot fit the new guard within that tuple's 32-symbol wire preamble. Experimental levels 9 and 10 require an explicit selection.</p> <p>Earlier firmware passed 16/16 packets in each direction between Heltec V4 and WisMesh Tag at SF5/BW250/64 and SF5/BW500/128, CR5, 909.950 MHz. That result established the existing wire-preamble convention; it does not validate the new timing model. All senders to an RXPS receiver must use a compatible wire preamble. LoRa OTA treats v1.17.1.5 as that capability boundary.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-frequency","title":"View or change this node's frequency","text":"<p>Search terms: radio frequency, LoRa frequency, MHz.</p> <p>Usage: - <code>get freq</code> - <code>set freq &lt;frequency&gt;</code></p> <p>Parameters: - <code>frequency</code>: Frequency in MHz</p> <p>Default: <code>869.618</code></p> <p>Note: Requires reboot to apply</p> <p>Connections: USB, browser/TCP/Ethernet CLI, Companion binary command <code>0x42</code> (USB/BLE/TCP), and authorized LoRa CLI. <code>set freq</code> saves the frequency; bandwidth, spreading factor, and coding rate stay as configured. Infrastructure roles also clamp transmit power to the board's limit for that frequency. Like <code>set radio</code>, it requires permission to configure the destination node.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-rx-boosted-gain-mode-sx12xx-and-lr1110-v1141","title":"View or change this node's rx boosted gain mode (SX12xx and LR1110, v1.14.1+)","text":"<p>Search terms: RX boost, receive gain, receiver sensitivity, boosted reception.</p> <p>Usage: - <code>get radio.rxgain</code> - <code>set radio.rxgain &lt;state&gt;</code></p> <p>Parameters:   - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: Target-specific. Most SX1262 and LR1110 targets default to <code>on</code>; Station G2/G3 targets default to <code>off</code>.</p> <p>Notes: - The saved setting is applied immediately and persists across reboots. - Periodic AGC resets restore the saved runtime setting; they do not replace it   with the target's compile-time default. - Existing installations retain their previously saved value after an upgrade.</p>"},{"location":"cli_commands/#view-or-change-rx-duty-cycle-power-saving","title":"View or change RX duty-cycle power saving","text":"<p>Search terms: RX power saving, receiver sleep, radio power saving, RXPS.</p> <p>Usage: - <code>get radio.rxps</code> - <code>get radio.rxps.config</code> - <code>get radio.rxps.rfrx_disabled</code> - <code>get rxps.wd</code> - <code>set radio.rxps.rfrx_disabled &lt;state&gt;</code> - <code>set radio.rxps off</code> - <code>set radio.rxps on</code> - <code>set radio.rxps conservative</code> - <code>set radio.rxps balanced</code> - <code>set radio.rxps max</code> - <code>set radio.rxps max preamble &lt;16|32&gt;</code> - <code>set radio.rxps overdrive</code> - <code>set radio.rxps overdrive preamble &lt;16|32&gt;</code> - <code>set radio.rxps riskyWorkingMax</code> - <code>set radio.rxps riskyWorkingMax preamble &lt;16|32&gt;</code> - <code>set radio.rxps &lt;1-10&gt;</code> - <code>set radio.rxps level &lt;1-10&gt;</code> - <code>set radio.rxps level &lt;1-10&gt; preamble &lt;16|32&gt;</code> - <code>set radio.rxps &lt;rx_us&gt; &lt;sleep_us&gt;</code></p> <p>Parameters: - <code>rx_us</code>, <code>sleep_us</code>: Receive and sleep durations in microseconds (<code>1000</code>-<code>30000000</code>). - <code>level</code>: Guarded levels <code>1</code>-<code>8</code>, followed by experimental levels <code>9</code> and <code>10</code>. Higher guarded levels allow more sleep. - <code>preamble</code>: RXPS timing assumption in symbols; <code>16</code> or <code>32</code>. This does not   change the radio's actual transmitted preamble. - <code>state</code>: <code>on</code> or <code>off</code>.</p> <p>Notes: - <code>get rxps.wd</code> reports the radio watchdogs' soft and hard recovery counts.   See receive calibration and recovery for   noise sampling, CAD handling, and the continuous-RX mode check. - <code>get radio.rxps.config</code> adds the persisted level and preamble assumption to   the on/off and timing values. Deployment tools use it to restore a   level-based preference without converting it to fixed manual timings. - <code>radio.rxps.rfrx_disabled</code> is a runtime-only diagnostic setting and resets to <code>off</code> after reboot. - Its default <code>off</code> state keeps the host-controlled SX1262 receive path enabled during RX duty-cycle mode. Setting it to <code>on</code> reproduces the old missing-RF_RX behavior and can significantly reduce receive sensitivity, making remote commands harder to receive. - <code>radio.rxps.rfrx_disabled</code> is supported only on SX1262 targets with a host-controlled RX enable pin. - <code>on</code> and <code>conservative</code> select level <code>3</code>, <code>balanced</code> selects level <code>6</code>, and   <code>max</code> selects level <code>8</code>; each named profile assumes a 16-symbol preamble. - The guarded catch ladders for levels 1-8 are <code>15,14,13,12,11,10,9,8</code> symbols   for preamble 16 and <code>24,20,16,14,12,10,9,8</code> for preamble 32 or longer.   Generated sleep leaves another 0.2 symbols of margin. The receive timer covers   the actual wire preamble, sync, explicit header, and one extra symbol. - <code>overdrive</code> selects level <code>9</code>; <code>riskyWorkingMax</code> selects level <code>10</code>. Both   operate outside the guarded timer condition. Upstream bench measurements   found packet loss at level 10; neither profile is a general guarantee of   reliable delivery. They are never selected by automatic level adjustment. - Named experimental profiles accept <code>preamble 32</code>; numeric levels keep the   existing automatic-preamble selection. Manual timings bypass the level model. - <code>MC_TCXO_DELAY_US</code> defaults to 1600 us. Initialization applies it and checks   TCXO/calibration errors. A board can override it for its oscillator. - Fresh Cascade-profile builds start with RXPS on at level <code>8</code> and a 16-symbol preamble. Saved operator settings still take precedence after an upgrade. - Level-based settings automatically recalculate their timings when the spreading factor or bandwidth changes. Custom <code>&lt;rx_us&gt; &lt;sleep_us&gt;</code> timings remain fixed. - <code>get radio.rxps</code> keeps the legacy on/off, RX, and sleep reply. The new   <code>get radio.rxps.config</code> reply adds the saved level and preamble assumption.   Radio-change replies and the Full Companion terminal status report any   effective level/preamble adjustment. Effective preamble 64 or 128 appears   only when the active tuple's physical wire preamble has that length. - The selected mode is applied immediately, persisted, and restored after reboot.</p>"},{"location":"cli_commands/#view-or-change-the-lora-fem-receive-path-gain-state-on-supported-boards","title":"View or change the LoRa FEM receive-path gain state on supported boards","text":"<p>Usage: - <code>get radio.fem.rxgain</code> - <code>set radio.fem.rxgain &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Notes: - This controls the external LoRa FEM receive-path LNA where the board supports it. - This is separate from <code>radio.rxgain</code>, which controls the radio chip receive gain mode.</p>"},{"location":"cli_commands/#view-or-change-the-lora-fem-transmit-path-gain-state-on-supported-boards","title":"View or change the LoRa FEM transmit-path gain state on supported boards","text":"<p>Usage: - <code>get radio.fem.txgain</code> - <code>set radio.fem.txgain &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Notes: - This controls a software-selectable external LoRa FEM transmit gain where the board supports it. - On Station G3, remove the PA PL1 jumper to allow software control. <code>on</code> selects PA PL1 high/short and <code>off</code> selects PA PL1 low/open. The PA PL2 hardware jumper determines whether this switches between power levels 1/3 or 2/4. - Select an operating level and SX1262 transmit power that comply with local RF limits and the Station G3 power-supply requirements. - The setting is saved immediately, but on Station G3 the level is applied to the hardware at the start of the next transmit, so that the PA supply rail is never re-targeted while the PA is being driven. <code>get</code> reports the configured state, which may lead the hardware until the node next transmits.</p>"},{"location":"cli_commands/#system","title":"System","text":""},{"location":"cli_commands/#view-or-change-this-nodes-name","title":"View or change this node's name","text":"<p>Usage: - <code>get name</code> - <code>set name &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Node name</p> <p>Set by build flag: <code>ADVERT_NAME</code></p> <p>Default: Varies by board</p> <p>Note: Advertised names can use up to 23 bytes when location is included and 31 bytes otherwise. Emoji and Unicode characters may take more than one byte. Names that exceed the available advert space are truncated at a valid UTF-8 code point boundary.</p>"},{"location":"cli_commands/#turn-wifi-esp-now-or-all-24-ghz-services-on-or-off","title":"Turn WiFi, ESP-NOW, or all 2.4 GHz services on or off","text":"<pre><code>get wifi\nset wifi off\nset wifi on\nget espnow\nset espnow off\nset espnow on\nget 2.4ghz\nset 2.4ghz off\nset 2.4ghz on\nset 2.4ghz on all\n</code></pre> Control Effect <code>wifi</code> Infrastructure WiFi, setup AP, TCP/WebUI, and WiFi MQTT services. ESP-NOW remains available. <code>espnow</code> The ESP-NOW bridge or primary ESP-NOW mesh transport in this build. Infrastructure WiFi remains available. <code>2.4ghz off</code> Stop WiFi, Bluetooth, and ESP-NOW; remember which were enabled. LoRa and wired transports remain available. <code>2.4ghz on</code> Restore the states saved by the first <code>off</code>. Repeated <code>off</code> preserves that snapshot. With no previous <code>off</code>, keep the current states. <code>2.4ghz on all</code> Enable every service available in this build and boot. <code>2.4ghz on force</code> is an alias. <p>These commands work in Companion, repeater, and room-server firmware where the services are available. Changes last until reboot; saved WiFi credentials, Bluetooth preferences, and bridge settings stay intact. <code>get 2.4ghz</code> lists each service as <code>on</code>, <code>off</code>, or <code>unavailable</code>. An nRF52 Companion controls its Bluetooth and reports WiFi/ESP-NOW as unavailable. Exclusive WiFi/Bluetooth builds retain their boot transport restriction; <code>on all</code> cannot reclaim a released Bluetooth stack.</p> <p>An <code>off</code> command requires a management connection that will survive it. Bluetooth can provide the fallback for <code>wifi off</code>; USB, Ethernet, or a CLI request over LoRa can provide it for <code>2.4ghz off</code>. WiFi association, a listening socket, and USB power alone do not count. On USB hardware without an observable open-client session, send the command through USB itself. To bypass the guard:</p> <pre><code>set wifi off force\nset espnow off force\nset 2.4ghz off force\n</code></pre> <p>Shutdown starts after the reply has had time to drain (normally 250 ms, up to two seconds for pending transport I/O). Network services stop before the shared WiFi driver. A normal shutdown is cancelled if its fallback connection disappears before it starts. The <code>get</code> commands report pending changes and startup/teardown failures. After <code>2.4ghz off</code>, use <code>2.4ghz on</code> or <code>on all</code> before enabling an individual service. The <code>all</code>/<code>force</code> suffix on on applies only to <code>2.4ghz</code>.</p> <p>WiFi and ESP-NOW share one hardware channel. A running ESP-NOW bridge pins setup and station connections to <code>bridge.channel</code>; starting the bridge alongside an existing WiFi connection requires that same channel. A mismatch reports a failed start and preserves the WiFi connection.</p>"},{"location":"cli_commands/#turn-bluetooth-on-or-off-companion","title":"Turn Bluetooth on or off (Companion)","text":"<pre><code>get bluetooth\nset bluetooth off\nset bluetooth off force\nset bluetooth on\n</code></pre> <p><code>get ble</code> and <code>set ble ...</code> are aliases. This controls the running Bluetooth service on ESP32 and nRF52 Companions: <code>off</code> stops advertising and disconnects Bluetooth clients; <code>on</code> enables it again. The change lasts until reboot.</p> <p>Plain <code>off</code> requires another active management connection. A connected USB terminal or binary client, TCP client, or browser terminal can provide that connection. WiFi association, a listening server, and USB power alone do not. On USB hardware without an observable open-host session (HWCDC or a UART bridge), issue the command through that USB client so the request itself proves it is active.</p> <p>Append <code>force</code> to <code>off</code> to permit disconnecting the only active connection. Use USB, another management transport, or reboot to regain access afterward. <code>force</code> is accepted only as the final argument to <code>off</code>.</p> <p>Commands sent through Bluetooth allow its reply to drain before shutdown (normally 250 ms, at most two seconds). <code>get bluetooth</code> shows <code>off pending</code> during that wait. A normal shutdown is cancelled if the other management connection disappears before it applies; <code>force</code> bypasses that check too.</p> <p>Bluetooth must be available in the current build and boot transport mode. An exclusive-WiFi boot still requires <code>set companion.transport ble</code> and a reboot before Bluetooth can be enabled.</p>"},{"location":"cli_commands/#view-or-change-the-independent-bluetooth-name-companion","title":"View or change the independent Bluetooth name (Companion)","text":"<p>Usage:</p> <ul> <li><code>get bluetooth.name</code></li> <li><code>set bluetooth.name &lt;name|default&gt;</code></li> </ul> <p><code>get ble.name</code> and <code>set ble.name ...</code> are accepted aliases. This command is specific to Companion firmware. The default is <code>MeshCore-&lt;advert name&gt;</code>; <code>default</code> (or <code>clear</code>) removes a custom override. Names are limited to 31 valid UTF-8 bytes without control characters and take effect after reboot.</p> <p>A binary Companion client should carry the same text in command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>), which works over USB, BLE, or TCP without entering USB terminal mode. See Companion radio binary protocol for the frame and reply format.</p>"},{"location":"cli_commands/#view-or-change-the-bluetooth-address-ble-companion","title":"View or change the Bluetooth address (BLE Companion)","text":"<p>Usage:</p> <ul> <li><code>get bluetooth.mac</code></li> <li><code>set bluetooth.mac &lt;address|random|random-every-boot|random-after-connect|default&gt;</code></li> </ul> <p><code>get ble.mac</code> and <code>set ble.mac ...</code> are accepted aliases. The setting is available on every Companion build that includes Bluetooth.</p> Value Result after reboot <code>C2:11:22:33:44:55</code> Save and use that custom address. <code>random</code> Generate one random address now, save it, and reuse it on later boots. <code>random-every-boot</code> Generate a new address once at each boot. <code>random everyboot</code> is also accepted. <code>random-after-connect</code> Keep one random address through unused boots. After an authenticated connection, arm a new address for the next boot. <code>default</code> or <code>clear</code> Remove the override and use the chipset's factory Bluetooth address. <p>A custom value must be a valid BLE random-static address in <code>XX:XX:XX:XX:XX:XX</code> form. Its first byte must be from <code>C0</code> through <code>FF</code>, and you are responsible for keeping addresses unique. Hyphens are also accepted on input; status output uses uppercase colons.</p> <p>Every change requires a reboot and invalidates the phone's previous view of the device. Forget the old device entry and pair again. <code>random-every-boot</code> also clears the Companion's saved peer bonds during each startup, so pairing and PIN entry are expected again after every reboot.</p> <p><code>random-after-connect</code> keeps the same address across any number of reboots when nobody successfully authenticated. As soon as an authenticated BLE connection succeeds, the next boot rotates the address and clears stale bonds. The marker is saved while connected, so a normal reboot, power switch, or battery pull after that connection all produce the same next-boot rotation.</p> <p>The address setting does not enable or disable stealth. Use the separate <code>bluetooth.stealth</code> flag below. <code>default</code> changes only the address policy.</p>"},{"location":"cli_commands/#view-or-change-bluetooth-stealth-ble-companion","title":"View or change Bluetooth stealth (BLE Companion)","text":"<pre><code>get bluetooth.stealth\nset bluetooth.stealth on\nset bluetooth.stealth off\n</code></pre> <p><code>get ble.stealth</code> and <code>set ble.stealth on|off</code> are short aliases. This flag defaults to <code>off</code> and is independent of the Bluetooth address policy. Enabling or disabling it keeps the configured custom/random/factory address policy unchanged and requires a reboot. Repeating <code>on</code> keeps an existing stealth pairing; repeating <code>off</code> does not alter address settings.</p> <p>For a custom address with stealth:</p> <pre><code>set bluetooth.mac C2:11:22:33:44:55\nset bluetooth.stealth on\nreboot\n</code></pre> <p>Use <code>set bluetooth.mac random</code> instead of the first line for one saved random address. Both combinations keep their address and bond across later boots. Rotating policies still rotate: <code>random-every-boot</code> reopens pairing at every boot, while <code>random-after-connect</code> reopens it on the first boot after an authenticated connection. Stealth stays enabled; each new address begins with a fresh pairing window so it cannot get hidden behind an unusable bond.</p> <p>With stealth on, the node is normally discoverable until the first authenticated pairing. After that, nRF52 uses directed advertising to the saved peer. ESP32 uses a minimal unnamed advertisement and a controller allowlist because its common Arduino BLE API does not expose the directed-advertising peer field. Both reject connection and scan requests from other peers. BLE cannot be completely radio silent and still accept a connection, so a passive radio sniffer may still observe packets. To deliberately clear the saved stealth peer, send <code>set bluetooth.stealth off</code>, then <code>set bluetooth.stealth on</code>, then reboot over USB or an existing authenticated connection. To leave stealth, set it <code>off</code> and reboot. If the saved node-side bond is lost, recovery reopens pairing. The former <code>set bluetooth.mac stealth</code> command is no longer accepted.</p> <p>This changes only the running MeshCore Companion application. On nRF52, the OTAFIX bootloader still uses its own address, which is visible only while the board is in BLE DFU/recovery mode. USB and LoRa updates are unaffected. Bluetooth update tools must follow that separate bootloader address after the handoff; they must not assume that a custom application address remains the DFU address. See the hardware observations for the tested XIAO handoff and host-cache caveats.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-latitude","title":"View or change this node's latitude","text":"<p>Usage: - <code>get lat</code> - <code>set lat &lt;degrees&gt;</code></p> <p>Set by build flag: <code>ADVERT_LAT</code></p> <p>Default: <code>0</code></p> <p>Parameters: - <code>degrees</code>: Latitude in degrees</p>"},{"location":"cli_commands/#view-or-change-this-nodes-longitude","title":"View or change this node's longitude","text":"<p>Usage: - <code>get lon</code> - <code>set lon &lt;degrees&gt;</code></p> <p>Set by build flag: <code>ADVERT_LON</code></p> <p>Default: <code>0</code></p> <p>Parameters: - <code>degrees</code>: Longitude in degrees</p>"},{"location":"cli_commands/#view-or-change-this-nodes-identity-private-key","title":"View or change this node's identity (Private Key)","text":"<p>Usage: - <code>get prv.key</code> - <code>set prv.key &lt;private_key&gt;</code></p> <p>Parameters: - <code>private_key</code>: Private key in hex format (64 hex characters)</p> <p>Local connection only: <code>get prv.key</code>. Companion also requires <code>ENABLE_PRIVATE_KEY_EXPORT=1</code>; use binary command <code>0x42</code> or the text terminal. Infrastructure <code>set prv.key</code> retains its administrator access rules.</p> <p>Note: Requires reboot to take effect after setting</p> <p></p>"},{"location":"cli_commands/#view-or-change-this-nodes-admin-password","title":"View or change this node's admin password","text":"<p>Usage: - <code>get password</code> - <code>password &lt;new_password&gt;</code></p> <p>Parameters: - <code>new_password</code>: New admin password</p> <p>Set by build flag: <code>ADMIN_PASSWORD</code></p> <p>Default: <code>password</code></p> <p><code>get password</code> returns the current admin password only on a local connection: USB, Ethernet, or the authenticated LAN browser CLI. It is rejected over LoRa. Companion has no local admin password and reports that explicitly, including through binary command <code>0x42</code>; this command does not report the Bluetooth PIN.</p> <p>Note: The password setter replies with confirmation.</p> <p>Note: Any node using this password will be added to the admin ACL list.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-guest-password","title":"View or change this node's guest password","text":"<p>Usage: - <code>get guest.password</code> - <code>set guest.password &lt;password&gt;</code></p> <p>Parameters: - <code>password</code>: Guest password</p> <p>Set by build flag: <code>ROOM_PASSWORD</code> (Room Server only)</p> <p>Default: <code>&lt;blank&gt;</code></p>"},{"location":"cli_commands/#view-or-change-this-nodes-owner-info","title":"View or change this node's owner info","text":"<p>Usage: - <code>get owner.info</code> - <code>set owner.info &lt;text&gt;</code></p> <p>Parameters: - <code>text</code>: Owner information text</p> <p>Default: <code>&lt;blank&gt;</code></p> <p>Note: <code>|</code> characters are translated to newlines</p> <p>Note: Requires firmware 1.12+</p>"},{"location":"cli_commands/#fine-tune-the-battery-reading","title":"Fine-tune the battery reading","text":"<p>Usage: - <code>get adc.multiplier</code> - <code>set adc.multiplier &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: ADC multiplier (0.0-10.0)</p> <p>Default: <code>0.0</code> (value defined by board)</p> <p>Note: Returns \"Error: unsupported by this board\" if hardware doesn't support it</p>"},{"location":"cli_commands/#send-a-repeater-flood-text","title":"Send a repeater flood text","text":"<p>Usage: - <code>send text.flood &lt;message&gt;</code></p> <p>Parameters: - <code>message</code>: Text to send to the shared <code>#repeaters</code> flood channel, prefixed with this node's name. Any <code>:</code> in the node name is sent as <code>;</code> so the prefix delimiter stays unambiguous.</p> <p>Example:</p> <pre><code>send text.flood checking ridge link\n</code></pre>"},{"location":"cli_commands/#view-or-change-battery-alert-state","title":"View or change battery alert state","text":"<p>Usage: - <code>get battery.alert</code> - <code>get battery.alert.region</code> - <code>set battery.alert on [region]</code> - <code>set battery.alert off</code></p> <p>Parameters: - <code>region</code>: Optional named region scope. When omitted, the repeater selects the single deepest (most narrow) named region in the configured hierarchy. If multiple regions tie for deepest, specify one explicitly.</p> <p>Defaults: - <code>battery.alert</code>: <code>off</code> - <code>battery.alert.region</code>: <code>&lt;unset&gt;</code></p> <p>Notes: - Enabling fails until at least one usable named region is defined. Alerts are never sent as unscoped floods. If the selected region is later removed, alerts stop until battery alerts are enabled again with a valid region. - Region hierarchy edits are not persistent until <code>region save</code> is run. After <code>region def west pnw wa w-wa sea</code>, run <code>region save</code> before enabling the alert if the hierarchy must survive a reboot. - A region must have a usable transport key. Public named regions derive one automatically; a private region without an available key is rejected. - The first alert is suppressed until the repeater has been up for at least 30 minutes. After that, the repeater checks every 30 minutes and sends low-battery warnings to the <code>#repeaters</code> channel in the selected region. - Once an alert finishes transmitting, another battery alert is suppressed for at least 12 hours. A queue rejection, stale-queue drop, or radio send failure does not start the cooldown. Battery recovery or toggling alerts off and back on does not bypass a completed alert's cooldown during the same boot. - With <code>region def west pnw wa w-wa sea</code>, <code>set battery.alert on</code> selects <code>sea</code>; <code>set battery.alert on w-wa</code> overrides that default. - <code>get battery.alert.region</code> returns the selected scope, for example <code>&gt; sea</code>. - The battery check never requests a wake earlier than its 30-minute deadline. If the normal loop is already awake when that deadline has elapsed, the check is effectively free of an additional wake. Time in light/event sleep counts toward the startup delay, and a pending alert keeps the repeater awake until the packet is handled.</p>"},{"location":"cli_commands/#view-or-change-battery-alert-thresholds","title":"View or change battery alert thresholds","text":"<p>Usage: - <code>get battery.alert.low</code> - <code>set battery.alert.low &lt;1-100&gt;</code> - <code>get battery.alert.critical</code> - <code>set battery.alert.critical &lt;0-99&gt;</code></p> <p>Defaults: - <code>battery.alert.low</code>: <code>20</code> - <code>battery.alert.critical</code>: <code>10</code></p> <p>Note: The low threshold must be greater than the critical threshold. Alerts at or below the critical threshold use <code>CRITICAL BATTERY</code> in the message; both severities use the same 12-hour resend cooldown.</p>"},{"location":"cli_commands/#enable-or-disable-the-rx-inactivity-watchdog-repeater-only","title":"Enable or disable the RX inactivity watchdog (Repeater Only)","text":"<p>Usage: - <code>get rx.watchdog</code> - <code>set rx.watchdog on</code> - <code>set rx.watchdog off</code></p> <p>Default: <code>on</code>, with a 24-hour no-RX timeout in normal mode.</p> <p>Notes: - In normal mode, the repeater reboots after 24 hours without a received packet passing MeshCore parsing. Each such reception restarts this timeout; checks use a sliding deadline rather than waiting for another 24-hour checkpoint. - While <code>tempradio</code> or <code>tempradioat</code> is running, windows of at least 12 hours use a 12-hour no-RX timeout. Shorter windows disable this reboot watchdog for the duration of the session. This temporary policy also overrides a saved normal-mode <code>off</code> setting. - Startup, a successful temporary-radio activation/replacement, expiry, cancellation, or manually changing this setting starts a fresh observation window. Expiry is processed before the watchdog, so a temporary window ending exactly at its watchdog deadline restores normal timing first. - <code>get rx.watchdog</code> reports both the effective on/off state and timeout or short-session disabled reason. <code>set rx.watchdog on|off</code> saves the normal-mode preference; temporary-session rules remain active until that session ends. Existing saved preferences are retained when upgrading; the new default applies to fresh settings or older preference files without this field. - The check uses the last successful MeshCore parse time, recorded before receive delays and routing filters. It does not require the packet to be addressed to this repeater or its encrypted payload to be decrypted; duplicate receptions also count. This checks MeshCore packet structure, not sender authentication. - It does not poll, sample, or wake the radio or CPU. A due check waits for the next normal loop/wake. With RX power saving enabled, qualifying packets received during normal listening windows count as activity; the watchdog does not alter the RX/sleep timing. - Transmitting, radio interrupts, and raw LoRa packets rejected by the MeshCore parser do not reset the timer. Packets dropped before parsing because the packet pool is full do not count either. This whole-board reboot setting is separate from the automatic radio-only recovery watchdog, which still measures successful raw radio reads.</p>"},{"location":"cli_commands/#enable-or-disable-the-nrf52-system-watchdog","title":"Enable or disable the nRF52 system watchdog","text":"<p>Usage: - <code>get system.watchdog</code> - <code>set system.watchdog on</code> - <code>set system.watchdog off</code></p> <p>Default: <code>on</code></p> <p>Notes: - This nRF52-only hardware watchdog resets the device if the application loop stops for 60 seconds, including an indefinite SoftDevice flash-write wait. - Enabling takes effect without a reboot. - The nRF52 hardware cannot stop a watchdog after it has started. Disabling is persisted immediately, then the current firmware stops feeding it so the board performs one watchdog restart within 60 seconds. It remains off after that restart. - This setting is nRF52-only. The SoftDevice flash deadlock does not apply to ESP32, whose existing watchdog behavior is unchanged.</p>"},{"location":"cli_commands/#estimate-and-correct-infrastructure-node-time-after-startup","title":"Estimate and correct infrastructure-node time after startup","text":"<p>Usage: - <code>get clock.sync</code> - <code>get clock.sync.status</code> - <code>get clock.sync.status.table</code> - <code>get clock.sync.status.&lt;1-16&gt;</code> - <code>get clock.sync.mesh</code> - <code>set clock.sync.mesh &lt;on|off&gt;</code> - <code>get clock.sync.mesh.edge</code> - <code>set clock.sync.mesh.edge &lt;on|off&gt;</code> - <code>clock.sync.mesh now</code> - <code>get clock.sync.internet</code> - <code>set clock.sync.internet &lt;on|off&gt;</code> - <code>get clock.sync.drift</code> - <code>set clock.sync.drift &lt;30-86400&gt;</code> - <code>get clock.sync.samples</code> - <code>set clock.sync.samples &lt;3-16&gt;</code></p> <p>Defaults: - <code>clock.sync.mesh</code>: <code>on</code> for all repeater, sensor, and room-server builds - <code>clock.sync.mesh.edge</code>: <code>on</code> - <code>clock.sync.internet</code>: <code>off</code> - <code>clock.sync.drift</code>: <code>600</code> seconds (10 minutes) - <code>clock.sync.samples</code>: <code>9</code></p> <p>When either source is enabled, the node makes its first clock-bootstrap attempt after 30 minutes of uptime, or immediately when the configured number of fresh evidence sources has been collected, whichever comes first. A successful estimate changes the RTC only when the absolute difference is greater than <code>clock.sync.drift</code>; correction can move the clock forward or backward. A valid estimate within the threshold counts as a successful sync without changing the clock. Seven days after each successful estimate, the node evaluates time again; the seven-day deadline therefore starts from the last successful estimate rather than from boot. This is a lazy uptime deadline: the check runs on the first normal loop/wake after it becomes due and does not wake the device by itself. If no source or consensus is available, the node retries every 30 minutes, and newly collected evidence triggers another immediate evaluation once the configured source count is present. Every reboot starts with the initial bootstrap attempt. An existing saved setting always overrides the platform default.</p> <p><code>clock.sync.mesh now</code> bypasses the startup/seven-day deadline and queues a LoRa-only consensus evaluation on the next normal loop, even when the internet source is also enabled. It uses any currently fresh samples without clearing the 16-slot table. If there is not yet enough evidence, mesh collection remains open and the next attempt follows the normal 30-minute retry. The command requires <code>clock.sync.mesh</code> to be on and does not bypass CLI, GPS, or NTP suppression; it also retains the normal quorum, timestamp-validity, and drift checks. The separate <code>clock</code> command only displays the current RTC and does not request a synchronization attempt.</p> <p><code>clock.sync.mesh</code> collects signature-verified advert timestamps and MAC-valid, decrypted Public-channel plain-text timestamps. In normal path mode, collection occurs only after the packet passes every forwarding filter. Sources are deduplicated by advert public key or case-insensitive Public-channel display name. Every fresh sample must also have a different full received path; all direct, zero-hop receptions count as the same empty path. This prevents repeated packets or multiple names arriving over one route from increasing the vote count.</p> <p>For a node at the edge of the network where every packet arrives through one relay path, <code>set clock.sync.mesh.edge on</code> changes the evidence requirement from distinct receive paths to distinct sources. Signature-verified adverts are deduplicated by public key, and Public-channel timestamps are deduplicated by case-insensitive display name. Repeated packets from one source still count once. Edge mode observes this verified evidence on the receive path, independently of the forwarding decision, so <code>repeat off</code> and forwarding filters do not prevent clock collection. Other packet types are observed normally but cannot be clock evidence because they do not provide a suitable authenticated Unix timestamp. Changing edge mode clears the in-memory sample table so evidence collected under the other policy is not reused. The setting is persistent and defaults on.</p> <p>At least the configured number of distinct fresh evidence sources (nine by default) and a strict majority of all fresh samples must fall within ten minutes of the median. In normal mode each source must use a distinct receive path. In edge mode signed adverts are distinct by public key and Public-channel messages are distinct by display name, but all may use the same receive path. The effective quorum is therefore the larger of <code>clock.sync.samples</code> and half the fresh sample count plus one. For example, a 9-vs-7 split can succeed but an 8-vs-8 split cannot. The median is used. <code>clock.sync.samples</code> accepts <code>3</code> through <code>16</code>; samples older than two hours are ignored. Status reports <code>mode=paths</code> or <code>mode=edge</code> and labels the collected evidence as <code>paths</code> or <code>sources</code>. It reports <code>reason=need-more-paths</code> or <code>reason=need-more-sources</code> when fewer than the configured number exist, and <code>reason=no-consensus</code> when enough evidence exists but the effective quorum does not agree. Mesh collection begins immediately after boot. Following a successful estimate, it resumes two hours before the next seven-day deadline so only evidence that can still be fresh at evaluation time is processed.</p> <p><code>get clock.sync.status</code> reports whether the clock was set and a <code>reason</code> when it was not. Common reasons include <code>waiting-deadline</code>, <code>need-more-sources</code>, <code>need-more-paths</code>, <code>no-consensus</code>, <code>within-drift</code>, <code>mesh-off</code>, and suppression by CLI, GPS, or internet time. It also reports whether collection is active, the fresh evidence count, the number of occupied table slots, and the next evaluation deadline.</p> <p><code>get clock.sync.status.table</code> shows the active sample table in compact form. Each item is <code>slot:type:id-prefix:age</code>, where type <code>A</code> is a signed advert and type <code>P</code> is a Public-channel message. A trailing <code>!</code> marks a stale sample. If the compact reply is truncated, query any slot with <code>get clock.sync.status.&lt;1-16&gt;</code>. The detail view reports the full source and path hashes, age-adjusted epoch, difference from the local clock, and freshness.</p> <p>A timestamp is eligible for a clock-sync sample only when it falls between the UTC build epoch embedded by <code>build.sh</code> and that time plus ten calendar years. Direct developer builds that bypass <code>build.sh</code> fall back to the compiler timestamp. Validation happens before a slot is selected or written, so an advert or Public-channel timestamp outside that window is not recorded as a clock sample.</p> <p>Before voting, the node advances each packet timestamp by an estimated transit time. The estimate sums the radio airtime at the original packet length and at each progressively longer relay length, plus the expected midpoint of the random flood-forward delay at every prior hop. The normal elapsed time since the radio recorded local receipt is then added when consensus is evaluated, so local signature/decryption/filter processing time is included too. This is better than using hop count alone because LoRa airtime changes with packet length and radio settings. Transit compensation is capped at the ten-minute consensus window. It cannot know sender queueing, channel contention, or a remote relay's non-matching <code>txdelay</code>, so the consensus window and median still absorb residual error.</p> <p>If a <code>clock sync</code> or <code>time &lt;epoch&gt;</code> CLI command successfully sets the clock, or a GPS provider writes a valid GPS time, LoRa-derived clock collection and correction are suppressed for the rest of that boot. Turning <code>clock.sync.mesh</code> off and back on does not clear this safety latch; only a reboot does. <code>get clock.sync.mesh</code> and <code>get clock.sync.status</code> report whether CLI or GPS time caused the suppression. On a WiFi MQTT build, a successful NTP sync is authoritative and also suppresses LoRa correction for the rest of that boot. Source selection starts fresh after a reboot, so LoRa remains the fallback when NTP cannot obtain internet time during that boot.</p> <p>Public-channel display names are not authenticated and can be spoofed. Received path hashes are also truncated, unauthenticated routing hints; requiring unique paths prevents ordinary duplicate-route inflation but is not a cryptographic identity check. Signed adverts authenticate the advert contents but do not prove that the advertising node's own clock is correct. Mesh time is therefore a consensus estimate, not an authoritative time service. Edge mode intentionally gives up receive-path diversity. Public-channel display names can be spoofed, so one sender can claim multiple names and inflate the edge-mode vote count.</p> <p><code>clock.sync.internet</code> is available on WiFi MQTT repeater-observer builds. Its initial and seven-day queries run on the MQTT/WiFi task and are read-only until the repeater applies the configured drift test. Failed queries retry after 30 minutes. On other infrastructure-node builds, the preference can be stored but status reports that internet time is unavailable. MQTT builds retain their existing startup NTP behavior required for MQTT/TLS/JWT operation; this setting controls the additional delayed drift checks. Startup NTP is always preferred when it succeeds, regardless of this setting.</p> <p>Sensor and room-server builds support mesh clock consensus and report <code>clock.sync.internet</code> as unavailable. Changing any <code>clock.sync.*</code> setting starts a new attempt for the current boot. Settings are persistent in <code>/clock_sync</code>; samples and schedule state are not.</p> <p>A backward correction is intentionally allowed, but peers that already recorded a later timestamp from this node may temporarily reject its lower timestamps as replays until corrected time passes the previously observed value.</p> <p>Example:</p> <pre><code>set clock.sync.drift 600\nset clock.sync.samples 3\nset clock.sync.mesh on\nset clock.sync.mesh.edge on\nclock.sync.mesh now\nget clock.sync.status\n</code></pre>"},{"location":"cli_commands/#view-this-nodes-public-key","title":"View this node's public key","text":"<p>Usage: <code>get public.key</code></p>"},{"location":"cli_commands/#view-this-nodes-firmware-version","title":"View this node's firmware version","text":"<p>Usage: <code>ver</code></p>"},{"location":"cli_commands/#view-this-nodes-configured-role","title":"View this node's configured role","text":"<p>Usage: <code>get role</code></p>"},{"location":"cli_commands/#view-or-change-this-nodes-power-saving-flag","title":"View or change this node's power saving flag","text":"<p>Search terms: battery saver, device power saving, low power mode.</p> <p>Usage: - <code>get powersaving</code> - <code>set powersaving on</code> - <code>set powersaving off</code></p> <p>Parameters:  - <code>on</code>: enable power saving - <code>off</code>: disable power saving</p> <p>Default: <code>on</code> for fresh Cascade-profile builds and Companion firmware; <code>off</code> for other infrastructure profiles</p> <p>Note: <code>get powersaving</code>, <code>set powersaving on</code>, and <code>set powersaving off</code> are shared by Companion and infrastructure. The saved preference controls whether power saving is allowed; active USB, logging and network services may keep the hardware awake. Actual sleep depends on the board.</p> <p>For the 1.17.1.5 G3 USB-disconnect report, use <code>set powersaving off</code> as the workaround. The released ESP32 sleep code can lose native USB after two minutes when the terminal is closed, even with a computer attached. The source fix blocks ESP32 light sleep while a native USB host is attached or live USB logging is enabled; ordinary CPU idle/yield remains available. The G3 button also wakes the device for at least two minutes. See the G3 release note for verification steps and the distinction between the fix and the published binaries.</p> <p>Companion firmware defaults this setting to <code>on</code>. Full Companion accepts the command from its local USB terminal and exposes the same setting in WebConfig. On ESP32, it lowers the CPU clock to 80 MHz, enables idle yielding, and enables the configured GPS duty cycle. USB and each active wireless transport remain available; SenseCAP Indicator Full keeps only its selected BLE or infrastructure-WiFi secondary transport active. <code>set powersaving off</code> restores the board's normal CPU clock and disables the GPS duty cycle. This device setting is separate from LoRa RXPS (<code>radio.rxps</code>) and WiFi modem power save (<code>wifi.powersave</code>). Infrastructure uses the same commands; its hardware and active-service sleep guards determine when the node can sleep.</p>"},{"location":"cli_commands/#view-or-set-the-reboot-interval-repeater-and-room-server","title":"View or set the reboot interval (Repeater and room server)","text":"<p>Usage: - <code>get reboot.interval</code> - <code>set reboot.interval &lt;hours&gt;</code></p> <p>Parameters: - <code>hours</code>: <code>0-255</code>; <code>0</code> disables scheduled reboots.</p> <p>Default: <code>0</code> (disabled)</p>"},{"location":"cli_commands/#control-an-exposed-gpio","title":"Control an exposed GPIO","text":"<p>Availability: ESP32 Repeater, Room Server, Bridge, and Sensor firmware. Companion firmware does not expose these commands. On nRF52, the commands are enabled only for Sensor builds on the Heltec T096, ProMicro, RAK3401, and RAK4631. GPIO expanders are not supported.</p> <p>Usage:</p> <ul> <li><code>get gpio</code> - list the Arduino pin numbers this firmware build permits</li> <li><code>get gpio state</code>, <code>get gpio states</code>, or <code>get gpio status</code> - list every available pin currently controlled by the user (anything not in <code>reset</code>)</li> <li><code>get gpio state &lt;pin&gt;</code> - show one pin's state; <code>states</code> and <code>status</code> are accepted here too</li> <li><code>get gpio &lt;pin&gt;</code> - show <code>on</code>, <code>off</code>, or <code>reset</code>, plus any pending timed transition</li> <li><code>set gpio &lt;pin&gt; on</code></li> <li><code>set gpio &lt;pin&gt; off</code></li> <li><code>set gpio &lt;pin&gt; reset</code></li> <li><code>set gpio &lt;pin&gt; &lt;on|off&gt; &lt;duration&gt; &lt;on|off|reset&gt;</code></li> </ul> <p>Examples:</p> <ul> <li><code>set gpio 16 on 30 off</code> - drive GPIO16 high for 30 seconds, then drive it low</li> <li><code>set gpio 16 on 5ms off</code> - drive GPIO16 high for 5 milliseconds, then drive it low</li> <li><code>set gpio 16 off 5 reset</code> - drive GPIO16 low for 5 seconds, then return it to high impedance</li> </ul> <p>An integer duration has seconds as its default unit, so <code>5</code> means 5 seconds. Add <code>ms</code> for milliseconds (<code>5ms</code>); an explicit <code>s</code> suffix is also accepted (<code>5s</code>). The maximum duration is 24 hours (86,400 seconds or 86,400,000 milliseconds). <code>on</code> or <code>off</code> without a duration remains in that state until another command, reset, or reboot.</p> <p><code>reset</code> changes the pin to an input with no pull resistor (high impedance). It does not reboot the node. It also cancels any pending timer for that pin. A new timed command for the same pin cancels and replaces the previous timer. GPIOs begin in <code>reset</code>; states and timers are not saved and are lost on reboot.</p> <p>The immediate reply confirms the applied state and any pending transition. When a timed transition finishes, a command issued over the authenticated remote CLI receives a second report such as <code>&gt; GPIO 16 timer complete: off</code>. Retries of the same authenticated timed command are recognized and do not restart its countdown.</p> <p>The pin number is the Arduino pin number used by that target (the normal GPIO number on ESP32 and the board's <code>D</code>/pin index on nRF52). The available-pin list is build-specific. Radio, flash/PSRAM, USB, serial console, display, GPS, I2C, buttons, LEDs, battery measurement, power control, bridge, Ethernet, watchdog, and other pins claimed by the firmware are rejected. A pin must also be physically broken out on your board; <code>get gpio</code> cannot detect wiring or an attached peripheral that is not represented by the firmware configuration.</p> <p>Electrical warning: GPIOs use 3.3 V logic and have limited drive current. Do not power a relay, motor, solenoid, or other load directly from a GPIO. Use a suitable transistor, MOSFET, optocoupler, or driver with the required protection components.</p>"},{"location":"cli_commands/#routing","title":"Routing","text":""},{"location":"cli_commands/#view-or-set-the-direct-path-override-for-the-current-remote-client","title":"View or set the direct path override for the current remote client","text":"<p>Usage: - <code>get outpath</code> - <code>get outpath path</code> - <code>set outpath &lt;hop1_hex,hop2_hex,...&gt;</code> - <code>set outpath path</code> - <code>set outpath direct</code> - <code>set outpath clear</code> - <code>set outpath flood</code></p> <p>Parameters: - <code>hopN_hex</code>: Hop hash with <code>2</code>, <code>4</code>, or <code>6</code> hexadecimal characters. Every hop must use the same width.</p> <p>Notes: - These commands require remote client context and update the caller's ACL entry. - <code>get outpath path</code> reports the reciprocal <code>PAYLOAD_TYPE_PATH</code> received after   the caller's latest flood login without changing the selected output route.   Because that packet is asynchronous, an immediate query can report   <code>&gt; path pending</code>; retry shortly. The observation window expires after one   minute, and the captured login path is not automatically selected. - <code>set outpath path</code> copies that observed route to <code>outpath</code> and saves it. It   returns an error without changing <code>outpath</code> if no route was received. - <code>direct</code> selects a zero-hop route for a directly reachable caller. - <code>clear</code> forgets the override, replies <code>&gt; outpath cleared</code>, and allows normal   path discovery to repopulate it. - <code>flood</code> forces replies to use flood packets until the client logs in again.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-repeat-flag","title":"View or change this node's repeat flag","text":"<p>Search terms: enable repeating, disable repeating, packet forwarding, stop relaying.</p> <p>Usage: - <code>get repeat</code> - <code>set repeat &lt;state&gt;</code></p> <p>Parameters:   - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>flood.channel.data on</code>; <code>flood.channel.data.hops h=all</code></p>"},{"location":"cli_commands/#view-or-change-this-nodes-advert-path-hash-size","title":"View or change this node's advert path hash size","text":"<p>1.17.1.5 infrastructure bug: affected Repeater, Room Server, and Sensor images accept <code>get path.hash.mode</code> but report <code>unknown config</code> for the setter. The command was not renamed. The source correction restores the setter; installed images need an updated build. See the setting-dispatch audit.</p> <p>Usage: - <code>get path.hash.mode</code> - <code>set path.hash.mode &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Path hash size (0-2)   - <code>0</code>: 1 Byte hash size (256 unique ids)[64 max flood]   - <code>1</code>: 2 Byte hash size (65,536 unique ids)[32 max flood]   - <code>2</code>: 3 Byte hash size (16,777,216 unique ids)[21 max flood]   - <code>3</code>: DO NOT USE (Reserved) </p> <p>Default: <code>0</code></p> <p>Note: the 'path.hash.mode' sets the low-level ID/hash encoding size used when the repeater adverts. This setting has no impact on what packet ID/hash size this repeater forwards, all sizes should be forwarded on firmware &gt;= 1.14. This feature was added in firmware 1.14</p> <p>Temporary Note: adverts with ID/hash sizes of 2 or 3 bytes may have limited flood propagation in your network while this feature is new as v1.13.0 firmware and older will drop packets with multibyte path ID/hashes as only 1-byte hashes are supported. Consider your install base of firmware &gt;=1.14 has reached a criticality for effective network flooding before implementing higher ID/hash sizes. </p>"},{"location":"cli_commands/#view-or-change-this-nodes-loop-detection","title":"View or change this node's loop detection","text":"<p>Usage: - <code>get loop.detect</code> - <code>set loop.detect &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>:    - <code>off</code>: no loop detection is performed   - <code>minimal</code>: packets are dropped if repeater's ID/hash appears 4 or more times (1-byte), 2 or more (2-byte), 1 or more (3-byte)   - <code>moderate</code>: packets are dropped if repeater's ID/hash appears 2 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)   - <code>strict</code>: packets are dropped if repeater's ID/hash appears 1 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)</p> <p>Default: <code>off</code></p> <p>Note: When it is enabled, repeaters will now reject flood packets which look like they are in a loop. This has been happening recently in some meshes when there is just a single 'bad' repeater firmware out there (probably some forked or custom firmware). If the payload is messed with, then forwarded, the same packet ends up causing a packet storm, repeated up to the max 64 hops. This feature was added in firmware 1.14</p> <p>Example: If preference is <code>loop.detect minimal</code>, and a 1-byte path size packet is received, the repeater will see if its own ID/hash is already in the path. If it's already encoded 4 times, it will reject the packet.  If the packet uses 2-byte path size, and repeater's own ID/hash is already encoded 2 times, it rejects. If the packet uses 3-byte path size, and the repeater's own ID/hash is already encoded 1 time, it rejects. </p>"},{"location":"cli_commands/#view-or-change-the-retransmit-delay-factor-for-flood-traffic","title":"View or change the retransmit delay factor for flood traffic","text":"<p>Search terms: flood forwarding delay, flood retransmit delay, flood TX delay.</p> <p>Usage: - <code>get txdelay</code> - <code>set txdelay &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Transmit delay factor (0-2)</p> <p>Default: <code>0.5</code></p> <p>Note: When multiple nearby repeaters all hear the same flood packet, each waits a random amount of time before retransmitting to avoid simultaneous collisions. This factor scales the size of that random window. Higher values reduce collision risk at the cost of added latency. <code>0</code> disables the window entirely.</p>"},{"location":"cli_commands/#view-or-change-the-retransmit-delay-factor-for-direct-traffic","title":"View or change the retransmit delay factor for direct traffic","text":"<p>Search terms: direct forwarding delay, direct retransmit delay, direct TX delay.</p> <p>Usage: - <code>get direct.txdelay</code> - <code>set direct.txdelay &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Direct transmit delay factor (0-2)</p> <p>Default: <code>0.3</code> (Repeater) - <code>0.2</code> (Room Server, Sensor)</p> <p>Note: Same collision-avoidance random window as <code>txdelay</code>, but applied to direct (non-flood, routed) traffic. The default is lower because direct packets are addressed to a specific next hop, so far fewer nodes compete to retransmit them.</p>"},{"location":"cli_commands/#experimental-view-or-change-the-processing-delay-for-received-traffic","title":"[Experimental] View or change the processing delay for received traffic","text":"<p>Usage: - <code>get rxdelay</code> - <code>set rxdelay &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Receive delay base (0-20)</p> <p>Default: <code>0.0</code></p> <p>Note: When enabled, repeaters that received a flood packet with a weak signal are held in a delay queue before processing, while those that received it with a strong signal process it immediately. This gives strong-signal paths forwarding priority. By the time weak-signal nodes process their copy, the packet may have already propagated and will be suppressed as a duplicate, reducing redundant retransmissions.</p>"},{"location":"cli_commands/#view-or-change-the-duty-cycle-limit","title":"View or change the duty cycle limit","text":"<p>Usage: - <code>get dutycycle</code> - <code>set dutycycle &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Duty cycle percentage (1-100)</p> <p>Default: <code>50%</code> (equivalent to airtime factor 1.0)</p> <p>Examples: - <code>set dutycycle 100</code> - no duty cycle limit - <code>set dutycycle 50</code> - 50% duty cycle (default) - <code>set dutycycle 10</code> - 10% duty cycle - <code>set dutycycle 1</code> - 1% duty cycle (strictest EU requirement)</p> <p>Note: Added in firmware v1.15.0</p>"},{"location":"cli_commands/#view-or-change-the-airtime-factor-duty-cycle-limit","title":"View or change the airtime factor (duty cycle limit)","text":"<p>Deprecated as of firmware v1.15.0. Use <code>get/set dutycycle</code> instead.</p> <p>Usage: - <code>get af</code> - <code>set af &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Airtime factor (0-9). After each transmission, the repeater enforces a silent period of approximately the on-air transmission time multiplied by the value. This results in a long-term duty cycle of roughly 1 divided by (1 plus the value). For example:   - <code>af = 1</code> -&gt; ~50% duty   - <code>af = 2</code> -&gt; ~33% duty   - <code>af = 3</code> -&gt; ~25% duty   - <code>af = 9</code> -&gt; ~10% duty   You are responsible for choosing a value that is appropriate for your jurisdiction and channel plan (for example EU 868 Mhz 10% duty cycle regulation).</p> <p>Default: <code>1.0</code></p>"},{"location":"cli_commands/#view-or-change-the-local-interference-threshold","title":"View or change the local interference threshold","text":"<p>Usage: - <code>get int.thresh</code> - <code>set int.thresh &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Interference threshold value</p> <p>Default: <code>0.0</code></p>"},{"location":"cli_commands/#enable-or-disable-hardware-channel-activity-detection-cad","title":"Enable or disable hardware Channel Activity Detection (CAD)","text":"<p>Usage: - <code>get cad</code> - <code>set cad &lt;on|off&gt;</code></p> <p>Description: When enabled, the radio performs a hardware Channel Activity Detection scan before transmitting and defers if the channel is busy. Runs independently of <code>int.thresh</code> - either, both, or none may be active.</p> <p>Fresh Cascade-profile builds default CAD to <code>off</code> across all roles, including Companion. Saved CAD settings take precedence after an upgrade. Use <code>set cad off</code> to disable it on an existing node or <code>set cad on</code> to enable it explicitly. The repeater applies the saved toggle to the radio during its periodic noise-floor service. With one runnable packet, a busy result uses the normal CAD retry delay and allows roughly four seconds of continuous busy results. As the runnable transmit queue grows, both delays are divided by its depth: retry spacing will not fall below 50 ms and the busy ceiling will not fall below 500 ms. Reaching the busy ceiling records a CAD-timeout error and attempts the next queued transmission rather than waiting indefinitely. Future-scheduled packets do not accelerate CAD. <code>get cad</code> includes the hardware busy-result count.</p> <p>Parameters: - <code>on|off</code>: Enable or disable hardware CAD</p> <p>Default: <code>off</code></p>"},{"location":"cli_commands/#view-or-change-the-agc-reset-interval","title":"View or change the AGC Reset Interval","text":"<p>Usage: - <code>get agc.reset.interval</code> - <code>set agc.reset.interval &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Interval in seconds rounded down to a multiple of 4 (17 becomes 16). 0 to disable.</p> <p>Default: <code>0.0</code></p>"},{"location":"cli_commands/#view-or-change-the-radio-watchdog-interval-mqtt-observer-only","title":"View or change the radio watchdog interval (MQTT observer only)","text":"<p>Usage: - <code>get radio.watchdog</code> - <code>set radio.watchdog &lt;minutes&gt;</code></p> <p>Parameters: - <code>minutes</code>: <code>0</code> to use the standard 30-minute soft recovery interval, or <code>1-120</code> minutes to override it</p> <p>Default: <code>5</code></p> <p>Note: This setting belongs to the MQTT observer runtime and is not available on a standalone FULL repeater. It sets the interval without a successfully received packet before soft radio recovery. Transmissions and interrupts alone do not restart the timer. Setting it to <code>0</code> removes the observer override; automatic radio recovery remains active. The normal hard recovery threshold is 12 hours, where the radio supports it, and recovery does not reboot the whole board. On quiet meshes, increasing the soft interval can reduce unnecessary recoveries when no traffic is expected.</p>"},{"location":"cli_commands/#enable-or-disable-multi-acks-support","title":"Enable or disable Multi-Acks support","text":"<p>Usage: - <code>get multi.acks</code> - <code>set multi.acks &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>0</code> (disable) or <code>1</code> (enable)</p> <p>Default: <code>0</code></p>"},{"location":"cli_commands/#view-or-change-the-flood-advert-interval","title":"View or change the flood advert interval","text":"<p>Usage: - <code>get flood.advert.interval</code> - <code>set flood.advert.interval &lt;hours&gt;</code></p> <p>Parameters: - <code>hours</code>: Interval in hours (3-168)</p> <p>Default: <code>47</code> (Repeater, Room Server) - <code>0</code>, disabled (Sensor)</p>"},{"location":"cli_commands/#view-or-change-the-zero-hop-advert-interval","title":"View or change the zero-hop advert interval","text":"<p>Usage: - <code>get advert.interval</code> - <code>set advert.interval &lt;minutes&gt;</code></p> <p>Parameters: - <code>minutes</code>: Interval in minutes rounded down to the nearest multiple of 2 (61 becomes 60) (60-240)</p> <p>Default: <code>2</code> on a factory-fresh node, then <code>0</code> (disabled) once configured.</p> <p>Note: A new install ships with a 2 minute zero-hop advert interval. Saving any setting resets an interval below the 60 minute minimum to <code>0</code>, on the assumption that the node has now been deliberately configured. To keep zero-hop adverts running, set an explicit value in the 60-240 range.</p>"},{"location":"cli_commands/#limit-the-number-of-hops-for-a-flood-message","title":"Limit the number of hops for a flood message","text":"<p>Search terms: hop limit, maximum hops, max hops, flood distance.</p> <p>Usage: - <code>get flood.max</code> - <code>set flood.max &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Maximum flood hop count (0-64)</p> <p>Default: <code>64</code></p>"},{"location":"cli_commands/#limit-the-number-of-hops-for-an-unscoped-flood-message","title":"Limit the number of hops for an unscoped flood message","text":"<p>Usage: - <code>get flood.max.unscoped</code> - <code>set flood.max.unscoped &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Maximum flood hop count (0-64) for a packet without a scope (no region set)</p> <p>Default: <code>0xFF</code> - indicates it hasn't been set, will track flood.max until it is.</p> <p>Note: An alternative to <code>region denyf *</code>, setting <code>flood.max.unscoped</code> to a lower value such as <code>3</code> would allow for local unscoped messages to propagate, while preventing noisy neighbors from flooding a local region.</p>"},{"location":"cli_commands/#limit-the-number-of-hops-for-an-advert-flood-message","title":"Limit the number of hops for an advert flood message","text":"<p>Usage: - <code>get flood.max.advert</code> - <code>set flood.max.advert &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Maximum flood hop count (0-64) for an advert packet</p> <p>Default: <code>8</code></p>"},{"location":"cli_commands/#forward-flood-group-data-packets-on-repeaters","title":"Forward flood group data packets on repeaters","text":"<p>Usage: - <code>get flood.channel.data</code> - <code>get flood.channel.data.hops</code> - <code>set flood.channel.data &lt;on|off&gt;</code> - <code>set flood.channel.data.hops &lt;all|1-7&gt;</code></p> <p>Parameters: - <code>on</code>: Retransmit received flood <code>GRP_DATA</code> channel packets. - <code>off</code>: Do not retransmit received flood <code>GRP_DATA</code> channel packets. - <code>all</code>: When <code>flood.channel.data</code> is <code>off</code>, block <code>GRP_DATA</code> at any received flood hop count. - <code>1-7</code>: When <code>flood.channel.data</code> is <code>off</code>, repeat <code>GRP_DATA</code> at this hop count or lower and block longer paths.</p> <p>Default: <code>flood.channel.data on</code>; <code>flood.channel.data.hops h=all</code></p> <p>Forwarding behavior: Repeater firmware only. The repeater still receives and logs the packet when logging is enabled; this only blocks retransmission. On generalized repeaters these commands manage an ordinary visible FPF7 <code>type=grp_data</code> drop row. <code>off</code> with <code>all</code> maps to <code>hops=all</code>; <code>off</code> with <code>N</code> maps to <code>hops=N+1+</code>. The 240 KB compact FPF6 profiles retain the legacy hard gate. Because it is an ordinary FPF7 row, a matching higher-priority <code>stop</code> rule can exempt traffic from it. The compact <code>get flood.filter</code> list marks the managed row with <code>~data</code>. Flood group text (<code>GRP_TXT</code>) is unaffected by this setting.</p> <p><code>get flood.channel.data</code> includes the active hop gate as <code>h=all</code> or <code>h&gt;N</code>.</p>"},{"location":"cli_commands/#bridge-and-radio-crossover-filters","title":"Bridge and radio crossover filters","text":"<p><code>mode=</code> selects where a generalized <code>flood.rule</code> / <code>flood.filter</code> row applies:</p> Mode Where the rule applies <code>radio</code> Ordinary LoRa flood forwarding. This is the default when <code>mode=</code> is omitted. <code>bridge</code> Packets entering or leaving an RS232 or ESP-NOW bridge, and MeshCore RX/TX packet publication through MQTT. <code>cross</code> Transmissions copied to the other radio profile, including a copy's retries. The same-profile transmission remains eligible. <code>bridge,cross</code> Both transport paths using one rule. <code>cross,bridge</code> is equivalent. <p>The third built-in repeater rule blocks authenticated <code>#wardriving</code> text and data at all hops on bridge and crossover paths, including temporary-radio sessions. It leaves same-profile traffic subject to the separate four-hop rule. <code>set radio2.cross on</code> does not override this filter.</p> <pre><code># Factory slot: inspect before replacing an existing rule.\nget flood.rule.3\nset flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\n# On an existing device, add it without overwriting an occupied slot.\nset flood.rule type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>Saved tables are preserved on upgrade; new defaults are seeded only when the table is first initialized. Bridge/cross modes accept drop, rate, priority and stop actions; scope rewrites, retry actions and TX timing are rejected. These modes cover direct as well as flood packets, in both crossing directions. The default authenticates the channel key, avoiding false drops from short channel-hash collisions. FULL room servers support explicit transport rules; companions and compact FPF6 profiles do not expose this table.</p> <p>See filtering documentation for persistence, queue/rate semantics, exceptions, and how to remove one or both blocks.</p>"},{"location":"cli_commands/#block-selected-flood-channels-with-fpf7","title":"Block selected flood channels with FPF7","text":"<p>The separate <code>flood.channel.block</code> command and 15-row table have been retired. Generalized repeaters use the 63-row FPF7 forward phase for authenticated channel blocks:</p> <pre><code>set flood.rule type=any channel=#test hops=all drop\nset flood.rule.2 type=any channel=#wardriving hops=5+ drop\nset flood.rule type=any channel=9cd8fcf22a47333b591d96a2b848b73f hops=4+ drop\nget flood.rule\ndel flood.rule.2\n</code></pre> <p><code>type=any</code> with a channel condition can authenticate only <code>GRP_TXT</code> and <code>GRP_DATA</code>, so it does not match other payload types. Use <code>hops=all</code> to block at every received hop count. To preserve the old <code>h=N</code> meaning of repeating through <code>N</code> hops and blocking longer paths, use <code>hops=N+1+</code>; old <code>h=4</code> is therefore <code>hops=5+</code>.</p> <p>New generalized repeater tables seed slot 2 with the second example. Existing FCB2 rows are imported once into free FPF7 slots and the retired file is then removed. The fixed-size STM32WL FPF6 build cannot match authenticated channels.</p>"},{"location":"cli_commands/#force-a-transport-scope-onto-floods","title":"Force a transport scope onto floods","text":"<p>Usage: - <code>get flood.channel.scope</code> - <code>get flood.channel.scope.&lt;n&gt;</code> - <code>set flood.channel.scope &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]</code> - <code>set flood.channel.scope.&lt;n&gt; &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]</code> - <code>del flood.channel.scope.&lt;n&gt;</code> - <code>del flood.channel.scope all</code></p> <p>Parameters: - <code>n</code>: Slot number within the table compiled for the target. Roomy ESP32 builds   provide <code>1-255</code>; classic ESP32 repeaters and nRF52/other   normal constrained builds provide <code>1-31</code>; very-tight STM32WL repeaters provide   <code>1-15</code>; the no-PSRAM LilyGo T-LoRa V2.1 repeater/observer provides <code>1-4</code>. - <code>channel</code>: <code>public</code>, a public <code>#channel</code>, or a 128/256-bit channel key in hex. - <code>txt:*</code>: Unauthenticated fallback for otherwise-unmatched <code>GRP_TXT</code> and   <code>GRP_DATA</code>. Plain <code>*</code> is an alias for <code>txt:*</code>. - <code>login:*</code>: Type-based wildcard for the remote-login/admin family: <code>REQ</code>,   <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code> (<code>0x00</code>, <code>0x01</code>, <code>0x02</code>,   <code>0x07</code>, and <code>0x08</code>). It classifies the outer type; a transit repeater cannot   authenticate whether a packet is actually part of a login session. - <code>other:*</code>: Type-based wildcard for every remaining flood payload type,   including flood-form TRACE, ACK, advert, multipart, control, OTA, reserved   types, and raw custom. - <code>region</code>: Existing named region with a usable transport key. A unique region   name prefix is accepted; wildcard region <code>*</code> is not a scope target. - <code>scope=&lt;name&gt;</code>: Regionless alternative to <code>region</code>. The public name is   normalized with a leading <code>#</code>, and its 128-bit transport key is derived   directly from that hashtag exactly as for <code>flood.filter scope=&lt;name&gt;</code>. It   does not need to exist in the region list. Public names up to 30 characters   are accepted; private <code>$</code> scopes are not. - <code>path=blacklist</code>: Optional. Require the received path to match the passive   <code>flood.filter.blacklist</code> ID table. No <code>flood.filter</code> drop row needs to be   enabled. One exact listed ID qualifies a 3-byte path. A 2-byte path requires   two matching received path entries, while a 1-byte path never qualifies. - <code>path=bucket:&lt;1-6&gt;</code>: Optional alternative to <code>path=blacklist</code>. Match IDs in   the selected persistent <code>flood.retry.bucket</code>. Each bucket holds up to 17   three-byte IDs and remains usable when <code>flood.retry.bridge</code> is off. It uses   the same 3-byte, 2-byte, and 1-byte thresholds as <code>path=blacklist</code>.   <code>recent.repeater</code> freshness and <code>flood.retry.ignore</code> do not affect this   passive match. - <code>tx=slow</code>: Optional. Use an effective inbound <code>rxdelay</code> base of   <code>max(2, configured rxdelay * 2)</code>, keep normal outbound queue priority, and   schedule retransmission with the maximum supported <code>txdelay</code> factor of   <code>2.0</code> after changing the scope. The default is fast; <code>tx=fast</code> may be   supplied explicitly when replacing a slow row.</p> <p>Default: No forced scopes.</p> <p>Remote ACL permission <code>4</code> (region/scope manager) can use all <code>get</code>, <code>set</code>, and <code>del flood.channel.scope</code> forms. Filter managers and other non-admin roles cannot change this table.</p> <p>Without <code>.n</code>, <code>set</code> updates the row for the same exact channel key or wildcard class with the same path selector, otherwise it uses the first empty slot. This permits an ordinary fallback and separate blacklist or bridge-bucket rows for the same channel. With <code>.n</code>, it replaces that slot. The three wildcard classes are independent and consume one slot each. <code>get flood.channel.scope</code> reports active/total slot counts; use the numbered form for row detail. Keyed rows are displayed by the first four bytes of their derived channel hash because channel secrets are never returned. Regionless targets are displayed with their normalized leading <code>#</code>.</p> <p>This acts on received <code>ROUTE_TYPE_FLOOD</code> and <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> packets. An unscoped packet gains the configured scope; an already-scoped packet has its existing transport codes replaced. For <code>GRP_TXT</code> and <code>GRP_DATA</code>, all exact channel-key rows are tried first and must validate the packet MAC/decryption. Matching path-qualified exact rows are   tried before ordinary exact fallback rows. A region-backed row whose target   is missing or unusable is skipped; later exact rows and then <code>txt:*</code> are tried. Exact keyed rows with a usable target therefore beat <code>txt:*</code> regardless of slot number. Within each wildcard class, path-qualified rows similarly precede ordinary fallback rows. <code>login:*</code> and <code>other:*</code> select their non-overlapping outer-type families without decrypting the payload. The lowest usable slot wins within each priority tier.</p> <p>Standard traceroute is direct-routed and is therefore outside this flood-only table. A custom flood-form <code>TRACE</code> is treated like every other flood: an applicable wildcard may rewrite it and region/unknown-code gates still apply.</p> <p>On a match, the repeater sets the route to <code>ROUTE_TYPE_TRANSPORT_FLOOD</code>, computes transport code 0 from the selected region or direct hashtag key and packet payload, and sets transport code 1 to zero. This occurs before region enforcement, forwarding filters, and the seen-packet lookup. For an already-scoped packet, the selected code replaces both incoming transport-code fields. Direct routes are never rewritten. A packet converted from unscoped is no longer subject to <code>flood.max.unscoped</code>; all rewritten packets remain subject to normal payload handling, <code>flood.max</code>, <code>flood.filter</code>, loop detection, and moderation. Assigning a scope does not make a packet type forwardable if the core would otherwise reject it. By default, if the selected scope differs and the rewritten packet is accepted for forwarding, its initial retransmission uses zero <code>txdelay</code> and the highest outbound queue priority so the newly scoped copy can win at the next hop. Adding <code>tx=slow</code> uses an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, keeps the ordinary queue priority, and uses the maximum <code>txdelay</code> factor of <code>2.0</code> for the retransmission. As with ordinary <code>txdelay</code>, the actual transmit delay is randomized from zero through the resulting window; factor <code>2.0</code> gives a maximum of ten packet airtimes. Neither mode preempts an active radio transmission or bypasses CAD and airtime-budget limits. Selecting the scope already carried by the packet is a no-op and does not grant special transmit treatment.</p> <p>A region-backed target must be locally flood-allowed and remains subject to the normal region gate. A <code>scope=&lt;name&gt;</code> target is trusted for this matched receive pass even though it has no region-list entry, matching the behavior of <code>flood.filter scope=&lt;name&gt;</code>. It does not create a region, consume a region slot, or change the allow/deny state for unrelated packets carrying the same transport code.</p> <p>If a region-backed row's target has been removed or has no usable key, the repeater tries the next applicable row. For group packets this means later authenticated exact rows followed by <code>txt:*</code>; wildcard duplicates likewise fall through to the next usable slot. When no usable mapping exists, the packet retains its original unscoped or scoped route.</p> <p>LoRa OTA remains functional when <code>other:*</code> is configured. OTA packets are given that target's transport code, replacing an existing code when necessary, but the OTA handler still accepts and re-floods them during the temporary-radio window. A region target must allow flooding; a direct target follows the regionless trust behavior above. The OTA core itself is dormant outside that window; no default flood filter row is needed for that behavior. Forced scope does not make OTA operate outside the window.</p> <p>Capacity cost: Each rule slot retains its 36-byte runtime and persistent record. A separate 32-byte-name table holds up to the smaller of the rule count or 32 distinct regionless targets; very-tight STM32WL builds hold one reusable direct target. Region-backed targets do not consume this table. The four-slot minimum uses 272 bytes RAM and a 278-byte file; it has room for the three wildcard classes plus one exact channel mapping. Very-tight 15-slot builds use 572 bytes RAM and a 578-byte file. The 31-slot table uses 2,108 bytes RAM and a 2,114-byte file. Roomy ESP32 builds use 255 rule slots and 32 direct-target slots: 10,204 bytes RAM and a 10,210-byte file. Classic ESP32 LoRa-OTA builds that cannot afford the 255-rule table use 31 slots instead. Both configured regions and regionless targets can be reused by any number of rules.</p> <p>Duplicate behavior: Mesh dedup hashes payload type and payload bytes; it does not hash route type, transport codes, or the ordinary flood path. Adding a transport scope therefore does not create a new duplicate identity. If the same payload later arrives scoped, unscoped, or through a different region, it is still the same seen packet. <code>TRACE</code> is the exception only in that its encoded <code>path_len</code> byte is also hashed.</p> <p>While equivalent non-TRACE flood copies are waiting in <code>rxdelay</code>, the normal receive-quality timing still selects the packet to process, but that winner receives a scope from the queued scoped copies with the same dedupe identity. If the copies carry different locally allowed scopes, the scope from the shortest received path wins. Unknown and denied transport codes are not candidates and therefore cannot overwrite an unscoped winner. With equal path lengths, the deeper child region wins because it is narrower. A remaining tie keeps queue order. The winner's own path, SNR reading, and scheduled time are not changed, and an already-scoped winner may have its code replaced by the better queued scope.</p> <p>The comparison is deferred until dequeue so each copy retains its original scope and path for arbitration. It can only use copies still present in <code>rxdelay</code>; it cannot replace a packet that already won the dedupe race. Flood-form TRACE participates in this arbitration; direct traceroute does not enter the flood queue.</p> <p>A packet that matches a fast <code>flood.channel.scope</code> or <code>flood.filter scope=</code> action and needs its scope changed bypasses the inbound <code>rxdelay</code> queue. A <code>tx=slow</code> row remains in that queue with twice the configured base, floored at <code>2.0</code>, and participates in normal queued-copy scope arbitration.</p> <p>Examples:</p> <pre><code>region put west\nregion save\nset flood.channel.scope #local west\nset flood.channel.scope.2 txt:* west tx=slow\nset flood.channel.scope.3 login:* west\nset flood.channel.scope.4 other:* west\nget flood.channel.scope\nget flood.channel.scope.1\ndel flood.channel.scope.2\n</code></pre> <p>A regionless exact mapping needs no <code>region</code> command:</p> <pre><code>set flood.channel.scope #rgdata scope=BlackHole86\nget flood.channel.scope\nget flood.channel.scope.1\n</code></pre> <p>For example, if an authenticated <code>#rgdata</code> packet arrives carrying scope <code>#usa</code>, that rule replaces <code>#usa</code> with <code>#BlackHole86</code> before forwarding. The rule also assigns <code>#BlackHole86</code> when the packet is unscoped or carries any other scope; it is a channel-to-target mapping, not an incoming-scope filter.</p> <p>To use bridge bucket 1 to assign <code>east</code> to <code>public</code> packets whose received 3-byte path contains <code>7576FB</code>, while assigning <code>west</code> to every other authenticated <code>public</code> packet:</p> <pre><code>set flood.retry.bucket 1 7576FB\nset flood.channel.scope public west\nset flood.channel.scope public east path=bucket:1\n</code></pre> <p>Additional 3-byte IDs may be added to bucket 1 later; any one exact hit qualifies the <code>east</code> row. This use is passive and does not require <code>flood.retry.bridge</code> to be enabled. The separate blacklist selector remains available for tables shared with <code>flood.filter path=blacklist</code> rules.</p>"},{"location":"cli_commands/#require-valid-incoming-scopes-only-on-selected-channels","title":"Require valid incoming scopes only on selected channels","text":"<p>Usage: - <code>get flood.channel.scope.require</code> - <code>get flood.channel.scope.require.&lt;n&gt;</code> - <code>set flood.channel.scope.require &lt;public|#channel|128/256-bit-key&gt;</code> - <code>set flood.channel.scope.require.&lt;n&gt; &lt;public|#channel|128/256-bit-key&gt;</code> - <code>del flood.channel.scope.require.&lt;n&gt;</code> - <code>del flood.channel.scope.require all</code></p> <p>Default: Empty; normal global region enforcement remains active.</p> <p>Once this table contains a row, received flood <code>GRP_TXT</code> and <code>GRP_DATA</code> packets use selective region enforcement. A packet authenticating against a listed channel key must already carry a transport scope matching a locally flood-allowed region. Listed channels arriving unscoped, with an unknown code, or with a denied region are not retransmitted. This tests the original incoming scope before any <code>flood.channel.scope</code> or <code>flood.filter scope=</code> rewrite. Those rewrite actions are skipped for a rejected listed channel, so they cannot rescue it or grant special receive/transmit timing.</p> <p>Other group channels bypass the region/unknown-code gate while the table is active. They remain subject to every other forwarding control, including <code>repeat</code>, <code>flood.max*</code>, packet filters, loop detection, payload validation, and moderation. Non-channel flood payload types retain normal global region enforcement.</p> <p>Channel matching validates the packet MAC/decryption with the configured key; the visible one-byte channel hash is only a prefilter. Public hashtag channels use their derived public key. Without <code>.n</code>, setting an existing key updates it and a new key uses the first empty slot. Numbered <code>set</code> replaces that slot. <code>get ...&lt;n&gt;</code> reports a four-byte derived prefix and key size without exposing the key. The table uses the same build-dependent slot count as <code>flood.channel.scope</code>.</p> <p>Remote ACL permission <code>4</code> can manage this table. Deleting its final row restores normal global region enforcement for group channels.</p> <p>Example:</p> <pre><code>set flood.channel.scope.require #bot\nget flood.channel.scope.require\nget flood.channel.scope.require.1\n</code></pre>"},{"location":"cli_commands/#change-persistent-flood-rules-in-the-field","title":"Change persistent flood rules in the field","text":"<p>For setup guidance, interactions with the existing forwarding controls, and worked moderation examples, see Flood Filtering and Moderation.</p> <p>Usage:</p> <ul> <li><code>get flood.rule</code></li> <li><code>get flood.rule.&lt;n&gt;</code></li> <li><code>get fr[.&lt;n&gt;]</code> (numbered form returns a complete short setter for copying)</li> <li><code>set fr[.&lt;n&gt;] &lt;type&gt; [h=&lt;range&gt;] [m=r|b|c|bc] [c=&lt;channel&gt;] &lt;d|s=&lt;scope&gt;|r=&lt;region&gt;|q=&lt;N&gt;|r|s&gt; [...]</code></li> <li><code>del fr.&lt;n&gt;</code> or <code>del fr all</code></li> <li><code>set flood.rule[.&lt;n&gt;] type=&lt;type&gt; [mode=radio|bridge|cross|bridge,cross] [hops=&lt;range&gt;] [channel=&lt;channel&gt;] [prefix=&lt;path-prefix&gt;] [in=&lt;input-scope&gt;] &lt;drop|scope=&lt;name&gt;|region=&lt;name&gt;|rate=&lt;N&gt;/min|retry|stop&gt; [priority=&lt;0-255&gt;] [tx=slow] [suspend=tempradio]</code></li> <li><code>del flood.rule.&lt;n&gt;</code></li> <li><code>del flood.rule all</code></li> <li><code>get flood.filter</code></li> <li><code>get flood.filter.&lt;n&gt;</code></li> <li><code>get flood.filter.blacklist</code></li> <li><code>get flood.filter.blacklist.&lt;n&gt;</code></li> <li><code>set flood.filter.blacklist &lt;ID[,ID...]&gt;</code></li> <li><code>set flood.filter.blacklist.&lt;n&gt; &lt;ID[,ID...]&gt;</code></li> <li><code>del flood.filter.blacklist</code></li> <li><code>del flood.filter.blacklist.&lt;n&gt;</code></li> <li><code>set flood.filter &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]</code></li> <li><code>set flood.filter.&lt;n&gt; &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]</code></li> <li><code>del flood.filter.&lt;n&gt;</code></li> <li><code>del flood.filter all</code></li> </ul> <p>The extended table is available on repeaters with the rule engine enabled and on FULL-profile ESP32 room servers. A FULL room server exposes <code>fr</code>, <code>flood.rule</code>, and <code>flood.filter</code>, has 31 slots, and requires an administrator for remote changes. It does not have the repeater's passive path blacklist, so <code>flood.filter.blacklist*</code> and <code>path=blacklist</code> are repeater-only; use the ordered <code>prefix=</code> match on a room server. Standard room-server profiles do not compile this table.</p> <p>Parameters:</p> <ul> <li><code>n</code>: Forward-rule slot in the build's compiled table (<code>1-63</code> on generalized   repeaters and <code>1-31</code> on FULL room servers; compact profiles may use fewer).</li> <li><code>mode</code>: Optional; omitted means <code>radio</code>. <code>bridge</code> filters bridge admission,   <code>cross</code> filters copies to the other radio profile, and <code>bridge,cross</code> covers   both with one row. <code>cross,bridge</code> is an alias. See the   mode matrix for scope and supported actions.</li> <li><code>type</code>: Payload type name, full <code>PAYLOAD_TYPE_*</code> name, decimal value <code>0-15</code>,   hexadecimal value <code>0x00-0x0F</code>, or <code>any</code>.</li> <li><code>hops</code>: Optional; omitted means <code>all</code>.</li> <li><code>N</code>: Match only at received hop count <code>N</code>.</li> <li><code>N+</code>: Match at received hop count <code>N</code> and higher.</li> <li><code>N-M</code>: Match the inclusive received-hop range.</li> <li><code>all</code>: Match every received hop count (<code>0-63</code>).</li> <li><code>0+</code>, <code>all</code>, and an omitted hop expression are equivalent. The CLI displays     the saved range as <code>all</code>.</li> <li><code>channel=*|public|#name|hash:XX|128-bit-key|256-bit-key</code>: Optional channel match.   <code>channel=*</code> means no channel condition at all, so the row matches everything   selected by <code>type=</code> (including all flood payload types with <code>type=any</code>). It   does not authenticate a packet. <code>public</code>, <code>#name</code>, and raw keys authenticate   one channel and therefore narrow the row to <code>GRP_TXT</code>/<code>GRP_DATA</code>.   <code>hash:XX</code> matches only the visible one-byte group-channel hash; <code>short:XX</code>   and a bare two-digit byte are accepted aliases and are displayed as   <code>hash:XX</code>. This form is deliberately unauthenticated. It can collide with   another channel once in 256 hash values, and a sender can choose the byte,   so use an exact channel name or key whenever it is available. In particular,   <code>channel=hash:11</code> does not mean Public: it matches Public plus every collision   or deliberately selected <code>0x11</code> value. <code>channel=public</code> performs the deeper   MAC/decrypt check with the Public channel key. That distinguishes an ordinary   <code>0x11</code> collision, but it is channel authentication rather than sender   authentication: the group MAC is two bytes and the Public key is shared.</li> <li><code>prefix=&lt;ID[,ID...]&gt;</code>: Optional ordered source-path prefix of one to three   pbyte IDs. IDs must all be 2, 4, or 6 hex characters, matching a packet's   1-, 2-, or 3-byte pbyte width. <code>path=&lt;prefix&gt;</code> is an alias.</li> <li><code>in=any|none|scoped|allowed|unknown|scope:&lt;name&gt;|region:&lt;name&gt;</code>: Optional   condition on the original incoming scope, before any rule rewrites it.   <code>none</code> is an unscoped flood. <code>scope:name</code> is the exact public   hashtag-derived scope. <code>region:name</code> is an exact allowed region match.</li> <li><code>drop</code>: Explicit drop action. The <code>flood.rule</code> form requires an explicit   action. For compatibility, a legacy <code>flood.filter</code> row with no rewrite,   rate, or stop action is treated as drop.</li> <li><code>scope=&lt;name&gt;</code>: Direct public-name scope rewrite. It derives a transport key   from the name and does not require a configured region. For example,   <code>scope=BlackHole86</code> is a regionless sink scope; <code>region=BlackHole86</code> would   instead require a real configured, flood-allowed region with that name.</li> <li><code>region=&lt;name&gt;</code>: Rewrite using an existing locally allowed region and one of   that region's transport keys.</li> <li><code>rate=N/min</code>: Per-node, per-row fixed one-minute forwarding limit. It can be   the only action or accompany <code>scope=</code>/<code>region=</code>. Counters are charged only   for packets that pass all forwarding gates.</li> <li><code>retry</code>, <code>retry=on</code>, <code>retry=allow</code>, or <code>action=retry</code>: Allow a matching   received flood packet to enter the configured flood-retry sequence. With no   active <code>retry</code> rows, retry eligibility remains backward compatible and is   controlled by the global retry settings. Once any active <code>retry</code> row exists,   the matching rows become a retry allow-list: a received flood must match at   least one surviving <code>retry</code> row. <code>flood.retry.bridge</code> still selects ordinary   or bridge-bucket completion for the allowed packet. This action can accompany   rewrite, rate, or stop, but not <code>drop</code>; compact syntax uses <code>f=r</code>.</li> <li><code>priority=0-255</code>: Optional primary processing order. Higher values run first.   At the same numeric priority, authenticated channel matches run before raw   <code>hash:XX</code> matches, which run before <code>channel=*</code>; lower slot number breaks the   remaining tie. The default is <code>0</code>; <code>pri=</code> is an alias. An explicitly higher   numeric priority still overrides this automatic specificity ordering.</li> <li><code>stop</code> or <code>action=stop</code>: Apply this matching row, then stop lower-order FPF7   rows from processing. It can stand alone or accompany drop, rewrite, or   rate. A stop-only row acts as an exception to lower-priority FPF7 rules.   If the same row uses <code>region=</code> and that configured region is missing, denied,   wildcard, or has no usable transport key, both the rewrite and its <code>stop</code>   are inert so lower-order safety rows still run. A direct <code>scope=</code> target does   not depend on region configuration.</li> <li><code>suspend=tempradio</code>: Optional. Skip this row while either <code>tempradio</code> or   <code>tempradio2</code> is active, including scheduled temporary sessions.</li> <li><code>require=region</code>: Legacy alias for <code>in=allowed</code>. Apply the row only if the   original incoming packet already passes this repeater's   region gate. An incoming transport scope must resolve to a locally allowed   region; an unscoped flood must be allowed by the wildcard region. The check   occurs before any scope rewrite during this receive pass.</li> <li><code>tx=slow</code>: Optional and valid with <code>scope=</code> or <code>region=</code>. Use an effective inbound   <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, keep normal outbound   queue priority, and retransmit with the maximum supported <code>txdelay</code> factor   of <code>2.0</code>. Scope rows default to fast; <code>tx=fast</code> explicitly restores that   default when replacing a slow row.</li> <li><code>path=blacklist</code>: Optional unordered path condition. The persistent blacklist   is repeater-only. It contains up to 255 unique 3-byte repeater IDs on ESP32   builds and 18 on other builds, each written as six hexadecimal digits. A   packet with 3-byte path hashes matches after one exact ID hit. A packet with   2-byte path hashes matches after two path entries match the first two bytes   of listed IDs. Packets with 1-byte path hashes never match this condition.   Each received path entry is counted at most once.</li> </ul> <p>The payload names follow the MeshCore packet-format allocation:</p> Value Short name Full name <code>0x00</code> <code>req</code> <code>PAYLOAD_TYPE_REQ</code> <code>0x01</code> <code>response</code> <code>PAYLOAD_TYPE_RESPONSE</code> <code>0x02</code> <code>txt_msg</code> <code>PAYLOAD_TYPE_TXT_MSG</code> <code>0x03</code> <code>ack</code> <code>PAYLOAD_TYPE_ACK</code> <code>0x04</code> <code>advert</code> <code>PAYLOAD_TYPE_ADVERT</code> <code>0x05</code> <code>grp_txt</code> <code>PAYLOAD_TYPE_GRP_TXT</code> <code>0x06</code> <code>grp_data</code> <code>PAYLOAD_TYPE_GRP_DATA</code> <code>0x07</code> <code>anon_req</code> <code>PAYLOAD_TYPE_ANON_REQ</code> <code>0x08</code> <code>path</code> <code>PAYLOAD_TYPE_PATH</code> <code>0x09</code> <code>trace</code> <code>PAYLOAD_TYPE_TRACE</code> <code>0x0A</code> <code>multipart</code> <code>PAYLOAD_TYPE_MULTIPART</code> <code>0x0B</code> <code>control</code> <code>PAYLOAD_TYPE_CONTROL</code> <code>0x0C</code> <code>ota</code> <code>PAYLOAD_TYPE_OTA</code> (this fork's LoRa OTA extension; reserved upstream) <code>0x0D</code> <code>13</code> reserved <code>0x0E</code> <code>14</code> reserved <code>0x0F</code> <code>raw_custom</code> <code>PAYLOAD_TYPE_RAW_CUSTOM</code> <p>Route scope: <code>mode=radio</code> rules are evaluated only for the two flood route values: <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> (<code>0x00</code>, flood plus transport codes) and <code>ROUTE_TYPE_FLOOD</code> (<code>0x01</code>, unscoped flood). Direct routes <code>0x02</code> and <code>0x03</code> are unaffected by radio rules. Bridge/cross rules also cover direct routes at their respective transport boundaries.</p> <p>Behavior: Match fields within one row are ANDed. Radio rows are matched against the same immutable receive-time packet, before any rule changes its scope. Bridge/cross rows match the packet at their admission boundary; a TX packet can already have an appended hop or rewritten scope. Each mode evaluates only its applicable rows, processed in descending <code>priority</code>. At equal numeric priority, authenticated channel matches precede raw hashes, which precede an unrestricted channel matcher; lower slot wins after that. The first matching <code>stop</code> row is included and all lower-order FPF7 matches are discarded. A stop cannot undo an earlier drop or bypass hard forwarding gates or the other policy phases. A row with <code>path=blacklist</code> must meet the path condition as well as its other conditions; blacklist IDs can occur anywhere in the received path and their configured order is irrelevant. In contrast, <code>prefix=</code> begins at the first received path entry and preserves order. A matching drop row prevents retransmission. The highest-order remaining matching scope/region row wins; matching drop and rate rows remain independent and can still block the rewritten packet. Scope rewriting happens before region enforcement and is trusted even when its name is absent from the local region list. It does not bypass <code>repeat</code>, <code>flood.max</code>, other drop rows, loop detection, or moderation.</p> <p>Retry selection uses that same ordered, stop-truncated match set. With at least one active <code>retry</code> row, a received flood starts a retry sequence only when one of those matching rows includes <code>retry</code>. This selector cannot override <code>flood.retry.count</code>, path/type attempt caps, <code>flood.retry.advert</code>, disabled forwarding, a drop decision, or any other hard forwarding gate. Locally originated floods retain the normal global retry behavior.</p> <p>With <code>require=region</code>, a failed check makes that scope row ineligible. It leaves the packet unchanged and does not set the filter-scope trust bypass, so an unknown or denied incoming region is rejected normally unless another independent scope rule rewrites it. Later eligible filter scope rows may still match.</p> <p>By default, when a scope row will change the packet's transport codes, the packet bypasses inbound <code>rxdelay</code>; its retransmission then uses zero <code>txdelay</code> and the highest outbound queue priority. With <code>tx=slow</code>, the rewrite instead uses an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, normal queue priority, and the maximum <code>txdelay</code> factor of <code>2.0</code>. The actual randomized transmit wait ranges from zero to ten packet airtimes. Selecting the scope already carried is a no-op and does not grant special treatment. An active radio transmission is not preempted, and CAD and airtime-budget limits still apply.</p> <p>The packet is still received and can still be logged. Rules are persistent data and can be changed over serial or authenticated remote CLI without an OTA or reboot. <code>flood.rule</code> and <code>flood.filter</code> address the same table on extended builds; FPF6 files are migrated in memory and the next save writes FPF7. FPF1-FPF5 files are rejected and filtering fails open. FPF7 stores canonical region names rather than transient numeric region IDs. Removing, reordering, or reusing a region ID therefore cannot silently retarget a rule. If a saved input or target region name is absent, that input match or rewrite is inert; restoring the same region name reactivates it. While either <code>tempradio</code> or <code>tempradio2</code> is active, only rows explicitly marked <code>suspend=tempradio</code> are skipped. Temporary radio is a radio state, not an OTA mode; normal payload types can also use the temporary channel. Other rows remain in force, and suspended rows resume after both temporary sessions end. A malformed persisted table fails open (no general rules are applied).</p> <p>Within one receive evaluation, rows that use the same channel key share one authentication result. The cache is discarded after that packet and stores neither plaintext nor passwords; different keys are authenticated separately. Raw <code>hash:XX</code> rows skip this authentication and compare only the one visible byte.</p> <p>Per-channel retry examples:</p> <pre><code># Use bridge-bucket retry only for authenticated Public and #hamradio traffic.\nset flood.retry.bridge on\nset flood.rule.2 type=any channel=public retry\nset flood.rule.3 type=any channel=#hamradio retry\n\n# If the channel key/name is unavailable, select visible channel hash A7.\n# This is an unauthenticated 1-byte hint, not a channel identity.\nset flood.rule.4 type=any channel=hash:A7 retry\n</code></pre> <p>Because Public's visible hash is <code>0x11</code>, a bare <code>hash:11 drop</code> row also matches Public. To exempt authenticated Public while dropping other packets that carry the same visible byte, put the exact Public rule first and stop lower-priority rules after it:</p> <pre><code># Retry and preserve authenticated Public; drop other channel-hash 11 packets.\nset flood.rule.2 type=any channel=public retry stop\nset flood.rule.3 type=any channel=hash:11 drop\n</code></pre> <p>The Public row matches only after its MAC/decrypt check succeeds. A colliding channel therefore misses that <code>stop</code> and reaches the raw-hash drop row. Both rows use the default numeric priority, but authenticated-channel specificity automatically orders Public first even if its slot number is higher. Without <code>stop</code>, both rows match Public and the sticky <code>drop</code> action wins. Omit <code>retry</code> from the Public row when only the forwarding exemption is wanted. An operator can deliberately reverse this order by assigning the hash row a higher numeric <code>priority</code>.</p> <p>Deleting or replacing the last active <code>retry</code> row restores the legacy global retry eligibility. Firmware that predates the <code>retry</code>/<code>hash:XX</code> FPF7 extension cannot preserve tables containing those rows; remove them before downgrading.</p> <p>Default rows: Repeater firmware and FULL ESP32 room-server firmware seed a new flood-filter table with <code>ota all suspend=tempradio</code> in slot 1. This blocks repeated LoRa OTA (<code>0x0C</code>) floods at every received hop unless either temporary radio profile is active. The OTA core independently refuses OTA receive, relay, and transmit outside temporary radio. The row is editable and deletable; once the table is saved, deletion is persistent. Restore the exact seeded row with:</p> <pre><code>set flood.filter.1 0x0C all suspend=tempradio\n</code></pre> <p>Omitting <code>all</code> is equivalent. Omit <code>.1</code> as well to reuse an identical rule or the first empty slot instead of replacing slot 1.</p> <p>Generalized repeaters also seed slot 2 with the authenticated <code>#wardriving</code> radio hop limit and slot 3 with the bridge/crossover block:</p> <pre><code>set flood.rule.2 type=any channel=#wardriving hops=5+ drop\nset flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>These numbered commands replace those slots. Saved tables are preserved on upgrade; use the unnumbered third command to add the new rule without replacing an occupied slot. See restoring the three defaults.</p> <p>Remote-admin lockout warning: There are no hidden payload-type or short-hop exceptions. FPF7 drop and rate rows may block <code>req</code>, <code>response</code>, <code>txt_msg</code>, <code>anon_req</code>, <code>path</code>, ACK, and multipart traffic beginning at hop <code>0</code> when their match fields say so. Transit repeaters cannot decrypt these outer types to distinguish an admin exchange from ordinary peer traffic. Keep a serial or other recovery path and stage broad deny/rate rules carefully.</p> <p>Without <code>.n</code>, <code>set</code> reuses an identical rule or uses the first empty slot. With <code>.n</code>, it replaces that slot, which is the intended way to change a row's match or action. <code>get flood.filter</code> or <code>get flood.rule</code> gives a compact list. Use the numbered form for full details, including channel, prefix, original-scope condition, action, timing, rate, and temporary-radio suspension.</p> <p><code>fr</code> is a shorter alias for <code>flood.rule</code>, with the same explicit-action requirement. Short and long field names can be mixed in either command:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nset fr.3 any c=#wardriving m=bc d\nget fr.3\n</code></pre> <p>The two setters above save the same row. <code>get fr.3</code> returns the complete short setter; <code>get fr</code> lists the table. Unnumbered <code>set fr ...</code> reuses an identical row or adds one to the first empty slot. <code>del fr.N</code> and <code>del fr all</code> have the same behavior as their long forms.</p> Full token Short token <code>type=...</code> Positional type or <code>t=...</code>; <code>*</code> means <code>any</code> <code>hops=...</code> Positional range or <code>h=...</code>; <code>*</code> means <code>all</code> <code>mode=radio/bridge/cross/bridge,cross</code> <code>m=r/b/c/bc</code> (choose one value) <code>channel=...</code>, <code>prefix=...</code> <code>c=...</code>, <code>p=...</code> <code>path=blacklist</code> <code>p=bl</code> (repeater only) <code>in=any/none/scoped/allowed/unknown</code> <code>i=*/n/s/a/u</code> (choose one value) <code>in=scope:name</code>, <code>in=region:name</code> <code>i=s:name</code>, <code>i=r:name</code> <code>drop</code>, <code>stop</code>, <code>retry</code> <code>d</code>, <code>s</code>, <code>r</code> <code>scope=name</code>, <code>region=name</code> <code>s=name</code>, <code>r=name</code> <code>rate=N/min</code>, <code>priority=N</code> <code>q=N</code>, <code>pri=N</code> <code>tx=slow</code>, <code>suspend=tempradio</code>, <code>retry</code> <code>f=s</code>, <code>f=t</code>, <code>f=r</code>; combine as <code>f=str</code> <p>All existing validation and permissions apply. <code>m=cb</code>, <code>m=b,c</code>, and <code>m=c,b</code> also mean bridge and crossover. Short aliases for <code>flood.channel.scope</code>, <code>flood.moderation</code>, and blacklist management are not added.</p> <p>The numbered long getters use this complete short setter when descriptive fields would exceed a reply. Defaults are omitted and specific payload types are printed numerically. If it still cannot fit, the reply is <code>Err - compact command exceeds reply size</code>, never a partial setter. Private channel keys are shown as <code>key:XXXXXXXX</code>; that reference can be reused while an active rule on the same device holds the key. Copying it to another device requires the original key, unless that device already has a matching rule. Unknown or ambiguous references are rejected. See the shorthand guide for examples.</p> <p>On generalized repeaters, filter rows, scope-rewrite rows, the shared blacklist, and <code>flood.channel.data</code> compatibility state are committed in one atomic FPF7 image. Compact FPF6 profiles retain separate files. Replacing or deleting the blacklist does not delete rows containing <code>path=blacklist</code>; such rows remain dormant while the list is empty. Path hashes are truncated routing identifiers, not authenticated identities, so this is a forwarding signal rather than proof that a particular repeater handled a packet.</p> <p>A common use is containment of bulk internet-to-mesh dumping: list the path IDs associated with the offending gateways, then add a broad <code>type=any hops=all path=blacklist drop</code> row. This prevents this repeater from retransmitting matching floods; it does not delete them from local logs or prove who originated them.</p> <p>The unnumbered blacklist <code>set</code> replaces the whole list and accepts up to 18 IDs so it fits every CLI transport. Numbered <code>set</code> writes up to 18 consecutive entries beginning at an existing slot or exactly the next slot, allowing an ESP32 list to grow to 255 entries in batches. Numbered deletion compacts subsequent slots. The unnumbered <code>get</code> reports the total and as many leading IDs as fit in one reply; use numbered <code>get</code> to inspect entries beyond that reply.</p> <p>Standard traceroute is direct-routed and therefore outside <code>flood.filter</code> entirely. A custom flood-form trace participates normally: <code>type=any</code>, explicit <code>trace</code>, rewrite, rate, drop, and stop rows can all apply.</p> <p>Examples:</p> <pre><code>set flood.rule.2 type=grp_data hops=4+ channel=#rgdata in=none scope=BlackHole86\nset flood.rule.3 type=grp_data channel=#rgdata in=scope:usa scope=BlackHole86\nset flood.rule.4 type=any prefix=860C rate=10/min\nset flood.rule.5 type=grp_data hops=0-2 channel=#rgdata priority=200 stop\nget flood.rule.2\nset flood.filter grp_data 4+\nset flood.filter.2 PAYLOAD_TYPE_ADVERT 6+\nset flood.filter ota 2-4\nset flood.filter.1 0x0C all suspend=tempradio\nset flood.filter grp_data all suspend=tempradio\nset flood.filter grp_txt all scope=local\nset flood.filter grp_data all scope=local require=region\nset flood.filter grp_data all path=blacklist scope=local tx=slow\nset flood.filter.blacklist A1B2C3,D4E5F6,112233\nset flood.filter.blacklist.4 445566\nset flood.filter.blacklist.19 778899,AABBCC,DDEEFF\nset flood.filter any all path=blacklist\nget flood.filter.blacklist\nget flood.filter.blacklist.4\nset flood.filter any 12+\nget flood.filter\nget flood.filter.2\ndel flood.filter.2\n</code></pre> <p>The first rule authenticates <code>#rgdata</code>, requires more than three received hops, and adds <code>#BlackHole86</code> only when no scope was present. The second rewrites the exact incoming <code>#usa</code> scope. The third demonstrates a two-byte pbyte source prefix and a global per-row rate cap. The fourth authenticates <code>#rgdata</code> at zero through two hops, applies no FPF7 action of its own, and stops lower-order FPF7 forward rows; hard gates and the rewrite/moderation phases still apply.</p> <p>The fixed 240 KB STM32WL profiles leave <code>MESH_ENABLE_FLOOD_RULE_ENGINE=0</code> and retain the compact, persistent FPF6 <code>flood.filter</code> and blacklist commands. They still filter floods, but do not expose the <code>flood.rule</code> alias or its extended channel, prefix, input-scope, region-action, or rate fields. No partition size changes are required.</p>"},{"location":"cli_commands/#moderate-flood-group-text-by-channel-sender-and-source-path","title":"Moderate flood group text by channel, sender, and source path","text":"<p>Usage: - <code>get flood.moderation</code> - <code>get flood.moderation.&lt;n&gt;</code> - <code>set flood.moderation &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]</code> - <code>set flood.moderation.&lt;n&gt; &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]</code> - <code>del flood.moderation.&lt;n&gt;</code> - <code>del flood.moderation all</code></p> <p>Parameters: - <code>n</code>: Moderation slot from <code>1</code> to <code>16</code>. - <code>channel</code>:   - <code>public</code>: Built-in Public channel.   - <code>#channel</code>: Derive the well-known hashtag-channel key.   - A 128-bit or 256-bit channel key in hex, for any other/private channel. - <code>sender</code>: Exact group-text display name. Matching is ASCII case-insensitive.   Quote names containing spaces, for example <code>\"Field User\"</code>. - <code>drop</code>: Do not forward matching messages. Equivalent to <code>rate=0/min</code>. - <code>rate=X/min</code>: Forward at most <code>X</code> matching messages per 60-second local   window. This option requires an exact sender rather than <code>*</code>. - <code>hops=N</code>: Do not forward a matching message whose received flood path count   is <code>N</code> or higher. <code>hops=all</code> removes this constraint. - <code>path=H1[,H2,H3]</code>: Match the start of the flood path. One to three hashes are   accepted; every hash must have the same 1-, 2-, or 3-byte width. - <code>path=*</code>: Match any source path (the default).</p> <p>At least one of <code>drop</code>, <code>rate=X/min</code>, or <code>hops=N</code> is required. Rate and hop limits can be combined. Rate counters are local to this repeater and rule, use a 60-second window beginning with the first matching message, and reset on reboot.</p> <p>Decode and identity behavior: Moderation applies only to flood <code>PAYLOAD_TYPE_GRP_TXT</code>. The repeater first checks the packet's channel-hash byte, then validates and decrypts with the configured key. It extracts the text before the first <code>:</code> from the standard <code>&lt;sender&gt;: &lt;message&gt;</code> plaintext. The channel key is stored locally but is never printed by <code>get</code>.</p> <p>The group-text sender is an unverified display name, not a public key. It can be spoofed. Combining it with the first one to three path hashes makes a more useful moderation signal, but path hashes are truncated and are not proof of the originating user. A path-qualified rule begins matching only after the packet contains all configured starting hops; it cannot identify a first hop on a zero-hop packet.</p> <p>As with general filtering, matching messages are still received/logged; only retransmission is denied. There are no moderation rules by default.</p> <p>Examples:</p> <pre><code>set flood.moderation public \"Noisy User\" rate=5/min\nset flood.moderation #local bot drop path=A1B2C3,D4E5F6\nset flood.moderation.3 00112233445566778899AABBCCDDEEFF alice rate=10/min hops=4 path=71CE82\nget flood.moderation\nget flood.moderation.3\ndel flood.moderation.3\n</code></pre>"},{"location":"cli_commands/#acl","title":"ACL","text":""},{"location":"cli_commands/#add-update-or-remove-permissions-for-a-companion","title":"Add, update or remove permissions for a companion","text":"<p>Usage:  - <code>setperm &lt;pubkey&gt; &lt;permissions&gt;</code></p> <p>Parameters: - <code>pubkey</code>: Companion public key - <code>permissions</code>:    - <code>0</code>: Guest   - <code>1</code>: Read-only   - <code>2</code>: Read-write   - <code>3</code>: Admin   - <code>4</code>: Region/scope manager (repeater delegated region and forced-scope management)   - <code>5</code>: Filter manager (repeater delegated forwarding-filter management)</p> <p>Filter manager scope: Permission <code>5</code> can use an explicit allowlist of non-secret operational/filter status commands and can change the forwarding controls <code>repeat</code>, <code>loop.detect</code>, <code>flood.max*</code>, <code>flood.channel.data*</code>, <code>flood.filter*</code>, <code>flood.rule*</code>, <code>fr[.N]</code>, and <code>flood.moderation*</code>. It cannot read guest, WiFi, MQTT, bridge, or other credentials, and it cannot change regions, ACL entries, radio settings, or other admin configuration. Permission <code>4</code> is limited to region commands, <code>flood.channel.scope*</code>, and the same non-secret status allowlist. Both delegated manager roles are protected from least-recently-active ACL eviction like administrators.</p> <p>Note: Removes the entry when <code>permissions</code> is omitted</p>"},{"location":"cli_commands/#view-the-current-acl","title":"View the current ACL","text":"<p>Usage:</p> <ul> <li><code>get acl</code> - full listing locally; first page over LoRa</li> <li><code>get acl &lt;page&gt;</code> - a numbered page, starting at 1, locally or over LoRa</li> </ul> <p>Available on repeaters, room servers, and sensors. Over LoRa, an authenticated admin session is required; guests, read-only/read-write clients, and delegated region/filter managers cannot read the ACL.</p> <p>Each page starts with <code>ACL &lt;page&gt;/&lt;pages&gt;</code> and contains up to two entries. Each entry is a two-digit hexadecimal permission byte followed by the full 64-character public key. For example, use <code>get acl 2</code> for the second page. An empty list returns <code>ACL: empty</code>. Deleted/guest entries with permission byte <code>00</code> are omitted, matching the local listing. Pages reflect the current live ACL, so entries can move between pages if permissions or clients change.</p> <p>Bare <code>get acl</code> keeps the full streamed listing on USB and direct network CLI, or via Companion binary command <code>0x42</code> where the role supports the command. The listing contains public keys and permissions, not passwords or shared secrets, and does not change the ACL.</p>"},{"location":"cli_commands/#recover-a-repeaters-future-dated-replay-timestamp","title":"Recover a repeater's future-dated replay timestamp","text":"<p>This is an explicit recovery operation after correcting a bad clock, not a contact deletion. It lowers selected replay timestamps to the repeater's current UTC epoch only when they are later than that epoch. Earlier values, public keys, permissions, stored paths, and historical identity records remain. The replay file is committed before the live table changes. No extra 60-second login reservation is added by this command.</p> <p>First set/synchronize and verify the repeater's clock (<code>clock</code>); a build-default clock without a manual or observed synchronization is not accepted. Also fix the companion's clock before its next login.</p> <p>USB console:</p> <pre><code>replay reset &lt;full-64-hex-public-key&gt;\nreplay reset all CONFIRM\n</code></pre> <p>Authenticated LoRa admin, including a resumed admin session:</p> <pre><code>replay reset &lt;full-64-hex-public-key&gt;\n</code></pre> <p>The reply shows <code>now=&lt;epoch&gt;</code>, <code>ttl=&lt;remaining-seconds&gt;s</code>, and a confirmation command containing the same full key and a one-use 32-hex-character token. Verify the displayed time and send that command before the original 300-second deadline. During the first 120 seconds, repeated requests for the same key by the same admin return the same token without restarting either timer. From 120 through 300 seconds, the token is retained for confirmation only: requests do not resend or replace it. This leaves at least 180 seconds to deliver a confirmation after the last permitted token response is generated (radio transit time still counts toward expiry). At 300 seconds it expires and a new request can receive a new token. Confirmation can succeed immediately; there is no requirement to wait for the resend window to close. The displayed TTL decreases on retries and is measured when the reply is generated, not when it reaches the companion.</p> <p>It can target the caller's own key or another exact key; prefixes, <code>self</code>, wildcards, and <code>all</code> are not allowed over LoRa. Tokens are bound to both the requesting admin and target, expire on reboot, and are invalid after use or a clock correction outside the five-second confirmation tolerance. A failed write requires a new confirmation. Challenge requests consult live token state instead of replaying cached challenge text; completed confirmation results remain cacheable without executing the reset again. Normal packet freshness checks still apply to retries.</p> <p>Only the physical serial console grants <code>all</code> access. Ethernet, browser and internal command callbacks do not count as USB. Guest, read-only, region-manager and filter-manager roles cannot reset replay state. This command is implemented in repeater firmware; room-server and sensor CLI are unchanged.</p> <p>Normal login and command admission checks remain in force: a fully locked-out caller that cannot send an accepted admin command needs another working admin or USB access. A corrupt/unreadable replay file fails closed and is not erased or formatted by this operation. Unknown keys do not create records.</p> <p>Security trade-off: lowering a replay boundary can admit previously captured future-dated login/command packets above the new boundary, including packets that could raise it again. The one-use token prevents the recovery command itself from being repeatedly executed; it does not replace the protocol's timestamp-based replay protection. Use recovery only after verifying clocks. Setting a clock alone never automatically resets this table.</p>"},{"location":"cli_commands/#view-or-change-this-room-servers-read-only-flag","title":"View or change this room server's 'read-only' flag","text":"<p>Usage: - <code>get allow.read.only</code> - <code>set allow.read.only &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code> (enable) or <code>off</code> (disable)</p> <p>Default: <code>off</code></p> <p>Make a room read-only while allowing selected writers:</p> <pre><code>set allow.read.only on\nsetperm &lt;PUBKEY_USER_1&gt; 2\n</code></pre> <p>With read-only mode on, a client without a valid room password can join as a read-only guest. Permission <code>2</code> gives the specified public key read-write access. Replace <code>&lt;PUBKEY_USER_1&gt;</code> with the user's full public key and repeat <code>setperm</code> for every approved writer.</p> <p>This does not remove write access from clients that already know the room password. Keep that password private, or replace it, if write access should be limited to the explicitly permitted users.</p>"},{"location":"cli_commands/#region-management-v110","title":"Region Management (v1.10.+)","text":""},{"location":"cli_commands/#bulk-load-region-lists","title":"Bulk-load region lists","text":"<p>Usage:  - <code>region load</code> - <code>region load &lt;name&gt; [flood_flag]</code></p> <p>Parameters: - <code>name</code>: A name of a region. <code>*</code> represents the wildcard region</p> <p>Note: <code>flood_flag</code>: Optional <code>F</code> to allow flooding</p> <p>Note: Indentation creates parent-child relationships (max 8 levels)</p> <p>Note: <code>region load</code> with an empty name will not work remotely (it's interactive)</p>"},{"location":"cli_commands/#save-any-changes-to-regions-made-since-reboot","title":"Save any changes to regions made since reboot","text":"<p>Usage:  - <code>region save</code></p>"},{"location":"cli_commands/#allow-a-region","title":"Allow a region","text":"<p>Usage:  - <code>region allowf &lt;name&gt;</code></p> <p>Parameters:  - <code>name</code>: Region name (or <code>*</code> for wildcard)</p> <p>Note: Setting on wildcard <code>*</code> allows packets without region transport codes</p>"},{"location":"cli_commands/#block-a-region","title":"Block a region","text":"<p>Usage:  - <code>region denyf &lt;name&gt;</code></p> <p>Parameters:  - <code>name</code>: Region name (or <code>*</code> for wildcard)</p> <p>Note: Setting on wildcard <code>*</code> drops packets without region transport codes</p>"},{"location":"cli_commands/#show-information-for-a-region","title":"Show information for a region","text":"<p>Usage:  - <code>region get &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Region name (or <code>*</code> for wildcard)</p>"},{"location":"cli_commands/#view-or-change-the-home-region-for-this-node","title":"View or change the home region for this node","text":"<p>Usage:  - <code>region home</code> - <code>region home &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Region name</p>"},{"location":"cli_commands/#view-or-change-the-default-scope-region-for-this-node","title":"View or change the default scope region for this node","text":"<p>Usage:  - <code>region default</code> - <code>region default {name|&lt;null&gt;}</code></p> <p>Parameters: - <code>name</code>: Region name,  or  to reset/clear"},{"location":"cli_commands/#create-a-new-region","title":"Create a new region","text":"<p>Usage:  - <code>region put &lt;name&gt; [parent_name]</code></p> <p>Parameters: - <code>name</code>: Region name - <code>parent_name</code>: Parent region name (optional, defaults to wildcard)</p> <p>Note: In firmware v1.15.0 and later, <code>region put</code> enables flooding for that region by default (you do not need a separate <code>region allowf &lt;name&gt;</code> after each <code>put</code>). On v1.14.0 and earlier, new regions may still require <code>region allowf</code> for flooding-see <code>region allowf</code>.</p>"},{"location":"cli_commands/#define-region-hierarchy-single-line","title":"Define region hierarchy (single line)","text":"<p>Usage: - <code>region def &lt;token&gt; [&lt;token&gt; ...]</code></p> <p>Parameters (tokens): Space-separated. A logical cursor starts at the wildcard <code>*</code>.</p> <ul> <li><code>name</code> - Create <code>name</code> as a child of the current cursor (equivalent to <code>region put name</code> with the cursor as parent). Cursor moves to <code>name</code>.</li> <li><code>name|jump</code> (or <code>name,jump</code>) - Create <code>name</code> as a child of the current cursor, then move the cursor to <code>jump</code> (must already exist on the node, or have been created earlier in this command). <code>jump</code> is not the parent of <code>name</code>; use this form to pop back up and start another branch.</li> </ul> <p>Behavior: Each created region defaults to flood-allowed (same as <code>region put</code>). The reply is the resulting region tree (same format as bare <code>region</code>); review it before running <code>region save</code> to persist. The command is transactional: invalid names, unknown or ambiguous jumps, table overflow, and hierarchy cycles return <code>Err - ...</code> without changing the existing tree.</p> <p>Existing regions: <code>region def</code> does not clear the existing tree - if a name already exists, its parent is updated to the current cursor; otherwise a new region is created. To start from scratch, <code>region remove</code> the unwanted regions first.</p> <p>Limits: Repeater serial accepts one line up to 160 characters. For larger trees, split across multiple <code>region def</code> commands; the cursor resets to <code>*</code> between commands, so lead the next command with <code>child|ancestor</code> to reposition. Each token splits at most once on <code>|</code> - <code>region def a|b|c|d</code> is not a flat-list shorthand; see the flat-list example below.</p> <p>Example - linear chain (each token becomes a child of the previous):</p> <pre><code>region def a b c d e\nregion save\n</code></pre> <p>Example - branched tree (equivalent to <code>region put a</code>, <code>region put b a</code>, <code>region put c b</code>, <code>region put d c</code>, <code>region put e b</code>, <code>region put f e</code>):</p> <pre><code>region def a b c d|b e f\nregion save\n</code></pre> <p>Example - transactional error:</p> <pre><code>region def a b c|nope d\n</code></pre> <p>The reply is <code>Err - unknown or ambiguous jump: nope</code>. The existing tree is unchanged; re-run with a corrected jump.</p> <p>Example - flat list (each region a child of <code>*</code>). Use <code>|*</code> after each token to pop the cursor back to the root before the next token:</p> <pre><code>region def a|* b|* c|* d|* e|* f\nregion save\n</code></pre>"},{"location":"cli_commands/#remove-a-region","title":"Remove a region","text":"<p>Usage:  - <code>region remove &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Region name</p> <p>Note: Must remove all child regions before the region can be removed </p>"},{"location":"cli_commands/#view-all-regions","title":"View all regions","text":"<p>Usage:  - <code>region list &lt;filter&gt;</code></p> <p>Serial Only: Yes</p> <p>Parameters: - <code>filter</code>: <code>allowed</code>|<code>denied</code></p> <p>Note: Requires firmware 1.12+</p>"},{"location":"cli_commands/#dump-all-defined-regions-and-flood-permissions","title":"Dump all defined regions and flood permissions","text":"<p>Usage:  - <code>region</code></p> <p>Serial Only: For firmware older than 1.12.0</p>"},{"location":"cli_commands/#region-examples","title":"Region Examples","text":"<p>Example 1: Using F Flag with Named Public Region</p> <pre><code>region load\n#Europe F\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates a region named <code>#Europe</code> with flooding enabled - Packets from this region will be flooded to other nodes</p> <p>Example 2: Using Wildcard with F Flag</p> <pre><code>region load \n* F\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates a wildcard region <code>*</code> with flooding enabled - Enables flooding for all regions automatically - Applies only to packets without transport codes</p> <p>Example 3: Using Wildcard Without F Flag</p> <pre><code>region load \n*\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates a wildcard region <code>*</code> without flooding - This region exists but doesn't affect packet distribution - Used as a default/empty region</p> <p>Example 4: Nested Public Region with F Flag</p> <pre><code>region load \n#Europe F\n  #UK\n    #London\n    #Manchester\n  #France\n    #Paris\n    #Lyon\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates <code>#Europe</code> region with flooding enabled - Adds nested child regions (<code>#UK</code>, <code>#France</code>) - All nested regions inherit the flooding flag from parent</p> <p>Example 5: Wildcard with Nested Public Regions</p> <pre><code>region load \n* F\n  #NorthAmerica\n    #USA\n      #NewYork\n      #California\n    #Canada\n      #Ontario\n      #Quebec\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates wildcard region <code>*</code> with flooding enabled - Adds nested <code>#NorthAmerica</code> hierarchy - Enables flooding for all child regions automatically - Useful for global networks with specific regional rules</p>"},{"location":"cli_commands/#direct-retry","title":"Direct Retry","text":"<p>Direct retry resends direct-routed packets when the downstream echo is not heard. It applies to direct messages, ACK packets, multipart packets carrying ACK payloads, and TRACE packets.</p> <p>The shared state, count, base, and step controls work on repeater, room-server, and sensor firmware. Recent-repeater/SNR controls are repeater-only because the other roles do not keep the repeater reachability table they require.</p>"},{"location":"cli_commands/#view-or-change-direct-retry-state","title":"View or change direct retry state","text":"<p>Search terms: enable tx retries, disable tx retries, stop direct retries, turn off retransmissions.</p> <p>Usage: - <code>get direct.retry</code> - <code>set direct.retry &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>on</code></p> <p>Notes: - New installs and older preference files without direct retry settings default to <code>on</code> with the <code>rooftop</code> preset.</p> <p>Examples:</p> <pre><code>get direct.retry\nset direct.retry on\nset direct.retry off\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-heard-table-gate","title":"View or change direct retry heard-table gate","text":"<p>Usage: - <code>get direct.retry.heard</code> - <code>set direct.retry.heard &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>on</code></p> <p>Note: This command is repeater-only. When enabled, the recent repeater table is the direct retry eligibility gate. Prefixes missing from the table are assumed reachable; prefixes in the table below the active SNR gate are blocked.</p> <p>Examples:</p> <pre><code>get direct.retry.heard\nset direct.retry.heard on\nset direct.retry.heard off\n</code></pre>"},{"location":"cli_commands/#view-or-apply-a-retry-preset","title":"View or apply a retry preset","text":"<p>Search terms: retry profile, retry defaults, rooftop retries, mobile retries, infrastructure retries.</p> <p>Usage: - <code>get retry.preset</code> - <code>set retry.preset &lt;preset&gt;</code></p> <p>Parameters: - <code>preset</code>: <code>infra</code>|<code>rooftop</code>|<code>mobile</code></p> <p>Notes: - Applies shared direct retry and flood retry defaults. - <code>infra</code>: fewer, slower retries for stable fixed infrastructure. - <code>rooftop</code>: default long retry window for weak rooftop links. - <code>mobile</code>: long retry count with shorter spacing for moving or changing links; flood retry count is <code>15</code>. - Changing <code>direct.retry.count</code>, <code>direct.retry.base</code>, <code>direct.retry.step</code>, <code>direct.retry.margin</code>, <code>flood.retry.count</code>, <code>flood.retry.path</code>, or <code>flood.retry.group.path</code> makes the preset report as <code>custom</code>.</p> <p>Examples:</p> <pre><code>get retry.preset\nset retry.preset infra\nset retry.preset rooftop\nset retry.preset mobile\n</code></pre>"},{"location":"cli_commands/#flood-retry","title":"Flood Retry","text":"<p>Flood retry resends flood-routed packets when the same packet is not heard from another qualifying repeater.</p> <p>The count, path, group-data path, and advert controls work on repeater, room-server, and sensor firmware. Flood forwarding must also be enabled for retries to run. Prefix, ignore, bridge, and bucket controls are repeater-only.</p>"},{"location":"cli_commands/#hop-zero-flood-retry-coding-rate","title":"Hop-zero flood retry coding rate","text":"<p>Flood packets with no path hops recorded yet use the same CR escalation ladder as direct retries. The starting point is the active radio CR, since a flood has no single next-hop repeater whose SNR can select a starting CR. Each retry uses its attempt number and the active radio setting; it does not restart the ladder from the previous retry's override. Forwarded packets with one or more recorded hops use the active radio CR on every retry, including bridge retries whose effective path length discounts ignored hops.</p> <p>The initial transmission uses the active radio CR. This table lists retries after that initial transmission; any later retries remain at CR8:</p> Starting CR Retry 1 Retry 2 Retry 3 Retry 4 Retry 5+ CR4 CR4 CR5 CR7 CR7 CR8 CR5 CR5 CR7 CR7 CR8 CR8 CR6 CR6 CR7 CR7 CR8 CR8 CR7 CR7 CR7 CR8 CR8 CR8 CR8 CR8 CR8 CR8 CR8 CR8 <p>The ladder is shared across presets. Presets change the retry budget, not the CR steps. At CR5, the maximum hop-zero schedules are:</p> Preset Configured flood count Hop-zero retries CR schedule after the initial send <code>infra</code> 1 2 CR5, CR7 <code>rooftop</code> 3 6 CR5, CR7, CR7, CR8, CR8, CR8 <code>mobile</code> 15 15 CR5, CR7, CR7, then CR8 for retries 4-15 <p>These budgets apply to group text and the origin login/message family (<code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, <code>PATH</code>). Existing payload caps, echo cancellation, and retry eligibility still apply: <code>REQ</code> and OTA do not use generic flood retries; other payloads allow at most one retry. An eligible advert at CR5 therefore gets only its first CR5 retry.</p> <p><code>set flood.retry.count 0</code> continues to disable all automatic flood retries, including hop zero. It leaves the initial transmission and all direct-retry settings and CR schedules unchanged. Direct retry's <code>direct.retry.cr</code> switch and SNR thresholds continue to control direct retries only. Per-packet CR overrides are restored after transmission and do not change the saved radio setting or physical preamble.</p>"},{"location":"cli_commands/#view-or-change-flood-retry-count","title":"View or change flood retry count","text":"<p>Search terms: flood tx retries, flood retry attempts, flood retransmissions, broadcast retries.</p> <p>Usage: - <code>get flood.retry.count</code> - <code>set flood.retry.count &lt;count&gt;</code></p> <p>Parameters: - <code>count</code>: Base retry attempts after the original send, from <code>0</code> to <code>15</code>. <code>0</code> disables flood retry.</p> <p>Note: The role first calculates its retry count: path count 0 uses <code>count * 2</code>, path count 1 uses <code>count * 1.5</code> rounded up, and path count 2 and higher uses the configured base count, with a hard cap of <code>15</code>. A shared payload policy then applies to every build: <code>REQ</code> never retries; <code>GRP_TXT</code> keeps the role-calculated count; remote-login-critical <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code> packets keep up to <code>15</code> at the originating node (path count 0) and cap at <code>2</code> after entering the path; all other flood payload types cap at <code>1</code>. These caps never raise a lower role-calculated count. Setting <code>count</code> to <code>0</code> immediately removes queued and future flood retries; a packet already transmitting is allowed to finish.</p> <p>Forwarded neighbor adverts have an additional loop guard independent of the advert retry setting. After this node completes an advert transmission and hears a downstream copy with a longer path, it does not forward that same advert again while the advert's signed timestamp is less than six hours old. Self-originated adverts, adverts without a heard echo, and adverts six hours old or older are unaffected.</p> <p>An enabled self-originated advert retry waits at least one additional minute beyond the normal airtime-aware retry delay. Once a newer self advert has successfully entered the outbound queue, its retry sequence replaces queued or future retries for older self adverts; an older advert already transmitting is allowed to finish. Companion firmware permits this single slow retry for its own adverts while continuing to block retry attempts for neighbor adverts it forwards.</p> <p>Defaults: - <code>infra</code>: <code>1</code> - <code>rooftop</code>: <code>3</code> - <code>mobile</code>: <code>15</code></p> <p>Examples:</p> <pre><code>get flood.retry.count\nset flood.retry.count 0\nset flood.retry.count 15\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-path-gate","title":"View or change flood retry path gate","text":"<p>Usage: - <code>get flood.retry.path</code> - <code>set flood.retry.path &lt;count|off&gt;</code></p> <p>Parameters: - <code>count</code>: Maximum flood path hash count eligible for retry, from <code>0</code> to <code>63</code>. - <code>off</code>: Disable the path-length gate.</p> <p>Defaults: - <code>infra</code>: <code>1</code> - <code>rooftop</code>: <code>2</code> - <code>mobile</code>: <code>1</code></p> <p>Examples:</p> <pre><code>get flood.retry.path\nset flood.retry.path 1\nset flood.retry.path off\n</code></pre>"},{"location":"cli_commands/#view-or-change-the-group-data-flood-retry-path-gate","title":"View or change the group-data flood retry path gate","text":"<p>Usage: - <code>get flood.retry.group.path</code> - <code>set flood.retry.group.path &lt;count|off&gt;</code></p> <p>Parameters: - <code>count</code>: Maximum flood path hash count eligible for retry for group data packets (<code>PAYLOAD_TYPE_GRP_DATA</code>/type 6), from <code>0</code> to <code>63</code>. - <code>off</code>: Disable only the group-data-specific gate. The general <code>flood.retry.path</code> gate still applies.</p> <p>Default: <code>1</code> for <code>infra</code>, <code>rooftop</code>, and <code>mobile</code> presets.</p> <p>Note: The stricter of <code>flood.retry.path</code> and <code>flood.retry.group.path</code> is used. A value of <code>1</code> allows retry sequences at path counts <code>0</code> and <code>1</code>; group data at path count <code>2</code> or higher is still forwarded normally but does not start a flood retry sequence. A value of <code>0</code> allows retries only at the originating sender.</p> <p>Setting <code>flood.retry.path</code> to <code>0</code> also sets <code>flood.retry.group.path</code> to <code>off</code> because the general zero-hop gate is already stricter. While the general gate remains <code>0</code>, attempts to set the group-data gate keep it <code>off</code>. Applying a named retry preset restores the group-data default of <code>1</code>.</p> <p>Examples:</p> <pre><code>get flood.retry.group.path\nset flood.retry.group.path 1\nset flood.retry.group.path off\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-advert-handling","title":"View or change flood retry advert handling","text":"<p>Usage: - <code>get flood.retry.advert</code> - <code>set flood.retry.advert &lt;on|off&gt;</code></p> <p>Parameters: - <code>on</code>: Retry node advert floods. - <code>off</code>: Do not retry node advert floods.</p> <p>Default: <code>off</code></p> <p>Examples:</p> <pre><code>get flood.retry.advert\nset flood.retry.advert off\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-target-prefixes","title":"View or change flood retry target prefixes","text":"<p>Usage: - <code>get flood.retry.prefixes</code> - <code>set flood.retry.prefixes &lt;prefixes|none|off&gt;</code></p> <p>Parameters: - <code>prefixes</code>: Comma-separated 3-byte path hash prefixes, up to 8 entries. - <code>none</code> or <code>off</code>: Clear the list.</p> <p>Note: When set, non-bridge flood retry only accepts same-packet echoes whose last hop matches one of these prefixes. When unset, any non-ignored last hop can cancel the retry.</p> <p>Examples:</p> <pre><code>get flood.retry.prefixes\nset flood.retry.prefixes A58296,860CCA,425E5C\nset flood.retry.prefixes none\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-ignored-prefixes","title":"View or change flood retry ignored prefixes","text":"<p>Usage: - <code>get flood.retry.ignore</code> - <code>set flood.retry.ignore &lt;prefixes|none|off&gt;</code></p> <p>Parameters: - <code>prefixes</code>: Comma-separated 3-byte path hash prefixes, up to 8 entries. - <code>none</code> or <code>off</code>: Clear the list.</p> <p>Note: Non-bridge flood retry does not cancel on same-packet echoes whose last hop matches this list. Bridge mode also excludes these prefixes from bucket and <code>other</code> hits.</p> <p>Examples:</p> <pre><code>get flood.retry.ignore\nset flood.retry.ignore 71CE82,C7618C\nset flood.retry.ignore none\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-bridge-mode","title":"View or change flood retry bridge mode","text":"<p>Usage: - <code>get flood.retry.bridge</code> - <code>set flood.retry.bridge &lt;on|off&gt;</code></p> <p>Note: Bridge mode retries until each configured fresh bucket, plus the non-source <code>other</code> bucket, has been heard or the retry count is exhausted. If prefixes in different buckets share their first byte, configuration commands return a warning because a 1-byte path cannot distinguish those buckets. The configuration remains valid: an ambiguous source is treated as belonging to every matching source bucket, and an ambiguous echo credits every matching target bucket so it cannot force retry exhaustion.</p> <p>Flood retry timing retains its fixed maximum-frame plus 20 packet-airtime wait, then adds a random <code>0-200%</code> of one additional packet airtime on every attempt. This de-synchronizes repeaters that may have missed the same echo while capping the added wait at two frames.</p> <p>Only one active retry sequence is kept for a given logical flood packet. An identical flood can still transmit normally, but it does not create a second sequence of extra attempts. Retry state is released if a queued packet is evicted, and the final echo window retains metadata without reserving a packet-pool entry.</p> <p>Bridge reachability learned from earlier hops in a successful echo is cached separately from <code>recent.repeater</code>. Only the final RF hop updates <code>recent.repeater</code> and its SNR, so indirect path entries cannot affect direct-retry SNR gating or coding-rate selection.</p> <p>Examples:</p> <pre><code>get flood.retry.bridge\nset flood.retry.bridge on\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-bridge-buckets","title":"View or change flood retry bridge buckets","text":"<p>Usage: - <code>get flood.retry.bucket.&lt;n&gt;</code> - <code>set flood.retry.bucket &lt;n&gt; &lt;prefixes|none|off&gt;</code></p> <p>Parameters: - <code>n</code>: Bucket number from <code>1</code> to <code>6</code>. - <code>prefixes</code>: Comma-separated 3-byte path hash prefixes, up to 17 entries per bucket. - <code>none</code> or <code>off</code>: Clear the bucket.</p> <p>Examples:</p> <pre><code>get flood.retry.bucket.1\nset flood.retry.bucket 1 71CE82,C7618C\nset flood.retry.bucket 2 none\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-count","title":"View or change direct retry count","text":"<p>Search terms: tx retries, transmit retries, direct retries, retry count, retry attempts, retransmission count, message retries, DM retries.</p> <p>Usage: - <code>get direct.retry.count</code> - <code>set direct.retry.count &lt;count&gt;</code></p> <p>Parameters: - <code>count</code>: Maximum retry attempts after the original send, from <code>1</code> to <code>15</code>.</p> <p>Default: <code>15</code> with the <code>rooftop</code> preset</p> <p>Note: This setting limits retries for eligible direct-routed packets such as traces, requests, responses, and ACKs. Direct-routed text messages (type 2) are an exception: they allow up to 21 retries after the original send, regardless of <code>direct.retry.count</code> or the repeater short-path cap. For example, <code>set direct.retry.count 1</code> limits eligible non-text packets to one retry, but does not reduce the text-message limit.</p> <p>These are maximums, not a fixed number of transmissions. Retries stop early when the node hears the next hop forward the packet. The special final-hop retry sends only one duplicate because the destination does not forward the packet. Repeater non-text retries are also capped at 8 for a retry path of up to 3 hops, 12 for 4 hops, and 15 for longer paths; these caps never increase a lower configured count.</p> <p>Use <code>set direct.retry off</code> to disable this node's direct retries, including text-message retries, and <code>set direct.retry on</code> to enable them again. A count of <code>0</code> is not supported. Sending apps and other nodes may have their own retry behavior; this setting does not change it.</p> <p>Examples:</p> <pre><code>get direct.retry.count\nset direct.retry.count 1\nset direct.retry.count 4\nset direct.retry.count 15\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-base-delay","title":"View or change direct retry base delay","text":"<p>Search terms: retry delay, retry timeout, retransmission timeout, wait between retries.</p> <p>Usage: - <code>get direct.retry.base</code> - <code>set direct.retry.base &lt;ms&gt;</code></p> <p>Parameters: - <code>ms</code>: First retry wait in milliseconds, from <code>10</code> to <code>5000</code>.</p> <p>Default: <code>175</code> with the <code>rooftop</code> preset</p> <p>Explanation: - The first retry waits for <code>base + packet-length add-on + random forwarding jitter</code>   after the preceding transmission completes. - TRACE and   ANON_REQ/type 7 packets use a 3x line-time add-on. TXT_MSG/type 2   packets use 7x. Other direct retry packets use 6x. - Room-server and sensor firmware use this configured base with the same   packet-type add-ons. - Larger values reduce channel pressure and give slow repeaters more time. - Smaller values recover faster but create tighter retry bursts.</p> <p>Examples:</p> <pre><code>get direct.retry.base\nset direct.retry.base 175\nset direct.retry.base 275\nset direct.retry.base 500\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-step-delay","title":"View or change direct retry step delay","text":"<p>Search terms: retry backoff, increasing retry delay, retry interval step.</p> <p>Usage: - <code>get direct.retry.step</code> - <code>set direct.retry.step &lt;ms&gt;</code></p> <p>Parameters: - <code>ms</code>: Extra milliseconds added for each subsequent retry, from <code>0</code> to <code>5000</code>.</p> <p>Default: <code>100</code> with the <code>rooftop</code> preset</p> <p>Explanation: - Retry delay is <code>base + packet-length add-on + random forwarding jitter + attempt_index * step</code>. - TRACE and ANON_REQ/type 7 packets   use a 3x packet-length add-on. TXT_MSG/type 2 packets use 7x.   Other direct retry packets use 6x. - Room-server and sensor firmware use this configured step with the same   packet-type add-ons. - With <code>base=175</code> and <code>step=100</code>, the fixed portion is <code>175</code>, <code>275</code>, <code>375</code>,   <code>475</code> ms, and so on, before the packet-length add-on and random jitter. - <code>step=0</code> keeps every retry at the same delay. - Larger steps spread retries over time and are safer on busy channels.</p> <p>Examples:</p> <pre><code>get direct.retry.step\nset direct.retry.step 0\nset direct.retry.step 50\nset direct.retry.step 100\nset direct.retry.step 250\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-snr-margin","title":"View or change direct retry SNR margin","text":"<p>Search terms: retry signal threshold, retry SNR threshold, retry signal margin.</p> <p>Usage: - <code>get direct.retry.margin</code> - <code>set direct.retry.margin &lt;snr_db&gt;</code></p> <p>Parameters: - <code>snr_db</code>: Extra SNR margin above the SF receive floor, from <code>0</code> to <code>40</code>.</p> <p>Default: <code>5.00</code> with the <code>rooftop</code> preset</p> <p>Notes: - This command is repeater-only. - Unknown repeaters are still retried. - Known repeaters below the receive floor plus this margin are skipped. - Failed attempts lower the recent repeater SNR estimate by <code>0.25 dB</code>.</p> <p>Examples:</p> <pre><code>get direct.retry.margin\nset direct.retry.margin 0\nset direct.retry.margin 2.5\nset direct.retry.margin 5\nset direct.retry.margin 10\n</code></pre>"},{"location":"cli_commands/#view-or-change-adaptive-direct-retry-coding-rate","title":"View or change adaptive direct retry coding rate","text":"<p>Usage: - <code>get direct.retry.cr</code> - <code>set direct.retry.cr off</code> - <code>set direct.retry.cr on</code> (room-server and sensor) - <code>set direct.retry.cr &lt;cr4_min&gt;,&lt;cr5_min&gt;,&lt;cr7_min&gt;,&lt;cr8_max&gt;</code></p> <p>Parameters: - <code>cr4_min</code>: Minimum SNR in dB to retry at CR4. - <code>cr5_min</code>: Minimum SNR in dB to retry at CR5. - <code>cr7_min</code>: Minimum SNR in dB to retry at CR7. - <code>cr8_max</code>: Maximum SNR in dB that forces CR8.</p> <p>Default: <code>10.00,7.50,2.50,2.50</code></p> <p>Explanation: - Higher SNR uses faster coding rates. - Lower SNR uses more robust coding rates. - Repeater retry attempts escalate from the adaptive starting CR. CR4 starts as CR4, CR5, CR7, CR7, then CR8. CR5 starts as CR5, CR7, CR7, then CR8. CR7 gets two attempts, then CR8. - Repeater adaptive CR selection intentionally skips CR6. - Non-repeater retry packets start at the current radio CR and follow the same escalation pattern, clamped at CR8. With the normal CR5 radio setting this is CR5, CR7, CR7, then CR8. - Room-server and sensor firmware accept <code>on</code> or <code>off</code>; numeric SNR thresholds   are repeater-only because those roles do not keep recent-repeater SNR data. - <code>off</code> disables per-packet direct-retry CR overrides and uses the current radio CR. - Retry packets may use a different coding rate, but they keep the radio's normal physical preamble. - Unknown repeaters start at <code>+3.00 dB</code> for adaptive CR selection. - A failed unknown repeater is seeded at <code>+2.75 dB</code>. - Each later failure lowers the SNR estimate by <code>0.25 dB</code>.</p> <p>Examples:</p> <pre><code>get direct.retry.cr\nset direct.retry.cr off\nset direct.retry.cr on\nset direct.retry.cr 10.0,7.5,2.5,2.5\nset direct.retry.cr 12.0,8.0,4.0,1.0\nset direct.retry.cr 8.0,5.0,1.5,0\nset direct.retry.cr 6.0,3.0,0,-2.0\nset direct.retry.cr 20.0,12.0,6.0,2.0\nset direct.retry.cr 4.0,2.0,0,-4.0\n</code></pre> <p>Example profiles: - Conservative weak-link profile:</p> <pre><code>set direct.retry.cr 12.0,8.0,4.0,1.0\n</code></pre> <ul> <li>Balanced rooftop profile:</li> </ul> <pre><code>set direct.retry.cr 10.0,7.5,2.5,2.5\n</code></pre> <ul> <li>Faster strong-link profile:</li> </ul> <pre><code>set direct.retry.cr 6.0,3.0,0,-2.0\n</code></pre> <ul> <li>Very cautious noisy-link profile:</li> </ul> <pre><code>set direct.retry.cr 20.0,12.0,6.0,2.0\n</code></pre>"},{"location":"cli_commands/#view-seed-or-clear-the-recent-repeater-table","title":"View, seed, or clear the recent repeater table","text":"<p>Usage: - <code>get recent.repeater</code> - <code>get recent.repeater &lt;page&gt;</code> - <code>get recent.repeaters &lt;page&gt;</code> - <code>get recent.repeaters search &lt;prefix&gt; [page]</code> - <code>set recent.repeater &lt;prefix&gt; [snr_db]</code> - <code>clear recent.repeater</code></p> <p>Parameters: - <code>prefix</code>: Repeater path-hash prefix as 2, 4, or 6 hex characters. - <code>snr_db</code>: Optional SNR in dB. If omitted or invalid, defaults to <code>3.0</code>. - <code>page</code>: 1-based result page.</p> <p>Note: These commands are repeater-only.</p> <p>The default capacity is 256 entries on classic ESP32, 2,048 on other ESP32 chips, 512 on nRF52, and 64 on other platforms. Builds can override it with <code>MAX_RECENT_REPEATERS</code>. Classic ESP32's history uses 3,072 bytes of startup heap instead of 24,576 bytes, leaving more memory for the packet pool and Wi-Fi.</p> <p>Output order: - <code>get recent.repeater</code> lists 3-byte prefixes first, then 2-byte prefixes, then 1-byte prefixes. - Within each prefix length, entries are sorted from highest SNR to lowest SNR. - <code>search</code> returns every overlapping path-hash entry. For example, searching   <code>860C</code> can return <code>86</code>, <code>860C</code>, and <code>860CCA</code>; it does not return a different   branch such as <code>86D0</code>. - Search rows include the monotonic age of the entry's most recent recording,   compacted to a whole <code>s</code>, <code>m</code>, or <code>h</code> field. Search pages contain up to six   rows so the result remains within the remote CLI reply limit.</p> <p>SNR details: - Recent repeater SNR is stored internally in quarter-dB units. - Heard repeater samples update an existing table entry with a weighted blend: <code>75%</code> existing SNR and <code>25%</code> new heard SNR, rounded up. - Direct retry success also feeds the heard echo SNR back into the same weighted table. - Direct retry failure is not weighted: each final echo-timeout failure lowers that repeater's SNR by <code>0.25 dB</code>. - Unknown repeaters start at <code>+3.00 dB</code> for adaptive CR selection. - If an unknown repeater fails, it is seeded into the table at <code>+2.75 dB</code>. - <code>set recent.repeater &lt;prefix&gt; [snr_db]</code> seeds a missing prefix or adds another weighted sample for an existing prefix. - Successful <code>set recent.repeater</code> replies include the stored prefix and SNR, for example <code>OK - set A1B2C3 at 3.0 SNR</code>. - Entries strictly older than 24 hours are removed during a sweep every three hours, so an entry can remain for at most approximately 27 hours.</p> <p>Examples:</p> <pre><code>get recent.repeater\nget recent.repeater 2\nget recent.repeaters search 86\nget recent.repeaters search 860C page 2\nset recent.repeater A1B2C3 8.5\nset recent.repeater 71CE82 -3.25\nset recent.repeater A1B2C3\nclear recent.repeater\n</code></pre>"},{"location":"cli_commands/#gps-when-gps-support-is-compiled-in","title":"GPS (When GPS support is compiled in)","text":""},{"location":"cli_commands/#view-or-change-gps-state","title":"View or change GPS state","text":"<p>Search terms: enable GPS, disable GPS, turn GPS on, turn GPS off.</p> <p>Usage: - <code>get gps</code> - <code>set gps &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>off</code></p> <p>Note: These command names are shared with GPS-capable Companion builds. Companion reports <code>on</code> or <code>off</code>; infrastructure includes receiver details: - <code>off</code> when the GPS hardware is disabled - <code>on, {active|deactivated}, {fix|no fix}, {sat count} sats</code> when the GPS hardware is enabled</p> <p>On repeaters, <code>gps off</code> cancels any acquisition already in progress. A later authorized location-telemetry request may wake the receiver, but only until its first valid fix is cached; the receiver then powers down again.</p>"},{"location":"cli_commands/#sync-this-nodes-clock-with-gps-time","title":"Sync this node's clock with GPS time","text":"<p>Usage:  - <code>gps sync</code></p> <p>The GPS must be enabled. When GPS power saving has put an enabled receiver to sleep, this command schedules a sync and wakes it; after <code>set gps off</code>, it reports <code>gps is off</code> without scheduling work.</p> <p>On repeaters with device power saving enabled, the automatic GPS cycle wakes for up to 10 minutes and repeats seven days after GPS sleeps. A valid GPS time can correct the RTC either forward or backward. With device power saving off, an enabled GPS refreshes the RTC every 30 minutes.</p>"},{"location":"cli_commands/#set-this-nodes-location-based-on-the-gps-coordinates","title":"Set this node's location based on the GPS coordinates","text":"<p>Usage:  - <code>gps setloc</code></p>"},{"location":"cli_commands/#view-or-change-the-gps-advert-policy","title":"View or change the GPS advert policy","text":"<p>Usage: - <code>gps advert</code> - <code>gps advert &lt;policy&gt;</code></p> <p>Parameters:  - <code>policy</code>: <code>none</code>|<code>share</code>|<code>prefs</code>    - <code>none</code>: don't include location in adverts   - <code>share</code>: share gps location (from SensorManager)   - <code>prefs</code>: location stored in node's lat and lon settings</p> <p>Default: <code>prefs</code> on every repeater, room-server, and sensor build that uses the common advert policy. A previously saved <code>none</code>, <code>share</code>, or <code>prefs</code> choice still overrides the first-boot default after an update.</p>"},{"location":"cli_commands/#sensors-when-sensor-support-is-compiled-in","title":"Sensors (When sensor support is compiled in)","text":""},{"location":"cli_commands/#view-or-change-telemetry-access-mode","title":"View or change telemetry access mode","text":"<p>Usage: - <code>get telemetry.access</code> - <code>set telemetry.access &lt;mode&gt;</code></p> <p>Parameters: - <code>mode</code>: <code>all</code>|<code>acl</code>   - <code>all</code>: allow telemetry requests using the requester-provided telemetry mask   - <code>acl</code>: require ACL read-only or higher for telemetry, including GPS</p> <p>Default: <code>all</code></p> <p>Note: <code>all</code> matches the previous sensor telemetry behavior.</p>"},{"location":"cli_commands/#view-the-list-of-sensors-on-this-node","title":"View the list of sensors on this node","text":"<p>Usage: <code>sensor list [start]</code></p> <p>Parameters: - <code>start</code>: Optional starting index (defaults to 0)</p> <p>Note: Output format: <code>&lt;var_name&gt;=&lt;value&gt;\\n</code></p>"},{"location":"cli_commands/#view-or-change-the-value-of-a-sensor","title":"View or change the value of a sensor","text":"<p>Usage:  - <code>sensor get &lt;key&gt;</code> - <code>sensor set &lt;key&gt; &lt;value&gt;</code></p> <p>Parameters: - <code>key</code>: Sensor setting name - <code>value</code>: The value to set the sensor to</p>"},{"location":"cli_commands/#bridge-when-bridge-support-is-compiled-in","title":"Bridge (When bridge support is compiled in)","text":"<p>For a complete two-repeater setup with each option explained, see the ESP-NOW bridge setup guide.</p>"},{"location":"cli_commands/#view-the-compiled-bridge-type","title":"View the compiled bridge type","text":"<p>Usage: <code>get bridge.type</code></p>"},{"location":"cli_commands/#view-or-change-the-bridge-enabled-flag","title":"View or change the bridge enabled flag","text":"<p>Search terms: enable bridge, disable bridge, serial bridge, RS232 bridge.</p> <p>Usage: - <code>get bridge.enabled</code> - <code>get bridge.running</code> - <code>set bridge.enabled &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p><code>bridge.enabled</code> is the saved intent. <code>bridge.running</code> reports whether the bridge actually started in this boot; they can differ after a hardware conflict, missing credentials, or a transient initialization failure. Normal merged repeater images default to <code>off</code>; dedicated bridge images may default to <code>on</code>.</p>"},{"location":"cli_commands/#add-a-delay-to-packets-routed-through-this-bridge","title":"Add a delay to packets routed through this bridge","text":"<p>Usage: - <code>get bridge.delay</code> - <code>set bridge.delay &lt;ms&gt;</code></p> <p>Parameters: - <code>ms</code>: Delay in milliseconds (0-10000)</p> <p>Default: <code>500</code></p>"},{"location":"cli_commands/#view-or-change-the-source-of-packets-bridged-to-the-external-interface","title":"View or change the source of packets bridged to the external interface","text":"<p>Usage: - <code>get bridge.source</code> - <code>set bridge.source &lt;source&gt;</code></p> <p>Parameters: - <code>source</code>:   - <code>rx</code>: bridges received packets   - <code>tx</code>: bridges transmitted packets</p> <p>Default: <code>tx</code></p> <p>Note: For MQTT, use <code>mqtt.rx</code> and <code>mqtt.tx</code> to control each direction independently. Both can be enabled together. Use <code>mqtt.enabled</code> as the MQTT master switch; <code>bridge.*</code> configures RS232 and ESP-NOW bridges.</p>"},{"location":"cli_commands/#view-or-change-the-mqtt-master-switch","title":"View or change the MQTT master switch","text":"<p>Search terms: enable MQTT, disable MQTT, MQTT on, MQTT off, WiFi logging.</p> <p>Usage:</p> <ul> <li><code>get mqtt.enabled</code></li> <li><code>set mqtt.enabled on</code></li> <li><code>set mqtt.enabled off</code></li> <li><code>get mqtt.running</code></li> <li><code>get mqtt.status</code></li> </ul> <p>These commands are the same on MQTT-capable Companion, Repeater, Room Server, and Sensor builds. The master switch is saved; turning it off disconnects MQTT while keeping broker presets and credentials. Turning it on allows those brokers to reconnect. <code>get mqtt.running</code> checks the service's runtime state; <code>get mqtt.status</code> reports individual broker connections. Enabling MQTT does not imply that a broker is connected.</p> <p>USB logging remains independent. On images with both outputs, <code>set logging.output off|usb|wifi|both</code> selects USB and MQTT together.</p>"},{"location":"cli_commands/#view-or-change-mqtt-rx-packet-uplinking","title":"View or change MQTT RX packet uplinking","text":"<p>Search terms: MQTT receive logging, MQTT RX capture, publish received packets.</p> <p>Usage: - <code>get mqtt.rx</code> - <code>set mqtt.rx &lt;on|off&gt;</code></p> <p>Parameters: - <code>on</code>: uplink received (RX) packets to MQTT brokers - <code>off</code>: disable RX packet uplinking</p> <p>Default: <code>on</code></p>"},{"location":"cli_commands/#view-or-change-mqtt-tx-packet-uplinking","title":"View or change MQTT TX packet uplinking","text":"<p>Search terms: MQTT transmit logging, MQTT TX capture, publish sent packets.</p> <p>Usage: - <code>get mqtt.tx</code> - <code>set mqtt.tx &lt;on|off|advert&gt;</code></p> <p>Parameters: - <code>on</code>: uplink all transmitted (TX) packets to MQTT brokers - <code>advert</code>: uplink only this node's own advert packets (self-originated advertisements only - forwarded adverts from other nodes are filtered out) - <code>off</code>: disable TX packet uplinking</p> <p>Default: <code>advert</code></p> <p>Note: <code>mqtt.rx</code> and <code>mqtt.tx</code> take effect immediately - no restart required. Both can be enabled simultaneously.</p>"},{"location":"cli_commands/#view-or-change-periodic-neighbors-publishing-mqtt-observer-neighbors-feature","title":"View or change periodic neighbors publishing (MQTT observer, neighbors feature)","text":"<p>Usage: - <code>get mqtt.neighbors</code> - <code>set mqtt.neighbors &lt;on|off&gt;</code></p> <p>Parameters: - <code>on</code>: periodically discover neighbor scopes and publish the neighbor table to the <code>neighbors</code> topic - <code>off</code>: disable periodic neighbors publishing</p> <p>Default: <code>off</code></p> <p>Note: Requires a build with the neighbors feature compiled in (all PSRAM boards, plus non-PSRAM boards built with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>); elsewhere this replies <code>Err - neighbors not enabled in this build</code>. Non-PSRAM builds publish at most 20 neighbours per pass to bound internal-DRAM use, and set <code>truncated</code> with the true <code>total_neighbors</code> when the table is larger. The setting is read live by the mesh loop - no restart required; enabling it triggers a discovery on the next pass. While enabled, <code>get mqtt.status</code> gains a trailing <code>nbr: &lt;next&gt;/&lt;last&gt;</code> field (time to next publish, and how the last publish went).</p>"},{"location":"cli_commands/#view-or-change-the-neighbors-publish-interval-mqtt-observer-neighbors-feature","title":"View or change the neighbors publish interval (MQTT observer, neighbors feature)","text":"<p>Usage: - <code>get mqtt.neighbors.interval</code> - <code>set mqtt.neighbors.interval &lt;hours&gt;</code></p> <p>Parameters: - <code>hours</code>: how often to publish the neighbor table (12-336, default 24)</p> <p>Default: <code>24</code> (hours)</p> <p>Note: Out-of-range values are rejected (not clamped). Requires a build with <code>WITH_MQTT_NEIGHBORS</code>; PSRAM boards enable it automatically and selected non-PSRAM variants opt in with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>.</p>"},{"location":"cli_commands/#view-or-change-the-ntp-server-mqtt-observer-only","title":"View or change the NTP server (MQTT observer only)","text":"<p>Usage: - <code>get mqtt.ntp</code> - <code>set mqtt.ntp &lt;hostname&gt;</code> - <code>set mqtt.ntp none</code></p> <p>Description: Sets the primary NTP server used for clock sync (required for JWT MQTT auth). On <code>set</code>, the device attempts an immediate sync of the just-configured server (primary only, so a typo fails fast) when WiFi is connected and the MQTT bridge is running.</p> <p>Fallbacks: If the primary fails, the firmware tries <code>pool.ntp.org</code>, <code>time.google.com</code>, <code>time.cloudflare.com</code>, <code>time.aws.com</code>, and <code>time.nist.gov</code> in order (skipping duplicates).</p> <p>Default: <code>pool.ntp.org</code> (when unset or <code>none</code>)</p>"},{"location":"cli_commands/#diagnose-ntp-server-connectivity-mqtt-observer-only","title":"Diagnose NTP server connectivity (MQTT observer only)","text":"<p>Usage: - <code>get mqtt.ntp.diag</code></p> <p>Description: Probes every configured NTP server (the custom primary, if set, plus the built-in fallbacks) and reports whether each responds. This is a pure connectivity diagnostic - it does not change the system clock.</p> <ul> <li>Serial console: prints a detailed table with each server's reported UTC time (or <code>FAIL</code>).</li> <li>Over LoRa: returns a compact <code>&lt;server&gt; ok|fail</code> list, one per line.</li> </ul> <p>Requires WiFi connected and the MQTT bridge running.</p>"},{"location":"cli_commands/#view-or-change-the-speed-of-the-bridge-rs-232-only","title":"View or change the speed of the bridge (RS-232 only)","text":"<p>Usage: - <code>get bridge.baud</code> - <code>set bridge.baud &lt;rate&gt;</code></p> <p>Parameters: - <code>rate</code>: Integer baud rate from <code>9600</code> through the board's compiled   <code>BRIDGE_MAX_BAUD</code> (commonly <code>500000</code>); for example <code>115200</code>. Stop the bridge   with <code>set bridge.enabled off</code> before changing it, then enable it again.</p> <p>Default: <code>115200</code></p>"},{"location":"cli_commands/#view-or-change-the-uart-used-by-the-bridge-rs-232-only","title":"View or change the UART used by the bridge (RS-232 only)","text":"<p>Usage: - <code>get bridge.uart</code> - <code>set bridge.uart &lt;port&gt;</code></p> <p>Parameters: - <code>port</code>: Hardware UART number compiled for the board. Most boards expose one   fixed UART. RAK4631 accepts <code>1</code> or <code>2</code>; UART 2 is the default so UART 1 can   remain available to the RAK12501/L76K GPS. RAK12500 GPS uses I2C rather than   this UART, but the explicit legacy Serial1 bridge omits the combined GPS   provider and therefore does not expose either GPS path.</p> <p>The setting is persistent and restarts an enabled bridge immediately. Normal repeater artifacts start with <code>bridge.enabled off</code>; configure the UART and baud rate before running <code>set bridge.enabled on</code>. On the canonical RAK4631 runtime image, UART 1 is reserved even if the bounded boot probe hears no RAK12501. Silence cannot prove that a cold L76K is physically absent, and that module remains powered by the shared WB_IO2/3V3_S rail. Use UART 2. UART 1 requires an explicit no-GPS/dedicated Serial1 bridge image. This fail-closed reservation also applies when the detected GPS is an I2C RAK12500; that receiver does not electrically use UART 1, but its presence cannot rule out another silent UART module.</p>"},{"location":"cli_commands/#view-or-change-the-channel-used-for-bridging-espnow-only","title":"View or change the channel used for bridging (ESPNow only)","text":"<p>Usage: - <code>get bridge.channel</code> - <code>set bridge.channel &lt;channel&gt;</code></p> <p>Parameters: - <code>channel</code>: Channel number from 1 through 13 in either format. This matches   the primary-ESP-NOW policy and the default regulatory range used by the   supported ESP32 targets.</p> <p>This controls the optional ESP-NOW bridge transport; it does not change a node's primary ESP-NOW mesh channel. Primary-ESP-NOW firmware uses <code>get espnow.channel</code> and <code>set espnow.channel &lt;1-13&gt;</code> instead.</p>"},{"location":"cli_commands/#view-or-change-the-esp-now-bridge-wire-format","title":"View or change the ESP-NOW bridge wire format","text":"<p>Usage: - <code>get bridge.format</code> - <code>set bridge.format &lt;format&gt;</code></p> <p>Parameters: - <code>format</code>:   - <code>wrapped</code>: the original ESP-NOW bridge framing (magic, checksum, and XOR     using <code>bridge.secret</code>)   - <code>raw</code>: the exact serialized MeshCore packet used by primary     <code>ESPNOWRadio</code> firmware</p> <p>Default: <code>wrapped</code></p> <p>The setting is persistent and restarts an enabled bridge immediately. Receive parsing is strict: <code>wrapped</code> accepts only wrapped frames and <code>raw</code> accepts only raw MeshCore frames. Coordinate the format and channel on every ESP-NOW peer; there is no automatic dual-format receive mode because it would permit ambiguous, asymmetric bridge deployments.</p> <p>Use <code>raw</code> to connect a LoRa-primary <code>*_repeater_bridge_espnow</code> node to <code>Generic_ESPNOW</code>, <code>SenseCapIndicator-ESPNow</code>, or another primary-ESP-NOW node. Raw mode enables the ESP-NOW LR PHY and sends at the same LR rate used by those targets. All nodes must use the same 1-13 channel. On a primary-ESP-NOW node, change that side with <code>set espnow.channel &lt;1-13&gt;</code> and reboot; on the bridge, use <code>set bridge.channel &lt;1-13&gt;</code>.</p> <p>Raw mode ignores <code>bridge.secret</code> and removes the bridge wrapper's lightweight network isolation. MeshCore's own packet authentication/encryption still applies where the packet type provides it, but public frames and routing metadata remain visible. The wrapped format's XOR is isolation, not strong cryptography. Bridge duplicate tracking remains active in both formats, but deploying multiple gateways between the same LoRa and ESP-NOW coverage areas can still increase duplicate traffic while their seen-packet tables converge.</p> <p>One ESP-NOW frame carries at most 250 payload bytes. In raw mode, serialized MeshCore packets up to that size remain byte-for-byte compatible with existing raw endpoints. Updated raw endpoints split 251-255-byte transport units into two versioned fragments and reassemble them by source MAC, length, and CRC; both endpoints must include this support for those sizes. Current valid MeshCore packet geometry reaches 254 bytes, while 255 is retained as transport headroom. Wrapped mode retains its legacy 246-byte maximum after the four-byte magic and checksum overhead, and drops larger packets instead of truncating them.</p>"},{"location":"cli_commands/#set-the-esp-now-secret","title":"Set the ESP-Now secret","text":"<p>Usage:  - <code>get bridge.secret</code> - <code>set bridge.secret &lt;secret&gt;</code></p> <p>Parameters: - <code>secret</code>: ESP-NOW bridge secret, 1-15 characters</p> <p>Default: Varies by board</p> <p>This setting is used only by <code>bridge.format wrapped</code>; raw mode ignores it.</p>"},{"location":"cli_commands/#view-the-bootloader-version-nrf52-only","title":"View the bootloader version (nRF52 only)","text":"<p>Usage: <code>get bootloader.ver</code></p> <p>Applies to every nRF52 board/role that exposes this getter, including Companion, repeater, and room-server firmware. It reads the installed bootloader region selected by the MBR/UICR boot address and bounded by the chip's flash geometry; it does not search application firmware or staged update files.</p> <p>The reader preserves a complete Adafruit/UF2 version string, including OTAFIX, preview, and vendor/build suffixes. If that string is absent or ambiguous, it uses the existing whole-image CRC and unique BLMF/BLM2 validation to read the embedded OTAFIX version (for example, <code>&gt; OTAFIX2.4.6</code>). Some current release images, including MeshTower V2 SD 2.4.6, omit the UF2 text entirely. As a last fallback, the Adafruit core's startup-captured version is explicitly labelled <code>(base)</code>; it cannot identify an OTAFIX/fork revision.</p> <p><code>unknown</code> remains possible for a bootloader exposing none of these version sources, invalid geometry/vectors, or unresolved ambiguity. There is no universal version field shared by every third-party bootloader. This is diagnostic only: displaying a version neither grants OTA capability nor bypasses install checks. The fix is in MeshCore application firmware; installing another bootloader alone does not update an older application's version reader.</p>"},{"location":"cli_commands/#view-power-management-support","title":"View power management support","text":"<p>Usage: <code>get pwrmgt.support</code></p>"},{"location":"cli_commands/#view-the-current-power-source","title":"View the current power source","text":"<p>Usage: <code>get pwrmgt.source</code></p> <p>Note: Returns an error on boards without power management support.</p>"},{"location":"cli_commands/#view-the-boot-reset-and-shutdown-reasons","title":"View the boot reset and shutdown reasons","text":"<p>Usage: <code>get pwrmgt.bootreason</code></p> <p>Note: Returns an error on boards without power management support.</p>"},{"location":"cli_commands/#view-the-boot-voltage","title":"View the boot voltage","text":"<p>Usage: <code>get pwrmgt.bootmv</code></p> <p>Note: Returns an error on boards without power management support.</p>"},{"location":"cli_commands/#ethernet-when-ethernet-support-is-compiled-in","title":"Ethernet (when Ethernet support is compiled in)","text":"<p>Ethernet support is available on RAK4631 boards with a RAK13800 (W5100S) Ethernet module. Use the <code>_ethernet</code> firmware variants (e.g. <code>RAK_4631_repeater_ethernet</code>) to enable this feature.</p>"},{"location":"cli_commands/#view-ethernet-connection-status","title":"View Ethernet connection status","text":"<p>Usage: - <code>eth.status</code></p> <p>Output: - <code>ETH: &lt;ip&gt;:&lt;port&gt;</code> when connected (e.g. <code>ETH: 192.168.1.50:23</code>) - <code>ETH: not connected</code> when Ethernet is not active</p> <p>Notes: - Available on repeater and room server firmware only. Companion radio ethernet firmware does not expose a CLI. - The Ethernet interface obtains an IP address via DHCP automatically on boot. - A TCP server listens on port 23 (default) for CLI connections. - Connect with any TCP client (e.g. <code>nc</code>, PuTTY) to access the same CLI available over serial.</p>"},{"location":"cli_settings_audit/","title":"CLI setting dispatch audit","text":"<p>The 1.17.1.5 source retained <code>get path.hash.mode</code> in <code>CommonCLI</code> but lost its setter when radio preferences moved into <code>CommonRadioPrefs</code>. Infrastructure roles call <code>CommonCLI</code> directly, so the shared parser's setter was unreachable. The correction restores <code>set path.hash.mode 0|1|2</code> there, validates the value, and saves accepted changes. Missing/invalid values report a value error and leave the setting unchanged.</p> <p>The other radio setters removed by the original refactor had already been restored. A feature-guarded check found a second mismatch: <code>get extra.sf</code> exposed stored data on non-LR2021 radios while its setter was compiled out. Both commands now return <code>Error: extra.sf requires an LR2021 radio</code> there. Supported LR2021 set/get behavior is preserved. These are source corrections; existing release binaries need rebuilding/updating to receive them.</p>"},{"location":"cli_settings_audit/#coverage","title":"Coverage","text":"Surface Check Common infrastructure CLI 72 literal setter keys and 84 query keys; every query has a setter or an explicitly reviewed read-only/alternate-command exception MQTT/observer CLI 33 literal setter keys and 39 query keys, including Wi-Fi, timezone, alerts, display and watchdog settings MQTT slots All nine writable slot subkeys have query/set coverage; <code>diag</code> is intentionally read-only Repeater, Room Server, Sensor Shared CLI delegation and role-specific query/set coverage Companion Shared-radio allowlist and parser agreement, persistence wiring, terminal-specific setters, and role query exceptions Radio settings moved by the refactor All 13 shared setters remain present in infrastructure dispatch Literal command comparisons Checks key lengths so a setter cannot accidentally compare its value against the key's terminating NUL Feature guards Preprocesses common and observer handlers for minimal, nRF52 GPS/SD, ESP32 WebConfig, ESP32 MQTT, RS232/GPS, ESP-NOW, and LR2021 profiles before comparing query/set coverage <p>Read-only exceptions include runtime connection status, diagnostics, firmware role, bootloader identity and reset information. Alternate-command exceptions include the password command and <code>set battery.alert on &lt;region&gt;</code>. These exceptions are explicit in the test, rather than silently allowing all missing setters. Dynamic/delegated command families and hardware-specific features continue to use their dedicated tests; the inventory is not a claim that every build has every feature enabled.</p>"},{"location":"cli_settings_audit/#executed-behavior-tests","title":"Executed behavior tests","text":"<p>The native C++ fixture compiles the production get/set dispatch branches and the real setting bodies for 14 radio-related settings: <code>radio</code>, <code>freq</code>, <code>af</code>, <code>dutycycle</code>, <code>int.thresh</code>, <code>cad</code>, <code>radio.rxgain</code>, <code>tx</code>, <code>rxdelay</code>, <code>agc.reset.interval</code>, <code>path.hash.mode</code>, <code>multi.acks</code>, <code>txdelay</code>, and <code>direct.txdelay</code>. It runs local and authenticated on-air caller timestamps, checks round-trip values and save calls, preserves AGC interval rounding, and checks that rejected hardware applies do not save or change preferences. Hardware callbacks are mocked; these are not live-radio or flash-durability tests. The fixture also runs with and without <code>USE_LR2021</code>, checking supported <code>extra.sf</code> set/query/clear behavior, invalid values, and the unsupported-radio error.</p> <p>The focused hash-mode test checks all valid modes, missing values, negative and out-of-range values, overflow, malformed numbers, whitespace, and similarly named unknown keys. Existing transport tests exercise Companion local/framed and on-air dispatch, local-only secret reads, and browser/stream routing under AddressSanitizer and UndefinedBehaviorSanitizer on Linux.</p> <p>Run the CI checks locally with a host C++ compiler (Linux is required for the existing sanitizer-enabled transport suite):</p> <pre><code>python3 -B test/test_path_hash_cli.py\npython3 -B test/test_cli_settings_contract.py\npython3 -B test/test_local_cli_access.py\n</code></pre> <p>All 14 tests passed on the Linux VM. The workflow runs these commands on future pushes and pull requests. The new inventory and native radio tests also passed with the Windows host compiler.</p> <p><code>pio run -e heltec_v4_repeater</code> passed after both corrections, including the firmware's flash-size and runtime-RAM checks. The initial audit used host tests and build checks; subsequent hardware checks are recorded in the dual-profile validation.</p>"},{"location":"companion_contact_cache/","title":"Full Companion contact caches","text":"<p>Full Companions on ESP32 and nRF52 without PSRAM now keep 16 outgoing paths and 16 shared secrets in RAM. Every contact remains in the contact table; selecting a different contact loads its saved path as needed. This recovers about 25.4 KiB of internal RAM in the 350-contact ESP32 qualification builds.</p> <p>See the qualification results for the six-board RAM comparison, physical tests, and shared-secret timings.</p> <p>PSRAM boards retain their existing complete contact table in external RAM. Legacy USB/BLE/WiFi Companion profiles also retain their inline paths and secrets. The build flag <code>MESH_CONTACT_CACHE=0</code> or <code>1</code> overrides this policy for qualification; it is not a runtime feature switch.</p>"},{"location":"companion_contact_cache/#paths-and-persistence","title":"Paths and persistence","text":"<p>The 16 resident paths use least-recently-used replacement. Contact records keep small handles to their saved paths, including 1-, 2-, and 3-byte hop hashes. The existing 152-byte contact record and Companion app frame formats are unchanged. ESP32 uses <code>/contacts3</code>; nRF52 also supports its paged contact store and migration from <code>/contacts3</code>. An erase is not required.</p> <p>A hot path needs no flash read. A cold path is read from its existing contact record. ESP32 reuses one open contact-file reader to avoid repeated SPIFFS metadata scans during synchronization and saving. It closes that reader before replacing the file or recovering a saved transaction.</p> <p>Changing a copied contact preserves the old path for a pending app response or rollback. Dirty entries are saved before eviction. If storage cannot be read, written, or represented completely, the operation fails instead of silently losing a contact or sending along a different route. Reboot retries an incomplete load from the preserved files. The path checksum also rejects a cold path changed underneath a live handle; it does not add a new checksum to the legacy ESP32 on-disk format.</p>"},{"location":"companion_contact_cache/#shared-secrets-and-power","title":"Shared secrets and power","text":"<p>Both platforms reuse the 16 most recent secrets from RAM. Cache misses use a platform-specific policy:</p> Platform Miss behavior ESP32 Recalculate the secret without reading or writing a secret file. nRF52 Try a saved LittleFS entry, then recalculate if it is unavailable. <p>On the V4, a measured SPIFFS secret lookup took 132,427 microseconds while key exchange took 21,932 microseconds. ESP32 therefore uses recalculation on a RAM-cache miss. It avoids secret-file writes and reduces time awake for this measured workload. These are elapsed times, not measurements of energy in joules; other ESP32 hardware has not been physically benchmarked.</p> <p>On a RAK3401, a LittleFS lookup took 7,812 microseconds versus 31,250 microseconds for key exchange. The nRF52 backend therefore uses saved flash entries to avoid repeat key exchange when a usable entry exists, including after reboot. Saved entries match the full peer public key and a fingerprint of the local key pair, and have a record checksum. Importing a different private or public key invalidates old results. A corrupt or missing saved entry is recalculated. The native tests use the firmware's actual Ed25519 key-exchange library and verify agreement with the peer's independently calculated secret.</p> <p>Derived secrets are expendable. Their storage keeps a reserve for contacts, preferences and filesystem metadata; a full filesystem leaves the calculated secret usable in RAM. nRF52 packs 56 entries into a 3,844-byte page to use its 4 KiB flash blocks efficiently. Small filesystems may not have space to persist secrets for all 350 contacts. A miss without a usable saved entry still performs key exchange.</p> <p><code>MESH_CONTACT_SECRET_FLASH_CACHE=0</code> or <code>1</code> overrides the miss policy for qualification builds. The optional ESP32 flash backend groups eight entries per file. The normal ESP32 policy does not create or use those files.</p>"},{"location":"companion_contact_cache/#inspect-the-cache","title":"Inspect the cache","text":"<p>From the Full Companion's ASCII USB terminal or authenticated local CLI:</p> <pre><code>get contact.cache\n</code></pre> <p>Cached builds report <code>paths=16 secrets=16</code>, <code>miss=calculate</code> or <code>miss=flash</code>, plus these boot-session counters:</p> Field Meaning <code>ram_hits</code> Shared secret reused from RAM. <code>flash_hits</code> Shared secret loaded from flash without recalculation. <code>calculations</code> Shared-secret key exchanges performed. <code>save_skips</code> Calculated secrets that could not be persisted, including storage reserve/backoff. <p>Uncached builds report <code>paths=inline secrets=inline</code>. The normal <code>memory</code> command on supported ESP32 Full Companions shows live heap and queue capacity.</p> <p><code>get contact.cache.timing</code> reports the last successful flash lookup and last key calculation in microseconds. Zero means no such operation has completed since boot. These timings exclude secret writes and are useful for comparing the work avoided on a valid flash hit.</p>"},{"location":"companion_contact_cache/#offline-messages-during-mota","title":"Offline messages during mOTA","text":"<p>Contact caches are independent of the offline message queue. Builds using the shared mOTA queue retain 256 frames normally and 128 while mOTA owns its workspace, then restore 256. No unread frames are discarded to start mOTA: synchronize the queue and retry if it exceeds the retained capacity. PSRAM-backed queues keep their existing capacity and allocation policy.</p> <p>Each queue frame occupies 177 bytes. Retaining 32 instead of 128 would make another 16,992 bytes (16.6 KiB) available inside the shared storage. It would not increase free heap by itself: the normal 256-frame storage is statically reserved, and the current mOTA context already fits in the loaned half. More mOTA scratch data would have to share that space to obtain an additional RAM saving. These changes keep the existing 128-frame mOTA limit.</p>"},{"location":"companion_contact_cache/#build-the-six-capacity-trials","title":"Build the six capacity trials","text":"<p>The optional environments in <code>platformio.nimble.ini</code> combine NimBLE, these contact caches, and the shared mOTA queue at 350 contacts, 40 channels and 256 normal offline frames. They remain outside the ordinary release matrix. The ordinary six constrained release recipes still use their established 150-contact limits pending wider hardware qualification.</p> <p>Enable <code>platformio.nimble.ini</code> as described in the NimBLE trial guide, then build one environment at a time. For example:</p> <pre><code>OUTPUT_DIR=.releases/contact-cache-v3 bash build.sh build-firmware \\\n  Heltec_v3_ram_trial_companion_radio_full_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-cache-trial \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n</code></pre> Hardware Trial environment Heltec V3 <code>Heltec_v3_ram_trial_companion_radio_full_nimble</code> Wireless Tracker <code>Heltec_Wireless_Tracker_ram_trial_companion_radio_full_nimble</code> Tracker V2, FEM on <code>heltec_tracker_v2_ram_trial_companion_radio_full_femon_nimble</code> Heltec CT62 <code>Heltec_ct62_ram_trial_companion_radio_full_nimble</code> XIAO ESP32-C3 <code>Xiao_C3_ram_trial_companion_radio_full_nimble</code> Generic ESP-NOW <code>Generic_ESPNOW_ram_trial_companion_radio_full_nimble</code> <p>The firmware RAM guard remains enabled. A successful linked budget is distinct from live free heap and physical Bluetooth/LoRa qualification on each board.</p> <p>The smaller NimBLE applications let the CT62, XIAO C3 and Generic ESP-NOW trials use two 1.5 MiB WiFi OTA slots on 4 MiB flash. Their 896 KiB SPIFFS and coredump stay at the same addresses as the ordinary <code>huge_app.csv</code> Full layout. Install the trial's merged image over USB first to install its partition table. Subsequent WiFi updates must fit the new slots. An application-only update from the ordinary single-slot Full layout cannot change that layout or enable WiFi OTA.</p>"},{"location":"companion_contact_cache/#regression-checks","title":"Regression checks","text":"<pre><code>python3 -B test/test_contact_cache.py\npython3 -B test/test_companion_contact_persistence_contract.py\npython3 -B test/test_companion_contact_stream_contract.py\npython3 -B test/test_nrf52_extrafs_contract.py\npython3 -B test/test_shared_mota_queue.py\npython3 -B test/test_t096_full_memory.py\npython3 -B test/test_firmware_ram.py\n</code></pre> <p>The cache tests compile the production path/secret cache code and extracted production persistence, routing and request functions with filesystem/radio adapters. They exercise 350 routes, eviction, snapshot rollback, page migration, identity changes, read/write/rename faults, handle exhaustion, packet release on a failed path read, and recovery after a simulated reset between file renames. They do not simulate a physical flash power cut.</p> <p><code>tools/hil/contact_cache_serial_stress.py</code> checks all 350 paths over USB, replaces them with a different generation, and optionally exercises secret eviction. Use an otherwise empty test node and exclusive access to its Companion data port. <code>--populate</code> writes test contacts; <code>--secrets</code> transmits 23 directed LoRa datagrams to synthetic peers. For an ESP32 cache trial:</p> <pre><code>python3 tools/hil/contact_cache_serial_stress.py --port /dev/ttyACM0 \\\n  --populate --generation 1 --secrets --expect-calculate --reboot\npython3 tools/hil/contact_cache_serial_stress.py --port /dev/ttyACM0 \\\n  --generation 1 --secrets --expect-calculate\n</code></pre> <p>Use the actual device path. Omit <code>--expect-calculate</code> for the nRF52 flash policy. The second invocation verifies the persisted paths after reboot.</p>"},{"location":"companion_contact_cache_results/","title":"Contact-cache and NimBLE RAM qualification","text":"<p>Test date: 2026-09-08. Firmware source: <code>b68aa1c6</code>.</p> <p>All six constrained ESP32 Full Companion trials pass the linked RAM budget at 350 contacts, 40 channels and 256 normal offline frames. Their final capability manifests confirm compiled Bluetooth/mOTA support and valid WiFi OTA layouts. These are the optional environments in the contact-cache guide. Ordinary release recipes retain their established contact limits pending qualification on those boards.</p>"},{"location":"companion_contact_cache_results/#linked-internal-ram","title":"Linked internal RAM","text":"<p>Every column below uses 350 contacts, 40 channels and 256 normal offline frames. Values are bytes available for runtime allocations after linking. The final margin subtracts the existing conservative runtime reservation; it is not a measurement of live free heap.</p> Hardware Bluedroid NimBLE NimBLE + mOTA queue loan Plus contact caches Final margin Heltec V3 143,776 158,896 170,152 196,168 23,112 Wireless Tracker 148,432 163,536 174,792 200,824 30,838 Tracker V2, FEM on 133,064 148,168 159,416 185,456 15,470 Heltec CT62 99,040 114,096 125,312 151,344 15,152 XIAO ESP32-C3 98,816 113,888 125,120 151,152 14,960 Generic ESP-NOW 99,776 114,800 126,032 152,064 15,872 <p>NimBLE recovers about 14.7 KiB. Contact caches add about 25.4 KiB on top of NimBLE and the shared mOTA workspace. NimBLE alone fails the unchanged budget at this capacity on all six; adding the queue loan passes only on the original Wireless Tracker. Adding the contact caches passes all six, with 14.6-30.1 KiB of margin. The same Bluetooth runtime allowance is used in every comparison.</p> <p>The shared mOTA queue stays at 256 frames normally and retains 128 while mOTA borrows its workspace, then returns to 256. A queue above 128 must be synchronized before that workspace can be borrowed; unread frames are not discarded to start mOTA. PSRAM-backed queues retain their existing policy.</p> <p>The baseline builds use <code>b041fc7f</code>; the final builds use <code>b68aa1c6</code>, with the same ESP32 Arduino 2.0.17 toolchain and NimBLE-Arduino 2.5.1 where applicable.</p> <p>The CT62, XIAO C3 and Generic ESP-NOW applications fit two 1.5 MiB OTA slots on 4 MiB flash. Their explicit trial layouts retain 896 KiB SPIFFS and the existing SPIFFS/coredump addresses. Install the merged image over USB when changing from the ordinary single-slot Full layout. The other three trials also retain verified dual WiFi OTA slots. All six remain mOTA senders.</p> <p>Additional builds check the platform and default-policy branches:</p> Build Available bytes Reserved runtime bytes Margin bytes Policy T096 Full, FEM on 100,076 73,728 26,348 nRF52 path/secret caches RAK3401 Full 99,900 50,976 48,924 nRF52 path/secret caches Wireless Paper Full 187,360 152,576 34,784 ESP32 caches, existing Bluedroid V4 Full NimBLE 263,944 173,056 90,888 Complete contacts in PSRAM XIAO nRF52 legacy BLE Companion 84,368 38,688 45,680 Existing inline contact storage <p>The V4 test-only forced-cache build also passes its RAM budget. The V4 normally keeps complete contacts in PSRAM; forcing caches adds internal RAM overhead. The six-board savings above apply to boards without PSRAM.</p>"},{"location":"companion_contact_cache_results/#physical-checks","title":"Physical checks","text":"<p>The VM V4 used the test-only cache override. USB tests verified all 350 contacts and all 64 saved path bytes per contact, cold individual lookups, replacement of the complete path set, and persistence after reboot. A secret workload contacted 21 distinct synthetic peers, then the first peer twice: 22 calculations, one RAM hit, and no secret-file access under the ESP32 policy.</p> <p>A sustained send test exposed a false receive watchdog recovery. RX could occur inside the main loop between two successful transmissions, while the watchdog observed TX at both loop boundaries. It counted from the start of the whole burst and could reset a working radio during a later CAD pause. <code>468cc3cf</code> restarts the receive recovery allowance after each successful TX. The native regression fails before that change and passes afterward; it also checks that a stuck receiver still gets recovered.</p> <p>The corrected V4 passed the same 23-datagram workload with zero radio error flags. It also passed a complete 350-path replacement, another send workload and a post-reboot path check with zero radio error flags. The replacement took about 127 seconds: dirty-cache eviction still performs synchronous SPIFFS contact-file saves, so bulk path updates remain a latency workload to qualify on the other ESP32 boards. After that run it reported 133,828 bytes free internal heap, a minimum of 130,976 bytes, and a largest free block of 122,868 bytes. These readings belong to the forced-cache V4 workload, not the six other boards.</p> <p>After qualification, the VM V4 was erased to remove synthetic contacts and installed with the normal PSRAM-backed V4 NimBLE trial from <code>b68aa1c6</code>. It is named <code>NimBLE-V4-VM</code>, uses the PIN shown on its display, and has powersaving off for USB use. That clean setup reported 143,612 bytes of free internal heap and passed 201 local USB requests with zero radio error flags. The Mercer V4 and XIAO S3 were left on their previously qualified NimBLE builds.</p> <p>The Mercer RAK3401 Full Companion verified 350 paths, eviction and persistence. Its first secret workload produced 21 calculations, one flash hit and one RAM hit with no skipped saves. After reboot, the same workload produced 22 flash hits, one RAM hit and zero calculations. Both completed with zero radio error flags. The final <code>b68aa1c6</code> RAK image repeated the 350-path and saved-secret checks with zero radio errors and zero calculations. The RAK was returned to the published <code>26303793</code> repeater application with its original repeater name and USA Cascade settings; the Pi's MQTT logger was restarted after the exclusive USB tests.</p>"},{"location":"companion_contact_cache_results/#shared-secret-timing","title":"Shared-secret timing","text":"Hardware/filesystem Successful saved-secret lookup Key exchange Selected miss policy V4 / SPIFFS 132,427 us 21,932 us Recalculate RAK3401 / LittleFS 7,812-8,789 us 31,250 us Read saved entry, calculate on miss <p>The SPIFFS timing comes from the earlier forced flash-cache experiment. The final ESP32 policy does no secret-file I/O. Both platforms reuse the 16 most recent secrets from RAM. These are elapsed-time measurements, not energy measurements; timing on other ESP32/nRF52 boards remains to be measured.</p>"},{"location":"companion_contact_cache_results/#regression-checks-and-evidence","title":"Regression checks and evidence","text":"<p>The contact-cache suite exercises the production cache and persistence code under address/undefined-behavior sanitizers, with the real Ed25519 key-exchange implementation. Its cases include 350 paths, identity changes, snapshots, legacy migration, storage faults, handle exhaustion and packet release when a cold path cannot be read. The related contract suites passed 62 checks. The native queue/store suites passed 27 cases, the radio-liveness suite passed eight, and the partition-selection suite passed 11.</p> <p>Hardware reproduction commands are in the contact-cache guide. The tracked harness is <code>tools/hil/contact_cache_serial_stress.py</code>. It requires exclusive access to the specified Companion data port.</p> <p>Local evidence in the qualification workspace:</p> <ul> <li><code>.releases/nimble-six-capacity/control/results.json</code>: 18 baseline builds.</li> <li><code>.releases/contact-cache/qualified/control/results.json</code>: final build results.</li> <li><code>.releases/contact-cache/qualified/built/</code>: firmware, ELFs, maps, RAM reports,   partition tables and capability manifests.</li> <li><code>.releases/contact-cache/qualified/control/</code>: final V4 USB and flash checks.</li> <li><code>.releases/contact-cache/control/</code>: earlier experiments, RAK results and   regression logs, including the watchdog's failing/passing test runs.</li> </ul> <p>Each final RAM report is checked against its ELF hash. All 12 final builds pass their RAM and OTA capability checks. Physical testing here covers the V4 and RAK3401; the six constrained ESP32 boards still need pairing, WiFi/BLE/LoRa coexistence and sustained-load testing on their own hardware. No GitHub release assets or firmware-picker entries were replaced by these experimental builds.</p>"},{"location":"companion_offline_queue/","title":"Companion Offline Message Queue","text":"<p>Companion firmware keeps received channel data, channel messages, and direct messages in one pending queue until a Companion client requests them with the sync-next-message command. This is volatile RAM, not message history in flash. A reboot clears it.</p>"},{"location":"companion_offline_queue/#default-capacities","title":"Default capacities","text":"Platform or memory profile Pending frames ESP32 with configured PSRAM 512 ESP32 without PSRAM 256 nRF52840 256 nRF52 Full Companion with the memory correction 256 normally; 128 while mOTA owns shared storage RP2040 256 STM32 16 Known constrained classic ESP32 target override 128 Meshadventurer Full Companion 16 Constrained Full ESP32 fallback 16 <p>An explicit target <code>OFFLINE_QUEUE_SIZE</code> overrides the platform default. The Heltec V2 and TLora V2 Full Companion profiles, for example, use 16 frames so their combined WiFi, BLE, and LoRa mOTA image retains enough internal DRAM. Meshadventurer SX1262 and SX1268 Full Companion use 16 frames together with 100 contacts and 30 group channels; their ordinary transport-specific images keep 128 frames and 40 channels.</p> <p>The nRF52 Full memory correction applies queue sharing to every nRF52 Full Companion. It keeps 256 frames normally, retaining each board's contacts, channels, and all Full transports. The upper 128 slots temporarily hold the mOTA context when a source or TempRadio discovery session starts. Stopping or disconnecting the USB/Bluetooth source returns all 256 slots; a discovery-only session returns them when TempRadio ends. This shares a fixed memory region and avoids heap fragmentation from resizing.</p> <p>Existing unread messages retain their order. If more than 128 frames are pending, mOTA refuses the loan and asks you to sync messages with a Companion app first. While the loan is active, the overflow policy below applies at 128 frames. The original <code>26303793</code> 1.17.1.5 builds reserve the queue and mOTA state separately. Sharing recovers about 19 KiB on nRF52 Full. The ST7735 color-display Full profiles require at least 72 KiB of heap space at link time; OLED and headless profiles use their own memory budgets.</p> <p>Standard, logging, MQTT, and Cascade build overlays retain the selected target capacity; they do not silently shrink the queue.</p> <p>Each queue slot currently costs 177 bytes. A 256-frame queue reserves 45,312 bytes, while a 512-frame queue reserves 90,624 bytes. There is no 256-frame protocol limit: the queue length and indexes can represent 512 or more. The practical limit is available RAM and the heap and stack headroom required by the transports and display.</p> <p>On ESP32 boards marked with <code>BOARD_HAS_PSRAM</code>, the queue is allocated from PSRAM before WiFi and BLE start. A failed 512-frame allocation retries at 256, then 128, and finally uses a 16-frame internal fallback. Full Companion prints the capacity actually allocated in its startup memory line as <code>offline_queue=&lt;frames&gt;</code>.</p>"},{"location":"companion_offline_queue/#full-queue-behavior","title":"Full queue behavior","text":"<p>The capacity is shared across Public, other channels, channel data, and direct messages. It is not a per-channel count. When the queue is full, firmware replaces the oldest queued channel frame so newer traffic can still arrive. If the full queue contains only direct messages, a new frame is dropped rather than deleting a direct message.</p> <p>Queue order is preserved. Removal uses a ring index, so delivering one pending message no longer copies every remaining frame; only the less-common removal of an old channel frame from a full queue may shift entries.</p> <p>Capacity is selected when firmware is compiled. There is no CLI or Companion protocol setting to resize it at runtime.</p>"},{"location":"companion_protocol/","title":"Companion Protocol","text":"<ul> <li>Last Updated: 2026-08-26</li> <li>Protocol Version: 14 (<code>FIRMWARE_VER_CODE</code>)</li> </ul> <p>The command and response catalogs track <code>examples/companion_radio/MyMesh.cpp</code>. Applications should negotiate the protocol and validate lengths because older firmware exposes a subset.</p> <p>This document is a practical guide to MeshCore's binary companion protocol. The same protocol frames can be carried by the enabled BLE, USB serial, Wi-Fi, or Ethernet companion interface; connection details differ by build.</p> <p>On builds exposing more than one transport, delivery-required replies follow the interface which supplied the command. The multi-frame contact-list response holds that route until <code>END_OF_CONTACTS</code>; best-effort asynchronous observations may still be broadcast to enabled clients. Treat the device as one Companion session rather than as independent per-transport sessions.</p> <p>The examples focus on BLE, but the packet formats are transport-independent.</p>"},{"location":"companion_protocol/#official-libraries","title":"Official Libraries","text":"<p>Please see the following repos for existing MeshCore Companion Protocol libraries.</p> <ul> <li>JavaScript: https://github.com/meshcore-dev/meshcore.js</li> <li>Python: https://github.com/meshcore-dev/meshcore_py</li> </ul>"},{"location":"companion_protocol/#important-security-note","title":"Important Security Note","text":"<p>All secrets, hashes, and cryptographic values shown in this guide are example values only.</p> <ul> <li>All hex values, public keys and hashes are for demonstration purposes only</li> <li>Never use example secrets in production</li> <li>Always generate new cryptographically secure random secrets</li> <li>Please implement proper security practices in your implementation</li> <li>This guide is for protocol documentation only</li> </ul>"},{"location":"companion_protocol/#table-of-contents","title":"Table of Contents","text":"<ol> <li>BLE Connection</li> <li>Packet Structure</li> <li>Commands</li> <li>Channel Management</li> <li>Message Handling</li> <li>Response Parsing</li> <li>Example Implementation Flow</li> <li>Best Practices</li> <li>Troubleshooting</li> </ol>"},{"location":"companion_protocol/#ble-connection","title":"BLE Connection","text":""},{"location":"companion_protocol/#service-and-characteristics","title":"Service and Characteristics","text":"<p>MeshCore Companion devices expose a BLE service with the following UUIDs:</p> <ul> <li>Service UUID: <code>6E400001-B5A3-F393-E0A9-E50E24DCCA9E</code></li> <li>RX Characteristic (App -&gt; Firmware): <code>6E400002-B5A3-F393-E0A9-E50E24DCCA9E</code></li> <li>TX Characteristic (Firmware -&gt; App): <code>6E400003-B5A3-F393-E0A9-E50E24DCCA9E</code></li> </ul> <p>An nRF52 Full Companion also exposes a separate LoRa mOTA source service. It does not replace or multiplex the normal Companion UART service:</p> <ul> <li>mOTA Service: <code>14518FC2-7E7A-4D84-8CAE-6664B0234CF2</code></li> <li>Device Request (notify): <code>2BFAA1EE-7030-459A-B65A-E7CFD5B09735</code></li> <li>Host Response (write with response): <code>ACF38A51-DD58-4DCE-917F-0B1135E41B1A</code></li> </ul> <p>All three mOTA attributes require an encrypted, MITM-authenticated connection using the Companion's six-digit PIN. The source remains inactive until the client subscribes to Device Request and explicitly starts it with command <code>0x4B</code>. See Bluetooth LoRa mOTA source.</p> <p>ESP32 and nRF52 Companion UART characteristics require the same PIN-protected, MITM-authenticated link. ESP32 advertises DisplayOnly capability so a central must enter the PIN shown by the Companion; a Just Works bond is insufficient.</p>"},{"location":"companion_protocol/#connection-steps","title":"Connection Steps","text":"<ol> <li> <p>Scan for Devices</p> <ul> <li>Scan for BLE devices advertising the MeshCore Service UUID</li> <li>Optionally filter by device name (typically contains \"MeshCore\" prefix)</li> <li>Note the device MAC address for reconnection</li> </ul> </li> <li> <p>Connect to GATT</p> <ul> <li>Connect to the device using the discovered MAC address</li> <li>Wait for connection to be established</li> </ul> </li> <li> <p>Discover Services and Characteristics</p> <ul> <li>Discover the service with UUID <code>6E400001-B5A3-F393-E0A9-E50E24DCCA9E</code></li> <li>Discover the RX characteristic <code>6E400002-B5A3-F393-E0A9-E50E24DCCA9E</code><ul> <li>Your app writes to this, the firmware reads from this</li> </ul> </li> <li>Discover the TX characteristic <code>6E400003-B5A3-F393-E0A9-E50E24DCCA9E</code><ul> <li>The firmware writes to this, your app reads from this</li> </ul> </li> </ul> </li> <li> <p>Enable Notifications</p> <ul> <li>Subscribe to notifications on the TX characteristic to receive data from the firmware</li> </ul> </li> <li> <p>Send Initial Commands</p> <ul> <li>Send <code>CMD_APP_START</code> to identify your app to firmware and get radio settings</li> <li>Send <code>CMD_DEVICE_QUERY</code> to fetch device info and negotiate supported protocol versions</li> <li>Send <code>CMD_SET_DEVICE_TIME</code> to set the firmware clock</li> <li>Send <code>CMD_GET_CONTACTS</code> to fetch all contacts</li> <li>Send <code>CMD_GET_CHANNEL</code> multiple times to fetch all channel slots</li> <li>Send <code>CMD_SYNC_NEXT_MESSAGE</code> to fetch the next message stored in firmware</li> <li>Setup listeners for push codes, such as <code>PUSH_CODE_MSG_WAITING</code> or <code>PUSH_CODE_ADVERT</code></li> <li>See Commands section for information on other commands</li> </ul> </li> </ol> <p>Note: MeshCore devices may disconnect after periods of inactivity. Implement auto-reconnect logic with exponential backoff.</p>"},{"location":"companion_protocol/#ble-write-type","title":"BLE Write Type","text":"<p>When writing commands to the RX characteristic, specify the write type:</p> <ul> <li>Write with Response (default): Waits for acknowledgment from device</li> <li>Write without Response: Faster but no acknowledgment</li> </ul> <p>Platform-specific:</p> <ul> <li>Android: Use <code>BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT</code> or <code>WRITE_TYPE_NO_RESPONSE</code></li> <li>iOS: Use <code>CBCharacteristicWriteType.withResponse</code> or <code>.withoutResponse</code></li> <li>Python (bleak): Use <code>write_gatt_char()</code> with <code>response=True</code> or <code>False</code></li> </ul> <p>Recommendation: Use write with response for reliability.</p>"},{"location":"companion_protocol/#mtu-maximum-transmission-unit","title":"MTU (Maximum Transmission Unit)","text":"<p>The default BLE MTU is 23 bytes (20 bytes payload). For larger commands like <code>SET_CHANNEL</code> (50 bytes), you may need to:</p> <ol> <li>Request Larger MTU: Request MTU of 512 bytes if supported<ul> <li>Android: <code>gatt.requestMtu(512)</code></li> <li>iOS: <code>peripheral.maximumWriteValueLength(for:)</code></li> <li>Python (bleak): MTU is negotiated automatically</li> </ul> </li> </ol>"},{"location":"companion_protocol/#command-sequencing","title":"Command Sequencing","text":"<p>Critical: Commands must be sent in the correct sequence:</p> <ol> <li> <p>After Connection:</p> <ul> <li>Wait for BLE connection to be established</li> <li>Wait for services/characteristics to be discovered</li> <li>Wait for notifications to be enabled</li> <li>Now you can safely send commands to the firmware</li> </ul> </li> <li> <p>Command-Response Matching:</p> <ul> <li>Send one command at a time</li> <li>Wait for a response before sending another command</li> <li>Use a timeout (typically 5 seconds)</li> <li>Match response to command by type (e.g: <code>CMD_GET_CHANNEL</code> -&gt; <code>RESP_CODE_CHANNEL_INFO</code>)</li> </ul> </li> </ol>"},{"location":"companion_protocol/#command-queue-management","title":"Command Queue Management","text":"<p>For reliable operation, implement a command queue.</p> <p>Queue Structure:</p> <ul> <li>Maintain a queue of pending commands</li> <li>Track which command is currently waiting for a response</li> <li>Only send next command after receiving response or timeout</li> </ul> <p>Error Handling:</p> <ul> <li>On timeout, clear current command, process next in queue</li> <li>On error, log error, clear current command, process next</li> </ul>"},{"location":"companion_protocol/#packet-structure","title":"Packet Structure","text":"<p>The MeshCore protocol uses a binary format with the following structure:</p> <ul> <li>Commands: Sent from app to firmware via RX characteristic</li> <li>Responses: Received from firmware via TX characteristic notifications</li> <li>All multi-byte integers: Little-endian byte order (except CayenneLPP which is Big-endian)</li> <li>All strings: UTF-8 encoding</li> </ul> <p>Most packets follow this format:</p> <pre><code>[Packet Type (1 byte)] [Data (variable length)]\n</code></pre> <p>The first byte indicates the packet type (see Response Parsing).</p>"},{"location":"companion_protocol/#commands","title":"Commands","text":"<p>The first byte selects the command. This is the current protocol-v14 command catalog; bytes <code>0x2C</code>-<code>0x31</code> are parked and <code>0x35</code> is unused.</p> Byte Firmware name Purpose <code>0x01</code> <code>CMD_APP_START</code> Start an app session and request self information. <code>0x02</code> <code>CMD_SEND_TXT_MSG</code> Send text to a contact. <code>0x03</code> <code>CMD_SEND_CHANNEL_TXT_MSG</code> Send channel text. <code>0x04</code> <code>CMD_GET_CONTACTS</code> Enumerate contacts, optionally modified since a timestamp. <code>0x05</code> / <code>0x06</code> <code>CMD_GET_DEVICE_TIME</code> / <code>CMD_SET_DEVICE_TIME</code> Read or set the device clock. <code>0x07</code> / <code>0x08</code> <code>CMD_SEND_SELF_ADVERT</code> / <code>CMD_SET_ADVERT_NAME</code> Advertise self or change the advertised name. <code>0x09</code> <code>CMD_ADD_UPDATE_CONTACT</code> Add or update a contact. <code>0x0A</code> <code>CMD_SYNC_NEXT_MESSAGE</code> Dequeue the next pending message. <code>0x0B</code> / <code>0x0C</code> <code>CMD_SET_RADIO_PARAMS</code> / <code>CMD_SET_RADIO_TX_POWER</code> Set radio parameters or transmit power. <code>0x0D</code> <code>CMD_RESET_PATH</code> Reset a contact's learned path. <code>0x0E</code> <code>CMD_SET_ADVERT_LATLON</code> Set advertised coordinates. <code>0x0F</code> <code>CMD_REMOVE_CONTACT</code> Remove a contact. <code>0x10</code> / <code>0x11</code> / <code>0x12</code> <code>CMD_SHARE_CONTACT</code> / <code>CMD_EXPORT_CONTACT</code> / <code>CMD_IMPORT_CONTACT</code> Share, export, or import contact data. <code>0x13</code> <code>CMD_REBOOT</code> Reboot after the required confirmation body. <code>0x14</code> <code>CMD_GET_BATT_AND_STORAGE</code> Read battery and storage usage. <code>0x15</code> <code>CMD_SET_TUNING_PARAMS</code> Set tuning parameters. <code>0x16</code> <code>CMD_DEVICE_QUERY</code> Negotiate protocol support and read device information. <code>0x17</code> / <code>0x18</code> <code>CMD_EXPORT_PRIVATE_KEY</code> / <code>CMD_IMPORT_PRIVATE_KEY</code> Export or import identity key material when enabled. <code>0x19</code> <code>CMD_SEND_RAW_DATA</code> Send an application raw-data packet. <code>0x1A</code>-<code>0x1D</code> <code>CMD_SEND_LOGIN</code> through <code>CMD_LOGOUT</code> Manage a server connection. <code>0x1E</code> <code>CMD_GET_CONTACT_BY_KEY</code> Look up a contact by public-key prefix. <code>0x1F</code> / <code>0x20</code> <code>CMD_GET_CHANNEL</code> / <code>CMD_SET_CHANNEL</code> Read or write a channel slot. <code>0x21</code>-<code>0x23</code> <code>CMD_SIGN_START</code> through <code>CMD_SIGN_FINISH</code> Stream data for identity signing. <code>0x24</code> <code>CMD_SEND_TRACE_PATH</code> Trace a direct route. <code>0x25</code> <code>CMD_SET_DEVICE_PIN</code> Set or clear the device PIN. <code>0x26</code> <code>CMD_SET_OTHER_PARAMS</code> Set telemetry, location, ACK, and related preferences. <code>0x27</code> <code>CMD_SEND_TELEMETRY_REQ</code> Send the legacy telemetry request. <code>0x28</code> / <code>0x29</code> <code>CMD_GET_CUSTOM_VARS</code> / <code>CMD_SET_CUSTOM_VAR</code> Read or set custom variables. <code>0x2A</code> <code>CMD_GET_ADVERT_PATH</code> Read a cached advertisement path. <code>0x2B</code> <code>CMD_GET_TUNING_PARAMS</code> Read tuning parameters. <code>0x32</code> <code>CMD_SEND_BINARY_REQ</code> Send an application binary request. <code>0x33</code> <code>CMD_FACTORY_RESET</code> Factory-reset after the required confirmation body. <code>0x34</code> <code>CMD_SEND_PATH_DISCOVERY_REQ</code> Request path discovery. <code>0x36</code> <code>CMD_SET_FLOOD_SCOPE_KEY</code> Select scoped or unscoped flood behavior. <code>0x37</code> <code>CMD_SEND_CONTROL_DATA</code> Send zero-hop control data. <code>0x38</code> <code>CMD_GET_STATS</code> Read core, radio, or packet statistics. <code>0x39</code> <code>CMD_SEND_ANON_REQ</code> Send an anonymous request. <code>0x3A</code> / <code>0x3B</code> <code>CMD_SET_AUTOADD_CONFIG</code> / <code>CMD_GET_AUTOADD_CONFIG</code> Write or read automatic-contact policy. <code>0x3C</code> <code>CMD_GET_ALLOWED_REPEAT_FREQ</code> Read allowed client-repeat frequency ranges. <code>0x3D</code> <code>CMD_SET_PATH_HASH_MODE</code> Set path-hash width mode. <code>0x3E</code> <code>CMD_SEND_CHANNEL_DATA</code> Send a channel binary datagram. <code>0x3F</code> / <code>0x40</code> <code>CMD_SET_DEFAULT_FLOOD_SCOPE</code> / <code>CMD_GET_DEFAULT_FLOOD_SCOPE</code> Write or read the default flood scope. <code>0x41</code> <code>CMD_SEND_RAW_PACKET</code> Queue a fully encoded raw mesh packet. <code>0x42</code> <code>CMD_RUN_CLI_COMMAND</code> Run a local CLI command (protocol v14+). <code>0x4A</code> <code>CMD_EXEC_LOCAL_OTA_CONTROL</code> Run one bounded local TempRadio or OTA command when the Companion includes the OTA CLI. <code>0x4B</code> <code>CMD_BLE_MOTA_SOURCE</code> Query, start, or stop an nRF52 Full Companion's Bluetooth-backed LoRa mOTA source. <code>0x78</code>-<code>0x7F</code> Deprecated hardware-setting aliases Receive-only compatibility for clients shipped before command <code>0x42</code> became the canonical settings path. <p>The sections below detail the most common frames. Refer to the source named above for command bodies that are not expanded here.</p> <p><code>CMD_RUN_CLI_COMMAND</code> is followed by the local CLI text without a terminating NUL. The device returns <code>RESP_CODE_CLI_REPLY</code> (<code>0x1D</code>) followed by the reply text. This is separate from sending a remote on-air CLI command with <code>CMD_SEND_TXT_MSG</code> and <code>TXT_TYPE_CLI_COMMAND</code>. The body must contain at least one byte and must not contain an embedded NUL. An unknown command is returned as the normal CLI reply text <code>Unknown command</code>, not as an error frame. Clients may prefix the CLI text with any two-character correlation tag and <code>|</code> (for example, <code>A7|get radio.rxgain</code>); the reply preserves that prefix.</p> <p>Direct USB, BLE, WiFi TCP, and Ethernet clients can also use this command for <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code>, <code>erase</code>, and <code>get prv.key</code> (when private key export is enabled). WiFi/MQTT builds accept <code>get wifi.pwd</code>, <code>get mqttN.password</code>, and <code>get mqttN.token</code>. <code>get password</code> reports that Companion has no admin password; infrastructure roles return their own admin password on a local CLI connection. These privileges do not apply to CLI commands relayed over LoRa. <code>set freq &lt;MHz&gt;</code> works through command <code>0x42</code> and authorized LoRa CLI, like <code>set radio</code>; it saves the frequency and requires reboot to apply. See local maintenance commands for role differences and the text-terminal equivalents.</p> <p>Full Companion clients can send <code>version</code> through this command to receive the untruncated build identity, for example <code>Companion 1.17.1.5-... (protocol 14, build 31-Aug-2026)</code>. This deliberately supplements rather than changes the 20-byte legacy version field in <code>RESP_CODE_DEVICE_INFO</code>, so existing clients keep the same frame layout.</p> <p>Firmware from this fork predating the upstream <code>0x42</code> allocation used <code>0x42</code>-<code>0x49</code> for these eight settings. This firmware accepts those values as deprecated inbound aliases so existing clients continue to work. A one-byte <code>0x42</code> frame is the legacy FEM-gain GET; <code>0x42</code> followed by text is the official <code>CMD_RUN_CLI_COMMAND</code>. New clients should use <code>CMD_RUN_CLI_COMMAND</code> for all of these settings, rather than allocating additional command bytes. For example, send <code>0x42</code> followed by <code>get radio.rxgain</code> or <code>set radio.rxgain on</code>. The reply is <code>RESP_CODE_CLI_REPLY</code> followed by the normal CLI reply text.</p> <p>Two deprecated binary alias blocks remain receive-only for compatibility:</p> Setting Original alias Later fork alias GET body/reply SET body/reply FEM receive gain <code>0x42</code> / <code>0x43</code> <code>0x78</code> / <code>0x79</code> No body; <code>OK, state</code> One byte <code>0</code>/<code>1</code>; <code>OK</code> Radio receive gain <code>0x44</code> / <code>0x45</code> <code>0x7A</code> / <code>0x7B</code> No body; <code>OK, state</code> One byte <code>0</code>/<code>1</code>; <code>OK</code> WiFi power save <code>0x46</code> / <code>0x47</code> <code>0x7C</code> / <code>0x7D</code> No body; <code>OK, mode</code> One mode byte <code>0</code>-<code>2</code>; <code>OK</code> Bluetooth name <code>0x48</code> / <code>0x49</code> <code>0x7E</code> / <code>0x7F</code> No body; <code>OK, custom, name</code> Zero to 31 UTF-8 bytes; <code>OK</code> <p>Each pair lists GET then SET. Here <code>OK</code> is <code>RESP_CODE_OK</code>; the remaining reply bytes have the same meanings as the CLI settings below. A bare <code>0x42</code> is the old FEM GET, while <code>0x42</code> plus at least one text byte is <code>CMD_RUN_CLI_COMMAND</code>. New clients must use the framed CLI form; these aliases exist only so deployed clients do not break after a firmware update.</p> <p>The equivalent framed CLI commands are:</p> Setting Commands Radio receive gain <code>get radio.rxgain</code>; <code>set radio.rxgain on|off</code> FEM receive gain <code>get radio.fem.rxgain</code>; <code>set radio.fem.rxgain on|off</code> WiFi power save <code>get wifi.powersave</code>; <code>set wifi.powersave none|min|max</code> Bluetooth name <code>get bluetooth.name</code>; <code>set bluetooth.name &lt;name|default&gt;</code> Bluetooth address <code>get bluetooth.mac</code>; <code>set bluetooth.mac &lt;address|random|random-every-boot|random-after-connect|default&gt;</code> Bluetooth stealth <code>get bluetooth.stealth</code>; <code>set bluetooth.stealth on|off</code> <p>The framed form works over the normal binary USB, BLE, or TCP transport and does not need the USB terminal-start token. Unsupported settings return the same explanatory text as the local CLI.</p> <p>WiFi power-save modes are:</p> Value Mode <code>0</code> <code>min</code> - minimum modem sleep <code>1</code> <code>none</code> - no modem sleep <code>2</code> <code>max</code> - maximum modem sleep <p>A Full Companion that runs BLE and infrastructure WiFi simultaneously rejects WiFi mode <code>none</code> because coexistence requires modem sleep. A Full Companion using ESP-NOW as its primary mesh radio also rejects <code>max</code>, because maximum modem sleep can miss broadcasts that the access point cannot buffer. If an older image saved a conflicting value, the effective mode is capped to and reported as <code>min</code>. Device power saving remains independent.</p> <p>The SenseCAP Indicator Full profiles run exactly one secondary wireless Companion transport per boot. Their active-mode constraints are:</p> Indicator mode Accepted <code>wifi.powersave</code> values LoRa + infrastructure WiFi <code>none</code>, <code>min</code>, <code>max</code> LoRa + BLE <code>min</code>, <code>max</code>; infrastructure WiFi is not started ESP-NOW + infrastructure WiFi <code>none</code>, <code>min</code>; <code>max</code> conflicts with primary ESP-NOW ESP-NOW + BLE <code>min</code>; infrastructure WiFi is not started and primary ESP-NOW remains active <p>The Bluetooth name can be configured over USB, BLE, or TCP. Use <code>set bluetooth.name default</code> to restore <code>MeshCore-&lt;advert name&gt;</code>; an empty CLI value is rejected. (<code>clear</code> is also accepted as an alias for <code>default</code>.) A custom name is limited to 31 valid UTF-8 bytes and takes effect after reboot.</p> <p>Bluetooth Companion builds also accept <code>bluetooth.mac</code> (<code>ble.mac</code> is an alias). A literal address must be a BLE random-static address; <code>random</code> generates and saves one, <code>random-every-boot</code> rotates it at each startup, and <code>random-after-connect</code> retains it through unused boots but rotates it on the first boot after an authenticated connection. <code>default</code> or <code>clear</code> restores the factory address. The change takes effect after reboot.</p> <p><code>bluetooth.stealth on|off</code> (<code>ble.stealth</code> is an alias) is a separate flag, defaulting to off. It preserves the address policy and can be combined with custom, saved random, rotating random, or factory addresses. With stealth on, the node advertises normally until the first authenticated pairing, then permits only that bonded peer to reconnect. Address changes clear the saved peer and reopen pairing without disabling stealth. Rotating policies retain their normal rotation triggers. Repeating <code>on</code> does not clear an existing bond. Both flag changes require reboot. The old MAC value <code>stealth</code> is not accepted.</p> <p>BLE still transmits directed or allowlisted advertisements; stealth is not radio silence. These are application settings; an nRF52 OTAFIX bootloader continues to advertise its separate DFU identity.</p>"},{"location":"companion_protocol/#bluetooth-lora-mota-source","title":"Bluetooth LoRa mOTA source","text":"<p>Protocol v14 lets a phone control an install-capable Companion's own LoRa OTA session. An nRF52 Full Companion can additionally act as the source for a remote repeater update without a USB computer. The normal Companion service still carries contacts, repeater login, CLI messages, and these two control commands. The separate mOTA service carries only host-folder request/response frames.</p> <p><code>CMD_EXEC_LOCAL_OTA_CONTROL</code> (<code>0x4A</code>) is followed by 1-174 printable ASCII bytes. A Companion built with the OTA CLI accepts only these local command families:</p> <pre><code>tempradio &lt;freq_kHz&gt;,&lt;bw_kHz&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;minutes&gt;\nnormalradio\nota ...\n</code></pre> <p><code>ota folder ...</code> is deliberately rejected because USB and Bluetooth source ownership must not be changed through the wrong transport. Embedded NUL, CR, LF, other control bytes, non-ASCII bytes, empty commands, and oversized frames return <code>ERR_CODE_ILLEGAL_ARG</code>. A recognized command replies with <code>RESP_CODE_OK</code>, one unsigned reply-length byte, and exactly that many printable result bytes. Shell metacharacters are rejected as well; the text is dispatched only to the in-firmware parser and is never passed to a host shell. Firmware without the OTA CLI feature returns <code>ERR_CODE_UNSUPPORTED_CMD</code>.</p> <p><code>CMD_BLE_MOTA_SOURCE</code> (<code>0x4B</code>) has one action byte:</p> Action Meaning <code>0</code> Read status without changing it. <code>1</code> Attach and enumerate the subscribed Bluetooth host's <code>.mota</code> catalog. <code>2</code> Detach the Bluetooth source. <p>Current firmware returns eleven bytes (legacy protocol-v14 previews returned the seven-byte prefix only):</p> <pre><code>00 action flags offered_le16 advertised_le16 source_packets_sent_le32\n</code></pre> <p>Flag bit <code>0x01</code> means the encrypted GATT channel is connected and Device Request notifications are enabled. Bit <code>0x02</code> means the Bluetooth catalog is attached. Bit <code>0x04</code> means USB or another folder transport currently owns the source slot. Start without a ready subscription, or while another source link owns the slot, returns <code>ERR_CODE_BAD_STATE</code>. A non-nRF52 Full Companion returns <code>ERR_CODE_UNSUPPORTED_CMD</code>. <code>source_packets_sent</code> is a per-attachment count of OTA packets accepted by the Companion's LoRa transmit adapter, including catalog/manifest traffic, data, proofs, and retries. It wraps as an unsigned 32-bit value. Clients should accept the legacy seven-byte response and display the packet counter as unavailable.</p> <p>After a successful start, the device sends the same bounded seeder frames used by <code>motatool serve</code> on Device Request:</p> <pre><code>device -&gt; host: 'M' 'S' op args... xor(op || args)\nhost -&gt; device: 'm' 's' op status payload... xor(all prior bytes)\n</code></pre> <p>Device requests are at most 11 bytes. A source response is at most 197 bytes. The host may split one response across multiple write-with-response operations when the negotiated ATT payload is smaller; it must preserve byte order and must not interleave another response. Bad checksums, partial frames, overflow, unsubscribe, loss of encryption, or disconnect fail closed. The firmware then detaches the catalog and stops advertising its entries. USB and Bluetooth folder sources are mutually exclusive.</p> <p>A Linux reference controller and seeder is provided at <code>tools/ble_mota/ble_mota_seeder.py</code>. It verifies every input with <code>motatool</code> before offering it. A mobile implementation should apply the same complete container verification before serving files.</p>"},{"location":"companion_protocol/#1-app-start","title":"1. App Start","text":"<p>Purpose: Initialize communication with the device. Must be sent first after connection.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x01\nBytes 1-7: Reserved (currently ignored by firmware)\nBytes 8+: Application name (UTF-8, optional)\n</code></pre> <p>Example (hex):</p> <pre><code>01 00 00 00 00 00 00 00 6d 63 63 6c 69\n</code></pre> <p>Response: <code>PACKET_SELF_INFO</code> (0x05)</p>"},{"location":"companion_protocol/#2-device-query","title":"2. Device Query","text":"<p>Purpose: Query device information.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x16\nByte 1: Highest companion protocol version understood by the app\n</code></pre> <p>Example (hex):</p> <pre><code>16 0E\n</code></pre> <p>Response: <code>PACKET_DEVICE_INFO</code> (0x0D) with device information</p>"},{"location":"companion_protocol/#3-get-channel-info","title":"3. Get Channel Info","text":"<p>Purpose: Retrieve information about a specific channel.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x1F\nByte 1: Channel index (0 through max_channels - 1)\n</code></pre> <p>Example (get channel 1):</p> <pre><code>1F 01\n</code></pre> <p>Response: <code>PACKET_CHANNEL_INFO</code> (0x12) with channel details</p>"},{"location":"companion_protocol/#4-set-channel","title":"4. Set Channel","text":"<p>Purpose: Create or update a channel on the device.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x20\nByte 1: Channel index (0 through max_channels - 1)\nBytes 2-33: Channel Name (32 bytes, UTF-8, null-padded)\nBytes 34-49: Secret (16 bytes)\n</code></pre> <p>Total Length: 50 bytes</p> <p>Channel index: - Slot count is build-specific. Read <code>max_channels</code> from byte 3 of   <code>PACKET_DEVICE_INFO</code>; current profiles commonly expose 1, 8, or 40 slots. - No slot number has an intrinsic public/private meaning.</p> <p>Channel Name: - UTF-8 encoded - Maximum 32 bytes - Padded with null bytes (0x00) if shorter</p> <p>Secret Field (16 bytes): - Supply the exact 16-byte channel key. A private channel normally uses a   cryptographically random key; known public and hashtag channels use their   defined or derived key. - An all-zero key is not the public-channel key.</p> <p>Example (create channel \"SMS\" at index 1 with secret):</p> <pre><code>20 01 53 4D 53 00 00 ... (name padded to 32 bytes)\n    [16 bytes of secret]\n</code></pre> <p>Note: The 32-byte secret variant is unsupported and returns <code>PACKET_ERROR</code>.</p> <p>Response: <code>PACKET_OK</code> (0x00) on success, <code>PACKET_ERROR</code> (0x01) on failure</p>"},{"location":"companion_protocol/#5-send-channel-message","title":"5. Send Channel Message","text":"<p>Purpose: Send a text message to a channel.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x03\nByte 1: 0x00\nByte 2: Channel index (0 through max_channels - 1)\nBytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds)\nBytes 7+: Message Text (UTF-8, variable length)\n</code></pre> <p>Timestamp: Unix timestamp in seconds (32-bit unsigned integer, little-endian)</p> <p>Example (send \"Hello\" to channel 1 at timestamp 1234567890):</p> <pre><code>03 00 01 D2 02 96 49 48 65 6C 6C 6F\n</code></pre> <p>Response: <code>PACKET_MSG_SENT</code> (0x06) on success</p>"},{"location":"companion_protocol/#6-send-channel-data-datagram","title":"6. Send Channel Data Datagram","text":"<p>Purpose: Send a binary datagram to a channel. Unlike channel text messages, datagrams carry no built-in sender identity and no timestamp - applications needing either must encode them inside the binary payload.</p> <p>Command Format:</p> <pre><code>Byte 0:                         0x3E\nByte 1:                         Channel index (0 through max_channels - 1)\nByte 2:                         Encoded path descriptor (0xFF = flood)\nBytes 3+:                       Encoded path bytes (omitted for 0xFF)\nNext 2 bytes (little-endian):   Data Type (`data_type`, uint16)\nRemaining bytes:                Binary payload (variable length)\n</code></pre> <p>For a direct send, the descriptor's low six bits are the hash count and its high two bits are the hash size minus one. Current mesh packets accept one-, two-, or three-byte hashes; the four-byte code is reserved. The following path therefore occupies <code>hash_count * hash_size</code> bytes; the descriptor itself is not a raw byte count.</p> <p>Example (flood, <code>DATA_TYPE_DEV</code>, payload <code>A1 B2 C3</code>, channel 1):</p> <pre><code>3E 01 FF FF FF A1 B2 C3\n</code></pre> <p>Data Type / Transport Mapping: - <code>0x0000</code> (<code>DATA_TYPE_RESERVED</code>) is invalid and rejected with <code>PACKET_ERROR</code>. - <code>0xFFFF</code> (<code>DATA_TYPE_DEV</code>) is the developer namespace for experimenting and developing apps. - Registered application/community namespaces occupy <code>0x0100</code>-<code>0xFEFF</code>; the remaining nonzero ranges are reserved for internal or development use. See the Registered data_type values table below.</p> <p>Limits: - Maximum payload length is <code>MAX_GROUP_DATA_LENGTH = MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 3 = 165</code> bytes. - Larger payloads are rejected with <code>PACKET_ERROR</code> (<code>ERR_CODE_ILLEGAL_ARG</code>).</p> <p>Response: <code>PACKET_OK</code> (0x00) on success, or <code>PACKET_ERROR</code> (0x01) with one of: - <code>ERR_CODE_NOT_FOUND</code> (2) - unknown <code>channel_idx</code> - <code>ERR_CODE_ILLEGAL_ARG</code> (6) - invalid <code>path_len</code>, reserved <code>data_type</code> (<code>0x0000</code>), or payload larger than <code>MAX_GROUP_DATA_LENGTH</code> - <code>ERR_CODE_TABLE_FULL</code> (3) - outbound send queue is full; retry later</p> <p>Inbound datagrams are delivered to the host via <code>RESP_CODE_CHANNEL_DATA_RECV</code> (0x1B); see Receive Channel Data Datagram.</p>"},{"location":"companion_protocol/#registered-data_type-values","title":"Registered <code>data_type</code> values","text":"<p><code>data_type</code> is an application identifier, not a payload-format identifier. Each registered value identifies an application that owns its own internal payload schemas. The firmware does not inspect payload contents - <code>data_type</code> is transported opaquely.</p> Value Constant Purpose 0x0000 <code>DATA_TYPE_RESERVED</code> Reserved; invalid on send 0x0001 - 0x00FF - Reserved for internal use 0x0100 - 0xFEFF - Registered application namespaces (see number_allocations.md) 0xFF00 - 0xFFFE - Testing/development; no registration required 0xFFFF <code>DATA_TYPE_DEV</code> Developer/experimental namespace <p>To register a new application, submit a PR adding a row to the table in docs/number_allocations.md. Internal sub-formats within an allocated application ID are owned by that application and are not tracked in MeshCore firmware or this document.</p>"},{"location":"companion_protocol/#receive-channel-data-datagram","title":"Receive Channel Data Datagram","text":"<p>Inbound group datagrams (radio-level <code>PAYLOAD_TYPE_GRP_DATA</code>, 0x06) are forwarded to the host as <code>RESP_CODE_CHANNEL_DATA_RECV</code> notifications.</p> <p>Frame Format (<code>RESP_CODE_CHANNEL_DATA_RECV</code>, 0x1B):</p> <pre><code>Byte 0:                 0x1B (packet type)\nByte 1:                 SNR (signed int8, scaled x4 - divide by 4.0 to recover dB)\nBytes 2-3:              Reserved (clients MUST ignore)\nByte 4:                 Channel index (0 through max_channels - 1)\nByte 5:                 Path Length (actual path length when flooded, otherwise 0xFF for direct)\nBytes 6-7:              Data Type (uint16 little-endian)\nByte 8:                 Data Length\nBytes 9 .. 8+data_len:  Payload\n</code></pre> <p>Path bytes are not forwarded: Only <code>path_len</code> is reported in the receive frame - the path itself is not copied to the host. There are no path bytes between byte 5 and the data_type field at bytes 6-7, regardless of <code>path_len</code>.</p> <p>Path Length semantics differ between send and receive:</p> Direction <code>path_len = 0xFF</code> <code>path_len != 0xFF</code> Send Flood the network Direct route; the encoded path follows (low 6 bits = hash count, top 2 bits + 1 = hash size; on-wire byte count = <code>hash_count x hash_size</code>) Receive Packet arrived via direct route Packet was flooded; this is the encoded <code>pkt-&gt;path_len</code> field as observed (no path bytes follow) <p>In other words, the meaning of <code>0xFF</code> is inverted between the two directions, and on receive the field carries metadata only - never a routable path. <code>path_len</code> is an encoded byte (see <code>Packet::isValidPathLen</code> / <code>Packet::writePath</code> in <code>src/Packet.cpp</code>), not a raw byte count.</p> <p>Note: The device may also emit <code>PACKET_MESSAGES_WAITING</code> (0x83) to notify the host that datagrams are queued; poll with <code>CMD_SYNC_NEXT_MESSAGE</code> (0x0A) to retrieve them.</p> <p>Parsing Pseudocode:</p> <pre><code>def parse_channel_data_recv(data):\n    if len(data) &lt; 9:\n        return None\n    snr_byte = data[1]\n    snr = (snr_byte if snr_byte &lt; 128 else snr_byte - 256) / 4.0\n    channel_idx = data[4]\n    path_len = data[5]\n    data_type = int.from_bytes(data[6:8], 'little')\n    data_len = data[8]\n    if 9 + data_len &gt; len(data):\n        return None\n    payload = data[9:9 + data_len]\n    return {\n        'snr': snr,\n        'channel_idx': channel_idx,\n        'path_len': path_len,\n        'data_type': data_type,\n        'payload': bytes(payload),\n    }\n</code></pre>"},{"location":"companion_protocol/#7-get-message","title":"7. Get Message","text":"<p>Purpose: Request the next queued message from the device.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x0A\n</code></pre> <p>Example (hex):</p> <pre><code>0A\n</code></pre> <p>Response:  - <code>PACKET_CHANNEL_MSG_RECV</code> (0x08) or <code>PACKET_CHANNEL_MSG_RECV_V3</code> (0x11) for channel messages - <code>PACKET_CONTACT_MSG_RECV</code> (0x07) or <code>PACKET_CONTACT_MSG_RECV_V3</code> (0x10) for contact messages - <code>PACKET_CHANNEL_DATA_RECV</code> (0x1B) for channel data datagrams - <code>PACKET_NO_MORE_MSGS</code> (0x0A) if no messages available</p> <p>Note: Poll this command periodically to retrieve queued messages. The device may also send <code>PACKET_MESSAGES_WAITING</code> (0x83) as a notification when messages are available.</p>"},{"location":"companion_protocol/#8-get-battery-and-storage","title":"8. Get Battery and Storage","text":"<p>Purpose: Query device battery voltage and storage usage.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x14\n</code></pre> <p>Example (hex):</p> <pre><code>14\n</code></pre> <p>Response: <code>PACKET_BATTERY</code> (0x0C) with battery millivolts and storage information</p>"},{"location":"companion_protocol/#channel-management","title":"Channel Management","text":""},{"location":"companion_protocol/#channel-types","title":"Channel Types","text":"<ol> <li>Public Channel<ul> <li>Uses a publicly known 16-byte key: <code>8b3387e9c5cdea6ac9e5edbaa115cd72</code></li> <li>Anyone can join this channel, messages should be considered public</li> <li>Used as the default public group chat</li> </ul> </li> <li>Hashtag Channels<ul> <li>Uses a secret key derived from the channel name</li> <li>It is the first 16 bytes of <code>sha256(\"#test\")</code></li> <li>For example hashtag channel <code>#test</code> has the key: <code>9cd8fcf22a47333b591d96a2b848b73f</code></li> <li>Traffic is encrypted on air, but anyone who knows or guesses the channel   name can derive the key. Hashtag channels should not be treated as private.</li> <li>Used as a topic based public group chat, separate from the default public channel</li> </ul> </li> <li>Private Channels<ul> <li>Uses a randomly generated 16-byte secret key</li> <li>Messages should be considered private between those that know the secret</li> <li>Users should keep the key secret, and only share with those you want to communicate with</li> <li>Used as a secure private group chat</li> </ul> </li> </ol>"},{"location":"companion_protocol/#channel-lifecycle","title":"Channel Lifecycle","text":"<ol> <li>Set Channel:<ul> <li>Read <code>max_channels</code> from device info, fetch those slots, and choose an   unused slot (normally an empty name and zeroed key)</li> <li>Generate or provide a 16-byte secret</li> <li>Send <code>CMD_SET_CHANNEL</code> with name and a 16-byte secret</li> </ul> </li> <li>Get Channel:<ul> <li>Send <code>CMD_GET_CHANNEL</code> with channel index</li> <li>Parse <code>RESP_CODE_CHANNEL_INFO</code> response</li> </ul> </li> <li>Delete Channel:<ul> <li>Send <code>CMD_SET_CHANNEL</code> with empty name and all-zero secret</li> <li>Or overwrite with a new channel</li> </ul> </li> </ol>"},{"location":"companion_protocol/#message-handling","title":"Message Handling","text":""},{"location":"companion_protocol/#receiving-messages","title":"Receiving Messages","text":"<p>Messages are received via the TX characteristic (notifications). The device sends:</p> <ol> <li>Channel Messages:</li> <li><code>PACKET_CHANNEL_MSG_RECV</code> (0x08) - Standard format</li> <li> <p><code>PACKET_CHANNEL_MSG_RECV_V3</code> (0x11) - Version 3 with SNR</p> </li> <li> <p>Contact Messages:</p> </li> <li><code>PACKET_CONTACT_MSG_RECV</code> (0x07) - Standard format</li> <li> <p><code>PACKET_CONTACT_MSG_RECV_V3</code> (0x10) - Version 3 with SNR</p> </li> <li> <p>Notifications:</p> </li> <li><code>PACKET_MESSAGES_WAITING</code> (0x83) - Indicates messages are queued</li> </ol>"},{"location":"companion_protocol/#contact-message-format","title":"Contact Message Format","text":"<p>Standard Format (<code>PACKET_CONTACT_MSG_RECV</code>, 0x07):</p> <pre><code>Byte 0: 0x07 (packet type)\nBytes 1-6: Public Key Prefix (6 bytes, hex)\nByte 7: Path Length\nByte 8: Text Type\nBytes 9-12: Timestamp (32-bit little-endian)\nBytes 13-16: Signature (4 bytes, only if txt_type == 2)\nBytes 17+: Message Text (UTF-8)\n</code></pre> <p>V3 Format (<code>PACKET_CONTACT_MSG_RECV_V3</code>, 0x10):</p> <pre><code>Byte 0: 0x10 (packet type)\nByte 1: SNR (signed byte, multiplied by 4)\nBytes 2-3: Reserved\nBytes 4-9: Public Key Prefix (6 bytes, hex)\nByte 10: Path Length\nByte 11: Text Type\nBytes 12-15: Timestamp (32-bit little-endian)\nBytes 16-19: Signature (4 bytes, only if txt_type == 2)\nBytes 20+: Message Text (UTF-8)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_contact_message(data):\n    packet_type = data[0]\n    offset = 1\n\n    # Check for V3 format\n    if packet_type == 0x10:  # V3\n        snr_byte = data[offset]\n        snr = ((snr_byte if snr_byte &lt; 128 else snr_byte - 256) / 4.0)\n        offset += 3  # Skip SNR + reserved\n\n    pubkey_prefix = data[offset:offset+6].hex()\n    offset += 6\n\n    path_len = data[offset]\n    txt_type = data[offset + 1]\n    offset += 2\n\n    timestamp = int.from_bytes(data[offset:offset+4], 'little')\n    offset += 4\n\n    # If txt_type == 2, skip 4-byte signature\n    if txt_type == 2:\n        offset += 4\n\n    message = data[offset:].decode('utf-8')\n\n    return {\n        'pubkey_prefix': pubkey_prefix,\n        'path_len': path_len,\n        'txt_type': txt_type,\n        'timestamp': timestamp,\n        'message': message,\n        'snr': snr if packet_type == 0x10 else None\n    }\n</code></pre>"},{"location":"companion_protocol/#channel-message-format","title":"Channel Message Format","text":"<p>Standard Format (<code>PACKET_CHANNEL_MSG_RECV</code>, 0x08):</p> <pre><code>Byte 0: 0x08 (packet type)\nByte 1: Channel index (0 through max_channels - 1)\nByte 2: Path Length\nByte 3: Text Type\nBytes 4-7: Timestamp (32-bit little-endian)\nBytes 8+: Message Text (UTF-8)\n</code></pre> <p>V3 Format (<code>PACKET_CHANNEL_MSG_RECV_V3</code>, 0x11):</p> <pre><code>Byte 0: 0x11 (packet type)\nByte 1: SNR (signed byte, multiplied by 4)\nBytes 2-3: Reserved\nByte 4: Channel index (0 through max_channels - 1)\nByte 5: Path Length\nByte 6: Text Type\nBytes 7-10: Timestamp (32-bit little-endian)\nBytes 11+: Message Text (UTF-8)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_channel_message(data):\n    packet_type = data[0]\n    offset = 1\n\n    # Check for V3 format\n    if packet_type == 0x11:  # V3\n        snr_byte = data[offset]\n        snr = ((snr_byte if snr_byte &lt; 128 else snr_byte - 256) / 4.0)\n        offset += 3  # Skip SNR + reserved\n\n    channel_idx = data[offset]\n    path_len = data[offset + 1]\n    txt_type = data[offset + 2]\n    timestamp = int.from_bytes(data[offset+3:offset+7], 'little')\n    message = data[offset+7:].decode('utf-8')\n\n    return {\n        'channel_idx': channel_idx,\n        'timestamp': timestamp,\n        'message': message,\n        'snr': snr if packet_type == 0x11 else None\n    }\n</code></pre>"},{"location":"companion_protocol/#sending-messages","title":"Sending Messages","text":"<p>Use the <code>SEND_CHANNEL_MESSAGE</code> command (see Commands).</p> <p>Important:  - The shared text envelope permits up to 160 UTF-8 bytes. For channel text,   firmware prepends <code>&lt;sender name&gt;:</code> inside that envelope, so the available   message body is <code>160 - prefix_bytes</code> and varies with the configured name. - Count encoded UTF-8 bytes, not Unicode characters. Split a longer message at   valid UTF-8 boundaries. - Include a chunk indicator (e.g., \"[1/3] message text\")</p>"},{"location":"companion_protocol/#response-parsing","title":"Response Parsing","text":""},{"location":"companion_protocol/#terminology","title":"Terminology","text":"<p>This document uses a spec-level naming convention (<code>PACKET_*</code>) for bytes the firmware sends back to the host. In the firmware source these same values are split across two <code>#define</code> families by purpose:</p> <ul> <li><code>RESP_CODE_*</code> - direct replies to a command (e.g. <code>RESP_CODE_CHANNEL_DATA_RECV</code> = <code>PACKET_CHANNEL_DATA_RECV</code> = 0x1B).</li> <li><code>PUSH_CODE_*</code> - asynchronous notifications not tied to a specific command (e.g. <code>PUSH_CODE_MSG_WAITING</code> = <code>PACKET_MESSAGES_WAITING</code> = 0x83).</li> </ul> <p>Byte values are authoritative; names are aliases. When reading firmware source, <code>RESP_CODE_X</code> / <code>PUSH_CODE_X</code> correspond to this doc's <code>PACKET_X</code> of the same numeric value.</p>"},{"location":"companion_protocol/#response-types","title":"Response types","text":"Value Firmware name Description <code>0x00</code> <code>RESP_CODE_OK</code> Command succeeded. <code>0x01</code> <code>RESP_CODE_ERR</code> Command failed; byte 1 is the error code. <code>0x02</code> <code>RESP_CODE_CONTACTS_START</code> Contact enumeration started. <code>0x03</code> <code>RESP_CODE_CONTACT</code> One contact record. <code>0x04</code> <code>RESP_CODE_END_OF_CONTACTS</code> Contact enumeration ended. <code>0x05</code> <code>RESP_CODE_SELF_INFO</code> Device self-information. <code>0x06</code> <code>RESP_CODE_SENT</code> Send accepted, with route/tag/timeout data. <code>0x07</code> / <code>0x08</code> <code>RESP_CODE_CONTACT_MSG_RECV</code> / <code>RESP_CODE_CHANNEL_MSG_RECV</code> Queued legacy-format message. <code>0x09</code> <code>RESP_CODE_CURR_TIME</code> Current device time. <code>0x0A</code> <code>RESP_CODE_NO_MORE_MESSAGES</code> Offline queue is empty. <code>0x0B</code> <code>RESP_CODE_EXPORT_CONTACT</code> Exported contact bytes. <code>0x0C</code> <code>RESP_CODE_BATT_AND_STORAGE</code> Battery and storage values. <code>0x0D</code> <code>RESP_CODE_DEVICE_INFO</code> Protocol and build information. <code>0x0E</code> <code>RESP_CODE_PRIVATE_KEY</code> Exported identity key, when enabled. <code>0x0F</code> <code>RESP_CODE_DISABLED</code> Requested sensitive feature is disabled. <code>0x10</code> / <code>0x11</code> <code>RESP_CODE_CONTACT_MSG_RECV_V3</code> / <code>RESP_CODE_CHANNEL_MSG_RECV_V3</code> Queued message with SNR fields. <code>0x12</code> <code>RESP_CODE_CHANNEL_INFO</code> Channel slot information. <code>0x13</code> / <code>0x14</code> <code>RESP_CODE_SIGN_START</code> / <code>RESP_CODE_SIGNATURE</code> Signing capacity or completed signature. <code>0x15</code> <code>RESP_CODE_CUSTOM_VARS</code> Custom-variable data. <code>0x16</code> <code>RESP_CODE_ADVERT_PATH</code> Cached advertisement path. <code>0x17</code> <code>RESP_CODE_TUNING_PARAMS</code> Tuning parameters. <code>0x18</code> <code>RESP_CODE_STATS</code> Requested statistics subtype. <code>0x19</code> <code>RESP_CODE_AUTOADD_CONFIG</code> Automatic-contact policy. <code>0x1A</code> <code>RESP_ALLOWED_REPEAT_FREQ</code> Allowed repeat-frequency ranges. <code>0x1B</code> <code>RESP_CODE_CHANNEL_DATA_RECV</code> Queued channel datagram. <code>0x1C</code> <code>RESP_CODE_DEFAULT_FLOOD_SCOPE</code> Default flood-scope data. <code>0x1D</code> <code>RESP_CODE_CLI_REPLY</code> Text returned by <code>CMD_RUN_CLI_COMMAND</code>."},{"location":"companion_protocol/#asynchronous-push-types","title":"Asynchronous push types","text":"Value Firmware name Description <code>0x80</code> <code>PUSH_CODE_ADVERT</code> Advertisement received. <code>0x81</code> <code>PUSH_CODE_PATH_UPDATED</code> A contact path changed. <code>0x82</code> <code>PUSH_CODE_SEND_CONFIRMED</code> A sent message was acknowledged. <code>0x83</code> <code>PUSH_CODE_MSG_WAITING</code> One or more offline frames are waiting. <code>0x84</code> <code>PUSH_CODE_RAW_DATA</code> Raw application data received. <code>0x85</code> / <code>0x86</code> <code>PUSH_CODE_LOGIN_SUCCESS</code> / <code>PUSH_CODE_LOGIN_FAIL</code> Server login result. <code>0x87</code> <code>PUSH_CODE_STATUS_RESPONSE</code> Server status response. <code>0x88</code> <code>PUSH_CODE_LOG_RX_DATA</code> Radio receive log data. <code>0x89</code> <code>PUSH_CODE_TRACE_DATA</code> Completed trace data. <code>0x8A</code> <code>PUSH_CODE_NEW_ADVERT</code> Newly stored contact advertisement. <code>0x8B</code> <code>PUSH_CODE_TELEMETRY_RESPONSE</code> Telemetry response. <code>0x8C</code> <code>PUSH_CODE_BINARY_RESPONSE</code> Binary request response. <code>0x8D</code> <code>PUSH_CODE_PATH_DISCOVERY_RESPONSE</code> Path-discovery response. <code>0x8E</code> <code>PUSH_CODE_CONTROL_DATA</code> Control/discovery data. <code>0x8F</code> <code>PUSH_CODE_CONTACT_DELETED</code> Oldest contact was deleted while making room. <code>0x90</code> <code>PUSH_CODE_CONTACTS_FULL</code> Contact storage is full."},{"location":"companion_protocol/#parsing-responses","title":"Parsing Responses","text":"<p>PACKET_OK (0x00):</p> <pre><code>Byte 0: 0x00\nBytes 1-4: Optional value (32-bit little-endian integer)\n</code></pre> <p>PACKET_ERROR (0x01):</p> <pre><code>Byte 0: 0x01\nByte 1: Error code (optional)\n</code></pre> <p>PACKET_CHANNEL_INFO (0x12):</p> <pre><code>Byte 0: 0x12\nByte 1: Channel Index\nBytes 2-33: Channel Name (32 bytes, null-terminated)\nBytes 34-49: Secret (16 bytes)\n</code></pre> <p>Note: The device returns the 16-byte channel secret in this response.</p> <p>PACKET_DEVICE_INFO (0x0D):</p> <pre><code>Byte 0: 0x0D\nByte 1: Firmware Version (uint8)\nBytes 2+: Variable length based on firmware version\n\nFor firmware version &gt;= 3:\nByte 2: Max Contacts Raw (uint8, actual = value * 2)\nByte 3: Max Channels (uint8)\nBytes 4-7: Active BLE PIN (32-bit little-endian; includes a generated session PIN)\nBytes 8-19: Firmware Build (12 bytes, UTF-8, null-padded)\nBytes 20-59: Model (40 bytes, UTF-8, null-padded)\nBytes 60-79: Version (20 bytes, UTF-8, null-padded)\nByte 80: Client repeat enabled/preferred (firmware v9+)\nByte 81: Path hash mode (firmware v10+)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_device_info(data):\n    if len(data) &lt; 2:\n        return None\n\n    fw_ver = data[1]\n    info = {'fw_ver': fw_ver}\n\n    if fw_ver &gt;= 3 and len(data) &gt;= 80:\n        info['max_contacts'] = data[2] * 2\n        info['max_channels'] = data[3]\n        info['ble_pin'] = int.from_bytes(data[4:8], 'little')\n        info['fw_build'] = data[8:20].decode('utf-8').rstrip('\\x00').strip()\n        info['model'] = data[20:60].decode('utf-8').rstrip('\\x00').strip()\n        info['ver'] = data[60:80].decode('utf-8').rstrip('\\x00').strip()\n\n    if fw_ver &gt;= 9 and len(data) &gt;= 81:\n        info['client_repeat'] = data[80] != 0\n    if fw_ver &gt;= 10 and len(data) &gt;= 82:\n        info['path_hash_mode'] = data[81]\n\n    return info\n</code></pre> <p>PACKET_BATTERY (0x0C):</p> <pre><code>Byte 0: 0x0C\nBytes 1-2: Battery Voltage (16-bit little-endian, millivolts)\nBytes 3-6: Used Storage (32-bit little-endian, KB)\nBytes 7-10: Total Storage (32-bit little-endian, KB)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_battery(data):\n    if len(data) &lt; 3:\n        return None\n\n    mv = int.from_bytes(data[1:3], 'little')\n    info = {'battery_mv': mv}\n\n    if len(data) &gt;= 11:\n        info['used_kb'] = int.from_bytes(data[3:7], 'little')\n        info['total_kb'] = int.from_bytes(data[7:11], 'little')\n\n    return info\n</code></pre> <p>PACKET_SELF_INFO (0x05):</p> <pre><code>Byte 0: 0x05\nByte 1: Advertisement Type\nByte 2: TX Power\nByte 3: Max TX Power\nBytes 4-35: Public Key (32 bytes, hex)\nBytes 36-39: Advertisement Latitude (32-bit little-endian, divided by 1e6)\nBytes 40-43: Advertisement Longitude (32-bit little-endian, divided by 1e6)\nByte 44: Multi ACKs\nByte 45: Advertisement Location Policy\nByte 46: Telemetry Mode (bitfield)\nByte 47: Manual Add Contacts (bool)\nBytes 48-51: Radio Frequency (32-bit little-endian, divided by 1000.0)\nBytes 52-55: Radio Bandwidth (32-bit little-endian, divided by 1000.0)\nByte 56: Radio Spreading Factor\nByte 57: Radio Coding Rate\nBytes 58+: Device Name (UTF-8, variable length, no null terminator required)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_self_info(data):\n    if len(data) &lt; 36:\n        return None\n\n    offset = 1\n    info = {\n        'adv_type': data[offset],\n        'tx_power': data[offset + 1],\n        'max_tx_power': data[offset + 2],\n        'public_key': data[offset + 3:offset + 35].hex()\n    }\n    offset += 35\n\n    lat = int.from_bytes(data[offset:offset+4], 'little') / 1e6\n    lon = int.from_bytes(data[offset+4:offset+8], 'little') / 1e6\n    info['adv_lat'] = lat\n    info['adv_lon'] = lon\n    offset += 8\n\n    info['multi_acks'] = data[offset]\n    info['adv_loc_policy'] = data[offset + 1]\n    telemetry_mode = data[offset + 2]\n    info['telemetry_mode_env'] = (telemetry_mode &gt;&gt; 4) &amp; 0b11\n    info['telemetry_mode_loc'] = (telemetry_mode &gt;&gt; 2) &amp; 0b11\n    info['telemetry_mode_base'] = telemetry_mode &amp; 0b11\n    info['manual_add_contacts'] = data[offset + 3] &gt; 0\n    offset += 4\n\n    freq = int.from_bytes(data[offset:offset+4], 'little') / 1000.0\n    bw = int.from_bytes(data[offset+4:offset+8], 'little') / 1000.0\n    info['radio_freq'] = freq\n    info['radio_bw'] = bw\n    info['radio_sf'] = data[offset + 8]\n    info['radio_cr'] = data[offset + 9]\n    offset += 10\n\n    if offset &lt; len(data):\n        name_bytes = data[offset:]\n        info['name'] = name_bytes.decode('utf-8').rstrip('\\x00').strip()\n\n    return info\n</code></pre> <p>PACKET_MSG_SENT (0x06):</p> <pre><code>Byte 0: 0x06\nByte 1: Route Flag (0 = direct, 1 = flood)\nBytes 2-5: Tag / Expected ACK (4 bytes, little-endian)\nBytes 6-9: Suggested Timeout (32-bit little-endian, milliseconds)\n</code></pre> <p>PACKET_SEND_CONFIRMED (0x82):</p> <pre><code>Byte 0: 0x82\nBytes 1-4: ACK code (32-bit little-endian)\nBytes 5-8: Round-trip time (32-bit little-endian, milliseconds)\n</code></pre>"},{"location":"companion_protocol/#error-codes","title":"Error Codes","text":"<p><code>PACKET_ERROR</code> (0x01) carries a single-byte error code in byte 1. Values match the <code>ERR_CODE_*</code> constants defined in <code>examples/companion_radio/MyMesh.cpp</code>:</p> Code Constant (firmware) Description 1 <code>ERR_CODE_UNSUPPORTED_CMD</code> Unknown or unsupported command byte / sub-command 2 <code>ERR_CODE_NOT_FOUND</code> Target not found (channel, contact, message, etc.) 3 <code>ERR_CODE_TABLE_FULL</code> Internal queue or table is full - retry later 4 <code>ERR_CODE_BAD_STATE</code> Operation not valid in current device state (e.g. iterator already running) 5 <code>ERR_CODE_FILE_IO_ERROR</code> Filesystem or storage I/O failure 6 <code>ERR_CODE_ILLEGAL_ARG</code> Invalid argument (bad length, out-of-range value, reserved field, etc.) <p>Note: Error codes may vary by firmware version. Always check byte 1 of <code>PACKET_ERROR</code> response, and treat unknown codes as generic errors.</p>"},{"location":"companion_protocol/#frame-handling","title":"Frame Handling","text":"<p>BLE implementations enqueue and deliver one protocol frame per BLE write/notification at the firmware layer.</p> <ul> <li>Apps should treat each characteristic write/notification as exactly one companion protocol frame</li> <li>Apps should still validate frame lengths before parsing</li> <li>Future transports or firmware revisions may differ, so avoid assuming fixed payload sizes for variable-length responses</li> </ul>"},{"location":"companion_protocol/#response-handling","title":"Response Handling","text":"<ol> <li>Command-Response Pattern:</li> <li>Send command via RX characteristic</li> <li>Wait for response via TX characteristic (notification)</li> <li>Match the response by the expected response type; frames do not carry a      general command sequence number</li> <li>Handle timeout (typically 5 seconds)</li> <li> <p>Use command queue to prevent concurrent commands</p> </li> <li> <p>Asynchronous Messages:</p> </li> <li>Device may send messages at any time via TX characteristic</li> <li>Handle <code>PACKET_MESSAGES_WAITING</code> (0x83) by polling <code>GET_MESSAGE</code> command</li> <li>Parse incoming messages and route to appropriate handlers</li> <li> <p>Validate frame length before decoding</p> </li> <li> <p>Response Matching:</p> </li> <li> <p>Match responses to commands by expected packet type:</p> <ul> <li><code>APP_START</code> -&gt; <code>PACKET_SELF_INFO</code></li> <li><code>DEVICE_QUERY</code> -&gt; <code>PACKET_DEVICE_INFO</code></li> <li><code>GET_CHANNEL</code> -&gt; <code>PACKET_CHANNEL_INFO</code></li> <li><code>SET_CHANNEL</code> -&gt; <code>PACKET_OK</code> or <code>PACKET_ERROR</code></li> <li><code>SEND_CHANNEL_MESSAGE</code> -&gt; <code>PACKET_MSG_SENT</code></li> <li><code>GET_MESSAGE</code> -&gt; <code>PACKET_CHANNEL_MSG_RECV</code>, <code>PACKET_CONTACT_MSG_RECV</code>, <code>PACKET_CHANNEL_DATA_RECV</code>, or <code>PACKET_NO_MORE_MSGS</code></li> <li><code>SEND_CHANNEL_DATA</code> -&gt; <code>PACKET_OK</code> or <code>PACKET_ERROR</code></li> <li><code>GET_BATTERY</code> -&gt; <code>PACKET_BATTERY</code></li> </ul> </li> <li> <p>Timeout Handling:</p> </li> <li>Default timeout: 5 seconds per command</li> <li>On timeout: Log error, clear current command, proceed to next in queue</li> <li>Some commands may take longer (e.g., <code>SET_CHANNEL</code> may need 1-2 seconds)</li> <li> <p>Consider longer timeout for channel operations</p> </li> <li> <p>Error Recovery:</p> </li> <li>On <code>PACKET_ERROR</code>: Log error code, clear current command</li> <li>On connection loss: Clear command queue, attempt reconnection</li> <li>On invalid response: Log warning, clear current command, proceed</li> </ol>"},{"location":"companion_protocol/#example-implementation-flow","title":"Example Implementation Flow","text":""},{"location":"companion_protocol/#initialization","title":"Initialization","text":"<pre><code># 1. Scan for MeshCore device\ndevice = scan_for_device(\"MeshCore\")\n\n# 2. Connect to BLE GATT\ngatt = connect_to_device(device)\n\n# 3. Discover services and characteristics\nservice = discover_service(gatt, \"6E400001-B5A3-F393-E0A9-E50E24DCCA9E\")\nrx_char = discover_characteristic(service, \"6E400002-B5A3-F393-E0A9-E50E24DCCA9E\")\ntx_char = discover_characteristic(service, \"6E400003-B5A3-F393-E0A9-E50E24DCCA9E\")\n\n# 4. Enable notifications on TX characteristic\nenable_notifications(tx_char, on_notification_received)\n\n# 5. Send AppStart command\nsend_command(rx_char, build_app_start())\nwait_for_response(PACKET_SELF_INFO)\n</code></pre>"},{"location":"companion_protocol/#creating-a-private-channel","title":"Creating a Private Channel","text":"<pre><code># 1. Generate 16-byte secret\nsecret_16_bytes = generate_secret(16)  # Use CSPRNG\nsecret_hex = secret_16_bytes.hex()\n\n# 2. Build SET_CHANNEL command\nchannel_name = \"YourChannelName\"\nchannel_index = choose_unused_slot(max_channels)\ncommand = build_set_channel(channel_index, channel_name, secret_16_bytes)\n\n# 3. Send command\nsend_command(rx_char, command)\nresponse = wait_for_response(PACKET_OK)\n\n# 4. Store secret locally\nstore_channel_secret(channel_index, secret_hex)\n</code></pre>"},{"location":"companion_protocol/#sending-a-message","title":"Sending a Message","text":"<pre><code># 1. Build channel message command\nchannel_index = 1\nmessage = \"Hello, MeshCore!\"\ntimestamp = int(time.time())\ncommand = build_channel_message(channel_index, message, timestamp)\n\n# 2. Send command\nsend_command(rx_char, command)\nresponse = wait_for_response(PACKET_MSG_SENT)\n</code></pre>"},{"location":"companion_protocol/#receiving-messages_1","title":"Receiving Messages","text":"<pre><code>def on_notification_received(data):\n    packet_type = data[0]\n\n    if packet_type == PACKET_CHANNEL_MSG_RECV or packet_type == PACKET_CHANNEL_MSG_RECV_V3:\n        message = parse_channel_message(data)\n        handle_channel_message(message)\n    elif packet_type == PACKET_MESSAGES_WAITING:\n        # Poll for messages\n        send_command(rx_char, build_get_message())\n</code></pre>"},{"location":"companion_protocol/#best-practices","title":"Best Practices","text":"<ol> <li>Connection Management:</li> <li>Implement auto-reconnect with exponential backoff</li> <li>Handle disconnections gracefully</li> <li> <p>Store last connected device address for quick reconnection</p> </li> <li> <p>Secret Management:</p> </li> <li>Always use cryptographically secure random number generators</li> <li>Store secrets securely (encrypted storage)</li> <li> <p>Never log or transmit secrets in plain text</p> </li> <li> <p>Message Handling:</p> </li> <li>Send <code>CMD_SYNC_NEXT_MESSAGE</code> when <code>PUSH_CODE_MSG_WAITING</code> is received</li> <li> <p>Implement message deduplication to avoid displaying the same message twice</p> </li> <li> <p>Channel Management:</p> <ul> <li>Fetch all channel slots even if you encounter an empty slot</li> <li>Ideally save new channels into the first empty slot</li> </ul> </li> <li> <p>Error Handling:</p> </li> <li>Implement timeouts for all commands (typically 5 seconds)</li> <li>Handle <code>RESP_CODE_ERR</code> responses appropriately</li> </ol>"},{"location":"companion_protocol/#troubleshooting","title":"Troubleshooting","text":""},{"location":"companion_protocol/#connection-issues","title":"Connection Issues","text":"<ul> <li>Device not found: Ensure device is powered on and advertising</li> <li>Connection timeout: Check Bluetooth permissions and device proximity</li> <li>GATT errors: Ensure proper service/characteristic discovery</li> </ul>"},{"location":"companion_protocol/#command-issues","title":"Command Issues","text":"<ul> <li>No response: Verify notifications are enabled, check connection state</li> <li>Error responses: Verify command format and check error code</li> <li>Timeout: Increase timeout value or try again</li> </ul>"},{"location":"companion_protocol/#message-issues","title":"Message Issues","text":"<ul> <li>Messages not received: Poll <code>GET_MESSAGE</code> command periodically</li> <li>Duplicate messages: Implement message deduplication using timestamp/content as a unique id</li> <li>Message truncation: Send long messages as separate shorter messages</li> </ul>"},{"location":"companion_radio_full/","title":"Full Companion","text":"<p>For runtime on/off commands and board exceptions, see feature switches by role. Open the USB web console for the default ASCII terminal.</p> <p>For practical on/off commands and update directions, see Full Companion feature switches.</p> <p><code>companion_radio_full</code> combines every qualified Companion transport for its platform into one artifact and acts as a host-backed LoRa mOTA source for updating other nodes. Most targets can run those transports simultaneously; the SenseCAP Indicator exception selects one secondary wireless transport per boot as described below.</p> <p>The full Companion is deliberately not a LoRa OTA destination: it has no firmware staging store, refuses <code>ota install</code>, and never advertises its own firmware as an mOTA image.</p> <p>Preference changes through the Companion protocol, WebConfig, or USB terminal report a storage error if saving fails, and restore their previous values. Settings that also change GPS or radio power-saving state restore that state; a busy radio rollback remains pending for recovery instead of reporting success.</p> Capability ESP32 full nRF52 full USB Binary Companion Yes Yes BLE Binary Companion Yes Yes USB ASCII terminal Yes Yes Dedicated USB plaintext logging No - shares the one USB TTY Yes Host-backed LoRa mOTA source WiFi TCP 5001 Exclusive USB mode or encrypted BLE WiFi Companion/WebConfig Yes No - nRF52840 has no WiFi Hardware serial Companion On targets with assigned serial pins On targets with assigned serial pins Ethernet Companion On targets with an Ethernet module On RAK4631 with RAK13800 LoRa self-update No No Optional self-update WiFi on existing dual-app layouts; USB on single-app layouts Bluetooth DFU with a compatible bootloader; USB always supported"},{"location":"companion_radio_full/#sensecap-indicator-transport-and-rendering-exception","title":"SenseCAP Indicator transport and rendering exception","text":"<p>Both SenseCAP Indicator Full layouts keep USB available and start exactly one secondary wireless Companion transport per boot: BLE or infrastructure WiFi. The saved <code>companion.transport</code> selection takes effect after reboot. BLE mode does not start infrastructure WiFi, WebConfig, MQTT, TCP Companion, or network OTA services. WiFi mode never initializes BLE and releases its controller and host memory. LoRa remains the primary radio on the LoRa layout. ESP-NOW remains the primary mesh radio in both ESP-NOW modes, including BLE mode; only the infrastructure-WiFi services are omitted.</p> <p>The requested 4-bit internal render profiles are:</p> Primary radio Secondary Companion transport Canvas LoRa Infrastructure WiFi Native 480x480 LoRa BLE Native 480x480 ESP-NOW Infrastructure WiFi Native 480x480 ESP-NOW BLE 320x320, scaled 1.5x to the 480x480 panel <p>All four modes retain the same 160x160 logical UI. If a contiguous native DMA-capable block is unavailable, startup keeps the device usable with the 320x320 emergency fallback and reports the canvas actually retained. Such a fallback is not a successful native-480 validation result.</p>"},{"location":"companion_radio_full/#build-and-install","title":"Build and install","text":"<p>The target is synthesized by <code>build.sh</code> only for an exact board recipe that has passed the combined-transport size check:</p> <ul> <li>The normal automatic path requires matching WiFi, USB, and BLE recipes on   ESP32, or matching USB and BLE recipes on nRF52.</li> <li>A measured qualification list also promotes an exact BLE recipe when the   same board can safely add its platform's remaining transports. It never   substitutes the pin map or peripherals from another board.</li> </ul> <p>The measured ESP32 additions are M5Stack Unit C6L; XIAO C6/S3, Meshimi, WHY2025 Badge, LilyGo T-LoRa C6, T3S3 SX1262/SX1276, T-Deck, TETH Elite, classic T-Beam SX1262/SX1276, and T-Beam S3 Supreme; Heltec Wireless Tracker, Wireless Paper, E213, E290, T190, CT62, and V4 expansion-kit TFT; Generic ESP-NOW; SenseCAP Indicator ESP-NOW/LoRa; Ebyte EoRa-S3; and Meshadventurer SX1262/SX1268. The measured nRF52 additions are GAT562 Mesh Watch13, LilyGo T-Echo Lite, LilyGo T-Impulse Plus, and Wio Tracker L1 E-Ink. Their old transport-specific names remain available for explicit compatibility builds, but the Full image is the canonical release artifact.</p> <p>Every ESP32 Full image includes ordinary WiFi Companion, WebConfig, and the TCP mOTA services, even when its historical build base was USB- or BLE-only. On <code>Generic_ESPNOW</code> and <code>SenseCapIndicator-ESPNow</code>, ESP-NOW is also the primary mesh radio and shares the same 2.4 GHz hardware. Those two Full images retain B/G/N for ordinary clients alongside ESP-NOW LR. Their ESP-NOW mesh, setup AP, and infrastructure connection all use one persisted channel, which defaults to 1. Configure the router's 2.4 GHz radio and every other primary ESP-NOW node for that same fixed channel. Turning Companion WiFi off stops its TCP/AP services but deliberately leaves the ESP-NOW mesh radio running on the selected channel.</p> <p>Every ESP32 Full Companion with a station connection synchronizes its UTC clock from NTP after boot and explicitly refreshes it every 24 hours. The common WiFi path owns this for non-MQTT and runtime-unconfigured nodes; a configured MQTT bridge owns the same boot-and-daily schedule. Successful sync updates an attached hardware RTC as well as the ESP32 clock and suppresses LoRa clock fallback for that boot. Reconnecting WiFi preserves the existing daily deadline. A timeout leaves the existing clock and fallback intact and retries without blocking radio work.</p> <p>Inspect or change the shared channel from the Full Companion text terminal:</p> <pre><code>get espnow.channel\nset espnow.channel 6\nreboot\n</code></pre> <p>The accepted range is 1 through 13; use only a channel permitted in your region and supported by the router. The setter persists the selection, but the running radio stays on its current channel until reboot. Coordinate the change across every primary ESP-NOW node and the router before rebooting, or the node will lose one or both links. This primary-radio setting is not <code>bridge.channel</code>; that command belongs to the separate ESP-NOW bridge feature. To attach a LoRa-primary <code>*_repeater_bridge_espnow</code> gateway to these nodes, match its <code>bridge.channel</code> and select <code>set bridge.format raw</code>; the bridge's backward-compatible default is the distinct wrapped format. WiFi power saving cannot put infrastructure WiFi and ESP-NOW on different channels. On these two primary-ESP-NOW Full targets, <code>max</code> is unavailable because maximum modem sleep can make the station miss ESP-NOW broadcasts; use <code>min</code> for WiFi/BLE/ESP-NOW coexistence. The firmware also holds the ESP-IDF RF wake reference for the primary mesh radio, so the ESP-NOW receiver remains continuous even though the reported coexistence setting is <code>min</code>.</p> <p>List the available targets:</p> <pre><code>bash build.sh list | grep companion_radio_full\n</code></pre> <p>Build by using one exact listed name:</p> <pre><code>bash build.sh build-firmware heltec_v4_r8_companion_radio_full \\\n  --firmware-version v1.17.0\n\nbash build.sh build-firmware RAK_4631_companion_radio_full \\\n  --firmware-version v1.17.0\n</code></pre> <p>To build every canonical full Companion target, select the corresponding interactive menu item or run:</p> <pre><code>bash build.sh build-full-companion-firmwares \\\n  --firmware-version v1.17.0\n</code></pre> <p>Canonical Companion bulk builds also omit legacy <code>_ps</code> and <code>_femoff</code> aliases. Power saving and controllable FEM receive gain are persisted runtime settings; the old names remain available through an explicit <code>build-firmware</code> command for compatibility. Full Companion replaces separate USB, BLE, ordinary WiFi, hardware-serial, Ethernet Companion, Terminal Chat, and USB-only packet-logging release artifacts whenever the exact board supports those combined transports. Direct builds of the legacy targets remain available. RAK4631 repeater and room server Ethernet builds remain separate because they are different standalone roles, not Companion transports. nRF52 separates framed traffic and logs; ESP32 makes those modes mutually exclusive on its one USB TTY. In WebConfig, use the FEM RX boost switch. From the text terminal (USB, or TCP 5002 on ESP32), use:</p> <pre><code>get radio.rxgain\nset radio.rxgain off\nset radio.rxgain on\nget radio.fem.rxgain\nset radio.fem.rxgain off\nset radio.fem.rxgain on\nget radio.fem.txgain\nset radio.fem.txgain off\nset radio.fem.txgain on\n</code></pre> <p><code>radio.rxgain</code> controls the radio chip's boosted receive-gain mode; the FEM commands control the external receive and transmit paths. The selected states are applied immediately and retained after reboot. FEM TX gain is reported as unsupported on boards without software-selectable PA gain.</p> <p>SSD1306 display builds also persist a runtime orientation. This replaces the separate rotated Full Companion release image:</p> <pre><code>get display.rotation\nset display.rotation 90\nset display.rotation 180\nset display.rotation 270\nset display.rotation 0\n</code></pre> <p><code>0</code> resets the screen to that board's compiled default orientation.</p> <p>Heltec E290 and T190 now use their Full Companion artifacts for simultaneous USB, BLE, and WiFi. Their older <code>usb_ble</code>, USB-only, and BLE-only names remain available only as explicit compatibility builds.</p> <p>Heltec V3 and base OLED V4 Full Companion also include the former direct WiFi MQTT Companion capability. Configure and enable MQTT at runtime through WebConfig; the canonical release therefore publishes the Full image instead of a second <code>companion_radio_wifi_mqtt</code> image. V4 TFT and expansion-kit layouts remain separate hardware images because their display and I2C wiring differs.</p> <p>Device power saving is separate from LoRa RXPS. It can be changed in WebConfig with the Device power saving switch or from the text terminal:</p> <pre><code>get powersaving\nset powersaving on\nset powersaving off\n</code></pre> <p>On ESP32, WiFi modem power saving is a third independent setting. Select it in the WebConfig WiFi card, or use the Full Companion text terminal:</p> <pre><code>get wifi.ssid\nget wifi.status\nget wifi.powersave\nget webui\nset wifi.ssid MyNetwork\nset wifi.pwd my-password\nset wifi.powersave min\nset wifi.powersave max\nstart webconfig\nstop webconfig\n</code></pre> <p>ESP32 WiFi Companions with WebConfig, including Full Companion, expose a CLI tab at the node's LAN address. It defaults to on; use <code>get wifi.cli</code>, <code>set wifi.cli on</code>, or <code>set wifi.cli off</code>. Older builds that report the browser terminal as unavailable need a firmware update. The open setup AP does not expose this tab.</p> <p>The browser accepts Companion configuration commands, including <code>get powersaving</code>, <code>set usb.logging on|off</code>, WiFi controls, and MQTT settings. <code>set mqtt.enabled on|off</code> controls MQTT without erasing broker settings; <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, and <code>get mqtt.status</code> distinguish the saved switch from current connections. <code>set logging.output off|usb|wifi|both</code> selects both outputs together. The browser also uses the complete Companion terminal for <code>card</code>, <code>import meshcore://...</code>, <code>list</code>, <code>to</code>, <code>send</code>, <code>login</code>, <code>cmd</code>, and delayed replies, with the same syntax as USB and TCP port 5002. See the terminal command guide for contact import and session ownership. USB MOTA session commands require the USB connection; WiFi host folders use port 5001.</p> <p>On the two primary-ESP-NOW Full targets, the same terminal also provides <code>get espnow.channel</code> and <code>set espnow.channel &lt;1-13&gt;</code>. A channel change is persisted and requires a reboot, unlike a WiFi power-save change.</p> <p>SSID and password writes return their reply first, then restart the Companion WiFi station with the saved credentials. A TCP terminal therefore disconnects shortly after either write; reconnect to the IP reported by the new network. Password entry is masked over USB. <code>get wifi.pwd</code> reads the saved password from any local connection, including binary command <code>0x42</code>; LoRa cannot read it. It may be empty for an open network, an ordinary passphrase of up to 63 characters, or an exact 64-character hexadecimal WPA/WPA2 PSK. Other 64-character values and all longer values are rejected.</p> <p>The normal binary Companion connection can also read or write this setting over USB, BLE, or TCP port 5000 without entering terminal mode. The mode values are <code>0</code> for <code>min</code>, <code>1</code> for <code>none</code>, and <code>2</code> for <code>max</code>; see the Companion protocol. A Full Companion that runs WiFi and BLE simultaneously rejects <code>none</code> because coexistence requires modem sleep. A primary-ESP-NOW Full target also rejects <code>max</code>; unlike infrastructure traffic, peer ESP-NOW broadcasts cannot be buffered by the access point while the station sleeps. If an older image saved a conflicting value, firmware applies and reports <code>min</code> instead. The SenseCAP Indicator uses the active-mode constraints in the exception above: LoRa + WiFi accepts all three values, ESP-NOW + WiFi accepts <code>none|min</code>, LoRa + BLE accepts <code>min|max</code> for the inactive WiFi setting, and ESP-NOW + BLE requires <code>min</code>. Fresh Cascade builds select <code>min</code>, and an existing valid saved selection takes precedence.</p> <p>On radios with RX duty-cycle support, WebConfig and the text terminal also expose the persisted RXPS setting:</p> <pre><code>get radio.rxps\nset radio.rxps off\nset radio.rxps on\nset radio.rxps level 8 preamble 16\nset radio.rxps 65625 60000\n</code></pre> <p>Fresh Cascade-profile Full Companion builds start with RXPS on at level 8 and a 16-symbol preamble. Changing it takes effect immediately and remains selected after reboot.</p> <p>Companion firmware defaults device power saving to on. Version 1.17.1.2 also turns it on once when upgrading an older Companion preference file, including one written by the short-lived default-off regression. After that one-time migration, an explicit <code>set powersaving off</code> selection remains persistent.</p> <p>On ESP32, enabling it lowers the CPU clock to 80 MHz, enables idle yielding, and enables the configured GPS duty cycle. Disabling it restores the normal CPU clock and keeps GPS awake. Active Full Companion transports remain available in both states; on the SenseCAP Indicator this means USB plus the selected BLE or infrastructure-WiFi secondary transport. WiFi modem sleep stays enabled when BLE and the ESP32 WiFi radio are active together because coexistence requires it. Changing device power saving does not overwrite the saved WiFi power-save mode. While a native-USB host is enumerated, the platform sleep attempt is held off so USB CDC remains responsive; detaching the host releases that guard. CPU, radio-modem, and GPS power-saving settings remain active, and USB power from a charger alone does not create a Companion session. The selected state is retained after reboot.</p> <p>On the LilyGo T-Beam 1W Full Companion, press the physical <code>BOOT</code> button once to turn the ESP32 WiFi radio and all WiFi services off or on. The screen confirms <code>WiFi: OFF</code> or <code>WiFi: ON</code>, and the selected state is retained after reboot. When WiFi is off, TCP ports 5000-5002, WebConfig, and MQTT are stopped; USB, BLE, the display, GPS, and LoRa continue to operate. Press BOOT again to restore WiFi, including the saved station or setup-AP mode. On boot, BLE starts two seconds after WiFi/WebConfig so their peak startup allocations do not overlap.</p> <p>Artifacts are written to <code>out/</code> by default.</p> <p>Full Companion behavior is selected with independent capability macros for TempRadio, the OTA CLI, the TCP terminal, USB folder seeding, and memory diagnostics. The legacy <code>COMPANION_RADIO_FULL</code> flag remains an input for older target recipes, but application behavior no longer uses that umbrella as an unrelated compile guard. In particular, ESP32 WiFi/WebConfig terminal controls are compiled from their actual WiFi/WebConfig capability. On targets that run ESP32 WiFi and BLE simultaneously, BLE is started first to avoid heap fragmentation. The SenseCAP Indicator starts only its selected secondary transport. Compile-time prerequisite checks reject inconsistent feature flags. After linking, the capability sidecar verifies USB, BLE, the OTA CLI, TempRadio, and each platform's host-folder transport; it also verifies the TCP terminal, WebConfig, and WiFi seeder on ESP32, plus dedicated logging on nRF52.</p> <p>On 4 MB ESP32 boards, the full target uses a single 3 MB application partition so WiFi, BLE, WebConfig, and source-only mOTA fit in one artifact. The T-Beam 1W Full Companion uses that same LilyGo factory-compatible boot layout on its 16 MB flash because this source-only role does not install updates into a second app slot. Flash the generated <code>-merged.bin</code> when first installing this partition layout. Other boards with 8 MB or more retain dual application partitions. Heltec V2 and TLora V2 use 100 contacts, 8 group channels, and a 16-frame offline queue in this combined profile because of internal DRAM limits. Meshadventurer SX1262 and SX1268 use 100 contacts, 30 group channels, and a 16-frame queue. These capacities preserve the required 8 KiB static internal-DRAM reserve alongside MOTA and all Full transports; their ordinary transport-specific images retain 160 contacts, 40 channels, and 128 queued frames.</p> <p>The 1.17.1.5 memory replacements for Generic ESP-NOW, Heltec Wireless Paper, Wireless Tracker, CT62, V3, Tracker V2, and XIAO C3 Full Companion use 150 contacts and retain their 256-frame queue and Full transports. Export contacts before updating if you have more than 150; entries beyond the new limit may be unavailable and a later save may omit them.</p> <p>Full Companions normally retain 256 pending Companion message frames. ESP32 boards with configured PSRAM retain 512 and allocate that queue from PSRAM before WiFi and BLE start. If PSRAM is unavailable at runtime, allocation falls back through 256 and 128 frames, then to a 16-frame internal buffer. The Full Companion startup memory line reports the capacity actually allocated as <code>offline_queue=&lt;frames&gt;</code>. The queue is volatile and shared by all channels and direct messages; it is not flash-backed history. See Companion offline message queue for all platform defaults and full-queue behavior.</p> <p>Every corrected nRF52 Full profile keeps 256 offline frames normally and temporarily lends 128 slots to mOTA to leave room for Bluetooth tasks, displays and UI allocations. Queue sharing preserves the board's contacts, channels, and USB/Bluetooth mOTA sending. See the memory correction.</p> <p>The nRF52 target inherits the board's ordinary USB Companion installation format and adds BLE plus the serial mOTA source. It does not enable an SD cache or any other board-specific storage behavior; host files are streamed as they are requested. Its image is bounded by the board's normal application region, not the smaller OTAFIX in-place workspace reserved for firmware that can update itself.</p>"},{"location":"companion_radio_full/#interfaces","title":"Interfaces","text":"Platform Interface Purpose Both USB, 115200 baud ASCII after boot or observable USB session reset; automatically switches on the first complete Binary Companion frame Both BLE Binary Companion; display builds show a random session PIN, while headless builds default to <code>123456</code> ESP32 TCP 5000 Binary Companion over WiFi ESP32 HTTP 80 Companion WebConfig and first-boot WiFi setup ESP32 TCP 5001 Host <code>.mota</code> folder from <code>motatool serve --tcp</code> ESP32 TCP 5002 Full Companion text terminal; same role commands as the USB terminal nRF52 USB mOTA mode Host <code>.mota</code> folder from <code>motatool serve --serial</code> nRF52 Encrypted BLE mOTA service Paired phone/tablet/Linux host <code>.mota</code> catalog <p>Delivery-required replies are returned only to the interface which supplied the latest command. A contact-list stream keeps that route locked from <code>CONTACTS_START</code> through <code>END_OF_CONTACTS</code>; commands waiting on another interface are read after the stream finishes. Best-effort asynchronous observations such as adverts remain broadcast so passive clients can refresh their views. Companion session state is device-wide, so use one active Companion application at a time. On nRF52, BLE remains available while USB is in terminal or mOTA mode.</p> <p>On WiFi TCP port 5000, reconnecting from the same IP retains queued outgoing frames. A different IP takes over immediately, but never receives the previous IP's replies: up to four queued frames are parked separately for 30 seconds from takeover. The old IP can reconnect within that window to retrieve them. Only one displaced IP's backlog is retained; if another client also needs that slot, the older backlog is discarded so the new connection is not delayed. This reuses an existing fixed buffer instead of allocating additional frame storage. Pending commands, signing sessions, and contact streams belonging to the displaced WiFi session are canceled immediately; already accepted radio message transmissions are not canceled. Queued frames are retained, not a resumable command session, and IP matching is not authentication. Turning WiFi off clears both queues. Stored message history is unaffected.</p> <p>Ethernet also retains complete queued frames for the same IP. Unlike WiFi, it has no spare backlog buffer: a different IP cancels the old owner's pending operations and discards its queued frames before the new socket is exposed. This keeps Ethernet's existing four-frame memory limit. On both transports, a live same-IP replacement preserves pending operations; an observed disconnect, disabled transport, or rejected input cancels them. Already queued frames can still be replayed on a same-IP reconnect, but canceled operations are not resumed.</p> <p>Partial TCP writes retain the unsent bytes without interleaving later frames. After a reconnect, an incomplete frame restarts from its header; the new TCP connection must not receive only the old connection's trailing bytes.</p> <p>Binary WiFi/Ethernet frames must declare 1\u2013176 payload bytes. Illegal lengths close the connection immediately, without waiting for the announced body or executing a truncated command. An incomplete binary header or payload has a five-second deadline once reception starts; reconnect to send a fresh frame. Ethernet raw-line terminal input has no typing deadline, but an overlong line also closes the connection instead of executing its prefix.</p> <p>USB Binary output is queued as complete length-prefixed frames. Temporary CDC or UART backpressure pauses the contact stream; a frame may drain through a smaller hardware FIFO in ordered chunks, but its remainder is retained and no later frame can interleave with it or cause it to be discarded.</p> <p>When a BLE client requests pairing, a display-equipped build wakes the screen, switches to the first home page, and keeps the active six-digit PIN visible until Bluetooth connects or the two-minute pairing window expires. USB, WiFi, Ethernet, and hardware-serial connections do not suppress this screen. With no saved BLE PIN, display builds generate a new PIN at boot; builds without a physical display use <code>123456</code>. A PIN saved through the Companion protocol takes effect after reboot.</p> <p>The Bluetooth device name is independently configurable. In the text terminal, use <code>get bluetooth.name</code> and <code>set bluetooth.name &lt;name&gt;</code>; use <code>set bluetooth.name default</code> to restore <code>MeshCore-&lt;node name&gt;</code>. The WebConfig Node card exposes the same optional field on Bluetooth-capable ESP32 builds. Custom names replace the complete Bluetooth label rather than inheriting the prefix, accept up to 31 valid UTF-8 bytes, and take effect after reboot. This does not change the node's mesh advertisement name.</p> <p>Every Bluetooth Companion also supports <code>get bluetooth.mac</code> and <code>set bluetooth.mac &lt;address|random|random-every-boot|random-after-connect|default&gt;</code>. A literal address is a BLE random-static identity, <code>random</code> creates one persistent identity, <code>random-every-boot</code> rotates it on startup, and <code>random-after-connect</code> rotates it on the first boot after an authenticated connection while leaving unused boots unchanged. <code>default</code> (or <code>clear</code>) restores the chipset address. None of these values changes the stealth flag. Reboot and re-pair after changing modes or after a rotation. Address rotation clears stale local bonds. On nRF52 this affects the MeshCore application only, not the OTAFIX bootloader's separate BLE DFU identity.</p> <p><code>get bluetooth.stealth</code> and <code>set bluetooth.stealth on|off</code> control an independent flag, defaulting to off. Combine it with a custom address or <code>random</code> to retain the address and bond across boots. With stealth on, normal discovery ends after the first authenticated pairing and only the saved peer may reconnect. Rotating MAC policies still rotate and reopen first pairing when they do; stealth remains enabled. Repeating <code>on</code> keeps an existing bond. Toggle <code>off</code>, then <code>on</code>, then reboot to reset first pairing. All flag changes need reboot. The node still sends directed or allowlisted BLE packets; it is not radio silent.</p> <p>ESP32 ports 5000, 5001, 5002, and WebConfig have no independent login layer. Expose them only on a trusted LAN or temporary setup network. See WiFi setup for credential setup and reconnect behavior.</p>"},{"location":"companion_radio_full/#usb-binary-and-text-terminal-modes","title":"USB Binary and text terminal modes","text":"<p>Full Companion USB starts in the ASCII terminal after boot or an observable USB session reset. MeshCore apps and <code>meshcli</code> send a <code>&lt;</code>-prefixed framed command, which automatically hands the untouched frame to the Binary Companion parser:</p> <pre><code>meshcli -s /dev/ttyACM0 -b 115200 ver\n</code></pre> <p>The automatic probe runs only at an empty prompt. A complete frame confirms binary mode; an incomplete probe returns to ASCII after one second. Binary mode then remains selected until an observable USB session reset, reboot, or the explicit terminal start token. See Full Companion USB CLI and binary switcher for the byte-level state machine, logging and mOTA ownership, recovery paths, and known limitations.</p> <p>Immediately after boot, an ordinary terminal can issue ASCII commands without a start token. If the device is already in Binary Companion mode, open the port with the terminal start token sent automatically:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre> <p>The input map prevents any Binary Companion control bytes received during the mode transition from changing the local terminal's character set or display state while leaving UTF-8 emoji intact. The banner confirms that terminal mode is active; do not enter the start token again after it appears.</p> <p>The terminal supports Companion chat commands, including <code>channels</code>, <code>channel &lt;name-or-slot&gt; &lt;message&gt;</code>, remote administration with <code>login &lt;admin-password&gt;</code> and <code>cmd &lt;remote-command&gt;</code>, and routed <code>trace [recipient-name-or-prefix]</code>, plus local <code>ota</code>, <code>tempradio</code>, and <code>normalradio</code> controls. <code>board</code> reports the exact hardware target. ESP32 Full Companion also provides <code>memory</code>, which reports heap, internal allocation, PSRAM, and offline-queue usage; it is omitted from non-ESP32 help. ESP32 builds also provide local WiFi credential, status, WebConfig, and power-save controls. Every Full Companion provides persistent <code>get/set usb.logging</code> and starts with logging off on a fresh installation.</p>"},{"location":"companion_radio_full/#esp32-single-usb-serial-port","title":"ESP32 single USB serial port","text":"<p>Every ESP32 Full Companion exposes one USB TTY with two exclusive modes. It starts as the ASCII terminal unless a saved logging-on preference boots directly into the logging terminal. If it is already binary, enter its text terminal with <code>+++MESHCORE-TERM-START</code>. For an ESP32 1.17.1.5 USB logging session, run these separate commands:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>The first command is the release's USB power-saving workaround. The same TTY then emits plaintext packet/debug logs and continues accepting CLI commands, including <code>set usb.logging off</code>. Framed Binary Companion is unavailable on USB while logging owns the TTY. Turning logging off sends the command reply, stops the logs, and leaves that TTY in the normal ASCII terminal, matching a fresh Full installation. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch it to Binary Companion afterward. A saved logging-on preference boots directly into this input-capable logging terminal. BLE and Wi-Fi Companion remain available while USB is logging on simultaneous targets. On the SenseCAP Indicator, only the selected BLE or Wi-Fi Companion transport remains available alongside the logging terminal.</p> <p>ESP32 Full Companion uses the repository's Arduino-ESP32 2.x platform base where the board supports it. RC32 and ESP32-C6 retain their board-required Arduino 3.x platform, but follow the same one-TTY policy. No ESP32 Full image creates an optional second CDC interface. The single-TTY behavior applies to native-USB ESP32-S3 boards and boards using a USB-UART bridge.</p>"},{"location":"companion_radio_full/#nrf52-dual-usb-serial-ports","title":"nRF52 dual USB serial ports","text":"<p>Current nRF52 Full Companion firmware can expose two CDC ACM serial interfaces on one physical USB cable:</p> <ul> <li>USB interface <code>00</code> is the primary Companion, text-terminal, and serial-mOTA   source port. It is always present, starts in ASCII after boot, and   automatically hands a complete <code>&lt;</code> frame to Binary Companion.</li> <li>USB interface <code>02</code> is the optional write-only plaintext packet/debug logging   port. Host input on this interface is ignored and cannot invoke firmware   commands.</li> </ul> <p>A fresh Full Companion starts with USB logging off and therefore enumerates only interface <code>00</code>. Use <code>set usb.logging on</code> to save logging on; the reply says that a reboot is required. Use <code>set usb.logging on reboot</code> to save it and have the node reboot automatically after the reply. The second interface appears after that reboot. Likewise, <code>set usb.logging off reboot</code> removes interface <code>02</code>. The optional <code>reboot</code> word is accepted only in these exact command forms and triggers a reboot only when the descriptor actually needs to change.</p> <p>These are Full Companion text-terminal commands. The superficially similar <code>meshcli ... get usb.logging</code> command uses the Binary Companion parameter registry and can report <code>Unknown var usb.logging</code>; it does not forward that line to the text terminal. Enter terminal mode on interface <code>00</code> with the <code>+++MESHCORE-TERM-START</code> token as described above, then issue the command.</p> <p>When logging is on, Linux normally shows two <code>/dev/ttyACM*</code> devices. Match the stable <code>/dev/serial/by-id/*-if00</code> and <code>*-if02</code> links, or use a udev rule matching <code>ID_USB_INTERFACE_NUM</code>, rather than assuming which tty number is assigned. On Windows they appear as two COM ports; identify them by USB interface instead of depending on a particular COM number. The nRF52 bootloader temporarily exposes its normal DFU serial interface during an update.</p> <p>Opening the nRF52 logging port prints <code>MeshCore USB logging port</code> followed by its portable identity, <code>USB CDC 1; interface 02; Linux stable suffix: -if02</code>. <code>get usb.logging</code> reports the same endpoint. Firmware cannot print the exact <code>/dev/ttyACM*</code> or <code>COM*</code> name because Linux, macOS, or Windows assigns that name after USB enumeration; use the <code>*-if02</code> link on Linux to obtain the exact path. For example, <code>readlink -f /dev/serial/by-id/*-if02</code> prints the host-assigned <code>/dev/ttyACM*</code> name.</p> <p>Every ESP32-S3 Full Companion image uses DIO flash mode, including the RAK3112 and RC32 profiles. The S3 ROM supports DIO while loading the software bootloader, and some flash configurations fail before the application starts when a merged image inherits QIO. DIO trades some maximum flash-read throughput for compatibility; it does not change a board's PSRAM type or any ordinary non-Full firmware profile.</p> <p>On nRF52, point MeshCore Companion software, <code>meshcli</code>, and <code>motatool</code> at interface <code>00</code>. When enabled and rebooted, point a plaintext reader or USB-connected MQTT service at interface <code>02</code>. On ESP32, use its only USB TTY for Binary Companion while logging is off, or for the plaintext CLI/logger while logging is on; close one consumer before switching modes. Turning logging off returns to ASCII, so the normal stop token or a valid framed probe is still required before Binary Companion owns the port.</p> <p>ESP32 Full Companion exposes this same text terminal on TCP port 5002. Connect with <code>nc DEVICE_IP 5002</code>; no USB control token is needed. USB terminal mode and the TCP terminal share recipient, login, command, trace, and display state, so only one may own the terminal at a time. The idle startup USB prompt yields to a TCP connection when no USB data client or partial command is present, and is restored when TCP disconnects. An active USB session rejects TCP; entering USB terminal mode later closes an active TCP session. On USB-Serial-JTAG and USB-to-UART hardware, the firmware cannot observe an idle host open, so actual buffered USB activity\u2014not the physical cable alone\u2014claims ownership. Disconnecting TCP clears pending terminal-only state without cancelling Binary Companion delivery or radio retries.</p> <p>Both terminal transports accept <code>reboot</code>. The reply is sent first and the device reboots one second later, so a script can distinguish an accepted reboot from an abruptly lost connection.</p> <p>Port 5002 is plaintext and has no device-local login gate. A remote-admin password entered with <code>login</code> is sent across the LAN connection as typed even though the terminal does not echo it. Use port 5002 only on a trusted LAN or a temporary setup network.</p> <p>For example:</p> <pre><code>channels\nchannel #rgdata Hello from Eugene \ud83d\udc4b\nshow\nshow channels on\nto Hilltop Repeater\npath A1B2C3,D4E5F6\npath 7773D0 7E7662\nlogin my-admin-password\ncmd ver\ntrace\n</code></pre> <p>The terminal <code>list [n]</code> command displays favorite contacts first and orders each favorite/non-favorite group by its most recent advertisement. This does not alter the binary Companion contact-list protocol.</p> <p>Unsolicited terminal output starts in a quiet mode: advertisements and ordinary channel messages are hidden, while <code>#emergency</code> messages remain visible. Use <code>show adverts on|off</code>, <code>show channels on|off</code>, and <code>show emergency on|off</code> to control each category independently; plain <code>show</code> reports their state. These runtime filters affect terminal printing only and reset to their defaults after reboot.</p> <p>The <code>to</code> command selects the remote-administration target. <code>path</code> shows its saved outgoing route; <code>path direct</code>, <code>path clear</code>, or a list separated by spaces, commas, or both changes the route used by subsequent <code>login</code>, <code>send</code>, and <code>cmd</code> commands. Every hop must use the same 2-, 4-, or 6-digit hexadecimal width. Login passwords are masked during entry and limited by the radio protocol to 15 UTF-8 bytes. Wait for the asynchronous login result before using <code>cmd</code>; command replies appear as <code>CLI -&gt; from &lt;name&gt;</code> and use a response window of 300% of the route estimate. <code>DIRECT via path &lt;hop,...&gt;</code> displays the exact saved prefixes copied into the packet. Remote ACL permissions determine which commands the target accepts. The matching reply reports its round-trip time from local queueing through result reception, including radio transit and remote execution. Only one terminal <code>cmd</code> can be pending at a time.</p> <p>Incoming unicast replies are labeled <code>ROUTED</code>. Their exact return prefixes are not available at the destination because each forwarder consumes its prefix; use <code>trace</code> to verify the return route.</p> <p>With no argument, <code>trace</code> uses the current <code>to</code> recipient. A name-prefix argument traces that contact directly without changing the current recipient. The contact must already have a known direct path; results show the SNR at each hop, or a timeout if the round trip does not return.</p> <p>An explicit route can use 1-, 2-, or 4-byte hexadecimal prefixes. Spaces, commas, and mixed separators are accepted:</p> <pre><code>trace path 1 12 34 56 34 12\ntrace path 2 1234,ABCD,5678,ABCD,1234\ntrace path 4 12345678, ABCDEF01 89ABCDEF, ABCDEF01,12345678\n</code></pre> <p>The entered route must include both the outward and return prefixes. Exact three-byte traces are not supported.</p> <p>Return to Binary mode with:</p> <pre><code>+++MESHCORE-TERM-STOP\n</code></pre> <p>An observable USB session reset restores ASCII, including after a Binary client disconnects. Native USB with DTR can detect a terminal closing; ESP32 hardware USB Serial/JTAG detects bus resets and physical host loss. UART bridges usually cannot report a terminal closing, so use the start token if they remain in Binary mode. A different baud rate, including 57600, does not select ASCII.</p> <p>On an ESP32 Full Companion built with <code>OTA_FOLDER_SERIAL</code>, <code>motatool</code> can keep the USB serial port open as an mOTA folder source when WiFi is unavailable:</p> <pre><code>motatool serve --serial /dev/ttyACM0 --dir ./motas -v\n</code></pre> <p>The tool sends the exact completed <code>ota folder on</code> line when it opens the port. Firmware recognizes it in startup ASCII or idle Binary Companion mode, then transfers the port to exclusive USB mOTA ownership before binary request/reply frames begin. The text terminal and Binary Companion are unavailable on that TTY until <code>motatool</code> detaches the folder. This matches the nRF52 ownership behavior described below. TCP port 5001 remains the preferred unattended source transport.</p>"},{"location":"companion_radio_full/#nrf52-usb-mota-mode","title":"nRF52 USB mOTA mode","text":"<p>The nRF52 full target has a third, exclusive USB mode for the host folder. Unmodified <code>motatool serve --serial</code> sends <code>ota folder on</code> when it opens the port. The startup ASCII terminal recognizes that exact completed line, leaves terminal mode, and gives the stream directly to exclusive mOTA handling. If the port is already in Binary Companion mode, the idle binary parser recognizes the same control sequence. The sequence is not examined inside a framed Binary Companion packet. See the switcher guide for the ownership transitions.</p> <p>While mOTA mode owns USB:</p> <ul> <li>mOTA manifests and blocks stream from the computer on demand.</li> <li>USB Binary and the USB text terminal are unavailable.</li> <li>BLE Binary Companion remains available.</li> <li><code>motatool</code> sending <code>ota folder off</code>, or disconnecting the USB data session,   detaches the folder and restores Binary mode.</li> </ul> <p>No modified <code>motatool</code> build, terminal token, or preliminary mode change is required.</p>"},{"location":"companion_radio_full/#nrf52-bluetooth-mota-source","title":"nRF52 Bluetooth mOTA source","text":"<p>Protocol v14 also lets a phone, tablet, or Bluetooth-capable Linux host feed the <code>.mota</code> catalog to an nRF52 Full Companion. Normal Companion commands stay on the Nordic UART service. Firmware data uses a separate GATT service, so binary app traffic cannot be mistaken for a firmware block.</p> <p>The client must pair with the Companion PIN, subscribe to the mOTA Device Request characteristic, and send <code>CMD_BLE_MOTA_SOURCE</code> action <code>start</code> over the normal Binary Companion connection. The source is available only while that encrypted MITM-authenticated connection remains active. Disconnecting, unsubscribing, overflowing a frame, or receiving malformed data automatically detaches the catalog. USB and BLE source modes are mutually exclusive.</p> <p>The included Raspberry Pi reference client validates each <code>.mota</code> with <code>motatool</code>, schedules the local TempRadio window, serves until interrupted, then detaches and restores the normal radio tuple:</p> <pre><code>python3 tools/ble_mota/ble_mota_seeder.py \\\n  --device MeshCore-MyCompanion \\\n  --dir ./motas \\\n  --local 'tempradio 909.950,250,5,5,120'\n</code></pre> <p>Prefer this relative <code>tempradio</code> form when the phone/Pi and radio clocks may disagree. It starts a duration on the Companion and does not compare their wall clocks. Use the absolute <code>tempradioat</code> scheduler only after synchronizing the participating nodes.</p> <p>Use <code>--pair</code> when the Linux host has not already bonded. BlueZ must have an agent capable of entering or confirming the six-digit PIN. Use <code>--source status</code> without <code>--dir</code> for a read-only channel/status check. The complete UUID, frame, action, and status definitions are in the Companion protocol.</p> <p>This reference process stands in for the phone application. A mobile app can use the same sequence while retaining its normal contact and Repeater Admin UI: log in to the destination, put each required node on the same bounded TempRadio tuple, start the local Bluetooth catalog, then send the normal remote <code>ota ls</code>, <code>ota pull</code>, and <code>ota install</code> commands. The destination still checks container geometry, hardware identity, hashes, signature policy, and the OTAFIX bootloader before installation.</p>"},{"location":"companion_radio_full/#serve-mota-images-manually","title":"Serve mOTA images manually","text":"<p>First put the destination, required relays, controller, and source on the same bounded TempRadio tuple. The example frequency below is not legal everywhere; choose a legal tuple supported by every participating radio.</p>"},{"location":"companion_radio_full/#esp32-source","title":"ESP32 source","text":"<p>Use the local console to start TempRadio:</p> <pre><code>nc 192.168.1.50 5002\n</code></pre> <pre><code>tempradio 909.950,250,5,5,120\nota status\n</code></pre> <p>Then start the dedicated TCP seeder:</p> <pre><code>motatool serve --dir ./motas --tcp 192.168.1.50:5001 -v\n</code></pre>"},{"location":"companion_radio_full/#nrf52-source","title":"nRF52 source","text":"<p>Use the USB terminal briefly to schedule TempRadio, then return to Binary mode and close the terminal:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM1\n</code></pre> <pre><code>tempradio 909.950,250,5,5,120\n+++MESHCORE-TERM-STOP\n</code></pre> <p>After sending the stop token, exit <code>picocom</code> with Ctrl-A, Ctrl-X.</p> <p>Start the serial seeder on that same port:</p> <pre><code>motatool serve --dir ./motas --serial /dev/ttyACM1 --baud 115200 -v\n</code></pre> <p><code>motatool</code> switches the port into mOTA mode automatically. Stop it with Ctrl-C to detach the folder. Reopen the terminal and use <code>normalradio</code> if the source should return early; otherwise the saved radio settings return when the bounded window expires.</p> <p>As a cable-free alternative, keep the normal Companion BLE session open and run the Bluetooth reference client shown in the nRF52 Bluetooth section. Do not run the USB seeder at the same time.</p> <p>Both platforms intentionally refuse firmware installation commands such as:</p> <pre><code>ota pull &lt;id&gt; flash\nota install\nota dev ...\n</code></pre>"},{"location":"companion_radio_full/#script-a-complete-update","title":"Script a complete update","text":"<p>The Bash and PowerShell wrappers accept a release ZIP or ready <code>.mota</code>, set up TempRadio, run <code>motatool</code>, monitor the exact image, install it on the destination, and restore the radio path. Use a separate Companion as the controller.</p> <p>For an ESP32 full source:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='target-admin-password'\n\n./tools/lora_ota/lora_ota.sh ./release.zip \"Roof Node\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.50:5001 \\\n  --source-cli-tcp 192.168.1.50:5002\n</code></pre> <p>For an nRF52 full source, the script automatically detects the token-switched terminal and uses the same source port sequentially for control and seeding:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='target-admin-password'\n\n./tools/lora_ota/lora_ota.sh ./release.zip \"Roof Node\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <pre><code>$env:MESHCORE_ADMIN_PASSWORD = 'target-admin-password'\n\n&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.zip' 'Roof Node' `\n  --controller-serial COM7 `\n  --source-serial COM8\n</code></pre> <p>See the start-to-finish LoRa OTA guide for package selection, nRF52 in-place deltas, relays, trust checks, and recovery behavior.</p>"},{"location":"companion_usb_ascii_validation/","title":"USB Companion ASCII default validation","text":"<p>The updated 1.17.1.6 Companion release covers 103 USB-enabled profiles: 52 ESP32 Full, 43 nRF52 Full, four RP2040 USB, and four STM32 USB. The BLE-only WM1110 image has no USB interface and is outside this change.</p>"},{"location":"companion_usb_ascii_validation/#behavior-and-cause","title":"Behavior and cause","text":"<p>Ordinary USB Companions previously started in Binary mode. Full Companions started in ASCII, but host-session cleanup could select or retain Binary mode for the next connection.</p> <p>All USB Companions now select ASCII before framed dispatch begins. An observable USB session boundary cancels old USB operations and clears partial input, queued protocol output, frame ownership, and mOTA attachment before restoring ASCII. A network terminal can defer that restoration; a new USB binary client that connects during the deferral keeps its chosen mode. BLE and network Companion transports keep their existing binary protocol.</p> <p>A complete framed app command still selects Binary mode automatically. An incomplete initial probe returns to ASCII after one second. Explicit terminal start/stop controls remain available.</p> <p>Session detection depends on the hardware. Native USB with DTR can detect a terminal closing. ESP32 hardware USB Serial/JTAG observes bus resets and host loss, but cannot reliably observe a program closing its handle. UART bridges usually cannot observe that close either. Idle time never forces an active binary app back into ASCII; use the start token on a port that remains Binary. See the USB mode guide.</p>"},{"location":"companion_usb_ascii_validation/#automated-validation","title":"Automated validation","text":"<ul> <li>The real firmware startup and reset functions are compiled and executed for   nRF52, ESP32 TinyUSB, ESP32 hardware USB, and RP2040, with and without the   Full macro. Cases include reconnecting from Binary or ASCII, delayed cleanup,   mOTA cancellation, network ownership, and a new binary client during deferral.</li> <li>55 native serial-mode/flow-control tests and 11 terminal-session/diagnostic   tests passed locally, along with 49 USB Python tests and the picker tests.</li> <li>STM32 number formatting is tested against an Arduino API without <code>ltoa</code>.   CI also compiles an ordinary RAK 3x72 USB Companion with the real core and   RadioLib, so missing packages and GPIO API incompatibilities fail the build.</li> </ul> <p>The 99 ESP32/nRF52/RP2040 profiles use <code>d4a641ff</code>. The four STM32 profiles additionally use the compatible Arduino 2.12 platform pin and build test in <code>d2c52e4d</code>. Both source revisions passed GitHub checks: main repair and STM32 repair.</p> <p>All 103 builds passed capability and RAM qualification. Packaging checks bind each application to its capability and memory manifests, retain the original profile capabilities and download formats, and verify ESP32 application/merged image consistency. Replacement publication verifies public SHA-256 digests before deleting old images and checks that unrelated firmware assets retain their original hashes. Release manifests, checksum lists, picker links, and capacity-note source references follow the new binaries.</p> <p>Publication completed with all 430 uploaded files verified through their public download URLs. The 412 superseded firmware/manifest files were removed. The remaining 1,837 assets kept their original hashes, and all five release checksum lists matched the final GitHub asset digests.</p> <p>No USB Companion was attached to the local computer for this repair. These results are compilation and automated protocol tests, not physical USB tests across the board matrix.</p>"},{"location":"companion_usb_client_validation/","title":"USB Companion client compatibility","text":"<p>The RAK4631 report was reproduced on the MercerWoodMesh Pi with the published <code>RAK_4631_companion_radio_full-v1.17.1.6-halo-keymind-cascade-dev-d4a641ff</code> image. The fixes described here are in the source and test firmware; the existing GitHub release assets have not yet been replaced with this fix. Hardware validation was completed on 2026-09-14 with test builds labeled <code>v1.17.1.6-usb-client-test-0e5955f8</code> (base commit plus these USB fixes).</p>"},{"location":"companion_usb_client_validation/#port-selection","title":"Port selection","text":"Hardware Companion/ASCII port USB logging RAK4631 and other nRF52 Full Companions Primary CDC, Linux <code>*-if00</code> Optional second CDC, <code>*-if02</code> ESP32 Full Companions Primary USB serial port Shares that port; must be off for Binary Companion <p><code>+++MESHCORE-TERM-STOP</code> changes the primary port to Binary Companion. Its <code>OK - Binary mode</code> reply does not move the client to a second port. Close the terminal before opening that same port with <code>meshcli -s PORT infos</code>. Do not use MeshCLI's repeater-mode <code>-r</code> option for a binary Companion connection.</p>"},{"location":"companion_usb_client_validation/#two-reproduced-failures","title":"Two reproduced failures","text":"<ol> <li>Stock <code>meshcore-cli</code> 1.6.3 was tested with <code>meshcore</code> 2.3.10, whose serial client    deliberately deasserts DTR. The nRF52 primary USB gate and response route    both required DTR. A raw battery query returned a valid 14-byte response    with DTR high and no bytes with DTR low.</li> <li>The automatic ASCII banner ended in <code>&gt;</code>. MeshCLI recognized that <code>&gt;</code> as a    binary frame marker and consumed the real response's leading <code>&gt;</code> as a    length byte. Even forcing DTR high in a diagnostic client did not recover    the first <code>APP_START</code> response. Stock MeshCLI exited without node information.</li> </ol> <p>The nRF52 transport now accepts real USB input as evidence of a client, tagged with the current session generation. Close, line-coding, and device-reset events invalidate that evidence; an old reader racing cleanup cannot grant access to a newer session. The write path remains bounded and does not wait for an unread host. CDC1 logging retains its own DTR requirement.</p> <p>The default ASCII terminal now suppresses its banner and unsolicited terminal events until ASCII input arrives. Enter or a command reveals the terminal. A binary probe receives a clean first response. Explicit START/STOP remains available, and an incomplete binary probe still times out back to ASCII.</p> <p>On a shared logging port, STOP now reports <code>ERROR: set usb.logging off before Binary mode</code> while logging is enabled. It no longer acknowledges Binary mode and immediately reclaims the port for ASCII logging.</p>"},{"location":"companion_usb_client_validation/#hardware-validation","title":"Hardware validation","text":"<p>The RAK4631 Full test firmware passed with an unmodified installed MeshCLI and its normal DTR-low serial library:</p> <ul> <li>ASCII <code>ver</code> from the default mode, without START;</li> <li>explicit STOP acknowledgement followed by 10 binary battery queries;</li> <li>10 immediate close/reopen queries each with DTR low and high;</li> <li>10 stock-library reconnects and three separate <code>meshcli ... infos</code> runs;</li> <li>all of the above while the second CDC streamed logs: 598 bytes received,   no logging disconnections.</li> </ul> <p>The Heltec V4 Full Companion also passed using its ESP32-S3 USB Serial/JTAG interface, with USB logging disabled:</p> <ul> <li>default ASCII <code>ver</code>, then STOP and 10 clean binary battery replies;</li> <li>10 stock-library reconnects and three unmodified <code>meshcli ... infos</code> runs;</li> <li>a stock-client connection directly after reboot, without either mode token.</li> </ul> <p>The shared-port logging policy was exercised on the V4 as well. With logging on, STOP returned the explicit error, a binary probe could not claim the port, and stock MeshCLI could not connect. After <code>set usb.logging off</code>, STOP worked, 10 binary replies were clean, and three stock-client reconnects succeeded.</p> <p>After testing, the V4's complete original flash snapshot was restored and verified by the flasher. Its original <code>v1.17.1-soak-v4-B</code> firmware answered again, and the previously active memory-soak collector was restarted. This test interrupted that board's uptime; the restored firmware starts a new run. Fresh successful V4 telemetry was verified at <code>2026-09-14T19:46:01Z</code>. The RAK4631 remains on the patched Full Companion test build with its separate logging interface enabled. The Pi's previously active services were restored.</p> <p>The nRF52 DTR stress sequence is deliberately not used on ESP32. Changing those control lines during immediate close/reopen triggered the V4's hardware bootloader and produced an <code>ESP</code> boot message. Preselecting RTS before opening did not prevent that transition on this host. ESP32 reconnect results above use the unmodified client's normal connection sequence instead.</p> <p>The test issues local information queries only. It does not transmit test chat messages over LoRa. Firmware installation and logging configuration are separate from the reusable test runner:</p> <pre><code>python3 tools/hil/companion_usb_client.py \\\n  --port /dev/serial/by-id/PRIMARY-if00 \\\n  --logging-port /dev/serial/by-id/LOGGING-if02 \\\n  --test-dtr --cycles 10 --output usb-client-results.json\n</code></pre> <p>Replace the example paths with the device's actual stable paths. Install <code>meshcore-cli</code> in the Python environment used for the test. Start after a fresh reboot so the default-ASCII check has a new session. On ESP32, omit both <code>--logging-port</code> and <code>--test-dtr</code>, and disable USB logging first.</p>"},{"location":"companion_usb_client_validation/#automated-checks","title":"Automated checks","text":"<ul> <li>53 Python USB checks pass, including compiled execution of the real nRF52   callbacks and transport gate with DTR-low clients, cleanup races, early   input, line-coding changes, physical disconnects, full TX FIFO, CDC1 isolation,   and the 1200-baud bootloader entry.</li> <li>The real terminal methods are compiled for ordinary and Full modes to verify   that unsolicited text is suppressed before the first binary response.</li> <li>The actual STOP branch is exercised for logging off, shared-port logging on,   and dedicated-port logging on.</li> <li>63 native serial-switching, flow-control, and terminal-session tests pass.</li> <li>RAK4631 Full and Heltec V4 Full firmware compile and pass their packaged   capability checks.</li> </ul> <p>The USB workflow runs the new compiled regression tests on subsequent changes.</p>"},{"location":"docs/","title":"Local Documentation","text":"<p>This document explains how to build and view the MeshCore documentation locally.</p>"},{"location":"docs/#building-and-viewing-docs","title":"Building and viewing Docs","text":"<pre><code>pip install mkdocs\npip install mkdocs-material\n</code></pre> <ul> <li><code>mkdocs serve</code> - Start the live-reloading docs server.</li> <li><code>mkdocs build</code> - Build the documentation site.</li> </ul>"},{"location":"double_frequency_v4_validation/","title":"Double center-frequency write: V4 transmitter / XIAO receiver","text":"<p>2026-09-14. Completed bounded comparison: neither single nor duplicate frequency writes reached 400/400. The duplicate adds about 86 us per hop. No production default was changed. Both radios are idle with HIL installed; the duplicate-write toggle is off. The earlier descending-SF sweep and its follow-up remain paused; no new exhaustive settling sweep was launched.</p>"},{"location":"double_frequency_v4_validation/#hardware-and-control","title":"Hardware and control","text":"<ul> <li>RX: XIAO ESP32-S3/WIO SX1262, COM31, MAC 28:84:85:b4:09:80. Normal gain   register 0x94, unchanged-modulation cache enabled, buffered 8 MHz SPI.</li> <li>TX: newly connected Heltec V4, COM7, MAC 44:1b:f6:6a:e8:44. Hardware probe   found ESP32-S3, 2 MB embedded PSRAM and 16 MB flash. HIL detected KCT8103L   FEM and reported the amplified TX path; chip RX gain 0x96.</li> <li>User explicitly authorized erasing the V4 without backup. Its full flash   was erased and a verified HIL upload completed. XIAO's previous HIL image   was replaced with a verified same-image A/B-capable build. No private   backup contents were read; RAK and other boards were not touched.</li> <li>SF10/125 kHz, CR4/5, four centers 909.500/909.750/910.000/910.250 MHz,   5.1-symbol visits (41,780 us), 32-symbol TX preamble, zero added settling,   synthetic 16-byte packets, -9 dBm chip request. No extra IRQ polling.</li> </ul> <p>The V4 FEM uses the repository's production detection and TX/RX control. HIL restores RX after success or error on each direct transmit path. The GC1109 branch (not detected here) uses bypass according to GC1109 table 4. The detected KCT8103L uses its amplified path; antenna-port TX power was not measured. This is not a power-matched Indicator/V4 comparison.</p>"},{"location":"double_frequency_v4_validation/#exact-experiment","title":"Exact experiment","text":"<p><code>scanfreqrepeat 1</code> makes the HIL <code>ExperimentalSX1262</code> repeat the same SetRfFrequency (0x86) immediately after the first successful frequency call, before modulation, packet parameters and RX restart. The second call skips the image-calibration check, but keeps normal BUSY/status handling. Only an identified RX-to-RX hop may repeat; ordinary setup/TX does not. Either write's failure propagates through the existing failed profile-apply path. The toggle defaults off at reboot and cannot change during an active scan.</p> <p>Both modes use the same XIAO binary. Actual SPI command counts, not only software policy labels, are checked against one or two 0x86 writes per hop. The modulation cache remains on in both modes.</p>"},{"location":"double_frequency_v4_validation/#rx-only-timing","title":"RX-only timing","text":"<p>Six-second windows in single/double/double/single order, with reboot/clean setup between windows. No reference packets transmitted during this phase.</p> Frequency writes Hops Mean switch Actual 0x86 Actual 0x8B Single, first 142 451.965 us 142 0 Double, first 141 538.213 us 282 0 Double, second 141 538.170 us 282 0 Single, second 142 451.930 us 142 0 <p>Weighted means: 451.948 us single, 538.192 us double: +86.244 us / +19.1%. All 566 hops had zero retune, RX-mode and cache errors. Maximum observed switch costs were 594 us single and 674 us double; these are samples, not hard latency guarantees. Unheld full-cycle means were about 168.942 ms versus 169.285 ms.</p>"},{"location":"double_frequency_v4_validation/#packet-checks","title":"Packet checks","text":"<p>Single first, then double, each up to 100 packets/channel and stopping on its first miss; a 400/400 result would have stopped all RF testing. Neither passed.</p> Frequency writes Valid before first miss Failed packet RF-run mean switch Hops / 0x86 writes Single 1 2, channel 2 452.719 us 235 / 235 Double 4 5, channel 2 542.063 us 255 / 510 <p>Both failed packets were receiver timeouts, with TX success acknowledged, zero device-error flags and RX mode still active. Both settings reported zero retune, RX-mode, cache and RX errors. Ordinary processing after received packets caused one/four modulation rewrites respectively; pure RX-only timing above is the cleaner comparison of the duplicate cost.</p> <p>All five good V4 packets reported -19 dBm RSSI. SNR was +9.0 dB in the single-write sample and +8.2..+9.2 dB (mean +8.675 dB) for four double-write samples. The previous Indicator run had 547 good packets at average -40.547 dBm RSSI, +8.311 dB SNR. Thus this V4 setup was about 21.5 dB stronger as seen by the receiver. Hardware/antenna/placement/power differences remain confounded; neither the Indicator nor close-range effects are proven causes.</p> <p>One versus four successes before a miss is too small and stop-conditioned to establish a reliability improvement or packet-error rate. Repeating center frequency did not remove the observed failure at this setting. No results for lower SFs or added settling delays are claimed for the V4. A weaker received signal is needed before treating a transmitter swap as a clean comparison.</p>"},{"location":"double_frequency_v4_validation/#artifacts-and-checks","title":"Artifacts and checks","text":"<p>Base checkout <code>0e5955f889788a4317863e731b38ffe09e3d5441</code>, branch <code>keymindCascade</code>, plus local uncommitted changes. RadioLib 7.7.1 pinned at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both builds/uploads succeeded and uploader verified written data. The 59 selected host/native tests passed (39 collectors, ten profile, four SX1262, five radio and one receive-mode), including FEM restore on error and frequency-repeat scope/error propagation. Temporary build overlay removed.</p> <p>Actually loaded firmware SHA-256:</p> <ul> <li>XIAO: <code>9f82d86ea78cfa6bc03fef4925f10c918c8b9fc7a96a7d2b565a04bd2f281288</code></li> <li>V4: <code>2ea2ce37d9d66fb4f8ec9cf3cedfbe7d4eb6d08bfe9abe6c817e5afb04885636</code></li> </ul> <p>Raw evidence and byte-preserving SHA-256:</p> <ul> <li>RX-only ABBA:   <code>38ded968a60ff19f45618ec35d75ce46354d81f163879185e9d6ff0e68da3ae0</code></li> <li>Single-write packets:   <code>4cadeba0d22b3ec6158ff295f1becfb57fde7ef8bf7fabbdbc6295f274619557</code></li> <li>Double-write packets:   <code>46bea8d9c095847ef8ccf4a4ed51ab5404eb5bb87d9cf62b832c3298159d1525</code></li> </ul>"},{"location":"esp32_memory_budget/","title":"Classic ESP32 image memory budget","text":"<p>Classic ESP32 has 320 KiB of internal DRAM, but at most 160 KiB can hold statically allocated data. The remaining DRAM is available only through the runtime heap. Bluetooth, tracing, and SDK reservations further constrain the usable region. See Espressif's memory types documentation.</p> <p>An image can therefore approach its static limit while PlatformIO reports less than 40% of the 320 KiB total in use. PSRAM does not expand the region used by ordinary internal <code>.data</code> and <code>.bss</code> allocations.</p>"},{"location":"esp32_memory_budget/#build-enforcement","title":"Build enforcement","text":"<p>Every classic ESP32 environment inheriting <code>esp32_base</code> runs <code>scripts/check_esp32_dram.py</code>. The release builder also adds the script when an ESP32 profile replaces the inherited extra scripts. The check runs before image generation, merging, and uploading, including cached <code>nobuild</code> uploads. It requires the ELF and linker map to be present for those cached operations. The check script must load after <code>merge-bin.py</code> so the merge target retains its pre-action. A merge also requires the bootloader/partition flash layout; <code>nobuild</code> cannot create a bootable merged image when that layout is absent.</p> <p>The check reads <code>dram0_0_seg</code> from the final linker map. SDK reservations are already reflected in that region; Bluetooth's reservation is not subtracted a second time. The occupied span runs from the region origin to <code>_heap_start</code>, including <code>.data</code>, <code>.bss</code>, <code>.noinit</code>, and alignment gaps. The allowed region is the smaller of the linker's region and 160 KiB.</p> <p>Builds must leave at least 8 KiB free within that static region. This is an additional project margin against near-full images, not an Espressif hardware limit or a prediction of free heap. A profile may require a larger margin with <code>custom_esp32_static_dram_reserve</code> in bytes; values below 8192 are rejected. Missing or unrecognized map boundaries also fail the check.</p> <p>For the Heltec V2 build used to investigate the repeater report:</p> Shared repeater defaults Static span Static region Remaining Result Previous 255 scope slots 124,020 B 124,580 B 560 B Rejected Tuned 31 scope slots 108,308 B 124,580 B 16,272 B Passed <p>These measurements remove the board's existing scope-capacity override to exercise the shared defaults. The normal Heltec V2 profile already used 31 scope slots. Exact sizes vary with build flags and SDK versions.</p> <p>To inspect an existing classic ESP32 build:</p> <pre><code>python3 scripts/check_esp32_dram.py .pio/build/Heltec_v2_repeater/firmware.map\npython3 test/test_esp32_dram.py\n</code></pre> <p>ESP32-S2, S3, and C-series chips have different memory maps and do not inherit this classic ESP32 check.</p>"},{"location":"esp32_memory_budget/#boot-versus-running-memory","title":"Boot versus running memory","text":"<p>The build gate checks static placement needed to load and start the image. It never counts heap-only RAM toward that static budget. Allocations made with <code>new</code> or <code>malloc</code> in global constructors consume heap and are not included in the static span. Moving a table there changes its placement, not total RAM consumption.</p> <p>Successful build checks do not prove that every runtime configuration will boot. Hardware validation must still cover startup allocations and the enabled Wi-Fi/Bluetooth services, recording minimum free internal heap and the largest free internal block. Available heap changes during initialization; for example, the Arduino 2.x repeater releases unused Bluetooth controller RAM in <code>initArduino()</code>, after global constructors have run.</p>"},{"location":"esp32_wifi_partition_migration/","title":"ESP32 legacy-partition migration over Wi-Fi","text":"<p>The partition-migration bridge lets a supported ESP32 node move from a small dual-OTA layout to a verified larger dual-OTA layout without cable flashing. It is designed for inaccessible repeaters: the bridge itself fits a legacy 1.25 MiB slot, replaces the table from Wi-Fi, and then exposes Wi-Fi again for the full application image.</p> <p>It currently has explicit, byte-for-byte generated target plans for Arduino ESP32 <code>default_8MB.csv</code> and <code>default_16MB.csv</code>. It does not guess a table for other flash sizes. Adding a board later means adding one reviewed target plan and its generated table-prefix test; the bridge core is otherwise shared.</p> Flash size Target table app0 / app1 size Typical board 8 MiB <code>default_8MB.csv</code> 0x330000 / 0x330000 Seeed XIAO ESP32-S3 16 MiB <code>default_16MB.csv</code> 0x640000 / 0x640000 Heltec V4 / V4.3 OLED"},{"location":"esp32_wifi_partition_migration/#what-the-bridge-preserves","title":"What the bridge preserves","text":"<p>Before it touches the partition table, the bridge reads the historical <code>/identity/_main.id</code> SPIFFS file. It requires all 96 bytes (32-byte public key followed by its 64-byte private key), stages them in an NVS namespace that is unchanged by both target layouts, then changes the table. On the first boot with the expanded layout it writes the staged value into SPIFFS, reads it back byte-for-byte, and only then clears the NVS staging record and offers the final uploader.</p> <p>The private identity is the guaranteed preservation boundary. The old SPIFFS image is deliberately not raw-copied into an expanded partition: SPIFFS is not safe to resize that way. Other SPIFFS-backed settings can be recreated after the full image boots.</p>"},{"location":"esp32_wifi_partition_migration/#eligible-source-layout","title":"Eligible source layout","text":"<p>The bridge only accepts a source table that has all of the following:</p> <ul> <li>NVS at <code>0x9000</code>, size <code>0x5000</code>, and OTA metadata at <code>0xE000</code>, size <code>0x2000</code>.</li> <li>Two distinct, non-empty OTA application slots and a non-empty SPIFFS   partition, all inside the physical flash size.</li> <li>A known exact 8 MiB or 16 MiB physical flash capacity and a source table   different from that capacity's target table.</li> </ul> <p>This means the source app-slot and SPIFFS sizes can vary; the bridge validates the live geometry instead of carrying board-name rules. It also ensures it is running from one source OTA slot. If it arrived in B, it CRC-copies itself to the future A address, selects A in OTA metadata, writes the table, and restarts. It therefore works whether the browser OTA updater placed the bridge in legacy A or B.</p> <p>Keep power stable while the bridge is replacing the 4 KiB table sector. A loss of power before that point leaves the old table and source intact. After that small critical write, the selected A copy of the bridge is the recovery path.</p>"},{"location":"esp32_wifi_partition_migration/#build-and-migrate-a-seeed-xiao-esp32-s3","title":"Build and migrate a Seeed XIAO ESP32-S3","text":"<p>The production bridge is a legacy-slot application image:</p> <pre><code>&amp; \"$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe\" run -e xiao_s3_partition_migrator\n</code></pre> <p>Build the Full XIAO image with its 8 MiB table:</p> <pre><code>$env:MESHCORE_ESP32_FULL_BUILD = '1'\n&amp; \"$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe\" run -e Xiao_S3_WIO_repeater_observer_mqtt\n</code></pre> <p>Upload the bridge through the legacy node's existing Wi-Fi browser updater. Then join <code>MeshCore-Migrate</code> (password <code>meshcore-migrate</code>) and wait for Expanded layout ready. Upload the Full app-only <code>.bin</code> from the second build at <code>/update</code>. Do not upload an <code>-merged.bin</code>: merged images include bootloader and table offsets for cable flashing, not browser OTA.</p> <p><code>xiao_s3_partition_legacy_seed</code> is a disposable-hardware test image only. It models the legacy table and an identity file; it is not a deployable repeater.</p>"},{"location":"esp32_wifi_partition_migration/#heltec-v4-v43","title":"Heltec V4 / V4.3","text":"<p>Build <code>heltec_v4_partition_migrator</code>, upload it through the legacy Wi-Fi updater, then upload the Full V4 app-only image after the bridge reports ready. The 16 MiB target table creates two 6.25 MiB OTA slots. See the V4 build notes for its build command.</p>"},{"location":"espnow_bridge_setup/","title":"ESP-NOW bridge: simple setup","text":"<p>Use two ESP32 LoRa boards to join two MeshCore networks with different radio settings. Each board repeats on its own LoRa network, and the boards exchange packets directly over 2.4 GHz ESP-NOW. No router, internet connection, or manual peer pairing is needed.</p> <pre><code>LoRa network A &lt;--&gt; Repeater A &lt;-- ESP-NOW --&gt; Repeater B &lt;--&gt; LoRa network B\n</code></pre>"},{"location":"espnow_bridge_setup/#1-choose-the-firmware","title":"1. Choose the firmware","text":"<p>Install the exact board's Full ESP-NOW bridge repeater image on each board. The target name ends in <code>_repeater_bridge_espnow</code>; a standard Heltec V4 uses <code>heltec_v4_repeater_bridge_espnow</code>. Full/MQTT and Full Companion images are different choices. See the firmware picker guide.</p> <p>Open each board's USB console at 115200 baud and run:</p> <pre><code>get bridge.type\n</code></pre> <p>The answer must be <code>espnow</code>. <code>mqtt</code>, <code>rs232</code>, or <code>none</code> means that image does not provide the ESP-NOW bridge described here.</p>"},{"location":"espnow_bridge_setup/#2-set-each-boards-lora-network","title":"2. Set each board's LoRa network","text":"<p>Configure one board at a time over USB. Replace the placeholders below with the radio settings used by the network on that board's side. Use <code>Bridge-A</code> for the first board and <code>Bridge-B</code> for the second, or choose your own names.</p> <pre><code>set bridge.enabled off\nset name Bridge-A\nset radio &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;\nreboot\n</code></pre> <p>Do not type the angle-bracket placeholders literally.</p> Radio option Meaning <code>freq</code> LoRa frequency in MHz. Match the local network on this side. <code>bw</code> LoRa bandwidth in kHz. Match that network's bandwidth. <code>sf</code> Spreading factor, 5-12. Match that network's setting. <code>cr</code> Coding-rate value, 5-8. Match that network's setting. <code>name</code> A label to tell the two repeaters apart. It does not pair them. <p><code>set radio</code> requires a reboot to apply. After reconnecting, <code>get radio</code> shows the saved settings. Use permanent radio settings for this setup; <code>tempradio</code> sessions expire.</p>"},{"location":"espnow_bridge_setup/#3-configure-the-esp-now-link-on-both-boards","title":"3. Configure the ESP-NOW link on both boards","text":"<p>Run this block on both boards. Replace <code>YourSharedKey</code> with the same case-sensitive secret on each board, using 1-15 characters. Channel <code>6</code> is an example; both boards must use the same channel.</p> <pre><code>set bridge.enabled off\nset bridge.channel 6\nset bridge.format wrapped\nset bridge.secret YourSharedKey\nset bridge.source tx\nset bridge.delay 500\nset repeat on\nset bridge.enabled on\n</code></pre> <p>These settings are saved across reboot. Bridge changes apply immediately; changing an enabled bridge's channel, format, or secret restarts the bridge. Stopping it first lets you finish configuring both sides before connecting them.</p>"},{"location":"espnow_bridge_setup/#what-each-bridge-option-does","title":"What each bridge option does","text":"Option Choices and purpose <code>bridge.enabled</code> <code>on</code> starts the bridge; <code>off</code> stops it and keeps its saved settings. <code>bridge.channel</code> The 2.4 GHz channel, 1-13. Match it on both boards. This is separate from the LoRa frequency in <code>set radio</code>. <code>bridge.format</code> <code>wrapped</code> is the default for this two-repeater setup and uses the shared secret. <code>raw</code> connects to primary-ESP-NOW nodes such as <code>Generic_ESPNOW</code> or <code>SenseCapIndicator-ESPNow</code>; it ignores the secret. Both peers must use compatible formats. <code>bridge.secret</code> A matching, case-sensitive value of 1-15 characters for <code>wrapped</code> mode. It separates bridge groups; it is not strong encryption. MeshCore's own message encryption remains in place. <code>bridge.source</code> <code>tx</code> crosses packets this repeater transmits on LoRa, after its forwarding decisions; use this for the setup above. <code>rx</code> crosses received packets before those decisions and can pass traffic the local repeater would not forward. <code>bridge.delay</code> Wait before processing a packet received from the other bridge, in milliseconds. Range: 0-10000. Start with the default <code>500</code>. <code>repeat</code> <code>on</code> enables normal LoRa forwarding; <code>off</code> disables forwarding. Keep it <code>on</code> on both bridge repeaters. Normal routing, scope, and packet-filter rules still apply. <code>bridge.type</code> Read-only firmware capability. It must report <code>espnow</code> for this guide. <code>bridge.running</code> Read-only runtime state. <code>on</code> means the local bridge started; it does not prove the other board is reachable. <p>This fork uses <code>set bridge.source tx</code> or <code>rx</code>. Some upstream guides use <code>logTx</code> and <code>logRx</code>; those are not the command values used here.</p> <p>For a LoRa gateway connected to primary-ESP-NOW Companions instead of another LoRa repeater, see raw ESP-NOW compatibility.</p>"},{"location":"espnow_bridge_setup/#4-check-the-link","title":"4. Check the link","text":"<p>Run on both boards:</p> <pre><code>get bridge.enabled\nget bridge.running\nget bridge.channel\nget bridge.format\nget bridge.secret\nget bridge.source\nget bridge.delay\nget repeat\nget radio\n</code></pre> <p>Expected: enabled and running <code>on</code>, matching channel/format/secret, source <code>tx</code>, delay <code>500</code>, repeat <code>on</code>, and the intended LoRa settings on each side.</p> <p>Send a message from a Companion on network A to one on network B, then reply from B to A. Check both directions; configuration readback alone does not test delivery.</p> <p>If it does not work:</p> <ul> <li>Commands are unavailable: check <code>get bridge.type</code> and the firmware choice.</li> <li>Enabled is on but running is off: initialization failed. Reboot and   check again; ensure another WiFi service is not occupying the radio.</li> <li>Both are running but traffic does not cross: compare channel, format,   and secret; confirm each board's LoRa settings were applied with a reboot,   and check the networks' forwarding and scope rules.</li> </ul> <p>A running bridge keeps the device awake, even with device power saving enabled. For every command's full details, see the bridge CLI reference.</p> <p>For a broader comparison with a Linux-based bridge, see the MeshCore Nexus bridging guide.</p>"},{"location":"espnow_bridge_setup/#keep-wardriving-traffic-off-the-bridge","title":"Keep wardriving traffic off the bridge","text":"<p>New generalized repeater filter tables include a third built-in rule that blocks authenticated <code>#wardriving</code> text and data in both bridge directions, at every hop count. The same row blocks crossover between radio profiles:</p> <pre><code>get flood.rule.3\nset flood.rule type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>The same rule can be added with the shorter command:</p> <pre><code>set fr any c=#wardriving m=bc d\n</code></pre> <p>Both forms use the same table. <code>m=b</code> means bridge only, <code>m=c</code> means crossover only, and <code>get fr.N</code> returns a short command for copying a numbered rule.</p> <p>The unnumbered command adds the rule safely on existing devices whose saved tables predate this default. It works with either bridge packet source and both ESP-NOW formats. Nearby same-profile LoRa forwarding retains the separate four-hop default. Use <code>mode=bridge</code> for a bridge-only block, or <code>mode=cross</code> for a crossover-only block. See the mode matrix and examples.</p>"},{"location":"faq/","title":"Frequently Asked Questions","text":"<p>For this fork's 1.17.1.5 USA Cascade release, start with feature switches by role and the USB web console. For nRF52 OTAFIX use the exact board/storage build from OTAFIX 2.4.6; older bootloader links below provide upstream/background context.</p> <p>A list of frequently-asked questions and answers for MeshCore</p> <ul> <li>Frequently Asked Questions</li> <li>1. Introduction<ul> <li>1.1. Q: What is MeshCore?</li> <li>1.2. Q: What do you need to start using MeshCore?<ul> <li>1.2.1. Hardware</li> <li>1.2.2. Firmware</li> <li>1.2.3. Companion Radio Firmware</li> <li>1.2.4. Repeater</li> <li>1.2.5. Room Server</li> </ul> </li> </ul> </li> <li>2. Initial Setup<ul> <li>2.1. Q: How many devices do I need to start using MeshCore?</li> <li>2.2. Q: Does MeshCore cost any money?</li> <li>2.3. Q: What frequencies are supported by MeshCore?</li> <li>2.4. Q: What is an \"advert\" in MeshCore?</li> <li>2.5. Q: Is there a hop limit?</li> </ul> </li> <li>3. Server Administration<ul> <li>3.1. Q: How do you configure a repeater or a room server?</li> <li>3.2. Q: Do I need to set the location for a repeater?</li> <li>3.3. Q: What is the password to administer a repeater or a room server?</li> <li>3.4. Q: What is the password to join a room server?</li> <li>3.5. Q: Can I retrieve a repeater's private key or set a repeater's private key?</li> <li>3.6. Q: The first byte of my repeater's public key collides with an existing repeater on the mesh. How do I get a new private key with a matching public key that has its first byte of my choosing?</li> <li>3.7. Q: My repeater may be suffering from deafness due to high power interference near my mesh's frequency, it is not hearing other in-range MeshCore radios. What can I do?</li> <li>3.8. Q: How do I make my repeater an observer on the mesh?</li> <li>3.9. Q: What is multibyte support? What do 1-byte, 2-byte, 3-byte adverts and messages mean?</li> <li>3.9.1. Q: What path hash sizes will my repeater forward?</li> <li>3.9.2. Q: What determines a packet's path hash size?</li> <li>3.9.3. Q: How do I change my companion's path hash size?</li> <li>3.9.4. Q: What does the CLI command <code>path.hash.mode</code> do on a repeater?</li> <li>3.9.5. Q: Why use 2- or 3-byte path hash for adverts?</li> <li>3.9.6. Q: When can we move away from 1-byte path hash for channel and direct messages?</li> </ul> </li> <li>4. T-Deck Related<ul> <li>4.1. Q: Is there a user guide for T-Deck, T-Pager, T-Watch, or T-Display Pro?</li> <li>4.2. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode?</li> <li>4.3. Q: Why is my T-Deck Plus not getting any satellite lock?</li> <li>4.4. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock?</li> <li>4.5. Q: What size of SD card does the T-Deck support?</li> <li>4.6. Q: What is the public key for the default public channel?</li> <li>4.7. Q: How do I get maps on T-Deck?</li> <li>4.8. Q: Where do the map tiles go?</li> <li>4.9. Q: How to unlock deeper map zoom and server management features on T-Deck?</li> <li>4.10. Q: How to decipher the diagnostics screen on T-Deck?</li> <li>4.11. Q: The T-Deck sound is too loud?</li> <li>4.12. Q: Can you customize the sound?</li> <li>4.13. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts?</li> <li>4.14. Q: How to capture a screenshot on T-Deck?</li> </ul> </li> <li>5. General<ul> <li>5.1. Q: What are BW, SF, and CR?</li> <li>5.2. Q: Do MeshCore clients repeat?</li> <li>5.3. Q: What happens when a node learns a route via a mobile repeater, and that repeater is gone?</li> <li>5.4. Q: How does a node discover a path to its destination and then use it to send messages in the future, instead of flooding every message it sends like Meshtastic?</li> <li>5.5. Q: Do public channels always flood? Do private channels always flood?</li> <li>5.6. Q: What is the public key for the default public channel?</li> <li>5.7. Q: Is MeshCore open source?</li> <li>5.8. Q: How can I support MeshCore?</li> <li>5.9. Q: How do I build MeshCore firmware from source?</li> <li>5.10. Q: Are there other MeshCore related open source projects?</li> <li>5.11. Q: Does MeshCore support ATAK?</li> <li>5.12. Q: How do I add a node to the MeshCore Map?</li> <li>5.13. Q: Can I use a Raspberry Pi to update a MeshCore radio?</li> <li>5.14. Q: Are there projects built around MeshCore?</li> <li>5.15. Q: Are there client applications for Windows or Mac?</li> <li>5.16. Q: Are there any resources that compare MeshCore to other LoRa systems?</li> </ul> </li> <li>6. Troubleshooting<ul> <li>6.1. Q: My client says another client or a repeater or a room server was last seen many, many days ago.</li> <li>6.2. Q: A repeater or a client or a room server I expect to see on my discover list (on T-Deck) or contact list (on a smart device client) are not listed.</li> <li>6.3. Q: How to connect to a repeater via BLE (Bluetooth)?</li> <li>6.4. Q: My companion isn't showing up over Bluetooth?</li> <li>6.5. Q: I can't connect via Bluetooth, what is the Bluetooth pairing code?</li> <li>6.6. Q: My Heltec V3 keeps disconnecting from my smartphone. It can't hold a solid Bluetooth connection.</li> <li>6.7. Q: My RAK/T1000-E/xiao_nRF52 device seems to be corrupted, how do I wipe it clean to start fresh?</li> <li>6.8. Q: WebFlasher fails on Linux with failed to open</li> </ul> </li> <li>7. Other Questions:<ul> <li>7.1. Q: How to update nRF (RAK, T114, Seeed XIAO) companion, repeater and room server firmware over the air using the new simpler DFU app?<ul> <li>7.1.1 Q: Can I update Seeed Studio Wio Tracker L1 Pro using OTA?</li> </ul> </li> <li>7.2. Q: How to update ESP32-based devices over the air?</li> <li>7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?</li> <li>7.4. Q: are the MeshCore logo and font available?</li> <li>7.5. Q: What is the format of a contact or channel QR code?</li> <li>7.6. Q: How do I connect to the companion via Wi-Fi, e.g. using a Heltec V3?</li> <li>7.7. Q: I have a Station G2, or a Heltec V4, or an Ikoka Stick, or a radio with an EByte E22-900M30S or an EByte E22-900M33S module, what should their transmit power be set to?</li> <li>7.8. Q: How do I use Ethernet with a RAK4631?</li> </ul> </li> </ul>"},{"location":"faq/#1-introduction","title":"1. Introduction","text":""},{"location":"faq/#11-q-what-is-meshcore","title":"1.1. Q: What is MeshCore?","text":"<p>A: MeshCore is a multi-platform system for enabling secure text-based communications utilizing LoRa radio hardware. It can be used for Off-Grid Communication, Emergency Response &amp; Disaster Recovery, Outdoor Activities, Tactical Security including law enforcement and private security and also IoT sensor networks. (source)</p> <p>MeshCore is free and open source:</p> <ul> <li>MeshCore is the routing and firmware etc., available on GitHub under MIT license</li> <li>There are clients made by the community, such as the web clients, these are free to use, and some are open source too</li> <li>The cross-platform mobile app developed by Liam Cottle for Android/iOS/PC etc. is free to download and use</li> <li>The T-Deck firmware is developed by Scott at Ripple Radios, the creator of MeshCore, is also free to flash on your devices and use</li> </ul> <p>Some more advanced, but optional features are available on T-Deck if you register your device for a key to unlock. On the MeshCore smartphone clients for Android and iOS/iPadOS, you can unlock the wait timer for repeater and room server remote management over RF feature.</p> <p>These features are completely optional and aren't needed for the core messaging experience. They're like super bonus features and to help the developers continue to work on these amazing features, they may charge a small fee for an unlock code to utilize the advanced features.</p> <p>Anyone is able to build anything they like on top of MeshCore without paying anything.</p>"},{"location":"faq/#12-q-what-do-you-need-to-start-using-meshcore","title":"1.2. Q: What do you need to start using MeshCore?","text":"<p>A: Everything you need for MeshCore is available at:</p> <ul> <li>Main Website: https://meshcore.io</li> <li>Firmware Flasher: https://flasher.meshcore.io</li> <li>MeshCore Firmware on GitHub: https://github.com/meshcore-dev/MeshCore</li> <li>MeshCore Companion Web App: https://app.meshcore.nz</li> <li>MeshCore Map: https://map.meshcore.io</li> <li>Liam Cottle's MeshCore Technical Presentation</li> </ul> <p>You need LoRa hardware devices to run MeshCore firmware as clients or server (repeater and room server).</p>"},{"location":"faq/#121-hardware","title":"1.2.1. Hardware","text":"<p>MeshCore is available on a variety of 433MHz, 868MHz and 915MHz LoRa devices. For example, Lilygo T-Deck, T-Pager, RAK Wireless WisBlock RAK4631 devices (e.g. 19003, 19007, 19026), Heltec V3, Xiao S3 WIO, Xiao C3, Heltec T114, Station G2, Nano G2 Ultra, Seeed Studio T1000-E. More devices are being added regularly.</p> <p>For an up-to-date list of supported devices, please go to https://flasher.meshcore.io</p> <p>To use MeshCore without using a phone as the client interface, you can run MeshCore on a LilyGo T-Deck, T-Deck Plus, T-Pager, T-Watch, or T-Display Pro. MeshCore Ultra firmware running on these devices is a complete off-grid secure communication solution.</p>"},{"location":"faq/#122-firmware","title":"1.2.2. Firmware","text":"<p>MeshCore firmware is organized by role and, for companions, by host transport. The main roles are Companion, Repeater, Room Server, and Sensor. The tree also contains specialized terminal-chat and KISS-modem builds. Availability depends on the board; use the flasher or that board's PlatformIO environments as the current source of truth.</p>"},{"location":"faq/#123-companion-radio-firmware","title":"1.2.3. Companion Radio Firmware","text":"<p>Companion radios connect MeshCore client software to LoRa. Depending on the board and build profile, the companion protocol can be exposed over BLE, USB serial, Wi-Fi, or Ethernet. Some boards also provide a Full Companion profile with additional local administration features. Check the exact build name and transport before flashing. Pending messages are held in a volatile shared queue; capacity depends on the platform and memory profile. See the Companion offline message queue for the exact defaults and limitations. See https://meshcore.io and the web client at https://app.meshcore.nz.</p>"},{"location":"faq/#124-repeater","title":"1.2.4. Repeater","text":"<p>Repeaters are used to extend the range of a MeshCore network. Repeater firmware runs on the same devices that run client firmware. A repeater's job is to forward MeshCore packets to the destination device. It does not forward or retransmit every packet it receives, unlike other LoRa mesh systems.</p> <p>A repeater can be remotely administered using a T-Deck running the MeshCore firmware with remote administration features unlocked, or from a BLE Companion client connected to a smartphone running the MeshCore app.</p>"},{"location":"faq/#125-room-server","title":"1.2.5. Room Server","text":"<p>A room server is a simple BBS server for sharing posts. T-Deck devices running MeshCore firmware or a BLE Companion client connected to a smartphone running the MeshCore app can connect to a room server.</p> <p>Room servers store message history on them and push the stored messages to users. Room servers allow roaming users to come back later and retrieve message history. With channels, messages are either received when it's sent, or not received and missed if the channel user is out of range. Room servers are different and more like email servers where you can come back later and get your emails from your mail server.</p> <p>A room server can be remotely administered using a T-Deck running the MeshCore firmware with remote administration features unlocked, or from a BLE Companion client connected to a smartphone running the MeshCore app.</p> <p>When a client logs into a room server, the client will receive the previously 32 unseen messages.</p> <p>Although room server can also repeat with the command line command <code>set repeat on</code>, it is not recommended nor encouraged. A room server with repeat set to <code>on</code> lacks the full set of repeater and remote administration features that are only available in the repeater firmware.</p> <p>The recommendation is to run repeater and room server on separate devices for the best experience.</p>"},{"location":"faq/#2-initial-setup","title":"2. Initial Setup","text":""},{"location":"faq/#21-q-how-many-devices-do-i-need-to-start-using-meshcore","title":"2.1. Q: How many devices do I need to start using MeshCore?","text":"<p>A: If you have one supported device, flash the BLE Companion firmware and use your device as a client. You can connect to the device using the Android or iOS client via Bluetooth. You can start communicating with other MeshCore users near you.</p> <p>If you have two supported devices, and there are not many MeshCore users near you, flash both to BLE Companion firmware so you can use your devices to communicate with your nearby friends and family.</p> <p>If you have two supported devices, and there are other MeshCore users nearby, you can flash one of your devices with BLE Companion firmware and flash another supported device to repeater firmware. Place the repeater high above ground to extend your MeshCore network's reach.</p> <p>After you flashed the latest firmware onto your repeater device, keep the device connected to your computer via USB serial, use the console feature on the web flasher and set the frequency for your region or country, so your client can remote administer the repeater or room server over RF:</p> <p><code>set freq {frequency}</code></p> <p>The repeater and room server CLI reference is here: https://docs.meshcore.io/cli_commands</p> <p>If you have more supported devices, you can use your additional devices with the room server firmware.</p>"},{"location":"faq/#22-q-does-meshcore-cost-any-money","title":"2.2. Q: Does MeshCore cost any money?","text":"<p>A: All radio firmware versions (e.g. for Heltec V3, RAK, T-1000E, etc.) are free and open source developed by Scott at Ripple Radios.</p> <p>The native Android and iOS client uses the freemium model and is developed by Liam Cottle, developer of meshtastic map at meshtastic.liamcottle.net on GitHub and reticulum-meshchat on GitHub.</p> <p>The T-Deck firmware is free to download and most features are available without cost. To support the firmware developer, you can pay for a registration key to unlock your T-Deck for deeper map zoom and remote server administration over RF using the T-Deck. You do not need to pay for the registration to use your T-Deck for direct messaging and connecting to repeaters and room servers.</p>"},{"location":"faq/#23-q-what-frequencies-are-supported-by-meshcore","title":"2.3. Q: What frequencies are supported by MeshCore?","text":"<p>A: Supported frequencies depend on the radio hardware and the rules for the country in which it operates. Common MeshCore hardware covers portions of the 433, 868, and 915 MHz ISM bands.</p> <p>Use the current regional preset offered by the client or flasher, confirm it with the local MeshCore community, and comply with local frequency, bandwidth, duty-cycle, and power limits. Do not copy an old frequency from this FAQ. Narrow presets commonly use BW62.5 with a lower spreading factor; their exact frequency and SF are region-specific and can change as deployments coordinate.</p> <p>If you have consensus from your community in your region to update your region's preset recommendation, please post your update request on  the #meshcore-app channel on the MeshCore Discord server  to let Liam Cottle know.</p>"},{"location":"faq/#24-q-what-is-an-advert-in-meshcore","title":"2.4. Q: What is an \"advert\" in MeshCore?","text":"<p>A: Advert means to advertise yourself on the network. In Reticulum terms it would be to announce. In Meshtastic terms it would be the node sending its node info.</p> <p>MeshCore allows you to manually broadcast your name, position and public encryption key, which is also signed to prevent spoofing. When you click the advert button, it broadcasts that data over LoRa. MeshCore calls that an Advert. There's two ways to advert, \"zero hop\" and \"flood\".</p> <ul> <li>Zero hop means your advert is broadcast to anyone that can hear it, and that's it.</li> <li>Flooded means it's broadcast and then repeated by all the repeaters that hear it.</li> </ul> <p>MeshCore clients only advertise themselves when the user initiates it. A repeater sends a flood advert once every 12 hours by default. This interval can be configured using the following command:</p> <p><code>set flood.advert.interval {hours}</code></p> <p>The separate <code>set advert.interval {minutes}</code> command controls the local zero-hop advert timer.</p>"},{"location":"faq/#25-q-is-there-a-hop-limit","title":"2.5. Q: Is there a hop limit?","text":"<p>A: Internally the firmware has maximum limit of 64 hops. In real world settings it will be difficult to get close to the limit due to the environments and timing as packets travel further and further. We want to hear how far your MeshCore conversations go.</p>"},{"location":"faq/#3-server-administration","title":"3. Server Administration","text":""},{"location":"faq/#31-q-how-do-you-configure-a-repeater-or-a-room-server","title":"3.1. Q: How do you configure a repeater or a room server?","text":"<p>A: When MeshCore is flashed onto a LoRa device for the first time, it is necessary to set the server device's frequency to make it utilize the frequency that is legal in your country or region.</p> <p>Repeater or room server can be administered with one of the options below:</p> <ul> <li>After a repeater or room server firmware is flashed onto a LoRa device, go to https://config.meshcore.io and use the web user interface to connect to the LoRa device via USB serial. From there you can set the name of the server, its frequency and other related settings, location, passwords etc.</li> </ul> <p></p> <ul> <li> <p>Connect the server device using a USB cable to a computer running Chrome on https://flasher.meshcore.io, then use the <code>console</code> feature to connect to the device</p> </li> <li> <p>Use a MeshCore smartphone client to remotely administer servers via LoRa.</p> </li> <li> <p>A T-Deck running unlocked/registered MeshCore firmware. Remote server administration is enabled through registering your T-Deck with Ripple Radios. It is one of the ways to support MeshCore development. You can register your T-Deck at:</p> </li> </ul> <p>https://buymeacoffee.com/ripplebiz/e/249834</p>"},{"location":"faq/#32-q-do-i-need-to-set-the-location-for-a-repeater","title":"3.2. Q: Do I need to set the location for a repeater?","text":"<p>A: While not required, with location set for a repeater it will show up on the MeshCore map in the future. Set location with the following command:</p> <p><code>set lat &lt;GPS Lat&gt;</code></p> <p><code>set lon &lt;GPS Lon&gt;</code></p> <p>You can get the latitude and longitude from Google Maps by right-clicking the location you are at on the map.</p>"},{"location":"faq/#33-q-what-is-the-password-to-administer-a-repeater-or-a-room-server","title":"3.3. Q: What is the password to administer a repeater or a room server?","text":"<p>A: The default admin password to a repeater and room server is <code>password</code>. Use the following command to change the admin password:</p> <p><code>password {new-password}</code></p>"},{"location":"faq/#34-q-what-is-the-password-to-join-a-room-server","title":"3.4. Q: What is the password to join a room server?","text":"<p>A: The default guest password to a room server is <code>hello</code>. Use the following command to change the guest password:</p> <p><code>set guest.password {guest-password}</code></p>"},{"location":"faq/#35-q-can-i-retrieve-a-repeaters-private-key-or-set-a-repeaters-private-key","title":"3.5. Q: Can I retrieve a repeater's private key or set a repeater's private key?","text":"<p>A: You can issue these commands to get or set a repeater's private key using a USB serial connection.</p> <p><code>get prv.key</code> to print a repeater's private key on the serial console <code>set prv.key &lt;hex&gt;</code> to set a repeater's private key on the serial console</p> <p>Reboot the repeater after <code>set prv.key &lt;hex&gt;</code> command for the new private key to take effect.</p>"},{"location":"faq/#36-q-the-first-byte-of-my-repeaters-public-key-collides-with-an-existing-repeater-on-the-mesh-how-do-i-get-a-new-private-key-with-a-matching-public-key-that-has-its-first-byte-of-my-choosing","title":"3.6. Q: The first byte of my repeater's public key collides with an existing repeater on the mesh. How do I get a new private key with a matching public key that has its first byte of my choosing?","text":"<p>A: You can generate a new private key and specify the first byte of its public key here: https://gessaman.com/mc-keygen</p> <p>Having multiple repeaters with the same first byte ID does not negatively affect the mesh or its functionality. Flood and pathed packets will still reach their destinations. First byte ID collision makes traceroute and path analysis harder because these tools don't know exactly which of the two (or more) colliding repeaters is the one in the path.</p> <p>Best practice is when you set up a new repeater, choose a public key that is not in use. If it is not possible to find a unique first byte for your repeater's public key, choose one that is unique within about 10 miles (16 km) to minimize collision with nearby repeaters.</p>"},{"location":"faq/#37-q-my-repeater-may-be-suffering-from-deafness-due-to-high-power-interference-near-my-meshs-frequency-it-is-not-hearing-other-in-range-meshcore-radios-what-can-i-do","title":"3.7. Q: My repeater may be suffering from deafness due to high power interference near my mesh's frequency, it is not hearing other in-range MeshCore radios. What can I do?","text":"<p>A: This may be due to the SX1262 radio's auto gain control feature. You can use this command to periodically reset its AGC.</p> <p><code>set agc.reset.interval &lt;number&gt;</code></p> <p>The <code>&lt;number&gt;</code> unit is in seconds and is incremented by 4. <code>set agc.reset.interval 4</code> works well to cure deafness.</p> <p>The reset is skipped while a packet is pending, being received, or being transmitted. When safe, <code>RadioLibWrapper::resetAGC()</code> warm-sleeps the radio, returns the wrapper to idle so receive mode is re-armed, reapplies the cached RX boost setting, and starts a fresh noise-floor calibration.</p>"},{"location":"faq/#371-q-can-firmware-recover-an-external-radio-whose-busy-pin-is-stuck-high","title":"3.7.1. Q: Can firmware recover an external radio whose BUSY pin is stuck high?","text":"<p>A: Current firmware first attempts a non-destructive RX/AGC re-arm and then uses a physical radio reset when the board exposes one. A normal RadioLib reinitialization is not reported as a hard reset unless firmware can actually pulse NRST or cycle the radio's power rail.</p> <p>Most supported external-radio boards expose NRST directly. RAK3401 pulses its dedicated NRST while leaving the shared peripheral rail and SPI controller intact, and LilyGo T-Beam 1W can cycle the radio regulator. The generic Tenstar C3 target describes a user-wired radio and has no reset connection by default. For unattended recovery on that target, wire NRST to a free GPIO and override <code>P_LORA_RESET</code> with that GPIO in the build configuration.</p> <p>The SenseCAP T1000-E LR1110 path was hardware-qualified with 50 successful radio-only resets: 25 in continuous receive and 25 with RX power saving active. The saved radio tuple, TX power, RX gain, and RX power-saving configuration were restored after every reset, bidirectional LoRa status traffic still passed, and the nRF52840 uptime remained continuous.</p> <p>An integrated STM32WL radio has no independently resettable RF peripheral, so it intentionally remains on the bounded soft-recovery path. If its radio core cannot recover, resetting only the radio is electrically impossible; the MCU must be restarted.</p>"},{"location":"faq/#372-q-does-firmware-automatically-update-lr1110-transceiver-firmware","title":"3.7.2. Q: Does firmware automatically update LR1110 transceiver firmware?","text":"<p>A: No. A transceiver update erases and rewrites the LR1110 itself, so it is not performed as a side effect of installing ordinary device firmware. Use the hardware vendor's physical-access maintenance procedure and verify the exact LR1110 and bootloader versions before changing them.</p> <p>Full remediation of Semtech SEM-PSA-2026-001 requires LR1110 BL2 0x1001 as well as the applicable transceiver firmware. It is a separate two-stage maintenance procedure and is not performed automatically by MeshCore.</p>"},{"location":"faq/#373-q-how-does-firmware-handle-lr2021-lowhigh-band-changes","title":"3.7.3. Q: How does firmware handle LR2021 low/high-band changes?","text":"<p>A: Firmware first selects the board's matching RF path, retunes the radio, and then reapplies output power so the LR2021 selects the correct low- or high-frequency PA. It also uses the matching RF-switch mode when RX or TX is launched. LR2021 high-band output power is limited to 12 dBm; a lower board-specific limit still takes precedence.</p> <p>On Meshnology W12, the two external FEM supplies are mutually exclusive: GPIO4 powers the sub-GHz GC1109 path and GPIO3 powers the 2.4 GHz RFX2402E path. Both supplies are disabled before the selected one is enabled. Temporary radio settings preserve the saved TX power and safely clamp only the active band; returning to the saved settings restores its applicable power. A permanent frequency change clamps the saved TX power to the new band's limit.</p> <p>The external SX1262, SX1268, LLCC68, LR1110, and LR2021 drivers also bound the post-SetTx BUSY wait. A failed PA ramp therefore returns an error and can enter the physical-reset recovery path instead of hanging the node indefinitely.</p>"},{"location":"faq/#38-q-how-do-i-make-my-repeater-an-observer-on-the-mesh","title":"3.8. Q: How do I make my repeater an observer on the mesh?","text":"<p>A: The observer instruction is available here: https://analyzer.letsmesh.net/observer/onboard</p>"},{"location":"faq/#39-q-what-is-multibyte-support-what-do-1-byte-2-byte-3-byte-adverts-and-messages-mean","title":"3.9. Q: What is multibyte support? What do 1-byte, 2-byte, 3-byte adverts and messages mean?","text":"<p>A: The original MeshCore protocol design uses the first byte of a repeater's public key to denote the repeater in a path. And with 1 byte for each repeater in the path, MeshCore packets can travel as many as 64 hops.</p> <p>However, with 1 byte, there are only 254 unique IDs (exclude 00 and FF which are reserved). Many meshes group have multiple repeaters with the same first byte in their public keys. Packets continue to pass through repeaters and the mesh is not harmed in any way. It does make it harder for tools to analyze paths with duplicated repeater IDs.</p> <p>Firmware version 1.14 and newer introduces the ability for repeaters to advert with 1-, 2-, or 3-byte adverts. Companions can also send out channel and direct messages with 1-, 2-, or 3-byte path. Adverts and messages sent in 1-byte path is compatible with repeater firmware older or newer than 1.14. They will travel up to 64 hops. 2-byte adverts and messages will travel up to 32 hops. 3-byte adverts and messages will travel up to 21 hops.</p>"},{"location":"faq/#391-q-what-path-hash-sizes-will-my-repeater-forward","title":"3.9.1. Q: What path hash sizes will my repeater forward?","text":"<p>Repeaters running firmware 1.14+ repeat packets sent with 1-, 2-, or 3-byte path hash. Repeaters on firmware older than 1.14 only repeat 1-byte path hash packets and silently drop 2- and 3-byte packets.</p>"},{"location":"faq/#392-q-what-determines-a-packets-path-hash-size","title":"3.9.2. Q: What determines a packet's path hash size?","text":"<p>The original packet sender determines the path hash size. The most common original sender is a companion app. The other common original sender is a repeater, when it broadcasts its advert.</p>"},{"location":"faq/#393-q-how-do-i-change-my-companions-path-hash-size","title":"3.9.3. Q: How do I change my companion's path hash size?","text":"<p>As of firmware version 1.14 and MeshCore app version 1.41.0, in the MeshCore app, you can set your companion's message path hash size in <code>Settings (gear icon)</code>, <code>Experimental Settings</code>.</p> <p>Until your regional mesh has the vast majority of the repeaters updated to 1.14+ firmware, it is recommended to keep your companion at the default 1-byte because pre-1.14 repeaters will silently drop messages with larger path hashes.</p>"},{"location":"faq/#394-q-what-does-the-cli-command-pathhashmode-do-on-a-repeater","title":"3.9.4. Q: What does the CLI command <code>path.hash.mode</code> do on a repeater?","text":"<p>This CLI command <code>path.hash.mode</code> only controls the path hash size used in a repeater's own advert broadcasts. It does NOT affect which packets the repeater forwards. A repeater with firmware 1.14+ always forward 1-, 2-, and 3-byte packets regardless of this setting.</p> <p>Usage: <code>set path.hash.mode {0|1|2}</code>:</p> <pre><code>+----------------+-----------------------+\n| path.hash.mode | Advert path hash size |\n+----------------+-----------------------+\n| 0              | 1 byte (default)      |\n+----------------+-----------------------+\n| 1              | 2 bytes               |\n+----------------+-----------------------+\n| 2              | 3 bytes               |\n+----------------+-----------------------+\n</code></pre> <p>It is safe to set your 1.14+ repeaters to mode 1 or 2.</p> <p></p>"},{"location":"faq/#395-q-why-use-2-or-3-byte-path-hash-for-adverts","title":"3.9.5. Q: Why use 2- or 3-byte path hash for adverts?","text":"<p>A longer path hash helps tools like the LetsMesh.net Analyzer and MeshMapper disambiguate repeaters more reliably. With only 1 byte, the chance of different repeaters having the same first byte in their public key is high, making it harder to tell them apart in mesh network analysis. Since this only affects adverts, there's no downside. 2- and 3-byte adverts don't travel as far as 1-byte adverts, but it is not important for MeshCore nodes to hear a repeater's advert that is 21 or 32 hops away.</p>"},{"location":"faq/#396-q-when-can-we-move-away-from-1-byte-path-hash-for-channel-and-direct-messages","title":"3.9.6. Q: When can we move away from 1-byte path hash for channel and direct messages?","text":"<p>You should move to send 2-byte or 3-byte channel and direct messages when the vast majority of the repeaters in your regional mesh are updated to firmware version 1.14 or newer. Setting your repeater's <code>path.hash.mode</code> to 1 (for 2-byte path hash) or 2 (for 3-byte path hash) now helps the community gauge to how many repeaters have updated to 1.14+. Please work with your MeshCore community together to decide when to switch to 2-byte path or 3-byte path for channel and direct messages.</p>"},{"location":"faq/#4-t-deck-related","title":"4. T-Deck Related","text":""},{"location":"faq/#41-q-is-there-a-user-guide-for-t-deck-t-pager-t-watch-or-t-display-pro","title":"4.1. Q: Is there a user guide for T-Deck, T-Pager, T-Watch, or T-Display Pro?","text":"<p>A: Yes, it is available on https://buymeacoffee.com/ripplebiz/ultra-v7-7-guide-meshcore-users</p>"},{"location":"faq/#42-q-what-are-the-steps-to-get-a-t-deck-into-dfu-device-firmware-update-mode","title":"4.2. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode?","text":"<p>A:</p> <ol> <li>Device off</li> <li>Connect USB cable to device</li> <li>Hold down trackball (keep holding)</li> <li>Turn on device</li> <li>Hear USB connection sound</li> <li>Release trackball</li> <li>T-Deck in DFU mode now</li> <li>At this point you can begin flashing using https://flasher.meshcore.io</li> </ol>"},{"location":"faq/#43-q-why-is-my-t-deck-plus-not-getting-any-satellite-lock","title":"4.3. Q: Why is my T-Deck Plus not getting any satellite lock?","text":"<p>A: For T-Deck Plus, the GPS baud rate should be set to 38400. Also, some T-Deck Plus devices were found to have the GPS module installed upside down, with the GPS antenna facing down instead of up. If your T-Deck Plus still doesn't get any satellite lock after setting the baud rate to 38400, you might need to open the device to check the GPS orientation.</p> <p>GPS on T-Deck is always enabled. You can skip the \"GPS clock sync\" and the T-Deck will continue to try to get a GPS lock. You can go to the <code>GPS Info</code> screen; you should see the <code>Sentences:</code> counter increasing if the baud rate is correct.</p> <p>Source</p>"},{"location":"faq/#44-q-why-is-my-og-non-plus-t-deck-not-getting-any-satellite-lock","title":"4.4. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock?","text":"<p>A: The OG (non-Plus) T-Deck doesn't come with a GPS. If you added a GPS to your OG T-Deck, please refer to the manual of your GPS to see what baud rate it requires. Alternatively, you can try to set the baud rate from 9600, 19200, etc., and up to 115200 to see which one works.</p>"},{"location":"faq/#45-q-what-size-of-sd-card-does-the-t-deck-support","title":"4.5. Q: What size of SD card does the T-Deck support?","text":"<p>A: Users have had no issues using 16GB or 32GB SD cards. Format the SD card to FAT32.</p>"},{"location":"faq/#46-q-what-is-the-public-key-for-the-default-public-channel","title":"4.6. Q: What is the public key for the default public channel?","text":"<p>A: T-Deck uses the same key the smartphone apps use but in base64 <code>izOH6cXN6mrJ5e26oRXNcg==</code></p> <p>There is no <code>=</code> key on the T-Deck's hardware keyboard. You can use the on-screen software keyboard to enter <code>=</code>. Tap the text box to enable the on-screen software keyboard. The third character is the capital letter <code>O</code> (Oh), not zero <code>0</code></p> <p>The smartphone app key is in hex: <code>8b3387e9c5cdea6ac9e5edbaa115cd72</code></p> <p>Source</p>"},{"location":"faq/#47-q-how-do-i-get-maps-on-t-deck","title":"4.7. Q: How do I get maps on T-Deck?","text":"<p>A: You need map tiles. You can get pre-downloaded map tiles here (a good way to support development):</p> <ul> <li>https://buymeacoffee.com/ripplebiz/e/342543 (Europe)</li> <li>https://buymeacoffee.com/ripplebiz/e/342542 (US)</li> </ul> <p>Another way to download map tiles is to use this Python script to get the tiles in the areas you want: https://github.com/fistulareffigy/MTD-Script</p> <p>There is also a modified script that adds additional error handling and parallel downloads: https://github.com/TheBestJohn/MTD-Script</p>"},{"location":"faq/#48-q-where-do-the-map-tiles-go","title":"4.8. Q: Where do the map tiles go?","text":"<p>Once you have the tiles downloaded, copy the <code>\\tiles</code> folder to the root of your T-Deck's SD card.</p>"},{"location":"faq/#49-q-how-to-unlock-deeper-map-zoom-and-server-management-features-on-t-deck","title":"4.9. Q: How to unlock deeper map zoom and server management features on T-Deck?","text":"<p>A: You can download, install, and use the T-Deck firmware for free, but it has some features (map zoom, server administration) that are enabled if you purchase an unlock code for \\$10 per T-Deck device. Unlock page: https://buymeacoffee.com/ripplebiz/e/249834</p>"},{"location":"faq/#410-q-how-to-decipher-the-diagnostics-screen-on-t-deck","title":"4.10. Q: How to decipher the diagnostics screen on T-Deck?","text":"<p>A: Space is tight on T-Deck's screen, so the information is a bit cryptic. The format is : <code>{hops} l:{packet-length}({payload-len}) t:{packet-type} snr:{n} rssi:{n}</code></p> <p>See here for packet-type: https://github.com/meshcore-dev/MeshCore/blob/main/src/Packet.h#L19</p> Value Payload <code>0x00</code> Request <code>0x01</code> Response <code>0x02</code> Plain text message <code>0x03</code> Acknowledgment <code>0x04</code> Node advertisement <code>0x05</code> Group text <code>0x06</code> Group datagram <code>0x07</code> Anonymous request <code>0x08</code> Returned path <code>0x09</code> Trace <code>0x0A</code> Multipart <code>0x0B</code> Control/discovery data <code>0x0C</code> OTA-over-LoRa data <code>0x0D</code>-<code>0x0E</code> Reserved <code>0x0F</code> Raw custom data <p>See Packet Format and Payload Format for the maintained descriptions.</p> <p>Source</p>"},{"location":"faq/#411-q-the-t-deck-sound-is-too-loud","title":"4.11. Q: The T-Deck sound is too loud?","text":""},{"location":"faq/#412-q-can-you-customize-the-sound","title":"4.12. Q: Can you customize the sound?","text":"<p>A: You can customize the sounds on the T-Deck, by placing <code>.mp3</code> files onto the <code>root</code> dir of the SD card. The files are:</p> <ul> <li><code>startup.mp3</code></li> <li><code>error.mp3</code></li> <li><code>alert.mp3</code></li> <li><code>new-advert.mp3</code></li> <li><code>existing-advert.mp3</code></li> </ul>"},{"location":"faq/#413-q-what-is-the-import-from-clipboard-feature-on-the-t-deck-and-is-there-a-way-to-manually-add-nodes-without-having-to-receive-adverts","title":"4.13. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts?","text":"<p>A: 'Import from Clipboard' is for importing a contact via a file named 'clipboard.txt' on the SD card. The opposite, is in the Identity screen, the 'Card to Clipboard' menu, which writes to 'clipboard.txt' so you can share yourself (call these 'biz cards', that start with \"meshcore://...\")</p>"},{"location":"faq/#414-q-how-to-capture-a-screenshot-on-t-deck","title":"4.14. Q: How to capture a screenshot on T-Deck?","text":"<p>A: To capture a screenshot on a T-Deck, long press the top-left corner of the screen. The screenshot is saved to the microSD card, if one is inserted into the device.</p>"},{"location":"faq/#5-general","title":"5. General","text":""},{"location":"faq/#51-q-what-are-bw-sf-and-cr","title":"5.1. Q: What are BW, SF, and CR?","text":"<p>A:</p> <p>BW is bandwidth - width of frequency spectrum that is used for transmission</p> <p>SF is spreading factor - how much should the communication spread in time</p> <p>CR is coding rate - from: https://www.thethingsnetwork.org/docs/lorawan/fec-and-code-rate</p> <p>TL;DR: default CR to 5 for good stable links. If it is not a solid link and is intermittent, change CR to 7 or 8.</p> <p>Forward Error Correction is a process of adding redundant bits to the data to be transmitted. During the transmission, data may get corrupted by interference (changes from 0 to 1 / 1 to 0). These error correction bits are used at the receivers for restoring corrupted bits.</p> <p>The Code Rate of a forward error correction expresses the proportion of bits in a data stream that actually carry useful information.</p> <p>There are 4 code rates used in LoRaWAN:</p> <p>4/5 4/6 5/7 4/8</p> <p>For example, if the code rate is 5/7, for every 5 bits of useful information, the coder generates a total of 7 bits of data, of which 2 bits are redundant.</p> <p>Making the bandwidth 2x wider (from BW125 to BW250) allows you to send 2x more bytes in the same time. Making the spreading factor 1 step lower (from SF10 to SF9) allows you to send 2x more bytes in the same time.</p> <p>Lowering the spreading factor makes it more difficult for the gateway to receive a transmission, as it will be more sensitive to noise. You could compare this to two people talking in a noisy place (a bar for example). If you're far from each other, you have to talk slow (SF10), but if you're close, you can talk faster (SF7)</p> <p>So, it's a balancing act between speed of the transmission and resistance to noise. The Things Network is mainly focused on LoRaWAN, but the LoRa low-level stuff still checks out for any LoRa project</p>"},{"location":"faq/#52-q-do-meshcore-clients-repeat","title":"5.2. Q: Do MeshCore clients repeat?","text":"<p>A: Companion clients do not repeat by default. Supported builds can opt into bounded client repeating on permitted frequencies, and the emergency-channel path has a bounded delayed relay behavior. Dedicated repeaters remain the normal and recommended way to extend network coverage. Room servers can repeat when explicitly configured, but separating the roles is generally preferable.</p>"},{"location":"faq/#53-q-what-happens-when-a-node-learns-a-route-via-a-mobile-repeater-and-that-repeater-is-gone","title":"5.3. Q: What happens when a node learns a route via a mobile repeater, and that repeater is gone?","text":"<p>A: If you used to reach a node through a repeater and the repeater is no longer reachable, the client will send the message using the existing (but now broken) known path, the message will fail after 3 retries, and the app will reset the path and send the message as flood on the last retry by default. This can be turned off in settings. If the destination is reachable directly or through another repeater, the new path will be used going forward. Or you can set the path manually if you know a specific repeater to use to reach that destination.</p> <p>In the case if users are moving around frequently, and the paths are breaking, they just see the phone client retries and revert to flood to attempt to re-establish a path.</p>"},{"location":"faq/#54-q-how-does-a-node-discover-a-path-to-its-destination-and-then-use-it-to-send-messages-in-the-future-instead-of-flooding-every-message-it-sends-like-meshtastic","title":"5.4. Q: How does a node discover a path to its destination and then use it to send messages in the future, instead of flooding every message it sends like Meshtastic?","text":"<p>Routes are stored in sender's contact list. When you send a message the first time, the message first gets to your destination by flood routing. When your destination node gets the message, it will send back a delivery report to the sender with all repeaters that the original message went through. This delivery report is flood-routed back to you the sender and is a basis for future direct path. When you send the next message, the path will get embedded into the packet and be evaluated by repeaters. If the hop and address of the repeater matches, it will retransmit the message, otherwise it will not retransmit, hence minimizing utilization.</p> <p>Source</p>"},{"location":"faq/#55-q-do-public-channels-always-flood-do-private-channels-always-flood","title":"5.5. Q: Do public channels always flood? Do private channels always flood?","text":"<p>A: Yes, group channels are A to B, so there is no defined path. They have to flood. Repeaters can however deny flood traffic up to some hop limit, with the <code>set flood.max</code> CLI command. Administrators of repeaters get to set the rules of their repeaters.</p> <p>Source</p>"},{"location":"faq/#56-q-what-is-the-public-key-for-the-default-public-channel","title":"5.6. Q: What is the public key for the default public channel?","text":"<p>A: The smartphone app key is in hex:</p> <p><code>8b3387e9c5cdea6ac9e5edbaa115cd72</code></p> <p>T-Deck uses the same key but in base64:</p> <p><code>izOH6cXN6mrJ5e26oRXNcg==</code></p> <p>The third character is the capital letter <code>O</code>, not zero <code>0</code>.</p> <p>Source</p>"},{"location":"faq/#57-q-is-meshcore-open-source","title":"5.7. Q: Is MeshCore open source?","text":"<p>A: Most of the firmware is freely available. Everything is open source except the T-Deck firmware and Liam's native mobile apps.</p> <p>Firmware repo: https://github.com/meshcore-dev/MeshCore</p>"},{"location":"faq/#58-q-how-can-i-support-meshcore","title":"5.8. Q: How can I support MeshCore?","text":"<p>A: Provide your honest feedback on GitHub and on MeshCore Discord server. Spread the word of MeshCore to your friends and communities; help them get started with MeshCore. Support Scott's MeshCore development at https://buymeacoffee.com/ripplebiz.</p> <p>Support Liam Cottle's smartphone client development by unlocking the server administration wait gate with in-app purchase</p> <p>Support Rastislav Vysoky (recrof)'s flasher website and the map website development through PayPal or Revolut</p>"},{"location":"faq/#59-q-how-do-i-build-meshcore-firmware-from-source","title":"5.9. Q: How do I build MeshCore firmware from source?","text":"<p>A: See instructions here: https://discord.com/channels/826570251612323860/1330643963501351004/1341826372120608769</p> <p>Build instructions for MeshCore:</p> <p>For Windows, first install WSL and Python+pip via: https://plainenglish.io/python/setting-up-python-on-windows-subsystem-for-linux-wsl-26510f1b2d80</p> <p>(Linux, Windows+WSL) In the terminal/shell:</p> <pre><code>sudo apt update\nsudo apt install libpython3-dev\nsudo apt install python3-venv\n</code></pre> <p>Mac: python3 should be already installed.</p> <p>Then it should be the same for all platforms:</p> <pre><code>python3 -m venv meshcore-venv\ncd meshcore-venv &amp;&amp; source bin/activate\npip install -U platformio\ngit clone https://github.com/meshcore-dev/MeshCore.git\ncd MeshCore\n</code></pre> <p>Choose an exact environment listed by <code>pio project config</code> or in the target board's <code>variants/*/platformio.ini</code>. For example:</p> <pre><code>pio run -e RAK_4631_repeater\n</code></pre> <p>The output is under <code>.pio/build/RAK_4631_repeater/</code>. Set the radio parameters to your current regional preset after flashing; if changing build defaults, keep that local change out of commits unless it is intended for every user.</p>"},{"location":"faq/#510-q-are-there-other-meshcore-related-open-source-projects","title":"5.10. Q: Are there other MeshCore related open source projects?","text":"<p>A: Liam Cottle's MeshCore web client and MeshCore JavaScript library are open source under MIT license.</p> <p>Web client: https://github.com/liamcottle/meshcore-web JavaScript: https://github.com/meshcore-dev/meshcore.js</p>"},{"location":"faq/#511-q-does-meshcore-support-atak","title":"5.11. Q: Does MeshCore support ATAK?","text":"<p>A: This repository does not ship or document an official ATAK integration. An external integration must account for LoRa airtime, moving endpoints, stale direct paths, and the collision cost of frequent flood fallback. Optional, bounded Companion repeating does not turn every mobile client into a dedicated repeater and does not remove those capacity constraints. Check current community projects before designing a deployment.</p> <p>Source</p>"},{"location":"faq/#512-q-how-do-i-add-a-node-to-the-meshcore-map","title":"5.12. Q: How do I add a node to the MeshCore Map?","text":"<p>A:</p> <p>To add a BLE Companion radio, connect to the BLE Companion radio from the MeshCore smartphone app. In the app, tap the <code>3 dot</code> menu icon at the top right corner, then tap <code>Internet Map</code>. Tap the <code>3 dot</code> menu icon again and choose <code>Add me to the Map</code></p> <p>To add a Repeater or Room Server to the map, go to the Contact List, tap the <code>3 dot</code> next to the Repeater or Room Server you want to add to the Internet Map, tap <code>Share</code>, then tap <code>Upload to Internet Map</code>.</p> <p>You can use the same companion (same public key) that you used to add your repeaters or room servers to remove them from the Internet Map.</p>"},{"location":"faq/#513-q-can-i-use-a-raspberry-pi-to-update-a-meshcore-radio","title":"5.13. Q: Can I use a Raspberry Pi to update a MeshCore radio?","text":"<p>A: Yes. Below are the instructions to flash firmware onto a supported LoRa device using a Raspberry Pi over USB serial.</p> <p>Instructions for nRF devices like RAK, T1000-E, T114 are immediately after the ESP instructions</p> <p>For ESP-based devices (e.g. Heltec V3) you need:</p> <ol> <li>Download the firmware file from https://flasher.meshcore.io.<ul> <li>Select the exact board and role. Artifact names and release URLs include a   changing version and commit, so copy the current download URL instead of   using an example URL from a guide.</li> <li>A non-merged application image is for an already compatible bootloader   and partition table. A merged image also contains low-level flash data.   Back up settings before either operation; do not assume a merged flash   preserves configuration, pairing data, or a previous partition layout.</li> <li>To download a copied URL from the shell, use   <code>curl -L '&lt;copied-url&gt;' -o &lt;firmware&gt;.bin</code>.</li> </ul> </li> <li>Confirm the <code>ttyXXXX</code> device path on your Raspberry Pi.<ul> <li>Run <code>ls /dev/ttyACM* /dev/ttyUSB* 2&gt;/dev/null</code> before and after connecting   the board. ESP devices can appear under either name.</li> </ul> </li> <li>Install esptool in a virtual environment.<ul> <li><code>python3 -m venv .venv &amp;&amp; . .venv/bin/activate</code></li> <li><code>python -m pip install --upgrade esptool</code></li> </ul> </li> <li>Flash the firmware.<ul> <li>For non-merged bin:<ul> <li><code>python -m esptool --port /dev/ttyUSB0 --chip auto write-flash 0x10000 &lt;non-merged-firmware&gt;.bin</code></li> </ul> </li> <li>For merged bin:<ul> <li><code>python -m esptool --port /dev/ttyUSB0 --chip auto write-flash 0x00000 &lt;merged-firmware&gt;.bin</code></li> </ul> </li> </ul> </li> </ol> <p>Instructions for nRF devices:</p> <p>For nRF devices (e.g. RAK, Heltec T114) you need the following:</p> <ol> <li>Download the firmware file from https://flasher.meshcore.io.<ul> <li>Select the exact board and role, and download its current ZIP package.   Do not rename a package from another board or reuse a static versioned URL.</li> </ul> </li> <li>Confirm the <code>ttyXXXX</code> device path on your Raspberry Pi.<ul> <li>Run <code>ls /dev/ttyACM* /dev/ttyUSB* 2&gt;/dev/null</code>; nRF bootloaders commonly   appear as <code>/dev/ttyACM0</code>, but the number can change.</li> </ul> </li> <li>In a virtual environment, install adafruit-nrfutil:<ul> <li><code>python3 -m venv .venv &amp;&amp; . .venv/bin/activate</code></li> <li><code>python -m pip install --upgrade adafruit-nrfutil</code></li> </ul> </li> <li>Flash the nRF device.<ul> <li><code>adafruit-nrfutil --verbose dfu serial --package &lt;firmware-package&gt;.zip -p /dev/ttyACM0 -b 115200 --singlebank --touch 1200</code></li> </ul> </li> </ol> <p>To manage a repeater or room server connected to a Pi over USB serial using shell commands, you need to install <code>picocom</code>. To install <code>picocom</code>, run the following command:</p> <ul> <li><code>sudo apt install picocom</code></li> </ul> <p>To start managing your USB serial-connected device using picocom, use the following command:</p> <ul> <li><code>picocom -b 115200 /dev/ttyUSB0 --imap lfcrlf</code></li> </ul> <p>From here, reference repeater and room server command line commands in the MeshCore docs here:</p> <ul> <li>https://docs.meshcore.io/cli_commands</li> </ul>"},{"location":"faq/#514-q-are-there-projects-built-around-meshcore","title":"5.14. Q: Are there projects built around MeshCore?","text":"<p>A: Yes, there are many. MeshCore's protocol is open source using the MIT license. The MIT license and the open source protocol makes it very easy for the MeshCore community to build new firmware for radios, applications on mobile devices, map tools, and analysis tools, and integration with other projects like Home Assistant.</p> <p>As new MeshCore community projects become available on a weekly basis, we have stopped tracking them here in this FAQ. samuk maintains a very exhaustive list of MeshCore community project at https://github.com/samuk/awesome-meshcore/blob/main/README.md. samuk accepts PRs and merges them regularly.</p>"},{"location":"faq/#515-q-are-there-client-applications-for-windows-or-mac","title":"5.15. Q: Are there client applications for Windows or Mac?","text":"<p>A: Yes, the same iOS and Android client is also available for Windows and Mac. You can find them together with the Android APK here: https://files.liamcottle.net/MeshCore</p> <p>Both the Windows and Mac versions of the client app are fully unlocked and are free to use.</p>"},{"location":"faq/#516-q-are-there-any-resources-that-compare-meshcore-to-other-lora-systems","title":"5.16. Q: Are there any resources that compare MeshCore to other LoRa systems?","text":"<p>A: Here is a list of MeshCore comparison resources:</p> <ul> <li>The Comms Channel on YouTube: https://www.youtube.com/watch?v=guDoKGs02Us</li> <li>MeshCore Advantages by MCarper: https://github.com/mikecarper/meshfirmware/blob/main/MeshCoreAdvantages.md</li> <li>MeshCore vs Meshtastic by austinmesh.org: https://www.austinmesh.org/about/meshcore-vs-meshtastic/</li> </ul>"},{"location":"faq/#6-troubleshooting","title":"6. Troubleshooting","text":""},{"location":"faq/#61-q-my-client-says-another-client-or-a-repeater-or-a-room-server-was-last-seen-many-many-days-ago","title":"6.1. Q: My client says another client or a repeater or a room server was last seen many, many days ago.","text":""},{"location":"faq/#62-q-a-repeater-or-a-client-or-a-room-server-i-expect-to-see-on-my-discover-list-on-t-deck-or-contact-list-on-a-smart-device-client-are-not-listed","title":"6.2. Q: A repeater or a client or a room server I expect to see on my discover list (on T-Deck) or contact list (on a smart device client) are not listed.","text":"<p>A:</p> <ul> <li>If your client is a T-Deck, it may not have its time set (no GPS installed, no GPS lock, or wrong GPS baud rate).</li> <li>If you are using the Android or iOS client, the other client, repeater, or room server may have the wrong time.</li> </ul> <p>You can get the epoch time on https://www.epochconverter.com and use it to set your T-Deck clock. For a repeater and room server, the admin can use a T-Deck to remotely set their clock (clock sync), or use the <code>time</code> command in the USB serial console with the server device connected.</p>"},{"location":"faq/#63-q-how-to-connect-to-a-repeater-via-ble-bluetooth","title":"6.3. Q: How to connect to a repeater via BLE (Bluetooth)?","text":"<p>A: You can't connect to a device running repeater firmware via Bluetooth. You can connect to devices running the BLE companion firmware via Bluetooth using the Android app.</p>"},{"location":"faq/#64-q-my-companion-isnt-showing-up-over-bluetooth","title":"6.4. Q: My companion isn't showing up over Bluetooth?","text":"<p>A: Make sure that you flashed the Bluetooth companion firmware and not the USB-only companion firmware.</p>"},{"location":"faq/#65-q-i-cant-connect-via-bluetooth-what-is-the-bluetooth-pairing-code","title":"6.5. Q: I can't connect via Bluetooth, what is the Bluetooth pairing code?","text":"<p>A: The default Bluetooth pairing code is <code>123456</code> on builds without a physical display. Display-equipped Companion builds generate a six-digit PIN at boot and show it when a client requests pairing. The display stays awake on the PIN page until Bluetooth connects or the two-minute pairing window expires.</p>"},{"location":"faq/#66-q-my-heltec-v3-keeps-disconnecting-from-my-smartphone-it-cant-hold-a-solid-bluetooth-connection","title":"6.6. Q: My Heltec V3 keeps disconnecting from my smartphone. It can't hold a solid Bluetooth connection.","text":"<p>A: Heltec V3 has a very small coil antenna on its PCB for Wi-Fi and Bluetooth connectivity. It has a very short range, only a few feet. It is possible to remove the coil antenna and replace it with a 31mm wire. The BT range is much improved with the modification.</p>"},{"location":"faq/#67-q-my-rakt1000-exiao_nrf52-device-seems-to-be-corrupted-how-do-i-wipe-it-clean-to-start-fresh","title":"6.7. Q: My RAK/T1000-E/xiao_nRF52/... device seems to be corrupted, how do I wipe it clean to start fresh?","text":"<p>A: If you're able to connect to the device from your MeshCore app 1. Navigate to Gear icon(Settings) on the upper right corner 2. Click on <code>Export Settings</code> button, choose <code>Select All</code> and Confirm. This will save your Node configuration 3. Now choose <code>Factory Reset</code> option 4. Confirm that you want to reset your device 5. Go to Bluetooth System settings and remove pairing of the device, so you can connect again 6. Connect your device in the app and enter the PIN 7. Navigate to Gear icon(Settings) on the upper right corner 8. Click on <code>Import Settings</code> and choose the file from 2., click on <code>Select All</code> and Confirm 9. Find <code>Reboot</code> button on of the Settings list</p> <p>B: You're not able to connect to the App 1. Connect USB cable to your device 2. Go to https://flasher.meshcore.io 3. Search for your device in the list 4. Choose <code>Companion Bluetooth</code> 5. Press <code>Enter DFU mode</code> button, choose your USB device 6. Press <code>Erase Flash</code> button, choose the device again and wait until it completes 7. Press <code>Flash!</code> button and choose the USB device last time 8. The device is erased and newest firmware is installed 9. You might need to remove the pairing in Bluetooth System Settings in order to re-pair the app again.</p> <p>An erase application or ordinary application ZIP/UF2 does not repair a damaged or partially overwritten SoftDevice. This can happen after flashing an nRF52 image for a different board or SoftDevice layout. A characteristic failure is that the application can boot and read its filesystem, but reboots or hangs when it writes or formats internal flash. Repeating <code>Erase Flash</code> is not a recovery for that condition.</p> <p>Recover it with a combined bootloader + SoftDevice package for the exact board (including XIAO Sense versus non-Sense), installed through serial/BLE DFU or SWD. With <code>adafruit-nrfutil</code>, the serial form is:</p> <pre><code>adafruit-nrfutil dfu serial -p &lt;port&gt; \\\n  -pkg &lt;exact-board-bootloader-with-softdevice&gt;.zip -sb -t 1200\n</code></pre> <p>Then install the exact-board MeshCore application. Do not use an application- only UF2, filesystem formatter, or a similarly named package from another nRF52 board as a substitute. See the confirmed XIAO recovery in issue #3284 and obtain the matching package from the OTAFIX releases.</p> <p>Separately, starting in firmware version 1.7.0, there is a CLI Rescue mode. If your device has a user button (e.g. some RAK, T114), you can activate the rescue mode by holding down the user button of the device within 8 seconds of boot. Then you can use the 'Console' on https://flasher.meshcore.io</p>"},{"location":"faq/#68-q-webflasher-fails-on-linux-with-failed-to-open","title":"6.8. Q: WebFlasher fails on Linux with failed to open","text":"<p>A: If the usb port doesn't have the right ownership for this task, the process fails with the following error:</p> <p><code>NetworkError: Failed to execute 'open' on 'SerialPort': Failed to open serial port.</code></p> <p>Allow user access on your USB port:</p> <p><code>sudo setfacl -m u:$USER:rw /dev/ttyUSB0</code></p>"},{"location":"faq/#7-other-questions","title":"7. Other Questions:","text":""},{"location":"faq/#71-q-how-to-update-nrf-rak-t114-seeed-xiao-companion-repeater-and-room-server-firmware-over-the-air-using-the-new-simpler-dfu-app","title":"7.1. Q: How to update nRF (RAK, T114, Seeed XIAO) companion, repeater and room server firmware over the air using the new simpler DFU app?","text":"<p>A: The steps below work on both Android and iOS as nRF has made both apps' user interface the same on both platforms:</p> <ol> <li>Download nRF's DFU app from iOS App Store or Android's Play Store, you can find the app by searching for <code>nrf dfu</code>, the app's full name is <code>nRF Device Firmware Update</code></li> <li>On https://flasher.meshcore.io, download the ZIP version of the firmware for your nRF device (e.g. RAK or Heltec T114 or Seeed Studio's Xiao)</li> <li>From the MeshCore app, log in remotely to the repeater you want to update with admin privileges</li> <li>Go to the Command Line tab, type <code>start ota</code> and hit enter.</li> <li>You should see <code>OK</code> to confirm the repeater device is now in OTA mode</li> <li>Run the DFU app, then tap <code>Settings</code> in the top-right corner</li> <li>Enable <code>Packet receipt notifications</code>, and change <code>Number of Packets</code> to 10 for RAK, 8 for T114. 8 also works for RAK.</li> <li>Select the firmware zip file you downloaded</li> <li>Select the device you want to update. If the device you want to update is not on the list, try enabling <code>OTA</code> on the device again</li> <li>If the device is not found, enable <code>Force Scanning</code> in the DFU app</li> <li>Tap <code>Upload</code> to begin OTA update</li> <li>If it fails, try toggling Bluetooth on your phone. If that doesn't work, try rebooting your phone. If you keep getting failures at the \"Enabling Bootloader\" step, try forgetting the nRF board in your iOS or Android device's Bluetooth settings and re-pair it through the DFU app.</li> <li>Wait for the update to complete. It can take a few minutes.</li> <li>It is strongly recommended that you install and use the OTAFIX bootloader at https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX.</li> <li>A companion must be running a build that exposes <code>start ota</code>; consult the     current flasher release notes rather than relying on a version threshold in     this FAQ.</li> <li>Please see the MeshCore Blog for additional information on OTA firmware flashing:<ul> <li>https://blog.meshcore.io/2026/04/06/otafix-bootloader</li> <li>https://blog.meshcore.io/2026/04/02/nrf-ota-update</li> </ul> </li> </ol>"},{"location":"faq/#711-q-can-i-update-seeed-studio-wio-tracker-l1-pro-using-ota","title":"7.1.1 Q: Can I update Seeed Studio Wio Tracker L1 Pro using OTA?","text":"<p>A:  You can flash this safer bootloader to the Wio Tracker L1 Pro https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX</p> <p>After this bootloader is flashed onto the device, you can trigger an over-the-air update using Bluetooth by holding the button next to the D-Pad and then clicking the reset button. Then follow the same OTA update instructions above. You can skip the <code>start ota</code> instruction and start the update using the DFU app.</p>"},{"location":"faq/#72-q-how-to-update-esp32-based-devices-over-the-air","title":"7.2. Q: How to update ESP32-based devices over the air?","text":"<p>A: For ESP32-based devices (e.g. Heltec V3):</p> <ol> <li>On https://flasher.meshcore.io, download the current non-merged    application image for the exact ESP32 board and role (no <code>merged</code> in the    filename).</li> <li>From the MeshCore app, log in remotely to the repeater you want to update with admin privileges.</li> <li>Go to the Command Line tab, type <code>start ota</code> and hit enter.</li> <li>You should see <code>OK</code> to confirm the repeater device is now in OTA mode.</li> <li>If the ESP32 is not already joined to Wi-Fi, <code>start ota</code> starts an open hotspot named <code>MeshCore-OTA</code> at <code>192.168.4.1</code>. If it is already joined, the command reports and uses its router-assigned address instead.</li> <li>From your phone or computer, connect to the <code>MeshCore-OTA</code> hotspot when one was started.</li> <li>Open the URL reported by <code>start ota</code> and upload the non-merged bin from the flasher. When the device started <code>MeshCore-OTA</code>, the URL is http://192.168.4.1/update.</li> </ol> <p>On an MQTT observer, stop WebConfig before running <code>start ota</code>; both servers use HTTP port 80. Likewise, stop the OTA uploader before running <code>start webconfig</code>.</p>"},{"location":"faq/#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu","title":"7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?","text":"<p>A: Yes, developer <code>che aporeps</code> has an enhanced OTA DFU bootloader for nRF52 based devices. With this bootloader, if it detects that the application firmware is invalid, it falls back to OTA DFU mode so you can attempt to flash again to recover. This bootloader has other changes to make the OTA DFU process more fault tolerant.</p> <p>Refer to https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX for the latest information.</p> <p>Currently, the following boards are supported:</p> <ul> <li>Elecrow ThinkNode M1, M3, and M6</li> <li>Heltec Automation Mesh Node T114 / HT-nRF5262</li> <li>LilyGO T-Echo</li> <li>Minewsemi MX25LE01</li> <li>Nologo ProMicro NRF52840 (aka SuperMini NRF52840)</li> <li>RAK4631</li> <li>RAK WisMesh Tag</li> <li>Seeed Studio SenseCAP Card Tracker T1000-E</li> <li>Seeed Studio SenseCAP Solar Node P1</li> <li>Seeed Studio Wio Tracker L1</li> <li>Seeed Studio XIAO nRF52840 BLE</li> <li>Seeed Studio XIAO nRF52840 BLE SENSE</li> </ul>"},{"location":"faq/#74-q-are-the-meshcore-logo-and-font-available","title":"7.4. Q: Are the MeshCore logo and font available?","text":"<p>A: Yes, it is on the MeshCore GitHub repo here: https://github.com/meshcore-dev/MeshCore/tree/main/logo</p>"},{"location":"faq/#75-q-what-is-the-format-of-a-contact-or-channel-qr-code","title":"7.5. Q: What is the format of a contact or channel QR code?","text":"<p>A:</p> <p>Channel: <code>meshcore://channel/add?name=&lt;name&gt;&amp;secret=&lt;secret&gt;</code></p> <p>Contact: <code>meshcore://contact/add?name=&lt;name&gt;&amp;public_key=&lt;secret&gt;&amp;type=&lt;type&gt;</code></p> <p>Where <code>&amp;type</code> is:</p> <ul> <li><code>chat = 1</code></li> <li><code>repeater = 2</code></li> <li><code>room = 3</code></li> <li><code>sensor = 4</code></li> </ul>"},{"location":"faq/#76-q-how-do-i-connect-to-the-companion-via-wi-fi-eg-using-a-heltec-v3","title":"7.6. Q: How do I connect to the companion via Wi-Fi, e.g. using a Heltec V3?","text":"<p>A: Flash an ESP32 companion Wi-Fi build. Its shared WebUI is enabled by default. If it has no saved Wi-Fi configuration, it starts an open <code>MeshCore-Setup-XXXX</code> access point. Join it and browse to http://192.168.4.1/. The wizard configures WiFi, node identity, and radio settings; MQTT companion builds add an MQTT step and MQTT tab, while non-MQTT companions remove those controls. After saving, the page and device screen show the station IP assigned by your router.</p> <p>If a saved network remains unreachable for two minutes, the setup AP starts as a fallback. If the original network returns, the companion closes that recovery portal and resumes normal LAN operation.</p> <p>The setup AP always uses <code>192.168.4.1</code>; the companion's station IP is assigned by DHCP and can be different. A real <code>WIFI_SSID</code> and <code>WIFI_PWD</code> can still be supplied at compile time as initial defaults, but they are no longer required.</p> <p>On the LAN, the WebUI remains available at the companion's station IP and the companion protocol remains available on TCP port <code>5000</code>. Companion builds do not have an admin CLI password, so this configuration page trusts the local LAN; do not put the companion on an untrusted WiFi network.</p> <p>ESP32 repeater and room-server builds use the same page, but keep it off by default. Run <code>set webui on</code> from the admin CLI, open the reported LAN URL, and sign in with the admin password; <code>get webui</code> reports its current address. Their MQTT observer variants expose the MQTT controls, while ordinary builds do not. The two 4 MB <code>LilyGo_TLora_V2_1_1_6_*_observer_mqtt</code> builds retain CLI-only configuration so their flash can keep two app slots for LoRa OTA.</p>"},{"location":"faq/#77-q-i-have-a-station-g2-or-a-heltec-v4-or-an-ikoka-stick-or-a-radio-with-an-ebyte-e22-900m30s-or-an-ebyte-e22-900m33s-module-what-should-their-transmit-power-be-set-to","title":"7.7. Q: I have a Station G2, or a Heltec V4, or an Ikoka Stick, or a radio with an EByte E22-900M30S or an EByte E22-900M33S module, what should their transmit power be set to?","text":"<p>A: For companion radios, you can set these radios' transmit power in the smartphone app. For repeater and room server radios, you can set their transmit power using the command line command <code>set tx</code>. You can get their current value using command line command <code>get tx</code></p> <p>[WARN] WARNING: Set these values at your own risk. Incorrect power settings can permanently damage your radio hardware.</p> Device / Model Region / Description In-App Setting (dBm) Target Radio Output Notes Station G2 Reference US915 Max Output 19 dBm 36.5 dBm (4.46W) US915 Max at 1dB compression point 16 dBm 35 dBm (3.16W) 1dB compression point EU868  Max at 1dB compression point 15 dBm 34.5 dBm (2.82W) 1dB compression point US915 1W Output 10 dBm 1W Refer to your local government's requirements EU868 1W Output 9 dBm 1W Refer to your local government's requirements Ikoka Stick E22-900M30S 1W Model 19 dBm 1W DO NOT EXCEED (Risk of burn out) data sheet Ikoka Stick E22-900M33S 2W Model 9 dBm 2W DO NOT EXCEED (Risk of burn out) data sheet Refer to your local government's requirements Heltec V4 Standard Output 10 dBm 22 dBm (~0.15W) High Output 22 dBm 28 dBm (~0.5W to 0.6W)"},{"location":"faq/#78-q-how-do-i-use-ethernet-with-a-rak4631","title":"7.8. Q: How do I use Ethernet with a RAK4631?","text":"<p>A: MeshCore supports Ethernet on RAK4631 boards using the RAK13800 WisBlock Ethernet module (based on the W5100S chip).</p> <p>Hardware required: - RAK4631 WisBlock Core - RAK19007 or RAK19018 WisBlock Base Board (with an available IO slot) - RAK13800 WisBlock Ethernet module - Ethernet cable connected to a network with a DHCP server</p> <p>Firmware: Flash one of the Ethernet-enabled firmware variants: - <code>RAK_4631_repeater_ethernet</code> - Repeater with Ethernet CLI access - <code>RAK_4631_room_server_ethernet</code> - Room server with Ethernet CLI access - <code>RAK_4631_companion_radio_ethernet</code> - Companion radio over Ethernet (replaces BLE)</p> <p>Connecting: - The device obtains an IP address via DHCP automatically on boot. - For repeaters and room servers, connect to the device on TCP port 23 using any TCP client (e.g. <code>nc &lt;ip&gt; 23</code> or PuTTY in raw mode). This gives you the same CLI available over serial/USB. - For companion radio firmware, the Ethernet interface replaces BLE as the transport to companion apps. Connect on TCP port 5000 (same as the WiFi companion radio). - Use the <code>eth.status</code> CLI command to check connection status and see the assigned IP address.</p>"},{"location":"filter_tool/","title":"Filter policy playground","text":"<p>Build a forwarding policy, see its readable definition, and simulate how a repeater handles a packet. Rules match received packet facts, then apply actions such as dropping, scoping, rate-limiting, or retrying a flood.</p> <p>Everything runs locally in this browser. Channel keys, packet facts, and policy drafts are not uploaded anywhere.</p> Policy design preview <p>     The phases and core conditions model current FPF7 behavior, including its     forward rows, scope rewrites, and shared blacklist. The readable policy     language, JSON, and Base64 bundle are still a prototype: current firmware     is configured with <code>set flood.*</code> or <code>set fr</code> commands and cannot install a     bundle from this page.   </p>"},{"location":"filter_tool/#build-a-policy","title":"Build a policy","text":"<p>Start with an example or build a rule, then test the draft against packet facts in the simulator below. The examples draw from Flood Filtering and Moderation.</p> Remote login and direct routes <p>       This policy only decides whether a relay retransmits a flood. Direct       packets and local delivery are unaffected. Rules matching the login/admin       family can still reduce multi-hop remote-login reach, so the analyzer       flags them.     </p> Example policies Choose one to load its full rules into the builder and draft. <p>         Read each summary as <code>when</code> all conditions match,         <code>do</code> the actions. A match alone does not stop forwarding.       </p> Payload selectors <code>type=</code> valueMatches <code>grp_data</code>Only the named payload type; see every exact type below <code>any</code>Every payload type <code>class:group</code>GRP_TXT and GRP_DATA <code>class:login</code>REQ, RESPONSE, TXT_MSG, ANON_REQ, and PATH <code>class:other</code>Every remaining payload type that is not group or login Other conditions and actions FieldMeaning <code>hops=</code>Received hop count: <code>all</code>, <code>3+</code>, <code>2-6</code>, or <code>3</code> <code>channel=</code><code>*</code> means no channel condition; a name or key authenticates one group channel; <code>hash:XX</code> is an unauthenticated one-byte fallback <code>rx.scope=</code>Original incoming transport scope <code>path=</code>Path prefix, blacklist, bucket, or loop match <code>tempradio=</code>Temporary-radio state <code>do drop</code>Do not retransmit <code>do scope=</code>Set the outgoing transport scope <code>do rate=</code>Apply a per-minute rate and burst <code>do timing=</code>Select fast, normal, or slow scheduling <p>         There is no <code>class:txt</code>. Use <code>type=grp_txt</code> for         channel text or <code>type=txt_msg</code> for peer text.       </p> Set #BlackHole86 scope on all #rgdata group traffic <code>when type=class:group hops=all channel=#rgdata do scope=#BlackHole86 timing=fast</code> Add #BlackHole86 scope to unscoped #rgdata data <code>when type=grp_data hops=all channel=#rgdata rx.scope=none do scope=#BlackHole86 timing=fast</code> Replace #usa with #BlackHole86 on #rgdata data <code>when type=grp_data hops=all channel=#rgdata rx.scope=scope:usa do scope=#BlackHole86 timing=fast</code> Rate-limit packets whose path starts with 860C <code>when type=any hops=all path=prefix:860C do rate=10/min burst=10</code> Drop selected flood types at their hop limits <code>when type=control hops=1+ do dropwhen type=req hops=3+ do drop; same for type=grp_datawhen type=response hops=9+ do drop; same for type=anon_req and type=path</code> Rate-limit Public messages from \u201cNoisy User\u201d <code>when type=grp_txt hops=all channel=public sender=\"Noisy User\" do rate=5/min burst=5</code> Stop forwarding traffic from blacklisted internet gateways <code>when type=any hops=all path=blacklist do drop</code> Three defaults: OTA, distant #wardriving, and bridge/crossover #wardriving <code>when type=ota hops=all tempradio=inactive do dropwhen type=any channel=#wardriving hops=5+ do dropwhen type=any channel=#wardriving hops=all via=bridge,cross do drop</code> Set #BlackHole86 scope on login and bucket-matched other traffic <code>when type=class:login hops=all do scope=#BlackHole86 timing=fastwhen type=class:other hops=all path=bucket:2 do scope=#BlackHole86 timing=slow</code> <p>Rule builder</p> Reset form <p>The factory example contains all three repeater defaults.         The playground's <code>via=</code> traffic-path matcher corresponds to firmware         <code>mode=radio|bridge|cross|bridge,cross</code>; the advanced Active/Shadow/Disabled         mode is a separate playground setting. See the         firmware mode guide.         This simulator models flood packets; firmware bridge/cross rules also cover direct routes.</p> Common match settings            Payload type or class            Any payload type Class: group text and data Class: login/admin family Class: every other payload REQ RESPONSE TXT_MSG ACK ADVERT GRP_TXT GRP_DATA ANON_REQ PATH TRACE MULTIPART CONTROL OTA Reserved type 13 Reserved type 14 RAW_CUSTOM            Received hops                       Channel (optional)                       Original incoming scope                       Path matcher            No path condition Ordered 1/2/3-byte pbyte prefix Passive blacklist Path bucket 1 Path bucket 2 Path bucket 3 Path bucket 4 Path bucket 5 Path bucket 6 Own-ID loop: strict Own-ID loop: moderate Own-ID loop: minimal            Ordered pbyte prefix                       Decrypted sender (optional)                       Traffic path (firmware mode)            Normal radio forwarding Bridge entry/exit Radio profile crossover Bridge and crossover            Temporary-radio state            Either state Inactive Active Common actions <p>         Choosing a phase-specific action automatically selects a compatible         phase and ACL owner. Open the advanced section to inspect or override         those choices.       </p>            Forwarding verdict            No verdict change Drop / do not retransmit            Region-gate decision            Leave global gate unchanged Require original allowed region Bypass global gate for this packet            Scope rewrite target            Do not rewrite scope Regionless public scope Configured region            Target name                       Token rate per minute (optional)                       Burst tokens                       Rewrite timing            Inherit normal behavior Fast-track rewrite Normal queue timing Slow receive/transmit timing            Queue priority            Inherit High Normal Low            Retry path bucket            No retry action Bucket 1 Bucket 2 Bucket 3 Bucket 4 Bucket 5 Bucket 6            Retry attempts                       Decision tag (optional)            Advanced execution, ownership, and flood route <p>           Direct packets already carry a supplied path and are intentionally           outside this engine. The route condition below only distinguishes           unscoped floods from transport-scoped floods.         </p>              Stable rule ID                           Processing phase              1 - Incoming scope gate 2 - Scope rewrite 3 - Forwarding decision 4 - Decrypted content 5 - Scheduling and retry              Rule owner / capability              ACL 4 - Region/scope manager ACL 5 - Filter manager Administrator Firmware-managed system rule              Priority                           Mode              Active Shadow - observe only Disabled              Rule processing after a match              Continue to later rules Skip later rules in this phase Skip all later policy rules              Flood route              Either flood route Unscoped flood only Transport-scoped flood only Readable policy definition <code></code> <p></p> Add rule to policy Copy definition <p>Policy draft</p> Clear policy            Approximate target budget            Compact STM32 - 2 KB nRF52 - 8 KB Classic ESP32 - 16 KB Roomy ESP32 - 64 KB <p>         Rules match the same immutable packet facts. Ordering is phase, then         descending priority, then authenticated channel, raw hash, or wildcard         specificity, then stable rule ID. Drop decisions are sticky.       </p>          Add a rule or load an example to start exploring.        <p>Immutable packet simulator</p> Reset packet Read a raw MeshCore packet <p>             Paste an on-air packet as hexadecimal. The decoder follows the             MeshCore wire format, displays its             header, route, pbyte path, and clear payload envelope, then loads             only facts actually present on the wire into the simulator.           </p> Runs locally          Raw packet hex         014e912ceebb98918b86772df5dacf1bcba9e4127ffffaa8665596aa3e2903a3b1901fdc53497dfca6b5d7df2d771bea68de Decode and load packet            Packet traffic path            Normal radio forwarding Bridge entry/exit Radio profile crossover          Received route          Unscoped flood Transport-scoped flood          Payload type          REQ RESPONSE TXT_MSG ACK ADVERT GRP_TXT GRP_DATA ANON_REQ PATH TRACE MULTIPART CONTROL OTA Reserved type 13 Reserved type 14 RAW_CUSTOM          Received hops                   Channel                   Received pbyte path                   Original scope status          Unscoped Allowed region Unknown or denied scope          Original scope name                   Resolved region name                   Decrypted sender                   Passive blacklist result          No match Matched          Matching path buckets                   Own-ID loop result          No loop match Strict only Moderate and strict Minimal, moderate, and strict          Temporary radio is active        Run policy simulation <p>Import and explain</p> <p>       Accepts one-line <code>policy set ... when ... do ...</code> definitions,       playground JSON, or a playground Base64 bundle.     </p> Explain input Load into builder <p>Export</p> Readable policy Policy JSON Playground Base64 <p>Proposed human-readable definition. Current firmware does not accept it yet.</p> <p>Structured draft used by this page.</p> <p>Browser-playground interchange only. It is not the final packed firmware codec.</p> Copy visible export Download JSON"},{"location":"filter_tool/#filter-builder-title","title":"Create a policy rule","text":""},{"location":"filter_tool/#filter-policy-title","title":"Rules in execution order","text":""},{"location":"filter_tool/#filter-simulator-title","title":"Explain an evaluation","text":""},{"location":"filter_tool/#filter-import-title","title":"Paste readable policy or a saved draft","text":""},{"location":"filter_tool/#filter-export-title","title":"Move or save this design","text":""},{"location":"filter_tool/#payload-type-reference","title":"Payload type reference","text":"<p>Use an exact <code>type=</code> value when a rule should match only one payload type. The class column shows which broader selector also matches it.</p> <code>type=</code> value Payload Class <code>req</code> Request <code>class:login</code> <code>response</code> Response <code>class:login</code> <code>txt_msg</code> Peer text message <code>class:login</code> <code>ack</code> Acknowledgment <code>class:other</code> <code>advert</code> Node advertisement <code>class:other</code> <code>grp_txt</code> Group-channel text <code>class:group</code> <code>grp_data</code> Group-channel datagram <code>class:group</code> <code>anon_req</code> Anonymous request <code>class:login</code> <code>path</code> Returned path <code>class:login</code> <code>trace</code> Path trace <code>class:other</code> <code>multipart</code> One frame in a multipart sequence <code>class:other</code> <code>control</code> Control or discovery data <code>class:other</code> <code>ota</code> OTA-over-LoRa data <code>class:other</code> <code>13</code> Reserved payload type 13 <code>class:other</code> <code>14</code> Reserved payload type 14 <code>class:other</code> <code>raw_custom</code> Application-defined raw data <code>class:other</code>"},{"location":"filter_tool/#current-fpf7-command-mapping","title":"Current FPF7 command mapping","text":"Firmware command FPF7 role <code>fr</code> / <code>flood.rule</code> / <code>flood.filter</code> Forward-phase match and action rows <code>flood.channel.data</code> Compatibility view over one visible <code>type=grp_data</code> forward drop row <code>flood.channel.scope</code> Scope-rewrite phase rows <code>flood.filter.blacklist</code> One shared unordered path-ID set referenced by <code>path=blacklist</code> rows <p>Generalized repeaters expose 63 forward rows and commit those sections together. The blacklist is useful for refusing to retransmit floods associated with internet gateways dumping bulk traffic, but a path ID is truncated and unauthenticated; it identifies a routing pattern, not a person.</p> <p>The firmware accepts both full and short CLI forms for the same forward row:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nset fr.3 any c=#wardriving m=bc d\n</code></pre> <p>Use <code>get fr.3</code> on the device to obtain a short setter ready to copy. This CLI syntax is separate from the playground's proposed policy/bundle format. See the shorthand reference.</p>"},{"location":"filter_tool/#proposed-evaluation-contract","title":"Proposed evaluation contract","text":"<p>The simulator uses these rules:</p> <ol> <li>Only flood retransmission enters the policy. Direct routing and local packet    delivery remain outside it.</li> <li>Every matcher reads the same immutable receive-time packet facts.</li> <li>Rules run by phase and descending numeric priority. At an equal priority,    authenticated channel matches run before raw one-byte hash matches, which    run before wildcard channel matches; stable rule ID breaks the remaining    tie. An explicitly higher numeric priority overrides channel specificity.</li> <li>A drop decision is sticky and cannot be undone by a later rule.</li> <li>The first matching scope, timing, queue, and retry action in execution order    wins.</li> <li>All matching token-bucket rate constraints remain attached to the decision.</li> <li><code>stop=phase</code> skips later rules in that phase. <code>stop=policy</code> skips later    configurable rules, but never mandatory packet validation or radio safety.</li> <li>Shadow rules report what they would do without changing the decision or    stopping other rules.</li> <li>Expensive facts such as channel-key matching, decryption, and path-table    lookup are resolved once per packet and reused by every matching rule.</li> </ol> <p>The byte-budget display is deliberately approximate until the packed firmware codec exists. It demonstrates why simple mappings should not reserve a maximum- sized structure for every possible condition and action.</p>"},{"location":"firmware_memory_budget/","title":"Firmware memory checks","text":"<p>Every firmware environment runs <code>scripts/check_firmware_ram.py</code> against its linked ELF before producing or uploading an image. <code>build.sh</code>, including option 3, also requires a passing report before collecting release files. Native host tests do not use a microcontroller RAM budget.</p> <p>The check reserves room for enabled runtime allocations as well as static data. A firmware image fitting its board's reported RAM total is insufficient: the display, packet pool, USB, Bluetooth workers and WiFi can allocate after startup. The T096 Full 1.17.1.5 report exposed this distinction.</p>"},{"location":"firmware_memory_budget/#what-is-counted","title":"What is counted","text":"Platform Source of available runtime RAM nRF52 Actual <code>__HeapBase</code> and <code>__HeapLimit</code>; excludes SoftDevice, retained state, ISR stack and the dedicated 64 KiB mOTA arena where present ESP32, S3, C3, C6 Linked ESP-IDF memory-region, capability and reservation tables; only internal, byte-addressable heap counts RP2040/RP2350 <code>__end__</code> to <code>__HeapLimit</code>, according to the selected linker STM32 <code>_end</code> to <code>_estack</code>, minus <code>_Min_Stack_Size</code> <p>ESP32 PSRAM, instruction-only RAM and RTC RAM never increase the internal budget. On chips other than classic ESP32, the late-reclaimed ROM stack region is excluded because its silicon-specific reservations are only known at boot. Classic ESP32 additionally retains its existing 8 KiB static DRAM check.</p> <p>The policy adds allowances for task stacks, radio packet pools, screen objects and pixel buffers, filesystem/sensor allocations, enabled wireless stacks, MQTT connections, OTA scratch and transient allocations. A 160x80 ST7735 framebuffer needs 25,602 bytes; an OLED allowance is 4 KiB. nRF52 Full with that color framebuffer must have at least 72 KiB available before startup allocations. Headless and OLED devices use their own smaller totals. The JSON lists each component and checks the largest available region against the largest planned single allocation.</p> <p>The small-screen message layout retains complete 160-byte messages. Its expanded preview records add 2,816 bytes to the startup allowance and increase the contiguous history allocation budget. The V4 can allocate that history in PSRAM; the guard conservatively reserves internal capacity so that PSRAM availability cannot hide a RAM shortage. A target may replace the generic UI allowance only with <code>MESH_COMPANION_SCREEN_STARTUP_BYTES</code>; a source-side assertion then covers its actual startup screens plus ESP32 allocator overhead.</p> <p>These are engineering allowances for supported configurations, not measured free heap after boot or a guarantee against every future allocation failure. Unknown platforms, unknown display drivers and missing linker metadata fail closed. <code>MESH_MIN_RUNTIME_HEAP</code> can raise a profile's requirement; it cannot lower the calculated requirement. Add an allocation allowance when adding a display, transport or other substantial feature.</p> <p>Wireless Paper Full keeps 350 contacts and 256 offline frames by lending the upper 128 queue slots to its mOTA workspace during a session. An idle WiFi mOTA listener leaves all 256 slots available. More than 128 unread frames refuses the loan; sync messages with an app first. USB/TCP source detach or disconnect returns all 256 slots and releases the ESP32 proof/leaf scratch buffers. The display and simultaneous USB, Bluetooth and WiFi remain enabled.</p>"},{"location":"firmware_memory_budget/#release-evidence-and-regression-tests","title":"Release evidence and regression tests","text":"<p>Full Companions without PSRAM also use 16-entry path and shared-secret caches. The optional NimBLE capacity trials retain the same RAM guards at 350 contacts and 256 normal offline frames.</p> <p>Each newly built firmware has a matching <code>.memory.json</code> report. It records the linked ELF SHA-256, available internal RAM, required RAM, largest region, and SHA-256 hashes for the actual firmware files and capability manifest. Packaging and resumed builds reject absent reports, failures, stale ELFs, missing files and changed firmware. Do not reuse a report for another build.</p> <p>Run PlatformIO commands sequentially in this checkout:</p> <pre><code>python3 -B test/test_firmware_ram.py\npython3 -B test/test_t096_full_memory.py\npython3 -B test/test_nrf52_ble_startup.py\npython3 -B test/test_shared_mota_queue.py\npython3 -B test/test_cascade_release_package.py\npio test -e native -f test_ota\n</code></pre> <p>Tests cover all resolved firmware environments' hooks, real ELF parsing, allocator table formats, excluded memory, allocation failure, package/report binding and the published T096 failing budget. Shared mOTA tests exercise complete transfers, queue wraparound, unread-message order, source ownership, stop/disconnect and repeated reuse. Bluetooth tests inject task and service startup failures. The manual staging buffer also has allocation-failure and repeated release tests. ESP32 tests run the actual WiFi mOTA listener and source framing through complete transfers, idle polling, queue-full refusal, network loss, CLI detach and USB/TCP ownership changes under address/leak sanitizers.</p> <p>For older releases without saved ELFs, an audit can compare their ESP allocator tables against a matching pinned SDK ELF and read reservations from the published application itself using <code>scripts/audit_esp32_image_ram.py</code>. Unrecognized layouts require another matching reference or a historical rebuild. An audit must identify original-log/linker calculations separately from new ELF checks and verify the published firmware hashes.</p> <p>Physical validation remains necessary: boot with and without USB, pair and exchange Bluetooth messages, visit every screen, wake with the button, enable logging/MQTT, transfer mOTA, and monitor heap during a sustained workload. See memory monitoring for runtime diagnostics.</p>"},{"location":"firmware_picker/","title":"Firmware picker","text":"<p>Each result now includes Restore your settings after flashing. Its commands follow the selected logging mode and the exact image's verified role/hardware controls. Select On, Off, or Check to view and copy the commands; Companion MQTT and GPS show their app/WebConfig steps instead. See feature switches by role for the full reference. The USB web console works with the default ASCII terminal on USB Companion and infrastructure roles.</p> <p>Pick the choices in any order. Every selection narrows all the other controls to firmware combinations that were actually built in the current release set. The optional chip-family filter (ESP32, nRF52, RP2040, or STM32) can narrow the hardware list first. You can skip it: picking hardware fills it in automatically.</p> <p>The picker reads public release metadata from GitHub. It does not upload device information. Hardware names, target names, and download links come directly from the published firmware assets.</p> Current release set <p>Loading release information...</p> <p>       For a new installation, choose the exact board and role, prefer a       FULL / complete profile when it is available, and select       Full install / layout migration (merged .bin). Narrower profiles       remain available when their reduced transport or feature set is intentional.     </p> <p>     Pick in any order. Use Any to clear one choice, or clear     everything with the button below. The address bar updates with your choices;     copy its URL to reopen or share the same selection.   </p> Optional: chip family <p>Skip this if you know your board. Picking hardware selects its chip family automatically. Choose Any to clear this filter.</p> Chip family Any chip family - skip this filter Hardware Loading hardware... Hardware variant Choose hardware first Install operation          Loading install choices...        Firmware role          Loading roles...        Logging / MQTT          Loading logging choices...        OTA capability          Loading OTA choices...        Connection / bridge mode Loading modes... Feature profile          Loading profiles...        Firmware variant Loading variants... Clear all choices Copy link to settings Link to these settings <p></p>      Loading the current firmware catalog...    <p>Exact firmware match</p> Recommended download <p></p> No exact firmware matched <p></p> Browse all firmware releases Advanced: search current release filenames <p>       Use this for uncommon board suffixes or expert recovery. A filename match       is not a board-identity check.     </p>        Filename contains"},{"location":"firmware_picker/#what-the-choices-mean","title":"What the choices mean","text":"Choice Use Companion A phone, computer, or host application controls the radio Repeater Standalone mesh relay Room Server Hosts room conversations and history Sensor / telemetry Publishes supported sensor data Terminal Chat Standalone serial-terminal interface USB logging / USB-connected MQTT Node remains attached to a computer over a data-capable USB cable Wi-Fi MQTT observer Firmware connects directly to MQTT over Wi-Fi; this is not USB logging USB logging + Wi-Fi MQTT Unified FULL image sends to both paths; avoid two publishers aimed at the same broker unless messages are deduplicated No logging Normal standalone operation without the dedicated logging/MQTT profile LoRa OTA repeater Repeater profile that can stage an exact matching update received over LoRa LoRa OTA source only Full Companion serving a host-supplied update to another node without self-installing it <p>Connection and bridge choices depend on the selected role. Companion firmware may offer Full, combined USB + Bluetooth, Bluetooth, USB, Wi-Fi, serial, or Ethernet transports. Normal repeater firmware includes runtime-controlled RS-232 support where the board has room; use <code>set bridge.enabled on</code> after configuring <code>bridge.uart</code> and <code>bridge.baud</code>. The Wio-E5 remains the capacity exception and offers a separate RS-232 image. Choose Wi-Fi MQTT under Logging / MQTT; it is an output mode, not a second connection choice. Repeaters may still offer separate ESP-NOW or Ethernet bridge firmware because those paths use different compiled drivers.</p> <p>For commands and option explanations, follow the ESP-NOW bridge setup guide.</p> <p>An ESP-NOW bridge target keeps LoRa as its primary mesh radio. Expanded ESP32 Full repeater and room-server images combine ESP-NOW with WiFi MQTT in the same firmware. MQTT and ESP-NOW are independent runtime transports: use <code>set mqtt.enabled on|off</code> for MQTT and <code>set bridge.enabled on|off</code> (or <code>set espnow.enabled on|off</code>) for ESP-NOW, so either or both can run. Both use one 2.4 GHz radio, so when both are enabled the ESP-NOW bridge channel must match the connected WiFi access point's fixed channel. ESP-NOW-only mode does not require WiFi credentials. Its runtime <code>bridge.format</code> setting chooses the peer protocol: <code>wrapped</code> (the backward-compatible bridge-to-bridge default using <code>bridge.secret</code>) or <code>raw</code> (direct MeshCore ESP-NOW LR frames for <code>Generic_ESPNOW</code>, <code>SenseCapIndicator-ESPNow</code>, and other primary-ESP-NOW nodes). This is one firmware choice, not two board images. Match <code>bridge.channel</code> to the primary nodes' <code>espnow.channel</code> before selecting <code>set bridge.format raw</code>. For Heltec V4 specifically, <code>companion_radio_full</code> is still a LoRa-primary Companion; choose the existing <code>heltec_v4_repeater_bridge_espnow</code> firmware to make that board the LoRa/ESP-NOW gateway. Use its exact merged artifact when changing roles or partition layouts.</p>"},{"location":"firmware_picker/#share-a-selection","title":"Share a selection","text":"<p>Select any combination of choices, then copy the address bar or use Copy link to settings. Opening the link restores those choices after the release catalog loads. Partial selections work too, so you can share a board and role while leaving other choices open. Clear all choices removes the picker parameters from the URL. Changes update the current browser-history entry without reloading the page or adding a Back-button entry for every click.</p> <p>For example, RAK3401 repeater with internal storage preselects that board, role, OTA capability, and storage profile.</p> <p>The query parameters are <code>chipFamily</code>, <code>hardwareFamily</code>, <code>hardware</code>, <code>role</code>, <code>logging</code>, <code>ota</code>, <code>mode</code>, <code>feature</code>, <code>variant</code>, and <code>install</code>. Values use the picker's internal identifiers rather than the displayed labels. The generated link also records <code>chipAuto</code> so automatic chip-family selection or an explicit Any choice behaves the same after reopening. Existing section anchors and unrelated query parameters are preserved.</p> <p>Links use the current release catalog. If a linked choice is no longer available or conflicts with another choice, the picker identifies it and asks you to review the remaining selections. The downloadable HTML's Copy link to settings button creates a public website link that other people can open.</p>"},{"location":"firmware_picker/#full-versus-standard","title":"FULL versus standard","text":"<p>For a new installation, use the FULL / complete profile when it exists and the board has enough flash. FULL profiles keep the complete supported feature set and CLI. Standard profiles remain useful for boards without a FULL build, for an intentionally narrower transport, or when retaining an existing compatible partition layout.</p> <p>Changing between standard and FULL ESP32 layouts requires the exact-board merged image over USB. A running application cannot safely move its own active and inactive partitions.</p> <p>Current <code>full-usb-wifi</code> profiles use one binary for no external output, USB packet logging/USB-connected MQTT, direct WiFi MQTT, or both. The picker shows that same exact binary for each compatible logging choice; select the saved runtime mode with <code>set logging.output off|usb|wifi|both</code>. A FULL logging-fallback profile is listed only when no WiFi MQTT sibling exists; it appears for both the no-output and USB choices because <code>set usb.logging off|on</code> is persistent. On a fresh unified FULL install with no saved SSID, the setup AP and WiFi radio remain available for 30 minutes per boot, then turn off automatically until the next reboot or power cycle. An explicit administrator <code>start webconfig</code> remains available as an override. A saved SSID switches to the normal indefinite reconnect behavior instead.</p> <p>Full Companion profiles use one binary for USB, BLE, ordinary Wi-Fi on ESP32, source-only LoRa OTA, Terminal Chat, optional USB packet logging, and any board-qualified serial or Ethernet Companion transport. Bulk builds therefore omit separate attached-transport, Terminal Chat, and USB-logging artifacts whenever the exact Full recipe exists. RAK4631 repeater and room-server Ethernet images remain separate roles. Fresh installs default to logging off. Heltec V3 and base OLED V4 Full images also contain the former direct Wi-Fi MQTT Companion capability, configured at runtime through WebConfig, so their separate <code>companion_radio_wifi_mqtt</code> artifacts are omitted from canonical builds as well.</p> <p>When Full Companion does not fit but a matching USB Companion does, that USB artifact also supplies Terminal Chat and replaces its standalone release image. Heltec E290 and T190 now publish one Full USB + BLE + WiFi Companion; their old combined and single-transport names are explicit-build compatibility aliases. SSD1306 Full Companion builds use <code>set display.rotation 90|180|270</code>; <code>0</code> restores the board default, so a separate rotated release image is not recommended.</p> <p>Ordinary non-OTA roles also use one artifact for normal operation and USB logging. On ESP32 1.17.1.5, run <code>set powersaving off</code> before <code>set usb.logging on</code>. Select the saved mode with <code>set usb.logging off|on</code>; no <code>-logging-</code> artifact is emitted. KISS, BLE-only Companion, and constrained LoRa OTA repeater images retain their protocol/partition contracts and do not inherit plaintext USB logging.</p> <p>nRF52 Full Companion keeps the multi-role primary interface on <code>00</code>; it starts as an ASCII terminal and automatically hands a complete <code>&lt;</code> frame to Binary Companion. <code>set usb.logging on reboot</code> adds its plaintext interface <code>02</code>.</p> <p>Every ESP32 Full Companion instead exposes one USB TTY. Logging is off by default, so the TTY serves the ASCII/Binary Companion switcher. On 1.17.1.5, run these two text commands to enable USB logging:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>The second command turns that same TTY into an input-capable plaintext CLI/logging stream; framed Binary Companion is unavailable on USB while logging owns it. <code>set usb.logging off</code> stops the logs and leaves the TTY in the normal ASCII terminal, matching a fresh Full installation. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch from there to Binary Companion. BLE and Wi-Fi Companion remain usable while the USB TTY is logging. ESP32 Full builds use the repository's Arduino-ESP32 2.x base where the board supports it; RC32 and ESP32-C6 retain their board-required Arduino 3.x platform but still expose only one USB TTY. A second ESP32 CDC interface is not part of the release profile.</p> <p>The picker includes the power-saving workaround when selecting USB or USB + WiFi logging on ESP32 1.17.1.5. WiFi/MQTT-only logging does not need it while the Repeater/Room Server bridge is running; check <code>get mqtt.running</code>. The workaround is not added to nRF52 directions. See logging by role for the saved settings and the original firmware's USB sleep issue.</p>"},{"location":"firmware_picker/#companion-usb-terminal-on-linux","title":"Companion USB terminal on Linux","text":"<p>Full, USB and USB + Bluetooth Companion results include Companion USB terminal (Linux / Bash) under Restore your settings after flashing, with copyable connection and recovery commands.</p> <p>Updated 1.17.1.6 USB Companions default to ASCII at boot and after an observable USB session reset. <code>picocom -b 115200 /dev/ttyACM0</code> is sufficient for a fresh session. A valid framed app command automatically selects Binary Companion. The command below also works with older firmware or a port left in Binary mode.</p> <p>Run this in Bash on the Linux computer connected to your radio:</p> <pre><code>picocom -b 115200 --imap spchex \\\n  --initstring $'\\r+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre> <p>Replace <code>/dev/ttyACM0</code> with your radio's port, such as <code>/dev/ttyACM1</code> or <code>/dev/ttyUSB0</code>. Use the primary USB data interface (<code>00</code> when multiple interfaces appear), and close other apps using it. The init string requests the ASCII CLI; its leading carriage return clears an unfinished input line. <code>--imap spchex</code> displays binary control bytes safely during the transition.</p> <p>If the terminal display is scrambled, exit picocom with Ctrl+A, then Ctrl+X, run <code>reset</code> in your Linux shell, then reconnect with the command above. At the radio prompt, run <code>version</code> and <code>board</code> to identify the node. See the Companion USB mode guide.</p>"},{"location":"firmware_picker/#companion-tempradio2-transmit-settings","title":"Companion tempradio2 transmit settings","text":"<p>LoRa Companion results for 1.17.1.6 and newer include Companion tempradio2: transmit on both under Restore your settings after flashing. After configuring <code>tempradio2</code> in <code>rxtx</code> mode, choose Transmit on both to copy:</p> <pre><code>set radio2.cross on\n</code></pre> <p>This copies new messages to both <code>radio</code> and <code>tempradio2</code>. The setting is saved, outlasts the temporary session and reboot, and also allows OTA traffic to cross profiles. Default isolation copies <code>set radio2.cross auto</code>; Check shows the temporary profile, crossing policy and per-profile transmit counters. See the two-profile setup guide.</p>"},{"location":"firmware_picker/#installation-methods","title":"Installation methods","text":"File Use <code>-merged.bin</code> Erase/fresh install, recovery, role migration, or partition-profile change on ESP32 over USB Non-merged <code>.bin</code> Update an existing same-board, same-role, same-partition installation <code>.zip</code> Native nRF52 Serial DFU update package; it is not an extra archive <code>.uf2</code> UF2 bootloader drag-and-drop install or update <code>.hex</code> Erase/recovery flash with a supported wired programmer <p>Never send a merged ESP32 image through browser OTA or LoRa OTA. Back up the node configuration and verify every filename suffix before flashing.</p>"},{"location":"firmware_picker/#lora-ota-and-otafix","title":"LoRa OTA and OTAFIX","text":"<p>A LoRa OTA repeater build installs repeater firmware that can receive and stage updates. A later LoRa update still needs an exact target identity, compatible partition signature, matching radio settings, and the correct update package.</p> <p>nRF52 LoRa OTA requires an OTAFIX bootloader built for the exact board. There is no universal bootloader file. Use the OTAFIX 2.4.6 for this release and select the hardware-matched HEX, Serial DFU ZIP, or bootloader-update UF2.</p>"},{"location":"firmware_picker/#hardware-and-variant-names","title":"Hardware and variant names","text":"<p>Hardware families with multiple released targets get a second hardware-variant menu. It separates revisions, display type, expansion kit, radio/PA layout, pin map, and other physical differences without crowding the first menu. The firmware-variant menu separately exposes choices that still require different code or wiring, such as serial port or the legacy <code>no_external_sensors</code> target suffix. For RAK3401 and RAK4631, the picker labels that compact LoRa OTA option Internal storage (no external storage board). Its result details explain the omitted optional environmental/ranging sensor drivers; the reduction does not disable generic I2C or unrelated board-integrated peripherals. Other boards retain the Reduced optional environmental/ranging drivers label. Reduced RAK3401 and RAK4631 targets retain INA219/INA226/INA260/INA3221 as voltage/current entries in the optional sensor table. They are not the only I2C users: the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals in compatible recipes. RAK12501/L76K GPS uses Serial1 instead. The explicit RAK4631 Serial1 bridge omits the combined GPS provider because its bridge owns the RAK12501 UART, so that legacy image does not expose RAK12500 either. The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>; to install both, keep RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>. Companion power saving, controllable FEM receive gain, and radio-chip receive gain are saved settings rather than separate recommended firmware files. Do not substitute a similarly named physical target.</p> <p>The header-wired RAK19007 W25Q16 LoRa-OTA recipes are also exact hardware variants, labeled External storage board (W25Q16) in the picker. W25Q16 is the flash-memory part on the added storage board; RAK13302 identifies the radio module, not the storage board. Choose this variant for RAK4631 or for RAK3401 + RAK13302 only when that core/radio combination, the <code>EF4015</code> flash wiring, and its matching OTAFIX bootloader are all present. The common base-board wiring does not make the two firmware or bootloader identities interchangeable.</p> <p>The picker recommends one Full Companion image instead of separate USB, BLE, ordinary WiFi, and USB-logging images. On ESP32, logging is off by default so the one USB TTY starts in ASCII and automatically changes to framed Companion when a complete <code>&lt;</code> frame arrives. Enabling logging gives that TTY to the plaintext CLI/logger and disables framed USB Companion until logging is turned off and the normal ASCII-to-binary mode switch occurs. nRF52 Full Companion retains its optional dedicated interface <code>02</code>. Exact filename search still finds old aliases from earlier releases.</p> <p>For same-partition ESP32 infrastructure migrations, the picker similarly recommends the ordinary target's exact-identity Full image when it is present. The former observer-named Full image remains available through exact filename search for deployed devices that still use that mOTA identity; it is not shown as a second recommended configuration.</p> <p>Some normal ESP32 roles begin in the legacy 1.25 MiB dual-OTA layout but have a canonical Full image with a larger partition table. Their Full image keeps the ordinary target identity for future mOTA updates, but the first install is always its exact <code>-merged.bin</code> over USB: LoRa mOTA intentionally rejects a package whose partition signature differs from the running layout. During this transition the portable artifact remains published for already-installed nodes. The current migration set is LilyGo T3S3 SX1262/SX1276 repeater and room-server roles, Station G2 repeater and room-server roles, and ThinkNode M2 repeater and room-server roles. Station G2 moves to two 6.25 MiB slots; the 4 MiB T3S3 and ThinkNode M2 boards move to two 1984 KiB slots.</p>"},{"location":"firmware_picker/#maintaining-the-runtime-directions","title":"Maintaining the runtime directions","text":"<p>The online picker and downloadable HTML use the same command renderer. Hardware-specific controls are enabled only when <code>_data/firmware_controls.json</code> matches the selected release family and exact target. If that metadata is missing or belongs to another release, the picker retains basic role/logging directions and links the complete guide without inventing hardware support. For 1.17.1.6, that JSON also records the verified LoRa OTA role of each image and USB logging modes where the packaged application was checked. Logging metadata is tied to the source hash of its firmware file. The normal iKoka 30 dBm repeater has USB logging and LoRa OTA; its compact no-external-sensors image has LoRa OTA without logging. Capacity directions come from each qualified profile's recorded reductions and are tied to the source hash of the selected download. The older 1.17.1.5 USB sleep workaround stays limited to that release.</p> <p>After qualifying a new release, resolve its PlatformIO configuration with no other PlatformIO process running, then generate the controls from that source revision and its staged manifests:</p> <pre><code>pio project config --json-output &gt; /tmp/meshcore-picker-pio-config.json\npython3 scripts/generate_picker_controls.py \\\n  --stage /path/to/staged-release \\\n  --pio-config /tmp/meshcore-picker-pio-config.json\n</code></pre> <p>Refresh the <code>data-controls-url</code> version query when publishing the generated metadata so browsers fetch the new release's controls.</p> <p>For the downloadable version, save the release family's public GitHub release objects as a JSON array, then package the same picker UI and controls:</p> <pre><code>python3 scripts/package_firmware_picker.py \\\n  --releases-json /path/to/releases.json \\\n  --output /path/to/FIRMWARE-PICKER.html\n</code></pre> <p>This HTML embeds its catalog and directions, so selections work without an internet connection. Firmware downloads and the USB web console still need network access. When replacing the downloadable picker on release pages, update its entry in each page's <code>SHA256SUMS.txt</code> as well.</p>"},{"location":"firmware_picker/#memory-corrected-11715-downloads","title":"Memory-corrected 1.17.1.5 downloads","text":"<p>Corrected downloads retain the 1.17.1.5 release page and use source suffix <code>aa20e927</code>, with <code>1e4d1e16</code> for Wireless Paper Full's 350-contact follow-up. The picker accepts replacement source hashes within that exact release version. Its installation directions identify the nRF52 queue-sharing behavior, Wireless Paper Full's 350 contacts with a shared 256/128-slot queue, and the 150-contact limit on the other six affected ESP32 Full profiles. Those notices apply only to the corrected files. See the memory correction details and each replacement's <code>.memory.json</code> report before updating.</p>"},{"location":"flood_filtering/","title":"Flood Filtering and Moderation","text":"<p>This guide explains the Keymind forwarding filters. Repeaters expose the full set of channel, rule, blacklist, and moderation controls described here. FULL-profile ESP32 room servers expose the generalized <code>flood.rule</code> table (and its <code>flood.filter</code> alias) with 31 forward-rule slots, but not the repeater's scope-rewrite, passive-blacklist, or text-moderation phases. Standard room-server profiles do not compile the rule table. Filters decide whether the node retransmits a packet and can assign a transport scope before that decision. They do not stop local reception, packet logging, or MQTT observation.</p> <p>Only flood routes are filtered:</p> <ul> <li><code>0x00</code> / <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> - flood routing with transport codes</li> <li><code>0x01</code> / <code>ROUTE_TYPE_FLOOD</code> - unscoped flood routing</li> </ul> <p>Direct routes <code>0x02</code> and <code>0x03</code> are never affected by these rules. The route and payload values follow the upstream packet-format reference and payload layouts, with this fork's LoRa OTA assignment noted below.</p>"},{"location":"flood_filtering/#automatic-flood-advert-limits","title":"Automatic flood-advert limits","text":"<p>Repeaters, room servers (including non-FULL builds), and forwarding sensors automatically limit relayed <code>ADVERT</code> packets. No CLI rule is needed. Companions and the repeater's receive-only MQTT observer do not allocate this history. This is separate from discovery-response limits, self-advert timers, hop caps, and the per-rule <code>rate=N/min</code> setting below.</p> <p>The ordinary quota is shared by the first 12 public-key hex characters (six bytes of the advertised origin key, not a path hash). Each prefix has a fixed 180-minute window starting with its first tracked valid flood advert.</p> Shortest received hops in that window Distinct adverts forwarded per 180 minutes 0\u20131 10 2 9 3 8 4 6 5 5 6 4 7 3 8+ 2 <p>The minimum received hop count, before adding this relay, sets the quota; one-, two-, and three-byte path hashes have the same policy. A shorter valid duplicate may increase the quota without restarting the window or clearing its count. Longer routes never decrease the allowance during that window. The payload signature must verify before any history changes. Path metadata itself is not signed, so this is a received-distance heuristic, not proof of physical distance.</p>"},{"location":"flood_filtering/#continuing-abuse-and-recovery","title":"Continuing abuse and recovery","text":"<ul> <li>A full public key that exceeds the normal level in one window receives a   first strike. If it exceeds that level again in the immediately following   window, it enters the bad list. A quiet intervening window breaks this chain.</li> <li>Escalation is deliberately conservative: once a key enters the bad list,   a later shorter route does not undo that decision, even if the increased   quota makes the current window fall below the normal level. This applies to   shorter duplicate and new adverts, including a matching-prefix key's route.   The existing restriction remains until seven-day recovery, manual clear, or   reboot; a shorter route alone never erases a recorded violation.</li> <li>The bad list matches all 32 public-key bytes, not the prefix. Different   full keys sharing a prefix share the ordinary forwarding quota, but their   received counts are not combined to accuse an innocent key of ongoing abuse.</li> <li>A bad-listed key may have at most one distinct advert forwarded every   12 hours, measured from its last admitted forward (including before   escalation). Ordinary forwarding filters still apply.</li> <li>Removal requires seven uninterrupted days without exceeding the normal   hop-based level. Recovery is measured against received distinct adverts,   not the much smaller number allowed to be forwarded. Silence also qualifies.</li> <li>Each over-limit window restarts recovery from that window's end. Continued   abuse can therefore extend the restriction indefinitely; it does not expire   automatically seven days after the first offence.</li> </ul>"},{"location":"flood_filtering/#inspect-the-current-limits","title":"Inspect the current limits","text":"<p>Use <code>get flood.advert</code> to list rate-limited origins, three per page. Continue with <code>get flood.advert 2</code>, etc. Rows show a 12-hex public-key prefix, the reason (<code>quota</code>, <code>history</code>, or <code>bad</code>), and the wait before another new advert is eligible under the automatic limiter. <code>get flood.advert key 1</code> shows the full key and counters for row 1, including the remaining bad-list recovery time. A bad-listed key remains visible with <code>wait=0s</code> when its next single forward is due. Prefix collisions appear as separate full-key entries.</p> <p>This is a live, read-only view: expiry can change row indices between queries, but reading never resets quotas or extends recovery. Sources rejected solely because the protected-history table is full are not retained, so they cannot be listed. See the CLI reference.</p>"},{"location":"flood_filtering/#clear-history","title":"Clear history","text":"<p>All timers use rollover-safe uptime, so setting the clock forward or backward cannot clear the restriction. This history is currently RAM-only: rebooting the relay clears it, and time while powered off is not tracked. A manual clear also resets both the ordinary quota and abuse history for its selected target:</p> <pre><code>clear flood.advert all\nclear flood.advert &lt;64-hex-full-public-key&gt;\n</code></pre> <p>These use the ordinary local/admin CLI authorization, including authenticated admin LoRa CLI. A prefix is never accepted for a targeted clear; missing or invalid selectors do not clear anything. Clearing an exact key preserves other full keys even when their 12-hex prefixes match. No preferences, contacts, neighbours, replay timestamps, or manually configured flood rules are erased.</p>"},{"location":"flood_filtering/#scope-and-resource-bounds","title":"Scope and resource bounds","text":"<p>Only forwarding is suppressed. Valid adverts remain available to local contact/neighbour handling and can still appear in raw RX logs or MQTT. This cannot prevent the origin or upstream repeaters from transmitting. Direct adverts, discovery control responses, messages, OTA packets, and this node's own scheduled adverts are not charged. Existing physical retry attempts of an admitted advert are not additional distinct adverts.</p> <p>The limiter retains up to eleven 64-bit payload hashes per full key per window: ten possible ordinary admissions plus evidence of exceeding the largest quota. Paths and transport scopes do not change these hashes. Retained duplicate hashes cannot consume additional quota even if the general packet-seen cache has evicted them. Once the eleven distinct receive slots are full, additional unretained payloads are suppressed until the next window. Only packets passing all ordinary forwarding gates consume forwarding quota; valid received traffic still supplies abuse evidence when another gate blocks it.</p> <p>The default is 128 full-key slots (18,432 bytes of entry storage plus small bookkeeping), 96 on nRF52 (13,824 bytes, preserving the mOTA runtime RAM reserve), or eight on RAM-constrained STM32 builds (1,152 bytes). <code>FLOOD_ADVERT_SOURCE_SLOTS</code> overrides the capacity at compile time. When full, the least-recently-heard normal key is removed first. Valid retained duplicates update last-heard too. Evicting a normal key discards its ordinary quota history, so capacity should still be sized for the deployment's active origins. First-strike evidence and bad-list entries are protected from eviction: if every slot protects abuse history, untracked origins are not forwarded until a slot expires or an administrator clears history. Table churn cannot erase an existing bad-list penalty. No heap allocation or per-packet filesystem writes are used.</p>"},{"location":"flood_filtering/#before-making-changes","title":"Before making changes","text":"<p>On a repeater, show the current forwarding controls:</p> <pre><code>get repeat\nget flood.max\nget flood.max.unscoped\nget flood.max.advert\nget flood.channel.data\nget flood.channel.data.hops\nget flood.channel.scope\nget flood.channel.scope.require\nget flood.filter\nget flood.rule\nget flood.filter.blacklist\nget flood.moderation\n</code></pre> <p><code>flood.rule</code> is an alias for <code>flood.filter</code>, not another table. Generalized repeater FPF7 has 63 forward-rule slots plus scope-rewrite and shared-blacklist sections in the same atomic policy file. FULL room servers have 31 forward slots and empty repeater-only sections. Compact target profiles retain their separate FPF6-era controls. <code>flood.moderation</code> has 16 slots. A new repeater FPF7 table starts with <code>ota all suspend=tempradio</code> in slot 1 and an authenticated <code>#wardriving hops=5+</code> radio drop in slot 2, and an authenticated <code>#wardriving hops=all mode=bridge,cross</code> drop in slot 3. FULL room servers seed only the OTA row; their generalized engine also accepts transport-mode rules. <code>flood.moderation</code> starts empty. A row can opt into <code>suspend=tempradio</code>; temporary radio is not synonymous with OTA and can carry normal packet types too. A corrupt or truncated table fails open, so corrupt storage does not silently enable blocking.</p> <p>On a FULL ESP32 room server, use <code>get flood.rule</code> (or <code>get flood.filter</code>) for the available table. Remote rule changes require room-server administrator access. <code>flood.filter.blacklist*</code> and <code>path=blacklist</code> are repeater-only; use the ordered <code>prefix=</code> condition on a room server.</p>"},{"location":"flood_filtering/#force-floods-into-a-transport-scope","title":"Force floods into a transport scope","text":"<p><code>flood.channel.scope</code> can add a scope to a received unscoped flood or replace the scope of a transport-scoped flood before this repeater forwards it:</p> <pre><code>set flood.channel.scope &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]\nset flood.channel.scope.&lt;slot&gt; &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]\nget flood.channel.scope\nget flood.channel.scope.&lt;slot&gt;\ndel flood.channel.scope.&lt;slot&gt;\ndel flood.channel.scope all\n</code></pre> <p>The channel may be <code>public</code>, <code>#channel</code>, or a 128/256-bit hex key. A bare target names an existing region with a usable transport key. Use <code>scope=&lt;name&gt;</code> instead to derive a regionless public hashtag scope exactly as <code>flood.filter scope=&lt;name&gt;</code> does. The direct name is normalized with a leading <code>#</code>, may contain up to 30 characters, and does not need a region-list entry. Keyed rules first check the one-byte channel hash carried in the packet, then validate the MAC by decrypting with the configured channel key. A hash collision alone cannot force a scope.</p> <p>For example, this authenticates only <code>#rgdata</code> and rewrites it to <code>#BlackHole86</code> without creating a region:</p> <pre><code>set flood.channel.scope #rgdata scope=BlackHole86\nget flood.channel.scope.1\n</code></pre> <p>If that channel arrives scoped to <code>#usa</code>, the rule replaces <code>#usa</code> with <code>#BlackHole86</code>. It also handles unscoped packets and replaces any other incoming scope; the source scope is not a condition on the rule.</p> <p>Add <code>path=blacklist</code> to make a channel-scope row eligible only when the received path matches the passive <code>flood.filter.blacklist</code> ID table. It does not require an enabled <code>flood.filter</code> drop row. With 3-byte paths, one exact listed ID qualifies. With 2-byte paths, two received path entries must match the first two bytes of listed IDs. A 1-byte path never qualifies.</p> <p>Use <code>path=bucket:&lt;1-6&gt;</code> to match one of the existing <code>flood.retry.bucket</code> tables instead. Each bridge bucket holds up to 17 three-byte IDs and remains usable by channel scoping while <code>flood.retry.bridge</code> is off. Bucket matching uses the same thresholds as the blacklist: one exact hit for 3-byte paths, two qualifying entries for 2-byte paths, and no matches for 1-byte paths. Channel scoping reads the configured IDs directly; <code>recent.repeater</code> freshness and <code>flood.retry.ignore</code> do not change this match.</p> <p>There are three independent wildcard classes:</p> <ul> <li><code>txt:*</code> handles otherwise-unmatched <code>GRP_TXT</code> and <code>GRP_DATA</code>; plain <code>*</code> is   its alias.</li> <li><code>login:*</code> handles <code>REQ</code>, <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code>.</li> <li><code>other:*</code> handles every remaining flood payload type, including flood-form   TRACE and OTA.</li> </ul> <p><code>login:*</code> and <code>other:*</code> classify only the visible outer payload type; they do not authenticate its contents. Exact channel rows with usable targets always take precedence over <code>txt:*</code>, even if that wildcard has a lower slot number. Within the exact class, matching path-qualified rows are tried before ordinary fallback rows. The same qualified-then-fallback order applies within each wildcard class. A missing or unusable target is skipped, so later rows remain eligible. The lowest usable slot wins within each priority tier.</p> <p>For example, this uses bridge bucket 1 to assign <code>east</code> to <code>public</code> packets whose received 3-byte path contains <code>7576FB</code>, and assigns <code>west</code> to all other authenticated <code>public</code> packets:</p> <pre><code>set flood.retry.bucket 1 7576FB\nset flood.channel.scope public west\nset flood.channel.scope public east path=bucket:1\n</code></pre> <p>More 3-byte IDs can be added to bucket 1 later. Any one of them qualifies the <code>east</code> row. Replacing or clearing that bucket changes which paths qualify but leaves both channel-scope rows intact. Bridge retry does not need to be enabled.</p> <p>On a successful match, an unscoped route changes from <code>ROUTE_TYPE_FLOOD</code> to <code>ROUTE_TYPE_TRANSPORT_FLOOD</code>; an already-scoped route remains transport-flood but receives replacement codes. Transport code 0 is calculated with the target region or direct hashtag key over the payload type and payload, and code 1 becomes zero. The change happens before region enforcement, forwarding filters, and deduplication. Consequently <code>flood.max.unscoped</code> no longer applies to a packet converted from unscoped, while <code>flood.max</code>, <code>flood.filter</code>, loop detection, and moderation still apply to every rewritten packet. A region target must be flood-allowed. A regionless target is trusted for this matched receive pass, but it neither creates a region nor changes how unrelated packets with the same transport code pass the region gate. By default, if the selected scope differs and the rewritten packet passes those checks, its initial retransmission uses zero <code>txdelay</code> and the highest outbound queue priority so the newly scoped copy can win at the next hop. Add <code>tx=slow</code> to use an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, retain normal outbound queue priority, and force the maximum <code>txdelay</code> factor of <code>2.0</code>. The actual transmit delay is still randomized, from zero through ten packet airtimes. It does not preempt an active radio transmission or bypass CAD and airtime-budget limits. Selecting the scope already present is a no-op and does not grant special treatment.</p> <p>Direct routes are never rewritten. Standard traceroute is direct-routed and therefore remains outside this flood-only table. A custom flood-form TRACE is treated like every other flood: an applicable wildcard may rewrite it and the normal region/unknown-code gates still apply. Scope assignment does not override normal payload validation or make an otherwise non-forwardable packet type forwardable.</p> <p>LoRa OTA (<code>0x0C</code>) falls under <code>other:*</code>. A matching row adds the selected transport code or replaces the existing one, but OTA still operates normally during the temporary-radio window because the OTA handler accepts both unscoped and transport-scoped flood routes. A region target must allow flooding; a direct target uses the regionless trust behavior above. A new repeater also seeds <code>ota all suspend=tempradio</code> in flood-filter slot 1. That visible rule blocks OTA forwarding at every received hop outside temporary-radio operation and is skipped while temporary radio is active. Independently, the OTA core refuses OTA receive, relay, and transmit outside an actually active temporary-radio window, even if the seeded row is deleted or replaced.</p> <p>Capacity is selected at build time:</p> <ul> <li>Roomy ESP32 builds: 255 rewrite slots and 32 regionless-target slots, 10,204   bytes RAM.</li> <li>Classic ESP32 repeaters, nRF52, and other normal   constrained builds: 31 rewrite and regionless-target slots, 2,108 bytes RAM.</li> <li>Very-tight STM32WL builds: 15 rewrite slots and one reusable regionless-target   slot, 572 bytes RAM.</li> <li>The no-PSRAM LilyGo T-LoRa V2.1 repeater/observer: 4 rewrite and   regionless-target slots, 272 bytes RAM. This minimum holds the   three wildcard classes and one exact channel mapping.</li> </ul> <p>Classic ESP32 uses the 31-slot default even on boards with PSRAM because these tables live in internal static DRAM. The separate channel-requirement table defaults to the same capacity and uses another 34 bytes per slot. Together, the 31-slot defaults save 15,712 bytes of static RAM compared with 255 slots. Custom builds can override <code>FLOOD_CHANNEL_SCOPE_SLOTS</code> and <code>FLOOD_CHANNEL_SCOPE_REQUIRE_SLOTS</code> with build flags.</p> <p>Each rule retains its 36-byte record. A separate table holds 32-byte normalized names for up to the smaller of the rule count or 32 distinct regionless targets, except that very-tight STM32WL builds retain one reusable direct target. Both configured regions and regionless targets can be reused by any number of rules.</p> <p>On generalized builds these records are the FPF7 rewrite phase, and the file stores only through the highest occupied slot. Compact FPF6 builds retain the standalone FCS5 file and the file sizes described by their build profile.</p>"},{"location":"flood_filtering/#require-valid-incoming-scopes-only-on-selected-channels","title":"Require valid incoming scopes only on selected channels","text":"<p><code>flood.channel.scope.require</code> changes region enforcement for received flood <code>GRP_TXT</code> and <code>GRP_DATA</code> packets from a global policy to a channel opt-in policy:</p> <pre><code>set flood.channel.scope.require &lt;public|#channel|128/256-bit-key&gt;\nset flood.channel.scope.require.&lt;slot&gt; &lt;public|#channel|128/256-bit-key&gt;\nget flood.channel.scope.require\nget flood.channel.scope.require.&lt;slot&gt;\ndel flood.channel.scope.require.&lt;slot&gt;\ndel flood.channel.scope.require all\n</code></pre> <p>An empty table preserves the normal global region behavior. Once at least one row exists, a group-channel packet that authenticates against a listed key must arrive as <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> with a transport code matching a locally flood-allowed region. An unscoped packet, an unknown transport code, or a code for a denied region is not retransmitted. The check uses the original incoming scope before <code>flood.channel.scope</code> or <code>flood.filter scope=</code> can rewrite it. Those rewrite actions are skipped for a rejected listed channel, so they cannot rescue it or grant special receive/transmit timing.</p> <p>Group-channel packets that do not authenticate against any listed key bypass the region/unknown-code forwarding gate. They still pass through <code>repeat</code>, <code>flood.max*</code>, <code>flood.filter</code>, loop detection, payload validation, and moderation. Non-channel flood payload types retain the normal global region behavior. A one-byte channel-hash collision is only a prefilter; the packet must also pass MAC validation/decryption with the configured key.</p> <p>Without <code>.slot</code>, setting an existing key updates its row and a new key uses the first empty row. Numbered <code>set</code> replaces that slot. Detail output displays only the first four derived hash bytes and key size, never the secret. The table has the same build-dependent slot count as <code>flood.channel.scope</code>; each row consumes 34 bytes of RAM and storage, plus a five-byte file header. ACL permission <code>4</code> can manage it.</p> <p>For example, this requires an allowed incoming scope on <code>#bot</code>, while every other group channel bypasses region enforcement:</p> <pre><code>set flood.channel.scope.require #bot\nget flood.channel.scope.require\n</code></pre>"},{"location":"flood_filtering/#interaction-with-duplicate-detection","title":"Interaction with duplicate detection","text":"<p>The seen-packet hash contains the payload type and exact payload bytes. It does not contain the route type, either transport code, or the ordinary flood path. For <code>TRACE</code> only, the encoded <code>path_len</code> byte is also included. Therefore an unscoped packet and the same packet after this repeater adds a transport code are the same duplicate. A later copy with a different scope is also the same duplicate; changing or adding scope cannot evade the seen table.</p> <p>When equivalent non-TRACE flood copies overlap in <code>rxdelay</code>, the normal receive-quality timing still chooses the packet to process, but that winner takes a scope from the queued copies whose transport code matches an allowed region in this repeater. Unknown and denied scopes are ignored. If eligible copies have different scopes, the shortest received path supplies the scope. Equal path lengths prefer the deepest matching child region (the narrowest configured scope). A remaining tie keeps queue order. The winner keeps its own path, SNR, and delay schedule; only its route and transport codes can change, including replacement of a less-preferred scope it already carried.</p> <p>Scope selection happens at dequeue so the original scopes remain available for comparison. It applies only while copies are queued and cannot alter a copy already processed into the seen table. Flood-form TRACE participates in the same arbitration. Direct traceroute never enters this flood queue.</p> <p>A packet that already matches a configured fast <code>flood.channel.scope</code> or <code>flood.filter scope=</code> action and needs its scope changed bypasses this inbound <code>rxdelay</code> queue entirely. A <code>tx=slow</code> row remains in the queue with twice the configured base, floored at <code>2.0</code>, and participates in normal queued-copy scope arbitration.</p>"},{"location":"flood_filtering/#runtime-flood-rules","title":"Runtime flood rules","text":"<p>On repeaters with the rule engine enabled and on FULL-profile ESP32 room servers, <code>fr</code>, <code>flood.rule</code>, and <code>flood.filter</code> name the same persistent table. The evaluator is fixed firmware, but every row is data, so an authenticated operator can add, replace, inspect, or delete a row without an OTA or reboot. Existing <code>flood.filter</code> commands remain compatible. Only FPF6 and FPF7 files are accepted; FPF1-FPF5 files are rejected and filtering fails open. A row saved by the extended engine uses FPF7. Older firmware cannot preserve an FPF7 table containing the packed <code>retry</code> action, one-byte <code>hash:XX</code> matcher, or <code>mode=bridge</code>/<code>cross</code> flags; remove those rows before downgrading. Old firmware rejects such a table and fails open, which disables its other filter rows too. New firmware loads older rows as <code>mode=radio</code> without changing their behavior.</p> <p>The former <code>flood.channel.block</code> table is now represented by ordinary FPF7 rows. On a generalized repeater, an existing FCB2 file is imported once into free FPF7 slots and then removed. For example, an old <code>#wardriving h=4</code> row becomes <code>type=any channel=#wardriving hops=5+ drop</code>. The 63-row table can hold all 31 former general filter rows, all 15 legacy channel-block rows, and the migrated global <code>flood.channel.data</code> gate. Compact STM32WL FPF6 builds cannot match authenticated channels and retain the older separate gate.</p> <p>On generalized repeaters, <code>flood.channel.data*</code> is a compatibility view over one ordinary visible FPF7 <code>type=grp_data ... drop</code> row. Turning it off creates or updates that row; turning it on removes the row. Its hop setting maps to <code>hops=all</code> or <code>hops=N+1+</code>. There is no hidden GRP_DATA forwarding check ahead of FPF7. Normal ordering applies, so a matching higher-priority <code>stop</code> row can exempt selected traffic. The compact rule list marks the managed row with <code>~data</code>.</p> <p>FPF7 binds <code>in=region:&lt;name&gt;</code> and <code>region=&lt;name&gt;</code> to canonical region names, not numeric region IDs. Removing, reordering, or reusing a region ID cannot silently redirect a rule. If the saved name is missing, an input-region match does not match and a target-region rewrite is skipped. Re-adding the same name reactivates the rule.</p> <p>The extended form is:</p> <pre><code>set flood.rule[.&lt;slot&gt;] type=&lt;type&gt; [mode=radio|bridge|cross|bridge,cross]\n    [hops=&lt;range&gt;] [channel=&lt;channel&gt;]\n    [prefix=&lt;ID[,ID...]&gt;] [in=&lt;input-scope&gt;] &lt;action&gt; [rate=&lt;N&gt;/min]\n    [priority=&lt;0-255&gt;] [stop] [tx=fast|slow] [suspend=tempradio]\nget flood.rule\nget flood.rule.&lt;slot&gt;\ndel flood.rule.&lt;slot&gt;\ndel flood.rule all\n</code></pre> <p>The command must be entered on one line. Match fields in one row are ANDed. Radio rows are matched against the same immutable packet state captured on receive, before any rule rewrites its scope. Bridge/cross rows match at their transport boundary. Only rows for the current mode participate in ordering and stop processing. Matching rows are then processed by descending numeric <code>priority</code>. At an equal numeric priority, authenticated channel matches run before raw <code>hash:XX</code> matches, raw hashes run before <code>channel=*</code>, and lower slot number breaks the remaining tie. Priority defaults to <code>0</code>; an explicitly higher numeric priority overrides specificity.</p> <p>Numbered examples replace the selected slots, including factory defaults. Omit the slot number to add a rule without replacing an occupied slot.</p> <p>The first matching <code>stop</code> row ends the FPF7 forward phase after that row. Higher-order matches and the stop row still apply; lower-order matches do not. A stop-only row is therefore an exception to lower-priority FPF7 rows. It cannot undo a higher-priority drop and it does not bypass hard forwarding gates or the scope-rewrite and moderation phases. Without a stop row, matching drop and rate rows remain independent and the highest-order matching scope or region rewrite wins.</p> <p>Match fields:</p> <ul> <li><code>type=</code> accepts the same packet names and numeric values as legacy   <code>flood.filter</code>. The positional form remains accepted.</li> <li><code>hops=</code> accepts <code>all</code>, <code>N</code>, <code>N+</code>, or <code>N-M</code>. The positional form remains   accepted. Received hops over 3 are written as <code>hops=4+</code>.</li> <li><code>mode=radio|bridge|cross|bridge,cross</code> selects the admission phase; omitted   means <code>radio</code>. See bridge and crossover filtering.</li> <li><code>channel=*|public|#name|hash:XX|128-bit-key|256-bit-key</code> optionally narrows by   channel. <code>channel=*</code> is an unconstrained wildcard: it performs no channel   authentication and matches every payload selected by <code>type=</code>. Thus   <code>type=any channel=*</code> means every flood payload type. <code>public</code>, <code>#name</code>, and   raw keys authenticate one channel and narrow the row to <code>GRP_TXT</code> or   <code>GRP_DATA</code>. <code>hash:XX</code> compares only the visible one-byte group-channel hash.   <code>short:XX</code> and a bare two-digit byte are aliases; saved output uses   <code>hash:XX</code>. This matcher is unauthenticated, has a 1-in-256 collision space,   and can be selected by a sender, so prefer an exact name or key when known.   <code>hash:11</code> is not an alias for Public: it includes Public and every <code>0x11</code>   collision, while <code>public</code> verifies and decrypts with the Public key. This is   channel authentication, not sender authentication: the group MAC is two   bytes and the Public key is shared.</li> <li><code>prefix=</code> is a source-path prefix containing one to three comma-separated   pbyte IDs. Every ID must use the packet's pbyte width: 2, 4, or 6 hex   characters for 1-, 2-, or 3-byte paths. Order matters and matching begins at   the first received path entry. <code>path=&lt;prefix&gt;</code> is an alias;   <code>path=blacklist</code> retains its separate unordered-list behavior.</li> <li><code>in=any|none|scoped|allowed|unknown|scope:&lt;name&gt;|region:&lt;name&gt;</code> tests the   original incoming route before any rewrite. <code>none</code> means an unscoped flood;   <code>scoped</code> means any transport flood; <code>scope:name</code> compares the exact public   hashtag-derived scope; and <code>region:name</code> compares an allowed configured   region. <code>allowed</code> is the legacy <code>require=region</code> test and includes an   unscoped packet when the wildcard region allows it. <code>unknown</code> means a scoped   packet that does not resolve to an allowed local region.</li> </ul> <p>Actions:</p> <ul> <li><code>drop</code> prevents retransmission when the row matches. The strict   <code>flood.rule</code> form requires an explicit action. For backward compatibility,   only a legacy <code>flood.filter</code> row with no rewrite, rate, or stop action means   drop implicitly.</li> <li><code>scope=&lt;name&gt;</code> derives a public transport scope directly from the name; no   region entry is consulted. <code>scope=BlackHole86</code> is therefore a valid   regionless sink. <code>region=&lt;name&gt;</code> is different: it resolves a configured,   flood-allowed region and one of that region's transport keys.</li> <li>A <code>stop</code> on a row whose <code>region=</code> target is currently unusable is also inert,   allowing lower-priority safety rules to run. Direct <code>scope=</code> targets do not   have this configuration dependency.</li> <li><code>rate=N/min</code> is a per-node, per-row fixed one-minute forwarding limit. It can   stand alone or accompany a scope/region rewrite. Quota is charged only after   every other forwarding gate, including moderation, accepts the packet. It is   not keyed per sender; use <code>flood.moderation</code> when a group-text rate must be   tied to an exact display name.</li> <li><code>retry</code> allows a matching received flood to start the configured retry   sequence. <code>retry=on</code>, <code>retry=allow</code>, and <code>action=retry</code> are aliases. If the   table has no active <code>retry</code> rows, global retry behavior is unchanged. If it   has one or more, those rows are a retry allow-list: at least one must remain   in the ordered, stop-truncated match set. The action may accompany rewrite,   rate, or stop, but not <code>drop</code>; its compact flag is <code>f=r</code>.</li> <li><code>priority=0-255</code> controls the primary processing order. Higher values run   first. Equal values use automatic channel specificity (authenticated, then   raw hash, then wildcard) before slot order. <code>pri=</code> is the compact alias.</li> <li><code>stop</code> (or <code>action=stop</code>) applies this row and prevents lower-order FPF7 rows   from acting. It can stand alone or accompany drop, rewrite, or rate.</li> </ul> <p>When several rows use the same channel key, authentication is performed once for that packet and reused by those rows. This cache lives only for the current receive evaluation; it is not persisted and never stores plaintext or a password. A <code>hash:XX</code> row deliberately skips authentication and uses only the one visible byte.</p> <p>The global retry controls remain hard gates. A <code>retry</code> row does not override a zero <code>flood.retry.count</code>, path/type attempt caps, disabled forwarding, <code>flood.retry.advert</code>, a drop verdict, or any other forwarding rejection. <code>flood.retry.bridge</code> independently chooses ordinary retry or bridge-bucket completion for an allowed packet. The selector applies to received floods; locally originated floods retain the normal global behavior.</p> <p>The exact requested examples are:</p> <pre><code># If #rgdata arrives unscoped with more than 3 received hops, add\n# the regionless #BlackHole86 scope.\nset flood.rule.2 type=grp_data hops=4+ channel=#rgdata in=none scope=BlackHole86\n\n# Rewrite the exact incoming #usa scope to #BlackHole86 for #rgdata.\nset flood.rule.3 type=grp_data channel=#rgdata in=scope:usa scope=BlackHole86\n\n# Match a two-byte source-path prefix and cap forwarding at 10 per minute.\nset flood.rule.4 type=any prefix=860C rate=10/min\n\n# Keep authenticated #rgdata at two hops or less out of lower-priority FPF7\n# rules. Hard gates and separate tables still apply.\nset flood.rule.5 type=grp_data hops=0-2 channel=#rgdata priority=200 stop\n\n# Retry received Public and #hamradio floods, using bridge completion.\n# Once these rows exist, other received floods are not retried.\nset flood.retry.bridge on\nset flood.rule.6 type=any channel=public retry\nset flood.rule.7 type=any channel=#hamradio retry\n\n# Fall back to an unauthenticated one-byte match if only the visible hash is known.\nset flood.rule.8 type=any channel=hash:A7 retry\n\nget flood.rule.2\nget flood.rule.3\nget flood.rule.4\n</code></pre> <p>Public's visible channel hash is <code>0x11</code>, so a <code>hash:11 drop</code> row also matches Public unless an earlier exact-channel rule stops it. This standalone example preserves authenticated Public while dropping other packets that use the same visible byte:</p> <pre><code>set flood.rule.2 type=any channel=public retry stop\nset flood.rule.3 type=any channel=hash:11 drop\n</code></pre> <p>The Public rule's MAC/decrypt check must succeed before its <code>stop</code> applies. A colliding channel misses that rule and reaches the hash drop. With equal numeric priorities, authenticated-channel specificity automatically puts the Public rule first regardless of slot order. Without <code>stop</code>, both rows match Public and the sticky drop wins. Remove <code>retry</code> from the Public row if the exemption should not also opt Public into flood retry. An explicitly higher numeric priority on the hash rule remains an operator override.</p> <p>The 240 KB STM32WL profiles keep <code>MESH_ENABLE_FLOOD_RULE_ENGINE=0</code> and retain the persistent compact FPF6 <code>flood.filter</code> and blacklist syntax below. They still perform filtering, but omit the generalized <code>flood.rule</code> parser and extended fields. No partition size is changed by this feature.</p> <p>The compatible filter and blacklist commands are:</p> <pre><code>set flood.filter.blacklist &lt;ID[,ID...]&gt;\nset flood.filter.blacklist.&lt;slot&gt; &lt;ID[,ID...]&gt;\nget flood.filter.blacklist\nget flood.filter.blacklist.&lt;slot&gt;\ndel flood.filter.blacklist\ndel flood.filter.blacklist.&lt;slot&gt;\nset flood.filter &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]\nset flood.filter.&lt;slot&gt; &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]\nget flood.filter\nget flood.filter.&lt;slot&gt;\ndel flood.filter.&lt;slot&gt;\ndel flood.filter all\n</code></pre> <p>The blacklist holds up to 255 unique 3-byte repeater IDs on ESP32 builds and 18 on other builds. Each is written as six hexadecimal digits. For example:</p> <pre><code>set flood.filter.blacklist A1B2C3,D4E5F6,112233\nset flood.filter.blacklist.4 445566\nset flood.filter any all path=blacklist\n</code></pre> <p>This is intended for abuse containment, such as refusing to retransmit floods that repeatedly enter the mesh through known internet gateways dumping bulk traffic. The list is shared by every FPF7 row and scope-rewrite row that uses <code>path=blacklist</code>; it is not copied into each rule.</p> <p>An unnumbered <code>set</code> replaces the list with up to 18 IDs, the largest command that fits every CLI transport. A numbered <code>set</code> writes a batch of up to 18 IDs beginning at an existing slot or the next consecutive slot. This is how an ESP32 list grows beyond 18. Deleting a numbered entry compacts the entries after it. Unnumbered <code>get</code> reports the total and prints the leading IDs that fit; numbered <code>get</code> retrieves one specific entry.</p> <p><code>path=blacklist</code> is an unordered precondition on that row. With 3-byte path hashes, one or more exact blacklist hits qualifies the packet. With 2-byte path hashes, two or more received path entries must match the first two bytes of listed IDs. Each received entry is counted at most once. A 1-byte path never qualifies. The IDs may occur anywhere in the received path; neither their list order nor their path order matters.</p> <p>Without a slot number, <code>set</code> reuses an identical row or selects the first empty slot. Use a slot number to replace a row whose match or action is changing. Omitting the hop expression means <code>all</code> (<code>0-63</code>).</p> <p>Numbered <code>get flood.rule.N</code> and <code>get flood.filter.N</code> normally use descriptive field names. On generalized builds, a reply that would be too long uses the complete <code>set fr.N ...</code> spelling below. <code>get fr.N</code> always requests that spelling. If even the short command exceeds one reply, it returns <code>Err - compact command exceeds reply size</code> instead of a partial command. Saving such a rule still succeeds and reports that its details exceed the reply size.</p>"},{"location":"flood_filtering/#shorthand-for-copying-rules","title":"Shorthand for copying rules","text":"<p>On generalized repeaters and FULL ESP32 room servers, <code>fr</code> is a shorter name for <code>flood.rule</code>. Both forms use the same parser, validation, permissions, and saved rows. Short and full field names can be mixed in either command. <code>fr</code> requires an explicit action, just like <code>flood.rule</code>.</p> <p>These commands set exactly the same rule:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nset fr.3 any c=#wardriving m=bc d\n</code></pre> Full form Short form Meaning <code>flood.rule[.N]</code> <code>fr[.N]</code> Same rule table for <code>get</code>, <code>set</code>, and <code>del</code>. <code>type=any</code> <code>any</code> or <code>*</code> First token: any payload type. Named/numeric types also work, with optional <code>t=</code>. <code>hops=N</code>, <code>N+</code>, <code>N-M</code>, or <code>all</code> <code>h=N</code>, <code>h=N+</code>, <code>h=N-M</code>, or <code>h=*</code> Hop condition; a bare range also works. Omitted means all hops. <code>mode=radio</code>, <code>bridge</code>, <code>cross</code>, <code>bridge,cross</code> <code>m=r</code>, <code>m=b</code>, <code>m=c</code>, <code>m=bc</code> Select the admission path. Omitted means radio; <code>cb</code>, <code>b,c</code>, and <code>c,b</code> also mean both transport paths. <code>channel=...</code> <code>c=...</code> Same authenticated name/key or explicit <code>hash:XX</code> matcher. <code>prefix=...</code> <code>p=...</code> Ordered path prefix. <code>path=blacklist</code> <code>p=bl</code> Shared unordered blacklist; repeater only. <code>in=any</code>, <code>none</code>, <code>scoped</code>, <code>allowed</code>, <code>unknown</code> <code>i=*</code>, <code>i=n</code>, <code>i=s</code>, <code>i=a</code>, <code>i=u</code> Incoming scope condition. <code>in=scope:name</code>, <code>in=region:name</code> <code>i=s:name</code>, <code>i=r:name</code> Match a specific incoming scope or region. <code>drop</code> <code>d</code> Drop matching traffic. <code>scope=name</code>, <code>region=name</code> <code>s=name</code>, <code>r=name</code> Rewrite to a public scope or configured region. <code>rate=N/min</code> <code>q=N</code> Per-row forwarding allowance. <code>priority=N</code> <code>pri=N</code> Higher values run first. <code>stop</code>, <code>retry</code> <code>s</code>, <code>r</code> Stop later rules or allow the configured flood retry. <code>tx=slow</code>, <code>suspend=tempradio</code>, <code>retry</code> <code>f=s</code>, <code>f=t</code>, <code>f=r</code> Flags can combine, for example <code>f=str</code>. <p>The <code>=</code> distinguishes <code>s=name</code> (scope) from <code>s</code> (stop), and <code>r=name</code> (region) from <code>r</code> (retry). Short forms keep the same action restrictions; for example, <code>m=bc r</code> is rejected because transport rules cannot enable retries.</p> <pre><code>get fr.3\n</code></pre> <p>Returns a complete command ready to copy:</p> <pre><code>set fr.3 any m=bc c=#wardriving d\n</code></pre> <p>The compact reply omits default values and prints specific payload types as numbers. <code>get fr</code> lists the table. <code>set fr ...</code> without a slot reuses an identical rule or adds it to the first empty slot. <code>del fr.3</code> removes slot 3; <code>del fr all</code> clears the forward rules.</p> <p>Private keys are still hidden in replies. A displayed <code>c=key:XXXXXXXX</code> is a local reference to the exact key in an active rule on that device, so it can be pasted to edit or copy a rule there. On another device, or after deleting the last rule holding that key, supply the original key instead. An unknown or ambiguous reference is rejected; it never becomes an unauthenticated channel-hash match.</p> <p>The shorthand does not rename <code>flood.channel.scope</code>, <code>flood.moderation</code>, or the blacklist-management commands. Companions and compact FPF6 profiles do not expose <code>fr</code>.</p>"},{"location":"flood_filtering/#scope-actions-and-legacy-rules","title":"Scope actions and legacy rules","text":"<p>A legacy row without <code>scope=</code> is the existing drop action. On extended builds, an explicit <code>drop</code> has the same result, while <code>rate=</code> by itself creates a rate-only row. A row with <code>scope=</code> adds transport scope to an unscoped packet or replaces the codes on an already-scoped packet. The scope name is normalized with a leading <code>#</code>, and the 128-bit transport key is derived directly from that hashtag. The name does not need to exist in the region list and is not added to it. Public names up to 30 characters are accepted; private <code>$</code> scopes are not.</p> <p><code>require=region</code> is the legacy spelling of <code>in=allowed</code>. The repeater evaluates the packet's original route before any rewrite in that receive pass. An incoming transport scope must match a locally allowed region; an unscoped flood must be allowed by the wildcard region. If the check fails, that row is skipped, the filter does not grant a region bypass, and the unchanged packet is allowed to fail normal region enforcement. Other independently configured scope rows still apply in their normal order.</p> <p>When multiple scope or region rows match, the highest numeric-priority row wins. Equal priorities use authenticated channel, raw hash, then wildcard specificity before the slot-number tie-break. Rewrite rows do not approve a packet: any matching drop row and every remaining forwarding gate can still reject it. A filter-assigned scope is trusted without local region-list validation, but <code>repeat</code>, <code>flood.max</code>, loop detection, and moderation still apply. By default, a changed scope bypasses inbound <code>rxdelay</code>, then is retransmitted with zero <code>txdelay</code> and the highest outbound queue priority. Add <code>tx=slow</code> to use an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, retain normal queue priority, and force the maximum <code>txdelay</code> factor of <code>2.0</code>; the randomized transmit delay ranges from zero through ten packet airtimes. <code>tx=fast</code> explicitly restores the default. Selecting the scope already present does not grant special treatment. Active radio transmission, CAD, and airtime-budget limits are unchanged.</p> <p>On generalized repeaters, forward rules, <code>flood.channel.scope</code> rewrite rows, the shared blacklist, and the <code>flood.channel.data</code> compatibility state are one atomic FPF7 policy image. Existing <code>/flood_ch_scope</code>, <code>/flood_filter_bl</code>, FPF6, and FCB2 data is imported once; the old files are removed only after the new image verifies and commits. Compact FPF6 repeaters retain separate files. Deleting the blacklist leaves <code>path=blacklist</code> rows in place but dormant until IDs are configured again. Path hashes are truncated routing identifiers and are not authenticated proof that a particular repeater\u2014or a particular person\u2014handled a packet. FULL room servers reject blacklist commands.</p> <p>On first initialization, flood-filter slot 1 is seeded with:</p> <pre><code>set flood.filter.1 0x0C all suspend=tempradio\n</code></pre> <p>This is a normal editable row. After the table has been saved, deleting it remains persistent across reboot; the firmware does not recreate it. Run the same command to restore the exact seeded row, or omit <code>.1</code> to preserve existing slot assignments and use the first empty slot. Operators may add <code>suspend=tempradio</code> to any other row that should be skipped while either <code>tempradio</code> or <code>tempradio2</code> is active. This includes scheduled temporary profiles. The row resumes once both temporary sessions have ended.</p> <p>Suspension does not approve a packet or bypass the rest of the filter table. It skips that row, then evaluation continues with the next row and the remaining forwarding gates. An ordinary drop <code>any</code> row therefore still applies during the temporary-radio window unless an earlier matching stop row ends FPF7 processing. <code>repeat</code>, <code>flood.max*</code>, region handling, loop detection, and the OTA subsystem's own hop limit also remain in force.</p> <p>Standard traceroute uses direct routing and bypasses <code>mode=radio</code> filters. Explicit bridge/cross filters can also match direct traffic at those transport boundaries; the built-in channel rule does not match TRACE packets. For a custom flood-form trace, <code>type=any</code>, explicit <code>trace</code>, scope, region, rate, and drop rows all behave normally. The stock core does not normally flood-forward TRACE packets.</p>"},{"location":"flood_filtering/#remote-administration-lockout-warning","title":"Remote-administration lockout warning","text":"<p>There are no hidden payload-type or short-hop exemptions in FPF7. Drop and rate rules can block <code>req</code>, <code>response</code>, <code>txt_msg</code>, <code>anon_req</code>, <code>path</code>, ACK, and multipart traffic beginning at hop <code>0</code> when their match fields say so.</p> <p>A flooded login starts as <code>ANON_REQ</code>; its reply is commonly a <code>PATH</code> packet carrying an encrypted <code>RESPONSE</code>. Before a direct return path is established, administrative replies and CLI text can also be flooded. Transit repeaters do not have the session key and cannot distinguish those encrypted admin exchanges from ordinary peer packets with the same outer type. A rule therefore affects the complete outer packet class, not only packets that ultimately authenticate as administrators. Keep a serial or other recovery path and stage broad deny/rate rules carefully.</p> <p>Hop expressions are based on the path count when this repeater receives the packet:</p> <ul> <li><code>N</code> matches exactly <code>N</code> received hops.</li> <li><code>N+</code> matches <code>N</code> or more received hops.</li> <li><code>N-M</code> matches the inclusive range.</li> <li><code>all</code> matches <code>0</code> through <code>63</code> hops.</li> <li><code>0+</code>, <code>all</code>, and omitting the hop expression are equivalent. <code>get</code> reports   the stored range using the canonical spelling <code>all</code>.</li> </ul> <p>Examples:</p> <pre><code># Stop forwarding group data once it arrives with four or more path entries.\nset flood.filter grp_data 4+\n\n# Stop long adverts, while still allowing shorter adverts.\nset flood.filter.2 advert 6+\n\n# Keep LoRa OTA floods from crossing this repeater at path counts 2 through 4.\nset flood.filter.3 ota 2-4\n\n# Assign #local scope to group text without requiring #local in the region map.\nset flood.filter grp_txt all scope=local\n\n# Rewrite only packets whose incoming region was already acceptable.\nset flood.filter grp_data all scope=local require=region\n\n# Rewrite matching blacklisted paths without fast-tracking their retransmission.\nset flood.filter grp_data all path=blacklist scope=local tx=slow\n\n# Drop matching flood types after the unordered path blacklist qualifies.\nset flood.filter.blacklist A1B2C3,D4E5F6,112233\nset flood.filter any all path=blacklist\n\n# Apply a hard ceiling to flood payload types at 12 or more received hops.\nset flood.filter any 12+\n</code></pre>"},{"location":"flood_filtering/#high-traffic-mesh-example","title":"High-traffic mesh example","text":"<p>This preset limits request and group-data propagation early while allowing the login-capable response, anonymous-request, and path types to travel farther:</p> <pre><code>set flood.filter req 3+\nset flood.filter response 9+\nset flood.filter 0x06 3+\nset flood.filter 0x07 9+\nset flood.filter path 9+\nset flood.filter control 1+\nget flood.filter\n</code></pre> Rule Stops retransmission when received with <code>req 3+</code> 3 or more path entries <code>response 9+</code> 9 or more path entries <code>0x06 3+</code> (<code>grp_data</code>) 3 or more path entries <code>0x07 9+</code> (<code>anon_req</code>) 9 or more path entries <code>path 9+</code> 9 or more path entries <code>control 1+</code> 1 or more path entries <p>On a new generalized repeater table, the three factory rules occupy slots 1 through 3, so these unnumbered commands normally fill slots 4 through 9. FULL room servers and compact tables seed only OTA and use slots 2 through 7. Existing tables may choose different free slots. All six rules take effect at the thresholds shown; there are no hidden short-hop exceptions. The Control rule allows a flood received with path count <code>0</code> to be forwarded once, then stops it at the next repeater. Normal node-discovery Control packets are direct zero-hop packets and bypass these <code>mode=radio</code> rules. These rules affect only retransmission by the repeater; local reception and logging remain unchanged.</p> <p>Accepted payload names are:</p> Value Short name Full name <code>0x00</code> <code>req</code> <code>PAYLOAD_TYPE_REQ</code> <code>0x01</code> <code>response</code> <code>PAYLOAD_TYPE_RESPONSE</code> <code>0x02</code> <code>txt_msg</code> <code>PAYLOAD_TYPE_TXT_MSG</code> <code>0x03</code> <code>ack</code> <code>PAYLOAD_TYPE_ACK</code> <code>0x04</code> <code>advert</code> <code>PAYLOAD_TYPE_ADVERT</code> <code>0x05</code> <code>grp_txt</code> <code>PAYLOAD_TYPE_GRP_TXT</code> <code>0x06</code> <code>grp_data</code> <code>PAYLOAD_TYPE_GRP_DATA</code> <code>0x07</code> <code>anon_req</code> <code>PAYLOAD_TYPE_ANON_REQ</code> <code>0x08</code> <code>path</code> <code>PAYLOAD_TYPE_PATH</code> <code>0x09</code> <code>trace</code> <code>PAYLOAD_TYPE_TRACE</code> <code>0x0A</code> <code>multipart</code> <code>PAYLOAD_TYPE_MULTIPART</code> <code>0x0B</code> <code>control</code> <code>PAYLOAD_TYPE_CONTROL</code> <code>0x0C</code> <code>ota</code> <code>PAYLOAD_TYPE_OTA</code> in this fork <code>0x0D</code> <code>13</code> reserved <code>0x0E</code> <code>14</code> reserved <code>0x0F</code> <code>raw_custom</code> <code>PAYLOAD_TYPE_RAW_CUSTOM</code> <p>Decimal values <code>0</code> through <code>15</code>, hexadecimal values <code>0x00</code> through <code>0x0F</code>, the full <code>PAYLOAD_TYPE_*</code> names, and <code>any</code> are also accepted. Upstream currently reserves <code>0x0C</code>; this fork assigns it to LoRa OTA. Rows are suspended during temporary-radio operation only when explicitly configured that way.</p>"},{"location":"flood_filtering/#moderate-group-text-by-channel-and-username","title":"Moderate group text by channel and username","text":"<p>Use <code>flood.moderation</code> for flood <code>GRP_TXT</code> messages. The repeater validates and decrypts the selected channel, extracts the display name before the first <code>:</code>, then applies the rule:</p> <pre><code>set flood.moderation &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]\nset flood.moderation.&lt;slot&gt; &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]\nget flood.moderation\nget flood.moderation.&lt;slot&gt;\ndel flood.moderation.&lt;slot&gt;\ndel flood.moderation all\n</code></pre> <p>Channels can be specified as:</p> <ul> <li><code>public</code> for the built-in Public channel</li> <li><code>#name</code> for a well-known hashtag channel</li> <li>a 128-bit or 256-bit channel key in hexadecimal</li> </ul> <p>The key is stored locally so packets can be authenticated and decrypted. It is not included in <code>get flood.moderation</code> output.</p> <p>Available actions are:</p> <ul> <li><code>drop</code> - do not retransmit any matching message</li> <li><code>rate=X/min</code> - retransmit at most <code>X</code> messages per local 60-second window</li> <li><code>hops=N</code> - do not retransmit when the received path count is <code>N</code> or higher</li> <li><code>path=H1[,H2,H3]</code> - require the first one to three path hashes to match</li> <li><code>path=*</code> - match every path; this is the default</li> </ul> <p>At least one of <code>drop</code>, <code>rate=X/min</code>, or <code>hops=N</code> is required. Rate and hop limits can be combined. <code>rate=0/min</code> is equivalent to <code>drop</code>.</p>"},{"location":"flood_filtering/#per-user-per-channel-rate-limits","title":"Per-user, per-channel rate limits","text":"<p>Rate limits require an exact username; <code>*</code> is not accepted for a rate rule. Username comparison is ASCII case-insensitive, and names containing spaces must be quoted. A rule's counter is independent from rules for the same name on other channels, so this directly supports \"X messages per minute from user X on channel Y.\" Counters are local to this repeater and reset on reboot.</p> <pre><code># At most five Public-channel messages per minute from this display name.\nset flood.moderation public \"Noisy User\" rate=5/min\n\n# A separate limit for the same name on #local.\nset flood.moderation #local \"Noisy User\" rate=10/min\n\n# Combine a rate limit with a maximum forwarding distance.\nset flood.moderation public alice rate=4/min hops=5\n</code></pre>"},{"location":"flood_filtering/#match-the-start-of-a-path","title":"Match the start of a path","text":"<p>Path matching accepts one-, two-, or three-byte hashes. Every hash in one rule must use the same width, and matching always starts at the beginning of the received path:</p> <pre><code>set flood.moderation #local bot drop path=A1B2C3,D4E5F6\nset flood.moderation public alice rate=3/min path=71\n</code></pre> <p>A path-qualified rule cannot match a zero-hop packet and does not match until the packet contains all path entries listed by the rule.</p>"},{"location":"flood_filtering/#how-the-forwarding-controls-combine","title":"How the forwarding controls combine","text":"<p>A flood packet is retransmitted only if it passes every applicable control. In other words, the controls combine as deny rules:</p> <ol> <li><code>flood.channel.scope.require</code> evaluates a listed group channel against the    original incoming scope; unlisted group channels bypass the later region    gate while the table is active.</li> <li><code>flood.channel.scope</code> tries a path-qualified channel row before that    channel's ordinary fallback, then adds or replaces the scope from either a    configured region or a direct <code>scope=&lt;name&gt;</code> target.</li> <li>All extended <code>flood.rule</code> match fields are evaluated against the same    original incoming packet. Matches are ordered by descending numeric    priority, then authenticated/raw-hash/wildcard channel specificity, then    ascending slot. The first matching <code>stop</code> row removes every later FPF7    match. The highest-order remaining <code>scope=</code> or <code>region=</code> row may replace the    channel-scope result; a direct scope does not require a region-list entry.</li> <li><code>repeat</code> and <code>flood.max*</code> are checked.</li> <li>The FPF7 forward phase, including any row managed through    <code>flood.channel.data*</code>, applies drop and rate decisions using that saved    match result. No packet type or short-hop range is silently exempted.</li> <li>Region and loop-detection rules are checked; a regionless scope assigned by    either table is already trusted when it has no region-list match, except    that it cannot rescue a channel rejected by    <code>flood.channel.scope.require</code>.</li> <li><code>flood.moderation</code> checks decrypted group text, username, rate, hops, and    path. If it accepts the packet, matching general-rule rate counters are    charged immediately before retransmission is approved.</li> </ol> <p>The first denial is enough to prevent retransmission. A packet that is denied can still appear in local logs or MQTT output, unless a separate <code>mode=bridge</code> rule blocks MQTT packet publication. Moderation runs last because its rate counters are charged only for packets that pass every other forwarding control and will actually be retransmitted.</p>"},{"location":"flood_filtering/#delegate-filter-management","title":"Delegate filter management","text":"<p>On repeaters, ACL permission <code>5</code> is the filter-manager role:</p> <pre><code>setperm &lt;companion-public-key-hex&gt; 5\n</code></pre> <p>A filter manager can read non-secret operational status and manage <code>repeat</code>, <code>loop.detect</code>, <code>flood.max*</code>, <code>flood.channel.data*</code>, <code>flood.filter*</code>, <code>flood.rule*</code>, <code>fr[.N]</code>, and <code>flood.moderation*</code>. Delegated <code>get</code> access uses an explicit allowlist: it cannot retrieve guest, WiFi, MQTT, bridge, or other credentials, and it cannot change regions, ACL entries, radio settings, or unrelated administrator settings. Because <code>flood.filter scope=</code> derives a public hashtag key directly, a filter manager can configure that action without region-manager permission; it still cannot edit the region hierarchy.</p> <p>FULL ESP32 room servers use their existing administrator check for remote <code>fr</code>, <code>flood.rule</code>, and <code>flood.filter</code> commands; they do not grant this table through permission <code>5</code>.</p> <p>ACL permission <code>4</code>, the region/scope-manager role, can read, add, replace, and delete <code>flood.channel.scope</code> and <code>flood.channel.scope.require</code> rows and manage regions. This lets the same delegate create target regions, assign forced scopes from regions or direct hashtag names, and select the channels that require valid incoming scopes.</p>"},{"location":"flood_filtering/#security-limitations","title":"Security limitations","text":"<p>Public and hashtag channels use shared, well-known keys. A valid channel MAC proves that the sender knew the channel key; it does not identify a person. The <code>&lt;sender&gt;</code> value is an unverified display name and can be spoofed. Path hashes are truncated routing hints and can collide or be manipulated; they are not authenticated user identities.</p> <p>Use username and path rules as traffic moderation, not as an authorization boundary. For a strict network boundary, combine these tools with region ACLs, private transport/channel keys, and controlled device access.</p>"},{"location":"flood_filtering/#filter-bridge-and-radio-crossover-traffic","title":"Filter bridge and radio crossover traffic","text":"<p>The <code>mode=</code> matcher selects a separate admission phase within the same <code>flood.rule</code> / <code>flood.filter</code> table:</p> Mode Where the rule applies <code>radio</code> Ordinary LoRa flood forwarding. This is the default when <code>mode=</code> is omitted. <code>bridge</code> Packets entering or leaving an RS232 or ESP-NOW bridge, and MeshCore RX/TX packet publication through MQTT. <code>cross</code> Transmissions copied to the other radio profile, including a copy's retries. The same-profile transmission remains eligible. <code>bridge,cross</code> Both transport paths using one rule. <code>cross,bridge</code> is equivalent. <p>The third built-in repeater filter is:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nget flood.rule.3\n</code></pre> <p>The equivalent short command is <code>set fr.3 any c=#wardriving m=bc d</code>. Use <code>m=b</code> for bridge only or <code>m=c</code> for crossover only.</p> <p>It authenticates both <code>GRP_TXT</code> and <code>GRP_DATA</code> against the public <code>#wardriving</code> channel key. A different channel with the same one-byte hash is not blocked. It covers every hop count, including zero-hop/local messages, flood routes and direct routes. It remains active during temporary-radio sessions and with <code>radio2.cross on</code>: enabling crossover makes a copy eligible, but does not override the filter. The second built-in rule still permits ordinary <code>#wardriving</code> forwarding through four received hops; the third rule keeps those messages on their originating radio profile.</p> <p>Bridge filtering runs in both directions before bridge deduplication, inbound queueing, serial writes, ESP-NOW queueing, or MQTT packet publication. It applies with either <code>bridge.source rx</code> or <code>bridge.source tx</code> and with wrapped or raw ESP-NOW framing. MQTT here is the observer packet output; this does not add MQTT-to-LoRa injection or filter MQTT status/telemetry. Local reception and local packet logs remain available. Switching one radio between profiles is covered by <code>cross</code>; the bridge's WiFi channel is a separate setting.</p> <p>Transport modes support <code>drop</code>, <code>rate=X/min</code>, <code>priority=</code>, and <code>stop</code>, with the existing type, channel, hops, prefix, blacklist, incoming-scope and <code>suspend=tempradio</code> matchers. Scope/region rewrites, retry actions, and TX timing actions are rejected in these modes. Ordering and <code>stop</code> apply only to rules in the current mode: a radio exception cannot bypass a bridge/cross drop. A combined rule shares one rate counter across bridge and cross admission attempts; retries count too. A rejected queue insertion can consume an admission allowance. Queued packets already admitted are not recalled by editing a rule. Same-profile transmissions use the ordinary radio policy.</p> <p><code>get flood.rule.N</code> shows <code>mode=</code>; the overview marks each row with its mode. Modes are persistent, case-insensitive, and apply immediately to new admission attempts. <code>radio</code> cannot be combined with <code>bridge</code> or <code>cross</code> in a single row. For transport rules, hop and scope matchers see the packet at that boundary: a TX/crossover packet can already contain an appended hop or rewritten scope. The built-in rule uses all hops and any scope, so these changes cannot bypass it. On FULL room servers, add a transport rule explicitly; their factory table still has only the OTA row. Companions and compact FPF6 builds do not expose this generalized filter table.</p> <p>Saved tables, occupied slots, and deleted defaults are preserved on upgrade. To add the new default to an existing table without replacing another rule, omit the slot number (repeating the identical command reuses its row):</p> <pre><code>set flood.rule type=any channel=#wardriving hops=all mode=bridge,cross drop\nget flood.rule\n</code></pre> <p>To allow only bridge traffic while retaining the crossover block, replace the third rule with <code>mode=cross</code>. Use <code>mode=bridge</code> to retain only the bridge block. Use <code>del flood.rule.3</code> to remove both, after checking that slot 3 is still the built-in rule. Removing it does not change the separate LoRa hop-limit rule.</p>"},{"location":"flood_filtering/#restore-the-factory-seeded-rows","title":"Restore the factory-seeded rows","text":"<p>The repeater's factory-seeded forwarding rows can be restored through the CLI:</p> <pre><code>set flood.rule.1 type=ota hops=all drop suspend=tempradio\nset flood.rule.2 type=any channel=#wardriving hops=5+ drop\nset flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>Or use the equivalent short forms:</p> <pre><code>set fr.1 ota d f=t\nset fr.2 any 5+ c=#wardriving d\nset fr.3 any c=#wardriving m=bc d\n</code></pre> <p>These commands explicitly replace the three seeded generalized-repeater slots. Inspect them first if they may now contain other rules. Compact FPF6 builds use only the first command's <code>flood.filter.1 0x0C all suspend=tempradio</code> form.</p>"},{"location":"flood_filtering/#remove-the-custom-rules","title":"Remove the custom rules","text":"<p>To save both tables in an empty state:</p> <pre><code>del flood.filter all\ndel flood.moderation all\nget flood.filter\nget flood.moderation\n</code></pre> <p>This does not change the older <code>flood.max*</code>, loop-detection, or region settings; inspect or reset those separately when troubleshooting.</p>"},{"location":"four_fixed_tx_dwell_validation/","title":"Four fixed transmitters: longer dwell repeats","text":"<p>Same physical MercerMesh fixture and installed firmware as the completed 5.1-symbol run: RAK4631, Heltec T096, MeshTower V2 and T1000-E fixed transmitters; Heltec V4 RX. SF10 / BW125 kHz / CR4/5, four channels spaced 1 MHz apart, 32-symbol preamble, normal SX1262 RX gain, -9 dBm chip TX setting, zero added settling and one frequency write per hop. No firmware was rebuilt or reflashed for these repeats.</p>"},{"location":"four_fixed_tx_dwell_validation/#61-symbol-run-user-stopped-incomplete-sample","title":"6.1-symbol run: user-stopped, incomplete sample","text":"<p>Started 2026-09-14 22:44:47 UTC. Dwell was 49,972 us per channel. All four stationary controls passed 100/100 again.</p> <p>The user requested stopping this run and proceeding to 7.7 symbols. The collector was interrupted only after verifying its PID, command line and owner. At the last saved checkpoint, 342/348 scored scan packets were received (98.28%), with six timeouts:</p> TX / channel Scored attempts Received Timeouts RAK4631 / 0 87 87 0 Heltec T096 / 1 87 86 1 MeshTower V2 / 2 87 85 2 T1000-E / 3 87 84 3 <p>This is not a completed 400-packet run or a validated full-run timing capture. An interrupted in-flight packet can exist beyond the last saved checkpoint; it is not scored as another success or failure. No final switch timing was collected before reboot. The raw capture remains incomplete, and the separate user-stop record documents why. All five radios were then independently verified idle, and ModemManager was restored. Gateway services stayed active; the V4 memory-soak service stayed inactive.</p> <ul> <li>Partial raw capture</li> <li>User stop record</li> <li>Verified cleanup</li> <li>Run provenance</li> </ul> <p>Partial raw capture SHA-256: <code>ad199124930da19fe56c78a4ea8280a6d94b95ef408589b19a9e165155dbf7fd</code>.</p>"},{"location":"four_fixed_tx_dwell_validation/#77-symbol-run","title":"7.7-symbol run","text":"<p>Launched 2026-09-14 22:58:14 UTC; collector ran from 22:58:15 to 23:11:45 UTC with 63,079 us visits. All four fixed-channel controls passed 100/100. The full scan completed with 395/400 received (98.75%), five timeouts and zero wrong-channel or invalid payloads. Thus 7.7 symbols did not achieve a 400/400 pass.</p> TX / channel Scanning result Timeouts Mean received RSSI (dBm) Mean received SNR (dB) RAK4631 / 0 100/100 0 -21.05 +8.14 Heltec T096 / 1 99/100 1 -4.35 +8.98 MeshTower V2 / 2 97/100 3 -44.86 +8.63 T1000-E / 3 99/100 1 -18.56 +8.26 <p>All 800 baseline/scan TX sequences were unique, all transmit calls succeeded, and every TX packet reported zero frequency and modulation configuration writes. There were zero packet-response transport replays. All four final TX lifetime checks reported 200 packets and a prepared, non-failed transmitter.</p> <p>The five timeouts occurred at scan attempts 158 (T1000-E), 184 (T096), and 200, 293, 314 (MeshTower). Each reported RX mode 1 and zero device errors. Final RX failure, RX-mode-error, cache-error and receive-error counters were zero.</p>"},{"location":"four_fixed_tx_dwell_validation/#measured-switch-and-sweep-timing","title":"Measured switch and sweep timing","text":"Hop population Count Minimum (us) Mean (us) Maximum (us) All single-pass switches 5,046 438 524.146 804 Cached modulation; no 0x8B 4,651 438 502.147 686 Post-reception modulation refresh 395 760 783.180 804 <p>Exactly 5,046 RF-frequency commands and 5,046 optimized RX resumes were counted, with one retune pass and zero second passes/detours. The 395 modulation writes match the 395 post-reception cache refreshes. This is the same cache behavior as the earlier run, not double-setting the radio. The slightly higher overall mean than the 5.1 run partly reflects a larger fraction of refresh hops.</p> <p>Across 860 measured idle cycles, the four-channel sweep averaged 254.351 ms, minimum 254.208 ms and maximum 255.482 ms. Relative to the 262.144 ms programmed preamble, that leaves 7.793 ms at the mean and 6.662 ms at the maximum. Nominal dwell was 63.079 ms; measured idle dwell averaged 63.084 ms. Packet-held visits include payload/guard time and are not comparable to idle cycles.</p> <p>The 7.7 run received three more packets than the earlier 5.1 run (395 versus 392 out of 400). This small, sequential comparison does not establish a reliable improvement or a lossless dwell threshold. The 6.1 result is partial and must not be treated as an equal-size completed comparison.</p>"},{"location":"four_fixed_tx_dwell_validation/#evidence-and-cleanup","title":"Evidence and cleanup","text":"<p>Unlike the original 5.1 run's overly strict host assertion, this collector completed normally with <code>complete: true</code> and exit code 0. Independent offline validation also passed. The same collector SHA-256 was used for both repeats: <code>cceb8a570f4aedeaf45d28b4b4590b23df3c1efd490c8e8e9cd74a23ba00024f</code>. The copied deployment/manifest files are provenance for reused firmware, not records of a new flash operation. Host options and acknowledged dwell match.</p> <ul> <li>Completed raw capture</li> <li>Validated summary</li> <li>Run provenance</li> <li>Cleanup readbacks and warnings</li> </ul> <p>Raw capture SHA-256: <code>5e3f9a80af1384c3072303428b75c8550ac42d2ac95bd1234bf92cb0aea625e8</code>.</p> <p>The cleanup wrapper retained three errors from its reboot phase: the T096 primary USB interface was temporarily missing/ambiguous, and attempts to open the MeshTower/T1000-E ports returned permission denied. Its subsequent final readbacks nevertheless succeeded for all five radios: each TX was unprepared, non-failed, packet count zero and autonomous TX disabled; RX scanning was inactive with zero channels. No further radio access or permission changes were attempted after those results returned. The wrapper's <code>verified_idle</code> flag remains false because it retains any earlier cleanup error, and the outer operation returned nonzero for that reason. These warnings happened after the complete RF sample; they are not counted as RF packet losses or silently removed from the record.</p> <p>ModemManager was restored active; gateway services remained active. The V4 memory-soak service remains inactive with test firmware installed. No firmware restore, commit, push or pull was performed. Previous raw captures are unchanged.</p>"},{"location":"four_fixed_tx_dwell_validation/#dwell-budget","title":"Dwell budget","text":"<p>One chirp at SF10/125 lasts 8.192 ms. For the experiment's nominal budget of one complete four-channel idle sweep inside 32 programmed preamble symbols:</p> <p><code>maximum dwell symbols = 32 / 4 - switching_ms / 8.192</code>.</p> <p>The 5.1-symbol run's mean switch (0.513980 ms) gives about 7.937 symbols; its maximum switch (0.801 ms) gives about 7.902 symbols, before other loop overhead. These are timing ceilings, not proven lossless dwell limits or a complete acquisition model. Near the ceiling there is little timing margin. At 7.7 symbols, four nominal dwell-plus-average-switch intervals total about 254.4 ms, versus a 262.144 ms programmed preamble.</p> <p>The host keeps the same seed and arrival-randomization rule, spanning about two nominal scan cycles; absolute arrival pauses therefore scale with dwell. The fixed-channel controls, sample counts, switching policy and firmware stay unchanged. As before, external PA/LNA paths and unrelated RF traffic mean this is a finite bench comparison, not a calibrated sensitivity or interference test.</p>"},{"location":"four_fixed_tx_single_pass_validation/","title":"Four fixed transmitters / fast single-pass receiver","text":""},{"location":"four_fixed_tx_single_pass_validation/#result","title":"Result","text":"<p>MercerMesh Pi bench run, started 2026-09-14 22:18:49 UTC (15:18:49 PDT): four physically separate, fixed-channel transmitters and the Heltec V4 receiver. The full stationary controls passed 400/400. The subsequent four-channel scan received 392/400 correctly (98%), with 8 timeouts (2%) and zero wrong-channel payloads. No RF retries were used.</p> TX / assigned channel Frequency (MHz) Fixed-RX control Scanning RX Scan mean RSSI (dBm) Scan mean SNR (dB) RAK4631 / 0 909.5 100/100 96/100 -20.69 +8.63 Heltec T096 / 1 910.5 100/100 98/100 -3.84 +8.45 Heltec MeshTower V2 / 2 911.5 100/100 100/100 -45.48 +8.41 Seeed T1000-E (LR1110) / 3 912.5 100/100 98/100 -18.27 +8.51 <p>RSSI/SNR describe received packets only. Each transmitter sent 200 unique packets across its baseline and scan. All 800 transmit calls returned success, with zero frequency or modulation commands during those packet calls. There were zero recovered/replayed USB responses in the packet records.</p>"},{"location":"four_fixed_tx_single_pass_validation/#switching-timing-and-command-evidence","title":"Switching timing and command evidence","text":"Hop population Count Minimum (us) Mean (us) Maximum (us) All single-pass switches 7,206 429 513.980 801 Cached modulation; no 0x8B 6,814 429 498.602 686 Modulation cache refresh 392 763 781.291 801 <p>The receiver recorded exactly 7,206 frequency commands and 7,206 optimized RX resumes: one frequency write and one resume per hop. Second-pass count was zero. Duplicate frequency writes, frequency/CR detours and added settling were disabled. Warm XOSC, bulk 8 MHz SPI and cached modulation were enabled.</p> <p>The average switch was 0.514 ms, but not every switch was below 0.6 ms. After each received packet, ordinary RX staging invalidates the modulation cache; the next hop refreshes it. Subsequent unchanged hops omit 0x8B. The 392 refreshes match the 392 received packets. The source path is <code>RadioLibWrapper::recvRaw()</code> -&gt; <code>startRecv()</code> / <code>startReceiveMode()</code> -&gt; <code>PhysicalLayer::startReceive()</code> -&gt; <code>CustomSX1262::stageMode()</code> -&gt; <code>SX1262ProfileSwitchState::invalidate()</code>. No production cache-invalidation behavior was changed for this test.</p> <p>Mean switch-plus-settling-instrumentation time was 515.698 us, maximum 803 us. The settling measurement averaged 1.718 us of timer/measurement overhead; the configured settling delay was zero. The idle four-channel sweep averaged 169.135 ms (maximum 170.470 ms), versus 262.144 ms for the 32-symbol preamble. Packet-held visits include reception/guard time and are not idle sweep timings. The <code>deferred</code> counter counts guard-loop deferrals, not lost packets.</p>"},{"location":"four_fixed_tx_single_pass_validation/#method-and-fixture","title":"Method and fixture","text":"<ul> <li>SF10 / 125 kHz / CR4/5; 32-symbol preamble; synthetic 16-byte CHS1 packets.</li> <li>Four channels spaced 1 MHz apart; 5.1-symbol RX visits (41,780 us).</li> <li>Each physical transmitter was configured once and remained on its assigned   frequency throughout both the controls and scanning.</li> <li>Receiver was reinitialized for each fixed-channel control and once before   the scan. All 100 control packets per transmitter were retained.</li> <li>Scan used 100 packets per channel, randomized channel order and arrival   pauses (seed 606125). Transmissions were staggered, not concurrent.</li> <li>Each expected packet had a 10-second scan timeout. Misses did not stop the   run, restart the scanner, force it onto the TX channel or trigger a retry.</li> <li>SX1262 normal RX gain was verified as register 0x94. The V4's external   KCT8103L front end remains distinct from the chip's boosted-gain setting.</li> <li>Requested TX power was -9 dBm at each radio chip. The Heltec TX boards have   external PA paths, held in TX mode by this HIL firmware; these are not   calibrated equal antenna-port powers.</li> <li>High-rate channel trace was disabled; command counters and timing remained   enabled. Gateway services remained running, so unrelated RF was not excluded.</li> </ul> Role Hardware serial / MAC Pi USB topology TX0 RAK4631 9AB3B64C641BA927 1-1.3.1 TX1 Heltec T096 651F8E496197F882 1-1.2.3 TX2 Heltec MeshTower V2 9352162A72082314 1-1.2.2 TX3 Seeed T1000-E LR1110 34A9141999729D5D 1-1.2.1 RX Heltec V4 44:1B:F6:69:CF:98 1-1.3.3 <p>Board selection checked serial plus topology, not transient tty names or CDC interface count. The RAK3401 gateway, serial 0B81C9C68D8D01B4, was excluded. The earlier local XIAO radios were not modified during this run.</p>"},{"location":"four_fixed_tx_single_pass_validation/#remaining-losses-and-interpretation","title":"Remaining losses and interpretation","text":"<p>Timeouts occurred at overall scan attempts 10, 14, 55, 65, 145, 299, 304 and 384. Thus they were not confined to startup. Each timeout reported RX mode 1 and zero device errors; TX calls returned success and still reported no configuration writes. Final RX failure, RX-mode, cache and receive-error counters were all zero.</p> <p>The wrong-channel behavior did not reproduce in this configuration. The remaining misses do not require a transmitter that retunes between packets. However, this is not a controlled A/B against the earlier XIAO setup: the RX board, TX boards/chips, antennas and geometry changed. These results do not prove that the earlier transmitter was faulty or establish the cause of the eight remaining losses.</p> <p>Several received signals were very strong, particularly the T096 at about -4 dBm. The weakest link, MeshTower V2 at about -45 dBm, passed 100/100 while scanning. That makes a controlled spacing/attenuation comparison worth considering, but this sample does not prove receiver overload. The observed 98% is a finite bench result, not a reliability guarantee or sensitivity test.</p>"},{"location":"four_fixed_tx_single_pass_validation/#capture-integrity-and-post-run-validation","title":"Capture integrity and post-run validation","text":"<p>All 400 scan probes finished and final radio telemetry was returned. The original host checker then rejected that telemetry because it incorrectly required zero modulation writes over the entire run, including post-packet RX staging. Its raw capture therefore remains <code>complete: false</code>, with final status preserved verbatim inside its error string. The normal <code>sender_final</code> collector step did not run. The raw failure record was not rewritten.</p> <p>Source review established the cache-refresh behavior above. The host checker now validates modulation writes against the measured refresh-hop count, checks that cached plus refresh hops equal total hops, and still requires single frequency writes, single fast resumes, zero added delay and the other policies. It also saves final telemetry before checking it, so future failures retain that structured record.</p> <p>Separate offline validation parsed the saved telemetry, checked the full 400-probe scan and all four 100-probe controls, verified 800 unique sequences, and checked every transmitter's packet counter from 1 through 200 and its zero-retune acknowledgments. A capture regression additionally checks that each TX/RX response ID matches its probe and every accepted payload/channel matches the assigned channel. No radio was rerun to replace the failed host assertion. The derived summary explicitly reports <code>original_collector_complete: false</code> and <code>post_run_validation_passed: true</code>.</p> <p>Evidence files:</p> <ul> <li>Immutable raw capture</li> <li>Independently validated summary</li> <li>Deployment record</li> <li>Build manifest</li> <li>Verified idle/service state</li> </ul> <p>Raw capture SHA-256: <code>42de3ac0c335b2c59f35c1cab217a01ef242c9f2e7b0010c8000a908a59232e6</code>. Derived summary SHA-256: <code>316bd551eb7306dfc576f4b88ad23e82cb1d701481d1e022067c961806d31bfe</code>.</p>"},{"location":"four_fixed_tx_single_pass_validation/#build-deployment-and-final-state","title":"Build, deployment and final state","text":"<p>Built from the dirty <code>keymindCascade</code> worktree based on <code>2b5a6f209835f0f67ed73fee78d36447a4566ce6</code>. This is not a claim that HEAD alone reproduces the images. The manifest records image and HIL-source hashes. All five PlatformIO builds succeeded and ran sequentially.</p> <p>After the host-checker correction, 25 focused unit/regression tests passed, including the preserved-capture check. <code>git diff --check</code> passed; its only warning concerned a pre-existing CRLF conversion in <code>MyMesh.cpp</code>.</p> <p>RadioLib was pinned to <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code> (7.7.1). The nRF framework was <code>d5413016</code> (1.10701.0); the ESP build used platform 6.11.0 / Arduino 2.0.17. The first three nRF targets retained S140 6.1.1 (FWID 0xB6, app base 0x26000); T1000-E retained S140 7.3.0 (FWID 0x123, app base 0x27000). nRF DFU packages were application-only, with their matching SoftDevice requirements intact. No nRF bootloader/SoftDevice replacement or cross-board override was used. Runtime FWID and application base were verified.</p> <p>V4 received the normal ESP bootloader, partition table, boot_app0 and HIL app at 0x0, 0x8000, 0xE000 and 0x10000, respectively, with esptool hash checks. No whole-flash bulk erase was issued. No backup was requested for these authorized bench deployments.</p> <p>The initial bundle's collector/deployer hashes are not the final scripts used: the actual run used <code>profile_four_tx_v2.py</code> with SHA-256 <code>b762e412636076902174c76b71961cc8ab3059c2b6de3dd3b4123bafcb06545c</code> (startup-greeting fix, original strict final assertion), and deployment used <code>profile_four_tx_deploy_v3.py</code> with SHA-256 <code>8a660788e0215e6ac1aece0a5d033521f9f376c9e51c00e760e918ebfd72cca1</code>. The current local collector includes the later validation correction; firmware images were not changed after the run. Remote evidence remains under <code>/home/mikec/hwtest/runs/four-tx-sf10-20260914</code>.</p> <p>All five radios were subsequently rebooted and independently verified idle. All TXs reported unprepared, packet count zero, no failure and autonomous TX disabled; V4 reported scanning inactive and zero hops after reboot. HIL firmware remains installed. ModemManager was restored active, gateway services were left active, and the V4 memory-soak service remains inactive because its firmware is now the bench receiver. No Pi USB hub power cycle was performed.</p> <p>No commit, push or pull was performed for this test. Unrelated worktree changes were preserved.</p>"},{"location":"full_companion_features/","title":"Full Companion: turn features on and off","text":"<p>For side-by-side Companion and infrastructure commands, see feature switches by role. MQTT and logging controls differ between these roles.</p> <p>Use the exact <code>companion_radio_full</code> image for your board. Full includes its supported transports and MOTA sending in one firmware; ordinary settings do not require rebuilding it. USB remains the normal way to update the Companion itself. WiFi/Bluetooth updates are optional, and Full does not install LoRa MOTA packages on itself.</p> <p>The Wireless Paper Full memory-sharing update keeps 350 contacts and 256 queued messages normally. During an mOTA session, 128 message slots are available while the other half holds its workspace. If more than 128 unread messages are queued, sync them with an app before starting mOTA. Disconnecting the source or turning it off returns all 256 slots. Idle WiFi mOTA listening does not borrow the queue. See the 1.17.1.5 release guide for the corrected download; the earlier <code>aa20e927</code> Wireless Paper image has 150 contacts.</p>"},{"location":"full_companion_features/#open-the-text-terminal","title":"Open the text terminal","text":"<p>Close the app or serial monitor using the USB port, then open a terminal at 115200 baud, or use the USB web console. A fresh Full Companion boot or observable USB session reset starts in ASCII text mode. If it is already in Binary Companion mode, send this line once and wait for the terminal banner:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>Run <code>help</code>, <code>board</code>, and <code>version</code> to inspect the device. On ESP32 you can alternatively open the node's LAN address and select CLI, or connect with <code>nc DEVICE_IP 5002</code>. Both use the same terminal commands as USB, including <code>import meshcore://...</code>, <code>list</code>, <code>to</code>, and <code>send</code>. Use <code>disconnect</code> to release a browser/TCP session. See the terminal guide. When finished, send <code>+++MESHCORE-TERM-STOP</code>, close the terminal, and reconnect your Companion app. These are local text commands; an app's custom-variable editor does not necessarily forward them.</p>"},{"location":"full_companion_features/#common-switches","title":"Common switches","text":"Feature Turn on Turn off When it takes effect Device power saving <code>set powersaving on</code> <code>set powersaving off</code> Immediately; saved LoRa receive power saving <code>set radio.rxps on</code> <code>set radio.rxps off</code> Saved; radio applies when available Radio chip RX boost <code>set radio.rxgain on</code> <code>set radio.rxgain off</code> Immediately; saved; supported radios only External FEM RX boost <code>set radio.fem.rxgain on</code> <code>set radio.fem.rxgain off</code> Immediately; saved; controllable FEM only External FEM TX gain <code>set radio.fem.txgain on</code> <code>set radio.fem.txgain off</code> Immediately; saved; controllable PA only ESP32 USB packet/debug logging For 1.17.1.5: <code>set powersaving off</code>, then <code>set usb.logging on</code> <code>set usb.logging off</code> Immediately; saved; logging owns the USB terminal nRF52 separate USB logging port <code>set usb.logging on reboot</code> <code>set usb.logging off reboot</code> Saves and reboots to add/remove the second USB port ESP32 browser settings <code>set webui on</code> <code>set webui off</code> Saved; starts/stops WebConfig ESP32 temporary setup portal <code>start webconfig ap</code> <code>stop webconfig</code> This session; opens a setup network/QR where available ESP32 WiFi firmware uploader <code>start ota</code> or <code>start ota ap</code> <code>stop ota</code> This session; only usable with two application slots Temporary MOTA radio window <code>tempradio 910.525,250,5,5,120</code> <code>normalradio</code> Bounded window; saved normal settings return afterward <p>Check a saved switch with the corresponding <code>get</code> command, for example <code>get usb.logging</code>, <code>get radio.rxps</code>, or <code>get webui</code>. Use <code>get powersaving</code> to inspect device power saving. Fresh installations enable device power saving and leave USB logging off. Existing saved preferences take precedence.</p> <p>For an ESP32 1.17.1.5 USB logging session, use this sequence in the text terminal:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>The power-saving step is the documented USB-session workaround for this release. It is saved separately; <code>set usb.logging off</code> does not restore power saving. nRF52 does not need the ESP32 workaround. WiFi-only MQTT logging does not need this USB step; see logging by role.</p> <p>ESP32 logging and Binary Companion share one USB port. After turning logging off, return to Binary Companion with <code>+++MESHCORE-TERM-STOP</code>. nRF52 keeps its optional logging port separate from its primary USB port and BLE connection. See the USB switching guide.</p>"},{"location":"full_companion_features/#wifi-bluetooth-gps-and-mqtt","title":"WiFi, Bluetooth, GPS, and MQTT","text":"<p>On ESP32, configure WiFi through the setup portal or these commands:</p> <pre><code>set wifi.ssid MyNetwork\nset wifi.pwd my-password\nget wifi.status\n</code></pre> <p>Credentials are saved. A credential change schedules a reconnect; a TCP terminal will disconnect. The WiFi switch on supported device displays or their assigned WiFi button controls the Companion WiFi services. Stopping WebConfig alone stops its browser service, while the Companion's TCP and MOTA services can remain available.</p> <p>WiFi modem sleep is independent of device power saving. Use <code>set wifi.powersave min</code> for normal BLE/WiFi coexistence; inspect the effective state with <code>get wifi.powersave</code>. <code>max</code> is available only where the firmware's radio coexistence policy permits it.</p> <p>Most Full Companions provide BLE alongside their other transports. There is no universal <code>set bluetooth off</code> command. SenseCAP Indicator selects one secondary wireless transport per boot:</p> <pre><code>set companion.transport wifi\nreboot\n</code></pre> <p>Use <code>set companion.transport ble</code> followed by <code>reboot</code> to select Bluetooth instead. USB stays available. The ESP-NOW layout keeps its primary ESP-NOW mesh active in either mode.</p> <p>For GPS-equipped boards, use <code>get gps</code>, <code>set gps on</code>, and <code>set gps off</code>. The Companion app's <code>gps=1</code> / <code>gps=0</code> custom setting controls the same GPS. Only boards with a compiled GPS provider expose this setting. Sharing location with contacts is a separate setting.</p> <p>When the exact Full image includes MQTT, use WebConfig's MQTT cards or the same CLI settings used by infrastructure, such as <code>set mqtt1.preset custom</code> and <code>set mqtt1.server broker.example.com</code>. <code>set mqtt.enabled on|off</code> controls MQTT without erasing the configured slots; check <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, and <code>get mqtt.status</code>. The MQTT tab's Enable MQTT checkbox controls the same saved switch. <code>set logging.output off|usb|wifi|both</code> selects USB and MQTT outputs together. Status, packets, raw, receive, and transmit switches control their individual publications. Builds without MQTT omit these controls. There is no need for a separate logging or WiFi-MQTT Companion image when that feature is included in Full.</p>"},{"location":"full_companion_features/#send-mota-from-any-full-companion","title":"Send MOTA from any Full Companion","text":"<p>Place valid, destination-specific <code>.mota</code> files in a host directory. Set the source, destination, controller, and required relays to the same bounded temporary radio tuple. For USA Cascade on LoRa hardware:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>On the computer connected to the Full Companion, run:</p> <pre><code>motatool serve --serial /dev/ttyACM0 --dir ./motas -v\n</code></pre> <p>This works on both ESP32 and nRF52 Full. Close the text terminal first. <code>motatool</code> automatically sends <code>ota folder on</code> and owns USB while serving. Stop the host tool to detach the source; use <code>normalradio</code> afterward to return early, or let the window expire. A <code>.bin</code>, <code>.uf2</code>, or DFU <code>.zip</code> is not itself a <code>.mota</code>; use motatool to prepare the package for the exact destination firmware and hardware.</p> <p>ESP32 also accepts a host over WiFi:</p> <pre><code>motatool serve --tcp DEVICE_IP:5001 --dir ./motas -v\n</code></pre> <p>nRF52 also accepts an authenticated Bluetooth host:</p> <pre><code>python3 tools/ble_mota/ble_mota_seeder.py \\\n  --device MeshCore-MyCompanion --dir ./motas \\\n  --local 'tempradio 910.525,250,5,5,120'\n</code></pre> <p>Use one MOTA source transport at a time. See the complete MOTA instructions for pairing, remote destination commands, and automation. ESP-NOW hardware uses its ESP-NOW primary radio rather than transmitting LoRa.</p>"},{"location":"full_companion_features/#update-the-companion-itself","title":"Update the Companion itself","text":"<p>USB is supported for every Full Companion. Use the exact board's UF2/DFU package or ESP32 image and the normal flasher. Preserve the target's existing partition layout unless deliberately performing a documented USB migration.</p> <p>For ESP32 with two application slots, <code>start ota</code> returns the WiFi uploader URL, normally <code>http://DEVICE_IP:8080/update</code>. <code>start ota ap</code> explicitly opens <code>MeshCore-OTA</code>; join it and use the returned URL. Upload the exact board's application <code>.bin</code>. The device reboots when the upload succeeds. Use <code>stop ota</code> to close an unused uploader. Port 8080 keeps WebConfig on port 80 available. Use a trusted local network or a temporary setup network.</p> <p>The 4 MB Full layouts and T-Beam 1W Full use a single application slot and require USB; the command reports that limitation. The artifact's <code>.capabilities.json</code> lists verified <code>ota_update_methods</code> when a wireless self-update path is usable.</p> <p>nRF52 Full exposes Bluetooth DFU to paired clients. Use the matching application DFU <code>.zip</code> with a compatible Nordic/Adafruit Legacy DFU client and the board's matching BLE-DFU-capable bootloader/SoftDevice. USB remains the fallback when the installed bootloader does not support that procedure. Bluetooth DFU updates the Companion; the separate Bluetooth MOTA source service feeds packages to other mesh nodes.</p> <p>For OTAFIX installations, use the exact board/storage profile from OTAFIX 2.4.6. It includes the Bluetooth reconnect fix from 2.4.5. Its release notes cover upgrades from older bootloaders, including the special UF2-drive precautions for version 2.4.3. The new 64 KiB retained-RAM staging feature applies to qualified internal-flash nRF52840 receivers; Full Companions continue to serve host-supplied packages without needing that receiver storage layout.</p>"},{"location":"full_companion_usb_switcher/","title":"Companion USB CLI and binary switcher","text":"<p>USB Companion uses one primary USB serial interface for two incompatible wire formats:</p> <ul> <li>a human-readable ASCII command line;</li> <li>the framed Binary Companion protocol used by MeshCore apps and <code>meshcli</code>.</li> </ul> <p>The primary interface starts in the ASCII terminal after each boot and returns to ASCII after a USB session reset that the hardware can observe. A Binary Companion client does not need to send a special mode command: its first valid frame automatically hands the interface to the binary parser.</p> <p>Current source keeps the default terminal quiet until the host sends ASCII input. Press Enter or type a command to see the banner. This prevents the ASCII <code>&gt;</code> prompt from being mistaken for the beginning of an app's first binary response. See USB client compatibility validation for the tested firmware and release status.</p> <p>These mode controls apply to Full and ordinary USB Companion builds. The explicit <code>+++MESHCORE-TERM-START</code> and <code>+++MESHCORE-TERM-STOP</code> controls remain available, including for older firmware. See the Terminal Chat CLI guide.</p>"},{"location":"full_companion_usb_switcher/#wire-formats","title":"Wire formats","text":"<p>Host-to-device Binary Companion frames use this layout:</p> <pre><code>'&lt;'  length-low  length-high  payload[length]\n</code></pre> <p>Device-to-host frames use the same little-endian length with a different marker:</p> <pre><code>'&gt;'  length-low  length-high  payload[length]\n</code></pre> <p>For example, a representative two-byte device query is:</p> <pre><code>3C 02 00 16 03\n</code></pre> <p>The ASCII terminal is line-oriented and accepts commands such as:</p> <pre><code>get radio.cad\nset display.rotation 90\nreboot\n</code></pre> <p>Changing the configured baud rate does not select a mode. Use 115200 for compatibility even though native USB CDC hardware does not use UART timing.</p>"},{"location":"full_companion_usb_switcher/#state-transitions","title":"State transitions","text":"<pre><code>                         complete '&lt;' frame\n                 +--------------------------------+\n                 |                                v\nboot ------&gt; ASCII terminal                  Binary Companion\n                 ^                                |\n                 |                                | +++MESHCORE-TERM-START\n                 | incomplete '&lt;' probe           |\n                 | (one-second timeout)            |\n                 +--------------------------------+\n\nASCII terminal -- +++MESHCORE-TERM-STOP ------&gt; Binary Companion\nany mode ------- observable USB session reset ---&gt; ASCII terminal\nESP32 logging terminal -- usb.logging off -----&gt; ASCII terminal\nany mode ------- reboot ------------------------&gt; ASCII terminal\n</code></pre> <p>Serial mOTA and single-TTY logging add exclusive ownership states described below. BLE, WiFi, Ethernet, and hardware-serial Companion transports are not switched; they remain binary.</p>"},{"location":"full_companion_usb_switcher/#how-automatic-detection-works","title":"How automatic detection works","text":"<ol> <li>Companion initializes the normal USB Binary Companion interface, then    gives its primary stream to the ASCII terminal before normal loop service    begins.</li> <li>While the prompt has no buffered input, the terminal peeks at the next byte.    It does not remove that byte.</li> <li>If the byte is <code>&lt;</code>, the terminal temporarily releases the stream and enables    the existing <code>ArduinoSerialInterface</code> frame parser.</li> <li>The parser consumes the original <code>&lt;</code>, the two-byte length, and the payload.    There is no second parser and no copied or synthetic frame.</li> <li>A monotonically increasing completed-frame counter confirms that the parser    received a complete frame. The interface then remains in Binary Companion    mode.</li> <li>If no complete frame arrives within one second, the parser state is reset    and the ASCII terminal prints a new banner and prompt.</li> </ol> <p>The switcher checks framing, not client identity. Any syntactically complete Binary Companion frame confirms binary mode; it does not require the first command to be <code>CMD_APP_START</code> or <code>CMD_DEVICE_QUERY</code>. Normal command validation still occurs after the frame parser returns the payload.</p> <p>The empty-prompt requirement prevents a literal <code>&lt;</code> in the middle of a command from silently changing modes. A literal <code>&lt;</code> typed as the first character does start a probe, but the terminal returns after the one-second timeout if no binary header and payload follow.</p>"},{"location":"full_companion_usb_switcher/#manual-controls","title":"Manual controls","text":"<p>The original controls remain available.</p> <p>From Binary Companion, send this exact unframed line while the parser is idle:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>Terminate it with CR or LF. The binary parser accepts control tokens only as complete delimiter-bounded lines; prefixes, suffixes, and partial tokens are ignored.</p> <p>From the ASCII terminal, send this exact sequence to return to binary mode:</p> <pre><code>+++MESHCORE-TERM-STOP\n</code></pre> <p>The stop sequence takes effect as soon as its last byte arrives in ASCII mode. The start sequence is recognized only as a completed line while the binary parser is idle and is not examined inside a length-prefixed frame.</p> <p><code>meshcli</code> can normally connect directly after boot:</p> <pre><code>meshcli -s /dev/ttyACM0 -b 115200 ver\n</code></pre> <p>An explicit terminal start token is still useful when the device is already in binary mode:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre>"},{"location":"full_companion_usb_switcher/#logging-and-mota-ownership","title":"Logging and mOTA ownership","text":"<p>The switcher never attempts to mix ASCII, framed Companion traffic, or binary mOTA traffic on the same stream.</p> Situation Primary USB behavior USB Companion after boot or observable session reset ASCII; a complete <code>&lt;</code> frame switches to Binary Companion nRF52 logging enabled Primary interface still follows the switcher; logs use the optional second interface ESP32 logging enabled at boot Logging terminal owns the only USB TTY; automatic <code>&lt;</code> detection is disabled nRF52 USB serial mOTA active mOTA owns primary USB; ASCII and Binary Companion are unavailable there BLE/WiFi/Ethernet/hardware serial Always Binary Companion and unaffected by the USB mode <p>On RAK4631 and other nRF52 Full Companions, ASCII and Binary Companion both use the primary interface (<code>*-if00</code> on Linux). The optional <code>*-if02</code> interface is for logging. <code>OK - Binary mode</code> acknowledges a mode change on the same primary port; it does not move the connection to the logging port.</p> <p>On every ESP32 Full Companion, use <code>set usb.logging off</code> in its logging terminal before trying to use USB with an app. That command stops logging and returns to the ordinary ASCII terminal; it does not select Binary Companion. The app's first valid framed probe can perform the normal automatic switch, or a human can send <code>+++MESHCORE-TERM-STOP</code> first. The framed/binary Companion parser is disabled while logging owns that TTY. BLE and WiFi Companion transports remain available while USB is logging. ESP32 Full builds use the Arduino-ESP32 2.x base where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but follow the same one-TTY policy. No ESP32 Full build enumerates a second CDC interface.</p> <p>With logging enabled on a shared port, the stop token is rejected with <code>ERROR: set usb.logging off before Binary mode</code>. Turn logging off first; a successful binary-mode acknowledgement must not immediately revert to logging.</p> <p>On nRF52, serial <code>motatool</code> is also text-first. Its exact initial <code>ota folder on</code> line is recognized in either startup ASCII or Binary Companion mode. From ASCII, the firmware leaves terminal mode and directly enters exclusive mOTA ownership; from binary, the idle frame parser recognizes the same control sequence. The following mOTA request/reply frames therefore cannot be consumed by the ASCII line editor. <code>motatool serve --serial</code> can be the first client after boot and does not require a terminal token or disconnect workaround.</p> <p>Only the exact completed line selects mOTA from ASCII. Extra arguments, leading/trailing whitespace, or a partial line remain ordinary terminal input.</p>"},{"location":"full_companion_usb_switcher/#shortcomings-and-edge-cases","title":"Shortcomings and edge cases","text":"<p>This mechanism is deliberately small and deterministic, but it is not a full protocol negotiation layer.</p>"},{"location":"full_companion_usb_switcher/#session-detection-depends-on-the-usb-hardware","title":"Session detection depends on the USB hardware","text":"<p>After the first complete binary frame, the device stays in Binary Companion mode for that session. Native USB with DTR/session events restores ASCII when the host closes or resets the connection. Old input, queued output and mOTA ownership are cleared before selecting the default for the next session.</p> <p>Some clients, including <code>meshcore</code> 2.3.10 used by stock MeshCLI, deliberately deassert DTR. The nRF52 primary interface also accepts actual incoming USB data as evidence of a client in the current session. Closing, changing line coding, or resetting USB invalidates that evidence. The dedicated logging interface continues to require its own connected reader.</p> <p>ESP32 hardware USB Serial/JTAG reports bus reset and physical host loss, but cannot reliably report a terminal program closing its handle. A USB-to-UART bridge also usually cannot report that close. On those ports, use the terminal start token to return from Binary mode without rebooting. Idle time alone never changes the selected protocol.</p> <p>An active network terminal temporarily delays restoring the USB ASCII prompt. If a fresh USB app sends a complete binary frame during that delay, its Binary mode remains selected when the network terminal closes.</p>"},{"location":"full_companion_usb_switcher/#detection-works-only-at-an-empty-prompt","title":"Detection works only at an empty prompt","text":"<p>If part of an ASCII command is already buffered, an incoming <code>&lt;</code> is treated as ordinary terminal input. Clear or submit the line before starting a Binary Companion client. Only one process should have the serial port open.</p>"},{"location":"full_companion_usb_switcher/#the-first-frame-has-a-one-second-deadline","title":"The first frame has a one-second deadline","text":"<p>The complete marker, length, and payload must arrive within the probe window. This is generous for local USB but may reject a heavily buffered serial proxy, a debugger that pauses the MCU, or a tool that writes the header and body with a long delay. A timed-out client can retry after the ASCII banner appears.</p>"},{"location":"full_companion_usb_switcher/#framing-confirmation-is-not-authentication","title":"Framing confirmation is not authentication","text":"<p>Any complete length-prefixed frame selects binary mode, even if its command is unknown or malformed at the application layer. This is safe for stream separation but means a random complete frame can leave the device in binary mode until an observable USB session reset or a manual switch back.</p>"},{"location":"full_companion_usb_switcher/#the-default-terminal-waits-for-input","title":"The default terminal waits for input","text":"<p>The firmware enters ASCII mode during boot but suppresses the banner and unsolicited terminal events until ASCII input identifies a terminal client. Send Enter or a harmless <code>get</code> command to display the banner. A binary client instead gets a clean first response. Older builds that immediately printed <code>&gt;</code> could consume the first binary response's marker as part of a bogus frame length; scanning past leading text alone did not reliably recover that reply.</p>"},{"location":"full_companion_usb_switcher/#text-and-binary-output-cannot-be-interleaved","title":"Text and binary output cannot be interleaved","text":"<p>Primary USB suppresses Binary Companion output while the terminal owns the stream. Packet/debug logging must use its dedicated CDC interface or the exclusive single-TTY logging mode. Writing diagnostic text directly to the primary binary stream will corrupt clients regardless of the switcher.</p>"},{"location":"full_companion_usb_switcher/#a-literal-leading-briefly-hides-the-prompt","title":"A literal leading <code>&lt;</code> briefly hides the prompt","text":"<p>Typing <code>&lt;</code> as the first terminal character begins a binary probe. With no complete frame, the prompt returns after one second and the banner is printed again. There is currently no escape syntax for entering a literal leading <code>&lt;</code>; prefix it with another character if it is needed as command text.</p>"},{"location":"full_companion_usb_switcher/#troubleshooting","title":"Troubleshooting","text":"<p>If <code>meshcli</code> cannot connect:</p> <ol> <li>close every terminal or logging reader using the primary interface;</li> <li>on ESP32, confirm that saved USB logging is off;</li> <li>reboot and let <code>meshcli</code> be the first process to open the data interface;</li> <li>use the stable <code>/dev/serial/by-id/*-if00</code> path on Linux when available;</li> <li>if a prompt appears after one second, the client's first frame was not    completed inside the probe window.</li> </ol> <p>If an ASCII terminal shows no banner, press Enter and issue a harmless query such as <code>get radio.cad</code>. If binary bytes appear, send the exact terminal start token or reboot.</p> <p>The switch policy is implemented in <code>UsbAsciiBinarySwitch.h</code>, with stream ownership in <code>main.cpp</code> and framing in <code>ArduinoSerialInterface.cpp</code>.</p>"},{"location":"full_usb_logging_validation/","title":"Full USB logging repair \u2014 1.17.1.6","text":"<p>Audit date: 2026-09-13. Release firmware source: <code>306feebe6d648a247f925894f876be9d747fc8d2</code>.</p> <p>The original Station G2 Full Repeater and Full Room Server images omitted USB packet logging. Both inherited <code>-UMESH_PACKET_LOGGING</code> from their ordinary MQTT observer recipes. Full added <code>-DMESH_PACKET_LOGGING=1</code>, but PlatformIO's <code>ProcessFlags</code> moves undefines after defines in the compiler command. The resulting image compiled successfully with its packet logger removed.</p> <p>The previous release gate checked OTA and other features without requiring USB logging in Full infrastructure. An old passing manifest could also be reused by <code>--resume</code> without the new logging evidence.</p>"},{"location":"full_usb_logging_validation/#published-image-audit","title":"Published-image audit","text":"<p>Each downloaded/cached artifact was matched to GitHub's published SHA-256. The check inspected application bytes, including the application inside nRF52 DFU ZIPs. It required the packet-log formatter and USB logging controls.</p> Release group Application images Missing USB packet logging ESP32 Full infrastructure/utility 157 2 ESP32 Full Companion 52 0 nRF52 Full Companion 43 0 Total 252 2 <p>Affected targets:</p> <ul> <li><code>Station_G2_repeater_observer_mqtt</code></li> <li><code>Station_G2_room_server_observer_mqtt</code></li> </ul> <p>V4/R8 Full builds and Station G2's Full ESP-NOW bridge passed. This audit does not count ordinary MQTT profiles that intentionally omit USB logging as broken. Artifact inspection proves compiled support, not hardware operation on every board.</p>"},{"location":"full_usb_logging_validation/#fix-and-regression-coverage","title":"Fix and regression coverage","text":"<ul> <li>Full builds that require logging remove inherited disables of   <code>MESH_PACKET_LOGGING</code> before PlatformIO parses flags. Other macros and   explicit logging-off profiles retain their policy.</li> <li>Full capability checks require the packet logger and USB controls in the   packaged application. Combined USB/WiFi profiles additionally require   the <code>logging.output</code> setter. ELF symbols or debug text cannot satisfy these   checks.</li> <li>Resumed builds must have passing application evidence for the current   logging contract, along with the existing artifact hashes and RAM checks.</li> <li>CI runs the flag, real PlatformIO/compiler, artifact, resume, and build-profile   regression suites.</li> </ul> <p>Focused verification (after installing PlatformIO and its tool-scons package):</p> <pre><code>python3 -B test/test_full_build_flag_dedup.py\npython3 -B test/test_full_logging_compile.py\npython3 -B test/test_firmware_capabilities.py\npython3 -B test/test_full_logging_resume.py\nbash test/test_build_profiles.sh\npython3 -B test/test_cascade_release_package.py\n</code></pre> <p>Both Station G2 profiles were rebuilt through <code>build.sh --full</code> with the original observer recipes, including their inherited logging undefines. They passed the new application checks, runtime RAM budgets, and both OTA slot size checks. The new checker rejects both original published images.</p> <p>On the Bellevue Station G2, the corrected Full repeater implementation also passed serial CLI and passive traffic checks: four RX and two TX packet log lines were captured. Its active temporary profile retained preamble 120 and the original schedule end time; the Pi relay services were restored.</p> <p>Corrected application SHA-256:</p> <pre><code>Repeater:    81a0a2926d4e567c069d0b10f316047881bcedce062afaa42119dddb2baadf23\nRoom Server: 7ee81f1cb65fc274bd363397c3c80ce9006d575efae50fe952c8ca246613a18c\n</code></pre>"},{"location":"gps_tracking/","title":"GPS Tracking","text":"<p>This document describes how GPS telemetry works for companion/client nodes and sensor nodes.</p>"},{"location":"gps_tracking/#scope","title":"Scope","text":"<p>GPS tracking uses the existing CayenneLPP GPS telemetry field. It does not add a new phone app protocol field.</p> <p>The GPS telemetry value contains latitude, longitude, and altitude. Speed, heading, and freshness are not sent as separate telemetry fields.</p> <p>If the firmware does not have a valid fresh GPS cache, it omits the GPS field from telemetry. This is intentional: stale or missing fixes are not reported as zero coordinates.</p>"},{"location":"gps_tracking/#freshness","title":"Freshness","text":"<p>GPS telemetry is cached separately from advert location.</p> <p>The cache behavior is:</p> <ul> <li>Refresh the cached GPS value every 2 hours only when at least one contact or   ACL client can receive location telemetry.</li> <li>Try for up to 15 minutes during a refresh.</li> <li>If the position stays within about 100 meters for 30 seconds, cache a weighted   average of the stable fixes, with newer fixes weighted more heavily.</li> <li>If the position moves outside that 100 meter circle during acquisition, cache   the latest valid fix.</li> <li>Omit GPS from telemetry if there is no fix or if the cached fix is more than   12 hours old.</li> </ul> <p>When a telemetry request asks for location, GPS is normally kept on for 2 hours after the latest location request. During that hold window, later location telemetry requests can use fresh GPS data as soon as valid fixes are available.</p> <p>If GPS is manually enabled, it stays on and valid fixes continue to update the cache.</p> <p>If no contact or ACL client can receive location telemetry, the scheduled 2-hour refresh does not run. A real location telemetry request can still turn GPS on, and manual GPS-on still keeps the cache updated.</p>"},{"location":"gps_tracking/#repeater-nodes","title":"Repeater Nodes","text":"<p>Repeaters use a shorter on-demand policy when GPS is manually off. An authorized location-telemetry request wakes the receiver only when its cached position is stale. The first valid fix is cached and the receiver immediately powers down; the next request can return that fix without another wake. <code>gps off</code> also cancels an acquisition already in progress. An acquisition that never obtains a fix retains the normal 15-minute safety timeout.</p> <p>When GPS and device power saving are both enabled, a repeater wakes GPS for up to 10 minutes to obtain a valid time and then sleeps it for seven days. A valid GPS time may correct the RTC either forward or backward. With device power saving off, an enabled GPS remains active and refreshes the RTC every 30 minutes.</p>"},{"location":"gps_tracking/#companionclient-nodes","title":"Companion/Client Nodes","text":"<p>Companion/client telemetry uses the existing companion telemetry permission system:</p> <ul> <li>base telemetry</li> <li>location telemetry</li> <li>environment telemetry</li> </ul> <p>Location telemetry is sent only when the requester's effective telemetry permissions include location. Those permissions are derived from the companion telemetry mode settings and contact flags.</p> <p>No new phone app behavior is required. Existing clients see the existing GPS telemetry field when it is present.</p> <p>The scheduled GPS cache refresh runs only when at least one stored contact has effective location telemetry access:</p> <ul> <li><code>location: allow all</code> with at least one stored contact</li> <li><code>location: allow flags</code> with at least one stored contact whose flags include   location</li> </ul>"},{"location":"gps_tracking/#sensor-nodes","title":"Sensor Nodes","text":"<p>Sensor telemetry access is controlled by:</p> <pre><code>get telemetry.access\nset telemetry.access all\nset telemetry.access acl\n</code></pre> <p><code>all</code> is the default and matches the previous sensor telemetry behavior. A request that reaches the normal sensor telemetry request path can receive the requested telemetry fields, including GPS, subject to the request mask and GPS freshness rules.</p> <p><code>acl</code> gates telemetry through the sensor ACL. A requester with read-only or higher permissions receives the existing telemetry set, including GPS. Guest or unknown requesters receive no telemetry fields.</p> <p>The scheduled GPS cache refresh follows the same access setting:</p> <ul> <li><code>all</code>: runs only when at least one ACL client exists</li> <li><code>acl</code>: runs only when at least one ACL client is read-only or higher</li> </ul> <p>Use the existing ACL command to grant access:</p> <pre><code>setperm &lt;pubkey&gt; 1\n</code></pre> <p>Permission values:</p> <ul> <li><code>1</code>: read-only, suitable for telemetry access</li> <li><code>2</code>: read-write</li> <li><code>3</code>: admin</li> </ul>"},{"location":"gps_tracking/#advert-location","title":"Advert Location","text":"<p>Advert location is separate from telemetry GPS. The advert policy is controlled with:</p> <pre><code>gps advert\ngps advert none\ngps advert share\ngps advert prefs\n</code></pre> <p>Policies:</p> <ul> <li><code>none</code>: do not include location in adverts</li> <li><code>share</code>: use the live/shared sensor manager location</li> <li><code>prefs</code>: use the stored node latitude and longitude preferences</li> </ul> <p><code>prefs</code> is the first-boot default for every repeater, room-server, and sensor build. Firmware updates retain an explicitly saved policy from the existing preferences filesystem.</p> <p>Telemetry GPS can be fresh while advert location is fixed or disabled, depending on this policy.</p>"},{"location":"gps_tracking/#recommended-setup","title":"Recommended Setup","text":"<p>For private sensor tracking:</p> <pre><code>set telemetry.access acl\nsetperm &lt;owner_pubkey&gt; 3\nsetperm &lt;trusted_pubkey&gt; 1\n</code></pre> <p>For compatibility with the older sensor behavior:</p> <pre><code>set telemetry.access all\n</code></pre> <p>For GPS telemetry behavior, leave the phone app unchanged. The firmware omits GPS when it is stale or missing and sends the existing GPS telemetry field when fresh data is available.</p>"},{"location":"halo_keymind_settings/","title":"Halo and Keymind Branch Settings","text":"<p>This file covers only CLI settings and helper commands added by the Halo or Keymind branches. Use CLI commands for the general infrastructure CLI. For MQTT, logging, and former variant controls, use feature switches by role; Full Companion uses different controls for some of these settings. See Repeater Flood Filtering and Moderation for a focused filter setup and troubleshooting guide.</p>"},{"location":"halo_keymind_settings/#quick-start","title":"Quick Start","text":"<pre><code>set retry.preset rooftop\nset direct.retry.heard on\nset flood.retry.advert off\nset flood.retry.bridge off\nset flood.retry.prefixes none\nset flood.retry.ignore none\n</code></pre> <p>Then verify:</p> <pre><code>get retry.preset\nget direct.retry.heard\nget flood.retry.advert\nget flood.retry.prefixes\nget flood.retry.ignore\n</code></pre> <p>Use prefixes from the analyzer or neighbors list or <code>get recent.repeater</code> after the repeater has been online for a few hours.</p>"},{"location":"halo_keymind_settings/#common-examples","title":"Common Examples","text":"<p>Disable retrying advert packets:</p> <pre><code>set flood.retry.advert off\nget flood.retry.advert\n</code></pre> <p>Ignore a repeater as a successful flood retry echo: Use this if you have a car repeater and a house repeater; have the house ignore the car.</p> <pre><code>set flood.retry.ignore 71CE82,C7618C\nget flood.retry.ignore\n</code></pre> <p>Only accept specific downstream relays as flood retry success: You're in a hole and need to hit a mountain top repeater to get out; keep trying till one you see one of these send out your packet.</p> <pre><code>set flood.retry.prefixes A58296,860CCA,425E5C\nget flood.retry.prefixes\n</code></pre> <p>Bridge two groups of repeaters:</p> <pre><code>set flood.retry.bridge on\nset flood.retry.bucket 1 71CE82,C7618C\nset flood.retry.bucket 2 BEEBB0,425E5C\nget flood.retry.bucket.1\nget flood.retry.bucket.2\n</code></pre> <p>Return to simple non-bridge flood retry:</p> <pre><code>set flood.retry.bridge off\nset flood.retry.prefixes none\nset flood.retry.ignore none\n</code></pre>"},{"location":"halo_keymind_settings/#added-settings","title":"Added Settings","text":"Setting What it does How to use Example <code>telemetry.temp</code>, <code>telemetry.volt</code>, <code>telemetry.volt.i2c</code>, <code>telemetry.gps</code> Repeater and room builds record 30-minute MCU temperature and battery samples for seven days. Detected INA voltage channels retain four days at 0.02 V resolution through 655.34 V; all-zero channels are omitted as disconnected. GPS-capable builds retain GPS separately. Repeater <code>telemetry.tx</code> sends temperature, battery, and per-channel I2C RAW_CUSTOM packets over the shared <code>data.tx</code> path on a persistent 1-30 day schedule or immediately for testing; automatic transmission is off by default and its retained cadence starts at two days. <code>data.tx</code> defaults to zero-hop direct plus automatic region selection without enabling any producer. GPS is never included. History resets on reboot. <code>get/set data.tx path|region</code>, <code>get telemetry.temp [page]</code>, <code>get telemetry.volt [page]</code>, <code>get telemetry.volt.i2c [channel [page]]</code>, <code>get telemetry.gps [page]</code>, <code>set telemetry.gps &lt;1-30&gt;</code>, <code>get telemetry.tx</code>, <code>set telemetry.tx schedule &lt;off|1-30d&gt;</code>, <code>send telemetry.tx now</code> <code>get data.tx</code> <code>battery.alert</code> Sends opt-in, region-scoped low-battery warnings to <code>#repeaters</code> after 30 minutes of uptime. <code>get battery.alert</code>, <code>get battery.alert.region</code>, <code>set battery.alert on [region]</code>, <code>set battery.alert off</code> <code>set battery.alert on sea</code> <code>battery.alert.low</code> Warning threshold percentage. Must be greater than <code>battery.alert.critical</code>. <code>get battery.alert.low</code>, <code>set battery.alert.low &lt;1-100&gt;</code> <code>set battery.alert.low 20</code> <code>battery.alert.critical</code> Critical threshold percentage. Critical and warning alerts use the same 12-hour resend cooldown. <code>get battery.alert.critical</code>, <code>set battery.alert.critical &lt;0-99&gt;</code> <code>set battery.alert.critical 10</code> <code>recent.repeater</code> Shows, searches, seeds, or clears the recent repeater prefix/SNR table used by direct retry and bridge freshness checks. Search results include the last-recorded age. Entries older than 24 hours are removed by a three-hour sweep. <code>get recent.repeater [page]</code>, <code>get recent.repeaters search &lt;2|4|6 hex&gt; [page]</code>, <code>set recent.repeater &lt;prefix&gt; &lt;snr_db&gt;</code>, <code>clear recent.repeater</code> <code>get recent.repeaters search A1B2</code> <code>flood.channel.data</code> Compatibility view for a visible FPF7 <code>type=grp_data</code> drop row on generalized repeaters. <code>off</code> creates the row and <code>on</code> removes it; compact FPF6 builds retain the legacy gate. Use an authenticated <code>channel=</code> row when only selected channels should be blocked. <code>get flood.channel.data</code>, <code>set flood.channel.data on/off</code> <code>set flood.channel.data off</code> <code>flood.channel.data.hops</code> Sets the compatibility row's hop range: <code>all</code> maps to <code>hops=all</code>; <code>1</code>-<code>7</code> repeats through that hop count and maps to <code>hops=N+1+</code>. <code>get flood.channel.data.hops</code>, <code>set flood.channel.data.hops &lt;all|1-7&gt;</code> <code>set flood.channel.data.hops 7</code> <code>flood.channel.scope</code> FPF7 rewrite-phase rows that add a transport scope to received unscoped floods or replace the scope of already-scoped floods. A bare target uses an existing flood-allowed region; <code>scope=&lt;name&gt;</code> derives a public hashtag target directly without creating a region, exactly like <code>flood.filter scope=</code>. By default, a changed packet bypasses inbound <code>rxdelay</code> and is forwarded at the highest outbound queue priority with zero initial <code>txdelay</code>, so the selected scope can win at the next hop. <code>tx=slow</code> uses an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, retains normal queue priority, and forces the maximum <code>txdelay</code> factor of <code>2.0</code>; its actual randomized transmit delay ranges from zero through ten packet airtimes. <code>path=blacklist</code> and <code>path=bucket:&lt;1-6&gt;</code> make a row path-qualified; bridge buckets remain usable while bridge retry is off. An already-matching scope is a no-op. Exact channel keys beat <code>txt:*</code>; path-qualified rows beat the ordinary channel fallback. <code>login:*</code> covers the remote-login family, and <code>other:*</code> covers every remaining flood type, including flood-form TRACE and OTA. Direct traceroute remains outside the flood table. Generalized builds commit these rows with the forward phase and blacklist; compact FPF6 builds retain separate storage. ACL permission <code>4</code> can manage the table. <code>get flood.channel.scope[.n]</code>, <code>set flood.channel.scope[.n] &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]</code>, <code>del flood.channel.scope.&lt;n&gt;|all</code> <code>set flood.channel.scope #rgdata scope=BlackHole86</code> <code>flood.channel.scope.require</code> Switches group-channel region enforcement to opt-in when the table has entries. Listed authenticated <code>GRP_TXT</code>/<code>GRP_DATA</code> channels must arrive already scoped to a locally allowed region; unscoped, unknown, or denied incoming scopes are dropped before any rewrite can rescue them. Unlisted group channels bypass only the region gate and retain all other forwarding controls. An empty table preserves global region behavior; non-channel payloads are unchanged. ACL permission <code>4</code> can manage the table. <code>get flood.channel.scope.require[.n]</code>, <code>set flood.channel.scope.require[.n] &lt;public|#channel|key&gt;</code>, <code>del flood.channel.scope.require.&lt;n&gt;|all</code> <code>set flood.channel.scope.require #bot</code> <code>flood.filter</code> Persistent flood-route rules selected by payload type and optional hop range. Generalized repeaters have 63 FPF7 forward slots; FULL ESP32 room servers have 31. Repeaters store their scope-rewrite phase, shared unordered blacklist, and channel-data compatibility state in the same atomic FPF7 image. <code>path=blacklist</code> is intended for forwarding abuse containment, including bulk internet-to-mesh dumping, but truncated path IDs are not authenticated identities. Fixed 240 KB STM32WL repeaters retain compact FPF6 filtering and separate blacklist storage. New generalized repeater tables seed slot 1 with <code>ota all suspend=tempradio</code> slot 2 with an authenticated <code>#wardriving hops=5+</code> radio drop, and slot 3 with <code>#wardriving hops=all mode=bridge,cross drop</code>. <code>mode=radio</code> is the default; <code>bridge</code>, <code>cross</code>, and <code>bridge,cross</code> select separate transport admission paths, including direct packets. Local receive/logging is unchanged. See the mode guide. <code>get flood.filter[.n]</code>, <code>set flood.filter[.n] &lt;type&gt; [N|N+|N-M|all] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]</code>, <code>del flood.filter.&lt;n&gt;|all</code>; repeater only: <code>get/set/del flood.filter.blacklist[.n]</code> <code>set flood.filter grp_txt all scope=local tx=slow</code> <code>flood.rule</code> Live alias for extended <code>flood.filter</code> on rule-engine repeaters and FULL ESP32 room servers. A row can AND packet type, hop range, optional channel match, ordered 1/2/3-byte pbyte source prefix, and original scope/region conditions, then drop, rewrite to a direct scope or configured region, enforce a per-row rate, allow flood retry, and/or stop lower-priority FPF7 rules. <code>channel=*</code> means no channel condition; <code>public</code>, <code>#name</code>, and keys authenticate; <code>hash:XX</code> is an unauthenticated one-byte fallback with collision/spoof risk. With no <code>retry</code> rows, global retry behavior is unchanged; once any exists, matching <code>retry</code> rows allow-list received floods while the global retry gates and <code>flood.retry.bridge</code> algorithm still apply. <code>scope=BlackHole86</code> directly derives a regionless sink scope; <code>region=BlackHole86</code> would require a configured flood-allowed region. All rows match the original receive-time packet. Higher numeric <code>priority</code> runs first; equal values automatically order authenticated channels before raw hashes before <code>channel=*</code>, then use lower slot as the final tie-break. Repeated rows with one channel key share a per-packet authentication result. Persistent FPF7 stores canonical region names, so region ID reorder or reuse cannot retarget a rule. A missing saved region makes its <code>region=</code> rewrite and paired <code>stop</code> inert until the name returns, allowing lower safety rows to run. Fixed 240 KB STM32WL profiles keep FPF6 and do not expose this alias; partition sizes are unchanged. <code>get flood.rule[.n]</code>, <code>set flood.rule[.n] type=&lt;type&gt; [hops=...] [channel=...] [prefix=...] [in=...] &lt;drop|scope=...|region=...|rate=N/min|retry|stop&gt; [priority=0-255]</code>, <code>del flood.rule.&lt;n&gt;|all</code> <code>set flood.rule.2 type=any channel=#hamradio retry</code> <code>flood.moderation</code> Decrypts keyed <code>GRP_TXT</code> channels and applies drop, per-username messages/minute, and maximum-hop controls, optionally matched against the first 1-3 path hashes. Supports <code>public</code>, <code>#channel</code>, and 128/256-bit channel keys. Sender names and truncated path hashes are moderation hints, not authenticated identities. <code>get flood.moderation[.n]</code>, <code>set flood.moderation[.n] &lt;channel&gt; &lt;sender&gt; &lt;drop|rate=X/min|hops=N&gt; [path=...]</code>, <code>del flood.moderation.&lt;n&gt;|all</code> <code>set flood.moderation public \"Noisy User\" rate=5/min hops=4</code> <code>clock.sync.mesh</code> Defaults on for all repeater, sensor, and room-server builds; a saved setting overrides that default. It estimates UTC as soon as the configured number of fresh signed-advert or valid Public-channel sources is collected, with a 30-minute bootstrap/retry timer when evidence is still insufficient, then repeats lazily seven days after each successful estimate. New evidence retriggers evaluation after a no-consensus result. <code>clock.sync.mesh now</code> queues an immediate LoRa-only attempt without bypassing quorum or source suppression. Only timestamps from firmware build time through build time plus ten years are recorded. Successful CLI, GPS, or WiFi/NTP clock updates suppress LoRa time collection until reboot; after reboot LoRa is the fallback if NTP cannot sync. Status reports the reason a clock was not set; its <code>.table</code> and <code>.1</code> through <code>.16</code> forms inspect collected samples. <code>get clock.sync.mesh</code>, <code>set clock.sync.mesh &lt;on|off&gt;</code>, <code>clock.sync.mesh now</code>, <code>get clock.sync.status[.table|.1-.16]</code> <code>set clock.sync.mesh on</code> <code>clock.sync.mesh.edge</code> Defaults on so edge infrastructure nodes can collect clock evidence when all packets arrive through one relay path. Verified evidence is observed before the forwarding decision, so disabled forwarding and forwarding filters do not prevent collection. Signed adverts are deduplicated by public key and Public-channel timestamps by case-insensitive display name; all may share one receive path. Public display names are unauthenticated and can be spoofed. Changing this setting clears current clock samples. <code>get clock.sync.mesh.edge</code>, <code>set clock.sync.mesh.edge &lt;on|off&gt;</code> <code>set clock.sync.mesh.edge on</code> <code>clock.sync.internet</code> Adds a read-only internet/NTP estimate at the same initial and seven-day checks on WiFi MQTT repeater-observer builds. Other builds retain the setting but report internet unavailable. <code>get clock.sync.internet</code>, <code>set clock.sync.internet &lt;on|off&gt;</code> <code>set clock.sync.internet on</code> <code>clock.sync.drift</code> Absolute correction threshold in seconds; the default is 600 seconds (10 minutes). The clock is moved forward or backward only when the estimate differs by more than this value. <code>get clock.sync.drift</code>, <code>set clock.sync.drift &lt;30-86400&gt;</code> <code>set clock.sync.drift 600</code> <code>clock.sync.samples</code> Minimum fresh evidence count before mesh time can be used: distinct receive paths in normal mode or distinct advert keys/Public-channel display names in edge mode. A strict majority of all fresh samples is also required. Range <code>3-16</code>; default <code>9</code>. <code>get clock.sync.samples</code>, <code>set clock.sync.samples &lt;3-16&gt;</code> <code>set clock.sync.samples 9</code> <code>outpath</code> Overrides the primary direct route used for replies to the current remote client. <code>get outpath</code>, <code>set outpath &lt;hops&gt;</code>, <code>set outpath direct</code>, <code>set outpath clear</code>, <code>set outpath flood</code> <code>set outpath A1B2C3,D4E5F6</code> <code>altpath</code> Adds a secondary direct route for repeater replies to the current remote client. <code>get altpath</code>, <code>set altpath &lt;hops&gt;</code>, <code>set altpath direct</code>, <code>set altpath clear</code>, <code>set altpath flood</code> <code>set altpath 71CE82,BA09F0</code> <p>The generalized filter table also accepts <code>fr</code> as a short alias for <code>flood.rule</code>: <code>set fr.3 any c=#wardriving m=bc d</code> is the full third built-in rule. Modes can be <code>m=r</code> (radio), <code>m=b</code> (bridge), <code>m=c</code> (crossover), or <code>m=bc</code> (both transport paths). <code>get fr.N</code> returns a short setter ready to copy; <code>del fr.N</code> deletes that row. Full names and short tokens can be mixed, with the same validation and permissions. See the shorthand reference.</p>"},{"location":"halo_keymind_settings/#other-keymind-commands","title":"Other Keymind Commands","text":"Command What it does How to use Example <code>send text.flood</code> Sends a <code>#repeaters</code> flood text message formatted as <code>&lt;node_name&gt;: &lt;message&gt;</code>, with <code>:</code> in the node name sent as <code>;</code>. <code>send text.flood &lt;message&gt;</code> <code>send text.flood checking ridge link</code>"},{"location":"halo_keymind_settings/#battery-alerts","title":"Battery Alerts","text":"<p>Battery alerts are off by default. Enabling requires a named region. With no region argument, the repeater selects the single deepest (most narrow) region in the hierarchy; if multiple regions tie, the command asks for an explicit region. For example, after <code>region def west pnw wa w-wa sea</code>, <code>set battery.alert on</code> selects <code>sea</code>, while <code>set battery.alert on w-wa</code> overrides the default. Alerts are never sent as unscoped floods, and removing the selected region stops alerts until a valid scope is selected again.</p> <p>The repeater suppresses alerts for its first 30 minutes of uptime. It then checks every 30 minutes and sends a flood text warning to <code>#repeaters</code> when voltage is above <code>1 V</code> and the estimated battery percent is below <code>battery.alert.low</code>.</p> <p>Warnings and critical alerts both use a <code>12</code>-hour resend cooldown, beginning only after the radio reports that the alert transmission completed.</p> <p>Defaults:</p> Setting Default <code>battery.alert</code> <code>off</code> <code>battery.alert.region</code> <code>&lt;unset&gt;</code> <code>battery.alert.low</code> <code>20</code> <code>battery.alert.critical</code> <code>10</code> <p>Example:</p> <pre><code>set battery.alert.low 20\nset battery.alert.critical 10\nset battery.alert on\nget battery.alert\nget battery.alert.region\n</code></pre> <p>CPU power saving remains compatible with the check. The battery timer never requests a wake earlier than its 30-minute deadline; when the normal loop is already awake after that deadline, no additional wake is needed. Sleeping time counts toward the startup delay, and an outbound warning prevents another sleep until the queued packet has been handled. This is separate from RX duty-cycle power saving, which only cycles the LoRa receiver and does not stop the main loop's battery timer.</p>"},{"location":"halo_keymind_settings/#recent-repeater-table","title":"Recent Repeater Table","text":"<p>Direct retry uses the recent repeater table when <code>direct.retry.heard</code> is <code>on</code>. Bridge buckets also use this table: a configured bucket prefix is active only when it was heard within the last hour.</p> <p>Show learned rows:</p> <pre><code>get recent.repeater\nget recent.repeater 2\nget recent.repeaters 2\nget recent.repeater page 3\nget recent.repeaters search A1\nget recent.repeaters search A1B2 page 2\n</code></pre> <p>Search matches overlapping 1-, 2-, and 3-byte path hashes. Each matching row shows its stored SNR and a whole <code>s</code>, <code>m</code>, or <code>h</code> age measured from the most recent recording. Search pages contain up to six rows.</p> <p>Seed or correct a prefix:</p> <pre><code>set recent.repeater A1B2C3 8.5\n</code></pre> <p>Clear learned and manually seeded rows:</p> <pre><code>clear recent.repeater\n</code></pre> <p>Rows are sorted by prefix width, then SNR. A full direct retry failure lowers the matching row by <code>0.25 dB</code>. Unfiltered paged replies contain up to <code>10</code> rows; an unpaged local serial query prints the full table.</p>"},{"location":"halo_keymind_settings/#direct-path-overrides","title":"Direct Path Overrides","text":"<p><code>outpath</code> and <code>altpath</code> apply to the current remote client ACL entry. They need remote client context, so they are not useful from the local serial CLI.</p> <p>Set paths with comma-separated hop hashes. Each hop must be <code>2</code>, <code>4</code>, or <code>6</code> hex characters, and all hops in one path must use the same width. Hex input is case-insensitive. Replies use uppercase hex and retain the commas, so the value can be copied directly into another <code>set outpath</code> or <code>set altpath</code> command.</p> <pre><code>get outpath\nget outpath path\nset outpath A1B2C3,D4E5F6\nset outpath path\nset outpath direct\nset outpath clear\nset outpath flood\nget altpath\nset altpath 71CE82,BA09F0\nset altpath clear\n</code></pre> <p>For example, both <code>set altpath 600000,0d2784,f8dada</code> and <code>Set altpath 600000,0d2784,f8dada</code> store the same path and reply with:</p> <pre><code>&gt; 600000,0D2784,F8DADA\n</code></pre> <p>The first CLI word is case-insensitive (<code>set</code>, <code>Set</code>, and <code>SET</code> are the same, as are <code>get</code>, <code>Get</code>, and the other command verbs). Argument case is preserved.</p> <p><code>get outpath path</code> reports the reciprocal path received after the latest flood login without changing <code>outpath</code>. That packet arrives asynchronously, so retry shortly if the first query reports <code>&gt; path pending</code>; the observation window expires after one minute. The login path is not automatically selected. <code>set outpath path</code> copies the observed route into <code>outpath</code> and saves it; it leaves the current route unchanged when no observed route is available.</p> <p><code>set outpath direct</code> sets a zero-hop direct route for a client reachable without repeaters. <code>set outpath clear</code> forgets the override, replies <code>&gt; outpath cleared</code>, and lets normal path discovery fill it again. <code>set outpath flood</code> forces replies to use flood packets until the client logs in again.</p> <p>When <code>outpath</code> is a valid direct path and <code>altpath</code> is also a valid, different direct path, repeater DM replies send two packets: one on <code>outpath</code> and one on <code>altpath</code>. The secondary <code>altpath</code> copy does not create its own direct-retry state, so retry tracking stays attached to the primary <code>outpath</code> packet. <code>altpath clear</code> disables the secondary direct reply. <code>altpath flood</code> is accepted for command symmetry, but it does not create a second flood reply; only a valid direct <code>altpath</code> sends the second packet.</p>"},{"location":"halo_keymind_settings/#direct-retry-settings","title":"Direct Retry Settings","text":"<p>Direct retry applies to direct-routed packets. A queued resend is canceled when the next-hop echo is heard. Repeaters expose the settings below; non-repeater firmware uses the same packet-type timing rules with fixed shared base/step timing.</p> Setting What it does How to use Example <code>retry.preset</code> Applies shared direct and flood retry defaults. Values: <code>infra</code>, <code>rooftop</code>, <code>mobile</code> or <code>0</code>, <code>1</code>, <code>2</code>. <code>get retry.preset</code>, <code>set retry.preset &lt;value&gt;</code> <code>set retry.preset rooftop</code> <code>direct.retry.heard</code> Uses the recent repeater table as the direct retry eligibility gate. <code>get direct.retry.heard</code>, <code>set direct.retry.heard on/off</code> <code>set direct.retry.heard on</code> <code>direct.retry.margin</code> SNR margin in dB above the SF-specific receive floor. <code>get direct.retry.margin</code>, <code>set direct.retry.margin &lt;0-40&gt;</code> <code>set direct.retry.margin 5</code> <code>direct.retry.count</code> Maximum direct retry attempts after initial TX. Direct-routed type 2 text packets always use 21 attempts regardless of this setting or the short-path cap. <code>get direct.retry.count</code>, <code>set direct.retry.count &lt;1-15&gt;</code> <code>set direct.retry.count 15</code> <code>direct.retry.base</code> Base wait in milliseconds before retry; packet-length add-on is 3x for TRACE and ANON_REQ/type 7, 7x for TXT_MSG/type 2, and 6x for other direct retry packets. <code>get direct.retry.base</code>, <code>set direct.retry.base &lt;10-5000&gt;</code> <code>set direct.retry.base 175</code> <code>direct.retry.step</code> Milliseconds added per retry attempt after the base, packet-length add-on, and random forwarding jitter. <code>get direct.retry.step</code>, <code>set direct.retry.step &lt;0-5000&gt;</code> <code>set direct.retry.step 100</code> <code>direct.retry.cr</code> Adaptive coding-rate thresholds for repeater direct retry packets. Repeaters use <code>CR4</code>, <code>CR5</code>, <code>CR7</code>, or <code>CR8</code>, then escalate by attempt: CR4, CR5, CR7, CR7, then CR8 from a CR4 start; CR5, CR7, CR7, then CR8 from a CR5 start. Non-repeaters start at the current radio CR and follow the same escalation pattern, clamped at CR8. <code>get direct.retry.cr</code>, <code>set direct.retry.cr &lt;cr4_min&gt;,&lt;cr5_min&gt;,&lt;cr7_min&gt;,&lt;cr8_max&gt;</code>, <code>set direct.retry.cr off</code> <code>set direct.retry.cr 10.0,7.5,2.5,0</code> <p>The default adaptive coding-rate profile is <code>10.0,7.5,2.5,2.5</code>. SNR <code>10.0 dB</code> and up uses <code>CR4</code>, <code>7.5 dB</code> and up uses <code>CR5</code>, <code>2.5 dB</code> and down uses <code>CR8</code>, and the middle band uses <code>CR7</code>. If no recent repeater table entry is available, retry packets use <code>CR5</code>. Use <code>set direct.retry.cr off</code> to disable adaptive coding-rate overrides. Repeater attempts escalate from the adaptive starting CR: <code>CR4</code>, <code>CR5</code>, <code>CR7</code>, <code>CR7</code>, then <code>CR8</code> from a <code>CR4</code> start; <code>CR5</code>, <code>CR7</code>, <code>CR7</code>, then <code>CR8</code> from a <code>CR5</code> start. Non-repeaters use the current radio CR as the first retry CR and follow the same pattern up to <code>CR8</code>.</p> <p>Preset details:</p> Preset Base Count Step SNR gate <code>infra</code> <code>275 ms</code> <code>4</code> <code>150 ms</code> SF floor + <code>15 dB</code> <code>rooftop</code> <code>175 ms</code> <code>15</code> <code>100 ms</code> SF floor + <code>5 dB</code> <code>mobile</code> <code>175 ms</code> <code>15</code> <code>50 ms</code> SF floor <p>Example for a quiet fixed repeater:</p> <pre><code>set retry.preset rooftop\nset direct.retry.heard on\nset direct.retry.margin 5\n</code></pre> <p>Example for a moving or weak-link node:</p> <pre><code>set retry.preset mobile\nset direct.retry.margin 0\n</code></pre>"},{"location":"halo_keymind_settings/#flood-and-advert-settings","title":"Flood And Advert Settings","text":"<p>Flood retry applies to flood-routed packets. A queued retry is canceled when the same packet is heard from a qualifying, non-ignored repeater. Bridge mode uses the bucket rules below instead.</p> Setting What it does How to use Example <code>flood.retry.count</code> Base flood retry attempts after initial TX. Role path scaling happens first, then all builds apply payload caps: <code>REQ</code> is <code>0</code>; <code>GRP_TXT</code> keeps up to <code>15</code>; remote-login <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code> keep up to <code>15</code> at path count 0 and cap at <code>2</code> in transit; every other flood type caps at <code>1</code>. A lower calculated value is preserved, and <code>0</code> disables flood retry. <code>get flood.retry.count</code>, <code>set flood.retry.count &lt;0-15&gt;</code> <code>set flood.retry.count 7</code> <code>flood.retry.path</code> Maximum path hash count eligible for flood retry, or <code>off</code> to disable the gate. <code>get flood.retry.path</code>, <code>set flood.retry.path &lt;0-63/off&gt;</code> <code>set flood.retry.path 1</code> <code>flood.retry.group.path</code> Additional path gate for group data (<code>type=6</code>) flood retries. The stricter of this and <code>flood.retry.path</code> applies; <code>off</code> disables only this additional gate. Setting the general path gate to <code>0</code> forces this setting to <code>off</code>; a named preset restores the default of <code>1</code>. <code>get flood.retry.group.path</code>, <code>set flood.retry.group.path &lt;0-63/off&gt;</code> <code>set flood.retry.group.path 1</code> <code>flood.retry.advert</code> Allows or blocks retry for node advert packets (<code>type=4</code>). Default is <code>off</code>. <code>get flood.retry.advert</code>, <code>set flood.retry.advert on/off</code> <code>set flood.retry.advert off</code> <code>flood.retry.prefixes</code> Target prefixes. If set, only same-packet echoes from matching last-hop prefixes cancel a retry. <code>get flood.retry.prefixes</code>, <code>set flood.retry.prefixes &lt;prefixes/none/off&gt;</code> <code>set flood.retry.prefixes BEEBB0,425E5C</code> <code>flood.retry.ignore</code> Ignored prefixes. In non-bridge retry, ignored last-hop echoes do not cancel retry. <code>get flood.retry.ignore</code>, <code>set flood.retry.ignore &lt;prefixes/none/off&gt;</code> <code>set flood.retry.ignore 71CE82,C7618C</code> <code>flood.retry.bridge</code> Enables bucket-based bridge retry logic. <code>get flood.retry.bridge</code>, <code>set flood.retry.bridge on/off</code> <code>set flood.retry.bridge on</code> <code>flood.retry.bucket.&lt;n&gt;</code> Shows one bridge bucket. Buckets are numbered <code>1</code>-<code>6</code>. <code>get flood.retry.bucket.&lt;n&gt;</code> <code>get flood.retry.bucket.1</code> <code>flood.retry.bucket</code> Sets bridge bucket prefixes. <code>set flood.retry.bucket &lt;1-6&gt; &lt;prefixes/none/off&gt;</code> <code>set flood.retry.bucket 1 71CE82,C7618C</code> <p>Extended <code>flood.rule</code> rows can select which received floods may use these settings. For example, enable bridge completion only for Public and <code>#hamradio</code> with <code>set flood.rule type=any channel=public retry</code> and a second row using <code>channel=#hamradio</code>. Adding the first active <code>retry</code> row changes received retry selection into an allow-list; deleting the last restores the legacy global selection. <code>channel=hash:XX</code> is available when only the visible one-byte hash is known, but it is not authenticated and is collision-prone. For example, <code>hash:11</code> includes Public and any other packet using <code>0x11</code>; <code>channel=public</code> alone performs the Public-key MAC/decrypt check.</p> <p>Bridge buckets may also be reused as passive <code>flood.channel.scope</code> path selectors with <code>path=bucket:&lt;1-6&gt;</code>. This does not require <code>flood.retry.bridge</code> to be enabled and does not depend on recent-repeater freshness or the retry ignore list.</p> <p>Forwarded neighbor adverts also use an automatic echo guard in every build. If this node hears a downstream, longer-path echo after transmitting an advert whose signed timestamp is less than six hours old, it will not forward that exact advert again during the six-hour age window. This guard works even when <code>flood.retry.advert</code> is off and does not affect self-originated adverts.</p> <p>Self-originated advert retries are deliberately slow: the first retry waits at least one extra minute beyond the normal airtime-aware delay. Queueing a newer self advert retires queued and future retry attempts for older self adverts without disturbing other flood retry sequences. Companion firmware allows the one slow retry for its own adverts but not for neighbor adverts it relays.</p> <p>The shared retry preset sets these flood defaults:</p> Preset Retry count Path gate Group-data path gate <code>infra</code> <code>1</code> <code>1</code> <code>1</code> <code>rooftop</code> <code>3</code> <code>2</code> <code>1</code> <code>mobile</code> <code>15</code> <code>1</code> <code>1</code> <p>Hop-zero flood retries use the direct-retry CR ladder starting at the active radio CR. With CR5, <code>infra</code> allows CR5, CR7; <code>rooftop</code> allows CR5, CR7, CR7, CR8, CR8, CR8; <code>mobile</code> allows CR5, CR7, CR7, then CR8 through retry 15. These lists exclude the initial send and remain subject to payload caps and echo cancellation. Floods with recorded hops keep the active CR. <code>flood.retry.count 0</code> still disables every automatic flood retry, including hop zero, without changing direct-retry settings or their CR schedule. See hop-zero flood retry coding rate for every starting CR and the payload limits.</p> <p>Example for path-gated retry:</p> <pre><code>set retry.preset rooftop\nset flood.retry.path 1\nset flood.retry.group.path 1\nset flood.retry.advert off\nset flood.retry.ignore 71CE82,C7618C\n</code></pre>"},{"location":"halo_keymind_settings/#north-south-buckets","title":"North South Buckets","text":"<p>Buckets describe groups of repeaters on different sides of this relay. Bucket numbers do not have built-in meanings; this example uses bucket <code>1</code> for North and bucket <code>2</code> for South.</p> <pre><code>              North bucket 1\n        +-----------------------+\n        | A1B2C3       D4E5F6   |\n        | North A      North B  |\n        +-----------+-----------+\n                    |\n                    v\n              +-----------+\n              | This node |\n              +-----------+\n                    ^\n                    |\n        +-----------+-----------+\n        | 71CE82       C7618C   |\n        | South A      South B  |\n        +-----------------------+\n              South bucket 2\n</code></pre> <p>Configure the buckets:</p> <pre><code>set flood.retry.bridge on\nset flood.retry.bucket 1 A1B2C3,D4E5F6\nset flood.retry.bucket 2 71CE82,C7618C\nset flood.retry.ignore none\n</code></pre> <p>Packet heard from the North:</p> <pre><code>     heard source\n         |\n         v\n  +--------------+        retry targets\n  | North bucket | -----&gt; South bucket\n  | bucket 1     | -----&gt; Other fresh/unbucketed relays\n  +--------------+\n</code></pre> <p>Packet heard from the South:</p> <pre><code>     heard source\n         |\n         v\n  +--------------+        retry targets\n  | South bucket | -----&gt; North bucket\n  | bucket 2     | -----&gt; Other fresh/unbucketed relays\n  +--------------+\n</code></pre> <p>Packet heard from an unbucketed or pathless source:</p> <pre><code>     heard source\n         |\n         v\n  +--------------+        retry targets\n  | Other bucket | -----&gt; North bucket\n  | implicit     | -----&gt; South bucket\n  +--------------+\n</code></pre> <p>Bridge retry stays eligible until every target bucket has been heard or <code>flood.retry.count</code> is exhausted. A configured bucket is a target only when at least one of its prefixes is fresh in <code>recent.repeater</code>. Prefixes in <code>flood.retry.ignore</code> never count as bucket hits.</p> <p>Configuration reports a warning when prefixes in different buckets, including bucket 7 (<code>flood.retry.prefixes</code>), share the same first byte. A 1-byte path cannot distinguish those buckets. Bridge mode therefore excludes every matching bucket when that short prefix is the source, and credits every matching target bucket when it is heard as an echo. This prevents an ambiguous short prefix from keeping an impossible target outstanding through every retry.</p> <p>Each flood retry wait retains the fixed maximum-frame plus 20 packet-airtime delay, then adds random jitter from zero to 200 percent of one additional packet airtime. This keeps nearby repeaters from repeating a collision on fixed timing while capping the added wait at two frames.</p> <p>Only one enhanced retry sequence can be active for the same logical flood packet. Identical floods still receive their normal transmission, but do not multiply the extra attempts. Evicted queued retries release their bridge state, and the final echo wait does not reserve a packet-pool entry.</p> <p>Earlier path hops from a successful bridge echo refresh a separate per-bucket reachability cache without an SNR value. Only the final hop, which actually sent the received RF frame, updates <code>recent.repeater</code> and its SNR. Indirect path hops therefore cannot change direct-retry SNR gating or coding-rate selection.</p>"},{"location":"halo_keymind_settings/#troubleshooting","title":"Troubleshooting","text":"<p>If advert packets are still retrying:</p> <pre><code>get flood.retry.advert\nset flood.retry.advert off\n</code></pre> <p>If ignored prefixes still appear in <code>flood retry good</code> logs:</p> <pre><code>get flood.retry.ignore\nset flood.retry.ignore &lt;prefix&gt;\n</code></pre> <p>The ignored prefix must match the last hop shown as <code>heard=&lt;prefix&gt;</code>. For example, this log needs <code>C7618C</code> in the ignore list:</p> <pre><code>flood retry good (... path=7773D0&gt;C7618C, heard=C7618C ...)\n</code></pre> <p>If retries are too aggressive:</p> <pre><code>set flood.retry.count 1\nset flood.retry.path 1\nset direct.retry.count 4\n</code></pre> <p>If retries are too sparse:</p> <pre><code>set flood.retry.count 7\nset flood.retry.path 2\n</code></pre>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/","title":"XIAO Bluetooth stealth hardware validation - 2026-09-07","text":"<p>Historical command syntax: the initial run used stealth as a MAC mode. Current firmware uses the independent <code>bluetooth.stealth on|off</code> flag instead and does not migrate that development mode. See current commands and the independent-flag follow-up below. Each observation applies only to the exact artifact listed in its section.</p> <p>This is a hardware observation report, not an all-board or phone qualification. The test host was the MercerWoodMesh Raspberry Pi Zero 2 W, accessed remotely over Tailscale. Tests used its built-in Bluetooth adapter, not USB resets or hub power switching. Local timestamps below use America/Los_Angeles.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#exact-target-and-firmware","title":"Exact target and firmware","text":"<ul> <li>Board: Seeed XIAO nRF52840; application name <code>MeshCore-4610BBD2</code>.</li> <li>Factory/bootloader address: <code>E5:C3:A8:B0:60:66</code>.</li> <li>Fresh stealth test address: <code>DC:8D:5E:45:89:6F</code>.</li> <li>Bonded test central: Mercer Pi, public address <code>B8:27:EB:F9:6E:8E</code>.</li> <li>Environment: <code>Xiao_nrf52_companion_radio_ble</code>, supported build wrapper,   target radio preset, default profile, GCC 14.2.1.</li> <li>Firmware: <code>dev-stealth3-4b400ea5</code>, including the uncommitted Bluetooth   identity changes on top of <code>4b400ea5</code>.</li> <li>Application ZIP SHA-256:   <code>acdce0af2334349c6e0a5786db5525b00d19befef340411d2e99008ce4d316ae</code>.</li> <li>Linked RAM: 183,232 / 237,568 bytes; flash: 616,504 / 708,608 bytes.</li> </ul> <p>The application was installed with Nordic Legacy BLE DFU. The tool verified the exact ZIP hash, bootloader advertisement and live DIS model <code>XIAO nRF52840</code> before transmitting 616,584 application bytes. Target image validation and target-initiated activation disconnect passed. The transfer reported about 2,223 bytes/second (about 277 seconds for payload transmission). Authenticated MeshCore device queries subsequently returned protocol 14, board <code>Seeed Xiao-nrf52</code>, and the expected unique test-version prefix.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#observed-results","title":"Observed results","text":"Check Result and evidence First-pair discovery <code>set bluetooth.mac stealth</code> saved a new random-static address; reboot returned that exact address with the normal name and Nordic UART advertisement. First authenticated pairing The Pi received a passkey request and completed pairing. BlueZ reported both Paired and Bonded. MITM-protected Nordic UART notifications and real command/reply exchanges worked at MTU 247. Pairing transition keeps the session alive The initial connection returned <code>stealth; bonded-peer-only advertising</code>, remained usable for five more seconds, and answered another command without disconnecting or pairing again. Advertising after disconnect A public-address passive scan captured <code>ADV_DIRECT_IND</code> from the exact target, with advertising data length zero. The capture contained no undirected advertisement or scan response from that address. Bonded reconnect Subsequent direct connections by saved BlueZ device identity succeeded without a new passkey, including live version, core-statistics and Bluetooth-mode replies. Warm reboot persistence Two commanded reboots retained the address and saved bond. Directed advertising was captured after reboot, followed by authenticated reconnect. Device uptime decreased from 61 seconds before the second reboot to 35 seconds at the next query; core error flags were zero. Slow advertising interval A successful bonded reconnect occurred about 61 seconds after reboot, beyond the 30-second fast-advertising interval. Reopen pairing Setting <code>stealth</code> again from an existing bonded connection generated a new address, and the next boot allowed a fresh first pairing. Restore default <code>set bluetooth.mac default</code> plus reboot restored <code>E5:C3:A8:B0:60:66</code> and normal discovery. Fresh PIN pairing, version/core-statistics queries and repeated <code>factory address (default)</code> replies passed. The bench target was left in this discoverable mode. <p>The newly completed pairing reaches Bluefruit's secured callback before its bonded flag is necessarily ready. Recording the completed pairing in the pair-complete callback as well, waiting for the deferred bond write, and deferring identity-list reconfiguration until disconnect are covered by this fresh-pair hardware run. Static source contracts also check those paths.</p> <p>The binary reboot command can reset the target before BlueZ receives its ATT write acknowledgement. One initial harness run reported <code>Unlikely Error</code> after successful pre-reboot commands. Later checks require an observed disconnect, a live post-reboot query and decreased device uptime; they do not treat the write exception or tool exit code alone as a successful reboot.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#discovery-and-dfu-cautions-found-during-testing","title":"Discovery and DFU cautions found during testing","text":"<p>An ordinary BlueZ discovery scan used a temporary random local address and did not show the directed target. A passive scan using the Pi's public identity did show it. Reconnection must use the saved peer/device identity; absence from an ordinary scan is not proof that the node stopped working. Conversely, BlueZ can retain a cached name after pairing, so a displayed name is not proof that the name is still being advertised. The packet-type and zero-length-payload capture is the relevant evidence here.</p> <p>The existing DFU handoff helper assumed the application and bootloader shared one address. That assumption is false with a custom application address: the authenticated handoff worked, but the helper timed out looking for DFU at the application address. A fresh exact-address scan found the known factory-address <code>XIAO_DFU</code> instead. An old factory-address host bond also caused the first DFU service-discovery attempt to disconnect; clearing only that old lab record allowed DFU. No bootloader code was changed for this test.</p> <p>An earlier application-address host pairing record was also removed before its saved stealth state was known. A direct, known-address connection from the same Pi identity allowed fresh PIN pairing and protected commands again. This does not prove that an arbitrary replacement phone can rediscover or recover a stealth node after forgetting its bond.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#remaining-hardware-gates","title":"Remaining hardware gates","text":"<ul> <li>True cold boot with all XIAO power sources, including battery, disconnected.   The XIAO reported a battery voltage and did not enumerate as USB on the Pi;   a Pi-only reboot or power cycle would not prove this gate.</li> <li>Unused-boot retention with <code>random-after-connect</code>, using a reboot trigger   that does not itself authenticate over BLE. The policy has native tests;   the remote BLE reboot command cannot prove this hardware gate.</li> <li>Android and iOS bonded reconnect, including a phone changing its resolvable   private address, and direct-connection behavior in the actual MeshCore app.</li> <li>Rejection of a connection from a second, unbonded physical central.</li> <li>ESP32 Bluedroid and NimBLE hardware. Those use allowlisted minimal   advertising rather than nRF52 directed advertisements.</li> <li>Node-side missing/corrupt bond and failed settings/bond-write fault injection.</li> </ul>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#repeatable-regression-procedure","title":"Repeatable regression procedure","text":"<ol> <li>Record the exact board, application version, ZIP hash, local/remote BLE    identities and original Bluetooth setting. Keep a working recovery path.</li> <li>Set the desired custom or random MAC, enable <code>bluetooth.stealth on</code>, reboot,    and capture normal discovery before pairing.</li> <li>Pair once. Require a stored bond and successful protected MeshCore commands,    then keep the original session open and issue another command.</li> <li>Disconnect. Capture the actual advertising type and payload with an    appropriate receiving identity; do not use cached scan names as evidence.</li> <li>Reconnect by the saved peer without another PIN and exchange commands.</li> <li>For custom and saved-random addresses, repeat <code>bluetooth.stealth on</code>, reboot    twice, and verify unchanged identity/bond, decreased uptime and live    commands. Include a reconnect after the fast-advertising period ends.</li> <li>Separately remove all target power and repeat the persistence checks.</li> <li>Test <code>bluetooth.stealth off</code>, then <code>on</code>, as a pairing reset, and <code>off</code> as    the exit from stealth. Verify live discovery, pairing, commands and an    unchanged MAC policy. Changing the address to <code>default</code> is a separate step.</li> <li>With each rotating MAC policy, verify that its rotation trigger still    works, stealth stays enabled, and the new address permits fresh pairing.</li> <li>Repeat relevant gates for a phone with address privacy and each BLE backend.</li> </ol> <p>Raw VM-side logs, the exact artifact and bounded test helper are in <code>/home/mesh/mercer-stealth-validation.jUDW0v/</code>. Raw Bluetooth captures are local diagnostics and should not be published without privacy review.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#mercer-crash-capture","title":"Mercer crash capture","text":"<p>During this run the Pi used its existing <code>dwc_otg.speed=1</code> full-speed USB configuration. Kernel and health logs were streamed to this VM. No new kernel errors or Pi lockup were observed during these tests; that does not establish the cause of the earlier lockup.</p> <p>The live test streams and all temporary scans were stopped at approximately 22:56 PDT. Journald remained active, the restore service remained enabled, and the test XIAO was disconnected in default mode. Disk journals occupied about 4.9 MiB at the final check.</p> <p>At 22:35 PDT, temporary persistent journaling was enabled with a 16 MiB configured disk-use limit, 2 MiB journal files, one-day retention and a 30-second normal sync interval. Recent buffered messages can still be lost in a sudden failure. The original <code>Storage=volatile</code> configuration is intact.</p> <p><code>mercer-crash-capture-restore.service</code> is enabled for the next Pi boot. It checks the armed boot ID, removes only the unchanged managed override, switches journald back to RAM and leaves the old disk journals for collection. Its same-boot no-op guard and unit syntax passed. The next-boot restoration has not yet been exercised; no Pi crash or reboot was deliberately induced.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#independent-flag-follow-up-dev-stflag","title":"Independent-flag follow-up - dev-stflag","text":"<p>The same XIAO and Pi were used later on 2026-09-07 to test the separate <code>bluetooth.stealth on|off</code> flag, with no development-mode migration. This run used <code>Xiao_nrf52_companion_radio_ble</code>, target radio preset, default profile, and firmware <code>dev-stflag-4b400ea5</code> with the uncommitted flag changes.</p> <ul> <li>Application ZIP SHA-256:   <code>48fc0ff2c716281771f8b525c62a0015c7605b07e7c513ab854c8b3ff3113f42</code>.</li> <li>Linked RAM: 183,232 / 237,568 bytes; flash: 617,192 / 708,608 bytes.</li> <li>Nordic Legacy BLE DFU verified the exact target, hash and model, transferred   617,272 application bytes at a reported 3,522 bytes/second, passed target   validation, and observed the target activation disconnect.</li> <li>Protected live device queries returned <code>dev-stflag-4b400ea5</code>, protocol 14,   and <code>Seeed Xiao-nrf52</code>; every queried core error-flags value was zero.</li> </ul> Check Observed result Default and rejected input Initial mode was factory address with stealth off. <code>set bluetooth.mac stealth</code> and <code>set bluetooth.stealth maybe</code> returned errors, leaving both settings unchanged. Custom plus stealth <code>D2:27:5A:40:06:99</code> advertised normally before first pairing. Fresh PIN pairing, stored bond, protected commands, and a five-second held session passed with stealth on. Repeated on and warm reboot Repeating <code>set bluetooth.stealth on</code> retained the paired state. After reboot, the same custom address accepted protected commands without another PIN. Uptime decreased from 84 to 67 seconds. Actual advertising after reboot A public-address passive capture showed <code>ADV_DIRECT_IND</code> for the custom address, data length zero, and no undirected advertisement or scan response from that address. The scan was explicitly disabled afterward. Off preserves custom address <code>set ble.stealth off</code> and reboot restored normal discovery at the same custom address. A live connection returned stealth off and the unchanged custom policy. Saved random plus stealth <code>F2:2E:E5:65:18:5E</code> passed first pairing and held commands. After reboot, it retained its address, saved-random policy and stealth bond; protected reconnect needed no PIN. Uptime decreased from 55 to 30 seconds. Random-after-connect plus stealth Selecting this policy kept stealth on and reopened pairing at <code>C7:FD:29:44:4F:3E</code>. Pairing produced both bonded-peer-only status and an armed next-boot rotation. Reboot changed the address to <code>F5:F3:89:B7:B5:26</code>, where normal discovery, fresh pairing and protected commands passed with stealth still on. Random-every-boot plus stealth The first boot used <code>F9:B2:03:DD:CC:43</code>, completed fresh pairing, and answered commands with stealth on. The next commanded reboot advertised <code>F8:C7:C0:96:1E:00</code>; fresh PIN pairing and protected commands passed again with the rotating policy and stealth on. Restore the bench target Setting the MAC to <code>default</code> kept stealth on until the separate <code>set bluetooth.stealth off</code>. After reboot, factory-address discovery, fresh PIN pairing and protected commands confirmed default MAC and stealth off. The obsolete factory-address host bond was replaced during this final pairing. <p>These checks used actual encrypted BLE connections at MTU 247, not scan sightings alone. Two first-pair harness attempts stopped before connecting because their unpaired BlueZ discovery object no longer existed. A fresh bounded scan immediately followed by pairing was used for retries; this was not a firmware GATT command failure. Reboot-write/disconnect races were accepted only with an observed disconnect and subsequent live device checks.</p> <p>Local automated verification passed 39 native cases, 32 source/persistence/UI contracts, and 11 real-browser cases. Supported-wrapper builds passed for XIAO nRF52, XIAO C3, M5Stack Unit C6L and XIAO S3 WIO Full Companion, covering nRF52, ESP32 NimBLE and ESP32 Bluedroid integration. The contracts and browser suite are included in the unit-test workflow; a browser must be available for the optional browser suite to execute instead of skip.</p> <p>Exact artifacts, build logs, command logs and the private packet capture are in <code>/home/mesh/bluetooth-stealth-flag.ApLB8o/</code> on the VM. The remaining hardware gates above still apply; these results do not qualify every board or phone.</p> <p>At 23:42 PDT the XIAO was disconnected in normal discoverable mode. The Pi retained the same boot ID throughout, remained responsive, and had no new kernel messages in the streamed log. Journald was active, the next-boot volatile-log restoration service was still enabled, and disk journals used about 5.9 MiB. No USB reset, Pi reboot, or target battery removal was used.</p>"},{"location":"hardware_validation_checklist/","title":"Hardware validation checklist","text":"<p>This file records dated hardware observations and open validation tasks. Historical defaults, versions, and test frequencies below describe the tested revision, not necessarily the current release. For current ASCII USB defaults and runtime switches, use feature switches by role.</p> <p>Use this checklist for release-candidate hardware runs. A check is complete only when its log identifies the physical device, firmware artifact, artifact hash, command result, and cold/warm boot outcome. Do not infer success from a tool's exit code when the tool has a documented false-success mode.</p>"},{"location":"hardware_validation_checklist/#bluetooth-stealth-qualification-2026-09-07","title":"Bluetooth stealth qualification - 2026-09-07","text":"<p>The XIAO stealth report records exact artifacts for the initial implementation and independent-flag follow-up. The flag run covers custom/saved-random pairing and bonded reboot reconnect, idempotent <code>on</code>, <code>off</code> preserving the MAC, directed advertising, and both rotating policies with stealth still enabled. It also gives the repeatable hardware regression procedure. True battery-disconnected cold boot, phone address-privacy behavior, a second unbonded central, and ESP32 hardware remain separate uncompleted gates; do not infer them from the XIAO results.</p>"},{"location":"hardware_validation_checklist/#current-marathon-ledger-through-2026-09-04","title":"Current marathon ledger (through 2026-09-04)","text":"Hardware Stable identity Current state Next blocking check Seeed XIAO nRF52840 <code>B35E71C1C3726CE7</code> OTAFIX candidate <code>0x02040405</code> passed exact serial install and corrected Legacy DIS model gates; the patched Bluetooth repeater-updater application was restored over BLE and returned as exact <code>2886:8044</code> USB Use the updater for an identity-gated Bluetooth transfer to another repeater, then prove current-build cold persistence Seeed Tracker T1000-E <code>34A9141999729D5D</code> OTAFIX candidate <code>0x02040405</code> and the <code>uf2reset</code>-fixed Full Companion are installed. The real text command returned exact <code>2886:0057</code> boot USB, the same fixed app was restored, and refreshed bonded BLE services pass as <code>MeshCore-09848C15</code> Restore the protected Repeater identity when Companion qualification is complete; cold boot, then force LR1110 reset RAK3401 <code>0B81C9C68D8D01B4</code>; FICR <code>8D8D01B4 0B81C9C6</code> OTAFIX test version <code>0x02040403</code> passes bidirectional application UF2, exact SWD application/bootloader readback, unchanged UICR, and a 74-block direct V4 LoRa apply from exact <code>3caf9dcf</code> to current HEAD <code>9fd580c8</code>. Post-apply USB and LoRa identity/hash checks pass and the temporary 0 dBm bench setting is restored to 22 dBm Add exact RF packet counters, then repeat the supported-bandwidth and controlled/passive/mixed routed-hop matrix Heltec T096 <code>651F8E496197F882</code> OTAFIX candidate <code>0x02040405</code> and the <code>uf2reset</code>-fixed no-footer Full Companion are installed. The real text command returned exact boot USB, and final USB terminal/Binary mode, dual CDC, version, help, and BLE identity pass Perform a privileged or physical host-driven USB bus reset without resetting the MCU; complete the deferred multi-click/long-press physical matrix Heltec MeshTower V2 with SD <code>9352162A72082314</code> OTAFIX candidate <code>0x02040405</code> passed serial combined install, the historical cached DIS handles, BLE application restore, and exact application USB return. Card format/cooldown/forced-format/raw-erase/remount and the live SD apply contract passed earlier Signed interrupted-download resume, corruption/signature rejection, then full/delta apply Heltec V4 USB MAC <code>44:1B:F6:6A:E8:44</code>; BLE <code>44:1B:F6:6A:E8:45</code> USB/BLE/Wi-Fi and all three TCP services pass on hardware. The final fresh-NTP-gated Full Companion image builds with 4.31 MB app space free Flash the exact final NTP build, prove NTP-before-TLS success/failure ordering, then OTA seeding SenseCAP Indicator LoRa CH340 plus USB MAC <code>D8:3B:DA:75:23:AC</code>; BLE <code>D8:3B:DA:75:23:AD</code> The current dark-layout application is SHA-256 <code>81bebdc07b6a8349c1c975cb5a0e30c5f6019d35bcac641e5f3d4df951f7406b</code>; identity-gated flash, USB ASCII/Binary switching, runtime logging, and separate configured-Wi-Fi, BLE, and TCP checks pass. Fresh-NTP HTTPS recovery, strict Range resume, STAGEV2 install, and RP USB readback passed on earlier exact artifacts; the final coordinator source still needs its blocked-UDP/123 hardware gate Physical display-wrap and four-mode render/heap checks, exact-final blocked-NTP recovery gate, LoRa/TempRadio, and non-empty OTA seeding <p>The current source checkpoint passes 1,132/1,132 native cases, 68/68 host broker/endpoint cases, all 318 LoRa-OTA chain/route/bundle cases, and 41/41 MOTA format/signature/delta cases under the documented pipx <code>detools</code> interpreter. Indicator geometry, dark-theme, and font-recovery contracts pass 4/4, 6/6, and 25/25. A serialized real Indicator ESP32-S3 Wi-Fi/USB profile also compiles at 95,944 bytes RAM and 1,589,433 bytes flash. The direct system-Python MOTA invocation predictably lacks <code>detools</code>; that environment boundary is not a firmware failure and must not be worked around by installing the package globally.</p> <p>The RAK failure log is <code>/home/mikec/hwtest/runs/rak3401-syncidle-clean-tSp7PLgA/result.txt</code> on the Mercerwood Pi. The tested UF2 SHA-256 was <code>650c9fda456685cdf99c1f2996c60f1f551cc9216d2b746a22c8cb78464b0ff7</code>. <code>cp</code> returned success in 95 ms, but <code>sync -f</code> failed with <code>EIO</code> after 157,188 ms. Post-failure SWD readback proved that all seven ordinary sectors whose bytes differed between the old and intended builds still contained the old values, and the settings page was still erased. The only available pre-copy SWD dump was taken several hours earlier, however, so it cannot prove that zero unchanged blocks were written during this attempt or establish when the stale S140-v7 tail in the first application page appeared. The next run must capture an immediate pre-copy dump as well as the post-copy dump. Serial DFU recovery then completed in 35,698 ms with the exact <code>Device programmed.</code> marker. All 1,830 UF2 payload blocks matched SWD readback after recovery, and the application passed a subsequent real power-removal boot.</p> <p>The corrected 2.4.4-preview.2 candidate was installed through identity-gated SWD from combined-image SHA-256 <code>9b1654baccd2a920f68651893e31d79170400d1a7982a3f854ae640f1d3513a8</code>. An immediate pre-copy dump closed the earlier evidence gap. A deliberately old UF2 then copied and flushed successfully in 16,568 ms, and the exact formerly failing UF2 above copied and flushed successfully in 16,601 ms. After each direction, all 1,830 payload blocks matched a full SWD readback with zero header or payload mismatches. The return update changed 123 bytes across five expected application pages, UICR remained byte-identical, and a subsequent downstream USB power removal plus Pi reboot returned the RAK as the same stable identity. It reported the intended <code>3caf9dcf</code> application, board, node name, USA radio tuple, and 22 dBm setting after that cold boot. The new bootloader's CLI source string is truncated before the injected preview number, so the independently hashed SWD artifact is the authoritative candidate identity for this run.</p> <p>The later TinyUSB lifecycle/generation candidate identifies itself as test version <code>0x02040403</code>. Its exact 40,960-byte bootloader readback SHA-256 is <code>f609eb18754070c54f127325b1cb48547baf5c6b1c695d36fd0c8e0874713c13</code>. With that candidate installed, a full <code>CURRENT.UF2</code> read completed before each write. The 936,960-byte <code>bf092b24</code> application UF2 (SHA-256 <code>12477a9734cf12eb920361bd21024e39bf303953fcf79d0bf720e00847e2ae92</code>) copied and flushed in 28,203 ms and returned to application mode four seconds later. The exact <code>3caf9dcf</code> application UF2 (SHA-256 <code>650c9fda456685cdf99c1f2996c60f1f551cc9216d2b746a22c8cb78464b0ff7</code>) then copied and flushed in 26,479 ms and also returned in four seconds. Both boots retained <code>RAK3401-OTA-BENCH</code> and <code>910.525/62.5/SF7/CR5</code>.</p> <p>Identity-gated SWD then read the entire 468,480-byte padded UF2 application range. Its SHA-256 exactly matched the converted source on both sides at <code>b2e37a7681027ca91d1b2bd8e39b55395d9e91d4863aed17131e50c1ba1d2227</code>. The bootloader still matched the installed <code>0x02040403</code> image byte-for-byte, and UICR still matched the pre-test image at <code>d029ea630c2f632a1b690cb52b2a96a28b6f870c656c3e1bd74ba3a571c53b9c</code>. The authoritative logs are under <code>/home/mikec/hwtest/runs/rak3401-uf2-02040403-20260830-170829</code> and <code>/home/mikec/hwtest/runs/rak3401-uf2-return-02040403-sfHiGEqA</code> on Mercerwood.</p> <p>The subsequent direct LoRa qualification used the V4 as controller/seeder and the RAK's exact <code>bf092b24</code> body <code>91CF4EC2882F23D6</code> as the base. Its mandatory fixed three-minute rehearsal passed on <code>909.95/250/SF5/CR5</code>, including natural expiry and exact normal-radio recovery. The 2,132-byte, two-block in-place delta reached <code>2/2</code> and ready in six seconds; install was accepted, and the new body appeared at the 60-second reboot probe. The automation took 514 seconds including rehearsal, clock/radio safety checks, and post-install verification. The final body was <code>27A223DDFC3A8F47</code>, version <code>1.17.1.5</code> at <code>3caf9dcf</code>, and the bootloader reported <code>blrc:B8</code>, which is OTAFIX's successful application apply result rather than an error. Exact target TX power was wrapped from 22 dBm to 0 dBm for the co-located transfer and restored to 22 dBm afterward; the source RXPS configuration and both normal radio tuples were also restored.</p> <p>Identity-gated SWD then read the live application at <code>0x26000</code>. All 468,384 bytes matched the intended release image exactly (SHA-256 <code>b496e3f4419c9f771564ed3c74b3407822f45acdf60cbd6c4625a54b181ca084</code>), and the independently recomputed EndF hash was <code>27A223DDFC3A8F47</code>. The target ID was <code>2FA509C1</code>, hardware ID was <code>RAK_3401</code>, and version word decoded to <code>1.17.1.5</code>. The 40,024-byte bootloader readback also matched the exact installed <code>ffb1580</code>/test-version-<code>0x02040402</code> artifact byte-for-byte; UICR was unchanged. After SWD reset-halt/resume, USB again reported the expected application, identity, name, radio, 22 dBm, no TempRadio lease, and <code>blrc:00</code> (the retained success diagnostic is intentionally cleared by the next normal boot).</p> <p>The current <code>0x02040403</code> bootloader candidate then passed a second direct V4 LoRa qualification using a materially larger application change. The unsigned in-place package was 75,614 bytes with 75,108 payload bytes and 74 transfer blocks. Its mandatory fixed three-minute rehearsal passed, including natural TempRadio expiry and exact normal-channel recovery; one lost read-only <code>ota status</code> reply was reconciled by its bounded exact retry. The transfer reached 74/74 and READY in 122 seconds, the explicit unsigned install was accepted, and reboot produced exact HEAD <code>9fd580c8</code> with body <code>744BC4443891ED10</code>. The complete safety-wrapped run took 589.487 seconds, including rehearsal, recovery, and final verification. The first postboot <code>ver</code> reply was lost and its exact read-only retry passed. Independent USB checks then confirmed target <code>2FA509C1</code>, hardware <code>RAK_3401</code>, unchanged identity/name/radio/RXPS/watchdog state, bootloader CRC <code>6683C066</code>, ABI 3, apply result <code>blrc:B8</code>, and no active TempRadio/download/seeder/key state. After the separate host-recovery exercise, the near-field TX setting was restored from 0 dBm to its exact original 22 dBm and read back over an authenticated LoRa session. The sanitized authoritative log is <code>/home/mikec/hwtest/runs/rak3401-02040403-head-vzWOXVxT/qualification-redacted.log</code> with SHA-256 <code>3e53dcaa5922c7c18a7890963b8fc092311d2db01caa5603640f43f1482802f6</code>.</p> <p>A serialized VM build of the six connected-board qualification profiles then completed 6/6 in 136.122 seconds: XIAO nRF52 BLE Companion, T1000-E BLE Companion, RAK3401 LoRa-OTA Repeater, SenseCAP Indicator LoRa USB/Wi-Fi Companion, MeshTower V2 SD LoRa-OTA Repeater, and the consolidated Heltec V4 V4.2/V4.3 Full Companion. The earlier V4 selector typo was rejected before any compile began and is not a firmware build failure.</p> <p>After the fresh-NTP download gate, shared SNTP coordinator, MQTT-to-MeshCore RTC handoff, and daily refresh policy were added, the complete native matrix passed 1,102/1,102 cases in 93.953 seconds. The scheduler is host-tested at 24-hours-minus-one-millisecond, the exact 24-hour boundary, normal and wrapped <code>millis()</code> values, a short retry that overrides the daily cadence, the zero deadline sentinel, and a Wi-Fi event latch. A reconnect after a successful sample preserves the existing deadline, so successful samples are requested after boot and then only once per day. All current Python and shell contract suites passed, and the expanded LoRa-OTA automation suite passed 317/317 cases.</p> <p>Serialized real builds also passed after that change. The final event-safe implementation uses an atomic <code>GOT_IP</code> latch so even a short initial connection before the 10-second MQTT status sample cannot skip the required boot NTP request. The final Heltec V4 MQTT Observer application is 1,853,304 bytes with SHA-256 <code>1938ae88fcdbe601cf8698df44b548656079562d899801886b808af913e5f9ac</code>. The consolidated Full V4 image used 2,250,801/6,553,600 flash bytes and left 4,302,799 bytes of app-image space. Its 2,251,272-byte application image has SHA-256 <code>05131eac29164be46d1bcceeb4f03455f5ea8d61c8d4f529b77d8adfe25fdb6a</code>; the 2,316,808-byte merged image has SHA-256 <code>c4c1fc639b6d0087c795a81aca79c07eba56dc4e071eb374dc70da0bec81815e</code>. The focused daily-NTP policy suites passed all 42 cases after the latch was added, and the Full capability manifest verified all ten expected features. The reduced RAK3401 LoRa-OTA Repeater also compiled with the verified WisBlock I2C aliases. At that source state its link used 471,344/815,104 flash bytes; the reduced external-sensor contract retains INA219/INA226/INA260/INA3221 as the voltage/current entries in the optional environmental-telemetry table. These are not the image's only I2C consumers. The image separately retains its SSD1306 display, auto-discovered I2C RTCs, RAK12500 I2C GPS, and RAK12501/L76K UART GPS paths. The configured INA3221 and RAK12500 both default to I2C address <code>0x42</code>; those two devices cannot coexist at those addresses. The supported combined arrangement leaves RAK12500 at <code>0x42</code>, straps INA3221 A0 to SCL for <code>0x43</code>, and uses a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>. The nRF52840 die-temperature and ADC battery-voltage paths are also retained. The 472,227-byte DFU ZIP SHA-256 is <code>fdd369005a61635756efa9e38b217376a952f334b0864f927a46799b65264fa9</code>, and the matching 943,104-byte UF2 SHA-256 is <code>2155632fde730e0ae2e4a72ce64f89910861f6c5105a4bd7ac96aaa538a33dca</code>. These VM results do not replace the remaining exact-final hardware test with UDP/123 blocked.</p> <p>The later serialized RAK3401 contract build, after the non-blocking nRF52 USB logging change, used 471,576 bytes before its 56-byte EndF trailer. Its EndF body hash is <code>026749684bf6ee8f</code>, target ID is <code>2FA509C1</code>, hardware ID is <code>RAK_3401</code>, and version word is <code>0x01110105</code>. The 472,435-byte DFU ZIP has SHA-256 <code>cf0880b26f2d6bd8157f8af76a6718fe1f998de8ea7df8cd952e734448201fb9</code>; the 943,616-byte UF2 has SHA-256 <code>f893a8cebf309af12a4a6f5483acb28f94158e18632f660e011658c846e8ca7f</code>. The linked ELF contains GPS, SSD1306, RTC, and the four INA families, while an exact symbol audit finds none of AHT10/20, BME280, BMP280, SHTC3, SHT4X, LPS22HB, MLX90614, VL53L0X, BME680/BSEC, BMP085, or RAK12035. The complete native matrix passed 1,112/1,112 cases at that intermediate source state. These are VM gates only; flash the exact artifacts and repeat the physical peripheral and blocked-clock checks before marking any later source state hardware-qualified.</p> <p>Subsequent source hardening changed RAK peripheral discovery: the shared 3V3_S rail remains enabled, UART GPS requires a complete checksum-valid NMEA sentence, an exact INA3221 identity blocks a conflicting u-blox probe, and a successful I2C GPS claim suppresses a sensor only on the same bus and address. The hashes and sizes above describe their recorded intermediate artifacts; they are not current-HEAD evidence and must not be reused for the hardened source.</p> <p>The immutable font endpoint was re-probed only after the VM reported <code>NTPSynchronized=yes</code>. GitHub returned HTTP 206 for bytes <code>0-65535</code>, an exact 65,536-byte match to the checked-in font (range SHA-256 <code>8b0dd308eb01469d1f9e732fba260720a80cc86f6cb5385c28e8a16c76dcfbf3</code>), with total length 1,302,608 and strong ETag <code>\"39ff0cfbe37e36905507697d042869c05374c3202dd96d5a9f98812153f324c1\"</code>. This validates the current strict Range assumptions against the live service; the exact-final Indicator still needs the negative hardware run proving that blocked UDP/123 prevents every TLS request and RP2040 staging write.</p> <p>Mercerwood subsequently recovered without a target write. Both its Tailscale and LAN addresses again accepted SSH, Bluetooth was idle, and the exact T1000-E stable serial <code>34A9141999729D5D</code> was present as application USB <code>239a:8029</code>. The RAK3401 simultaneously uses the same VID/PID, which confirms that every continuation must resolve the stable serial/by-id identity rather than VID/PID. The T1000-E remained in the exact bonded Full Companion application; no stale DFU, scanner, <code>meshcli</code>, or HCI-capture process was running.</p> <p>The post-reboot seven-TTY inventory was also resolved without assuming that one board owned adjacent device names. <code>ttyUSB0</code> is the SenseCAP Indicator's ESP32-S3 CH340 UART and <code>ttyACM5</code> is its RP2040; their sibling physical USB paths and the Indicator's live TCP board reply agree. The separately attached <code>ttyACM4</code> is the MeshTower V2 native <code>HT-n5262</code> endpoint and returned the qualified MeshTower build over its own console. The remaining ACM endpoints independently identify the RAK3401, XIAO nRF52840, Heltec V4, and T1000-E.</p> <p>ModemManager had restarted after the Pi reboot and could probe otherwise idle radio consoles. Six serial-bearing boards now use stable-serial-only <code>ID_MM_DEVICE_IGNORE</code> rules. Because the Indicator CH340 has no stable serial, its separate rule requires the exact current physical port chain and exact <code>1a86:7523</code> identity; there is no broad CH340, product, or VID/PID-only rule. A controlled ModemManager restart reported zero modems, displaced no TTY owner, caused no USB disconnect/re-enumeration, and left all seven endpoints ignored. The same mctomqtt process retained sole ownership of the RAK, while a subsequent Indicator TCP query still returned the expected board and build. Reversible root-only backups were retained on the Pi before each rule update.</p>"},{"location":"hardware_validation_checklist/#run-wide-gates","title":"Run-wide gates","text":"<ul> <li>[ ] Record commit, version string, role/profile, artifact filename, size, and       SHA-256 before flashing.</li> <li>[ ] Archive the exact ELF and symbol/objdump map beside each qualification       firmware. A rebuilt ELF is acceptable for diagnosis only after its       firmware binary matches byte-for-byte; compiler <code>__DATE__</code>/<code>__TIME__</code>       strings can otherwise change both bytes and the EndF body hash.</li> <li>[ ] Bind every operation to a stable USB serial number or physical USB path;       never rely on a changing <code>ttyACM</code>/<code>ttyUSB</code> number.</li> <li>[ ] After erasing/reflashing a BLE board that reuses its Bluetooth address,       remove any stale host bond and pair again with the board's current PIN       before diagnosing service-discovery disconnects. On Linux, verify the       BlueZ agent actually accepted the passkey; a scanner seeing the device is       not proof that Companion GATT is usable.</li> <li>[ ] Do not use BlueZ's advertisement <code>service_uuids</code> as a same-address warm       handoff identity gate. After application/bootloader transitions BlueZ can       merge the bootloader's cached GATT UUIDs into the live application's       advertisement. Gate the application advertisement by exact address and       name, then require the live connected BLEDfu service, control/revision       characteristics, retained bond/encryption, notification subscription,       and observed target disconnect before accepting the handoff.</li> <li>[ ] Do not treat <code>meshcli -P</code> as an infallible pairing probe. Immediately       after one successful post-DFU session, a second invocation with the exact       paired XIAO address hit the meshcore-cli <code>NoneType ... pair/disconnect</code>       path before it created a Bleak client. BlueZ still reported the exact       bond and the same command without <code>-P</code> connected and synchronized the       clock successfully. Capture this as a host-tool failure, then verify the       device independently before blaming firmware.</li> <li>[ ] After a successful <code>BleakClient.connect()</code>, start a fresh disconnect       generation before beginning DFU. BlueZ can fail one internal LE attempt,       retry successfully, and still deliver the failed attempt's callback. A       stale event caused the host to stop notifications and issue a local HCI       disconnect after a valid image CRC but before ACTIVATE; the target and       bootloader had not dropped the link. Preserve an HCI trace through       activation so local-host and remote-target disconnects remain       distinguishable.</li> <li>[ ] Before a BLE pairing/throughput test on a Wi-Fi-managed Pi, record both       management addresses and a same-LAN recovery vantage point. The XIAO       pairing run completed, but Mercerwood then stopped answering on both its       Wi-Fi and Tailscale addresses; BellevueBBS confirmed the old LAN address       was absent at ARP and no replacement LAN host exposed SSH. This is an       infrastructure outage until Pi logs prove a cause, not a firmware or BLE       failure. The T1000-E pairing run reproduced the management outage: its       exact application paired successfully and exposed the complete DFU       service, then Mercerwood stopped accepting SSH and ultimately stopped       answering Tailscale pings. No buttonless DFU write had been sent, and the       T1000 remained in its valid application. Capture Pi Wi-Fi/firmware logs       after recovery and avoid leaving discovery enabled between operations.</li> <li>[ ] Confirm the selected board and role before every erase or flash.</li> <li>[ ] Before every SWD write, read the target FICR device ID and match it to the       intended board's stable USB serial (and physical wiring record). A USB       product name or remembered cable position is not sufficient.</li> <li>[ ] Confirm no other PlatformIO process is active; run only one PlatformIO       build, test, clean, or upload at a time.</li> <li>[ ] Record the installed bootloader, SoftDevice, partition table, or flash       layout independently of the application banner where applicable.</li> <li>[ ] Test both a software reboot and a real power removal/cold boot.</li> <li>[ ] After an update, read back identity, version, radio tuple, node name, and       persistent settings instead of assuming they survived.</li> <li>[ ] Save command output and elapsed milliseconds. Mark a test <code>FAIL</code>, not       <code>PASS</code>, if the transport reports an I/O error even when firmware later       boots.</li> <li>[ ] Before calling a node hung, validate that the probe uses that profile's       command terminator, check a second transport, and capture PC/LR/watchdog       state over identity-gated SWD before reset. Resume once and retest before       using reset as recovery so the diagnostic state is not destroyed first.</li> <li>[ ] Treat a remote login acknowledgement and the following command reply as       separate LoRa packets. A lost login acknowledgement is not proof of       failed authentication when a command-matched private reply from the       selected contact key is present; an explicit negative login result still       fails closed.</li> <li>[ ] Restore the intended USA radio preset and normal-radio mode after tests.</li> <li>[ ] Compare both semantic version and exact EndF/body hash. A transition       between two commits carrying the same version string must stop at the       normal reinstall guard unless the run plan explicitly records and passes       <code>--allow-non-upgrade</code>; a different commit name alone is not authorization.</li> <li>[ ] Do not allow a non-interactive transmission-failure prompt to continue       retry cycles forever. Optional capability probes must fail/fall back after       a bounded interval, while mutations and cleanup retain their stronger       bounded-lease recovery rules.</li> <li>[ ] Before the first remote command after any controller/source reboot, read       its RTC and compare it with a trusted host clock. Advance a clock which is       behind and prove readback; never move a radio clock backward. Fail closed       when it is more than 10 minutes ahead. During the RAK rehearsal the V4       rebooted to <code>2026-03-01</code> while the RAK remained at <code>2026-08-30</code>; the RAK       received the direct packets but correctly rejected their old timestamps       as replays. Setting the V4 to host epoch immediately restored login and       the exact public-key reply at SNR -1.5 dB.</li> <li>[ ] Before every external HTTPS download, require a fresh SNTP response for       that bounded operation, a plausible signed wall clock, connected Wi-Fi,       and a non-expired proof immediately before opening TLS. Re-check the proof       before every resumed/Range TLS connection. A retained plausible RTC or       mesh time is not a substitute for observing NTP, and failure must occur       before any HTTP request body or flash writer begins.</li> <li>[ ] Treat an unacknowledged immediate <code>tempradio</code> mutation as potentially       active, not merely lost. On the tested repeater, scheduled-radio expiry       deliberately waits for <code>hasOutbound()</code> to clear; a CLI reply stranded on       the temporary tuple can therefore hold the node there beyond its nominal       lease. Prefer one fixed absolute <code>tempradioat</code> window per node, so duplicate       delivery cannot extend it, and prove the return on both tuples before a       transfer. If recovering an older immediate handoff, join the exact       temporary tuple to drain the reply before issuing <code>normalradio</code>.</li> <li>[ ] Do not diagnose a co-located high-power LoRa bench failure as weak RF       without an overdrive check. On the RAK3401/V4 bench, the RAK at 22 dBm       produced only 3/6 status replies around -1.5 dB SNR, while a reversible       0 dBm setting produced 6/6 replies in 5--8 seconds at +12 to +12.5 dB       SNR. Read the original power, lower it only for the near-field test, and       require exact restoration afterward.</li> </ul>"},{"location":"hardware_validation_checklist/#compute-placement-gate","title":"Compute-placement gate","text":"<ul> <li>[ ] Run firmware builds, PlatformIO, mOTA/delta generation, compression,       full-image hashing sweeps, symbol generation, and other sustained CPU or       memory work on the VM. Do not offload these jobs to a Pi merely because       the hardware and source artifacts are attached there.</li> <li>[ ] Use the Mercerwood Pi as the identity-gated hardware gateway, SWD/USB/BLE       test host, and LoRa/Wi-Fi seeder. Copy only the completed artifact plus       its manifest/hash to the Pi, then verify the copied SHA-256 before use.</li> <li>[ ] Run CPU work on a Pi only when Pi performance or deployment behavior is       itself the test subject, and label that exception in the run log.</li> <li>[ ] Do not assume a non-interactive SSH session has the same <code>PATH</code> as an       interactive shell. Resolve pipx-installed tools such as esptool and       detools to their explicit venv path, record the version, and fail before       erase if the pinned executable is unavailable.</li> <li>[ ] Treat short serial/BLE/SWD control scripts on the Pi as hardware I/O, not       as permission to generate artifacts there. Use the explicit Python from       the relevant pipx environment when a probe needs one of its dependencies;       the Pi system Python did not contain <code>pyserial</code> during the RAK run.</li> </ul>"},{"location":"hardware_validation_checklist/#lora-controlled-host-recovery-gate","title":"LoRa-controlled host recovery gate","text":"<ul> <li>[x] The privileged recovery boundary is a root-owned, group-restricted       AF_UNIX broker with a fixed command grammar and fixed <code>systemctl</code> argv.       The unprivileged MQTT endpoint cannot gain privileges under       <code>NoNewPrivileges</code>, cannot select an executable or unit, and commits an       action only after its signed challenge/reply has been published and       confirmed. The installed broker passed its cold activation, peer       credential, socket owner/mode, injection, duplicate, timeout, durable       reservation, and ambiguous-outcome checks.</li> <li>[x] A signed <code>host network restart</code> was accepted exactly once in 4.088       seconds. The broker retained one <code>network-restart</code> record at sequence 1,       and the fixed unit journal had exactly one start/finish pair. Independent       management probing measured 7.184 seconds from last successful probe to       first recovered success and 6.314 seconds from first failure to recovery.       Pi-local loopback MQTT delivered 107/107 samples; mosquitto, mctomqtt,       and the endpoint retained their exact PIDs, and mctomqtt remained the sole       owner of the RAK USB port. One read-only LoRa status reply was lost at the       temporary 0 dBm bench setting, then authenticated status returned       <code>scheduled</code>; no mutation was replayed. One monitor parsed two       <code>systemctl --value</code> columns in reverse order, so its boolean labels are       discarded; its PID/MQTT trace and the independent postchecks remain       valid.</li> <li>[x] A signed <code>host reboot</code> was accepted exactly once in 3.312 seconds and       armed the fixed 10-second timer. A changed boot ID and one observed       outage prove one reboot; management recovery took 35.763 seconds from       the last pre-outage success and 31.276 seconds from the first failed       probe. Postboot signed LoRa uptime replied in 3.651 seconds. All seven       exact USB identities returned, only the RAK port was owned, the deployed       configuration hashes were unchanged, and NetworkManager, Tailscale,       mosquitto, mctomqtt, the endpoint, and both privileged sockets were       active. Broker action state is intentionally under <code>/run</code> and persistent       journaling was unavailable, so exactly-once evidence is the accepted       reply, one boot-ID transition, one outage, an inactive timer, and no       second outage; do not claim a durable postboot operation record.</li> <li>[x] Reboot auto-started the still-enabled ModemManager service, but all seven       exact devices retained <code>ID_MM_DEVICE_IGNORE=1</code>, zero modems appeared,       and no TTY was probed or claimed. The service was returned to its       pretest inactive state without disabling or masking it. The RAK then       passed exact identity/body/radio gates; an explicit radio-busy rejection       left TX at 0 dBm, one bounded idempotent retry after idle returned OK,       and authenticated readback proved exact restoration to 22 dBm. V4       identity, power-saving, RXPS, TempRadio, and seeder state also matched       their pretest values.</li> </ul> <p>The sanitized host-recovery evidence bundle is under <code>out/host-actions-live-20260831/</code>. Its <code>SHA256SUMS</code> manifest has SHA-256 <code>5acff71ed98f483bb769e8c99c577bf358d0491355ac72855ee7093cd658bf21</code>, and <code>sha256sum -c</code> verifies every deployed-hash, pre/post-state, radio, OTA, network, and reboot record in that manifest.</p>"},{"location":"hardware_validation_checklist/#mercerwood-pi-usb-power-cycle-gate","title":"Mercerwood Pi USB power-cycle gate","text":"<ul> <li>[ ] Confirm the Pi is reachable through Wi-Fi/Tailscale and that <code>eth0</code> is not       the active management path before cycling its downstream USB tree.</li> <li>[ ] Stop all flashes/transfers, run <code>sync</code>, and release SWD GPIO 8 and GPIO 11       to inputs with no pulls before removing USB power. This prevents an SWD       signal from partially back-powering an otherwise unpowered nRF52.</li> <li>[ ] Never issue a standalone <code>uhubctl ... -a off</code> to Pi root hub location <code>1</code>.       Once its only port is off, the hub disappears from <code>uhubctl</code> discovery and       a separate <code>-a on</code> command fails with <code>No compatible devices detected at       location 1!</code>. This has interrupted two hardware runs.</li> <li>[ ] A downstream hub may be cycled only after resolving the board's stable       USB serial to an exact sysfs path and proving that hub advertises       per-port power switching. Record the hub location and port, cycle only       that port, and gate the re-enumerated VID/PID/serial before continuing.       The T1000-E qualification safely used child hub <code>1-1.2</code>, port 3; this is       not permission to cycle the ganged root hub at location <code>1</code>.</li> <li>[ ] Do not use <code>uhubctl</code> <code>off</code>, <code>on</code>, or atomic <code>cycle</code> on Mercerwood root       hub location <code>1</code>. Physical testing showed that even one atomic <code>cycle</code>       powers the ganged root hub down and then cannot rediscover it to restore       power. Use a planned Wi-Fi-issued <code>sudo reboot</code>, which is the verified       recovery, or arrange a true upstream VBUS removal when that distinction       is part of the test.</li> <li>[ ] Treat root hub <code>1</code> as a ganged operation: every attached test board and USB       Ethernet adapter loses power. After recovery, enumerate every stable       <code>/dev/serial/by-id</code> identity again before resuming any board-specific test.</li> <li>[ ] On this heavily populated root hub, inspect kernel logs for real transfer       faults before and after a flash, and stop ModemManager while it could open       a test TTY. A CH340/ESP32-S3 write which lost the chip at 460800 baud       completed and verified at 115200 after a planned Pi reboot; start at the       board-qualified conservative rate rather than treating a fast partial       transfer as firmware failure.</li> <li>[ ] Under non-interactive SSH, do not let <code>udisksctl</code> fall through to an       interactive polkit password prompt. After resolving the exact UF2 block       device by board serial, either use an already-mounted volume or an       explicit <code>sudo -n mount</code> at a board-specific mount point; re-check       <code>INFO_UF2.TXT</code> model/version before copying.</li> </ul>"},{"location":"hardware_validation_checklist/#seeed-xiao-nrf52840","title":"Seeed XIAO nRF52840","text":"<ul> <li>[ ] Stable USB identity distinguishes application (<code>2886:8044</code>) from UF2       bootloader (<code>2886:0044</code>).</li> <li>[ ] Do not repeat the known-failing full-application UF2 copy under the       installed initial 2.4.4 candidate. The identity-gated 897,024-byte copy       returned exit 0, then <code>sync -f</code> failed with <code>EIO</code> in 850 ms; the kernel       logged an offline device, lost queued writes, and FAT errors before USB       disappeared. Recover through a separately hash-gated BLE/serial path and       qualify a corrected bootloader candidate before retrying UF2.</li> <li>[ ] SWD readback exactly matches the intended bootloader-region SHA-256.</li> <li>[ ] Actual SoftDevice FWID and runtime application base match the artifact       (<code>S140 7.3.0</code>: FWID <code>0x0123</code>, application base <code>0x27000</code>).</li> <li>[ ] Exercise and independently verify the exact-board combined       bootloader+SoftDevice recovery path before relying on it in the field.       A wrong-layout nRF52840 application can overwrite part of S140 while the       UF2 bootloader still accepts files and the application still reads flash;       internal writes or <code>InternalFS.format()</code> may then hang or reboot. An       application-only UF2 and a filesystem erase cannot repair that state.       The known XIAO incident in upstream issue #3284 recovered only after the       matching Sense/non-Sense OTAFIX bootloader+S140 ZIP was installed. Keep       board identity, SoftDevice FWID, application base, and package contents       as four separate pre-write gates.</li> <li>[ ] Invalid settings enter persistent UF2 recovery after a cold boot.</li> <li>[ ] UF2 application copy returns success; <code>sync -f</code> returns success; the host       has no offline-sector, lost-write, or FAT I/O errors.</li> <li>[ ] Application enumerates after update and reports the expected board,       version, role, and radio tuple.</li> <li>[ ] Legacy serial DFU crosses all application pages, emits the exact       <code>Device programmed.</code> success marker, and rejects false-success output.       Two application serial-DFU attempts on this board timed out waiting for       the start ACK while <code>adafruit-nrfutil</code> still returned exit 0, so exit       status alone is explicitly insufficient.</li> <li>[ ] Legacy BLE DFU verifies each cumulative PRN receipt exactly and fails on       a missing, short, regressive, or overreported offset; it may adapt       only among the packet-size-specific safe receipt windows after timely       exact receipts and must step back down on slow exact receipts. Final       application/SoftDevice/bootloader CRC and a peer disconnect are mandatory       before declaring success.</li> <li>[ ] Every upward PRN move is a bounded adjacent-level probe. A failed probe       or a later real demotion blocks further increases for that transfer, while       additional slow exact receipts may still negotiate down one level at a       time. This prevents <code>4 -&gt; 8 -&gt; 4 -&gt; 8</code> churn without disabling a safe       initial probe or a <code>32 -&gt; 16 -&gt; 8</code> fallback.</li> <li>[x] The exact Full Companion ZIP       <code>Xiao_nrf52_companion_radio_full-v1.17.1.5-halo-keymind-cascade-3caf9dcf.zip</code>       (SHA-256 <code>9a916c1a3ea83d8f6dd704465fe9c044a363478f852a4369cf6b13424a7a9430</code>)       installed over BLE in 237,297 ms at about 2,110 B/s using ATT MTU 247,       244-byte writes, PRN 4, and exact cumulative receipts. Validate and the       target-initiated disconnect passed. USB then reported the exact expected       version/hash, USA radio tuple, key, RXPS policy, and reversible       Terminal/Binary mode; the new application advertised NUS as       <code>MeshCore-4610BBD2</code>.</li> <li>[x] The post-update application was paired through BlueZ with the expected       PIN. Companion GATT then returned the same public key, USA radio tuple,       22 dBm limit, non-repeater role, board, and build over BLE. Its RTC was       18,038 seconds behind the trusted host; <code>clock sync</code> advanced it and the       immediate readback was within one second of the host interval. No       backward clock write was performed.</li> <li>[x] A second exact same-image update exercised application buttonless DFU and       retained-peer bootloader entry. The bootloader deliberately reused the       bonded application address <code>E5:C3:A8:B0:60:66</code> rather than the cold-entry       address ending in <code>:67</code>; exact name, Legacy DFU service, and DIS model       gates still passed. The first adaptive threshold remained at PRN 4 and       completed all 448,416 bytes at about 877 B/s in 527,832 ms; validate,       target disconnect, USB identity, application key, role, and USA radio       readback all passed. The application clock was then about 10 minutes       behind because its RTC did not advance during the bootloader transfer;       it was advanced to the host clock and proved by immediate readback.</li> <li>[x] A third same-image A/B run used bounded neutral-window exploration. At       244-byte writes, two exact neutral PRN-4 receipts triggered one adjacent       PRN-8 probe. PRN 8 measured about 845 B/s against an approximately       879 B/s PRN-4 baseline, so the helper rolled back to PRN 4 after two       receipts and never re-probed. All 448,416 bytes completed at about       870 B/s in 531,804 ms; CRC validation, target disconnect, USB return,       exact Companion key/role/radio readback, and post-DFU forward clock sync       passed. This proves up/down sender-window adaptation and no churn, while also showing       that PRN receipt overhead is not the bonded-path bottleneck on this run.</li> <li>[x] A bootloader candidate built from exact ZIP SHA-256       <code>9c70200fc15a315a50ec68d2a905b5bcf2fc07a796a21fbd439535ec19a608be</code>       disabled inherited slave latency locally during DFU DATA. The controller       trace still reported the peer-negotiated 30 ms interval and latency 4,       with no connection-parameter update after START; the change is therefore       a local event-attendance override, not a GAP speed renegotiation. A cold       address-generation control completed 448,416 bytes at 2,231 B/s and       passed validation/activation in 226,103 ms.</li> <li>[x] Two subsequent bonded application-to-bootloader runs completed the exact       same 448,416-byte image at 3,524 and 3,534 B/s. Their complete elapsed       times, including exact application advertisement proof, buttonless       handoff, bootloader scan, erase, DATA, CRC validation, activation, and       reboot, were 169,414 and 169,221 ms. Both targets initiated the final       disconnect; USB returned as stable serial <code>B35E71C1C3726CE7</code>; the public       key, 22 dBm setting, USA <code>910.525/62.5/SF7/CR5</code> tuple, board, and build       read back exactly. Compared with the prior roughly 877 B/s bonded run,       the DATA rate improved by about 4.0x without increasing the PRN window       beyond 8.</li> <li>[x] An exact bonded B-A-B link-profile sequence used the same Full Companion       ZIP SHA-256 <code>9a916c1a3ea83d8f6dd704465fe9c044a363478f852a4369cf6b13424a7a9430</code>,       lab helper SHA-256 <code>4909c617de37b5666cc622b7190568f002280f55bf26a05843ea283f2be8f566</code>,       handoff helper SHA-256       <code>1bad570173079b623bbe2bbb9e5ba7c4f8ac379bf966bfd4382c5266fb9fd214</code>,       stable USB serial, bonded address, and 448,416-byte application throughout.       First B, <code>xiao-ble-event-length-prestart-20260830-072641-W7COxm</code>, used one       exact pre-START 15 ms/latency-0 update with <code>0/0</code> no-preference event-length       hints and completed DATA in 72.030 seconds at 6,225 B/s; DFU through target       disconnect was 102.792 seconds and the full workflow was 117,064 ms.       Control A, <code>xiao-ble-control-prestart-20260830-073149-yKf0lO</code>, requested no       update, retained the bootloader connection's 30 ms/latency-4 link, and       completed DATA in 134.131 seconds at 3,343 B/s; DFU was 165.137 seconds and       the full workflow was 182,624 ms. Final B,       <code>xiao-ble-exact15-prestart-20260830-073554-FuGPfH</code>, repeated exact 15 ms and       completed DATA in 71.970 seconds at 6,231 B/s; DFU was 102.799 seconds and       the full workflow was 117,179 ms. Both B rates were about 1.86x control and       differed by only 0.096%.</li> <li>[x] The B-A-B protocol and link gates passed independently. Both B runs probed       PRN 4 -&gt; 8 after an exact 0.135-second four-packet receipt, rolled back       once to PRN 4 after the exact 0.345-second eight-packet receipt, and never       re-probed. Control A likewise probed after 0.269 seconds and rolled back       after 0.600 seconds. Each B bootloader connection had exactly one matching       HCI Update Complete before START; control A had no bootloader-connection       update. All three captures contained zero connection updates from START       through DATA, CRC validation, activation, and the target-initiated       disconnect. Each run ended <code>RESULT=PASS</code>, <code>RC=0</code>, <code>STAGE=complete</code>; final B       returned the exact Full Companion application as USB <code>2886:8044</code>, stable       serial <code>B35E71C1C3726CE7</code>, with current application name       <code>MeshCore-4610BBD2</code>. A fresh post-B binary Companion query independently       re-gated the unchanged public identity, name, Full Companion role, 22 dBm       power, and USA <code>910.525/62.5/SF7/CR5</code> radio tuple. A separate bonded BLE       application query then returned the same board, build, and Full Companion       role, so the USB return did not mask a broken Companion BLE path or stale       bootloader alias.</li> <li>[x] The current host-controller ceiling is independently characterized. The       Pi Zero 2 W Broadcom UART controller reports HCI/LMP 4.2 but supports only       LE 1M; LE Read Maximum Data Length and Read Suggested Default Data Length       both return Unknown HCI Command. The final B capture contains 1,837 full       244-byte firmware writes,       each split into ten 27-byte HCI ACL fragments; all 18,425 transmitted ACL       fragments received completed-packet accounting. The median full-write gap       was 29.947 ms at 15 ms versus 59.936 ms in control A. A BLE 5 controller       with working Data Length Extension is therefore the next host-side speed       experiment; this built-in controller cannot exercise DLE or LE 2M.</li> <li>[x] The host helper now clears a disconnect callback left by an unsuccessful       internal BlueZ connection attempt only after <code>connect()</code> has returned a       live link, and labels PRN changes as adaptation rather than link       negotiation. All 81 strict host tests pass. The first physical run before       this fix still proved the 3,520 B/s DATA rate and returned a successful       validation response, but is correctly recorded as FAIL because the stale       host event prevented ACTIVATE.</li> <li>[ ] Warm app-to-bootloader handoff is tested with the application watchdog       active; cold recovery is tested separately.</li> <li>[ ] BLE Companion/recovery behavior and radio-reset recovery are exercised.</li> <li>[x] The post-Pi-recovery application still enumerated as exact       <code>2886:8044</code> / <code>B35E71C1C3726CE7</code>, but one identity-gated, bounded USB       Binary Companion attempt received no protocol response. <code>meshcore-cli</code>       1.6.0 printed both of its no-response error lines and nevertheless exited       zero; the supervisor treated the attempt as a failure and independently       proved that no process retained the serial port. The exact terminal-stop       token and an identity/path-gated USB bus reset also failed, which excludes       an ordinary startup Terminal-mode hold and host USB endpoint state. The       external tool defect remains in upstream <code>meshcore-cli</code> 1.6.3: its serial       creation failure returns normally, so callers must validate command output       instead of trusting exit zero. The LoRa-OTA controller has an exact       three-diagnostic regression and continues to fail closed.</li> <li>[x] An exact hash-recorded Full Companion application DFU erased/replaced only       the application and completed in 36 seconds. The transferred ZIP was       440,083 bytes with SHA-256       <code>9946b8417c389784ac92c20e4ce5cf0b6a0123a58136627c0689815637f96992</code>.       The same stable USB serial returned as interface <code>00</code>; USB and the existing       bonded BLE identity both reported <code>Seeed Xiao-nrf52</code>, the 31-Aug-2026       build, and Companion role. Preserved settings included a roughly six-month       stale clock, which Binary Companion <code>clock sync</code> advanced to one second of       the Pi without changing the role.</li> <li>[x] The recovered application passed explicit Terminal start/stop, exact board       query, saved <code>usb.logging off</code>, source-only OTA status, and a real serial       <code>motatool serve</code> attach/detach with an empty folder (<code>COUNT -&gt; 0</code>). Binary       Companion returned after both terminal and mOTA ownership. Enabling USB       logging and rebooting produced exact interfaces <code>00</code> and <code>02</code>; interface       <code>02</code> emitted 123 bytes of entirely printable log data while Binary       Companion stayed usable on <code>00</code>. Disabling and rebooting removed <code>02</code>,       restored the single-interface descriptor, and read back logging off.</li> <li>[ ] A physical power-removal cold test is still needed to prove persistence of       the current application. It cannot retrospectively determine whether a       power cycle alone would have cleared the original stall. Answer that only       after reproducing the stall under a bounded stress loop, capturing state,       and power-cycling before any DFU. The application DFU proves recovery but       intentionally does not claim the underlying stall trigger is fixed.</li> </ul>"},{"location":"hardware_validation_checklist/#seeed-tracker-t1000-e","title":"Seeed Tracker T1000-E","text":"<ul> <li>[x] The cross-role <code>uf2reset</code> repair was hardware-qualified with Full       Companion ZIP SHA-256       <code>16e470c0d66bec14e1e9f2d4ebe04d83ffb30efa606465f885cbe9fc3d004a14</code>.       It was built from <code>f2c15225</code> with GCC 14.2.1, the USA Cascadia/Cascade       profile, and embedded version       <code>v1.17.1-uf2reset-f2c15225-f2c15225</code>. Serial DFU took 32.196 seconds and       stable application USB returned in 35.888 seconds. Terminal entry,       version, help, the exact no-argument command, application disconnect, and       stable <code>2886:0057</code> boot USB all passed in one 8.898-second script. The same       image was restored in 32.204 seconds and stable <code>239a:8029</code> USB returned       in 36.313 seconds; a final terminal check returned Binary mode cleanly.</li> <li>[x] The fixed application advertises live as <code>MeshCore-09848C15</code> at       <code>D1:A0:86:CD:BB:C6</code>. The obsolete Pi bond for the earlier temporary       identity was removed, and the exact address was paired again with the       qualification PIN. Paired, bonded, and trusted state, an encrypted BLEDfu       revision read, and the Nordic UART service all passed. The pre-run old       application enumerated but produced neither a terminal response nor a       live advertisement, so this run does not claim continuity of that       temporary identity or of application-owned settings across a combined       SoftDevice/bootloader recovery install.</li> <li>[x] Stable application identity <code>34A9141999729D5D</code> is recorded and is not       confused with the RAK3401 even though both currently enumerate with USB       product ID <code>239a:8029</code>. Application is <code>239a:8029</code>; the exercised       bootloader is <code>2886:0057</code>, with the same stable serial and exact       <code>T1000-E</code>/<code>T1KE_DFU</code> model/name gates.</li> <li>[x] A post-Pi-recovery, identity-gated, read-only USB Companion query returned       the exact T1000-E model, non-repeater Full Companion role, 22 dBm maximum,       and <code>910.525/62.5/SF7/CR5</code>. Its clock readback was within the query's       few-second host interval. No clock, radio, role, key, or settings write       was issued.</li> <li>[ ] Board, version, repeater role, bootloader status, and USA radio tuple are       correct after erase/install and after reboot. The live baseline and a       2,184 ms software reboot passed: <code>3caf9dcf</code>, <code>Seeed Tracker T1000-E</code>, 22 dBm,       <code>910.525/62.5/SF7/CR5</code>, OTA target <code>7B071FA0</code>, bootloader       <code>0.11.0-OTAFIX2.4.3</code>, and full OTA base hash       <code>3E92B157128B6963</code>. A real power-removal boot is still required.</li> <li>[ ] UF2 and serial DFU installation paths complete without host I/O errors.       On OTAFIX 2.4.3, an identity-gated root copy of the exact old UF2 returned       success in 112 ms, but the device disconnected before host writeback was       durable: <code>sync -f</code> failed with <code>EIO</code> after 17,695 ms and the kernel logged       lost asynchronous writes/FAT read errors. The old application happened to       boot and retained its settings, but this transport is a FAIL. Retest       with the corrected 2.4.4 candidate before qualifying T1000-E UF2.</li> <li>[x] The installed <code>t1000e_repeater_lora_ota_no_external_sensors</code> profile does       not compile the Companion BLE transport and did not advertise during a       post-reboot BlueZ scan; that is expected for this repeater image. BLE       Companion qualification belongs to the separate T1000-E Companion build.</li> <li>[x] The exact latency-disable bootloader candidate ZIP (SHA-256       <code>ebe9739ce40c2c7cc1f52076f9614194959fcf6df93d37666b69b7bd415fab68</code>)       installed through identity-gated serial DFU. The final output contained       exactly one terminal <code>Device programmed.</code> success line, the bootloader       returned as <code>2886:0057</code>, and its embedded manifest identifies       <code>T1KE_DFU</code>, S140 7.3/FWID <code>0x0123</code>, application base <code>0x27000</code>, and test       version <code>0x02040403</code>.</li> <li>[ ] The later connection-policy-reapply combined ZIP (SHA-256       <code>c2de1fb2704154b4abc371b6b4827c32ad09c4d15f3f6d97d0f4182bb51fff58</code>)       was identity-gated, transferred, validated, activated, and returned as       exact <code>2886:0057</code> recovery USB. <code>INFO_UF2.TXT</code> reported       <code>0.11.0-OTAFIX2.4.3-3-gffb1580-dirty-test-version-0x02040403</code>, S140       7.3.0, and the T1000-E board. The earlier and later candidates share the       same visible version string, however, so package sequencing and INFO_UF2       do not independently prove the installed bootloader bytes. Require an       identity-gated live bootloader-region readback or a uniquely versioned       rebuild before checking this item.</li> <li>[x] The combined-image BLE transport itself passed: 193,688 bytes at       3,331 B/s, target CRC validation, and target-initiated activation. The       package contains SoftDevice plus bootloader and <code>APP=0</code>, so remaining in       recovery USB was the correct postcondition. Its first supervisor record       is not accepted as run-level evidence: TERM inherited status zero and       wrote a false <code>PASS</code> at <code>STAGE=post_copy_usb</code>. A separate audit records       the transport result, and all later wrappers map INT/TERM to nonzero and       refuse <code>PASS</code> unless <code>STAGE=complete</code>.</li> <li>[x] A separate exact application recovery after that combined transfer       completed 404,468 bytes at 2,095 B/s, validated, activated, and returned       stable application USB in 225,899 ms. The lower rate is the expected       cold/unbonded class, not the bonded warm baseline.</li> <li>[x] A cold exact Full Companion application ZIP (SHA-256       <code>b3be000ab2391527a325cc868e2706dec291c167b6e6cd3495908addb8af6c65</code>)       completed all 404,468 DATA bytes over BLE at 1,572 B/s. The complete       workflow took 281,236 ms (about 1,438 B/s end to end, including setup,       validation, activation, and reboot). ATT MTU reached 247, but BlueZ's       independently cached maximum write size was still 20, so the       identity-gated helper correctly used 20-byte packets, adapted PRN       8 -&gt; 16 -&gt; 32, validated CRC, activated, observed the target-initiated       disconnect, and gated the exact USB application return.</li> <li>[x] The Full Companion application advertised as <code>MeshCore-F9AD7082</code> at the       expected address generation, paired with the qualification PIN, and       exposed its bonded, MITM-protected Legacy DFU service after connection.       That DFU service is intentionally absent from the advertisement, so an       advertisement-only check is insufficient. A 1200-baud USB touch instead       selects serial-only DFU and correctly produces no BLE advertisement;       use the bonded application control characteristic for a warm BLE handoff.</li> <li>[x] Exact same-address bonded warm buttonless DFU passed. The application       advertisement, Paired/Bonded state, connected BLEDfu service/control/       revision layout, encrypted notification/write gate, observed target       disconnect, <code>T1KE_DFU</code> advertisement, DIS model <code>T1000-E</code>, ATT MTU 247,       and 244-byte write capability were all checked. All 404,468 bytes were       confirmed in 121.081 seconds at 3,340 B/s; DFU through target disconnect       took 144.076 seconds and the full supervisor took 176.958 seconds. CRC,       activation, and exact <code>239a:8029</code>/<code>34A9141999729D5D</code> USB return passed.</li> <li>[x] Two accepted in-DATA 30 ms -&gt; 15 ms -&gt; 30 ms controller experiments       completed without corrupting either image, but were decisive negative       performance results. The first finished DATA in 425.398 seconds at       951 B/s; the later candidate finished DATA in 449.063 seconds at 901 B/s.       HCI capture found the cause: <code>hcitool lecup</code> silently encoded both       connection-event-length hints as <code>0x0001</code> (0.625 ms). The Pi's Broadcom       4.2 controller consequently scheduled about one ACL fragment per event:       roughly 64 fragments/s at 15 ms and 32 fragments/s after the 30 ms       \"rollback\", versus roughly 120--144 fragments/s on the untouched link.       The later pre-START controls prove that 15 ms itself is not slow; the       restrictive event-length hint and in-DATA update/rollback were unsafe.</li> <li>[x] Two exact 15 ms/latency-0, zero-event-length lab controls passed:       <code>t1000-ble-event-length-prestart-20260830-071549-QOeVuw</code> completed all       404,468 DATA bytes in 64.905 seconds at 6,232 B/s (95.635 seconds through       target disconnect; 112,639 ms full workflow), and       <code>t1000-ble-event-length-prestart-20260830-071825-VE9Re3</code> completed DATA in       62.070 seconds at 6,516 B/s (92.794 seconds through target disconnect;       106,807 ms full workflow). Both used exact <code>0/0</code> no-preference minimum and       maximum connection-event lengths. On each bootloader connection the HCI       trace contains exactly one successful update before START and none from       START through DATA, validation, activation, and the target disconnect;       Update Complete preceded START by 7.535 and 7.536 seconds. Completed-packet       clusters followed the 15 ms connection anchors, while the median full-size       DFU write gap was 29.997 ms in both traces. Exact package hash, CRC,       activation, and stable application USB return passed twice.</li> <li>[x] <code>t1000-ble-event-length-prestart-20260830-071358-ogzmRy</code> is the bounded       negative control. HCI accepted exact 15 ms/latency 0 with both event-length       hints set to 10 ms, then reported <code>Connection Timeout (0x08)</code> 6.810 seconds       after Update Complete during the 20-second pre-START pause. The run failed       closed at <code>STAGE=pre_start_update</code> in 44,227 ms; START and application DATA       were never sent. A 10 ms event-length hint is therefore rejected for this       adapter/target pair.</li> <li>[ ] Production BLE DFU keeps the controller-negotiated link and issues no raw       host connection update unless that exact adapter/target profile has been       separately graduated. The opt-in lab path may issue exactly one request on       the bootloader connection before START while sent/confirmed are zero: exact       interval and latency, <code>0/0</code> no-preference event-length hints, bounded pause,       and a matching HCI Update Complete are mandatory. Failure or mismatch       disconnects before START. Never update or roll back the link during DATA;       only the protocol PRN/window may adapt there. Compare complete repeated       control/candidate DFUs offline before graduating a production profile.</li> <li>[ ] Repeat the cold transfer with the host's bounded BlueZ readiness wait.       When ATT MTU is greater than 23 while the cached write capability remains       20, it polls the same connected DFU characteristic for at most three       seconds, aborts on disconnect, disappearance, or characteristic-handle       change, and otherwise falls back safely to 20. The four readiness unit       cases and all 81 strict helper tests pass; a physical 20 -&gt; 244-byte       promotion is still required.</li> <li>[ ] Restore the protected       <code>t1000e_repeater_lora_ota_no_external_sensors</code> application (target       <code>0x7B071FA0</code>, exact ZIP SHA-256       <code>9b9be2bee9ebb6644d22806d404fe02c415d037707713d206fa43a8c689cf632</code>)       through identity-gated application DFU while retaining the candidate       bootloader. Do not use the generic repeater image or the unqualified UF2       path. Verify the protected private/public identity without printing the       private key, plus exact name, latitude/longitude, build/body/OTA target,       USA radio, 22 dBm, GPS off, power saving on, RX gain on, RXPS on,       watchdog on, telemetry access <code>all</code>, no TempRadio/download, and a valid       admin login.</li> <li>[ ] LoRa radio reset/recovery is forced and normal receive/transmit resumes.       Normal post-reboot bidirectional LoRa is already proven: the V4 learned a       zero-hop path, received the exact message-specific ACK in 558 ms, and       received the T1000-E's exact <code>3caf9dcf</code> version reply. A deliberately       forced LR1110 recovery event is still required.</li> <li>[x] Direct V4 LoRa OTA receive, apply, reboot, and post-update verification       passed from exact <code>bf092b24</code> body <code>9443FB5E6F23FC1B</code> to exact <code>3caf9dcf</code>       body <code>3E92B157128B6963</code> on OTAFIX 2.4.3. The mandatory fixed three-minute       rehearsal passed at <code>909.950/250/SF5/CR5</code>, including natural expiry and       return to <code>910.525/62.5/SF7/CR5</code>. The 2,036-byte/two-block delta reached       ready in six seconds, the new body replied at the 50-second probe, and the       complete safety-wrapped runner took 519 seconds. V4 source RXPS and both       normal radio tuples were restored. The co-located T1000 was temporarily       reduced to 0 dBm and restored to 22 dBm using bounded retries across its       RXPS busy windows.</li> <li>[x] Independent post-LoRa-OTA USB verification matched the protected pre-run       private key, public key, name, latitude, and longitude without printing       private material. GPS remained off; device power saving, system watchdog,       RX gain, and RXPS remained on; telemetry access remained <code>all</code>; no       TempRadio lease or download remained. <code>blrc:B8</code> is the expected OTAFIX       application-apply success diagnostic. A subsequent software reboot reset       uptime and preserved the exact build/body, name, radio, 22 dBm, GPS,       power-saving, RXPS, watchdog, and no-TempRadio state. The CDC symlink did       not disappear during this warm reset, so uptime/readback\u2014not USB removal\u2014       is the required reboot proof on this board.</li> <li>[x] GPS was initially off, enabled successfully under device power saving,       reported active/no-fix/zero-satellites with its duty-cycle deadline, and       was restored to off. Device power saving reported on, RXPS reported       <code>on,18205,20423</code>, GPS advert policy <code>prefs</code>, and telemetry access <code>all</code>.</li> </ul>"},{"location":"hardware_validation_checklist/#rak3401","title":"RAK3401","text":"<ul> <li>[x] Stable USB identity and SWD FICR identity are independently matched.</li> <li>[x] Source-level WisBlock peripheral pins are complete and non-conflicting:       I2C SDA/SCL are P0.13/P0.14 through both <code>PIN_WIRE_*</code> and       <code>PIN_BOARD_*</code>; GPS-module RX crosses to MCU UART TX P0.16, GPS-module TX       crosses to MCU UART RX P0.15, and PPS is P0.17. A static contract test       prevents these aliases from silently disappearing or being uncrossed.</li> <li>[x] Ordinary/full-sensor RAK3401 profiles use the source-built Adafruit BME680       provider, not Bosch's precompiled BSEC archive, so upstream issue #3292's       soft-float/hard-float link mismatch is not reachable there. The reduced       LoRa-OTA profile deliberately omits BME680/BSEC and the other declared       optional environmental/ranging drivers. A static contract test requires       the hard-float path fix and BSEC dependency if BSEC is enabled in this       board or an inherited full-sensor recipe later.</li> <li>[ ] With the RAK13302 radio installed, detect a RAK12501/L76K UART GPS from a       complete checksum-valid NMEA sentence in sensor slot A. Confirm random       UART bytes, an incomplete sentence, and a bad checksum do not claim GPS.</li> <li>[ ] Detect RAK12500 I2C GPS alone at <code>0x42</code>; exercise GPS power saving and       confirm the shared 3V3_S rail, OLED, RTC, and other slots remain powered.</li> <li>[ ] Detect INA3221 alone at the firmware-configured <code>0x42</code> and prove the       discovery path does not send u-blox configuration traffic to it.</li> <li>[ ] Exercise RAK12500 at <code>0x42</code> and INA3221 at <code>0x43</code> together after strapping       INA3221 A0 to SCL and building with       <code>-DTELEM_INA3221_ADDRESS=0x43</code>; verify both retain independent telemetry.</li> <li>[ ] With a representative omitted environmental sensor attached, confirm the       reduced image leaves the generic I2C bus healthy but does not advertise a       driver that was intentionally removed.</li> <li>[x] Local USB terminal probes are terminated with carriage return (<code>\\r</code>).       This CLI echoes an LF-only command without executing it; an echoed       <code>ver</code> with no reply is therefore a bad probe, not evidence of a hung       application. Confirm any suspected hang with a CR-terminated command,       LoRa status, and SWD state before resetting the board.</li> <li>[x] Assert CDC DTR when probing the RAK terminal. With DTR deasserted, writes       reached the port but no CLI replies were returned; the same exact       stable-identity port returned the expected version immediately after DTR       was asserted. Keep 1200-baud bootloader touch separate from 115200-baud       application probes, and allow a full reply window so delayed responses       are not attributed to the following command.</li> <li>[x] Installed S140 6.1.1 FWID (<code>0x00B6</code>) and runtime application base       (<code>0x26000</code>) are independently verified.</li> <li>[x] Bootloader version and apply capabilities are independently reported.</li> <li>[x] UF2 application copy returns success; <code>sync -f</code> returns success; no USB       reset/timeout or offline-sector errors occur; SWD readback matches every       UF2 payload byte. Current 2.4.4-preview.2 result is PASS in both       current\u2192old and old\u2192current directions.</li> <li>[x] Board, repeater role, version, name, and USA radio tuple are verified       after serial recovery and again after a real cold boot.</li> <li>[x] Six consecutive authenticated <code>ota self</code> attempts leave the application       healthy. In the qualification run, two login/reply pairs were lost, one       login succeeded while its command reply was lost, and the next three       commands replied in about 2.5 seconds each. A CR-terminated local <code>ver</code>       probe passed after every attempt; packet loss did not become a node hang.</li> <li>[ ] An unchanged admin login does not rewrite the ACL flash file, while an       actually changed/newly learned persistent route schedules exactly one       delayed save and survives reboot. Cover delayed flood-path replies,       already-unknown paths, changed permissions/secrets, new/evicted clients,       and the intentionally non-persistent guest case. Do not rely on an       unrelated login write to capture a later PATH response.</li> <li>[ ] Location and private-key persistence are verified without exposing the       private key in logs.</li> <li>[x] Serial recovery rejects nrfutil's false exit-0 failure, requires the exact       success marker, and produces a byte-exact SWD application readback.</li> <li>[ ] UF2/serial recovery works with both the deployed older bootloader family       and the current backward-compatible application.</li> <li>[ ] Bluetooth advertisement and connection work when enabled. The tested       repeater profile does not advertise BLE during normal operation.</li> <li>[x] Direct LoRa OTA from the V4 passes with elapsed time, bounded retry       behavior, final hash/version verification, exact radio restoration, and       independent SWD readback. The qualified <code>bf092b24</code> base       <code>91CF4EC2882F23D6</code> reached <code>3caf9dcf</code>/<code>27A223DDFC3A8F47</code> using a       two-block, 2,132-byte delta: ready in six seconds, new body at the       60-second reboot probe, and 514 seconds for the complete safety-wrapped       run. Log:       <code>/home/mikec/hwtest/runs/rak3401-0dbm-final-9KWjey61/run.log</code>.</li> <li>[x] The current OTAFIX test version <code>0x02040403</code> independently passes a       74-block direct LoRa update from exact <code>3caf9dcf</code> body       <code>27A223DDFC3A8F47</code> to HEAD <code>9fd580c8</code> body <code>744BC4443891ED10</code>.       READY took 122 seconds and the complete three-minute-rehearsal,       transfer, install, reboot, recovery, and restore wrapper took 589.487       seconds. Lost read-only preflight and postboot replies were reconciled by       bounded exact retries. USB confirmed the target/hardware/body and       bootloader success result, and authenticated LoRa readback confirmed the       final 22 dBm restoration. Sanitized log:       <code>/home/mikec/hwtest/runs/rak3401-02040403-head-vzWOXVxT/qualification-redacted.log</code>.</li> <li>[ ] Add exact RF packet sent/confirmed counters to the device/host telemetry.       The qualified run records two payload blocks, all seeder reads, command       retries, and final success, but those are not equivalent to LoRa packet       counts and must not be presented as such.</li> <li>[ ] Repeat at each supported bandwidth and record 0-hop, 1-hop, and 2-hop       estimates from measured airtime rather than extrapolating only by file size.</li> </ul>"},{"location":"hardware_validation_checklist/#rak4631-reduced-profiles","title":"RAK4631 reduced profiles","text":"<ul> <li>[x] Serialized VM contracts distinguish the three application identities:       the plain and Serial2 reduced profiles retain the combined WisBlock GPS       provider and all four INA voltage/current drivers; the explicit legacy       Serial1 profile retains the INA drivers and omits GPS. This is build       evidence only, not physical peripheral qualification.</li> <li>[ ] On the plain reduced profile, detect and read RAK12500 I2C GPS, a       RAK12501/L76K UART GPS in a separate run, the SSD1306 OLED, a supported       autodiscovered RTC, and representative INA telemetry. Verify GPS sleep and       repeated discovery never lower the shared WB_IO2/3V3_S rail.</li> <li>[ ] With a UART RAK12501 installed and detected, confirm the Serial2 bridge       and GPS remain usable together. Select Serial1 and try to enable the       bridge with the GPS preference both on and off; verify each attempt is       refused before the bridge starts and does not change GPS transport,       acquisition, hold, or cached-fix state. The shared WB_IO2/3V3_S rail must       remain high and GPS must remain usable after each refusal.</li> <li>[ ] With only an I2C RAK12500 installed, and again with neither GPS installed,       select Serial1 on the merged image and confirm bridge enable is refused       without changing saved UART/runtime state. Silence or an I2C-only detection       must not defeat the fail-closed RAK12501 reservation. Confirm Serial2 starts       and I2C GPS telemetry remains usable.</li> <li>[ ] Exercise RAK12500 at <code>0x42</code> and INA3221 at <code>0x43</code> together with the       address-matched build. Separately place INA3221 alone at the configured       <code>0x42</code> and prove the identity guard prevents u-blox configuration writes.</li> <li>[ ] With a logic analyzer, hold SDA low and then SCL low before sensor       discovery. Confirm the validated board pins receive at most nine       open-drain recovery clocks and a STOP only after SCL rises; the firmware       must skip discovery if either line remains low. Repeat on ProMicro's       remapped SDA 8/SCL 7 and verify the user-button pin is never driven.</li> <li>[ ] Record the remaining core limitation: the pinned Adafruit nRF52 Wire       implementation has no transaction timeout. This preflight cannot protect       display/RTC calls made earlier in boot or interrupt a peripheral that       wedges after a transaction begins. Qualify those cases with a hard power       cut/watchdog fixture before claiming bus-hang recovery.</li> <li>[ ] Confirm the explicit legacy Serial1 image exposes neither UART RAK12501       nor I2C RAK12500. Record this as a combined-provider build limitation, not       an assertion that RAK12500 electrically conflicts with the UART.</li> </ul>"},{"location":"hardware_validation_checklist/#heltec-t096","title":"Heltec T096","text":"<ul> <li>[x] The cross-role <code>uf2reset</code> repair was hardware-qualified on the exact       no-footer Full Companion image. ZIP SHA-256 is       <code>0585bee1c0b278a68788f78af384bcbdb5633d57f9ea301fc14f1c80c4275489</code>;       embedded version is <code>v1.17.1-uf2reset-f2c15225-f2c15225</code>. Terminal entry       and help passed, the exact command disconnected application USB in       1.031 seconds, and stable boot USB returned in 2.026 seconds. The final       Full image installed over serial in 38.900 seconds and stable application       USB returned in 41.672 seconds. Final primary terminal/Binary switching,       dedicated logging interface, version, help entry, and live       <code>MeshCore-8E229D0A</code> advertisement at <code>CF:A8:18:36:DE:8B</code> all passed.</li> <li>[x] Stable USB serial <code>651F8E496197F882</code> distinguishes the application       (<code>239A:8029</code>) from the OTAFIX serial-DFU interface. Every flash followed       that identity across the host-assigned <code>COM9 -&gt; COM6 -&gt; COM9</code> transition;       the simultaneously connected MeshPocket on <code>COM20</code> was never selected.</li> <li>[x] Baseline bootloader <code>0.11.0-OTAFIX2.4.3</code> was installed at this checkpoint. The restored Repeater       reports application body hash <code>3B6D1A729C087243</code>, target <code>98411AC6</code>, apply       ABI 3, codec mask <code>0x5</code>, and stage address <code>0xED000</code>. The application ZIP       is 708,216 bytes with SHA-256       <code>abb00560cc5618ae155bf10252e9261127416a7a91b5f6565837384f0dec2390</code>.</li> <li>[x] A 48,229-byte in-place delta with SHA-256       <code>988bd2385e9c995d0ae04effb6bb5cd614227c7c764590d82bd1943da2f18e4d</code>       transferred over LoRa in 47/47 blocks from the MeshPocket seeder and       applied successfully. The first application boot reported bootloader       result <code>B8</code>; the running body hash matched the candidate exactly. No chat       message was sent for this transfer.</li> <li>[x] The generic delayed AGC/watchdog arming fix passes warm-reboot hardware       checks on both the T096 and MeshPocket. The restored T096 retained AGC       interval 8 and, after 215 seconds, was in RX with 100 packets received,       28 sent, zero core errors, and <code>err_flags=0</code>. The Pocket's quiet-channel       liveness recovery set only the expected radio-watchdog bit; temporarily       matching the USA channel then received 14 packets with zero receive       errors before its saved <code>869.618/62.5/SF8/CR5</code> profile was restored. At       498 seconds the T096 had one CAD-busy timeout after 37 busy-channel       samples, then returned to RX with no queue, watchdog, or start-RX fault.</li> <li>[x] Exact Full Companion ZIP SHA-256       <code>ee92856e5bfb7877b0d8bff6d6a5873d8037fc178ddb151202a9e6a6d9d59e73</code>       installed by serial DFU and passed the reversible dual-CDC test. Logging       off exposed only interface <code>00</code>; <code>set usb.logging on reboot</code> added       interface <code>02</code> as <code>COM21</code>. Opening <code>02</code> emitted both portable identity       lines, 980 captured bytes were entirely printable, and host input produced       no echo or command reply while Binary Companion on <code>00</code> returned the exact       model, key, and radio tuple.</li> <li>[x] With interface <code>02</code> deliberately unread, 11/11 text-terminal probes stayed       between 212 and 231 ms for 44.4 seconds. A longer 100-second hold buffered       8,636 entirely printable bytes while 60/60 hard-bounded Binary Companion       reconnects passed with no timeout; the final full identity query completed       in 739 ms. Neither USB interface disconnected. Logging off plus reboot       removed <code>02</code>, read back off on <code>00</code>, and the qualified Repeater was then       restored with its original name, public key, and USA radio tuple.</li> <li>[x] The descriptor/reconnect follow-up built a 482,271-byte Full Companion DFU       ZIP with SHA-256       <code>2a5a6bd0fd26031a2c2e047af6ead8f85f0d617da238d0cd6d816f7d5c41ec6f</code>.       On the physical T096, Windows read interface <code>02</code>'s bus-reported       description as <code>MeshCore Logging</code>. Two immediate open/close cycles each       delivered the complete 80-byte two-line identity marker with no NUL or       other invalid control byte, while Binary Companion on interface <code>00</code>       retained the exact key, model, and <code>910.525/62.5/SF7/CR5</code> tuple.</li> <li>[x] The final short-write/reconnect guard built a 482,271-byte Full Companion       DFU ZIP with SHA-256       <code>bbbc3459b2c032af23c6da05e41984cb0250398b57ba56ea99166456700ace6f</code>       and EndF body hash <code>41365E4DB0FF4AE5</code>. On the physical T096, interface       <code>02</code> again reported <code>MeshCore Logging</code>; 3/3 explicit DTR sessions each       delivered one complete 80-byte marker with no NUL or invalid control byte.       With that logging endpoint held open and unread, interface <code>00</code> completed       60/60 Binary Companion reconnect queries and retained public key       <code>8e229d0a9ace9bd6f768fc1237d9e3ebca340d1ff1c6087349983a07f305903a</code>       plus the exact <code>910.525/62.5/SF7/CR5</code> tuple.</li> <li>[x] The corrected Windows flasher identifies Binary-mode Full Companion and       links the same-radio <code>MI_02</code> inventory row to <code>MI_00</code>. An intentional       selection of <code>COM21/MI_02</code> was canonicalized to <code>COM9/MI_00</code> before any       1200-baud action; the exact USB serial then followed       <code>COM9 -&gt; COM6 -&gt; COM9</code>, never touched the logging endpoint or MeshPocket,       and produced both <code>Device programmed.</code> and <code>Flash completed.</code>. The VM was       suspended only across each touch/transfer and resumed immediately. After       restoring the qualified Repeater and performing a final warm reboot, the       58-second snapshot was in RX with 28 packets received, 9 sent, zero core       errors, an empty queue, and <code>err_flags=0</code>.</li> <li>[x] Final flasher review now revalidates the selected USB identity and exact       interface immediately before both the direct 1200-baud open and its Python       fallback, and balances every successfully written terminal START with a       STOP even when the banner is lost. Windows PowerShell 5.1 and PowerShell 7       regression suites pass. A second physical restore deliberately selected       <code>COM21/MI_02</code>; it was canonicalized to <code>COM9/MI_00</code>, followed the same       <code>COM9 -&gt; COM6 -&gt; COM9</code> transition, and completed without touching the       MeshPocket. At 112 seconds the restored Repeater retained its name, OTA       body hash <code>3B6D1A729C087243</code>, USA radio tuple, and AGC interval 8; it was in       RX with 20 packets received, 6 sent, zero core errors, an empty queue, and       <code>err_flags=0</code>. The VM was running again immediately after the flash.</li> <li>[x] The T096-only message profile defines <code>UI_MESSAGE_CHANNEL_FOOTER=0</code>;       every other profile retains the default footer. The exact incoming       <code>#testing</code> message <code>T096 footer test: wrapped text should reach the screen       bottom.</code> traversed the live channel receive/display path, and the temporary       empty <code>#testing</code> channel slots on both endpoints were restored byte-for-byte.       Static profile coverage passes 2/2. No framebuffer or camera capture was       available, so the evidence is the exact live UI path plus the compiled       board-specific flag rather than a pixel photograph.</li> <li>[x] The then-final Full Companion artifact at this checkpoint,       <code>v1.17.1-t096-head-fcd1f8cc-usbtask8-fcd1f8cc</code>, was installed. Its DFU ZIP       is 487,231 bytes with SHA-256       <code>CD267952F420294DF21CA96E3AA6D924C6EF7467C31C8D69B46F31E6719A1D67</code>;       the application is 486,428 bytes with a 486,372-byte EndF body and hash       <code>2E03B1C1166D4CC0</code>. The ELF exposes strong <code>T</code> definitions for both CDC       callbacks, mount/unmount, SOF, and the CDC0-only framework flush override.</li> <li>[x] Identity-gated BLE application DFU passed through the bonded address       <code>CF:A8:18:36:DE:8B</code>: encrypted application handoff from       <code>MeshCore-8E229D0A</code>, same-address <code>T096_DFU</code> Legacy service, and DIS model       <code>HT-n5262G</code> all matched. The target confirmed 486,428/486,428 bytes in       565.986 seconds at 859 payload B/s, validated, activated, and initiated       the expected disconnect; end-to-end time was 603.967 seconds. USB serial,       version, board, public key, radio tuple, EndF hash, and bootloader apply       ABI 3/codecs <code>0x5</code> returned exactly, and a fresh active scan observed the       application name again at the same address.</li> <li>[x] The real host <code>motatool</code> opened <code>COM9</code>, survived the intentional CDC       session-settle purge, attached an empty folder with <code>COUNT -&gt; 0</code> and       <code>OK folder attached</code>, then detached it and restored Binary mode. This       test sent no mesh messages. Three primary-port close/reopen cycles after       deliberately abandoned terminal output exposed zero stale bytes and each       returned a clean banner. Five logging-port reopen sessions each began       with the exact 80-byte identity marker and contained no NUL or invalid       control byte.</li> <li>[x] With both USB outputs deliberately unread for 65 seconds after a 10,000-byte       terminal input burst, the primary accumulated 16,886 printable bytes and       CDC1 accumulated 3,735 printable bytes beginning with its exact marker.       <code>ver</code> and Binary Companion remained responsive. A subsequent warm reboot       removed USB for 2.209 seconds, returned both interfaces in 2.409 seconds,       and CDC1 again emitted the exact marker. At 65 seconds the fresh boot had       <code>err_flags=0</code>, an empty outbound queue, 9 received floods, and zero CRC       errors. A Windows host-side composite       restart was attempted but denied by the non-elevated PnP API, so the       distinct host-driven BUS_RESET case remains a physical/privileged check;       it is not inferred from the warm-reboot result.</li> <li>[x] After the operator physically removed and restored T096 power (the off       interval was not measured), stable serial <code>651F8E496197F882</code> returned as       primary <code>MI_00</code>/<code>COM9</code> and logging <code>MI_02</code>/<code>COM21</code>. The cold terminal       reported exact version       <code>v1.17.1-t096-head-fcd1f8cc-usbtask8-fcd1f8cc</code>, Heltec T096 identity,       public key, USA radio tuple, BLE name, dedicated-CDC logging state, EndF       body hash <code>2E03B1C1166D4CC0</code>, and bootloader apply ABI 3/codecs <code>0x5</code> with       stage ceiling <code>0xD4000</code>; mOTA remained source-only with no folder attached,       and STOP restored Binary mode. CDC1's first read was the exact 80-byte       identity marker with no NUL. At 150 seconds, Binary stats reported 4,224       mV, <code>err_flags=0</code>, an empty outbound queue, 47 packets received, zero       packets sent, and zero TX airtime. A second core checkpoint advanced       monotonically to 315 seconds with 4,220 mV, <code>err_flags=0</code>, and an empty       queue, providing no evidence of a watchdog reboot. A fresh active BLE       scan observed <code>MeshCore-8E229D0A</code> at the same <code>CF:A8:18:36:DE:8B</code>       address; BlueZ still       reported paired, bonded, and trusted. No mesh message was sent. This proves       cold persistence, but not the distinct host-only USB <code>BUS_RESET</code> path.</li> <li>[x] The display auto-off wake failure was traced to the shared ST7735 power       lifecycle: <code>turnOff()</code> released SCK/MOSI as inputs, but the nRF52       <code>SPIClass::begin()</code> wake path was a no-op while the SPI object still       considered itself initialized. The shared driver now restores the bus-pin       directions and nRF52 high-drive configuration explicitly, waits through       reset release, and primes the retained frame after <code>DISPON</code>. Static wake       ordering and the T096 footer profile pass, and the exact Full Companion artifact       <code>v1.17.1-t096-head-fcd1f8cc-wake1-fcd1f8cc</code> compiled at 486,348 bytes.       Its 487,231-byte serial-DFU ZIP has SHA-256       <code>A091F6DC458177BB26B8384B2AAAC0A9FD550322179F96062CCD3F0F5BB0E585</code>;       the 486,428-byte OTA image reports a 486,372-byte EndF body with hash       <code>E9AB2A36E9F7091F</code>. Identity-gated <code>meshfirmware</code> selected <code>COM21/MI_02</code>,       canonicalized it to <code>COM9/MI_00</code>, followed <code>COM9 -&gt; COM6 -&gt; COM9</code>, and       emitted both <code>Device programmed.</code> and <code>Flash completed.</code> without touching       the MeshPocket. The VM was suspended only across touch/transfer and was       running again as soon as exact serial <code>651F8E496197F882</code> returned. Live       readback then matched the public key, Heltec T096 board, USA       <code>910.525/62.5/SF7/CR5</code> tuple, ABI 3/codecs <code>0x5</code>/stage <code>0xD4000</code>, and exact       80-byte CDC1 marker; core checkpoints advanced through 369 seconds with       <code>err_flags=0</code>, an empty queue, and zero TX. Follow-up physical testing       confirmed auto-off wake and single-click page navigation. Double-click,       triple-click, long-press, and simultaneous-button gestures remain deferred.</li> <li>[x] A signed bootloader mOTA package for OTAFIX HIL candidate <code>0x02040401</code>       transferred over LoRa in 40/40 blocks, passed the privileged-install gate,       installed with the watchdog enabled, and rebooted with unchanged node and       radio settings. The installed bootloader CRC changed to the package's       expected <code>381BAE6E</code>; the temporary HIL signer was removed afterwards.</li> <li>[x] A 486,796-byte Full Companion application completed bonded Legacy BLE DFU       at approximately 5.7-6.2 kbit/s payload throughput, then returned with the       same identity and USA radio tuple. The later CDC0 first-open fix preserved       immediate <code>APP_START</code> input across the eight-millisecond session gate:       first client after reboot passed with CDC1 logging active, followed by       10/10 immediate COM9 close/reopen queries. CDC1 continued to emit its exact       identity marker and printable packet/debug logs.</li> </ul>"},{"location":"hardware_validation_checklist/#heltec-meshtower-v2-with-sd","title":"Heltec MeshTower V2 with SD","text":"<ul> <li>[x] Stable serial <code>9352162A72082314</code> and physical downstream-hub path       <code>1-1.2</code> port 4 identify this board across application and bootloader       descriptors; no other attached nRF52 endpoint was selected. The older       2.4.3 bootloader's UF2/serial failure was rejected rather than treated as       a successful flash.</li> <li>[x] Exact <code>1.17.1.5-halo-keymind-cascade-marathon-hwtest-e26d48e4</code> SD       Repeater boots with hardware ID <code>Heltec_tower_v2</code>, target <code>0A9DBBF0</code>,       body hash <code>E9282D470AAC348B</code>, and USA radio       <code>910.525/62.5/SF7/CR5</code>. <code>ota self</code> reports SD apply ABI 3 with codec mask       <code>0x5</code>; <code>ota bootloader</code> reports board <code>239A0071</code>, target <code>1150F50E</code>, name       <code>TOWER_V2_OTA</code>, and capability byte <code>09</code>.</li> <li>[x] A post-Pi-recovery identity-gated serial audit reconfirmed the exact       Tower V2 model, Repeater role, build, <code>910.525/62.5/SF7/CR5</code>, target       <code>0A9DBBF0</code>, body <code>E9282D47</code>, SD ABI 3/codecs <code>0x5</code>, and installed       bootloader identity/capability <code>239A0071</code>/<code>09</code>. The card reported       959.6 MiB free and no active download. This profile exposes the local       text console but deliberately has no runtime <code>usb.logging</code> setting; the       unknown-setting reply is a capability result, not a transport failure.</li> <li>[x] Card detection and destructive maintenance pass. Normal format took       3,927 ms; an immediate repeat was rejected by the five-minute cooldown;       forced format took 3,933 ms; and raw erase plus format took 3,947 ms.       The card remounted empty with 16.0 KiB used and 959.6 MiB free, and both       completion ages were recorded. Automatic archive capture was then       disabled deterministically, leaving only <code>/mota/cache.off</code>.</li> <li>[ ] SD card detection, staging, hash validation, apply, cleanup, and recovery       from missing/corrupt media pass.</li> <li>[ ] Multi-page application and bootloader update paths pass across a cold boot.</li> <li>[ ] LoRa OTA receive/apply reports the expected target ID and installed version.</li> </ul>"},{"location":"hardware_validation_checklist/#heltec-v4","title":"Heltec V4","text":"<ul> <li>[x] Exact V4 hardware variant is reported (<code>Heltec V4.3 OLED</code>); OLED/TFT       variants are not merged.</li> <li>[x] Full Companion boots with USB logging off and Binary Companion selected.       The text terminal independently reports the complete build string;       protocol <code>ver</code> has a shorter fixed-width version field.</li> <li>[ ] USB logging changes take effect immediately on this single-TTY ESP32       profile, require no reboot, and return to Binary Companion only through       the explicit terminal-stop mode change.</li> <li>[x] Bluetooth pairing and Companion protocol operations pass. Qualification       required removing the Pi's stale pre-flash bond, pairing through a BlueZ       <code>KeyboardOnly</code> agent with the current displayed/reported PIN, then       reconnecting; BLE <code>infos</code> and <code>ver</code> returned the exact V4.3 OLED identity.</li> <li>[x] Saved Wi-Fi connects to <code>SlowFi</code>, returns at <code>192.168.1.51</code> after the test       host reboot, reports Wi-Fi power save <code>min</code>, and remains governed by the       configured-network behavior rather than the unconfigured 30-minute       shutdown policy.</li> <li>[x] TCP Binary Companion (<code>5000</code>), Wi-Fi OTA (<code>5001</code>), and text CLI (<code>5002</code>)       are each tested and cannot be confused with one another. Port 5000       returned the exact Companion identity; 5002 returned the full terminal,       version, Wi-Fi, logging, RXPS, and memory state; and a real <code>motatool       serve --tcp 192.168.1.51:5001 -v</code> session received <code>COUNT -&gt; 0</code> from an       intentionally empty folder. Disconnect then restored <code>folder:not       connected</code> while the 5001 listener stayed active.</li> <li>[ ] For a shared Full-Companion controller/seeder, bind the source identity       to the exact public key already read from Binary Companion port 5000.       Do not require <code>get public.key</code> from text port 5002: the hardware-tested       V4 Full CLI rejects that command. Port 5002 must still prove the local       TempRadio state/tuple, while keyed on-air destination replies prove the       physical LoRa handoff.</li> <li>[ ] V4 seeds direct and routed LoRa OTA; TempRadio preflight, apply, and       automatic normal-radio restoration all pass.</li> </ul>"},{"location":"hardware_validation_checklist/#seeed-sensecap-indicator-lora","title":"Seeed SenseCAP Indicator LoRa","text":"<ul> <li>[x] Flashing selects the ESP32-S3 CH340 endpoint, never the Indicator RP2040       ACM endpoint; esptool MAC probing succeeds before erase. The qualifying       merged write used 115200 baud and completed with flash hash verification.</li> <li>[x] A fresh merged install completes SPIFFS initialization and reports the       intended Full Companion version/role and <code>Seeed SenseCAP Indicator</code>       hardware identity. The exact qualifying artifact was       <code>SenseCapIndicator-LoRa_companion_radio_full-1.17.1.5-halo-keymind-cascade-marathon-e26d48e4-merged.bin</code>,       2,070,152 bytes, SHA-256       <code>df08b770313ca8776436456525681cf286cd9b5b40e05e7cf55f21ef097f338a</code>;       its ELF, map, manifest, and partition signature are archived beside it on       the Mercerwood Pi.</li> <li>[x] The current dark-layout Full Companion application was flashed app-only       with exact CH340/MAC/partition gates, preserving identity, Wi-Fi, and       settings. The 2,147,800-byte application has SHA-256       <code>81bebdc07b6a8349c1c975cb5a0e30c5f6019d35bcac641e5f3d4df951f7406b</code>;       esptool verified its flash hash in 134.2 seconds. USB Binary/terminal,       saved logging-off state, configured Wi-Fi, BLE, TCP ports 5000/5001/5002,       and an empty-folder Wi-Fi mOTA <code>COUNT -&gt; 0</code> exchange all pass afterward.</li> <li>[x] Keep one identity-gated CH340 descriptor open with DTR/RTS deasserted       through startup. On the valid-current-font path, the Indicator streams a       1,302,608-byte font from its RP2040 at 1 Mbps before registering the USB       terminal, so allow at least 30 seconds before the first command. A       missing/corrupt-font recovery instead runs in the background after the       interfaces start. Reopening short probes can reset the ESP32 repeatedly       and create a false UART-hang diagnosis; the controlled run returned       <code>ver</code> and <code>board</code> after the same apparent-silence condition.</li> <li>[x] Automatic font recovery starts from a physically corrupt RP asset. The       setup deliberately installed 64 all-zero bytes, CRC32 <code>758d6336</code>, in       place of <code>/meshcore/ui-font.vlw</code>; the ESP32 rejected that asset and kept       its built-in fallback font while recovery ran.</li> <li>[x] Every new HTTPS recovery attempt waits for a fresh SNTP callback and a       signed epoch at or after the compiled asset publication time before it       opens TLS. The forced-resume run observed fresh syncs in 3,700, 400, and       699 ms across three outer attempts, including two failed TLS handshakes;       the final normal run synced in 1,999 ms and only then logged the first       <code>api.github.com</code> connection. A retained merely plausible clock is not       accepted. CA validation and the compiled asset SHA-256 remain mandatory.</li> <li>[x] The release-source normal path downloaded all 1,302,608 bytes into PSRAM       in 13,205 ms, closed TLS, verified SHA-256       <code>61bce9662db314054e7bcfaa26147a28ad7b500b51baac4cae1caacce90b7421</code>,       staged receiver-paced 512-byte <code>MCFONT STAGEV2</code> chunks in 36,676 ms,       committed, and verified RP CRC32 <code>19f80d64</code> at 76.7 seconds from reset.       An independent <code>MCFONT GET</code> over RP USB then returned exactly 1,302,608       bytes with the same CRC and SHA in 15.273 seconds. The exact installed       application is       <code>SenseCapIndicator-LoRa_companion_radio_full-1.17.1.5-halo-keymind-cascade-marathon-font-recovery-e26d48e4.bin</code>;       its log is       <code>/home/mikec/hwtest/runs/indicator-release-recovery-lUZEmBHL/esp-serial.log</code>       on Mercerwood. The current RP service reports protocol 2 and completed       STAGEV2 accounting; its installed flash was not independently read back,       so no RP artifact hash is inferred from the archived candidates.</li> <li>[x] Strict Range recovery passed a forced hardware interruption. Exact test       application SHA-256       <code>cfd5aec497cb9919f87c0f82f5deaf8614d411582a709cea1c36275529c0bb68</code>       closed the initial response at verified offset 1,048,576. Its first       same-offset resume handshake failed; bounded retry 2/2 then accepted only       the remaining 254,032-byte <code>206</code> response under the original strong       ETag/<code>If-Range</code>, retained the same PSRAM buffer and SHA stream, completed       the download in 49,422 ms, staged in 36,702 ms, committed, and passed an       independent exact USB readback. The full log is       <code>/home/mikec/hwtest/runs/indicator-range-v2-xbKr09wI/esp-serial.log</code>.       An earlier forced 512 KiB run proved one correct resume at 524,288 but       later exhausted its second reconnect on a TLS failure; it is retained as       regression-trigger evidence rather than an end-to-end pass.</li> <li>[x] Rebooting the exact release-source application with the current valid       font performed no NTP query, TLS connection, or GitHub request. The       valid-font boot log is       <code>/home/mikec/hwtest/runs/indicator-release-valid-a84vd7Du/esp-serial.log</code>.</li> <li>[x] The post-qualification shared SNTP-coordinator source compiles in the       real Arduino-ESP32 2.x LoRa USB/WiFi profile (1,587,965 bytes, 60.6% of       its OTA slot), the dynamically generated ESP-NOW Full profile (2,093,465       bytes, 79.9%), and the matching RP2040 transactional service. After the       VM independently reported <code>NTPSynchronized=yes</code>, an       end-to-end request to the immutable GitHub asset returned HTTP 200,       exactly 1,302,608 bytes, and SHA-256       <code>61bce9662db314054e7bcfaa26147a28ad7b500b51baac4cae1caacce90b7421</code>.       A live <code>524288-1302607</code> continuation then returned HTTP 206, the same       strong ETag, an exact 778,320-byte <code>Content-Length</code>, and a byte-for-byte       hash match against the checked-in font tail; the pinned Sectigo E46 root       independently verified the current <code>api.github.com</code> chain.       The same coordinator also compiles in the real       <code>heltec_v4_repeater_observer_mqtt</code> profile: its 1,852,392-byte EndF image       has SHA-256       <code>fe8352654437f67488b412e1c1a690f2874e836abb5a5d209654bd030c713d7e</code>.       MQTT's three process-global <code>configTime()</code> paths are lease-protected,       and a busy asynchronous refresh uses a wrap-safe five-second retry       deadline instead of overwriting another service's SNTP callback or       recording a false successful refresh.       The exact final LoRa Full artifact gate then passed 11/11 linked-image       markers, including both <code>requesting fresh NTP time before download</code> and       the subsequent TLS-open marker. Its 2,146,312-byte application has       SHA-256       <code>f557088a5ef3f49f74ab01ca95fefc76911cca4073f01b77cee4882284fc5110</code>       and 475,128 bytes remain in its app slot; the matching 2,211,848-byte DIO       merged image has SHA-256       <code>52a4559774384b54dd7fb81da82c791e2c9564991fcf016bcad3b6ad756c1fb2</code>.       The exact ELF, map, capability manifest, and partition signature are       archived together under <code>/tmp/indicator-full-daily-ntp.WQ6ozM</code> on       the VM pending transfer to the hardware-run archive.       The ESP-NOW Full sibling passed the same 11/11 gate with a 2,093,928-byte       application (527,512 bytes free), SHA-256       <code>fcd9e0e8a37551a845a234fc10eaa4a9f420d54172039b9241f4696a12d4c65f</code>,       and matching DIO merged-image SHA-256       <code>f3637c23f58204f5b752b68a1bd494601cb68bee9c27b664832d40abd03cc186</code>;       its complete archive is <code>/tmp/indicator-espnow-full-ntp-gate.YN9T8l</code>.       Repeat the negative UDP/123-blocked hardware gate on this exact final       source before treating the coordinator refinement as hardware-qualified.</li> <li>[ ] Full Wi-Fi SSID, setup address, and related status text wrap without       clipping on the physical display. The new dark palette and exclusive       lower pairing block are installed; a fresh bond removal held the random       PIN request on-screen for 30 seconds and then an immediate second attempt       paired, trusted, and returned the exact Indicator identity over BLE. A       human physical-readability confirmation is still required; the automated       geometry tests prove the PIN block is centered at four-fifths height and       cannot overlap IP, inbox, or status text.</li> <li>[ ] Boot the exact current LoRa and ESP-NOW Full artifacts in both saved       secondary-transport modes and capture the <code>Indicator render</code> line. Require       LoRa + WiFi, LoRa + BLE, and ESP-NOW + infrastructure WiFi to retain       480x480, and ESP-NOW + BLE to select 320x320 scaled to the panel. A logged       emergency 320x320 fallback keeps the unit recoverable but does not pass a       native-480 gate.</li> <li>[ ] For all four boots, record free heap and largest internal block before       interfaces and after the selected interface is usable. In WiFi mode prove       BLE never starts; in BLE mode prove infrastructure WiFi, WebConfig, MQTT,       and TCP never start. Keep the primary LoRa or ESP-NOW radio exchanging       traffic throughout. For both BLE modes pair/encrypt, negotiate MTU,       subscribe, exchange repeated Companion requests, disconnect/reconnect,       and repeat after bond removal; exercise network/TCP traffic in both WiFi       modes and record the lowest heap/largest-block values.</li> <li>[x] With no saved SSID, setup Wi-Fi powers down after the absolute 30-minute       window even if queried or used.</li> <li>[x] A software reboot starts a fresh unconfigured setup window.</li> <li>[x] With a saved SSID, Wi-Fi reconnects to <code>SlowFi</code>, reports minimum modem       power save, and remains governed by normal configured-network behavior.</li> <li>[x] Bluetooth Companion pairing and protocol operations pass after saving a       deterministic qualification PIN, removing any stale host bond, pairing,       disconnecting the <code>bluetoothctl</code> client, and reconnecting with meshcli.       Binary <code>infos</code>/<code>ver</code> returned the exact Indicator identity and USA tuple.       A second connection after the USB-open reboot and logging-mode exercise       also returned the exact build; one initial scanner miss was resolved by       an explicit BlueZ discovery pass and was not a firmware advertisement       failure.</li> <li>[x] Wi-Fi/TCP Companion, CLI, and OTA endpoints pass at <code>192.168.1.54</code>:       port 5000 returned Binary Companion identity, port 5002 returned the full       text version/status, and motatool completed a port-5001 <code>COUNT -&gt; 0</code>       protocol exchange against an empty served folder.</li> <li>[x] Fresh Full starts with USB logging off. On this single-TTY ESP32 profile,       logging on/off applies and persists without a descriptor-changing reboot;       the same held-open ASCII terminal reported off -&gt; on -&gt; off correctly,       emitted live Wi-Fi/radio diagnostics while on, then accepted the explicit       terminal-stop token and returned a valid 85-byte Binary Companion device       info frame for <code>Seeed SenseCAP Indicator</code> without rebooting. Companion       remained independently usable over Bluetooth and Wi-Fi.</li> <li>[x] Normal-radio LoRa transmit and receive pass. At the installed 22 dBm,       a co-located discovery request overloaded the nearby receivers and found       zero nodes; temporarily reducing only the Indicator to 0 dBm produced       three repeater replies at RSSI -29 to -59 dBm, proving both directions.       The saved 22 dBm value was restored and independently read back after the       test; this near-field result is a lab-power gate, not a firmware failure.</li> <li>[ ] TempRadio sanity check, OTA seeding, and normal-radio restoration pass.</li> </ul>"},{"location":"hardware_validation_checklist/#cross-radio-lora-ota-acceptance","title":"Cross-radio LoRa OTA acceptance","text":"<ul> <li>[ ] Run a three-minute reachability preflight before staging or changing any       repeater radio settings.</li> <li>[ ] Test direct, fully controlled multi-hop, passive TempRadio hop, and mixed       controlled/passive paths independently.</li> <li>[ ] Record bytes, LoRa packets sent, packets confirmed, retries, useful       throughput, total elapsed time, and per-phase elapsed time.</li> <li>[ ] Confirm every controlled intermediate returns to its saved radio tuple.</li> <li>[ ] Verify target application and bootloader hashes after apply, not merely the       OTA tool's final status line.</li> <li>[ ] Exercise interruption/retry and confirm incomplete data cannot be approved       or booted.</li> </ul>"},{"location":"heltec_v4_wifi_partition_migration/","title":"Heltec V4 legacy-partition migration over Wi-Fi","text":"<p>Heltec V4/V4.3 OLED repeaters with their normal 16 MiB flash use the shared ESP32 Wi-Fi partition migration bridge. It changes Arduino's old <code>default.csv</code> layout, with two 1.25 MiB OTA slots, to <code>default_16MB.csv</code>, with two 6.25 MiB OTA slots.</p> <p>Build the bridge application image:</p> <pre><code>&amp; \"$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe\" run -e heltec_v4_partition_migrator\n</code></pre> <p>Upload <code>.pio/build/heltec_v4_partition_migrator/firmware.bin</code> through the legacy browser Wi-Fi updater. Rejoin <code>MeshCore-Migrate</code> with password <code>meshcore-migrate</code>; when it reports Expanded layout ready, upload the app-only Full V4 repeater image at <code>/update</code>.</p> <p>Do not use an <code>-merged.bin</code> in either browser uploader. Merged images contain bootloader and table offsets for cable flashing. The bridge preserves the private identity; other SPIFFS-backed settings may be recreated after the Full image starts.</p>"},{"location":"home_text_spacing/","title":"Home-screen text spacing","text":"<p>On non-Indicator companions, a visible Bluetooth PIN or connection status owns a separate bottom-aligned block. It replaces the ordinary inbox instruction, clock and WiFi rows while displayed. The PIN stays below the inbox title; the label and value use measured font heights, including the MeshPocket's larger e-paper font. An unusually short viewport may omit the label, never overlap the title or clip the PIN. Indicator's dedicated pairing layout is unchanged.</p> <p>The repeater home page also stacks measured font-height rows instead of fixed ten-pixel offsets. Long names and status lines are ellipsized horizontally.</p> <p>Run <code>python3 -m unittest discover -s test -p test_home_text_spacing.py -v</code> on a host with a C++ compiler. This renders the actual companion and repeater home branches, recording every text rectangle and rejecting overlaps or clipping. It covers 128x64 OLED, 160x80 T096, 250x122 MeshPocket and larger viewports, PIN/connected/disabled/prompt states, WiFi variants, long strings and a sweep of font heights. It also checks the static reader hint. The separate native display and T096 tests exercise the driver drawing/measurement methods.</p> <p>Hardware acceptance: check that the full six-digit PIN is near the bottom, with no text over it; connect/disconnect Bluetooth and verify no stale digits; then check the repeater's five rows and the V4's non-blinking reader footer.</p>"},{"location":"host_cli_service/","title":"LoRa CLI Host Service","text":"<p>The repeater <code>host &lt;text&gt;</code> command lets an authenticated LoRa administrator request a small, explicitly allowed operation from a USB-connected computer. The included Raspberry Pi endpoint supports these exact requests:</p> <pre><code>cmd host help\ncmd host cpu-temp\ncmd host hostname\ncmd host uptime\ncmd host load\ncmd host memory\ncmd host disk-free\ncmd host clock status\ncmd host clock sync\ncmd host clock set &lt;unix_epoch&gt;\ncmd host network restart\ncmd host reboot\ncmd host action status &lt;operation_id&gt;\ncmd host run &lt;alias&gt; [arguments]\n</code></pre> <p>The first seven actions after <code>help</code> are read-only. Clock changes, network restart, and reboot are opt-in actions and are disabled unless explicitly enabled. Text such as <code>reboot now</code>, <code>cpu-temp; reboot</code>, and embedded newlines is not a command: the endpoint accepts only an exact allowlist match.</p> <p>The bridge is included in normal repeater firmware except on Wio-E5. Its specialized RS232 bridge image omits the host service because the combined application exceeds the fixed 240 KiB partition; use the normal Wio-E5 repeater image when the USB/MQTT host service is needed.</p>"},{"location":"host_cli_service/#run-alongside-meshcoretomqtt","title":"Run alongside meshcoretomqtt","text":"<p><code>meshcoretomqtt</code> must remain the only process that opens the repeater USB serial port. The endpoint communicates with it through the same MQTT broker, which can be local to the Raspberry Pi:</p> <pre><code>LoRa -&gt; repeater -&gt; USB -&gt; meshcoretomqtt -&gt; MQTT -&gt; host endpoint\nLoRa &lt;- repeater &lt;- USB &lt;- meshcoretomqtt &lt;- MQTT &lt;- host endpoint\n</code></pre> <p>Clock-recovery deployments must run the loopback broker, <code>meshcoretomqtt</code>, and endpoint on the same Pi. A wrong Pi clock can prevent TLS validation against a remote broker, while split host clocks can reject the signed live claim before the correction arrives. Remote brokers remain suitable for ordinary commands when the connection and both clocks are already healthy.</p> <p>Launch <code>meshcoretomqtt</code> with its existing arguments plus <code>--debug</code>; its current debug-topic parser needs that flag to publish the repeater request record. Do not open the serial TTY from the host endpoint too.</p> <p>This feature does not compare the repeater wall clock with the Pi clock. Minutes of drift, an unset repeater clock, and later clock corrections are safe: request freshness comes from a live one-time challenge. The normal <code>meshcoretomqtt</code> <code>sync_time</code> setting may remain enabled for its other uses, but host-command authorization does not depend on it.</p> <p>Generate a dedicated service key using the Python environment installed by <code>meshcoretomqtt</code>:</p> <pre><code>sudo /opt/mctomqtt/venv/bin/python3 host_cli_service.py \\\n  --generate-key /etc/mctomqtt/host-cli-key.json\nsudo chown mctomqtt:mctomqtt /etc/mctomqtt/host-cli-key.json\nsudo chmod 600 /etc/mctomqtt/host-cli-key.json\n</code></pre> <p>Add the printed public key to the existing <code>meshcoretomqtt</code> configuration:</p> <pre><code>[remote_serial]\nenabled = true\nallowed_companions = [\n  \"SERVICE_PUBLIC_KEY_PRINTED_ABOVE\"\n]\nnonce_ttl = 120\ncommand_timeout = 10\n</code></pre> <p>Restart <code>meshcoretomqtt</code>, then run the endpoint. Replace <code>USA</code> with the exact three-character IATA namespace configured in the broker and supply the repeater's complete 64-character public key:</p> <pre><code>sudo -u mctomqtt /opt/mctomqtt/venv/bin/python3 host_cli_service.py \\\n  --broker 127.0.0.1 \\\n  --iata USA \\\n  --repeater-key REPEATER_PUBLIC_KEY \\\n  --service-key /etc/mctomqtt/host-cli-key.json\n</code></pre> <p>Add <code>--username NAME --password-file FILE</code> for broker authentication. Add <code>--tls</code>, and optionally <code>--ca-cert FILE</code>, for TLS. Custom installations can use <code>--request-topic</code> and <code>--command-topic</code> to match their broker namespace. The endpoint source and its systemd/configuration details are in <code>examples/host_cli_service</code>.</p>"},{"location":"host_cli_service/#allowlisted-programs-and-arguments","title":"Allowlisted programs and arguments","text":"<p>Add <code>--programs-file FILE</code> to expose locally selected programs as <code>host run &lt;alias&gt; [arguments]</code>. The example JSON file fixes each executable, fixed leading arguments, maximum 1-5 second runtime, and the exact remote argument schema. For example:</p> <pre><code>cmd host run fan on 15\n</code></pre> <p>The example maps that request to the fixed process argument vector:</p> <pre><code>/usr/local/bin/mesh-fan-control --source lora on 15\n</code></pre> <p>The supported argument rules are an explicit non-option <code>choice</code>, a bounded nonnegative <code>integer</code>, or a short <code>token</code> using a restricted ASCII character set. Alias lookup and every argument validation happen before process creation. Execution uses an absolute configured path, no stdin, <code>shell=False</code>, a minimal environment, and <code>/</code> as its working directory. Extra arguments, leading-option injection, shell syntax, control characters, and invalid quoting are rejected. The allowlist file and executable must not be group- or world-writable.</p> <p>Copy and edit <code>programs.example.json</code>, then give the service account only the operating-system permissions needed by those trusted programs.</p>"},{"location":"host_cli_service/#opt-in-network-and-reboot-recovery","title":"Opt-in network and reboot recovery","text":"<p>These actions use their own socket-activated root broker, independently of the clock-control broker. Installing or enabling clock control does not grant host recovery actions. Install the following as root-owned files:</p> <pre><code>sudo install -o root -g root -m 0755 meshcore_host_actions.py \\\n  /usr/local/sbin/meshcore-host-actions\nsudo install -o root -g root -m 0644 meshcore-host-actions.socket \\\n  /etc/systemd/system/meshcore-host-actions.socket\nsudo install -o root -g root -m 0644 meshcore-host-actions.service \\\n  /etc/systemd/system/meshcore-host-actions.service\nsudo install -o root -g root -m 0644 meshcore-networkmanager-restart.service \\\n  /etc/systemd/system/meshcore-networkmanager-restart.service\nsudo install -o root -g root -m 0644 meshcore-host-reboot.timer \\\n  /etc/systemd/system/meshcore-host-reboot.timer\nsudo install -o root -g root -m 0644 meshcore-host-reboot.service \\\n  /etc/systemd/system/meshcore-host-reboot.service\n</code></pre> <p>The root-owned broker policy enables nothing by default. Create a systemd drop-in and select <code>network-restart</code>, <code>reboot</code>, or both as an exact comma-separated list:</p> <pre><code>sudo systemctl edit meshcore-host-actions.service\n</code></pre> <pre><code>[Service]\nEnvironment=MESHCORE_HOST_ACTIONS=network-restart,reboot\n</code></pre> <p>Reload systemd and enable only the broker socket:</p> <pre><code>sudo systemctl daemon-reload\nsudo systemctl enable --now meshcore-host-actions.socket\n</code></pre> <p>After changing the policy on an already active installation, restart <code>meshcore-host-actions.service</code> so the broker reads the new value.</p> <p>Finally add <code>--allow-network-restart</code>, <code>--allow-reboot</code>, or both to the unprivileged endpoint. An action must pass both gates: the endpoint flag and the root-owned broker policy. The endpoint never invokes <code>sudo</code>; remove legacy <code>wifi-restart</code> program aliases and host-action sudoers entries because sudo aliases are not a fallback for this hardened service. Use the exact <code>host network restart</code> action instead.</p> <p>Systemd creates <code>/run/meshcore-host-actions.sock</code> as <code>root:mctomqtt</code> mode <code>0660</code>. The root broker authenticates both the endpoint UID and primary GID with <code>SO_PEERCRED</code>, while the endpoint authenticates the root-created listener. The protocol is one bounded ASCII line. Neither the caller nor request text can choose an executable, unit, path, or argument. The broker can start only the fixed static NetworkManager restart service or the fixed reboot timer; the broker and action units have empty capability sets and systemd sandboxing. The configured <code>mctomqtt</code> UID and its effective primary GID are the delegated local trust boundary; supplementary group membership alone is rejected.</p> <p>Side effects follow a fail-closed two-phase sequence. The endpoint reserves a canonical 128-bit operation ID with <code>PREPARE</code>, publishes its reply with MQTT QoS 1, and requires <code>wait_for_publish</code> plus <code>is_published</code> confirmation before sending one <code>COMMIT</code>. It does not block the Paho network callback while waiting. No confirmation means no commit. Reboot uses a fixed approximately 10-second timer that starts only after commit. The MQTT confirmation proves acceptance by the local broker, not delivery over USB and LoRa; there is no correlated serial delivery acknowledgement, so the physical reply is best effort.</p> <p><code>network restart</code> deliberately drops Wi-Fi and Tailscale management while NetworkManager restarts. Use a loopback MQTT broker and keep the broker, <code>meshcoretomqtt</code>, host endpoint, and USB device services independent of NetworkManager: they must not have <code>Requires=</code>, <code>BindsTo=</code>, or ordering dependencies on it. This preserves the local reply/commit path while remote management temporarily disappears.</p> <p>The operation ID is derived from the authenticated repeater key, request ID, and nonce. The reply displays it, and its state can be queried later:</p> <pre><code>cmd host action status 0123456789ABCDEF0123456789ABCDEF\n</code></pre> <p>The root broker retains at most 64 records for the current boot. It persists <code>prepared</code> before replying and <code>in-progress</code> before scheduling, schedules a committed operation at most once, and never automatically retries an ambiguous outcome. A broker restart converts recovered <code>in-progress</code> to <code>ambiguous</code>. Only an old uncommitted <code>prepared</code> record may be evicted; otherwise a full store rejects new work. Reusing an operation ID for a different action is rejected. <code>scheduled</code> means PID 1 accepted the fixed unit job; it does not claim that the subsequent network restart or reboot completed successfully.</p> <p>A distinct reboot is rejected while another reboot is committed or ambiguous, so a second request cannot falsely promise a fresh 10-second timer while the first timer is already running. A new reboot reservation may supersede only an older, uncommitted reboot reservation; the superseded operation can no longer be committed.</p>"},{"location":"host_cli_service/#opt-in-clock-recovery","title":"Opt-in clock recovery","text":"<p><code>clock status</code> reports the Pi epoch and NTP synchronization state without root access. To enable the exact <code>clock sync</code> and <code>clock set &lt;unix_epoch&gt;</code> actions, install <code>meshcore_clock_control.py</code> as <code>/usr/local/sbin/meshcore-clock-control</code>, owned by root and mode <code>0755</code>, then install the accompanying <code>meshcore-clock-control.socket</code> and <code>meshcore-clock-control.service</code> and static <code>meshcore-chrony-step.service</code> files in <code>/etc/systemd/system</code> as root-owned mode-<code>0644</code> files:</p> <pre><code>sudo install -o root -g root -m 0755 meshcore_clock_control.py \\\n  /usr/local/sbin/meshcore-clock-control\nsudo install -o root -g root -m 0644 meshcore-clock-control.socket \\\n  /etc/systemd/system/meshcore-clock-control.socket\nsudo install -o root -g root -m 0644 meshcore-clock-control.service \\\n  /etc/systemd/system/meshcore-clock-control.service\nsudo install -o root -g root -m 0644 meshcore-chrony-step.service \\\n  /etc/systemd/system/meshcore-chrony-step.service\nsudo systemctl daemon-reload\nsudo systemctl enable --now meshcore-clock-control.socket\n</code></pre> <p>The socket is fixed at <code>/run/meshcore-clock-control.sock</code>; systemd creates it as <code>root:mctomqtt</code> with mode <code>0660</code>. Run the endpoint as user and primary group <code>mctomqtt</code>, then add <code>--allow-clock-control</code>. The endpoint validates the socket metadata and authenticates the connected server as root with Linux <code>SO_PEERCRED</code>. The root service independently requires the peer's UID and primary GID to match <code>mctomqtt:mctomqtt</code> before it reads or executes a request. No clock-control sudo rule is used; remove old clock-helper sudoers lines when upgrading.</p> <p>Both layers require one canonical unsigned decimal argument with no sign, leading zero, whitespace, or trailing text. The accepted epoch range is 2020 through 2099. The private protocol accepts only the complete bounded ASCII lines <code>sync</code> and <code>set &lt;epoch&gt;</code>. Every child process uses a fixed absolute argv, <code>shell=False</code>, and a timeout no longer than 1.5 seconds.</p> <p><code>clock set</code> changes <code>CLOCK_REALTIME</code> without disabling NTP, then requests an NTP step. If the NTP request fails, the response honestly reports that the clock changed and which synchronization step remains incomplete. If <code>clock sync</code> enables NTP but the explicit step/restart fails, that partial outcome is also reported. When chrony is available, the root broker starts only the fixed static <code>meshcore-chrony-step.service</code>. That hardened one-shot runs <code>/usr/bin/chronyc -a makestep</code> as <code>_chrony:_chrony</code>, with no capabilities, <code>AF_UNIX</code> only, and a one-second start timeout; it can therefore reach chrony's private runtime socket without broadening the root broker. The <code>_chrony</code> account comes from the Debian/Raspberry Pi chrony package. Without chrony, the broker restarts systemd-timesyncd. Clock drift cannot authorize a captured command: the signed request still needs the repeater's live one-time claim, whose deadline is monotonic rather than wall-clock based.</p>"},{"location":"host_cli_service/#trust-and-injection-controls","title":"Trust and injection controls","text":"<p>The MQTT broker transports records but does not establish their authenticity. The endpoint checks the configured repeater identity and verifies its Ed25519 signature over the complete request ID, random nonce, and Base64URL request. It also validates framing, UTF-8, and byte limits. It does not execute that first record.</p> <p>Instead, the endpoint stores the request in memory, creates a random 64-bit challenge, and sends <code>@claim=&lt;random&gt;</code> through <code>meshcoretomqtt</code>'s signed serial channel. The repeater accepts it only from physical USB while the exact ID and nonce are pending, then signs a <code>CLAIMED</code> proof containing the challenge. Only a matching live proof lets the endpoint perform allowlist matching and execute the action. It consumes the proof before execution, so MQTT redelivery cannot execute an action twice.</p> <p>A captured request only causes a new challenge that an idle repeater refuses. A captured proof does not match a new challenge, and restarting the endpoint forgets pending challenges. Repeater/Pi clock drift therefore cannot turn an old <code>reboot</code> or <code>run</code> record into a valid action. The reply and claim commands still use short-lived JWTs; <code>meshcoretomqtt</code> checks their signer allowlist, target, expiration, signature, and separate replay nonce. Wall-clock expiry and its in-memory nonce cache are not sufficient across a backward clock jump plus restart; the firmware's live one-time claim is what protects these host actions. Keep recovery-mode <code>allowed_companions</code> limited to the dedicated service key, with the endpoint and <code>meshcoretomqtt</code> on the same Pi.</p> <p>Newlines and other reply control characters are converted to spaces and are also independently rejected by the firmware parser.</p> <p>Protect the service private key and use broker ACLs that allow it to subscribe only to the selected repeater debug topic and publish only to that repeater serial-command topic. A private key listed in <code>allowed_companions</code> is trusted to sign serial requests.</p>"},{"location":"host_cli_service/#limits","title":"Limits","text":"<ul> <li>The request is at most 155 UTF-8 bytes after <code>host</code>, or 152 bytes with the   legacy three-byte companion correlation prefix.</li> <li>The complete LoRa reply is at most 162 UTF-8 bytes.</li> <li>Only one host request can be pending per repeater.</li> <li>Only one privileged action or action-status query can be active; overlapping   work is rejected before reservation.</li> <li>The live claim must complete within 4 seconds. Allowlisted programs have a   configured 1-5 second child-process timeout. Privileged actions and status   queries share one 5-second broker/reply-confirmation deadline.</li> <li><code>host.reply</code> is accepted only through physical USB, not LoRa or Ethernet.</li> </ul> <p>Use <code>cmd get host</code> to report the bridge state and limits.</p>"},{"location":"kiss_modem_protocol/","title":"MeshCore KISS Modem Protocol","text":"<p>Standard KISS TNC firmware for MeshCore LoRa radios. Compatible with any KISS client (Direwolf, APRSdroid, YAAC, etc.) for sending and receiving raw packets. MeshCore-specific extensions (cryptography, radio configuration, telemetry) are available through the standard SetHardware (0x06) command.</p> <p>KISS protocol version 2 adds an opt-in logical port 1 for MeshCore's second time-shared LoRa profile. It is still one physical transceiver: the firmware fast-switches between <code>radio</code> and <code>radio2</code>; it does not create a second radio.</p>"},{"location":"kiss_modem_protocol/#serial-configuration","title":"Serial Configuration","text":"<p>115200 baud, 8N1, no flow control.</p>"},{"location":"kiss_modem_protocol/#frame-format","title":"Frame Format","text":"<p>Standard KISS framing per the KA9Q/K3MC specification.</p> Byte Name Description <code>0xC0</code> FEND Frame delimiter <code>0xDB</code> FESC Escape character <code>0xDC</code> TFEND Escaped FEND (FESC + TFEND = 0xC0) <code>0xDD</code> TFESC Escaped FESC (FESC + TFESC = 0xDB) <pre><code>+------+-----------+--------------+------+\n| FEND | Type Byte | Data (escaped)| FEND |\n| 0xC0 |  1 byte   | 0-510 bytes  | 0xC0 |\n+------+-----------+--------------+------+\n</code></pre>"},{"location":"kiss_modem_protocol/#type-byte","title":"Type Byte","text":"<p>The type byte is split into two nibbles:</p> Bits Field Description 7-4 Port <code>0</code> primary <code>radio</code>; <code>1</code> secondary <code>radio2</code> for Data only in protocol v2; controls stay on port 0 3-0 Command Command number <p>Maximum unescaped frame size: 512 bytes.</p>"},{"location":"kiss_modem_protocol/#standard-kiss-commands","title":"Standard KISS Commands","text":""},{"location":"kiss_modem_protocol/#host-to-tnc","title":"Host to TNC","text":"Command Value Data Description Data <code>0x00</code> Raw packet Queue on primary <code>radio</code>; use type <code>0x10</code> to queue on <code>radio2</code> in v2 (one pending packet total) TXDELAY <code>0x01</code> Delay (1 byte) Transmitter keyup delay in 10ms units (default: 50 = 500ms) Persistence <code>0x02</code> P (1 byte) CSMA persistence parameter 0-255 (default: 63) SlotTime <code>0x03</code> Interval (1 byte) CSMA slot interval in 10ms units (default: 10 = 100ms) TXtail <code>0x04</code> Delay (1 byte) Post-TX hold time in 10ms units (default: 0) FullDuplex <code>0x05</code> Mode (1 byte) 0 = half duplex, nonzero = full duplex (default: 0) SetHardware <code>0x06</code> Sub-command + data MeshCore extensions (see below) Return <code>0xFF</code> - Exit KISS mode (no-op)"},{"location":"kiss_modem_protocol/#tnc-to-host","title":"TNC to Host","text":"Type Value Data Description Data <code>0x00</code> Raw packet Received packet from primary <code>radio</code> Data <code>0x10</code> Raw packet Received packet from secondary <code>radio2</code> (v2) <p>Data frames carry raw packet data only, with no metadata prepended. The Data command payload is limited to 255 bytes to match the MeshCore maximum transmission unit (MAX_TRANS_UNIT); frames larger than 255 bytes are silently dropped. The KISS specification recommends at least 1024 bytes for general-purpose TNCs; this modem is intended for MeshCore packets only, whose protocol MTU is 255 bytes. A v2 port-1 Data packet reaches RF only while <code>radio2</code> is configured <code>rxtx</code>; with <code>off</code> or <code>rx</code>, the modem returns <code>TxDone(0)</code> and never falls back to primary.</p> <p>Only one packet may be pending for radio transmission at a time. If the host sends a second Data frame before the first has completed, the modem responds with Error (0xF1) and TxBusy (0x07).</p>"},{"location":"kiss_modem_protocol/#fast-dual-profile-receive-switching","title":"Fast dual-profile receive switching","text":"<p>After OpenHop (or another KISS client) configures <code>radio2</code> or <code>tempradio2</code>, the board's <code>radio_driver.loop()</code> performs the RF hops locally. KISS does not send a command for every hop: that would be slower than the serial link alone. The shared scanner uses a 600 \u00b5s nominal retune allowance per hop, with the profile timing/preamble calculation accounting for it. It is a measured target rather than a hard maximum; packet handling and a slow board loop can extend an individual hop. The KISS parser services at most 32 incoming bytes per outer loop so a busy OpenHop serial peer cannot starve the scanner.</p> <p>Thus \u201caround 0.6 ms\u201d refers to the on-board RF setting transition, not a full host-to-board request/response round trip. The returned Data port (<code>0x00</code> or <code>0x10</code>) identifies which profile actually received each packet.</p> <p><code>SetRadio2</code> and <code>SetTempRadio2</code> acknowledge that their tuple was accepted and scheduled; they do not acknowledge that a receiver has already entered that tuple. The next local scanner service performs the retune. KISS clients should configure the profiles once and let the board perform automatic time-sharing; a 115200-baud serial round trip cannot be a 0.6 ms receive-hop control plane. Clients that need temporary-lease state can poll <code>GetTempRadio2</code>.</p>"},{"location":"kiss_modem_protocol/#host-output-backpressure","title":"Host Output Backpressure","text":"<p>Outbound frames are encoded into a 2-slot queue and flushed when serial output space is available; <code>loop()</code> never blocks on writes. Radio TX state advances independently of host read speed. TxDone is retained until it can be queued. If the outbound queue is full, the modem responds with Error (0xF1) and TxBusy (0x07). Hosts should read serial promptly to avoid delayed responses.</p>"},{"location":"kiss_modem_protocol/#csma-behavior","title":"CSMA Behavior","text":"<p>The TNC implements p-persistent CSMA for half-duplex operation:</p> <ol> <li>When a packet is queued, monitor carrier detect</li> <li>When the channel clears, generate a random value 0-255</li> <li>If the value is less than or equal to P (Persistence), wait TXDELAY then transmit</li> <li>Otherwise, wait SlotTime and repeat from step 1</li> </ol> <p>In full-duplex mode, CSMA is bypassed and packets transmit after TXDELAY.</p>"},{"location":"kiss_modem_protocol/#sethardware-extensions-0x06","title":"SetHardware Extensions (0x06)","text":"<p>MeshCore-specific functionality uses the standard KISS SetHardware command. The first byte of SetHardware data is a sub-command. Standard KISS clients ignore these frames.</p>"},{"location":"kiss_modem_protocol/#frame-format_1","title":"Frame Format","text":"<pre><code>+------+------+-------------+--------------+------+\n| FEND | 0x06 | Sub-command | Data (escaped)| FEND |\n| 0xC0 |      |   1 byte    |   variable   | 0xC0 |\n+------+------+-------------+--------------+------+\n</code></pre>"},{"location":"kiss_modem_protocol/#request-sub-commands-host-to-tnc","title":"Request Sub-commands (Host to TNC)","text":"Sub-command Value Data GetIdentity <code>0x01</code> - GetRandom <code>0x02</code> Length (1 byte, 1-64) VerifySignature <code>0x03</code> PubKey (32) + Signature (64) + Data SignData <code>0x04</code> Data to sign EncryptData <code>0x05</code> Key (32) + Plaintext DecryptData <code>0x06</code> Key (32) + MAC (2) + Ciphertext KeyExchange <code>0x07</code> Remote PubKey (32) Hash <code>0x08</code> Data to hash SetRadio <code>0x09</code> Freq (4) + BW (4) + SF (1) + CR (1) SetTxPower <code>0x0A</code> Power dBm (1) GetRadio <code>0x0B</code> - GetTxPower <code>0x0C</code> - GetCurrentRssi <code>0x0D</code> - IsChannelBusy <code>0x0E</code> - GetAirtime <code>0x0F</code> Packet length (1) GetNoiseFloor <code>0x10</code> - GetVersion <code>0x11</code> - GetStats <code>0x12</code> - GetBattery <code>0x13</code> - GetMCUTemp <code>0x14</code> - GetSensors <code>0x15</code> Permissions (1) GetDeviceName <code>0x16</code> - Ping <code>0x17</code> - Reboot <code>0x18</code> - SetSignalReport <code>0x19</code> Enable (1): 0x00=disable, nonzero=enable GetSignalReport <code>0x1A</code> - SetRadio2 <code>0x1B</code> Radio2 parameters (13; see below) GetRadio2 <code>0x1C</code> - SetTempRadio2 <code>0x1D</code> Radio2 parameters + duration (15) GetTempRadio2 <code>0x1E</code> -"},{"location":"kiss_modem_protocol/#response-sub-commands-tnc-to-host","title":"Response Sub-commands (TNC to Host)","text":"<p>Response codes use the high-bit convention: <code>response = command | 0x80</code>. Generic and unsolicited responses use the <code>0xF0</code>+ range.</p> Sub-command Value Data Identity <code>0x81</code> PubKey (32) Random <code>0x82</code> Random bytes (1-64) Verify <code>0x83</code> Result (1): 0x00=invalid, 0x01=valid Signature <code>0x84</code> Signature (64) Encrypted <code>0x85</code> MAC (2) + Ciphertext Decrypted <code>0x86</code> Plaintext SharedSecret <code>0x87</code> Shared secret (32) Hash <code>0x88</code> SHA-256 hash (32) Radio <code>0x8B</code> Freq (4) + BW (4) + SF (1) + CR (1) TxPower <code>0x8C</code> Power dBm (1) CurrentRssi <code>0x8D</code> RSSI dBm (1, signed) ChannelBusy <code>0x8E</code> Result (1): 0x00=clear, 0x01=busy Airtime <code>0x8F</code> Milliseconds (4) NoiseFloor <code>0x90</code> dBm (2, signed) Version <code>0x91</code> Version (1) + Reserved (1) Stats <code>0x92</code> RX (4) + TX (4) + Errors (4) Battery <code>0x93</code> Millivolts (2) MCUTemp <code>0x94</code> Temperature (2, signed) Sensors <code>0x95</code> CayenneLPP payload DeviceName <code>0x96</code> Name (variable, UTF-8) Pong <code>0x97</code> - SignalReport <code>0x9A</code> Status (1): 0x00=disabled, 0x01=enabled Radio2 <code>0x9C</code> Saved radio2 parameters (13) TempRadio2 <code>0x9E</code> Active temporary radio2 + remaining minutes (15) OK <code>0xF0</code> - Error <code>0xF1</code> Error code (1) TxDone <code>0xF8</code> Result (1): 0x00=failed, 0x01=success RxMeta <code>0xF9</code> SNR (1) + RSSI (1)"},{"location":"kiss_modem_protocol/#error-codes","title":"Error Codes","text":"Code Value Description InvalidLength <code>0x01</code> Request data too short InvalidParam <code>0x02</code> Invalid parameter value NoCallback <code>0x03</code> Feature not available MacFailed <code>0x04</code> MAC verification failed UnknownCmd <code>0x05</code> Unknown sub-command EncryptFailed <code>0x06</code> Encryption failed TxBusy <code>0x07</code> Radio TX busy, or host output queue full"},{"location":"kiss_modem_protocol/#unsolicited-events","title":"Unsolicited Events","text":"<p>The TNC sends these SetHardware frames without a preceding request:</p> <p>TxDone (0xF8): Sent after radio transmission completes. Contains a single byte: 0x01 for success, 0x00 for failure. Delivery to the host may be delayed under serial backpressure but is not dropped.</p> <p>RxMeta (0xF9): Sent after each Data frame (type 0x00 or v2 type 0x10) with SNR (1 byte, signed, value x4) and RSSI (1 byte, signed, dBm). It remains exactly two bytes; the Data port identifies the receiving profile. Queued with the data frame; omitted if the data frame cannot be queued. Enabled by default; toggle with SetSignalReport. Standard KISS clients ignore this frame.</p>"},{"location":"kiss_modem_protocol/#data-formats","title":"Data Formats","text":""},{"location":"kiss_modem_protocol/#radio-parameters-setradio-radio-response","title":"Radio Parameters (SetRadio / Radio response)","text":"<p>All values little-endian.</p> Field Size Description Frequency 4 bytes Hz (e.g., 869618000) Bandwidth 4 bytes Hz (e.g., 62500) SF 1 byte Spreading factor (5-12) CR 1 byte Coding rate (5-8)"},{"location":"kiss_modem_protocol/#secondary-radio-parameters-setradio2-radio2-response","title":"Secondary Radio Parameters (SetRadio2 / Radio2 response)","text":"<p><code>SetRadio2</code> is the binary KISS equivalent of <code>radio2</code>. It changes only RAM state for this KISS session; it does not write the Mesh CLI profile file. All values are little-endian. The mode values are <code>0=off</code>, <code>1=rx</code>, and <code>2=rxtx</code>. An <code>off</code> tuple may contain zero radio parameters, which are ignored.</p> Field Size Description Frequency 4 bytes Hz Bandwidth 4 bytes Hz SF 1 byte Spreading factor (5-12) CR 1 byte Coding rate (5-8) Mode 1 byte <code>off</code>, <code>rx</code>, or <code>rxtx</code> as above Preamble 2 bytes Symbols; <code>0</code> chooses automatic <p><code>GetRadio2</code> returns this exact 13-byte tuple. The modem preserves the exact frequency and bandwidth values sent by the host even though its radio driver uses floating-point MHz/kHz internally.</p>"},{"location":"kiss_modem_protocol/#temporary-secondary-radio-settempradio2-tempradio2-response","title":"Temporary Secondary Radio (SetTempRadio2 / TempRadio2 response)","text":"<p><code>SetTempRadio2</code> is the binary KISS equivalent of <code>tempradio2</code>: the 13-byte secondary tuple followed by <code>duration_minutes:u16</code>, from 1 to 10080. It is RAM-only and automatically restores the saved <code>radio2</code> tuple on expiry or reboot. A mode <code>off</code> with duration zero cancels the temporary lease and immediately restores saved <code>radio2</code>; all other <code>off</code>/zero-duration combinations are invalid. <code>GetTempRadio2</code> returns the active 13-byte tuple plus remaining minutes, rounded up. It returns a zero/off tuple with zero duration when no temporary lease is active.</p> <p>Changing saved <code>radio2</code> during an active temporary lease does not interrupt the active tuple; the replacement becomes active when the lease ends. Pending KISS Data is bound to a profile generation at queue time. If that profile is replaced before RF transmission begins, the modem sends normal <code>TxDone(0)</code> and never falls back to the other profile.</p>"},{"location":"kiss_modem_protocol/#version-version-response","title":"Version (Version response)","text":"Field Size Description Version 1 byte Firmware version Reserved 1 byte Always 0"},{"location":"kiss_modem_protocol/#encrypted-encrypted-response","title":"Encrypted (Encrypted response)","text":"Field Size Description MAC 2 bytes HMAC-SHA256 truncated to 2 bytes Ciphertext variable AES-128 block-encrypted data with zero padding"},{"location":"kiss_modem_protocol/#airtime-airtime-response","title":"Airtime (Airtime response)","text":"<p>All values little-endian.</p> Field Size Description Airtime 4 bytes uint32_t, estimated air time in milliseconds"},{"location":"kiss_modem_protocol/#noise-floor-noisefloor-response","title":"Noise Floor (NoiseFloor response)","text":"<p>All values little-endian.</p> Field Size Description Noise floor 2 bytes int16_t, dBm (signed) <p>The modem recalibrates the noise floor every 2 seconds with an AGC reset every 30 seconds.</p>"},{"location":"kiss_modem_protocol/#stats-stats-response","title":"Stats (Stats response)","text":"<p>All values little-endian.</p> Field Size Description RX 4 bytes Packets received TX 4 bytes Packets transmitted Errors 4 bytes Receive errors"},{"location":"kiss_modem_protocol/#battery-battery-response","title":"Battery (Battery response)","text":"<p>All values little-endian.</p> Field Size Description Millivolts 2 bytes uint16_t, battery voltage in mV"},{"location":"kiss_modem_protocol/#mcu-temperature-mcutemp-response","title":"MCU Temperature (MCUTemp response)","text":"<p>All values little-endian.</p> Field Size Description Temperature 2 bytes int16_t, tenths of degC (e.g., 253 = 25.3degC) <p>Returns <code>NoCallback</code> error if the board does not support temperature readings.</p>"},{"location":"kiss_modem_protocol/#device-name-devicename-response","title":"Device Name (DeviceName response)","text":"Field Size Description Name variable UTF-8 string, no null terminator"},{"location":"kiss_modem_protocol/#reboot","title":"Reboot","text":"<p>Sends an <code>OK</code> response, flushes serial, then reboots the device. The host should expect the connection to drop.</p>"},{"location":"kiss_modem_protocol/#sensor-permissions-getsensors","title":"Sensor Permissions (GetSensors)","text":"Bit Value Description 0 <code>0x01</code> Base (battery) 1 <code>0x02</code> Location (GPS) 2 <code>0x04</code> Environment (temp, humidity, pressure) <p>Use <code>0x07</code> for all permissions.</p>"},{"location":"kiss_modem_protocol/#sensor-data-sensors-response","title":"Sensor Data (Sensors response)","text":"<p>Data returned in CayenneLPP format. See CayenneLPP documentation for parsing.</p>"},{"location":"kiss_modem_protocol/#cryptographic-algorithms","title":"Cryptographic Algorithms","text":"Operation Algorithm Identity / Signing / Verification Ed25519 Key Exchange X25519 (ECDH) Encryption AES-128 block encryption with zero padding + HMAC-SHA256 (MAC truncated to 2 bytes) Hashing SHA-256"},{"location":"kiss_modem_protocol/#notes","title":"Notes","text":"<ul> <li>Data payload limit (255 bytes) matches MeshCore MAX_TRANS_UNIT; no change needed for KISS \"1024+ recommended\" (that applies to general TNCs, not MeshCore)</li> <li>Modem generates identity on first boot (stored in flash)</li> <li>All multi-byte values are little-endian unless stated otherwise</li> <li>SNR values in RxMeta are multiplied by 4 for 0.25 dB precision</li> <li>TxDone is sent as a SetHardware event after each transmission</li> <li>Legacy KISS clients use only type 0x00 data and remain compatible. Version-2-aware clients can use type 0x10 to send on, or identify reception from, <code>radio2</code>.</li> <li>Standard KISS clients can safely ignore all SetHardware (0x06) frames</li> <li>See packet_format.md for packet format</li> </ul>"},{"location":"lora_ota_automation/","title":"Scripted LoRa OTA from start to finish","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>The dedicated RAK3401 chain report records the physical failures of withdrawn migrations and the physically qualified compact nine-step replacement. Its runner blocks the withdrawn chains and pins every accepted bridge image by SHA-256.</p> <p><code>tools/lora_ota/lora_ota.sh</code> and <code>tools/lora_ota/lora_ota.ps1</code> automate a MeshCore LoRa firmware update from a release <code>.zip</code> or ready <code>.mota</code>. They identify the destination, validate the hardware and running firmware, prepare the right container, move the participating nodes to a temporary radio channel, serve and monitor the download, request installation, restore the controller, and check the rebooted node.</p> <p>The script cannot install the destination's first OTA-capable firmware. It can stage signed v3 bootloader containers with <code>--no-install</code>, but never sends the privileged bootloader install command. Invalid v2 containers carrying the bootloader flag remain rejected. Do the first nRF52 bootloader installation over USB. An already-capable, explicitly supported internal-flash, XIAO QSPI, or exact MeshTower V2 microSD repeater may later use the separate manual <code>ota bootloader install</code> workflow.</p>"},{"location":"lora_ota_automation/#required-topology","title":"Required topology","text":"<p>The reliable serial topology uses two local radios:</p> <pre><code>                                      authenticated admin commands\ncomputer -- MeshCore binary API --&gt; controller Companion -------------------+\n   |                                                                         |\n   +-- raw text CLI + mOTA seeder --&gt; OTA source ---- LoRa OTA blocks ----&gt; target\n                                                        |                    ^\n                                                        +-- relay(s) --------+\n</code></pre> <ul> <li>Controller: a Companion connected through serial, TCP, or BLE. The   script uses <code>meshcli</code> to send remote admin commands to the target and changes   the controller's live radio parameters during the transfer. A serial   Companion stays in its normal Binary USB mode at 115200 baud.</li> <li>OTA source: an OTA-enabled repeater/FULL node whose USB port is a raw   text CLI, an ESP32 <code>companion_radio_full</code> using WiFi ports 5001 and 5002, or   an nRF52 <code>companion_radio_full</code> whose USB port switches between Binary,   terminal control, and exclusive mOTA seeding.</li> <li>Target: an OTA-enabled ESP32 or nRF52 node present in the controller's   contact list. Its admin password is required.</li> <li>Relays: optional. They do not need to install OTA themselves, but every   relay on the path must be running current firmware and have an overlapping   TempRadio window.</li> </ul> <p>One serial port cannot serve both controller roles: <code>meshcli</code> must keep reopening the controller while <code>motatool</code> owns the source port. The script rejects an attempt to use the same port for both.</p> <p>The USB ASCII switch (<code>+++MESHCORE-TERM-START</code>) is the local control path, not the mOTA data framing. On an nRF52 dual-CDC Full Companion, the script uses that mode briefly for <code>ota status</code> and TempRadio commands. It then closes the CLI and starts <code>motatool</code>; the exact <code>ota folder on</code> preamble switches the same USB interface <code>00</code> into exclusive mOTA mode from either startup ASCII or Binary Companion mode. If USB logging was enabled and the Full Companion rebooted, its separate interface <code>02</code> continues to provide plaintext logging and is not a controller or source port. With default logging off, interface <code>02</code> is not enumerated. BLE remains available.</p> <p>ESP32 Full Companion normally uses its dedicated TCP seeder on port 5001. ESP32 builds that also retain serial folder support use the same exclusive USB mOTA ownership state as nRF52. The exact <code>ota folder on</code> line transfers the USB port from startup ASCII or idle Binary Companion mode before binary mOTA frames begin; neither console mode shares that port until the folder detaches.</p>"},{"location":"lora_ota_automation/#bootloader-packages-and-station-identifiers","title":"Bootloader packages and station identifiers","text":"<p>Both wrappers use the same package-aware runner. It identifies application versus bootloader updates from container metadata, not filenames. A ZIP mixing application inputs and bootloader mOTAs requires <code>--zip-member</code>; their versions and target IDs are independent and must not be ranked together.</p> <p>Signed format-3 nRF52 bootloader packages can be staged with <code>--no-install</code>. Use the same controller/source/TempRadio arguments as an application transfer, but provide the bootloader <code>.mota</code> (or its ZIP member) and <code>--no-install</code>. Without that flag, even <code>--yes</code> stops before opening a radio. Bootloader staging requires Python <code>cryptography</code> in the interpreter running the wrapper and a current <code>motatool</code> supporting format 3. The runner reuses <code>tools/mota/motalib.py</code> for strict geometry, embedded identity/CRC, capability, hash and signature validation, and still runs <code>motatool verify</code> including any <code>--public-key</code> pin.</p> <p>If Python cannot load <code>cryptography</code>, an interactive run offers:</p> <pre><code>Install cryptography privately and retry signature verification? [y/N]\n</code></pre> <p>After approval, it uses the exact running Python interpreter to install <code>cryptography==50.0.1</code> and its dependencies from PyPI into a separate per-user, per-interpreter cache. Binary wheels only are accepted; the repair does not compile native code, overwrite system/virtual-environment packages, change PATH, use <code>sudo</code>, or bypass externally-managed Python protections. It checks Ed25519 against a known valid signature and a tampered message, then retries the original full package verification. A later run can reuse a working cache without another download. This works for direct <code>.mota</code> files and bootloader members inside ZIPs; ordinary application updates and raw <code>--tcp-cli</code> commands do not need this library.</p> <p>The interpreter must have working pip. If pip is missing, the script gives an exact-interpreter <code>ensurepip</code> command and operating-system pip/venv guidance; it does not silently install system tools. No compatible binary wheel, an old pip, network/download failures, an unwritable cache, or a failed signature check stop the run before radio access. Pip output is shown and installation is bounded at ten minutes. The radio admin-password environment variable is not passed to pip. Partial installation files may remain in the displayed private directory. The cache is under <code>meshcore-lora-ota/python/&lt;interpreter-id&gt;/cryptography==50.0.1</code> in the same per-user cache base described below for <code>motatool</code>.</p> <p>Only <code>y</code> or <code>yes</code> approves this repair; <code>--yes</code> is not installation consent. Noninteractive runs print a copyable private-install command and stop. After running that command manually, rerun the original OTA command; no Python path changes are needed. Declining never skips signature verification.</p> <p>It probes actual <code>motatool inspect</code> support before radio access: older and newer builds may advertise the same version. If the tool is missing or incompatible, an interactive run offers an automatic repair:</p> <pre><code>Install this bootloader-capable motatool and continue after verification? [y/N]\n</code></pre> <p>Only <code>y</code> or <code>yes</code> approves installation. <code>--yes</code> does not approve host software installation. Noninteractive runs stop and print a copyable manual installation command plus the <code>--motatool</code> argument to use afterward.</p> <p>The motatool repair builds the mikecarper/motatool fork at pinned revision <code>8c38369e7d35ad50cf74261869676d52dd24adf7</code>, with Cargo's <code>--locked</code> dependencies, in a separate per-user cache directory. It needs matching stable Cargo and rustc 1.86.0 or newer and a native linker already installed; otherwise it points to Rust installation and stops without installing anything. The pinned dependency set needs more than the older <code>rust-version</code> in motatool's own manifest: <code>zeroize 1.9.0</code> needs edition 2024, and ICU/idna dependencies need Rust 1.86. Cargo 1.75 is a version problem, not a root-permission problem; no nightly toolchain is necessary.</p> <p>Before asking to build or downloading crates, the runner checks both executable versions. It keeps a compatible default pair; otherwise it looks for versioned executables on PATH (such as Ubuntu's <code>cargo-1.91</code> and <code>rustc-1.91</code>) and already installed stable rustup toolchains. It displays the selected paths and pins both for the build process, so a newer Cargo cannot silently invoke an old rustc. Rustup proxies are resolved to their actual toolchain binaries before changing to the build directory. No default toolchain, symlink, system PATH, or package installation is changed, and probes disable rustup's automatic toolchain install. Tool version probes have ten-second timeouts. A working cached motatool does not need Cargo or Rust checks at all.</p> <p>To choose a pair explicitly, append:</p> <pre><code>--cargo cargo-1.91 --rustc rustc-1.91\n</code></pre> <p>These options also accept executable paths, not shell aliases or a command with embedded arguments. Explicit selections and <code>RUSTC</code>/<code>CARGO_BUILD_RUSTC</code> compiler overrides are honored; if incompatible, they fail instead of silently selecting another compiler. <code>--rustc</code> takes precedence over those environment variables. The manual build command includes the chosen compiler as well as Cargo. Native linker, SDK, and system-library availability are still checked by the real build; a passed version check is not a guarantee that every host prerequisite is present. Source/dependency downloads, build time and disk use are disclosed before confirmation. Cargo progress is displayed, with a one-hour build timeout. The radio admin-password environment variable is not passed to the build.</p> <p>The installer does not overwrite the selected/system <code>motatool</code> or alter PATH. It may replace only a previous copy in its displayed private install directory. After installation it repeats the bootloader-package capability check and uses the new binary for this run only if that check passes. A later run using the default <code>motatool</code> selection can reuse the checked cache without downloading again; switching from an explicit <code>--motatool</code> path still asks permission. Refusal, a failed build, or a failed recheck stops before opening any radio. Failed build files may remain in the displayed cache directory for diagnostics.</p> <p>The install root is <code>meshcore-lora-ota/motatool/&lt;revision&gt;</code> under <code>%LOCALAPPDATA%</code> on Windows, <code>~/Library/Caches</code> on macOS, or <code>$XDG_CACHE_HOME</code> (default <code>~/.cache</code>) on Linux. Cargo uses an explicit <code>--root</code>, <code>--rev</code>, and <code>--locked</code> instead of replacing a global installation or following a moving branch.</p> <p>Before transfer it queries the destination's <code>ota bootloader status</code>, checks its bootloader-specific target/hardware identity, installed ABI/codecs and matching internal/QSPI/SD storage profile. It does not compare an application version or application target ID to a bootloader package. After transfer it checks the destination's exact staged MID and image-hash confirmation, then prints the manual command; it never sends a bootloader install command:</p> <pre><code>ota bootloader status\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Review and send those commands on the destination, not the source. The device independently enforces signer authorization, safe live storage, continuity and upgrade-only policy at installation. <code>--base</code>, <code>--allow-non-upgrade</code>, and <code>--prepare-only</code> remain application-only. See the bootloader prerequisites and recovery limits.</p> <p><code>TARGET_NODE</code>, <code>--relay</code>, and <code>--source-contact</code> accept a contact name, full public key, or unique hexadecimal key prefix. The runner reads the controller's existing contact table and binds each selection to a full key before remote commands, so emoji names need not be typed and later name changes cannot redirect the run. Duplicate names, ambiguous prefixes, or the same radio under different participant aliases stop with an actionable error. Missing destination and relay contacts must first be imported or discovered. A missing connected source can be imported with the confirmation prompt below; a key alone does not create a contact.</p> <p>For a separate source with a managed USB/TCP console, automatic source selection reads the physical source's full public key and matches it in the controller's contacts. Repeaters use <code>get public.key</code>. Full Companion does not implement that repeater command: on both USB and TCP, its key is read from a fresh terminal welcome banner, with a supported <code>ver</code> reply on the same connection proving the terminal is live. USB briefly uses the existing STOP/START/STOP terminal wrapper to obtain that banner, even for an ASCII-first Full Companion; TCP reads the greeting from a new connection. Identity rechecks repeat this exchange rather than trusting a key cached from an earlier connection.</p> <p><code>ota status</code> identifies the Full Companion seeder role before this probe. For unrecognized firmware, only an explicit unsupported <code>get public.key</code> response can trigger the Companion fallback. Timeouts, permission errors, malformed keys, missing/ambiguous banners, and failed <code>ver</code> replies still stop the run. Firmware that exposes neither identity mechanism needs a supported terminal firmware; the runner does not guess a key from the node name or skip the identity check.</p> <p>Source selection does not require the source's current name to match an old saved advert, and duplicate/emoji names cannot redirect this lookup. An explicit <code>--source-contact</code> must identify that same physical source. If its key is missing, an interactive run offers:</p> <pre><code>Add the connected OTA source to this controller's contacts? [y/N]\n</code></pre> <p>This works through both the shell and PowerShell launchers. The runner reads the source's existing <code>card</code> command over USB/TCP, checks the full key in its contact card against the connected source, and shows its name/key before asking. On approval it rechecks the source/controller identities and live contact table, then uses MeshCore's existing <code>import_contact</code> API. Signature validation remains with the controller's normal advert importer. For manual-add controllers it can approve only that exact source through <code>add_pending</code>; it does not enable general auto-add. A fresh <code>reload_contacts</code> must confirm the full source key before OTA continues. No LoRa advertisement or firmware update is required for this import.</p> <p>The default answer is No; <code>--yes</code> does not approve adding a contact. A noninteractive run stops with instructions to rerun in a terminal. Unsupported <code>card</code> firmware, malformed/mismatched cards, and unverified imports stop with manual-import/discovery guidance. To protect existing contacts, the controller's overwrite-oldest policy must be verifiably disabled; otherwise the runner stops and shows how to disable that bit without changing other auto-add flags. It does not change this policy itself. A full table or rejected import cannot be worked around by deleting another contact; an uncertain import is not automatically retried. An approved contact remains on the controller for subsequent runs.</p> <p>The normal/TempRadio on-air ACK checks still run; adding a contact does not prove radio reachability or skip those checks. When the controller and source are the same TCP Full Companion, use the verified <code>--source-shares-controller</code> topology; it does not need a contact for itself.</p>"},{"location":"lora_ota_automation/#destination-requirements","title":"Destination requirements","text":"Destination Package installed One-time prerequisite Raw ZIP handling ESP32 Full application image OTA-enabled image with an A/B partition table Builds a full mOTA from the matching non-merged application <code>.bin</code> nRF52, internal flash In-place delta Exact-board OTAFIX bootloader with mOTA apply support Requires <code>--base</code> with the exact image currently running nRF52 repeater, external QSPI Full image or in-place delta QSPI-aware exact-board OTAFIX bootloader and matched repeater build Builds a full mOTA; adding <code>--base</code> requests a delta MeshTower V2 nRF52, microSD Full image or in-place delta SD-aware exact-board OTAFIX bootloader and compatible card Builds a full mOTA; adding <code>--base</code> requests a delta <p>MeshTower V2 microSD application and bootloader containers require an Ed25519 signature from a key in the device allowlist. Supply <code>--sign-key</code> when the runner must build a container, and install the BLM2-capable SD-aware bootloader locally before attempting application or bootloader OTA. Preview.12 requires USB/BLE DFU or SWD; see MeshTower V2 microSD LoRa OTA.</p> <p>The firmware inside a raw ZIP must have a valid MeshCore <code>EndF</code> trailer. An ESP32 merged/factory image is not an application image and is rejected. A generic vendor DFU ZIP may also be unusable if it does not contain the raw EndF-bearing <code>.hex</code> or <code>.bin</code>.</p> <p>For an internal-staging nRF52, the exact base image is irreducible information. The node reports its eight-byte body hash, but that hash cannot reconstruct the firmware bytes needed to create a delta. Keep the <code>.pio/build/ENV/firmware.hex</code> that was actually flashed. A matching filename or version alone is not enough.</p>"},{"location":"lora_ota_automation/#1-install-the-host-tools","title":"1. Install the host tools","text":"<p>Install Python 3.10 or newer, Rust, Git, the official <code>meshcore-cli</code> 1.6.0 or newer, and the official <code>motatool</code>.</p> <p>For signed bootloader staging, see the automatic <code>cryptography</code> and bootloader-capable <code>motatool</code> repairs above. Pip is needed only when installing the missing Python dependency; Rust/Cargo and a native linker are needed only when building motatool, not when using an already compatible binary. The runner checks the selected meshcli version before opening radios. Keep its serial/BLE dependencies in meshcli's own environment (pipx handles these); installing cryptography in meshcli's pipx environment does not make it available to the separate Python interpreter running this wrapper. A ready bootloader <code>.mota</code> does not need the Python <code>detools</code> or <code>intelhex</code> build dependencies.</p> <p>On Bash:</p> <pre><code>python3 -m pip install --user pipx\npython3 -m pipx ensurepath\npipx install meshcore-cli\n\ngit clone https://github.com/vk496/motatool.git\ncargo install --path ./motatool\n\nmeshcli -v\nmotatool --version\n</code></pre> <p>On PowerShell:</p> <pre><code>py -m pip install --user pipx\npy -m pipx ensurepath\npipx install meshcore-cli\n\ngit clone https://github.com/vk496/motatool.git\ncargo install --path .\\motatool\n\nmeshcli -v\nmotatool --version\n</code></pre> <p>Restart the shell if <code>pipx</code> or Cargo reports that it changed <code>PATH</code>.</p>"},{"location":"lora_ota_automation/#2-identify-and-test-both-local-links","title":"2. Identify and test both local links","text":"<p>List serial devices:</p> <pre><code>meshcli -l\n</code></pre> <p>The examples below assume <code>/dev/ttyACM0</code> is the controller and <code>/dev/ttyACM1</code> is the OTA source. On Windows they might be <code>COM7</code> and <code>COM8</code>. Close picocom, a serial monitor, the phone app, and any other program holding either link.</p> <p>Test the controller's binary API:</p> <pre><code>meshcli -s /dev/ttyACM0 -b 115200 ver\n</code></pre> <p>For an ordinary raw-text source, test its OTA support:</p> <pre><code>meshcli -r -s /dev/ttyACM1 -b 115200 \"ota status\"\n</code></pre> <p>The command must print an <code>OTA | ... target:XXXXXXXX</code> status.</p> <p>For an nRF52 full Companion, open the source port with terminal mode selected automatically:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM1\n</code></pre> <p>Run <code>ota status</code>. It must report <code>OTA seeder</code>, <code>install:disabled</code>, and target <code>00000000</code>; send <code>+++MESHCORE-TERM-STOP</code> before closing the terminal. The automation detects and performs this token-wrapped preflight itself, so no extra command-line option is needed.</p> <p>For an ESP32 full Companion, test its separate WiFi control console instead:</p> <pre><code>./tools/lora_ota/lora_ota.sh --tcp-cli 192.168.1.50 \"ota status\"\n</code></pre> <p>It must report <code>OTA seeder</code>, <code>install:disabled</code>, and target <code>00000000</code>.</p> <p>This standalone fallback uses Python's raw TCP socket directly. It works with <code>meshcli</code> versions whose <code>-r</code> mode rejects <code>-t</code>; it does not need <code>meshcli</code>, <code>motatool</code>, <code>nc</code>, or a firmware package. It defaults to text port 5002; port 5000 speaks the binary Companion protocol and port 5001 serves mOTA data. The firmware must expose the text console; this option does not enable one.</p> <p>Specify a port or adjust the total connection/command timeout (10 seconds by default):</p> <pre><code>./tools/lora_ota/lora_ota.sh --tcp-cli 192.168.1.50:5002 --timeout 15 \"ver\"\n</code></pre> <p>PowerShell uses the same option:</p> <pre><code>.\\tools\\lora_ota\\lora_ota.ps1 --tcp-cli 192.168.1.50 \"ota status\"\n</code></pre> <p>Place <code>--tcp-cli</code> first. Each invocation sends one command and waits for the complete reply and terminal prompt. Connection failures, timeouts, missing replies, and rejected commands exit nonzero. If USB owns the terminal, close the active USB terminal and try again. Commands are never automatically resent in this standalone mode: a timeout after sending may mean the command executed but its reply was lost. Inspect the device state before repeating a change.</p> <p>For an actual OTA run, continue using <code>--source-tcp HOST:5001</code> with <code>--source-cli-tcp HOST:5002</code>; that existing control path also bypasses <code>meshcli</code> raw mode. The standalone fallback does not transfer a firmware image itself.</p> <p>Changing a terminal to 57600 baud does not select ASCII mode. USB Companion builds and the normal raw management CLI use 115200 unless a particular build was explicitly configured otherwise.</p>"},{"location":"lora_ota_automation/#3-check-the-destination-once","title":"3. Check the destination once","text":"<p>The destination must be in the controller's contacts and remotely reachable on the normal channel. The script runs these authenticated checks itself:</p> <pre><code>ota status\nget bootloader.ver\nota self\nota stats\n</code></pre> <p>The script uses <code>get bootloader.ver</code> as an optional platform/version hint, not as an install gate. It makes one attempt without an interactive retry loop. <code>unknown</code>, an unsupported/missing command, an unrecognized reply, or a lost reply produces a warning and does not by itself block the run. In particular, older MeshCore firmware can report <code>unknown</code> for the installed signed OTAFIX 2.4.6 MeshTower V2 SD image because it omits the legacy UF2 version string. Both the shell and PowerShell launchers use this same behavior; no application or Companion firmware update is required for this host-side workaround. The runner also accepts the new <code>OTAFIX2.4.6</code> and explicitly labelled <code>0.11.0 (base)</code> formats.</p> <p>The runner still requires <code>ota self</code> to report <code>bootloader: apply OK</code>, <code>bootloader: QSPI apply OK</code>, or <code>bootloader: SD apply OK</code> and checks the reported bootloader ABI and codec mask against the selected package. If the version command is unavailable on older firmware, the script warns and falls back to the legacy <code>ota self</code> platform marker. If an nRF52 bootloader lacks the required capabilities, install the exact-board OTAFIX bootloader first. Positive nRF52 capability markers take precedence over a generic unsupported getter response, so it cannot silently skip nRF52 safety checks. Bootloader packages still require the independently checked <code>ota bootloader status</code> board, target, ABI, codec and storage identity; missing version text never bypasses package signature checks or the explicit bootloader-install workflow. The separate hardware-qualified <code>rak3401_mota_chain.py</code> retains its exact deployed version restriction; it is not a general OTAFIX 2.4.6 update runner. Current firmware also reports <code>maxblk:2048</code> near the front of both OTA replies. The runner treats a missing marker as the deployed 1 KiB receive limit, rejects a ready 2 KiB package for such a target before transfer, and passes the live limit to <code>motatool --block-size</code> when it builds from raw firmware. Thus updating an older target from a release ZIP produces a compatible 1 KiB package while a current target retains the 2 KiB application default. <code>ota stats</code> is only an optional EndF version probe. It uses one bounded retry cycle; unsupported firmware or a lost reply falls back directly to the required <code>ver</code> command instead of entering an operator continuation loop.</p> <p>The default TempRadio tuple is:</p> <pre><code>909.950,250,5,5,120\n</code></pre> <p>The test default is 250 kHz bandwidth, SF5, and CR5. The frequency is only a North American example: choose a legal frequency supported by every participating radio and appropriate to your location. Older radios that do not support SF5 require a complete replacement tuple passed with <code>--temp-radio</code>.</p> <p>Before that long window is allowed, the live runner performs a mandatory independent three-minute rehearsal. Its exact normal-channel <code>ota status</code> and <code>ota self</code> identity proof gets one shared four-minute, read-only budget before any schedule, radio override, seeder, or transfer is armed; this tolerates a marginal link without consuming or extending a live lease. It advances a stale managed controller with exact readback and treats a source terminal's whole-minute display as an uncertainty window, never as an exact epoch. A source minute overlapping the host is preserved; a completely stale minute is pinned to a guarded future value and read back once. Neither clock is moved backward, and the runner stops if a managed clock cannot be proven within the ten-minute limit. Each remote participant must expose an empty <code>tempradioat</code> schedule. The runner projects one fixed start/end interval into each participant's independently sampled RTC, sends each mutation once, proves every exact identity on the temporary tuple, waits for natural expiry, and proves the complete normal path again. A lost schedule reply is resolved by those on-air proofs; it is never blindly replayed with a fresh duration.</p> <p>The published RAK3401 <code>v1.16.7-c1caa5ad</code> LoRa-OTA image includes <code>get/set/del tempradioat</code> and can take this safe first step. A truly older or reduced build without fixed TempRadio scheduling is rejected before mutation; bootstrap it locally or with another explicitly controlled maintenance path. The automation does not substitute an immediate <code>tempradio</code> command whose first delivery could remain queued after cleanup.</p>"},{"location":"lora_ota_automation/#rxps-handling-during-tempradio","title":"RXPS handling during TempRadio","text":"<p>RXPS improves receive performance per unit of radio-on time, so the runner keeps the destination's saved RXPS preference enabled whenever the selected fast tuple has a qualified timing window. Before changing any radio, it reads <code>ver</code> from the destination, controller, source, and every named relay. It treats v1.17.1.5 as the first forward contract in which every SF5-SF8 transmission, including a retry, uses the same tuple-selected physical preamble: normally 32 symbols, 64 only when 32 cannot enable RXPS, and 128 only when neither 32 nor 64 can. A saved RXPS level is also safely retuned after a radio change. An older or unparseable destination version fails closed: the runner temporarily sends <code>set radio.rxps off</code> instead of assuming an ad-hoc build contains the timing fixes. Automation deliberately treats the version as a wire-format contract.</p> <p>For the default SF5/BW250 tuple, the runner keeps destination RXPS on only when the destination and every possible sender are v1.17.1.5 or newer. It does not overwrite an existing level-based preference. Current firmware retunes that preference against the tuple-selected 64-symbol wire preamble; the qualified boundary is effective level 8, preamble 64 (<code>1252 / 6424 us</code>). A manually configured node may save <code>set radio.rxps level 8 preamble 32</code> before entering TempRadio: when 32 symbols cannot cover the TCXO transition, firmware safely selects the real 64-symbol preamble. If the saved setting uses fixed manual timings, or even one participant is older or unknown, RXPS is temporarily off. This avoids the receive gap that a 32-symbol sender or an unretuned manual window would create.</p> <p>The complete qualified SX1262+TCXO policy is:</p> TempRadio SF/BW Saved reference setting Qualified boundary Automation SF7/BW500 <code>level 7 preamble 32</code> 7 / 32 RXPS on for a current destination SF6/BW250 <code>level 7 preamble 32</code> 7 / 32 RXPS on for a current destination SF5/BW125 <code>level 7 preamble 32</code> 7 / 32 RXPS on for a current destination SF5/BW250 <code>level 8 preamble 32</code> 8 / 64 RXPS on only when every participant follows the 64-symbol contract SF6/BW500 <code>level 8 preamble 32</code> 8 / 64 RXPS on only when every participant follows the adaptive-preamble contract SF5/BW500 <code>level 8 preamble 32</code> 8 / 128 RXPS on only when every participant follows the adaptive-preamble contract SF5/BW62.5 <code>level 10 preamble 16</code> 10 / 16 RXPS on for a current destination Unqualified tuple none continuous RX RXPS temporarily off <p>If RXPS was already off, the runner leaves it off. Otherwise it writes the original level, preamble assumption, receive/sleep periods, and temporary decision to protected <code>target-rxps-settings.json</code> in the run's working directory, verifies the temporary state, and restores the exact original setting after the target is back on its normal radio. Current firmware exposes this complete state through <code>get radio.rxps.config</code>; a legacy reply has only on/off and periods, so the runner can restore those periods but cannot reconstruct an unreported saved level. A radio change later recalculates from a preserved saved minimum, so moving back to a slower tuple returns to the operator's saved level.</p> <p>The OTA source has a stricter policy than the destination. For every source with a managed serial or TCP CLI, the runner reads and retains its exact RXPS preference, using the legacy fixed-period query only when the detailed query is unavailable. It builds and verifies the package, completes the read-only target checks, and obtains confirmation while that preference remains unchanged. Immediately before the first radio mutation, it reads the source RXPS state again, disables RXPS, and verifies the readback. Source RXPS stays off through catalog serving, download, installation, and post-install identity verification. Cleanup first proves that the source has returned to its normal radio, then restores and verifies the exact saved level/preamble or fixed-period state once. A source whose RXPS state cannot be read, disabled, or restored safely fails closed. If current firmware explicitly rejects an RXPS disable or restore with <code>radio busy; retry</code>, the runner retries that idempotent mutation at staggered 210\u2013378 ms intervals. All 32 delays are distinct and contribute about 9.4 seconds of waits; source-CLI command round-trip time is additional. This avoids repeatedly sampling one radio phase while retaining a strict attempt cap. Other rejections are not replayed.</p>"},{"location":"lora_ota_automation/#4-run-an-esp32-update","title":"4. Run an ESP32 update","text":"<p>The ZIP can contain a compatible ready <code>.mota</code> or the exact board-and-role non-merged application <code>.bin</code>:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='target-admin-password'\n\n./tools/lora_ota/lora_ota.sh ./release.zip \"Roof ESP32\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <p>The script shows the detected target, hardware, running hash, chosen package, version, manifest ID, and action before asking for confirmation. For an unattended job, add <code>--yes</code>:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Roof ESP32\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1 \\\n  --yes\n</code></pre> <p>PowerShell equivalents:</p> <pre><code>$env:MESHCORE_ADMIN_PASSWORD = 'target-admin-password'\n\n&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.zip' 'Roof ESP32' `\n  --controller-serial COM7 `\n  --source-serial COM8\n\n&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.mota' 'Roof ESP32' `\n  --controller-serial COM7 `\n  --source-serial COM8 `\n  --yes\n</code></pre> <p>Prefer the environment variable or the interactive password prompt. Passing <code>--password</code> works, but the wrapper's own command line may be visible to other local processes. The runner keeps the password out of child <code>meshcli</code> command lines and removes its protected temporary command file after each call.</p>"},{"location":"lora_ota_automation/#5-run-an-nrf52-update","title":"5. Run an nRF52 update","text":"<p>If the input ZIP already contains a compatible in-place delta <code>.mota</code>, no base argument is needed: its embedded base hash is compared with the live node. If the ZIP contains raw new firmware, supply the exact running image:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./nrf52-new-release.zip \"Hill nRF52\" \\\n  --base ./firmware-that-is-running.hex \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <pre><code>&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\nrf52-new-release.zip' 'Hill nRF52' `\n  --base '.\\firmware-that-is-running.hex' `\n  --controller-serial COM7 `\n  --source-serial COM8\n</code></pre> <p>Before building a delta, the runner proves that the base's target ID, hardware identity, firmware version when available, and <code>EndF</code> body hash match the live destination. It then asks <code>motatool</code> for codec 2, the nRF52 in-place format. The normal workspace is <code>0x98000</code>.</p> <p>For a QSPI-backed repeater or the SD-backed MeshTower V2 target, a raw ZIP becomes a full image without <code>--base</code>. Supplying an exact base requests a smaller in-place delta and automatically selects the conservative external workspace <code>0xC6000</code>, which is safe for S140 v6 and v7 application layouts. An explicit <code>--inplace-memory</code> overrides the automatic value.</p> <p>The live runner detects QSPI from <code>ota self</code> (<code>QSPI apply OK</code>) or <code>ota status</code> (<code>bl:QSPI</code>) and refuses an explicit <code>QSPI store:ERR 0K</code> report even when the bootloader itself advertises QSPI apply support. Offline <code>--prepare-only</code> runs must supply <code>--nrf-qspi</code>; do not use that switch for a board that only exposes QSPI pins or uses the chip as a Companion filesystem. The application and bootloader must both be from the matched repeater list in the nRF52 QSPI guide.</p>"},{"location":"lora_ota_automation/#6-add-intermediate-relays","title":"6. Add intermediate relays","text":"<p>List relays from farthest to nearest so each command is sent before its route moves to TempRadio. A bare relay name uses the destination password; use <code>NAME=PASSWORD</code> when it differs:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1 \\\n  --relay \"Far Relay=far-password\" \\\n  --relay \"Near Relay=near-password\"\n</code></pre> <p>PowerShell uses the same arguments:</p> <pre><code>&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.mota' 'Remote Target' `\n  --controller-serial COM7 `\n  --source-serial COM8 `\n  --relay 'Far Relay=far-password' `\n  --relay 'Near Relay=near-password'\n</code></pre>"},{"location":"lora_ota_automation/#other-connection-choices","title":"Other connection choices","text":"<p>The controller can use any one of:</p> <pre><code>--controller-serial PORT\n--controller-tcp HOST[:PORT]       # default port 5000\n--controller-ble ADDRESS_OR_NAME\n</code></pre> <p>An ESP32 FULL/repeater source can serve over its dedicated WiFi seeder port while its raw USB CLI is used to start TempRadio:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.50:5001 \\\n  --source-cli-serial /dev/ttyACM1\n</code></pre> <p>An ESP32 <code>companion_radio_full</code> uses WiFi for both dedicated source links:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.50:5001 \\\n  --source-cli-tcp 192.168.1.50:5002\n</code></pre> <p>Port 5002 defaults automatically when it is omitted from <code>--source-cli-tcp</code>. Current Full Companion firmware exposes its complete role-specific text terminal there; the runner uses only <code>ota</code>, <code>tempradio</code>, and <code>normalradio</code>, and remains compatible with older bounded port-5002 consoles. The source-only Companion never stages or installs the image itself; it streams the host folder to other nodes over LoRa. See the full Companion guide for manual operation and interface details.</p> <p>An nRF52 <code>companion_radio_full</code> uses one USB source port sequentially. The runner automatically wraps local control commands in the terminal tokens, and unmodified <code>motatool</code> switches that port into mOTA mode when seeding starts:</p> <p>The wrapper sends STOP, then START, before each command. This makes fallback independent of whether a prior raw probe left an unobservable USB-UART connection in ASCII or Binary mode. Seeder startup is reported only after the verbose device log contains its <code>COUNT</code> acknowledgement; an immediate device <code>ERR</code> or a missing acknowledgement fails during startup instead of surfacing later as a catalog timeout.</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <p>If the source is already on the exact TempRadio tuple through a scheduled or manual operation, <code>--source-already-temp</code> lets a TCP source run without a raw CLI link. The script cannot verify, extend, or shorten that source window, so leave a comfortable time margin. It also cannot inspect or change that unmanaged source's RXPS state; disable source RXPS yourself before starting the run and restore it only after returning the source to its normal radio.</p> <p>Use <code>--controller-baud</code> or <code>--source-baud</code> only for a build whose corresponding interface is genuinely configured to another speed.</p>"},{"location":"lora_ota_automation/#package-selection-and-safety-gates","title":"Package selection and safety gates","text":"<p>For a ZIP, the runner first examines every <code>.mota</code> without extracting paths. It keeps only packages matching the live target, hardware, base, platform, codec, and bootloader capabilities. It chooses the newest compatible version and prefers a delta over a full image at the same version. If equally suitable files differ, select one explicitly:</p> <pre><code>--zip-member path/inside/archive/update.mota\n</code></pre> <p>If no ready mOTA is usable, it searches <code>.bin</code> and <code>.hex</code> members for a valid, matching <code>EndF</code>, then builds the platform-appropriate container. Every result is structurally checked by the runner and independently passed through <code>motatool verify</code> before any radio changes. Direct firmware and mOTA inputs, as well as individual ZIP members, are rejected above 64 MiB before being loaded.</p> <p>Useful controls:</p> <ul> <li><code>--public-key signer.key.pub</code> requires a particular Ed25519 signer during   verification.</li> <li><code>--sign-key signer.key</code> signs a newly built container.</li> <li><code>--no-install</code> downloads and verifies the image but leaves it staged. By   default the runner then schedules the target, relays, and a script-configured   source back to their normal radios. Combining it with   <code>--leave-controller-radio</code> deliberately preserves the destination, relays,   and separate controller on the TempRadio topology; a managed source is still   returned to normal so its exact RXPS setting can be restored.   If the version gate required RXPS off, it stays off while that topology is   preserved; use <code>target-rxps-settings.json</code> to restore it only after sending   <code>normalradio</code>.</li> <li><code>--allow-non-upgrade</code> deliberately permits the same or an older application version.</li> <li><code>--replace-active-download</code> deliberately discards a different update already   downloading or staged on the target. Without it, that update is preserved.</li> <li><code>--source-shares-controller</code> is for a Full Companion whose USB Binary API is   the controller while its TCP port <code>5001</code> is the source. It verifies that the   source's port-<code>5000</code> public key equals the controller key, then binds the   fresh port-<code>5002</code> Full Terminal banner's complete public key to that Binary   identity and challenges it with the supported <code>ver</code> command. It does not   assume the Full Terminal implements repeater-only <code>get public.key</code>. Port   <code>5002</code> uses a bounded local <code>tempradio</code> override to move the shared physical   radio without overwriting its saved normal tuple; the Binary API remains the   authenticated transport. Cleanup sends local <code>normalradio</code>, proves that   override inactive, and then reasserts the saved Binary tuple. It cannot be   combined with   <code>--leave-controller-radio</code>,   because exact source RXPS restoration requires that shared physical radio to   be back on its verified normal tuple.</li> <li><code>--require-system-watchdog-off</code> checks <code>get system.watchdog</code> immediately   before every <code>ota install</code> transmission and refuses installation unless the   destination reports <code>&gt; off</code>. Use it for nRF52 chains whose bootloader cannot   service an application watchdog inherited across reset.</li> <li>Managed <code>--relay</code> nodes have their original <code>rxdelay</code> and <code>txdelay</code> captured   in the work directory. During transfer the runner verifies <code>rxdelay 0</code> and   an airtime-scaled <code>txdelay 0.3</code> (override with <code>--relay-txdelay</code>), then   restores both values before the relay leaves TempRadio.</li> <li><code>--work-dir PATH</code> chooses a new, non-existent work directory.</li> <li><code>--meshcli PATH</code> and <code>--motatool PATH</code> select binaries not on <code>PATH</code>.</li> <li><code>--package-build-timeout SECONDS</code> bounds local mOTA generation. It defaults   to 3600 seconds. Run detools, delta/compression, and raw-firmware package   generation on a workstation or build VM, then transfer the completed,   hash-verified <code>.mota</code> to a Pi-class radio host. The Pi should perform only   lightweight identity-gated hardware I/O and serve that finished artifact;   preparation still occurs before any radio state changes.</li> <li><code>--debug</code> prints redacted child commands, timeouts, process status, stdout,   and stderr. Admin passwords are never printed, but node names, addresses,   paths, and command replies can still be sensitive; share the log carefully.</li> </ul> <p>For offline package preparation only:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.zip offline \\\n  --prepare-only \\\n  --platform nrf52 \\\n  --target-id 1234ABCD \\\n  --target-base-hash 0011223344556677 \\\n  --target-hw Heltec_T114 \\\n  --base ./firmware-that-is-running.hex\n</code></pre> <p>Live operation is safer because the script obtains these values directly from the destination.</p>"},{"location":"lora_ota_automation/#what-happens-during-a-run","title":"What happens during a run","text":"<ol> <li>Validate the input paths and host tools, then prove the source is either an    OTA-enabled raw CLI or a source-only full Companion control interface. Read    and durably save a managed source's exact RXPS preference without changing    it.</li> <li>Before sending any remote packet, prove the managed source has no active,    pending, or fixed TempRadio work, then gate the source and controller    clocks. Advance a stale exact clock to host time; for a minute-resolution    source, preserve an overlapping minute or use one guarded forward value    with readback. Preserve a small future lead and fail closed above the    ten-minute drift limit. Then    authenticate to the target, query its target ID, hardware, running body    hash, firmware version, bootloader version, and nRF52 bootloader    capabilities, and save the controller's normal radio tuple.</li> <li>Select or build one compatible v2 application mOTA and verify all block    hashes, Merkle root, full-image hash where applicable, identity fields,    signature, codec, base, and the live firmware's reported maximum block size    (1 KiB for legacy replies without <code>maxblk</code>, currently 2 KiB otherwise).    Version-3 bootloader packages are refused before any target state changes.</li> <li>Read every participant's version, save the destination's RXPS state,    select the qualified destination policy, and show the confirmation prompt.</li> <li>Run the fixed-window three-minute rehearsal described above. This phase    does not disable RXPS, start a seeder, request a pull, or install anything;    the long transfer remains completely unarmed until temporary and normal    reachability both pass.</li> <li>Fresh-read, disable, and verify source RXPS; apply and verify the    destination RXPS policy; then start TempRadio on the    target, far-to-near relays, and source. A separate controller is moved and    read back through Binary; a shared Full Companion instead schedules its    bounded local override while Binary remains the transport. The runner    rejects a TempRadio window that cannot cover setup, seeder startup,    discovery, the transfer timeout, final polling, and install checks.</li> <li>Start <code>motatool serve</code>, discover the exact eight-hex manifest ID, request    <code>ota pull &lt;id&gt; flash</code>, and poll until that same ID reports ready. A seeder    process exit stops the run immediately. For <code>--no-install</code>, schedule all    script-controlled nodes back to their normal radios before restoring the    controller, unless <code>--leave-controller-radio</code> was requested.</li> <li>Recheck that exact ID, give the target a short final TempRadio safety window,    and request <code>ota install</code>. Then shorten each relay's TempRadio window so the    normal multi-hop route returns, stop the seeder, shorten the source window,    restore the controller, and probe <code>ota self</code> every 10 seconds through the    configured readiness window (five minutes by default). The exact new body    hash is the readiness signal;    only then does the runner require the exact package version. A relayed run    continues the 10-second probes through the mandatory relay-return window. A    source supplied with <code>--source-already-temp</code> is never modified.    <code>--leave-controller-radio</code> moves the controller back to TempRadio only after    this normal-channel verification. Restore the destination's exact original    RXPS setting after normal-channel identity is proven. A managed source stays    RXPS-off through that verification and its exact setting is restored only    after its own TempRadio state is proven inactive.</li> </ol> <p>Remote replies are matched only after queued messages have been drained and only when they come from the intended contact and fit the command. A ready status for another manifest ID is an error, never permission to install it.</p>"},{"location":"lora_ota_automation/#transmission-loss-and-retries","title":"Transmission loss and retries","text":"<p>Read-only and replay-safe transmissions retry up to three times. Three retries or 90 seconds, whichever comes first, opens a 10-second stop-or-continue prompt when stdin is an interactive terminal. Continue remains the default on timeout or Enter, so an operator can persist through a temporary outage; enter <code>s</code> or <code>stop</code> to end the run, and Ctrl-C remains immediate. With non-interactive stdin, the runner stops after that finite automatic retry cycle instead of silently starting another cycle forever. Optional participant-version probes always use a bounded cycle and degrade to <code>unknown</code>; optional destination <code>ota stats</code> falls back directly to <code>ver</code>. The mandatory normal-channel destination baseline is the narrow exception: it may make nine total read-only attempts but is stopped by one hard four-minute deadline before any TempRadio lease or OTA mutation exists. Proofs inside the live rehearsal retain the smaller four-attempt limit.</p> <p>Commands that change OTA state are reconciled before replay:</p> <ul> <li>After a lost <code>ota pull</code> reply, <code>ota status</code> must show the requested manifest   ID before the runner treats the pull as started. Otherwise the safe retry   policy applies.</li> <li>A lost <code>ota install</code> reply is not blindly resent. After a short wait, it is   sent again only if the target replies that the same manifest is still ready.   If the target has stopped replying because it may be rebooting, the runner   restores the normal path and lets post-reboot identity resolve the outcome.   The target's final three-minute safety window also returns a non-rebooting   target to the normal channel promptly.</li> </ul> <p>Retries and operator-selected continuation can outlast the original TempRadio budget. If a bounded window expires, rerun the same package after the nodes return to their normal channel; the manifest-ID check resumes its partial download without replacing it.</p> <p>The working directory is created before a managed source can be changed, then retained and printed at exit. It contains the exact served mOTA, <code>motatool-serve.log</code>, extracted build inputs when needed, and <code>controller-radio.txt</code>. A managed source also gets a protected <code>source-rxps-settings.json</code> containing its exact original preference and idempotent restore command. Its contents and directory entry are flushed before RXPS is disabled. When the destination started with RXPS enabled, protected <code>target-rxps-settings.json</code> records its manual recovery state. The RAK3401 chain points every nested step at one chain-root source record, so a rerun after host power loss does not adopt the temporary RXPS-off state as the original. A retained record is accepted only for the same managed CLI endpoint. These files contain no saved admin password. After exact source restoration, a standalone run atomically retires its record; the chain retains its shared record between steps and retires it only after the verified endpoint restoration completes.</p>"},{"location":"lora_ota_automation/#interruption-and-recovery","title":"Interruption and recovery","text":"<p>Ctrl-C stops the seeder, detaches its serial folder, makes a bounded attempt to shorten a source TempRadio window started by the script, and attempts to restore the controller. For a managed source it leaves RXPS off until the source is proven back on its normal radio, then restores and verifies the saved source preference. A transient success-path restore failure remains armed for one more idempotent cleanup attempt. The target and relays remain on TempRadio only until their bounded windows end; rebooting also restores their saved radio settings. A normal cleanup restores the destination's exact RXPS periods. If that remote restore cannot be confirmed, use <code>target-rxps-settings.json</code> after the target returns to its normal channel. A partial download remains safe. Once the target is reachable again (after its TempRadio window ends, or after putting the controller back on that tuple), rerunning the same package recognizes its manifest ID and resumes the existing session instead of clearing it.</p> <p>When a chained run has already proved the newly running body hash, its retained previous package can briefly report <code>verifying staged blocks</code> after TempRadio reactivates the OTA manager. The runner waits only through the configured discovery timeout, keeps checking source liveness, and accepts only the same manifest becoming <code>ready to install</code> or the manager becoming idle. A changed ID, failed or incomplete state, or timeout stops the chain. It then proves the exact installed body again. If that same session is still attached and ready, the runner detaches it with <code>ota cancel</code>; if the manager has become idle, it sends no cancel. An ordinary-channel <code>no download</code> status proves only that the manager is idle, not that persistent staging was erased. The runner therefore does not issue or describe an IDLE cancel as durable cleanup. The next chain transition explicitly re-adopts and proves the expected previous MID before detaching it; after the final install OTAFIX has consumed the approval word, so any retained container is inert and is replaced by the next valid pull.</p> <p>A hard process kill or host power loss cannot run cleanup. Recover a serial controller using the tuple saved in the printed work directory:</p> <pre><code>radio=$(tr -d '\\r\\n' &lt; ./meshcore-lora-ota-20260807-123456-1234/controller-radio.txt)\nmeshcli -s /dev/ttyACM0 set radio \"$radio\"\n</code></pre> <pre><code>$radio = (Get-Content '.\\meshcore-lora-ota-...\\controller-radio.txt' -Raw).Trim()\nmeshcli -s COM7 set radio $radio\n</code></pre> <p>For a managed source, first return it to its ordinary radio, then inspect <code>source-rxps-settings.json</code> and issue its exact <code>restore_command</code> through the same serial or TCP-console endpoint recorded in that file. The command is idempotent; confirm the full setting with <code>get radio.rxps.config</code> before resuming an update.</p> <p>If you stop during final confirmation, reconnect on the node's normal channel and run <code>ota self</code> and <code>ver</code>. A completed run returns success only when <code>ota self</code> reports a valid new body hash and <code>ver</code> exactly matches the package; an unverified install returns status 2. Do not immediately replace a staged image: the default active-download guard preserves it until you explicitly use <code>--replace-active-download</code> or run <code>ota cancel</code>.</p> <p>Exit status is <code>0</code> for success, <code>2</code> for a validation or operational error, and <code>130</code> for Ctrl-C.</p>"},{"location":"management_decoder/","title":"Management report decoder","text":"<p>Paste MGR1 management-report payloads or complete GroupData packets from a packet analyzer to read a radio's public management information. Everything, including password authentication and ACL decryption, happens locally in this browser. The report, password, and candidate public key are never uploaded.</p> <p>The public portion of a report is deliberately plaintext, but it is not authenticated until a management password is supplied. A password-authenticated page proves that its public fields and encrypted ACL bytes have not been altered by someone who does not know that password.</p>"},{"location":"management_decoder/#decode-a-management-report","title":"Decode a management reportEncrypted ACL entries","text":"MGR1 payload or complete GroupData packet hex <p>     Spaces, line breaks, colons, dashes, <code>0x</code>, and MQTT JSON fields named     <code>raw</code> or <code>data</code> are accepted. Paste all pages from one report     together to view a complete multi-page ACL. Press Ctrl/Command+Enter to decode.   </p> Management password (optional for public fields; required for ACLs) <p>     The password remains in this page only. The decoder derives the MGR1 AES-SIV key in     your browser and does not send it anywhere.   </p> Candidate administrator public key (optional) <p>     ACL encryption reveals per-radio 12-byte fingerprints, not recoverable public keys.     Supplying a complete candidate key checks whether its fingerprint appears in this report.   </p> Decode management report Clear local data Load authenticated example Decode notes"},{"location":"management_decoder/#what-the-decoder-accepts","title":"What the decoder accepts","text":"<ul> <li>Complete <code>PAYLOAD_TYPE_GRP_DATA</code> (<code>0x06</code>) analyzer/MQTT packet hex. It checks   the MeshCore route header, encoded path length, MGR1 page bounds, and required   zero padding.</li> <li>A canonical MGR1 payload beginning with <code>4D475231</code> (<code>MGR1</code>).</li> <li>One raw packet or canonical payload per line; duplicate observations of an   identical page are deduplicated.</li> </ul> <p>Use the same password configured by <code>set mgmt.password</code>. A decoded ACL lists the report-specific fingerprints and the administrator and/or OTA-signer flags. It cannot turn a fingerprint back into a full key. Use the optional candidate field to test a specific full public key.</p> <p>For the report schedule, public-field layout, cryptographic design, and the offline Python capture tool, see Management reports.</p>"},{"location":"management_reports/","title":"Management reports (MGR1)","text":"<p>Available on repeater (including observer), room-server and sensor firmware. Companions/terminal-chat nodes and KISS modems do not originate these reports. Off by default. A management password and explicit enable are both required. No radio settings, existing preferences layout, or OTA authorization policy is changed by enabling reporting. This protocol does not authorize updates.</p>"},{"location":"management_reports/#cli","title":"CLI","text":"<p>Run through the existing local CLI or an authenticated administrator session:</p> <pre><code>get data.tx\nset data.tx path 1:12ab77\nset data.tx region auto\nset mgmt.password &lt;12-to-96-byte password&gt;\nset mgmt.direct 5\nset mgmt.flood 21\nset mgmt.enabled on\nget mgmt\nset mgmt.enabled off\n</code></pre> <p>Use a long randomly generated password. There is no password getter. Firmware stores the derived 32-byte key, not the plaintext password. That stored key is equivalent authority to decrypt reports and must also be protected. Passwords entered into terminal programs may still be recorded by those programs.</p> <p><code>data.tx</code> is the single shared route for management reports, telemetry history, and future scheduled data producers. Its fresh-install defaults are <code>path=direct</code> (zero hops) and <code>region=auto</code>; configuring it never enables a producer. Paths use <code>1:</code>, <code>2:</code> or <code>3:</code> followed by complete hop hashes without separators, or the comma-separated form accepted by <code>set outpath</code>. <code>none</code> removes the path. <code>get/set mgmt.path</code> remain compatibility aliases for <code>get/set data.tx path</code>.</p> <p><code>region=auto</code> uses the radio's configured default region when it is usable; otherwise it resolves the unique deepest flood-enabled entry in the region hierarchy. If equally deep candidates make that choice ambiguous, it resolves to nothing and no fallback is transmitted. <code>default</code> requires and follows <code>region default</code>; a region name pins that named scope. <code>none</code> disables scoped fallback. The resolved transport key is looked up when a report starts, so edits to the region definition take effect without rewriting <code>/data_tx</code>.</p> <p>The direct path leads to the receiver/uplink's vicinity; this broadcast-radio datagram has no private destination identity. The radio ID in the payload identifies the reporter.</p> <p>Direct and flood schedules are independently configurable and may each be turned off. Fresh settings are <code>direct=5d</code> and <code>flood=21d</code>; global reporting is still off until <code>mgmt.enabled on</code>. Direct accepts 5\u201390 days and requires the shared path. Flood accepts 21\u201390 days and requires a resolvable shared region. At least one route must remain active while reporting is enabled. The legacy <code>set mgmt.interval N</code> shorthand enables both, setting direct to <code>N</code> and flood to <code>max(21,N)</code>. No transmission is sent merely by configuring a password. Initial reporting waits for the configured schedules. Reports have deterministic per-radio/per-sequence jitter of up to an hour; pages are spaced at least a minute apart.</p> <p>The radio cannot know that an observer uploaded a packet to MQTT, so the flood schedule is deliberately independent of direct transmission. A region-scoped <code>TRANSPORT_FLOOD</code> is sent at its independently configured interval. An unresolved or ambiguous data region blocks that transmission rather than sending an unscoped flood. If direct and flood become due together, the flood is sent and replaces the redundant direct copy. Ordinary reports are never retried in a tight loop; a partial report gives up after an hour. Existing relay filters, hop limits and duty constraints still apply.</p> <p>Schedule state is atomically reserved before transmission, and checkpointed hourly. Timers use elapsed powered-on time rather than the RTC: clock corrections cannot create floods, and reboot does not clear the budget. Downtime is not credited; each reboot can delay a report by up to an additional hour. This is a deliberately conservative tradeoff for nodes with unreliable clocks. Off/on and password changes do not reset the flood limit. Corrupt/unreadable state or failed writes stop reporting; <code>get mgmt</code> shows <code>FAULT(no TX)</code> until storage is repaired and the radio restarted. <code>/management</code> and the shared <code>/data_tx</code> are versioned, CRC-protected, and replaced transactionally.</p> <p>Weekly history is collected once a minute while enabled. Hour-bucket extrema cover 7 days to 7 days + 1 hour (conservative boundary bucket). The first report after enable/reboot is marked partial where appropriate. Since-report extrema reset after all pages have been queued, retaining readings taken since the snapshot for the next report. These statistics are not durable; reboot loses the history, not the flood countdown. Temperature is MCU temperature, not ambient. Reporting does not wake GPS, start Wi-Fi, or initialize external OTA media. Unknown capabilities/readiness are explicitly distinguishable from false. History/snapshot working memory is allocated only when reporting is enabled and is bounded to 1.5 KiB, plus a small configuration object and temporary stack use.</p>"},{"location":"management_reports/#routing-and-mqtt","title":"Routing and MQTT","text":"<p>Both direct/path and flood reports use <code>PAYLOAD_TYPE_GRP_DATA</code> (<code>0x06</code>). The route bits independently select direct or flood. <code>MGR1</code> is an application extension with literally plaintext public fields, not a call to the ordinary encrypted <code>createGroupDatagram()</code> builder. A fixed public marker is not an owner or password-derived channel ID. There is no outer channel encryption.</p> <p>The body is padded with zeroes to a group-compatible length <code>3 + 16*n</code> (maximum 179 bytes). Existing repeaters in the checked upstream implementation route group data without requiring a successful channel decryption. This fork recognizes the management envelope before ordinary channel processing. Reception of a management packet never exempts it from forwarding policy. Some third-party firmware may apply additional channel/layout policies; interoperability with every fork is not guaranteed. Packet logging/uplinks can capture it without the password.</p> <p><code>RAW_CUSTOM</code> (<code>0x0F</code>) is not used for reports because stock upstream does not flood-route it.</p> <p>The observer's existing MQTT <code>PACKET</code> JSON supplies the complete frame in <code>raw</code>. No broker configuration or password changes are necessary to capture a report. The decoder understands all four route forms, 1\u20133-byte hashes, scope transport codes, and duplicate copies heard by several uplinks:</p> <pre><code>python -m pip install -r tools/management/requirements.txt\npython tools/management/report.py --mqtt capture.jsonl\n</code></pre> <p>The password is prompted, not supplied as a process argument. Input may be JSONL or a JSON array of MQTT messages. Alternatively omit <code>--mqtt</code> for a JSON array of canonical payload hex strings. <code>--match-admin FULL_PUBLIC_KEY</code> in canonical payload mode matches a known administrator against the encrypted fingerprints. This is an offline capture decoder, not a broker subscriber or downlink service.</p> <p>For a browser-local decoder that also decrypts and authenticates ACL entries, use the Management report decoder. It does not upload the captured packet or password.</p>"},{"location":"management_reports/#canonical-payload-little-endian","title":"Canonical payload (little endian)","text":"Offset Bytes Field 0 4 <code>MGR1</code> 4 16 First 16 bytes of reporter public key 20 4 Persisted report sequence (never wraps; exhaustion stops TX) 24 4 RTC Unix timestamp; advisory, may be wrong 28 4 Firmware major/minor/patch/pre packed as mOTA version 32 4 Bootloader packed version, or unknown 36 4 EndF target ID 40 8 Complete mOTA delta-base body hash 48 4 EndF image length 52 4 Staging capacity; planning still checks actual package geometry 56 4 OTA capability bits 60 2 Uptime hours, saturated at 65535 62 4 Weekly minimum mV, minimum \u00b0C, maximum \u00b0C 66 4 Since-report extrema in the same format 70 1 History coverage hours, capped at 168 71 1 Interval days for this report's direct or flood schedule 72 1 Role: 1 repeater, 2 room server, 3 sensor 73 1 Compiled/detected capability bits 74 1 Active status bits 75 1 Mask of status bits whose state is known 76 2 Validity/partial-history flags 78 1 Zero-based page index 79 1 Total pages (1\u20136) 80 1 Unique ACL count (0\u201336) 81 1 First ACL index in this page 82 1 ACL entries on this page (0\u20136) 83 13 \u00d7 count AES-SIV encrypted ACL entries after ACL 16 Full AES-SIV authentication tag after tag 0\u201315 Zero padding to group-compatible length; not part of canonical payload <p>Each private entry is a per-radio 12-byte keyed fingerprint followed by flags: bit 0 administrator, bit 1 trusted OTA signer. Duplicate entries combine flags. An oversized ACL fails closed rather than silently truncating. The reported allowlist includes all current full administrators and all four possible trusted OTA signing keys; region/filter managers and ordinary clients are excluded.</p> <p>Feature bits: 0 Wi-Fi, 1 GPS, 2 NTP, 3 USB data, 4 LoRa OTA. Wi-Fi active means connected, GPS means receiver enabled (not necessarily a fix), NTP means an actual accepted NTP response this boot, USB means observable native USB data connection (not power or an unobservable external UART bridge). OTA capability means compiled support; active means an established usable apply/store path.</p> <p>Validity bits: 0 firmware version, 1 bootloader version, 2 EndF/base identity, 3 staging capacity, 4 partial week, 5 partial since-report period, 6 MCU temperature. Voltage is unsigned millivolts, zero missing. Temperatures: zero missing, 1\u2013251 represent \u221250\u2026200 \u00b0C, 252 below range, 253 above range, 254\u2013255 reserved. OTA bits: 0 protocol compiled, 1 transfer DEFLATE, 2 2-KiB app transfer blocks; bits 8\u201323 are apply codec bits (full/sequential/in-place). Transfer DEFLATE is not compressed bootloader apply. There is no manifest ID. Exact old binaries are still needed on the computer to generate a differential update; a hash alone cannot reconstruct them. Unknown metadata must not be treated as OTA readiness.</p>"},{"location":"management_reports/#cryptography","title":"Cryptography","text":"<p>Password root: <code>SHA256(\"#\" || literal UTF-8 password)</code> (hashtag-style derivation). Subkeys: <code>HMAC-SHA256(root, ASCII_domain || radio_id16)</code>. Domains: <code>MeshCore-MGR1-SIV</code>, <code>MeshCore-MGR1-ACL</code>. Fingerprint: <code>HMAC-SHA256(ACL_subkey, radio_id16 || full_admin_key32)[0:12]</code>. The same owner has different fingerprints on different radios. A collector needs a candidate administrator's full key to identify a fingerprint.</p> <p>Encryption is RFC 5297 AES-SIV-CMAC-256, using the existing rweather AES primitive. The single associated-data string is the complete 83-byte clear header. Ciphertext is exactly the ACL byte length. Full 16-byte tag, no truncation. This deterministic misuse-resistant mode avoids reliance on the firmware's noncryptographic general-purpose RNG or RTC nonces. An identical restored snapshot may repeat ciphertext, but does not expose XORs of different ACL plaintexts as nonce-reused stream encryption would.</p> <p>All public fields are readable without a password but are authenticated only to password holders. A shared password authenticates knowledge of that password, not a unique individual radio identity; another holder can forge reports. There is no per-device signature. Collectors must enforce their own persisted sequence/replay policy and explicitly handle factory resets/restored backups. The decoder verifies snapshot consistency but does not maintain a database. This fast password derivation permits offline guessing, so twelve characters is only a minimum length, not a guarantee of password strength. Packet timing, public metadata and entry/page counts remain visible.</p>"},{"location":"mbedtls-tls-footprint/","title":"Shrinking the per-connection TLS footprint on non-PSRAM observers","text":""},{"location":"mbedtls-tls-footprint/#why","title":"Why","text":"<p>On a non-PSRAM Heltec V3 running two WSS/JWT broker slots, the largest allocatable block in internal DRAM walks down in ~16 KiB steps at every TLS reconnect while total free heap stays flat. Measured on hardware over 50 reconnect cycles: 62,452 -&gt; 16,372 bytes, permanently.</p> <p>The step size is not a coincidence. <code>framework-arduinoespressif32 3.20017</code> (Arduino 2.0.17, IDF 4.4) builds mbedTLS with the symmetric buffer configuration:</p> <pre><code>CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN 16384      # sizes BOTH the in and out record buffers\nCONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE 1\n# CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN       -- not defined\n# CONFIG_MBEDTLS_DYNAMIC_BUFFER               -- not defined\n# CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH   -- not defined\n</code></pre> <p>Read from <code>packages/framework-arduinoespressif32/tools/sdk/esp32s3/qio_qspi/include/sdkconfig.h</code>. Note the separate <code>framework-arduinoespressif32-libs</code> package in <code>~/.platformio</code> belongs to the esp32c6 env (pioarduino, IDF 5.3) and is not what this env links against -- though it happens to carry identical mbedTLS values.</p> <p>So each broker slot costs 2 x 16 KiB = 32 KiB of contiguous internal DRAM in record buffers alone, and two slots cost 64 KiB on a board with roughly 80 KiB free. Every reconnect frees and re-allocates those buffers, and anything that lands in the vacated hole in between prevents them from going back, which is the ratchet.</p> <p>Confirmed by two independent observations: losing a whole TLS session returned exactly 16,384 bytes of contiguity on one device and exactly 32,768 on another, and per-connection teardown frees ~41.6-44.7 KB total.</p>"},{"location":"mbedtls-tls-footprint/#what-the-firmware-could-already-do-and-its-limit","title":"What the firmware could already do, and its limit","text":"<p><code>softDisconnect()</code> (branch <code>perf/mqtt-renewal-no-stop</code>, commit <code>6c51e468</code>) stops the JWT renewal bounce from destroying and recreating the esp-mqtt task, keeping its 6 KiB stack out of the hole. Measured: the staircase arrests after 2 steps at 36,852 through cycle 16, where the baseline took 4 steps and settled at 16,372 by cycle 11 -- about 20 KB better.</p> <p>That is as far as the application layer reaches. MQTT 3.1.1 has no re-authentication packet, so presenting a fresh JWT requires a transport reconnect; mbedTLS's internal allocation order during the handshake is not controllable from the application. The remaining cost is the record buffers themselves.</p>"},{"location":"mbedtls-tls-footprint/#the-changes","title":"The changes","text":"<p>All three are compile-time in mbedTLS, and the Arduino framework ships precompiled <code>.a</code> archives (<code>tools/sdk/esp32s3/lib/libmbedtls.a</code>), so a project-level <code>-D</code> cannot change them. A custom framework build is required.</p> Setting From To Saving per connection <code>CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN</code> unset <code>y</code> enables the two below <code>CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN</code> 16384 (implied) 16384 none -- keep it <code>CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN</code> 16384 (implied) 4096 ~12 KiB <code>CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE</code> <code>1</code> <code>n</code> ~4 KiB <p>Roughly 16 KiB per connection, 32 KiB across two slots.</p>"},{"location":"mbedtls-tls-footprint/#why-inbound-stays-at-16-kib","title":"Why inbound stays at 16 KiB","text":"<p>A peer may legitimately send a 16 KiB TLS record. Lowering the inbound limit only works if both brokers negotiate the max-fragment-length extension or provably never send larger, and getting it wrong produces invalid-record and handshake failures rather than a clean error. Outbound is ours to choose: this firmware's MQTT and WebSocket frames are far below 4 KiB (<code>MAX_TRANS_UNIT</code>-bounded packets plus small JSON), so 4 KiB is comfortable.</p>"},{"location":"mbedtls-tls-footprint/#risk-on-the-peer-certificate","title":"Risk on the peer certificate","text":"<p>Dropping <code>KEEP_PEER_CERTIFICATE</code> means <code>mbedtls_ssl_get_peer_cert()</code> returns NULL after the handshake. Chain validation still happens -- only retention of the parsed leaf changes. This firmware verifies against a CA (<code>GTS_ROOT_R4</code> / the bundle) and never inspects the peer certificate or a fingerprint, so it should be safe. It does change <code>mbedtls_ssl_session</code> layout, which is exactly why the whole framework must be rebuilt together rather than swapping a single archive in.</p>"},{"location":"mbedtls-tls-footprint/#build-procedure","title":"Build procedure","text":""},{"location":"mbedtls-tls-footprint/#do-not-use-esp32-arduino-lib-builder-for-this","title":"Do not use esp32-arduino-lib-builder for this","text":"<p><code>release/v4.4</code> is the branch matching Arduino 2.0.x, but its <code>update-components.sh</code> clones every dependency at master, so it no longer resolves. Five successive failures, each a different repo: the arduino branch name it passes to <code>-A</code> does not exist; <code>jq</code> is absent from the IDF image and its absence makes <code>build.sh</code>'s target loop a silent no-op that still exits 0; <code>esp_littlefs</code> and <code>esp32-camera</code> master require IDF &gt;=5.0/&gt;=5.1; <code>esp32-camera</code> later needs an <code>esp_jpeg</code> version the 4.4 registry cannot satisfy; and tinyusb's source layout no longer matches <code>arduino_tinyusb/CMakeLists.txt</code>. Pinning each one in turn just surfaces the next.</p>"},{"location":"mbedtls-tls-footprint/#rebuild-only-the-mbedtls-archives","title":"Rebuild only the mbedTLS archives","text":"<p>More rigorous anyway, because it reuses the shipped <code>sdkconfig</code> verbatim -- so the archives differ from stock only by the intended change, with no arduino-version or <code>DYNAMIC_BUFFER</code> drift.</p> <p>This is ABI-safe for the content-length change specifically: <code>ssl.h</code> declares <code>in_buf</code> and <code>out_buf</code> as <code>unsigned char *</code>, allocated in <code>ssl_setup()</code>, and no public struct embeds a CONTENT_LEN-sized array. The other precompiled archives (esp-tls, esp_http_client, esp-mqtt) therefore remain compatible. It is not safe for <code>CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE</code>, which changes <code>mbedtls_ssl_session</code> layout -- that one needs everything rebuilt together, so it is excluded here.</p> <ol> <li>Minimal IDF project whose only component requirement is <code>mbedtls</code>.</li> <li><code>sdkconfig.defaults</code> = the shipped    <code>packages/framework-arduinoespressif32/tools/sdk/esp32s3/sdkconfig</code>, with    <code>CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN=16384</code> replaced by the three asymmetric lines.    Verify the diff is exactly 5 lines before building.</li> <li><code>docker run --rm -v $PWD:/project -w /project espressif/idf:v4.4.7 idf.py -DIDF_TARGET=esp32s3 build</code></li> <li>Confirm <code>build/config/sdkconfig.h</code> carries <code>OUT_CONTENT_LEN 4096</code>.</li> <li>Stage the four archives under the framework's names -- note the rename:</li> </ol> built framework name stock size rebuilt <code>esp-idf/mbedtls/libmbedtls.a</code> <code>libmbedtls.a</code> 113,914 113,338 <code>esp-idf/mbedtls/mbedtls/library/libmbedtls.a</code> <code>libmbedtls_2.a</code> 1,252,150 1,245,718 <code>.../libmbedcrypto.a</code> <code>libmbedcrypto.a</code> 4,302,698 4,259,458 <code>.../libmbedx509.a</code> <code>libmbedx509.a</code> 676,590 673,318 <p>All within ~1% of stock, which is a good check that only the config differs.</p>"},{"location":"mbedtls-tls-footprint/#wire-it-in-with-l-never-platform_packages","title":"Wire it in with -L, never platform_packages","text":"<pre><code>PLATFORMIO_BUILD_FLAGS=\"-L/path/to/staged/archives\" pio run -e Heltec_v3_repeater_observer_mqtt\n</code></pre> <p>Verify with <code>grep -oE \"[^ ]*libmbed[a-z0-9_]*\\.a\" .pio/build/&lt;env&gt;/firmware.map | sort -u</code> -- every path must be the staged directory.</p> <p>Do not point <code>platform_packages</code> at a <code>file://</code> copy of the framework. PlatformIO installs it over the shared <code>~/.platformio/packages/framework-arduinoespressif32</code>, silently changing mbedTLS for every other ESP32 env and project on the machine. It does this even when the copy's <code>package.json</code> version differs -- verified twice here, and both times the fix was <code>rm -rf</code> the package and <code>pio pkg install</code> to re-download stock. A prepended library search path keeps the change scoped to one env, because the linker takes each archive member from the first archive that satisfies an undefined symbol.</p>"},{"location":"mbedtls-tls-footprint/#how-to-verify-it-worked","title":"How to verify it worked","text":"<ol> <li><code>strings</code>/<code>grep</code> the new <code>sdkconfig.h</code> for the four settings.</li> <li>Build and check the RAM figure; static usage should be unchanged (these are heap buffers).</li> <li>On hardware, <code>get mqtt.stats</code> at boot with two slots connected: the largest free block    should start roughly 24-32 KiB higher than the current 62-67 KiB.</li> <li>Soak across reconnect cycles and compare the floor against the two recorded runs:    baseline settled 16,372 (cycle 11); <code>softDisconnect</code> holds 36,852 (cycle 16).</li> </ol>"},{"location":"mbedtls-tls-footprint/#prior-art-in-this-investigation","title":"Prior art in this investigation","text":"<p><code>.scratch/mqtt-non-psram-heap-staircase-analysis-2026-08-05.md</code> (untracked -- <code>.scratch/</code> is globally gitignored) holds the full allocation inventory. <code>~/mqtt-soak/STATE.md</code> holds the soak evidence, including two retracted hypotheses worth not repeating: the perf commits were not the cause, and waev does not cap connections per IP.</p>"},{"location":"mixed_scan_validation/","title":"Mixed-bandwidth two-channel reception test","text":"<p>V4 transmitter on MercerWoodMesh; XIAO ESP32-S3/Wio SX1262 receiver. Channel 0: 909.5 MHz, SF7/62.5 kHz, preamble 32. Channel 1: 910.5 MHz, 500 kHz, SF and preamble below. Both use CR4/5, explicit header, CRC and 64-byte test payloads. Fast RX-preamble scanning uses four symbols of the active profile per visit, not four simultaneous channels or hardware CAD.</p> <p>Each setting starts with a five-packet-per-channel continuous-RX baseline. Scanning sends 50 packets per channel in shuffled order with random host delays. Only CRC-valid, payload-validated, sequence-matched packets count. Any scan loss escalates the 500 kHz preamble by 16, capped at 128. SF9 and SF8 start at 32; SF7 starts at 48. An additional SF8/40 test was requested after SF8/48; its firmware adds acceptance of preamble 40 without changing radio timing or scanning behavior.</p> 500 kHz SF Preamble Mode SF7/62.5 received 500 kHz received Mean scan cycle SF9 32 Fixed baseline 5/5 5/5 \u2014 SF9 32 Scan 50/50 50/50 14.676 ms SF8 32 Fixed baseline 5/5 5/5 \u2014 SF8 32 Scan 50/50 49/50 12.628 ms SF8 48 Fixed baseline 5/5 5/5 \u2014 SF8 48 Scan 50/50 50/50 12.629 ms SF8 40 Fixed baseline 5/5 5/5 \u2014 SF8 40 Scan 50/50 49/50 12.630 ms SF7 48 Fixed baseline 5/5 5/5 \u2014 SF7 48 Scan 50/50 50/50 11.603 ms <p>These are strong-signal, sequential-transmission lab results. Successful reception of 50 packets is not proof of zero loss over months. The receiver remains on one channel through an entire detected packet, so overlapping traffic on the other channel can be lost. Scan-cycle measurements exclude time occupied by packet reception; USB command handling can add timing outliers.</p> <p>Machine-readable counts, timings and firmware/source hashes: mixed_scan_results.json.</p> <p>After testing, both boards were restored to their original B soak firmware using app-only flashes. Version and normal radio settings were verified on both boards; Wi-Fi was connected and MQTT reported <code>custom (ok)</code>. Both persistent soak loggers were restarted in phase <code>B-post-CAD-soak</code>, marking the intentional uptime reset.</p>"},{"location":"mixed_sf_bw_validation/","title":"Equal-symbol-time mixed SF/BW, four-channel test","text":"<p>2026-09-14. Promising, but no strict 400/400 pass. With no added settling, the mixed scanner received 61 consecutive packets on the correct channels, then timed out on packet 62. The near-ceiling +22.4 ms setting received four packets and timed out on the fifth. There were no wrong-channel payloads in either run. Both stopped on the first miss without retries.</p>"},{"location":"mixed_sf_bw_validation/#configuration","title":"Configuration","text":"Channel Center (MHz) SF BW (kHz) Symbol time (ms) 0 909.5 9 62.5 8.192 1 910.5 10 125 8.192 2 911.5 11 250 8.192 3 912.5 12 500 8.192 <p>These preserve the preceding SF10/125 symbol duration exactly, rather than approximately: <code>symbol_us = 2^SF * 1000 / BW_kHz</code>. The supported SF/BW values and symbol-rate equation are specified in Semtech's SX1261/2 datasheet, sections 6.1.1.1\u20132. Equal symbol durations do not imply equal payload airtime or sensitivity.</p> <ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, MAC 28:84:85:B4:09:80.</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, serial B35E71C1C3726CE7.</li> <li>Normal RX gain 0x94, -9 dBm TX chip request, CR4/5, 32-symbol preamble,   16-byte CHS1 packets, 1 MHz channel spacing. No extra IRQ tracing/polling.</li> <li>5.1-symbol visits = 41,780 us; programmed preamble = 262,144 us.</li> <li>Double frequency write retained, warm XOSC, bulk SPI and fast RX restart.   SF/BW changes on every hop, so one 0x8B command is required on every hop.</li> <li>Goal per setting: 100 packets/channel, 400 total, strict channel identity.   No relaxed off-channel acceptance and no automatic channel-count expansion.</li> </ul> <p>The lab scanner stages four channels through the existing two production profile slots; this does not change the public two-profile protocol.</p>"},{"location":"mixed_sf_bw_validation/#positive-controls","title":"Positive controls","text":"<p>Before scanning, each profile received ten fixed-frequency probes after full normal initialization. All four passed 10/10, forty total. Zero frequency commands occurred after each setup; no stationary receiver hardware failure. These are fresh ten-packet controls, not claims of 100/100 on each new profile.</p> <p>Both devices acknowledge the same exact modulation table through <code>mixinfo</code>. Transmitter results verify SF, fractional BW, center, sequence and packet size. RX records verify center-command word and SF/BW at packet read. Full expected payload identity and CRC remain required. Mode/cache errors are treated as fixture failures rather than ordinary RF misses.</p>"},{"location":"mixed_sf_bw_validation/#timing-controls-and-settling-budget","title":"Timing controls and settling budget","text":"<p>Six-second RX-only window at zero added delay: 141 hops, mean 637.922 us, maximum 828 us. The largest 100 us delay step with a 500 us per-hop reserve is <code>floor((262144/4 - 41780 - 828 - 500)/100)*100 = 22400 us</code>.</p> <p>The +22,400 us RX-only verification window measured 87 hops, mean 638.241 us, maximum 833 us. Nineteen complete idle cycles measured mean 259,292.789 us, maximum 259,310 us, below the 262,144 us preamble. Every hop had two observed frequency commands and one modulation command, with no mode/cache/RX errors.</p> <p>This is an empirical near-ceiling budget, not a guarantee of acquisition for every arrival phase. Longer packet holds and software jitter can defeat the idle-cycle calculation. RX is active throughout added settling.</p>"},{"location":"mixed_sf_bw_validation/#four-channel-results","title":"Four-channel results","text":"Added settling Strict received / attempted before first miss Failed TX profile Mean switch (us) Max switch (us) Max idle cycle (us) 22,400 us 4 / 5 Channel 2, SF11/250 660.951 892 259391 0 us 61 / 62 Channel 0, SF9/62.5 674.819 899 169798 <p>Both failures were timeouts, with TX rc=0, RX mode=1, device errors=0. Both runs had zero mode/cache/receive errors and zero off-channel payloads. The +22.4 ms run exercised 163 hops, 326 frequency commands and 163 modulation commands. Zero-delay exercised 718 hops, 1,436 frequency commands and 718 modulation commands. Optimized RX resume counts equaled hop counts.</p> <p>No-delay per-channel counts at stop:</p> Channel Received Attempted Good-packet mean RSSI (dBm) Good-packet mean SNR (dB) 0 15 16 -34.00 11.15 1 16 16 -33.69 8.24 2 15 15 -34.33 5.78 3 15 15 -33.27 3.47 <p>The receiver stayed longer on some visits: maximum held visit 582,993 us with settling, 580,577 us without. Held-visit statistics include successful packet reception, so these maxima alone do not prove false off-channel preamble holds in this experiment. No IRQ trace was collected for the two failures; their precise mechanism is not established.</p> <p>The longer success sequence and absence of wrong-channel payloads are encouraging relative to the earlier uniform-SF/BW tests, but do not establish a statistically measured improvement or zero-loss reliability. Each setting was censored at first failure; do not present 61/62 as an unbiased measured packet-delivery rate or either run as a completed 400-packet test. The random arrival method is seeded, not RF-phase synchronized across configurations.</p>"},{"location":"mixed_sf_bw_validation/#implementation-verification-and-final-state","title":"Implementation, verification and final state","text":"<p>HIL-only <code>ProfileMixedChannels.h</code>, <code>basemixed</code>, <code>mixtx</code>, <code>scanmixed</code> and <code>profile_switch_mixed.py</code> add the bounded experiment. Uniform modes preserve their defaults. Post-hop checks use the actual per-channel modulation; the uniform collector and settling evidence checks reject mixed-mode results. Receive ownership, packet guards, BUSY and command-error handling remain intact.</p> <p>17 native profile tests and 48 HIL host tests passed. Tests cover fractional 62.5 kHz, equal symbol duration, table identity, normal uniform mapping, required modulation writes, TX replay, and wrong-policy rejection. Both firmware builds and normal uploads succeeded. The nRF52 ZIP is application- only, SoftDevice ID 0x0123; no bootloader or SoftDevice replacement. RAK COM29 was not opened. Production settings/source were not changed this turn.</p> <p>Both boards rebooted idle after the second failed setting, with test firmware retained. No autonomous TX, background collectors or restoration. Temporary PlatformIO overlay removed. No commit or push was requested. Existing unrelated working-tree changes remain intact. <code>git diff --check</code> passed apart from unrelated pre-existing CRLF warnings.</p>"},{"location":"mixed_sf_bw_validation/#provenance","title":"Provenance","text":"<p>Raw capture: <code>tools/hil/profile_switch_mixed_equal_symbols_results.json</code>. It includes the four baselines, two timing controls and two strict scans, with <code>complete:true</code>, <code>stopped:both_delay_controls_failed</code>, and no fixture or cleanup errors. Earlier captures were not rewritten.</p> <ul> <li>Raw SHA-256: <code>49de5c6415b1becdca02bc6e3c72d5e55127e92e758bbe3ac6c342c89e3723dd</code></li> <li>RX BIN SHA-256: <code>20d3008ef3d92610510748f64ac90c327f37c91d96cd3ac55272a918867fd5d0</code></li> <li>TX ZIP SHA-256: <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> <li>TX HEX SHA-256: <code>1225bcc70854a224f2862443d816b0e9216a253da87c42e96569a933204af941</code></li> </ul> <p>RX build reported 94,844 bytes RAM / 367,537 bytes flash. TX reported 18,220 / 95,908 bytes. Source is keymindCascade commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> plus existing uncommitted work and these HIL changes; this is not a clean-release comparison.</p>"},{"location":"nimble_companion_trial/","title":"ESP32-S3 NimBLE Full Companion trial","text":"<p>These optional builds use NimBLE-Arduino 2.5.1 with the existing ESP32 Arduino 2.0.17 toolchain. They are hardware qualification builds, outside the normal release matrix and firmware picker.</p> <p>See the 2026-09-08 hardware results for measured RAM, MAC-policy checks, WiFi updates, and remaining qualification.</p> <p>The contact-cache guide adds six optional 350-contact trials for ESP32 boards without PSRAM, including Heltec V3. Their qualification results include linked RAM margins, V4/RAK hardware tests and the mOTA queue policy.</p> Hardware Trial environment Contacts Channels Offline queue Heltec V4.2/V4.3 OLED, FEM on <code>heltec_v4_2_v4_3_companion_radio_full_femon_nimble</code> 350 40 512 XIAO ESP32-S3 with WIO SX1262 <code>Xiao_S3_WIO_companion_radio_full_nimble</code> 350 40 256 <p>The XIAO profile uses WIO radio pins CS 41, DIO1 39, BUSY 40 and RESET 42. It is not the generic XIAO profile for separately wired radio modules. Both boards retain their parent Full Companion features, USB mOTA sender, WiFi update slots, and PSRAM-backed offline queue. The V4 also retains direct MQTT.</p> <p>The small-screen message layout uses 6-pixel capitals on 128x64 panels and 5-pixel capitals on very tiny panels. It includes a compact channel/sender line and full message previews. Font selection is automatic.</p>"},{"location":"nimble_companion_trial/#build","title":"Build","text":"<p>Enable the optional configuration in the ignored <code>platformio.local.ini</code>:</p> <pre><code>[platformio]\nextra_configs =\n  variants/*/platformio.ini\n  platformio.nimble.ini\n</code></pre> <p>If that file already contains local settings, merge this list with them. Run one PlatformIO/build.sh command at a time. Both commands below use USA Cascade:</p> <pre><code>OUTPUT_DIR=.releases/nimble-v4 bash build.sh build-firmware \\\n  heltec_v4_2_v4_3_companion_radio_full_femon_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-nimble-test \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n\nOUTPUT_DIR=.releases/nimble-xiao bash build.sh build-firmware \\\n  Xiao_S3_WIO_companion_radio_full_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-nimble-test \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n</code></pre> <p>Use the merged image at address 0 for a USB installation. The V4 uses 16 MB flash; the XIAO uses 8 MB. Both use DIO flash mode. Use the application-only <code>.bin</code> for an existing, matching WiFi OTA layout. Remove the optional config entry when finished to return to the ordinary release matrix.</p>"},{"location":"nimble_companion_trial/#bluetooth-identity-and-pairing","title":"Bluetooth identity and pairing","text":"<p>All existing MAC settings remain available from the ASCII USB terminal and the app's authenticated local CLI. A setting takes effect after reboot.</p> Command Behavior <code>get bluetooth.mac</code> Show the saved MAC policy. <code>set bluetooth.mac C2:17:15:04:00:01</code> Use this custom random-static address. <code>set bluetooth.mac random</code> Generate one address and retain it across boots. <code>set bluetooth.mac random-every-boot</code> Generate a new address on each boot. <code>set bluetooth.mac random-after-connect</code> Rotate on the next boot after an authenticated connection; otherwise retain the address. <code>set bluetooth.mac default</code> Restore the factory Bluetooth address. <code>set bluetooth.stealth on</code> Pair once, then accept the saved bonded peer. <code>set bluetooth.stealth off</code> Restore ordinary discovery without changing the MAC policy. <code>get bluetooth.stealth</code> Show pairing or bonded-peer-only state. <p>The <code>ble.mac</code> and <code>ble.stealth</code> aliases also work. A literal custom address must be a valid BLE random-static address (first byte C0-FF). Forget the old entry in the phone's Bluetooth settings and pair again after an address change or switching Bluetooth libraries. Existing Bluedroid bonds are not migrated.</p> <p>Stealth does not disable the selected rotation policy. If rotation changes the address on reboot, first pairing opens again for the new identity.</p> <p>Pairing requires encryption, PIN authentication and a stored bond. NimBLE's controller byte order is converted explicitly, so a custom address appears over the air in the order entered. Failed identity setup stops advertising and retries initialization instead of advertising the wrong address.</p>"},{"location":"nimble_companion_trial/#v4-wifi-setup-qr","title":"V4 WiFi setup QR","text":"<p>The active WiFi setup page displays a compact QR code with a one-pixel white border. The normal open setup network fits a 44 x 44 pixel code, with 2 x 2 pixel modules. The SSID, portal address and <code>HOLD STOP</code> hint remain beside it. Short-click to leave the page; hold the button on this page to start or stop the setup AP. From USB, <code>start webconfig ap</code> starts the same setup session.</p> <p>When the setup AP is inactive and the node has joined WiFi, this page shows <code>WIFI CONNECTED</code>, <code>IP &lt;address&gt;</code>, <code>SETUP AP INACTIVE</code>, then <code>HOLD START AP</code> from top to bottom. The address appears once assigned and clears when the station disconnects. While the setup AP is active, the QR page shows the setup portal's address instead.</p>"},{"location":"nimble_companion_trial/#regression-checks","title":"Regression checks","text":"<pre><code>python3 -B test/test_nimble_companion.py\npython3 -B test/test_bluetooth_mac_contract.py\npython3 -B test/test_bluetooth_pairing_ui.py\npython3 -B test/test_heltec_v4_wifi_setup_page.py\npython3 -B test/test_firmware_ram.py\npython3 -B test/test_esp32_dram.py\npython3 -B test/test_shared_mota_queue.py\npython3 -B test/test_companion_mqtt_stack.py\npio test -e native -f test_companion_node_prefs \\\n  -f test_ble_tx_stall_watchdog -f test_companion_frame_queue \\\n  -f test_display_driver\n</code></pre> <p>The adapter test compiles the actual transport under address/undefined-behavior sanitizers with API doubles. It injects allocation, identity and bond failures; checks PIN authentication and stealth; and exercises 176-byte frames, MTU and notification subscription gating, retry and duplicate prevention. Embedded builds compile against the pinned real library. RAM reports retain the existing wireless budget; linked headroom is not a measurement of live free heap. The MQTT save callback also has a compiler-enforced stack-frame regression check: nested preference copies previously overflowed the V4 loop task when saving MQTT settings through WebConfig, despite sufficient free heap.</p> <p>Hardware qualification must additionally verify pairing and reconnection, advertised addresses for every MAC policy, contact synchronization, WiFi/BLE coexistence, and uptime under load. BlueZ results do not establish iOS or Android camera/pairing compatibility.</p>"},{"location":"nimble_companion_trial_results/","title":"ESP32-S3 NimBLE trial results, 2026-09-08","text":"<p>These are local hardware trial results for USA Cascade Full Companions on a Heltec V4.3 OLED and a Seeed XIAO ESP32-S3 with WIO SX1262. The V4.2 shares the profile but was not physically tested. Build and command instructions are in the trial guide.</p> <p>The final source revision is <code>9dbab431</code>, using NimBLE-Arduino 2.5.1 and the existing Arduino-ESP32 2.0.17 toolchain. These optional profiles are outside the ordinary release matrix. This trial does not change GitHub release assets or the firmware picker.</p>"},{"location":"nimble_companion_trial_results/#capacity","title":"Capacity","text":"Measurement Heltec V4 XIAO S3 WIO Contacts / channels 350 / 40 350 / 40 PSRAM-backed offline queue 512 256 Application image, bytes 1,774,600 1,510,536 OTA application slot, bytes 6,553,600 3,342,336 Linked internal capacity before runtime allocation, bytes 263,944 265,576 Required runtime RAM budget, bytes 173,056 148,480 Headroom beyond that budget, bytes 90,888 117,096 Live free heap with Bluetooth and 350 test contacts, bytes 142,644 147,444 Minimum free heap during that contact test, bytes 138,024 142,788 <p>The live contact-test readings are from revision <code>7f1bd8b1</code>. Revision <code>9dbab431</code> retains the same Bluetooth adapter, contact allocation and queue sizes, and fixes the MQTT save stack use described below. Linked capacity is not live free heap; the firmware memory reports label that distinction.</p> <p>A matching V4 build using Bluedroid had 248,840 bytes of linked internal capacity. NimBLE recovers 15,104 bytes at link time. The matching Bluedroid application was 2,169,848 bytes. There was no matching physical Bluedroid heap measurement, so these figures do not establish a live heap saving.</p>"},{"location":"nimble_companion_trial_results/#bluetooth-hardware-checks","title":"Bluetooth hardware checks","text":"<p>Both boards passed the following cases with BlueZ on the Mercerwood Pi:</p> <ul> <li>PIN authentication, encryption, stored bonding, and bonded reconnection.</li> <li>MTU 179; accepted 176-byte writes and complete 148-byte contact notifications.</li> <li>Insert and synchronize all 350 synthetic contacts without missing or   duplicate entries.</li> <li>Custom MAC address appears over the air in the entered byte order and   persists across reboots.</li> <li>Saved random MAC persists; random-every-boot changes on each boot.</li> <li>Random-after-connect retains its address through an unauthenticated boot   and rotates on the boot following an authenticated connection.</li> <li>Stealth first pairing, bonded-peer reconnection, and reconnection after   reboot with a stable identity.</li> <li>Restore factory MAC and ordinary discovery.</li> <li>Three reconnect samples with no observed downward free-heap trend.</li> </ul> <p>The complete MAC suite ran on <code>7f1bd8b1</code>. Final-image connection and update checks also verify the unchanged adapter after the MQTT stack fix. Synthetic contacts were removed after testing; factory MAC mode and stealth off were restored.</p>"},{"location":"nimble_companion_trial_results/#mqtt-save-stack-overflow","title":"MQTT save stack overflow","text":"<p>The V4 test reproduced an actual reset while saving MQTT settings through WebConfig. Serial output identified <code>Stack canary watchpoint triggered (loopTask)</code>. <code>onConfigBatchEnd()</code> kept a second 2.8 KB preference copy while the loader and NVS code also used stack space. Free heap was not the limiting resource.</p> <p>The loader already updates its destination only after validation, so the callback now passes the live preference object directly. The actual Xtensa callback frame shrank from 2,928 bytes to 32 bytes. The regression test compiles the real callback with a 512-byte frame ceiling and demonstrates that the previous nested-copy implementation fails the check.</p> <p>On the corrected <code>9dbab431</code> image, the 11-setting WebConfig batch completed with all entries accepted and no reboot. The V4 connected to a local Mosquitto broker, published MQTT traffic, and kept its authenticated Bluetooth session alive through a 30-second load interval with continuous uptime and zero reported error flags. Free heap measured 120,684 then 122,140 bytes; the minimum was 118,332 bytes and the largest free block was 110,580 bytes. Disabling the test MQTT slot also completed successfully without reboot.</p>"},{"location":"nimble_companion_trial_results/#wifi-updates-and-qr","title":"WiFi updates and QR","text":"<p>Both boards completed real application-image uploads over WiFi with Bluetooth connected, followed by reboot and reconnection using the saved bond. Repeated HTTP page requests and Bluetooth status requests ran together before upload. The image hash was checked before transmission, and the running firmware version was checked after reboot.</p> <p>The V4 WiFi setup page again contains a QR code. The default open setup SSID fits a 44 x 44 pixel code: 2 x 2 pixel modules and an exact one-pixel white border. The native test rendered the actual display/QRCode code and decoded the result with ZXing. SSID, portal address and the hold-to-stop hint fit beside it. Physical phone-camera scanning has not been verified.</p>"},{"location":"nimble_companion_trial_results/#observed-limits","title":"Observed limits","text":"<p>One XIAO warm reboot left its USB endpoint unresponsive while Bluetooth still answered. The user's physical unplug/replug restored USB; the later full MAC suite completed its commanded reboots successfully. The cause of that one USB failure is unconfirmed.</p> <p>The XIAO initially failed to associate with the saved WiFi network. Reapplying the SSID scheduled a fresh connection, after which it joined at -53 dBm and completed WiFi OTA. No antenna change was needed for that recovery.</p> <p>This was functional hardware testing, not a long-duration soak. iOS/Android app pairing, phone camera scanning, multiple TLS MQTT brokers, and an end-to-end LoRa mOTA transfer were not qualified in this trial. The XIAO parent profile does not include direct MQTT; the V4 does.</p>"},{"location":"nimble_companion_trial_results/#final-application-hashes","title":"Final application hashes","text":"Hardware SHA-256 V4 <code>e6a1522ced4ed38ddd00e7cdf8393857224adbb622888a86370c0f7a3ee28d88</code> XIAO S3 WIO <code>ecf7afe6222e3897556a04e022515f9dcfcb825172dae9eaaa72eb92396dd004</code>"},{"location":"nrf52-usb-ready-fix/","title":"nRF52 USB READY hang","text":"<p>The RAK3401 on Mercer was found stuck in the framework's TinyUSB power handler: USBD was enabled and attached, but its write-one-to-clear READY event was already consumed. The duplicate-event guard also required HFCLK to be running. If that guard missed the completed initialization, the following unbounded READY wait could stop application startup. A bootloader update alone cannot replace this USB driver in an already installed MeshCore application.</p> <p>The wait and guard were inherited through the pinned Adafruit nRF52 Arduino framework, not introduced by the recent OTAFIX upstream merge. TinyUSB's wait dates back at least to 2019; the guard was added in upstream commit 7d9efd0697. OTAFIX's August 24 HFCLK backport addressed a later clock wait, leaving this earlier READY wait uncovered. The exact live interrupt ordering is not known; the stalled program counter and consumed event were read directly over SWD.</p> <p>All nRF52 environments inherit <code>pre:scripts/nrf52_usb_power_fix.py</code>. It compiles a build-local replacement for the matching framework driver, without changing PlatformIO's shared SDK or affecting ESP32 builds. A changed/unrecognized framework implementation stops the build for review. The backport:</p> <ul> <li>requests HFCLK before checking the consumed READY event;</li> <li>rechecks attachment while waiting, including completion by another callback;</li> <li>bounds both waits with one 100,000-poll budget, independent of OS ticks;</li> <li>ignores stale READY on a disabled peripheral and exits if it is removed.</li> </ul> <p>The poll budget is an iteration limit, not a promised elapsed-time timeout. If the clock/peripheral never becomes ready, the caller returns instead of freezing the application. A later power event can retry; permanent electrical failure can still require reconnecting USB. This does not establish or fix the separate Pi hub/controller fault.</p> <p>Run <code>python3 -B test/test_nrf52_usb_power.py -v</code>. The tests compile the actual patched handler from the pinned-framework fixture, model W1C event semantics, and cover duplicate/nested callbacks, delayed/missing clocks and READY, removal, retry, and detached USB. Restoring the inherited READY prefix must reproduce the infinite wait under a subprocess deadline. Additional tests check SDK isolation, idempotence, fail-closed patching, and all nRF52 environment hooks. The harness is shared with OTAFIX's TinyUSB fork at <code>test/otafix/nrf5x_power_test.py</code>; keep the two copies in sync when extending it.</p>"},{"location":"nrf52_companion_storage_recovery/","title":"nRF52 Companion automatic ExtraFS recovery","text":"<p>Companion builds using internal ExtraFS reserve 100 KiB at <code>0xD4000..0xED000</code>. Identity and preferences remain in the separate 28 KiB primary store at <code>0xED000..0xF4000</code>. This applies to internal-ExtraFS Companion builds, including Full, not repeaters or external QSPI storage.</p> <p>At startup the firmware:</p> <ol> <li>Mounts primary storage without erasing nonblank media. Only proven-blank    primary storage may be initialized automatically.</li> <li>Checks the exact ExtraFS address, size, block geometry, and application    linker reservation, then attempts a non-formatting secondary mount.</li> <li>Validates primary filesystem metadata before any destructive secondary    recovery. An unavailable primary store blocks recovery and identity replacement.</li> <li>Keeps an already mounted, metadata-valid ExtraFS unchanged. If its initial    mount or validation failed, unmounts and retries once without formatting.</li> <li>If the retry remains unusable, automatically formats only the reserved    100 KiB region, then remounts and validates it. There is one format attempt    per boot; failure keeps the contact/channel write quarantine active.</li> <li>Runs the existing verified migration from primary into ExtraFS. Primary    contact/channel sources are retired only after every destination is copied,    read back, and the migration transaction is committed. Identity and    preferences stay on primary.</li> </ol> <p>No terminal repair command, phone intervention, or bootloader update is needed for this recovery path when a compatible application/layout is already used. After successful recovery, the Companion storage API reports 100 KiB total rather than the 28 KiB primary fallback.</p>"},{"location":"nrf52_companion_storage_recovery/#data-loss-boundary","title":"Data-loss boundary","text":"<p>Automatic rebuilding prioritizes a usable contact/channel store over retaining an unreadable secondary filesystem. Data stored only in that damaged region can be lost. Surviving primary files are migrated, but may not contain the latest secondary-only changes. An API backup remains advisable before flashing. Primary storage is never formatted by this recovery path.</p> <p>This is mount/metadata recovery, not forensic file recovery. An invalid migration journal, unreadable individual contact page, primary-source error, full filesystem, or failed migration cleanup does not on its own trigger a format of a mountable, metadata-valid secondary store. Those cases retain the existing validation, retry, and incomplete-load protections.</p>"},{"location":"nrf52_companion_storage_recovery/#regression-coverage","title":"Regression coverage","text":"<p><code>test/test_internal_secondary_fs_repair</code> exercises healthy/no-format startup, successful remount, failed remount/traversal followed by one repair, and format/remount/validation failure. <code>test/test_nrf52_extrafs_contract.py</code> checks primary-first ordering, internal-only geometry guards, quarantine handling, and the separation between migration failures and destructive recovery.</p>"},{"location":"nrf52_companion_storage_recovery/#t1000-e-hardware-qualification-2026-09-03","title":"T1000-E hardware qualification (2026-09-03)","text":"<p>A device reporting 25/28 KiB primary fallback and contact enumeration error 5 was flashed with the recovery build. With no explicit repair command, startup activated 100 KiB ExtraFS and loaded all 125 contacts and 40 channel slots. Identity, preferences, radio settings, and channels matched the pre-update API snapshot. Add, edit, and delete of an owned temporary contact each survived a separate normal reboot; the device ended with the original 125 contacts and 27/100 KiB usage. The 161 offline/native regression tests and target build passed.</p> <p>This was not lossless recovery of every historical RAM value: 21 contacts had older advertisement/local-modification timestamps, including one older advertised location. No contact was missing, and no computer-backup restoration was used. A subsequent read-only scan found no readable cached advert for any of the 125 contacts. Without a surviving newer copy, firmware cannot infer those earlier values; receiving new verified advertisements can refresh them normally.</p>"},{"location":"nrf52_power_management/","title":"nRF52 Power Management","text":""},{"location":"nrf52_power_management/#overview","title":"Overview","text":"<p>The nRF52 Power Management module provides battery protection features to prevent over-discharge, minimise likelihood of brownout and flash corruption conditions existing, and enable safe voltage-based recovery.</p>"},{"location":"nrf52_power_management/#features","title":"Features","text":""},{"location":"nrf52_power_management/#boot-voltage-protection","title":"Boot Voltage Protection","text":"<ul> <li>Checks battery voltage immediately after boot and before mesh operations commence</li> <li>If voltage is below a configurable threshold (e.g., 3300mV), the device configures voltage wake (LPCOMP + VBUS) and enters protective shutdown (SYSTEMOFF)</li> <li>Prevents boot loops when battery is critically low</li> <li>Skipped when external power (USB VBUS) is detected</li> </ul>"},{"location":"nrf52_power_management/#voltage-wake-lpcomp-vbus","title":"Voltage Wake (LPCOMP + VBUS)","text":"<ul> <li>Configures the nRF52's Low Power Comparator (LPCOMP) before entering SYSTEMOFF</li> <li>Enables USB VBUS detection so external power can wake the device</li> <li>Device automatically wakes when battery voltage rises above recovery threshold or when VBUS is detected</li> <li>Uses no LPCOMP hysteresis; on divided battery inputs the additional 50 mV   comparator hysteresis can move the effective battery wake point by several   hundred millivolts and strand an otherwise charged node</li> </ul>"},{"location":"nrf52_power_management/#early-boot-register-capture","title":"Early Boot Register Capture","text":"<ul> <li>Captures RESETREAS (reset reason) and GPREGRET2 (shutdown reason) before SystemInit() clears them</li> <li>Allows firmware to determine why it booted (cold boot, watchdog, LPCOMP wake, etc.)</li> <li>Allows firmware to determine why it last shut down (user request, low voltage, boot protection)</li> </ul>"},{"location":"nrf52_power_management/#shutdown-reason-tracking","title":"Shutdown Reason Tracking","text":"<p>Shutdown reason codes (stored in GPREGRET2):</p> Code Name Description 0x00 NONE Normal boot / no previous shutdown 0x4C LOW_VOLTAGE Runtime low voltage threshold reached 0x55 USER User requested powerOff() 0x42 BOOT_PROTECT Boot voltage protection triggered"},{"location":"nrf52_power_management/#supported-boards","title":"Supported Boards","text":"Board family Implemented LPCOMP wake VBUS wake Seeed Studio XIAO nRF52840 (<code>xiao_nrf52</code>) Yes Yes Yes SenseCAP Solar Yes Yes Yes RAK4631 / RAK3401 Yes Yes Yes GAT562 30S / EVB Pro / Tracker Pro / Watch13 Yes Yes Yes Heltec T096 / T114 / T1 / Tower V2 Yes Yes Yes Muzi Works R1 Neo Partial Inactive Inactive Promicro nRF52840 No No No RAK WisMesh Tag No No No Heltec Mesh Solar No No No LilyGo T-Echo / T-Echo Lite / T-Impulse Plus No No No WIO Tracker L1 / L1 E-Ink / WM1110 No No No Mesh Pocket / Meshtiny / Nano G2 Ultra No No No ThinkNode M1 / M3 / M6 No No No T1000-E No No No Ikoka Nano / Stick / Handheld (nRF) No No No Keepteen LT1 / Minewsemi ME25LS01 No No No <p>Notes: - \"Implemented\" reflects Phase 1 (boot lockout + shutdown reason capture). - R1 Neo has the integration compiled, but its board configuration deliberately   sets <code>PWRMGT_VOLTAGE_BOOTLOCK</code> to <code>0</code>; automatic protective shutdown and its   voltage/VBUS recovery wake are therefore inactive. - User power-off does not enable LPCOMP wake; voltage recovery is armed only   for boot protection and automated low-voltage shutdown. - VBUS detection is used to skip boot lockout on external power, and VBUS wake is configured alongside LPCOMP when supported hardware exposes VBUS to the nRF52.</p>"},{"location":"nrf52_power_management/#technical-details","title":"Technical Details","text":""},{"location":"nrf52_power_management/#architecture","title":"Architecture","text":"<p>The power management functionality is integrated into the <code>NRF52Board</code> base class in <code>src/helpers/NRF52Board.cpp</code>. Board variants provide hardware-specific configuration via a <code>PowerMgtConfig</code> struct and override <code>initiateShutdown(uint8_t reason)</code> to perform board-specific power-down work and conditionally enable voltage wake (LPCOMP + VBUS).</p>"},{"location":"nrf52_power_management/#early-boot-capture","title":"Early Boot Capture","text":"<p>A static constructor with priority 101 in <code>NRF52Board.cpp</code> captures the RESETREAS and GPREGRET2 registers before: - SystemInit() (priority 102) - which clears RESETREAS - Static C++ constructors (default priority 65535)</p> <p>This ensures we capture the true reset reason before any initialisation code runs.</p>"},{"location":"nrf52_power_management/#board-implementation","title":"Board Implementation","text":"<p>To enable power management on a board variant:</p> <ol> <li> <p>Enable in platformio.ini:    <code>ini    -D NRF52_POWER_MANAGEMENT</code></p> </li> <li> <p>Define configuration in variant.h:    <code>c    #define PWRMGT_VOLTAGE_BOOTLOCK    3300   // Won't boot below this voltage (mV)    #define PWRMGT_LPCOMP_AIN          7      // AIN channel for voltage sensing    #define PWRMGT_LPCOMP_REFSEL       2      // REFSEL (0-6=1/8..7/8, 7=ARef, 8-15=1/16..15/16)</code></p> </li> <li> <p>Implement in board .cpp file:    ```cpp    #ifdef NRF52_POWER_MANAGEMENT    const PowerMgtConfig power_config = {      .lpcomp_ain_channel = PWRMGT_LPCOMP_AIN,      .lpcomp_refsel = PWRMGT_LPCOMP_REFSEL,      .voltage_bootlock = PWRMGT_VOLTAGE_BOOTLOCK    };</p> </li> </ol> <p>void MyBoard::initiateShutdown(uint8_t reason) {      // Board-specific shutdown preparation (e.g., disable peripherals)      bool enable_lpcomp = (reason == SHUTDOWN_REASON_LOW_VOLTAGE ||                            reason == SHUTDOWN_REASON_BOOT_PROTECT);</p> <pre><code> if (enable_lpcomp) {\n   configureVoltageWake(power_config.lpcomp_ain_channel, power_config.lpcomp_refsel);\n }\n\n enterSystemOff(reason);\n</code></pre> <p>}    #endif</p> <p>void MyBoard::begin() {      NRF52Board::begin();  // or NRF52BoardDCDC::begin()      // ... board setup ...</p> <p>#ifdef NRF52_POWER_MANAGEMENT      checkBootVoltage(&amp;power_config);    #endif    }    ```</p> <p>For user-initiated shutdowns, <code>powerOff()</code> remains board-specific. Power management only arms LPCOMP for automated shutdown reasons (boot protection/low voltage).</p> <ol> <li>Declare override in board .h file:    <code>cpp    #ifdef NRF52_POWER_MANAGEMENT      void initiateShutdown(uint8_t reason) override;    #endif</code></li> </ol>"},{"location":"nrf52_power_management/#voltage-wake-configuration","title":"Voltage Wake Configuration","text":"<p>The LPCOMP (Low Power Comparator) is configured to: - Monitor the specified AIN channel (0-7 corresponding to P0.02-P0.05, P0.28-P0.31) - Compare against VDD fraction reference (REFSEL: 0-6=1/8..7/8, 7=ARef, 8-15=1/16..15/16) - Detect UP events (voltage rising above threshold) - Use no hysteresis so the configured recovery threshold is not widened by the battery divider - Wake the device from SYSTEMOFF when triggered</p> <p>VBUS wake is enabled via the POWER peripheral USBDETECTED event whenever <code>configureVoltageWake()</code> is used. This requires USB VBUS to be routed to the nRF52 (typical on nRF52840 boards with native USB).</p> <p>LPCOMP Reference Selection (PWRMGT_LPCOMP_REFSEL):</p> REFSEL Fraction VBAT @ 1M/1M divider (VDD=3.0-3.3) VBAT @ 1.5M/1M divider (VDD=3.0-3.3) 0 1/8 0.75-0.82 V 0.94-1.03 V 1 2/8 1.50-1.65 V 1.88-2.06 V 2 3/8 2.25-2.47 V 2.81-3.09 V 3 4/8 3.00-3.30 V 3.75-4.12 V 4 5/8 3.75-4.12 V 4.69-5.16 V 5 6/8 4.50-4.95 V 5.62-6.19 V 6 7/8 5.25-5.77 V 6.56-7.22 V 7 ARef - - 8 1/16 0.38-0.41 V 0.47-0.52 V 9 3/16 1.12-1.24 V 1.41-1.55 V 10 5/16 1.88-2.06 V 2.34-2.58 V 11 7/16 2.62-2.89 V 3.28-3.61 V 12 9/16 3.38-3.71 V 4.22-4.64 V 13 11/16 4.12-4.54 V 5.16-5.67 V 14 13/16 4.88-5.36 V 6.09-6.70 V 15 15/16 5.62-6.19 V 7.03-7.73 V <p>Important: For boards with a voltage divider on the battery sense pin, LPCOMP measures the divided voltage. Use: <code>VBAT_threshold ~ (VDD * fraction) * divider_scale</code>, where <code>divider_scale = (Rtop + Rbottom) / Rbottom</code> (e.g., 2.0 for 1M/1M, 2.5 for 1.5M/1M, 3.0 for XIAO).</p>"},{"location":"nrf52_power_management/#softdevice-compatibility","title":"SoftDevice Compatibility","text":"<p>The power management code checks whether SoftDevice is enabled and uses the appropriate API: - When SD enabled: <code>sd_power_*</code> functions - When SD disabled: Direct register access (NRF_POWER-&gt;*)</p> <p>This ensures compatibility regardless of BLE stack state.</p>"},{"location":"nrf52_power_management/#cli-commands","title":"CLI Commands","text":"<p>Power management status can be queried via the CLI:</p> Command Description <code>get pwrmgt.support</code> Returns \"supported\" or \"unsupported\" <code>get pwrmgt.source</code> Returns current power source - \"battery\" or \"external\" (5V/USB power) <code>get pwrmgt.bootreason</code> Returns reset and shutdown reason strings <code>get pwrmgt.bootmv</code> Returns boot voltage in millivolts <p>On boards without power management enabled, <code>get pwrmgt.source</code> and <code>get pwrmgt.bootmv</code> return:</p> <pre><code>ERROR: Power management not supported\n</code></pre> <p><code>get pwrmgt.support</code> returns <code>unsupported</code>. <code>get pwrmgt.bootreason</code> is not compiled out at all and answers on every board: <code>getResetReason()</code> and <code>getShutdownReason()</code> are virtuals on the base board class, so a board that does not override them reports <code>Not available</code> rather than an error. ESP32 boards override the reset half with <code>esp_reset_reason()</code>, so they return a real reset reason and <code>Not available</code> for the shutdown reason.</p>"},{"location":"nrf52_power_management/#debug-output","title":"Debug Output","text":"<p>When <code>MESH_DEBUG=1</code> is enabled, the power management module outputs:</p> <pre><code>DEBUG: PWRMGT: Reset = Wake from LPCOMP (0x20000); Shutdown = Low Voltage (0x4C)\nDEBUG: PWRMGT: Boot voltage = 3450 mV (threshold = 3300 mV)\nDEBUG: PWRMGT: LPCOMP wake configured (AIN7, ref=3/8 VDD)\n</code></pre>"},{"location":"nrf52_power_management/#phase-2-planned","title":"Phase 2 (Planned)","text":"<ul> <li>Runtime voltage monitoring</li> <li>Voltage state machine (Normal -&gt; Warning -&gt; Critical -&gt; Shutdown)</li> <li>Configurable thresholds</li> <li>Load shedding callbacks for power reduction</li> <li>Deep sleep integration</li> <li>Scheduled wake-up</li> <li>Extended sleep with periodic monitoring</li> </ul>"},{"location":"nrf52_power_management/#references","title":"References","text":"<ul> <li>nRF52840 Product Specification - POWER</li> <li>nRF52840 Product Specification - LPCOMP</li> <li>SoftDevice S140 API - Power Management</li> </ul>"},{"location":"number_allocations/","title":"Number Allocations","text":"<p>This document lists unique numbers/identifiers used in various MeshCore protocol payloads.</p>"},{"location":"number_allocations/#group-data-types","title":"Group Data Types","text":"<p>The <code>PAYLOAD_TYPE_GRP_DATA</code> payloads have a 16-bit data-type field, which identifies which application the packet is for.</p> <p>To make sure multiple applications can function without interfering with each other, the table below is for reserving various ranges of data-type values. Just modify this table, adding a row, then submit a PR to have it authorised/merged.</p> <p>NOTE: the range FF00 - FFFF is for use while you're developing, doing POC, and for these you don't need to request to use/allocate.</p> <p>Once you have a working app/project, you need to be able to demonstrate it exists/works, and THEN request type IDs. So, just use the testing/dev range while developing, then request IDs before you transition to publishing your project.</p> Data-Type range App name Contact 0000 - 00FF -reserved for internal use- 0100 MeshCore Open zsylvester@monitormx.com - https://github.com/zjs81/meshcore-open 0110 - 011F Ripple ripple_biz@protonmail.com - https://buymeacoffee.com/ripplebiz 0120 MCO Advanced most.original.address@gmail.com - https://github.com/HDDen/meshcore-open/tree/rename-mco-advanced FF00 - FFFF -reserved for testing/dev- <p>(add rows, inside the range 0100 - FEFF for custom apps)</p>"},{"location":"ota_easy/","title":"Easy firmware updates over LoRa","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>This guide shows the shortest manual path for sending firmware from a computer to a MeshCore node over LoRa. Choose the package type for the destination node:</p> <p>For an end-to-end controller that accepts a release ZIP or ready mOTA, see Scripted LoRa OTA from start to finish.</p> Destination Update type Files needed to build the <code>.mota</code> Installer ESP32 Full firmware New non-merged application <code>.bin</code> ESP32 A/B firmware slots nRF52, internal staging In-place delta Exact running <code>firmware.hex</code> and new <code>firmware.hex</code> Exact-board OTAFIX bootloader Supported nRF52 QSPI repeater Full firmware or in-place delta New <code>firmware.hex</code>; a delta also needs the exact running <code>firmware.hex</code> Matching QSPI-aware OTAFIX bootloader MeshTower V2 SD target Full firmware or in-place delta New <code>firmware.hex</code>; a delta also needs the exact running <code>firmware.hex</code> Matching SD-aware OTAFIX bootloader <p>An internal-staging nRF52 target accepts only an in-place delta built against its exact running firmware. Matched QSPI repeater targets and the MeshTower V2 microSD target can also install a full image because the complete container stays off-chip. See nRF52 repeater OTA with external QSPI and MeshTower V2 microSD LoRa OTA.</p> <p>MeshTower V2 microSD application and bootloader containers must be Ed25519-signed by a key in the device allowlist; pass <code>--sign</code> to <code>motatool build</code> (or <code>--sign-key</code> to the end-to-end runner) when building one. Its BLM2-capable SD-aware bootloader is also required before ordinary application or bootloader OTA can use the reset-retained authorization record. Upgrade preview.12 locally over USB/BLE DFU or SWD first; there is no raw-card compatibility handoff.</p>"},{"location":"ota_easy/#temporary-ota-channel-used-in-this-guide","title":"Temporary OTA channel used in this guide","text":"Setting Value Center frequency 910.525 MHz Bandwidth 250 kHz Spreading factor SF5 Coding rate used in this guide CR5 Example window 120 minutes <p>The copy/paste command is:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>The fourth value is the transmit coding rate. This guide uses CR5, but the participating nodes' coding rates do not need to match.</p> <p><code>tempradio</code> is not saved and the node returns to its normal radio settings when the window ends or the node reboots. Current full-parser firmware also accepts <code>normalradio</code>, which cancels the temporary window and restores the saved tuple after replying on the current channel. This frequency is intended for North American configurations. Confirm that it is permitted in your location and change it when necessary.</p> <p>At SF5/BW250, an SX1262+TCXO destination can keep RXPS enabled only when it and every sender that can reach it (controller, source, and relays) follow the v1.17.1.5-or-newer adaptive-preamble contract. The qualified destination boundary is effective level 8, preamble 64 and <code>1252 / 6424 us</code>. For manual setup, save <code>set radio.rxps level 8 preamble 32</code> before entering TempRadio; the <code>32</code> is a conservative saved timing assumption and current firmware selects the real 64-symbol wire preamble when it retunes the temporary radio. For an older, unknown, or mixed-version path, use <code>set radio.rxps off</code> for the maintenance window. First record <code>get radio.rxps.config</code>; after <code>normalradio</code>, restore a reported level with <code>set radio.rxps level N preamble P</code> (omit <code>preamble P</code> when <code>P</code> is <code>0</code>). A legacy node returns only on/off and periods, which can be restored with <code>set radio.rxps RX_US SLEEP_US</code>. The scripted runner performs the version checks, temporary change, verification, and restoration automatically while preserving automatic retuning. SF5/BW500 is too fast for RXPS even with a 64-symbol preamble, so current firmware selects 128 and uses the qualified level-8 <code>626 / 6398 us</code> timing when every participant supports the adaptive contract.</p>"},{"location":"ota_easy/#before-you-start","title":"Before you start","text":"<p>Both paths require:</p> <ul> <li>A destination artifact explicitly identified by its release table as install-capable. Some lean internal   nRF52 builds carry <code>lora_ota_no_external_sensors</code> in the filename, while matched QSPI boards enable install   support in the normal full-sensor repeater or room-server artifact, so filename text alone is not authoritative. Confirm   support with <code>ota self</code> and <code>ota status</code>. Intermediate repeaters do not need an install-capable build:   current repeater firmware relays OTA packets opaquely without storing or installing them.</li> <li>An OTA-enabled MeshCore source connected to the computer by USB serial, or   an ESP32 WiFi companion/FULL source connected over WiFi as described below.</li> <li>Overlapping <code>tempradio</code> windows on the source, destination, and every repeater needed between them.</li> </ul> <p>LoRa OTA packets are generated, consumed, and relayed only while <code>tempradio</code> is active. Intermediate repeaters apply their normal forwarding filters, duplicate checks, and flood limits; they do not interpret the OTA payload. If any required window closes, the transfer stops making progress and can resume during a later overlapping window.</p> <p><code>build.sh</code> provides a <code>*_repeater_lora_ota_no_external_sensors</code> or <code>*_room_server_lora_ota_no_external_sensors</code> build for standalone ESP32 and nRF52 infrastructure targets that need a smaller internal update workspace. Those siblings omit selected optional environmental and ranging drivers while retaining board-native features such as displays, buttons, battery monitoring, and GPS where the target uses the GPS-preserving lean profile. RAK3401 and RAK4631 reduced builds also retain INA219, INA226, INA260, and INA3221 I2C voltage/current monitors; together these drivers cost less than 5 KiB in the measured profile. Those four monitor drivers are not the only retained I2C support: the board's SSD1306 OLED, supported autodiscovered RTCs, and the RAK12500 GPS remain separate I2C peripherals in GPS-compatible RAK recipes. RAK12501/L76K GPS instead uses UART Serial1. The RAK3401 OTA repeater supports either GPS module in sensor slot A; slot D conflicts with the RAK13302 radio's BUSY/DIO1 lines. The RAK4631 OTA repeater defaults its runtime RS-232 bridge to Serial2 so the UART RAK12501 can retain Serial1. The runtime guard always reserves Serial1 because a bounded silent probe cannot prove a cold RAK12501 is absent; the shared WB_IO2/3V3_S rail keeps a fitted module powered and driving the UART. Use Serial2. Serial1 requires an explicit no-GPS/dedicated image. The merged image remains fail-closed even when it detects an I2C RAK12500. The explicit legacy Serial1 bridge omits the combined GPS provider, including the otherwise non-UART RAK12500 path.</p> <p>The firmware-configured INA3221 address and the RAK12500 address are both <code>0x42</code>; they cannot coexist on one bus at those addresses. Keep RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both are installed.</p> <p>Selected nRF52 boards with matched external QSPI application and bootloader support can instead make the normal full-sensor repeater or room-server install-capable; those targets do not need to reserve internal flash for the downloaded container. SolarXiao 30S and 33S use this matched external-QSPI path and therefore do not emit redundant no-external-sensors siblings. A RAK19007 can use the same separately wired W25Q16 with either RAK4631 or RAK3401 + RAK13302: the flash consumes no WisBlock slot and GPS remains supported in slot A. This is not the RAK15001 arrangement; RAK15001 and RAK13302 share a chip-select and cannot be used together. Other normal repeaters can still serve as intermediate relays but cannot necessarily install an update themselves. ESP32 <code>-ota-</code> siblings also retain the lightweight browser WiFi uploader (<code>start ota</code>), the complete CLI, and up to 254 neighbors; constrained targets use 50 as recorded in their capability manifests. RP2040 and STM32 repeaters do not currently have a safe self-apply path, but current repeater firmware can still relay OTA packets opaquely during TempRadio.</p> <p>For one explicitly selected internal-flash nRF52 repeater or room server, the default <code>--build-profile auto</code> run emits two install-capable choices. The <code>*-full-ota-*</code> artifact retains external sensors, while the <code>*_lora_ota_no_external_sensors-reduced-ota-*</code> artifact trades only those optional drivers not explicitly retained by the board profile for more delta-staging space. They retain the same OTA target identity so update tooling does not confuse the optimization choice with a different board. QSPI- and SD-backed repeater and room-server roles emit only the complete choice unless a measured size failure requires a fallback.</p> <p>nRF52 <code>-ota-</code> siblings are compiled with size optimization instead of the Adafruit platform's default speed optimization. This prevents the retained software Ed25519 fallback from expanding beyond the fixed in-place workspace; CC310 hardware crypto, hardware RNG mixing, telemetry history, and board-native features remain enabled.</p> <p>ESP32 <code>*-full-usb-wifi-ota-*</code> artifacts retain all compiled features and enable LoRa OTA for every FULL role, including room servers, sensors, observers, and bridges. A FULL image requires its expanded partition table: install the matching merged image over USB once before installing later non-merged FULL updates over LoRa. ESP32 MQTT observers and ESP-NOW bridges are always emitted as FULL artifacts; compact-CLI variants are no longer built. The <code>*-full-usb-wifi-ota-*</code> profile compiles USB packet logging and direct WiFi MQTT into one image. Use <code>set logging.output off|usb|wifi|both</code> to persist the desired path. A <code>*-full-logging-ota-*</code> artifact is now only a fallback for a hardware/role combination without a WiFi MQTT target and can produce substantial serial output.</p>"},{"location":"ota_easy/#choose-the-source-radio","title":"Choose the source radio","text":"<p>Use an OTA-enabled MeshCore node as the source. It receives the update folder from the computer, then advertises it over LoRa. ESP32 USB/WiFi companions and FULL ESP32 roles include the required transport. A <code>*_companion_radio_full</code> target keeps only the source half of LoRa OTA: it serves host images but cannot stage or install one for itself. ESP32 full combines USB, BLE, and WiFi; nRF52 full combines USB and BLE because nRF52840 has no WiFi. A small set of high-capacity, non-PSRAM classic ESP32 companions keep their normal image and provide a separate <code>-full-logging-ota-</code> fallback with 100 contacts, 8 group channels, a 16-frame offline queue, and persistent USB output selection. Install that variant's merged image over USB once before using it. Connect the source by USB serial or, when supported, by WiFi. For an ordinary raw-text USB source, confirm that its USB CLI accepts:</p> <pre><code>ota folder on\n</code></pre> <p>If an older build reports that <code>OTA_FOLDER_SERIAL</code> is not compiled in, install a current <code>-ota-</code>, <code>-full-usb-wifi-ota-</code>, or applicable <code>-full-logging-ota-</code> build first. Do not use a KISS modem: KISS firmware is a TNC/KISS frame interface and does not provide the MeshCore CLI or the OTA-folder transport that <code>motatool serve</code> requires.</p> <p>An nRF52 <code>companion_radio_full</code> starts in its USB ASCII terminal and automatically changes to Binary Companion when it receives a complete <code>&lt;</code> frame. It also recognizes <code>motatool</code>'s exact initial <code>ota folder on</code> line and enters exclusive mOTA mode directly, so <code>motatool serve --serial</code> can be the first client after boot. No terminal token or preliminary disconnect is required. Stopping the tool or disconnecting resets USB to Binary. BLE remains available throughout. See the Full Companion USB switcher guide for the complete ownership transitions. Protocol v14 can instead take the catalog from a paired phone or Linux host over a separate encrypted BLE mOTA service while Binary Companion remains active. USB and BLE catalog sources are mutually exclusive. See the Full Companion Bluetooth source guide.</p> <p>For an ESP32 WiFi companion or FULL ESP32 source with active WiFi, use its dedicated OTA seeder:</p> <pre><code>motatool serve --dir ./motas --tcp &lt;source-host&gt;:5001 -v\n</code></pre> <p>Port <code>5001</code> is separate from the companion application port (<code>5000</code>) and the HTTP configuration/browser-OTA port (<code>80</code>, depending on the role). An ESP32 <code>companion_radio_full</code> also has its complete role-specific text terminal on port <code>5002</code>; OTA automation uses its <code>ota</code> and TempRadio subset. See the full Companion guide. On a FULL repeater or room server, <code>start webconfig</code> can bring up the saved WiFi connection. Other FULL roles with browser OTA support can raise <code>MeshCore-OTA</code> with <code>start ota</code> and use <code>192.168.4.1:5001</code>. The TCP seeder auto-attaches; do not also run <code>ota folder on</code> for USB serial.</p>"},{"location":"ota_easy/#install-motatool","title":"Install <code>motatool</code>","text":"<p>Install Rust if necessary, then install the standalone packaging and serving tool:</p> <pre><code>git clone https://github.com/vk496/motatool\ncargo install --path ./motatool\n</code></pre>"},{"location":"ota_easy/#esp32-package-a-full-firmware-image","title":"ESP32: package a full firmware image","text":"<p>The destination must be an OTA-capable ESP32 with an A/B partition table. Download or build the new non-merged <code>.bin</code> application for the destination's exact board and role. Do not use an ESP32 <code>-merged.bin</code> factory image.</p> <p>Put the application firmware in a working directory, then build a full <code>.mota</code> container. For example:</p> <pre><code>mkdir -p ./motas\nmotatool build --fw ./Heltec_v3_repeater-ota-v1.16.05.bin --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>Replace the example filename with the firmware for the destination's exact target. With no <code>--base</code> argument, <code>motatool build</code> creates a full-image update. The firmware must contain its MeshCore <code>EndF</code> identity trailer so <code>motatool</code> and the destination can verify the target, hardware, and version.</p> <p>Do not continue if <code>motatool verify</code> reports a failure.</p>"},{"location":"ota_easy/#nrf52-package-a-full-image-or-in-place-delta","title":"nRF52: package a full image or in-place delta","text":""},{"location":"ota_easy/#1-install-and-check-the-otafix-bootloader","title":"1. Install and check the OTAFIX bootloader","text":"<p>This is a one-time prerequisite. Install the OTAFIX bootloader built for the destination's exact board from the OTAFIX nRF52 bootloader releases. Internal-staging delta updates require OTAFIX 2.4 or newer. External QSPI and SD staging require OTAFIX 2.4.1 or newer and release notes that explicitly list the exact board and storage mode. Follow the release's board-specific installation and erase instructions. If it does not contain the destination's exact board, this LoRa install path is not yet available for that board; never substitute a similar board's bootloader.</p> <p>Before preparing or downloading a LoRa update, run this on the destination:</p> <pre><code>get bootloader.ver\nota self\n</code></pre> <p>The first command identifies the installed nRF52 bootloader. Continue only if the <code>ota self</code> reply includes the apply mode required by this target:</p> <pre><code>bootloader: apply OK\nbootloader: QSPI apply OK\nbootloader: SD apply OK\n</code></pre> <p>The reply also contains the running firmware's <code>base_hash</code>. Save it for the package check below. A stock, legacy, or older OTAFIX bootloader without <code>.mota</code> in-place-apply support will report that apply support is missing, and <code>ota install</code> will refuse to reboot into it.</p>"},{"location":"ota_easy/#2-choose-full-or-delta-packaging","title":"2. Choose full or delta packaging","text":"<p>For a QSPI- or SD-backed target, a full update needs only the new raw <code>firmware.hex</code>:</p> <pre><code>mkdir -p ./motas\nmotatool build --fw ./LilyGo_T-Echo_repeater-new.hex --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>Use a full package when an exact base image is unavailable. Use the delta path below when reducing airtime is worth retaining the exact running image.</p>"},{"location":"ota_easy/#3-keep-the-exact-current-and-new-application-images-for-a-delta","title":"3. Keep the exact current and new application images for a delta","text":"<p>You need the raw <code>.pio/build/&lt;environment&gt;/firmware.hex</code> from the build that is actually running, plus the corresponding <code>firmware.hex</code> from the new build. Save the current file before building the new version, because PlatformIO reuses that path. For example:</p> <pre><code># Save this immediately after building/flashing the version now running on the node.\ncp .pio/build/Heltec_t114_repeater_lora_ota_no_external_sensors/firmware.hex \\\n  ./Heltec_t114_repeater_lora_ota_no_external_sensors-running.hex\n\n# After checking out and building the new version, save its image separately.\ncp .pio/build/Heltec_t114_repeater_lora_ota_no_external_sensors/firmware.hex \\\n  ./Heltec_t114_repeater_lora_ota_no_external_sensors-new.hex\n</code></pre> <p>Replace <code>Heltec_t114_repeater_lora_ota_no_external_sensors</code> with the destination's exact PlatformIO environment. The two images must be for the same board and role, and both must contain their <code>EndF</code> trailers. Do not pass a release <code>.uf2</code> or BLE-DFU <code>.zip</code> to <code>motatool</code>; those are installation containers rather than raw application images.</p> <p>Keeping a file with the same version label is not enough: the base must be byte-for-byte identical to the running application. The hash check in the next step proves that it is the right file.</p> <p>On RAK4631 repeaters, use the <code>RAK_4631_repeater_lora_ota_no_external_sensors</code> environment. It retains built-in battery monitoring but omits selected optional environmental/ranging drivers so the delta fits the safe in-place workspace. INA219, INA226, INA260, and INA3221 I2C voltage/current monitors remain supported despite the legacy target name. That trim does not remove the SSD1306 OLED, autodiscovered I2C RTCs, or GPS-compatible RAK12500 I2C path. The <code>0x42</code> RAK12500/INA3221 addressing rule above still applies. If the device has a RAK15001 installed in sensor slot C and the matching RAK15001 OTAFIX bootloader, use <code>RAK_4631_repeater_rak15001_slot_c_lora_ota</code> instead. That target retains the full sensor/GPS set and can install either a full image or a delta from the external 2 MiB store.</p> <p>With the separately wired Winbond breakout, use <code>RAK_4631_repeater_w25q16_lora_ota</code> for RAK4631 or <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code> for RAK3401 + RAK13302. Both require an <code>EF4015</code> 2 MiB device. As a one-time prerequisite, install <code>wiscore_rak4631_w25q16</code> for RAK4631 or <code>wiscore_rak3401_rak13302_w25q16</code> for RAK3401 + RAK13302. Wire CLK/MISO/MOSI to the RAK19007 IO connector pins 26/27/28, CS to J11 AIN1, and VCC/GND to J12 VDD/GND. Fit an approximately 10 kOhm CS-to-VDD pull-up; never use VBAT. The SPI pins require underside taps or an interposer, but no sensor slot is occupied. See the nRF52 QSPI guide before installing either image.</p>"},{"location":"ota_easy/#4-build-and-check-the-in-place-delta","title":"4. Build and check the in-place delta","text":"<pre><code>mkdir -p ./motas\nmotatool build \\\n  --base ./Heltec_t114_repeater_lora_ota_no_external_sensors-running.hex \\\n  --fw ./Heltec_t114_repeater_lora_ota_no_external_sensors-new.hex \\\n  --patch-type in-place \\\n  --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p><code>motatool</code> prints the generated filename. Inspect that file:</p> <pre><code>motatool inspect ./motas/GENERATED_FILENAME.mota\n</code></pre> <p>Check all three of these before serving it:</p> <ul> <li><code>codec_id</code> is <code>2 (detools-in-place)</code>.</li> <li><code>base_hash</code> is the same 8-byte value reported by the destination's <code>ota self</code> command.</li> <li>The numeric <code>target_id</code> exactly matches <code>target:</code> in the destination's <code>ota status</code>, and the hardware and   firmware version identify the intended board and role. If <code>inspect</code> shows <code>N/A</code> for the human-readable   target name, the tool's name table is older than that environment; the numeric IDs still must match.</li> </ul> <p>Current layout-aware <code>motatool</code> derives the safe workspace from the new firmware's authenticated EndF layout record, so the normal recipe deliberately omits <code>--inplace-memory</code>. If older tooling requires an explicit override, use <code>0xC6000</code> only for matched external SD/QSPI staging and <code>0x98000</code> for an internal-staging nRF52 such as the RAK4631 lean OTA build. Do not substitute the external value on an internal target, and do not override either value unless you have verified the exact app base, bootloader, and package geometry. Do not continue if verification or any identity check fails.</p>"},{"location":"ota_easy/#transfer-and-install-either-package","title":"Transfer and install either package","text":""},{"location":"ota_easy/#1-start-the-temporary-ota-channel","title":"1. Start the temporary OTA channel","text":"<p>First save the current <code>ota config</code> output. For a direct source-to-destination link, set both OTA-enabled endpoints to direct-only mode before starting the transfer:</p> <pre><code>ota config hops 0\n</code></pre> <p>Do not use <code>hops 1</code> as extra margin on a direct link. It tells a receiving repeater to retransmit each direct DATA/PROOF packet; that unnecessary half-duplex transmission can make it miss the source's next fragment, especially with older single-block receivers. Use <code>hops 1</code> only when one real intermediate relay is required, <code>hops 2</code> for two, and so on. This setting is saved, so restore the original value after the maintenance window.</p> <p>On the source node, destination node, and every intermediate repeater, then run:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>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 <code>tempradio</code>.</p> <p>If you administer the destination over LoRa, the controller used to send later <code>ota</code> commands must also be able to communicate on this temporary channel. For unattended nodes, use synchronized <code>tempradioat</code> entries instead of manually starting the windows. Ensure the nodes' clocks are set before using <code>tempradioat</code>.</p>"},{"location":"ota_easy/#2-serve-the-update-from-the-computer","title":"2. Serve the update from the computer","text":"<p>Close any serial terminal using the source node's USB port, find its device name, and start the server:</p> <pre><code>motatool serve --dir ./motas --serial /dev/ttyACM0 -v\n</code></pre> <p>Replace <code>/dev/ttyACM0</code> with the USB serial device of the source companion selected above. <code>motatool</code> attaches the folder to the source, which advertises the update over LoRa while its temporary-radio window is active. KISS modem serial ports cannot be used here.</p> <p>For an nRF52 Full Companion and a Bluetooth-capable host, the equivalent cable-free source is:</p> <pre><code>python3 tools/ble_mota/ble_mota_seeder.py \\\n  --device MeshCore-MyCompanion \\\n  --dir ./motas \\\n  --local 'tempradio 910.525,250,5,5,120'\n</code></pre> <p>Leave this command running until the destination finishes downloading.</p>"},{"location":"ota_easy/#3-find-and-download-the-update","title":"3. Find and download the update","text":"<p>On the destination node, check its state and ask for nearby updates:</p> <pre><code>ota status\nota ls\n</code></pre> <p>Discovery is asynchronous. <code>ota ls</code> says <code>refreshing</code>; wait a few seconds and run it again even if it first shows an older row. Select <code>[same target]</code>: it can say <code>full</code> for ESP32 and external SD/QSPI nRF52 targets, or <code>delta</code> for any supported nRF52 target. Do not select <code>[unsupported]</code> (for example, a source's self-served full image on an internal-staging nRF52). Rows labelled <code>bootloader</code> are also outside this ordinary application flow: they are never automatic and <code>ota install</code> refuses them. Only an already-capable, allowlisted internal-flash, XIAO-QSPI, or exact MeshTower V2 microSD nRF52 target can use the separate explicit bootloader workflow. Use the row's stable eight-hex manifest ID rather than its changing list position:</p> <pre><code>ota pull 838B8169 flash\n</code></pre> <p>If a legacy internal-flash nRF52 reports <code>no EndF</code>, only a row marked <code>[rescue]</code> is eligible. Current rescue-capable firmware requires <code>ota pull &lt;mid8&gt; flash rescue</code>, followed after completion by <code>ota rescue install &lt;base_hash16&gt;</code>. Older running firmware without those commands must be recovered over USB. Shared-internal bootloader-update builds are stricter: without a valid live <code>EndF</code>, every internal pull is refused before erase because the normal application may extend through <code>0xED000</code>. Recover those builds over USB/BLE DFU or SWD instead of relying on the older 608 KiB rescue estimate.</p> <p>Monitor the transfer:</p> <pre><code>ota status\n</code></pre> <p>To adjust LoRa OTA pacing, use <code>get ota.speed</code> and <code>set ota.speed &lt;0.05..3&gt;</code> on the source, destination, and OTA relays. <code>1</code> preserves the existing timing; lower values slow OTA down, and higher values shorten adjustable delays. This saved setting covers both profiles and OTA adverts as well as the transfer. It does not change radio modulation or the configured airtime budget. See LoRa OTA speed for details.</p> <p>For a powered bench update where restart-resume is not needed, <code>ota config checkpoint 0</code> on the destination removes periodic progress writes. It is a smaller optimization than selecting the correct hop count and it trades away persisted mid-download resume; restore the previous checkpoint cadence afterward.</p> <p>Current repeater firmware automatically uses the full transmit budget during a bounded TempRadio window. Older receivers do not: if <code>get af</code> reports a nonzero value on such a node, record it, use <code>set af 0</code> for the maintenance window, and restore it afterward. This affects how promptly the legacy receiver can send its next block/proof request; it does not increase LoRa transmit power. Use a full duty budget only where the selected frequency and local rules permit it.</p> <p>The update is ready when the status says <code>ready to install</code>. Discovery is background traffic, while an active OTA download is primary mesh traffic. At the temporary-radio settings in this guide, allow roughly one hour for a typical ESP32 full image over a quiet, direct link. That is a planning estimate, not an upper bound: repeaters, retries, weak links, and normal mesh traffic can extend it well past an hour. The 120-minute example window is intentional. If necessary, start another overlapping <code>tempradio</code> window; the download resumes rather than starting over.</p>"},{"location":"ota_easy/#4-verify-and-install","title":"4. Verify and install","text":"<p>Once the destination reports <code>ready to install</code>, run:</p> <pre><code>ota install\n</code></pre> <p>The destination verifies the complete package again before approving it. ESP32 installs the full image into its inactive A/B slot. nRF52 checks the bootloader and storage capabilities and, for a delta, the base hash, then reboots into OTAFIX. The bootloader independently rechecks the package, installs the external full image or applies the delta in place, and verifies the resulting image. Pre-install failures leave the running firmware unchanged and report the reason. If power is lost after an nRF52 in-place apply has begun, OTAFIX will not boot a partial image; it enters recovery DFU so a known-good application can be restored.</p> <p>After the node returns, reconnect on its normal radio channel and confirm:</p> <pre><code>ota status\n</code></pre>"},{"location":"ota_easy/#quick-troubleshooting","title":"Quick troubleshooting","text":"<ul> <li>Nothing appears in <code>ota ls</code>: confirm that <code>motatool serve</code> is still running and every required node   has an active <code>tempradio 910.525,250,5,5,120</code> window.</li> <li>The CLI says LoRa OTA is not included: that firmware does not contain the LoRa OTA feature.   If it is the source or destination, install a supported <code>-ota-</code> build over WiFi or USB first. An intermediate   repeater does not need the OTA CLI and can relay opaquely while its matching <code>tempradio</code> window is active.</li> <li>The update shows another environment or a raw <code>[hw XXXXXXXX]</code>: it is for a different board or firmware   role. Do not install it.</li> <li>An internal-flash nRF52 marks a full update <code>[unsupported]</code>: it can install only an in-place delta.   A matched QSPI repeater or MeshTower V2 microSD target accepts full images with its corresponding bootloader.</li> <li>A QSPI nRF52 reports <code>QSPI store:ERR 0K</code> or <code>bl:NO-QSPI</code>: do not download an install package. Install   the exact QSPI-aware bootloader and check that the selected application matches the board's flash wiring.   A RAK W25Q16 target must identify exactly <code>EF4015</code> and 2048K; also check its physical CS pull-up.</li> <li>nRF52 reports no bootloader apply support: install the exact-board in-place-delta OTAFIX bootloader   before trying LoRa OTA.</li> <li>nRF52 reports a base mismatch: the file passed to <code>--base</code> is not the exact application running on   the destination. Rebuild the delta from the correct saved <code>firmware.hex</code>.</li> <li>The download stalls: check the source, destination, and intermediate repeaters. Restart matching,   overlapping temporary-radio windows if one expired. On a direct link, also require <code>ota config hops 0</code>;   a larger reach makes a repeater destination unnecessarily echo source packets.</li> <li>The serial port is busy: close the serial terminal before starting <code>motatool serve</code>.</li> <li>The destination rejects the package: verify the source files, their <code>EndF</code> trailers, the package's   target/hardware identity, and the result of <code>motatool verify</code>.</li> </ul> <p>For additional commands and safety details, see the full OTA user guide. For protocol and container internals, see the OTA protocol specification.</p>"},{"location":"ota_meshtower_v2_sdcard/","title":"MeshTower V2 microSD LoRa OTA","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>The <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code> target uses the MeshTower V2 onboard microSD socket as persistent storage for its own LoRa OTA downloads. It accepts full application images, in-place application deltas, and explicitly selected signed v3 bootloader packages. After verification, the matching SD-aware OTAFIX bootloader reads the staged file from the card and programs the selected nRF52840 application or bootloader region.</p> <p>The pin assignment follows the Heltec MeshTower V2 partial reference circuit:</p> Signal nRF52840 pin Arduino pin number SD CS P1.00 32 SD MOSI P1.01 33 SD SCK P0.06 6 SD MISO P0.26 26 <p>The SD socket uses its own SPI peripheral, so card traffic does not change the LoRa radio pinout.</p>"},{"location":"ota_meshtower_v2_sdcard/#card-requirements","title":"Card requirements","text":"<p>Use a FAT16, FAT32, or exFAT card accepted by the bundled SdFat version. The normal update path imposes no additional MBR/sector-1 layout requirement; filesystem layouts SdFat cannot mount are still rejected. MeshCore creates <code>/meshcore-ota.mota</code> as a contiguous file and passes its exact sector range to OTAFIX in reset-retained MCU RAM.</p> <p>MeshCore never reads or writes raw sector 1 and does not infer ownership from blank card sectors. Both application and bootloader OTA require a locally provisioned BLM2-capable bootloader that understands the retained-RAM record. Preview.12 must first be upgraded over USB/BLE DFU or SWD.</p>"},{"location":"ota_meshtower_v2_sdcard/#capacity-and-update-types","title":"Capacity and update types","text":"<p>The card removes the internal-flash staging limit. The <code>.mota</code> container may be much larger than the old internal staging gap, and either a full image or an in-place delta may be downloaded. The installed firmware itself must still fit the nRF52840 application region below InternalFS (ending at <code>0xED000</code>); SD storage does not increase the MCU's executable flash.</p> <p>For this S140 v6 target, the maximum application image including its <code>EndF</code> trailer is <code>0xC7000</code> bytes (815,104 bytes). To package a full self-update:</p> <pre><code>motatool build --fw ./Heltec_tower_v2_sdcard-new.hex \\\n  --sign ./trusted-signer.key --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>A delta uses the exact installed image as its base. The normal <code>0x98000</code> workspace remains compatible. If either image is larger than that legacy limit, build the patch with the SD target's larger workspace:</p> <pre><code>motatool build \\\n  --base ./Heltec_tower_v2_sdcard-running.hex \\\n  --fw ./Heltec_tower_v2_sdcard-new.hex \\\n  --patch-type in-place \\\n  --inplace-memory 0xC7000 \\\n  --sign ./trusted-signer.key \\\n  --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>The download is resumable because the partial <code>.mota</code> stays on the card. Once it reaches <code>ready</code>, <code>ota install</code> performs the final verification, publishes a one-reset authorization record, and reboots. SD application installation requires a valid signature from a key in the node's allowlist. Keep the card inserted through the reboot and installation.</p> <p>The BLM2 retained-auth SD-aware bootloader is mandatory for application OTA. <code>ota install</code> refuses to reboot if its continuity metadata does not match the running S140 family/FWID/application layout or if its capability marker does not advertise SD staging and the selected codec. Existing <code>Heltec_tower_v2_repeater</code> firmware continues to use the internal-flash delta path and is unchanged.</p>"},{"location":"ota_meshtower_v2_sdcard/#signed-bootloader-update","title":"Signed bootloader update","text":"<p>Only this exact SD build exposes the privileged LoRa bootloader-update command. It requires an already installed exact-board ABI-3 OTAFIX bootloader whose one unambiguous capability marker is exactly <code>0x09</code> (<code>SD|BOOT_UPDATE</code>) and whose codec mask is <code>0x0005</code> (<code>FULL|INPLACE</code>). Requiring both application codecs prevents a bootloader self-update from disabling either normal SD application path. A stock bootloader still requires USB/BLE DFU or SWD. The sole remote bootstrap is intentionally absent: preview.12 and any other legacy-v1 image must be upgraded locally before either SD application or bootloader OTA.</p> <p>The signed v3 container is exactly 41,330 bytes and carries a 40 KiB candidate for the installed <code>239A0071 / TOWER_V2_OTA</code> identity (boot target <code>1150F50E</code>). It uses the same contiguous <code>/meshcore-ota.mota</code> file as an application update. GPREGRET <code>0x6B</code> plus the distinct SD source marker <code>0x53</code> selects the bootloader path; LoRa transport remains payload type <code>0x0C</code>.</p> <p>The application linker still ends at <code>0xED000</code>, but OTAFIX needs <code>0xE0000..0xEA000</code> as temporary scratch while replacing itself. Before a boot package can be downloaded or approved, MeshCore requires a hash-valid live <code>EndF</code> proving the complete running image ends by <code>0xE0000</code>; OTAFIX repeats that no-overlap check before its first erase. An application extending above that boundary can still receive normal FULL or delta application updates from SD, but its bootloader must be updated locally.</p> <p>MeshCore also checks the live boot settings before touching that scratch page. Erased settings and a valid-app record with CRC disabled are allowed. When a nonzero bank CRC is active, its recorded <code>bank_0_size</code> must cover the complete EndF-inclusive running image and must end by <code>0xE0000</code>; an undersized or oversized record refuses the operation and requires local DFU/SWD.</p> <p>Because the card is removable, approval is bound to the exact bytes that were authenticated. For both fmt2 application and fmt3 bootloader packages, MeshCore authenticates one exact signed manifest, requires every streamed manifest byte to match it, and verifies the leaves, payload, and image. During that same pass it hashes the entire container with only the mutable four-byte <code>APRV</code> field normalized to zero. After writing and syncing <code>APRV</code>, MeshCore publishes a 72-byte <code>MOTASDA2</code> record at reset-retained RAM address <code>0x20006008</code>. The record binds package purpose/format, exact LBA range, card size, container length, and that normalized SHA-256. OTAFIX consumes and clears the record before reading the card; changing the card or file can only fail. A power loss erases the authorization and also fails closed.</p> <p>For fmt3, MeshCore additionally writes and readback-verifies the temporary 64-byte <code>MOTASDBL</code> token at <code>0xE0000</code>, binding the exact total and signed manifest <code>image_hash</code>. OTAFIX requires the parsed manifest, streamed payload, and final scratch image to match it. The token page becomes scratch during a successful boot update and is not permanently reserved.</p> <p>Every new candidate also carries a backward-compatible <code>BLM2</code>/<code>SOFT</code> continuity extension next to its legacy embedded manifest. The complete 76-byte envelope is fixed at final raw-image offset <code>0x9FB4</code>; a relocated copy is not a valid candidate. Its embedded bootloader version must equal the outer package version, match the runtime SoftDevice family/FWID, application base, and layout ABI, and be strictly newer than an installed BLM2 version. Preview values use low bytes <code>1..254</code> and a stable release uses <code>0xFF</code>; zero-preview and all-ones versions are invalid. Remote bootloader rollback is not supported; use local DFU/SWD when rollback or migration is intentional.</p> <p>Bootloader packages are never autofetched or autoinstalled. Select and confirm one exact package manually:</p> <pre><code>ota ls\nota pull &lt;MID8&gt; flash\n# wait for ota status to report the bootloader download ready\nota bootloader\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Copy the MID and first 16 image-hash hex digits from <code>ota bootloader</code>. Ordinary <code>ota install</code> rejects this package, and the bootloader command rejects an application package. Keep the SD card inserted through the reboot. A later <code>ota status</code> value of <code>blup:C8</code> reports a successful bootloader replacement.</p> <p>After reboot, <code>ota bootloader</code> displays the installed board identity, CRC and capabilities. Its <code>mid</code> and <code>hash</code> fields describe a currently staged download, not the installed bootloader, so <code>staged:none mid=- hash=-</code> is not an install failure. <code>blrc:00</code> means no retained apply result is available; it does not by itself prove either success or failure.</p> <p>Older MeshCore application firmware can report <code>get bootloader.ver</code> as <code>unknown</code> for OTAFIX 2.4.6 because this bootloader image omits the legacy <code>UF2 Bootloader</code> text. The updated getter also reads the CRC-validated BLM2 version. For the official signed MeshTower V2 SD 2.4.6 <code>.mota</code>, the installed identity is <code>TOWER_V2_OTA</code>, CRC <code>5DACDB3D</code>, ABI <code>3</code>, and capabilities <code>09</code>. Compare the exact board/storage package when interpreting these values; the non-SD image differs.</p>"},{"location":"ota_meshtower_v2_sdcard/#sd-card-cli","title":"SD card CLI","text":"<p>The SD-backed target provides these CLI commands:</p> <pre><code>set sdcard format [--force]\nset sdcard erase [--force]\nget sdcard\nget sdcard *\nget sdcard format\nget sdcard erase\nget sdcard free\nget sdcard ls\nget sdcard ls 2\nget sdcard dir 3\n</code></pre> <p><code>format</code> creates a new FAT16, FAT32, or exFAT filesystem according to card size. <code>erase</code> first uses the card's raw media erase command and then formats it, so a successful erase finishes with a usable filesystem. Both operations destroy all data on the card and cancel any staged OTA download.</p> <p>The firmware records successful format and erase completion times in RAM. Repeating the same operation within five minutes is rejected unless <code>--force</code> is present. Format and erase have independent cooldowns. Because erase also formats the card, a successful erase updates both timestamps. The timestamps reset when the device reboots. The <code>get sdcard</code> age queries report how long ago each operation completed. <code>get sdcard free</code> reports used and free filesystem space in human-readable binary units.</p> <p><code>get sdcard ls</code> and <code>get sdcard dir</code> recursively list files on the card, two files per page. A bare command shows page 1; append a positive page number to move through the remaining results. Each row includes the path and a compact file size. The header reports the selected page, total pages, and total files.</p>"},{"location":"ota_meshtower_v2_sdcard/#persistent-ota-archive-and-seeder","title":"Persistent OTA archive and seeder","text":"<p>On the SD-backed target, automatic OTA archiving is on by default. While the temporary OTA radio is active, the node requests full catalogs from seeders and saves every complete mOTA it discovers, including firmware for other hardware targets and codecs that this node cannot install. Archive downloads use the same per-block Merkle proof checks as an install download, but archived images are never selected for local installation.</p> <p>Completed containers are stored as <code>/mota/&lt;manifest-id&gt;.mota</code>. An interrupted download remains <code>/mota/&lt;manifest-id&gt;.part</code> and resumes when that mOTA is seen again. Completed files survive reboot, are enumerated on the first archive access or TempRadio window, and are advertised and served directly from SD. The SD target supports the protocol maximum served set: its own running firmware plus up to 254 archived mOTAs.</p> <p>Automatic capture preserves an 8 MiB free-space reserve for manual <code>/meshcore-ota.mota</code> installation staging. It stops starting new archive files when the next file would cross that reserve. Archive allocation first tries the fast contiguous path and then falls back to an ordinary fragmented FAT file; only the bootloader staging file requires contiguous sectors.</p>"},{"location":"ota_meshtower_v2_sdcard/#preload-many-motas-from-a-computer","title":"Preload many mOTAs from a computer","text":"<p>You can populate the archive much faster on a computer than over LoRa. Use only complete, verified <code>.mota</code> containers. Do not copy firmware <code>.bin</code>, <code>.hex</code>, <code>.zip</code>, or <code>.part</code> files into the archive.</p> <p>Install the standalone <code>motatool</code> first if it is not already available:</p> <pre><code>git clone https://github.com/vk496/motatool.git\ncargo install --path ./motatool\n</code></pre> <p>The on-card filename is part of the archive index and has a strict format:</p> <pre><code>/mota/&lt;merkle_root&gt;.mota\n</code></pre> <p><code>&lt;merkle_root&gt;</code> is the eight-hex-digit value printed by <code>motatool inspect</code>. It is also the mOTA's four-byte manifest ID. The extension must be lowercase, the file must be directly inside <code>/mota</code>, and descriptive release filenames are not indexed. For example, if inspection reports:</p> <pre><code>merkle_root    : ABCD1234\n</code></pre> <p>copy that container to:</p> <pre><code>/mota/abcd1234.mota\n</code></pre> <p>If two containers have the same Merkle root, they have the same protocol ID and cannot both be present. Keep only the intended one. The current SD seeder can index up to 254 archived files. A served file must use a logical block size of at most 1024 bytes and contain at most 2048 blocks; check <code>block_size</code> and <code>block_count</code> in <code>motatool inspect</code> when importing unusually large images. Files outside that serve geometry are not counted or advertised. If a malformed <code>/mota/&lt;id&gt;.mota</code> conflicts with a newly discovered valid image, the repeater preserves the malformed file as <code>&lt;id&gt;.bad</code> through <code>&lt;id&gt;.bad9</code> and downloads a clean replacement instead of treating path existence as a valid cache hit.</p> <p>To prepare and load the card:</p> <ol> <li>Format it as described under Card requirements. The    easiest route is to insert it in the repeater, run <code>set sdcard format</code>, power    the repeater off, and then move the card to the computer. Formatting destroys    the existing card contents.</li> <li>Mount the card on the computer and create a directory named <code>mota</code> at the    filesystem root. Do not use a nested directory such as <code>/firmware/mota</code>.</li> <li>Run <code>motatool verify FILE.mota</code> for every source file. Do not copy a file    that reports <code>FAIL</code>.</li> <li>Run <code>motatool inspect FILE.mota</code>, read its <code>merkle_root</code>, and copy the file    to <code>/mota/&lt;lowercase-merkle-root&gt;.mota</code> on the card.</li> <li>Flush pending writes, safely eject the card, power the repeater off, insert    the card, and boot    <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code>.</li> </ol> <p>On Linux or macOS, this Bash example verifies and imports every <code>.mota</code> from <code>./motas</code>. Replace the example mount path before running it:</p> <pre><code>card_mount=/media/YOU/MESHCORE\nmkdir -p \"$card_mount/mota\"\n\nshopt -s nullglob\nfor image in ./motas/*.mota; do\n  motatool verify \"$image\" || exit 1\n  mid=$(motatool inspect \"$image\" |\n    awk '$1 == \"merkle_root\" { print tolower($3) }')\n  if [[ ! $mid =~ ^[0-9a-f]{8}$ ]]; then\n    echo \"Could not read the Merkle root from: $image\" &gt;&amp;2\n    exit 1\n  fi\n\n  destination=\"$card_mount/mota/$mid.mota\"\n  if [[ -e $destination ]]; then\n    cmp -s \"$image\" \"$destination\" || {\n      echo \"Different containers have the same ID: $mid\" &gt;&amp;2\n      exit 1\n    }\n  else\n    cp \"$image\" \"$destination\"\n  fi\ndone\nsync\n</code></pre> <p>On Windows, create <code>E:\\mota</code>, inspect each source with <code>motatool inspect</code>, and rename it to the reported lowercase root in the same way. Safely eject the drive after all copies finish.</p> <p>After boot, scan the archive and confirm the card contents from the repeater console:</p> <pre><code>get sdcard ls\nget sdcard ls 2\nota cache\nota folder\n</code></pre> <p><code>ota cache</code> should report the imported count. <code>ota folder</code> reports the current served count; once OTA serving starts in TempRadio, that set also includes the repeater's running firmware. If the files appear in <code>get sdcard ls</code> but not in the served count, check their exact names, run <code>motatool verify</code> again, and inspect their block geometry. It is fine to run <code>ota cache off</code> for a curated, read-mostly archive: that disables capture of new mOTAs but continues serving every valid file already on the card.</p>"},{"location":"ota_meshtower_v2_sdcard/#serve-the-preloaded-archive-over-tempradio","title":"Serve the preloaded archive over TempRadio","text":"<p>LoRa OTA traffic exists only during an active temporary-radio window. The SD repeater, each receiving node, and every intermediate repeater in the path need overlapping windows on the same temporary channel. Use a frequency permitted for the node's configured region. This North American example uses the recommended fast OTA settings and a 120-minute window:</p> <pre><code>tempradio 909.950,250,5,5,120\n</code></pre> <p>Start the farthest receiving node first, then intermediate repeaters, and the SD source last so their windows overlap for as long as possible. Before or during the source window, <code>ota cache</code> makes the source scan and attach the SD archive. Entry into TempRadio automatically triggers an OTA advertisement burst; <code>ota announce</code> can send another advertisement immediately.</p> <p>On a receiving OTA-capable node, allow a few seconds for catalog exchange, then run:</p> <pre><code>ota ls\nota ls 2\nota get &lt;mid8&gt; flash\nota status\n</code></pre> <p>Use <code>ota ls 2</code>, <code>ota ls 3</code>, and so on when the source advertises more than the two rows that fit in one remote CLI reply. Each row includes a stable eight-hex-digit manifest ID. Use that ID instead of a list number, because asynchronous catalog refreshes can reorder rows between the list and pull commands. A receiver retains the complete protocol catalog and verifies every transferred block. It still applies its normal target, hardware, codec, signature, and installation checks. The SD repeater may advertise images for many hardware families; it never installs those archive files merely because it serves them.</p> <p>When a temporary window expires or a node reboots, it returns to its saved radio settings and OTA transfer stops. The archive remains on the card. Start another set of overlapping <code>tempradio</code> windows to resume an interrupted download, or use synchronized <code>tempradioat</code> entries for a scheduled window.</p> <p>Archive capture is lower priority than operator work. An explicit <code>ota pull</code> to install storage or a host folder immediately takes the single receive slot; the archive partial is checkpointed and resumes later. Existing cached files can still answer peer requests while another archive file is downloading.</p> <p>Use these commands to inspect or control automatic capture:</p> <pre><code>ota cache\nota cache on\nota cache off\nota config cache on\nota config cache off\n</code></pre> <p>The on/off choice is saved on the SD card. Turning capture off stops new downloads but keeps serving files already cached. Formatting or erasing the card removes both the archive and its off marker, so a newly formatted card returns to the default-on setting. <code>ota config sdseed on|off</code> is also accepted as an alias.</p>"},{"location":"ota_nrf52_bootloader_update/","title":"nRF52 bootloader updates over LoRa","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>Selected nRF52840 repeater LoRa-OTA builds can replace their matching OTAFIX bootloader without replacing the running application. This is a privileged maintenance path, not a normal firmware update. A stock bootloader must first be replaced with the exact ABI-3 self-update-capable OTAFIX build over USB/BLE DFU or SWD. MeshTower SD also requires the BLM2 retained-auth version to be provisioned locally before either application or bootloader OTA.</p>"},{"location":"ota_nrf52_bootloader_update/#storage-layouts","title":"Storage layouts","text":"Layout Application limit Staged boot package Work area Handoff / capability XIAO-module raw QSPI below <code>0xE0000</code> external QSPI offset 0 dedicated internal <code>0xE0000..0xEA000</code> scratch source <code>0x51</code>, flags <code>0x0E</code> Qualified internal-flash target normal <code>0xED000</code> flash limit; top 64 KiB SRAM reserved for application-delta staging shared internal slot, exact start <code>0xE2000</code> the same eleven-page slot; no second flash reservation source <code>0xED</code>, flags <code>0x0A</code> MeshTower V2 microSD normal <code>0xED000</code> limit contiguous <code>/meshcore-ota.mota</code> dynamic internal <code>0xE0000..0xEA000</code> scratch; live image must end by <code>0xE0000</code> source <code>0x53</code>, flags <code>0x09</code> <p>The exact SD target is <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code>. Its normal application FULL and delta updates continue to use the SD file without the bootloader-update scratch restriction. For a bootloader package only, both MeshCore and OTAFIX require a hash-valid live <code>EndF</code> proving the complete running image ends at or below <code>0xE0000</code>. If boot settings carry a nonzero app bank CRC, the recorded bank size must also cover that full EndF-inclusive image and stop by <code>0xE0000</code>; erased or explicitly CRC-disabled settings remain valid. OTAFIX then copies the verified 40 KiB payload from SD into <code>0xE0000..0xEA000</code> and uses the MBR copy operation to replace <code>0xF4000..0xFE000</code>. The application linker remains at <code>0xED000</code>; a future application extending above <code>0xE0000</code> can still use application mOTA but must update its bootloader through local DFU/SWD.</p> <p>The removable SD authorization is fail-closed for both application and bootloader packages. MeshCore directly authenticates one exact signed manifest, requires the streamed copy to remain byte-identical, verifies all leaves/payload/image bytes, and computes a normalized full-container SHA-256 in that same pass (<code>APRV</code> bytes are treated as zero). After syncing <code>APRV</code>, it publishes a 72-byte <code>MOTASDA2</code> record in reset-retained RAM at <code>0x20006008</code>. That record binds purpose/format, first LBA, sector count, total length, card sector count, and the normalized digest. OTAFIX copies, validates, and clears the record before SD access. A card swap/mutation or a power cycle therefore fails closed; there is no general sector-1 ownership inference.</p> <p>For fmt3, MeshCore also writes and readback-verifies a 64-byte <code>MOTASDBL</code> token at <code>0xE0000</code>. That token contains the exact container length and the exact authenticated signed manifest <code>image_hash</code>. OTAFIX requires the same hash in the parsed manifest, streamed payload, and final scratch image. The page is consumed as scratch during success and is not permanently reserved.</p> <p>The first BLM2-capable MeshTower bootloader cannot be delivered to preview.12 through the retained-RAM protocol that preview.12 predates. MeshCore does not write a raw-sector compatibility record because a blank sector is not proof of ownership. Upgrade preview.12 through USB/BLE DFU or SWD. Both fmt2 application and fmt3 bootloader OTA then require the installed BLM2 metadata to match the live SoftDevice/application layout; neither MeshCore nor OTAFIX uses sector 1.</p> <p>The internal path does not change the application's <code>0xED000</code> flash limit or permanently set aside separate app-OTA, boot-package, and flash-scratch regions. Qualified applications do use a dedicated linker that reserves the top 64 KiB of SRAM for hybrid application-delta staging and a retained authorization record. That SRAM is never part of a bootloader-update package. The ordinary bottom-aligned internal flash store holds one container prefix at a time: either an application delta or the complete bootloader package.</p> <p>The exact bootloader container is 41,330 bytes: 365 bytes of signed mOTA metadata, a 40 KiB payload, and the five-byte trailer. Below the normal <code>0xED000</code> store ceiling it bottom-aligns at <code>0xE2000</code>. Admission requires a hash-valid live <code>EndF</code> proving the current application, including its trailer, ends at or before <code>0xE2000</code>. OTAFIX then reads each source window before erasing and compacts the payload forward in place to the page-aligned raw range <code>0xE2000..0xEC000</code>; it verifies every page and the whole image before asking the MBR to copy that image over <code>0xF4000..0xFE000</code>.</p> <p>An ordinary application delta can be smaller or larger than this eleven-page shape. On the qualified profile, a delta larger than one page uses the minimum page-aligned flash prefix ending at <code>0xED000</code> and keeps up to 64 KiB of its logical tail in reset-retained SRAM; its detools workspace must stop at the actual flash-prefix start. A one-page-or-smaller delta stays wholly in flash. In either case the reconstructed application must stop below <code>0xED000</code>. The two package kinds are mutually exclusive because they use the same flash store, and a bootloader package never uses the volatile SRAM suffix.</p> <p>For internal-self-update builds, an absent or corrupt live <code>EndF</code> disables all internal staging before the first erase. The older 608 KiB rescue estimate is unsafe when a normally linked application may extend to <code>0xED000</code>. Builds without this feature retain the legacy rescue behavior.</p>"},{"location":"ota_nrf52_bootloader_update/#internal-flash-target-inventory","title":"Internal-flash target inventory","text":"<p>The release builder consumes the allowlist in <code>tools/mota/nrf52_internal_bootloader_targets.txt</code>. Ten names are also literal PlatformIO environments and are enabled automatically when built directly. The other eleven are release aliases assembled from a base environment plus the lean OTA overlay; build them through <code>build.sh</code>, which passes the same allowlist decision to the common pre-build guard. These lean repeater/bridge targets have no OTA-owned SD/QSPI store and have an exact curated OTAFIX manifest identity:</p> Build target(s) Installed OTAFIX identity Boot target ID <code>Heltec_tower_v2_repeater_lora_ota_no_external_sensors</code> <code>239A0071 / TOWER_V2_OTA</code> <code>1150F50E</code> T096 lean repeater and RS232 bridge <code>239A0071 / T096_DFU</code> <code>42354C85</code> <code>Heltec_t1_repeater_lora_ota_no_external_sensors</code> <code>239A0071 / T1_DFU</code> <code>FC556FFC</code> T114 display and without-display lean repeaters <code>239A0071 / T114_DFU</code> <code>0C3F2902</code> <code>Mesh_pocket_repeater_lora_ota_no_external_sensors</code> <code>239A0071 / MESH_POCKET_OTA</code> <code>059277F4</code> <code>KeepteenLT1_repeater_lora_ota_no_external_sensors</code> <code>239A00B3 / KeepteenLT1_OTA</code> <code>DB2E7B51</code> <code>Minewsemi_me25ls01_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / MX25_DFU</code> <code>026AA982</code> <code>ProMicro_repeater_lora_ota_no_external_sensors</code> <code>239A00B3 / PROM_DFU</code> <code>AF79E8CC</code> <code>t1000e_repeater_lora_ota_no_external_sensors</code> <code>28860057 / T1KE_DFU</code> <code>E6F5F03F</code> <code>ThinkNode_M3_repeater_lora_ota_no_external_sensors</code> <code>239A00DA / TNM3_DFU</code> <code>0CA41DB2</code> <code>RAK_3401_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / 3401_DFU</code> <code>23818A80</code> RAK4631 lean repeater and both lean RS232 bridges <code>239A0029 / 4631_DFU</code> <code>2D0DF000</code> GAT562 30S/Tracker Pro/EVB Pro lean targets <code>239A0029 / GAT562_DFU</code> <code>D50D2D44</code> <code>R1Neo_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / 4631_DFU</code> <code>2D0DF000</code> <code>RAK_WisMesh_Tag_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / RTAG_DFU</code> <code>C72E9C9C</code> <p>Board IDs are not globally unique. For generic targets, the signed hardware ID is the exact NUL-padded 32-byte value <code>NRF_BL_&lt;BOARD_ID&gt;_&lt;DEVICE_NAME&gt;</code>. The wire target is the little-endian first four SHA-256 bytes of all 32 padded bytes. The installed and candidate embedded manifest pairs must match exactly. XIAO retains its deployed <code>XIAO_BL_28860044</code> / <code>XIAO_BL_28860045</code> identity and raw board-ID target.</p> <p>The Python reference builder and release tooling audit these boot targets for duplicates and collisions with application target IDs. Generic image parsing can inspect a future canonical identity, but signing/building a package fails until that exact identity is in the qualified inventory.</p> <p>Earlier GAT562 installations may report the RAK-compatible <code>4631_DFU</code> identity. The installed and candidate identity pair must match exactly, so a remote bootloader update cannot migrate one of those devices to <code>GAT562_DFU</code>. Provision the GAT562-specific OTAFIX bootloader once through USB/BLE DFU or SWD; subsequent signed bootloader mOTA updates use target <code>D50D2D44</code>.</p>"},{"location":"ota_nrf52_bootloader_update/#embedded-continuity-and-version-policy","title":"Embedded continuity and version policy","text":"<p>Every remotely supplied successor retains the legacy 44-byte CRC-valid <code>BLMF</code> v1 record for identity continuity and diagnostics. Immediately after that record is a 32-byte <code>BLM2</code>/<code>SOFT</code> extension. The complete 76-byte envelope is fixed at the final raw-image offset <code>0x9FB4</code>; relocated candidates are refused, while installed legacy-v1 discovery remains a generic diagnostic scan. The extension carries the actual packed bootloader version, SoftDevice family and FWID, application base, layout ABI, and zero compatibility/reserved fields; the legacy whole-image CRC covers the extension too. Scanners first count CRC-valid 44-byte base manifests, then interpret continuity only after one base identity remains. A malformed claimed extension therefore cannot make a duplicate identity disappear, and a sole half-present extension is rejected rather than treated as legacy.</p> <p>MeshCore requires the candidate extension, exact equality between its embedded version and the signed outer mOTA version, and exact agreement with the running SoftDevice family/FWID/application layout. Qualified internal/QSPI paths may bootstrap a CRC-valid installed legacy-v1 image once; the SD path never does and requires local BLM2 provisioning. Once the installed bootloader has BLM2 metadata, the candidate version must be strictly greater. Preview low bytes are <code>1..254</code>, a stable release uses <code>0xFF</code>, and low-byte zero or all-ones values are rejected. There is no remote rollback/migration override; intentional rollback uses USB/BLE DFU or SWD.</p> <p>The legacy <code>no_external_sensors</code> profiles trim selected optional environmental and ranging drivers to preserve flash headroom; they do not generally disable the I2C bus. Reduced RAK3401 and RAK4631 recipes retain INA219, INA226, INA260, and INA3221 voltage/current monitors. Those are entries in the optional sensor table, not the complete set of I2C consumers: the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals where the exact board recipe enables them. RAK3401 retains its compatible RAK12500 I2C and RAK12501/L76K UART GPS paths in sensor slot A. The plain RAK4631 repeater and Serial2 bridge retain GPS. Its RAK12501 path uses Serial1; the explicitly compiled Serial1 RS232 bridge therefore omits the combined GPS provider, including RAK12500, even though RAK12500 itself is I2C rather than UART.</p> <p>The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>. They cannot coexist on the same bus at those addresses. Leave RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use firmware built with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both modules are installed.</p> <p>Boards with onboard external flash are not silently redirected to internal staging. Mesh Solar, Nano G2 Ultra, T-Impulse Plus, ThinkNode M8, T-Echo Lite/Card, MeshTracker X1, and Wio WM1110 have board-specific QSPI hardware and need a separately matched QSPI path where available. Full Companions, other SD/QSPI/ExtraFS roles, Ethernet roles, source-only roles, and unqualified full-sensor roles are excluded from the internal-flash inventory. The exact MeshTower V2 SD role above is separately qualified for its SD path.</p> <p>This internal layout is limited to nRF52840 devices with 1 MiB internal flash, the exact S140 v6/v7 map, and the 40 KiB boot region at <code>0xF4000..0xFE000</code>. nRF52833 and smaller nRF52 parts cannot provide that map plus a non-overlapping 41,330-byte live staging slot, so configuration fails closed instead of selecting smaller or overlapping geometry.</p>"},{"location":"ota_nrf52_bootloader_update/#explicit-install-workflow","title":"Explicit install workflow","text":"<p>The <code>tools/lora_ota/lora_ota.sh</code> and <code>.ps1</code> runners can perform the discovery, transfer, verification and radio cleanup for a bootloader mOTA with <code>--no-install</code>. They detect format 3 automatically and check the destination's bootloader-specific identity/capabilities. They do not install it: the final MID/hash confirmation below remains an explicit operator action. A mixed application/bootloader ZIP requires <code>--zip-member</code>.</p> <p>Check the installed identity and capability marker:</p> <pre><code>ota bootloader\n</code></pre> <p>The response must show a CRC-valid exact identity, ABI 3 or newer, both FULL and INPLACE application codecs (<code>codecs=0x5</code>), and exact flags <code>0x09</code> for MeshTower V2 SD, <code>0x0A</code> for internal shared storage, or <code>0x0E</code> for XIAO QSPI. A bootloader row is visible in <code>ota ls</code>, but it is never autofetched or autoinstalled. Fetch its exact MID, then explicitly arm it:</p> <pre><code>ota pull &lt;MID8&gt; flash\n# wait for ota status to report the download ready\nota bootloader\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Copy both confirmation values from the second <code>ota bootloader</code> response. Ordinary <code>ota install</code> rejects a bootloader package; the bootloader command rejects an application package. The FULL-codec exception exists only for that manual bootloader MID. Ordinary application FULL remains disabled on an internal single-slot node, bootloader autofetch remains off, and a partial bootloader package is not automatically resumed after an application reboot.</p> <p>Before writing <code>APRV</code>, the application authenticates and authorizes the package: exact v3 geometry, trusted Ed25519 signer, signed/embedded identity, one unambiguous capability marker, embedded CRC, sane vectors, complete Merkle/payload/image hashes, storage-specific safe live placement, and the typed MID/hash confirmation. The manifest root and target inside the received manifest must also equal the MID/target that opened the fetch before any store is allocated. On SD, <code>APRV</code>, the retained geometry/container authorization, and the internal signed-image-hash token are published in that order before the reset trigger. OTAFIX consumes that application-written authorization and then independently rechecks the safety/integrity subset: strict v3 structure, canonical identity/capabilities, vectors, full payload SHA, embedded manifest CRC, the applicable live <code>EndF</code>/bank-settings no-overlap geometry, the SD token binding where applicable, scratch readback, and final copy hash. It does not re-run Ed25519, the signer allowlist, Merkle leaves/root, or the typed operator confirmation. Success is reported as <code>blup:C8</code>.</p>"},{"location":"ota_nrf52_bootloader_update/#failure-behavior","title":"Failure behavior","text":"<p>The feature fails closed when the MCU/map is wrong, required valid <code>EndF</code> headroom is insufficient, an unsupported external/ExtraFS role owns the target, the exact installed capability marker is absent or ambiguous, identity cannot be derived unambiguously, or any package check fails. Before the storage-specific scratch/copy step, the application and bootloader are unchanged. OTAFIX consumes the trigger and authorization before its first destructive action, so an interrupted operation cannot automatically retry a partly consumed package. On SD, the retained-RAM authorization is zero-consumed before media access; <code>APRV</code> and the fmt3 flash token may persist but are inert without a new explicit authenticated re-arm and reset trigger. No SD raw-sector handoff is created or consumed. Use USB/BLE DFU or SWD for initial provisioning and local recovery.</p> <p>For XIAO and ordinary external-QSPI details, see nRF52 repeater LoRa OTA with external QSPI.</p>"},{"location":"ota_nrf52_qspi/","title":"nRF52 repeater LoRa OTA with external QSPI","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>Selected nRF52840 repeater builds use their dedicated external QSPI NOR flash as a raw LoRa OTA staging device. This removes the internal-flash staging conflict: the complete <code>.mota</code> stays off-chip, and the bootloader can use the entire internal application region while it installs either a full image or an in-place delta.</p> <p>This is a matched application-and-bootloader feature. A board merely having an nRF52840, free RAM, or pins named QSPI is not enough. Both halves must use the exact flash wiring, and <code>ota self</code> must confirm the store and bootloader before an update is downloaded.</p>"},{"location":"ota_nrf52_qspi/#supported-repeater-families","title":"Supported repeater families","text":"<p>QSPI staging is enabled only for explicitly matched repeater-role environments (and RS232 bridge variants that directly inherit one of those repeater targets) on these currently matched families:</p> <ul> <li>Seeed XIAO nRF52840 and XIAO nRF52840 Sense modules, including the   <code>Xiao_nrf52</code>, SolarXiao 30S/33S, and XIAO-module Ikoka handheld, Nano, and   Stick repeaters</li> <li>original LilyGo T-Echo</li> <li>Elecrow ThinkNode M1 and M6</li> <li>Seeed Wio Tracker L1</li> <li>Seeed SenseCAP Solar Node P1</li> <li>RAK4631 with a RAK15001 in WisBlock sensor slot C, using the dedicated   <code>RAK_4631_repeater_rak15001_slot_c_lora_ota</code> application and matching   <code>wiscore_rak4631_board_rak15001_slot_c</code> OTAFIX bootloader</li> <li>RAK4631 with an externally wired Winbond W25Q16JV breakout on RAK19007,   using <code>RAK_4631_repeater_w25q16_lora_ota</code></li> <li>RAK3401 with its RAK13302 1 W radio and the same externally wired W25Q16JV   breakout on RAK19007, using   <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code></li> </ul> <p>Heltec T114 is intentionally not in this list. Its public V1, V2.0, and V2.1 schematics show U9 (MX25R1635F) as an optional QSPI footprint, so standard T114 application and bootloader targets do not assume that external NOR is populated.</p> <p>The XIAO-module derivatives use the matching XIAO or XIAO Sense OTAFIX bootloader shown by the module's <code>INFO_UF2.TXT</code>. Do not substitute a similar bootloader for a board with different QSPI pins. For example, the T-Echo Card and T-Echo Lite have different flash wiring and are not enabled by the original T-Echo target.</p> <p>Companion builds are intentionally excluded. Some companion targets use the same external QSPI as a LittleFS message/data store, where raw OTA staging would corrupt the filesystem; other companions simply do not assign that chip to OTA. Room-server, sensor, and KISS roles are unchanged. Raw QSPI OTA is scoped to the explicitly matched repeater-derived environments.</p>"},{"location":"ota_nrf52_qspi/#rak15001-placement-and-module-conflicts","title":"RAK15001 placement and module conflicts","text":"<p>RAK15001 is a 2 MiB GD25Q16C standard SPI module, not a quad-I/O flash. The dedicated RAK4631 target uses the nRF52840 QSPI peripheral in its single-data-line FAST_READ/page-program modes at 8 MHz and accepts only the module's exact <code>C8 40 15</code> JEDEC ID. <code>ota self</code> reports <code>QSPI store:2048K</code> only when the expected module responds. An empty slot or a different SPI device reports <code>QSPI store:ERR 0K</code>, and install is refused.</p> <p>The module is electrically usable in sensor slot A-D because those slots share the SPI signals and RAK15001 has onboard 10 kOhm pull-ups on WP# and HOLD#. The supported MeshCore/OTAFIX combination nevertheless requires slot C. It is the placement that remains safe when a RAK12501 GNSS is fitted in either of its supported slots, A or D: slot C avoids the GNSS PPS/reset nets on IO1/IO2 and IO5/IO6. In particular, GPS in A plus flash in B would share IO1/IO2 through the modules' auxiliary pins.</p> <p>Only one device that uses the shared WisBlock SPI chip-select may be fitted. Do not combine this target with RAK13800 Ethernet, RAK15002 SD, or another SPI module. RAK13800 and RAK15001 cannot coexist because they use the same SPI chip-select. Update a RAK13800 Ethernet build locally over USB using the release's Manual UF2 or Serial DFU (.zip) download; it cannot use this RAK15001 LoRa-OTA staging target.</p> <p>RAK3401 with RAK13302 remains incompatible with RAK15001. The 1 W radio uses the same WisBlock SPI clock/data pins and the same chip-select as RAK15001. Firmware cannot independently select or detect those two chips, so a stock RAK3401 + RAK15001 assembly cannot provide reliable OTA staging without a hardware chip-select rework. This restriction does not apply to the separate-CS W25Q16 wiring below.</p> <p></p>"},{"location":"ota_nrf52_qspi/#one-w25q16-wiring-for-rak4631-or-rak3401-rak13302","title":"One W25Q16 wiring for RAK4631 or RAK3401 + RAK13302","text":"<p>An external Winbond W25Q16JV breakout can remain attached to a RAK19007 while the core is changed between RAK4631 and RAK3401 + RAK13302. It shares only the WisBlock SPI clock/data nets and has its own chip-select on AIN1:</p> W25Q16 breakout RAK19007 connection nRF52840 / Arduino pin <code>CLK</code> IO connector pin 26, <code>SPI_CLK</code> P0.03 / <code>3</code> <code>DO</code> / MISO IO connector pin 27, <code>SPI_MISO</code> P0.29 / <code>29</code> <code>DI</code> / MOSI IO connector pin 28, <code>SPI_MOSI</code> P0.30 / <code>30</code> <code>CS</code> J11 <code>AIN1</code> P0.31 / <code>31</code> <code>VCC</code> J12 <code>VDD</code> regulated 3.3 V <code>GND</code> J12 <code>GND</code> ground <p>Fit a physical approximately 10 kOhm pull-up from <code>CS</code> to J12 <code>VDD</code>. That keeps the flash deselected during reset, bootloader entry, and a core-module swap. Power the breakout only from J12 <code>VDD</code>; never use J11 <code>VBAT</code>, which can exceed the flash's supply rating. The six-pin breakout does not expose WP#/IO2 or HOLD#/IO3; do not add nRF IO2/IO3 wiring. A breakout with an onboard power LED works, but that LED draws continuously and is undesirable for low-power or solar operation.</p> <p>This arrangement consumes no WisBlock sensor slot. However, <code>SPI_CLK</code>, <code>SPI_MISO</code>, and <code>SPI_MOSI</code> are not available on the easy 2.54 mm J10/J11/J12 headers. Those three signals require a short underside-pad tap or a suitable IO-connector interposer at pins 26-28. J11 and J12 alone are not sufficient.</p> <p>GPS remains supported in sensor slot A. RAK12500 uses I2C, while RAK12501/L76K uses UART plus its auxiliary control signals; neither uses the shared SPI clock/data bus. On RAK4631 the built-in SX1262 has a separate private SPI bus. On RAK3401 the RAK13302 and flash share clock/data, but have independent chip-selects: RAK13302 NSS is P0.26 and flash CS is P0.31. The matched firmware holds the radio NSS high while it temporarily hands the bus to the flash, then restores the radio SPI interface.</p> <p>The breakout target accepts only a 2 MiB W25Q16 with JEDEC ID <code>EF 40 15</code> and runs it at 8 MHz in standard single-data-line SPI mode. A substituted W25Q32, W25Q64, or W25Q128 fails closed instead of being treated as the OTA store. Use the complete application/bootloader identity row that matches the fitted core:</p> Core and radio PlatformIO environment MOTA hardware identity OTAFIX board / DFU device name RAK4631 built-in SX1262 <code>RAK_4631_repeater_w25q16_lora_ota</code> <code>RAK4631_W25Q16</code> <code>wiscore_rak4631_w25q16</code> / <code>4631_W25Q16_DFU</code> RAK3401 + RAK13302 1 W <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code> <code>RAK3401_RAK13302_W25Q16</code> <code>wiscore_rak3401_rak13302_w25q16</code> / <code>3401_W25Q16_DFU</code> <p>The physical flash wiring is identical, but the two application and bootloader pairs are not interchangeable.</p>"},{"location":"ota_nrf52_qspi/#one-time-prerequisite","title":"One-time prerequisite","text":"<p>Install a QSPI-capable OTAFIX 2.4.1 preview.9 or newer bootloader for the exact board from the OTAFIX releases before using LoRa OTA. The release notes must explicitly list that board's QSPI mode. Also install the SoftDevice version expected by that target. The application refuses the install handoff when the bootloader does not advertise QSPI support.</p> <p>For the external W25Q16 option, install the corresponding bootloader once before installing its MeshCore application: <code>wiscore_rak4631_w25q16</code> (<code>DEVICE_NAME=4631_W25Q16_DFU</code>) for RAK4631, or <code>wiscore_rak3401_rak13302_w25q16</code> (<code>DEVICE_NAME=3401_W25Q16_DFU</code>) for RAK3401 plus RAK13302. Use only a release that explicitly names that exact pairing. Do not substitute the RAK15001 bootloader or swap the two W25Q16 bootloaders merely because the base-board wiring is the same.</p> <p>For the first migration from the ordinary <code>wiscore_rak4631_board</code> bootloader to <code>wiscore_rak4631_board_rak15001_slot_c</code>, use Nordic serial DFU or a compatible BLE DFU client with the exact slot-C OTAFIX combined bootloader + SoftDevice DFU package (or use SWD), then reinstall the slot-C MeshCore application. The release filename has this form:</p> <pre><code>wiscore_rak4631_board_rak15001_slot_c_bootloader-&lt;OTAFIX-version&gt;_s140_6.1.1.zip\n</code></pre> <p>Do not copy the slot-C bootloader-update UF2 onto the stock UF2 drive. The stock loader is bound to <code>DEVICE_NAME=4631_DFU</code>, while the slot-C image is bound to <code>4631_15001C_DFU</code>, so that UF2 is intentionally rejected. After the one-time DFU/SWD migration, later canonical slot-C bootloader UF2 files work normally. The combined OTAFIX package above is not the MeshCore application's Serial DFU <code>.zip</code>; an application package does not migrate the bootloader.</p> <p>After installing the repeater application, check:</p> <pre><code>get bootloader.ver\nota self\nota status\nota qspi\n</code></pre> <p>A ready RAK15001 target reports all of the following:</p> <pre><code>QSPI store:2048K\nbootloader: QSPI apply OK\nbl:QSPI\nQSPI jedec=C84015 size=2048K sr1=00 stage=jedec\n</code></pre> <p>A ready external W25Q16 target instead identifies the Winbond part:</p> <pre><code>QSPI store:2048K\nbootloader: QSPI apply OK\nbl:QSPI\nQSPI jedec=EF4015 size=2048K sr1=00 stage=jedec\n</code></pre> <p>Other supported boards can report a capacity different from 2048K; the RAK15001 and W25Q16 targets must report exactly 2048K and their respective exact JEDEC IDs. <code>QSPI store:ERR 0K</code>, <code>NO QSPI</code>, or <code>bl:NO-QSPI</code> means the flash wiring, flash power, chip-select pull-up, application, or bootloader does not match. Do not start an install in that state.</p> <p><code>ota qspi</code> is a read-only diagnostic probe available on QSPI OTA builds. It reports the exact JEDEC ID, status-register byte, last store stage, and the first latched storage error. Run it after an immediate <code>storage error</code> before starting another pull; later capacity probes preserve that failure detail.</p>"},{"location":"ota_nrf52_qspi/#capacity-and-package-types","title":"Capacity and package types","text":"<p>The store reads the JEDEC capacity at runtime and accepts supported 1 MiB through 16 MiB devices using 24-bit addressing. QSPI capacity is not the final firmware limit. The reconstructed application, including its 56-byte <code>EndF</code> trailer, must fit its build's linked application region:</p> SoftDevice layout Application region Maximum image S140 v7, boot-update-capable XIAO module <code>0x27000..0xE0000</code> <code>0xB9000</code> (757,760 bytes) S140 v7, app base <code>0x27000</code> <code>0x27000..0xED000</code> <code>0xC6000</code> (811,008 bytes) S140 v6, app base <code>0x26000</code> <code>0x26000..0xED000</code> <code>0xC7000</code> (815,104 bytes) <p>The XIAO limit is deliberately 52 KiB smaller. Its linker and post-link record cap every ordinary application at <code>0xE0000</code>; OTAFIX reserves <code>0xE0000..0xEA000</code> as a 40 KiB self-update scratch bank, with the remaining gap left unused before InternalFS. Full and delta application packages for these targets derive their effective application end from that <code>0xE0000</code> record and are rejected if their reconstructed image or detools geometry crosses it.</p> <p>A full package needs only the new raw <code>firmware.hex</code> or non-merged application image. An in-place delta still needs the exact image currently running. The automation uses a conservative <code>0xC6000</code> detools workspace for external nRF52 staging so one package setting is safe for both layouts.</p> <p>For online automation, QSPI is detected from <code>ota self</code> or <code>ota status</code>. For offline preparation, identify it explicitly:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.zip target-name \\\n  --prepare-only \\\n  --platform nrf52 \\\n  --nrf-qspi \\\n  --target-id 12345678 \\\n  --target-hw Xiao_nrf52\n</code></pre> <p>Use the real target ID and hardware identity from the destination. A ready full <code>.mota</code> normally uses that target ID for discovery and routing. An operator can deliberately override the routing target for a role change, so <code>target_id</code> is not an apply-time safety assertion; the destination still enforces the package's hardware identity before approval.</p>"},{"location":"ota_nrf52_qspi/#explicit-xiao-bootloader-updates-over-lora","title":"Explicit XIAO bootloader updates over LoRa","text":"<p>This section documents the deployed XIAO raw-QSPI layout. Curated nRF52840 targets without external staging use a separate internal-flash layout with the same explicit operator safety model; see nRF52 bootloader updates over LoRa.</p> <p>Bootloader delivery is available only when all of these are already true:</p> <ul> <li>the application is an <code>OTA_QSPI_BOOTLOADER_UPDATE</code> XIAO-module repeater build   linked below <code>0xE0000</code>;</li> <li><code>ota bootloader</code> shows a CRC-valid installed <code>XIAO_DFU</code> embedded identity for   board ID <code>28860044</code> (base) or <code>28860045</code> (Sense);</li> <li>the installed OTAFIX marker reports ABI 3 or newer and both QSPI (<code>0x04</code>) and   boot-update (<code>0x08</code>) capability bits;</li> <li>the package is the exact signed v3/40-KiB/1-KiB-block profile for that board,   and its signer is already in <code>ota key</code>'s trusted allowlist.</li> </ul> <p>This is not part of normal automation. Bootloader catalog rows are labelled <code>bootloader</code>; even a capable node never autofetches or autoinstalls them, and ordinary <code>ota install</code> rejects them in every application backend. The <code>tools/lora_ota</code> deployment runner also refuses v3 packages. Fetch and arm one only with the explicit flow:</p> <pre><code>ota ls\nota pull &lt;MID8&gt; flash\n# wait for ota status to report the same bootloader download as ready\nota bootloader\n# copy the exact mid= and hash= values printed above\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>The pull command is only transport intent; it does not authorize an install. The final command must reproduce both the complete staged manifest ID and the first eight bytes of its signed image hash. Before approval the application again checks package/root/payload/image hashes, Ed25519 signature and trusted allowlist, exact signed <code>XIAO_BL_...</code> ID, installed and incoming embedded   manifest/CRC/name/board identity, vector table, ABI-3 QSPI+boot-update marker,   and the adjacent CRC-covered <code>BLM2</code>/<code>SOFT</code> continuity extension at the exact   final-image offset <code>0x9FB4</code>. The embedded   boot version must equal the signed outer package version, the SoftDevice   family/FWID/application base/layout ABI must match the running platform, and   a successor to installed BLM2 must be strictly newer. Low-byte-zero and   all-ones versions are invalid. Remote rollback is refused; use local DFU/SWD.</p> <p>After the reply drains, GPREGRET <code>0x6B</code> and GPREGRET2 <code>0x51</code> enter the special OTAFIX path. <code>APRV</code> carries the app's signature/allowlist and explicit operator authorization decision. OTAFIX independently rechecks the strict structure, identity/capabilities, vectors, payload SHA, embedded CRC, and copy hashes before using the reserved scratch bank to replace its own <code>0xF4000..0xFE000</code> region. The running application remains preserved; a rejected candidate returns to it unchanged. Post-reboot <code>ota status</code> reports bootloader-update diagnostics as <code>blup:C0</code> to <code>blup:CF</code> (<code>blup:C8</code> is success), separately from ordinary application <code>blrc</code>.</p> <p>This feature cannot update a stock or old bootloader that lacks the capability marker: perform the first exact-board combined bootloader+SoftDevice migration over USB/BLE DFU or SWD. Do not attempt to bootstrap it with a v3 package.</p>"},{"location":"ota_nrf52_qspi/#storage-ownership-and-recovery","title":"Storage ownership and recovery","text":"<p>The QSPI store is raw, not a file inside LittleFS. It owns the flash from offset zero, erases 4 KiB sectors as blocks arrive, writes data before progress metadata, and verifies every programmed page. A previously interrupted download is reopened only when its header and trailer are valid; every claimed block is re-hashed before it is trusted. Between a probe, transfer operation, or checkpoint, firmware puts the NOR into deep power-down, deactivates the nRF QSPI peripheral, and turns off a board-provided flash power-enable pin. The next operation powers the chip, shifts the NOR's <code>0xAB</code> wake command over GPIO, then activates the nRF QSPI peripheral and identifies the flash. Waking it before peripheral activation is required because a flash in deep power-down ignores the activation traffic itself. Merely running <code>ota self</code> therefore does not leave QSPI drawing active-mode current or prevent the following operation from reactivating it.</p> <p>Installing a QSPI repeater build over a former companion build therefore repurposes the external flash and destroys companion filesystem data as OTA sectors are written. Back up anything important first. Returning to a companion build may require formatting its external data store.</p> <p>Before changing internal application flash, the application verifies package integrity, hardware identity, signature policy, and bootloader capabilities. The target ID selects discovery/fetch routing and can be deliberately overridden; it is not a second hardware gate. The bootloader then verifies a full payload before its first application erase. For a delta, the application rejects invalid detools geometry before approval and the bootloader independently repeats the base and geometry checks before applying it. It clears the one-shot approval marker before invalidating the running image. If power is lost after application writes begin, the bank remains invalid and OTAFIX enters USB/BLE recovery rather than booting a partial image.</p> <p>See Easy firmware updates over LoRa for the transfer commands and the OTA protocol for the container and handoff details.</p>"},{"location":"ota_protocol/","title":"MeshCore OTA - <code>.mota</code> container &amp; LoRa protocol","text":"<p>This is the single source of truth for MeshCore's over-the-air firmware update system (\"mOTA\"). It is written for developers who want to implement an interoperable peer (server, fetcher, relay, or host tool) in another codebase or project. Everything below is implemented in this repository and covered by host, simulation, build, or hardware tests as noted in the relevant section. Hardware qualification is target- and chain-specific; do not infer it from implementation alone. Where a section names a source file, that file is the authoritative reference for byte-level details.</p> <p>Just want to update your node? See the plain-language OTA user guide - this document is the technical/wire specification.</p> <p>Design goals</p> <ul> <li>Distribute firmware over LoRa as a self-verifying, resumable, single-source block transfer that   survives reboots and never auto-applies without explicit consent.</li> <li>Trustless mesh relay: repeaters may forward packets while the source alone serves firmware data;   integrity is content-addressed   against a signed merkle root, so a relay need not be trusted and never needs the signing keys.</li> <li>Primary while transferring: periodic discovery stays at background priority, but manifest, block,   data, and proof packets for an active fetch use primary queue priority at every relay hop.</li> <li>Portable: the engine (<code>src/helpers/ota/OtaManager</code>) is Arduino/radio/crypto-free and host-testable,   so the same logic drives a device, a simulation, or a third-party implementation.</li> </ul> <p>Source map (all under <code>src/helpers/ota/</code> unless noted)</p> Concern File Constants, enums, flags <code>OtaFormat.h</code> Container/manifest parse <code>MotaContainer.{h,cpp}</code> Merkle tree + proofs <code>MerkleTree.{h,cpp}</code> EndF self-identity <code>FirmwareInfo.{h,cpp}</code> Wire message codec <code>OtaProtocol.{h,cpp}</code> Session engine (serve+fetch+discovery) <code>OtaManager.{h,cpp}</code> Multi-mota / folder relay <code>OtaSource.h</code>, <code>MotaSourceSerial.{h,cpp}</code>, <code>MotaSeederProto.h</code> Staging stores <code>OtaStore.h</code>, <code>OtaStoreFlashNrf52.*</code>, <code>OtaStoreFlashEsp32.*</code> Apply <code>OtaApply.*</code>, bootloader <code>Adafruit_nRF52_Bootloader_OTAFIX</code> Device glue (CLI/context) <code>OtaCli.cpp</code>, <code>OtaContext.h</code> Host tooling <code>motatool</code> (standalone Rust CLI: build/verify/inspect/serve); <code>tools/mota/</code> (Python reference lib <code>motalib.py</code> + build/test glue)"},{"location":"ota_protocol/#1-conventions","title":"1. Conventions","text":"<ul> <li>Endianness: all multi-byte integers are little-endian unless stated.</li> <li>Hashes (multihash): the hash family is declared once per manifest via <code>hash_algo</code> =   <code>0x12</code> = SHA-256 (the multihash code for sha2-256).   Truncations used:</li> <li><code>sha2-256:4</code> - first 4 bytes of the SHA-256 digest. Merkle leaves, internal nodes, root, proofs,     <code>manifest_id</code>, and the discovery <code>set_digest</code>.</li> <li><code>sha2-256:8</code> - first 8 bytes. Base-firmware identity (<code>base_hash</code>, <code>EndF.body_hash</code>).</li> <li><code>sha2-256:32</code> - full digest. The image security anchor (<code>image_hash</code>).   Digests are stored bare (just the truncated bytes); the family is implied by <code>hash_algo</code>.</li> <li>Signatures: Ed25519 (RFC 8032), 64-byte detached signature, 32-byte public key.</li> </ul> <p>Reference constants (<code>OtaFormat.h</code>):</p> Name Value ASCII / note Container <code>MAGIC</code> <code>6D 4F 54 41</code> <code>mOTA</code> Container <code>TRAILER</code> <code>76 6B 34 39 36</code> <code>vk496</code> <code>EndF</code> marker <code>45 6E 64 46</code> <code>EndF</code> <code>hash_algo</code> (sha2-256) <code>0x12</code> multihash code application <code>format_ver</code> <code>0x02</code> ordinary full/delta application package bootloader <code>format_ver</code> <code>0x03</code> privileged exact-identity nRF52 bootloader package only <code>approval</code> = not approved <code>FF FF FF FF</code> erased NOR word <code>approval</code> = approved <code>41 50 52 56</code> <code>APRV</code> <code>MFLAG_FULL</code> <code>0x01</code> flags bit0 <code>MFLAG_SIGNED</code> <code>0x02</code> flags bit1 <code>MFLAG_BOOTLOADER</code> <code>0x04</code> flags bit2; valid only in the exact v3 bootloader profile <code>CODEC_FULL</code> / <code>_SEQUENTIAL</code> / <code>_INPLACE</code> <code>0</code> / <code>1</code> / <code>2</code> Section 5 <code>PAYLOAD_TYPE_OTA</code> <code>0x0C</code> MeshCore packet type (<code>src/Packet.h</code>) <code>MAX_PACKET_PAYLOAD</code> <code>184</code> usable bytes per packet (<code>src/MeshCore.h</code>) Default application block size <code>2048</code> <code>block_size_log2 = 0x0B</code>; deployed 1 KiB application packages remain accepted Bootloader-package block size <code>1024</code> fixed <code>block_size_log2 = 0x0A</code> for format 3 OTA discovery TX priority <code>250</code> background (<code>OTA_TX_PRIORITY</code>, <code>src/Mesh.h</code>) OTA active-transfer TX priority <code>0</code> primary (<code>OTA_TRANSFER_TX_PRIORITY</code>, <code>src/Mesh.h</code>) <p>Current application firmware publishes its receive/reassembly ceiling as the compact <code>maxblk:2048</code> field near the front of both <code>ota status</code> and <code>ota self</code>. Keeping the field ahead of variable diagnostics ensures it survives the 160-byte remote-admin reply limit. Host updaters must treat an absent field as the deployed legacy capability (<code>1024</code>), reject a ready package whose manifest block size exceeds that capability, and use the reported size when turning a raw firmware image into a new application package. This capability does not change the format-3 bootloader package's fixed 1 KiB geometry.</p>"},{"location":"ota_protocol/#2-firmware-image-the-endf-trailer","title":"2. Firmware image &amp; the <code>EndF</code> trailer","text":"<p>Every OTA-capable build appends a fixed 56-byte <code>EndF</code> trailer to its flashed image so a running node can discover its own size and self-describing identity on any MCU (no linker symbols needed). Every field is always present at a constant offset. Implemented by <code>FirmwareInfo.cpp</code>; appended at build time by <code>tools/mota/pio_endf.py</code> (post-build hook).</p> <pre><code>flashed image = BODY (image bytes) || EndF trailer\nEndF trailer (fixed 56 bytes):\n  off 0   4   \"EndF\"        45 6E 64 46\n  off 4   4   body_len      uint32 LE - length of BODY (excludes the whole trailer)\n  off 8   8   body_hash     sha2-256:8 of BODY\n  off 16  4   fw_version    uint32 LE, packed MAJOR&lt;&lt;24|MINOR&lt;&lt;16|PATCH&lt;&lt;8|pre  (0 = unknown)\n  off 20  4   target_id     uint32 LE - sha2-256:4(pio_env): hardware + role + partition (fetch routing)\n  off 24  32  hw_id         NUL-padded ASCII hardware tag (brick-safety), e.g. \"RAK4631\" (\"\" = unknown)\n</code></pre> <ul> <li>Self-describing identity. <code>pio_endf.py</code> uses <code>build.sh</code>'s <code>MOTA_TARGET_ID</code> when present (required for   virtual LoRa-OTA build names), otherwise it computes <code>target_id</code> from the PlatformIO env name. It reads   <code>hw_id</code> from <code>MOTA_HW_ID</code> and <code>fw_version</code>   from <code>FIRMWARE_VERSION</code>. The device reads them back (<code>ota_self_firmware()</code>), so a node's advertised   identity is correct regardless of how it was built - and the packaging tool reads them straight from a raw   <code>.bin</code> (no <code>--target-env</code>/<code>--fw-version</code> flags, no reliance on filenames; Section 9, Section 13). A dev build with no   dotted version simply carries <code>fw_version = 0</code> / empty <code>hw_id</code> (= unknown) - still a full 56-byte trailer.</li> <li>Size discovery: scan flash from the partition top downward for the <code>EndF</code> marker; the byte before it   is the last BODY byte (the trailer is always 56 bytes). See <code>ota_self_firmware()</code>.</li> <li>Delta base matching: a node's <code>body_hash</code> is read directly from its own <code>EndF</code>; a delta's <code>base_hash</code>   (Section 5) must equal it. <code>body_hash</code> is over BODY only.</li> <li>No circularity: <code>EndF</code> hashes only the BODY, never itself.</li> </ul> <p>The \"reconstructed image\" referenced by the manifest is the full <code>BODY || EndF</code> (what gets flashed).</p>"},{"location":"ota_protocol/#esp32-application-slot-profiles","title":"ESP32 application-slot profiles","text":"<p>ESP32 Companion firmware is exempt from the portable-slot limit. When an exact Full recipe exists, one expanded-partition image supplies USB, BLE, WiFi, source-only LoRa OTA, and persistent USB logging instead of separate transport artifacts. A small set of high-capacity, non-PSRAM classic ESP32 companions use 100 contacts, 8 group channels, and a 16-frame offline queue in that combined image to preserve internal-DRAM headroom. MQTT observers and ESP-NOW bridges always use FULL builds because fitting them into the legacy slot would require removing CLI and role features. Except for those FULL roles and the ESP32-C6 case below, non-companion ESP32 artifacts, including room, sensor, and repeater roles, must fit the legacy slot from <code>0x10000</code> up to <code>0x150000</code> (<code>0x140000</code>, 1,310,720 bytes), including the 56-byte <code>EndF</code> trailer. The build checks both that limit and the target's actual app partition. The ESP32-C6 <code>no_external_sensors</code> OTA siblings are the narrow exception: the Arduino 3.x WiFi runtime cannot fit that cross-family ceiling, so those images retain their established target-specific 1920 KiB or larger A/B app layout and are checked against the actual app partition. For standalone ESP32 and nRF52 repeater and room-server roles that need a lean staging profile, <code>build.sh</code> also exposes an explicit <code>*_lora_ota_no_external_sensors</code> artifact: the ordinary role remains sensor-enabled, while that sibling trims selected optional environmental/ranging drivers for LoRa distribution. SolarXiao 30S and 33S use matched external QSPI staging, so their ordinary full-sensor repeater and room-server images are already install-capable and no redundant lean sibling is generated. Integrated GPS and other board-native telemetry remain enabled where the target selects the GPS-preserving lean profile. The legacy suffix describes a driver trim, not removal of the generic I2C bus. Reduced RAK3401 and RAK4631 profiles retain INA219, INA226, INA260, and INA3221 voltage/current monitors. These are retained optional-sensor-table drivers, not the only I2C consumers: SSD1306 display, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals where selected by the board recipe. The RAK3401 OTA repeater also retains RAK12500 I2C and RAK12501/L76K UART GPS support; install either GPS module in sensor slot A because slot D conflicts with the RAK13302 radio's BUSY/DIO1 lines. The plain RAK4631 OTA repeater and its Serial2 bridge retain GPS. RAK12501 uses Serial1. Its explicitly compiled Serial1 bridge therefore omits the combined GPS provider, including RAK12500, even though RAK12500 itself does not use the UART.</p> <p>The firmware-configured INA3221 address and RAK12500 address are both <code>0x42</code>, so those devices cannot share one bus at those addresses. Keep RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use firmware built with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both are installed.</p> <p>ESP32 siblings retain the compact browser WiFi updater and use up to 254 neighbors. Internal-DRAM-constrained targets use 50 as recorded in the artifact capability manifest; see ESP32 memory budget. RP2040 and STM32 targets are not offered because those platforms do not yet have a safe bootloader/apply path.</p> <p>nRF52 LoRa-OTA siblings use size optimization rather than the Adafruit platform's default <code>-Ofast</code>. This keeps the runtime software Ed25519 fallback from being expanded into tens of kilobytes of repeated curve arithmetic while retaining CC310 hardware crypto, hardware RNG mixing, telemetry history, and board-native features.</p> <p>WiFi-heavy non-companion roles are not reduced to fit the legacy application slot. <code>build.sh</code> automatically promotes every ESP32 MQTT observer and ESP-NOW bridge to the expanded FULL partition profile. These artifacts retain the complete role CLI, WebConfig where supported, display and optional sensor support, full timezone and TLS behavior, and the board's normal power-management implementation. The compact CLI is not compiled into any build. Ordinary repeater and room-server builds remain sensor-enabled; only explicitly named <code>*_lora_ota_no_external_sensors</code> siblings trim selected optional environmental/ranging drivers for LoRa distribution, and those siblings retain the complete CLI and target-declared I2C peripherals.</p> <p>MQTT observer radio and bridge preferences use verified temporary files plus a recoverable backup. A reset during a settings save restores the last committed common preference image or publishes the completed new image; it does not leave a partially written <code>/com_prefs</code> file to fail on the next boot. A truncated legacy image is rejected before any partial radio or string fields are applied, then rewritten from safe defaults.</p> <p>Option 3 in <code>build.sh</code> emits one <code>*-full-usb-wifi-ota-*</code> ESP32 artifact for each FULL-capable non-companion hardware/role that has a matching MQTT environment. It compiles USB packet logging and direct WiFi MQTT together. A <code>*-full-logging-ota-*</code> fallback is emitted only when there is no MQTT sibling; ordinary non-OTA roles compile runtime USB logging into their canonical image, so separate standard-logging artifacts are not emitted. Non-MQTT FULL twins are also skipped for covered ESP32 roles. MQTT observers and ESP-NOW bridges are emitted only with expanded FULL partitions. Menu option 8, or <code>build-full-esp32-firmwares</code>, builds the unified profiles plus necessary fallbacks. Menu option 9, or <code>build-full-esp32-logging-firmwares</code>, builds only those fallbacks. FULL builds restore WebConfig, display support, optional external sensors, and the full role CLI and feature set, full ElegantOTA where that target declares the required library, and LoRa OTA for every included role, including room servers, sensors, observers, and bridges. They use expanded A/B partition tables: 1984 KiB application slots on 4 MiB boards and the framework's larger dual-OTA tables on 8 MiB and 16 MiB boards. Explicit <code>*_lora_ota_no_external_sensors</code> targets are not duplicated; their ordinary repeater or room-server build is the FULL, sensor-enabled counterpart. The <code>*-full-usb-wifi-ota-*</code> profile enables USB packet logging and MQTT, with a persistent <code>logging.output</code> selector; its verbose internal debug remains off. The fallback <code>*-full-logging-ota-*</code> profile enables USB debug and packet logging and has no MQTT target. Install a matching <code>*-full-usb-wifi-ota-*-merged.bin</code> or <code>*-full-logging-ota-*-merged.bin</code> over USB once to write the expanded partition table. After that, its matching non-merged FULL application image can be installed through USB, WiFi OTA, or LoRa OTA. Do not install a non-merged FULL image onto a node that still has its old partition table.</p> <p>Implementer note: the bootloader (and any non-Arduino consumer) MUST locate the body extent by scanning for <code>EndF</code>, never by trusting a stored size - see the bootloader contract in Section 12.</p>"},{"location":"ota_protocol/#3-the-mota-container","title":"3. The <code>.mota</code> container","text":"<p>The distributed form (host-built, wire-transferred). Parsed by <code>mota_parse()</code> in <code>MotaContainer.cpp</code>.</p> <pre><code>off            size   field\n0              4      MAGIC = 6D 4F 54 41\n4              4      MOTA_TOTAL_SIZE  uint32 LE - total container bytes (incl. manifest, leaves[],\n                                       payload, trailer). Lets a node pre-reserve staging and compute\n                                       write_start = staging_region_end - MOTA_TOTAL_SIZE.\n8              M      MANIFEST         (Section 4; M = 197 fixed + leaves[], 4*BC; no length field - BC from payload_size)\n8 + M          P      PAYLOAD          (payload_size bytes; delta or full image)\n8 + M + P      5      TRAILER = 76 6B 34 39 36\n</code></pre> <p><code>MOTA_TOTAL_SIZE = 4 + 4 + M + P + 5</code>. The manifest <code>M</code> includes <code>leaves[]</code>; the manifest-minus-leaves prefix (<code>mfl</code>, sent over the wire as <code>OTA_MANIFEST</code>) is <code>[8, leaves_off)</code>.</p> <p>Staged (in-flash) form. Written bottom-aligned so <code>TRAILER</code> ends at <code>staging_region_end</code>. Identical bytes, except the device mutates two regions in place (both NOR-safe, no re-erase): the <code>leaves[]</code> slots (filled as blocks arrive - Section 7) and the 4-byte <code>approval</code> field (on owner consent - Section 4.2). Everything else is immutable.</p>"},{"location":"ota_protocol/#4-the-manifest","title":"4. The manifest","text":"<p>Fixed layout. Every field sits at a constant offset and is always present - <code>base_hash</code>, <code>signer_pubkey</code> and <code>signature</code> are zero-filled when not applicable (a full image / an unsigned container). Only <code>leaves[]</code> is variable (one 4-byte hash per block). So the manifest-minus-leaves (<code>mfl</code>) is always 197 bytes and the parser is plain offset reads - no conditionals. Parsed by <code>mota_parse_manifest()</code>.</p> <pre><code>off  size   field            notes\n0    1      format_ver       = 0x02 application, or 0x03 privileged bootloader package\n1    1      flags            bit0 FULL; bit1 SIGNED; bit2 BOOTLOADER; bits3-7 reserved 0\n2    1      hash_algo        0x12 = sha2-256\n3    4      target_id        device/arch/role discriminator (Section 9)\n7    4      fw_version       MAJOR&lt;&lt;24 | MINOR&lt;&lt;16 | PATCH&lt;&lt;8 | pre   (comparable uint32)\n11   4      image_size       size of the reconstructed image (BODY||EndF)\n15   4      payload_size     PAYLOAD bytes in this container\n19   1      block_size_log2  e.g. 0x0B = 2048 (new application default); 0x0A = deployed 1024\n20   4      merkle_root      sha2-256:4 over PAYLOAD blocks (Section 6) - also the manifest_id\n24   32     image_hash       sha2-256:32 of the reconstructed image - SECURITY anchor\n56   1      codec_id         0=full/raw, 1=detools-sequential, 2=detools-in-place\n57   32     hw_id            NUL-padded ASCII hardware tag (e.g. \"RAK4631\"); same tag =&gt; bootable-compatible.\n                             SIGNED. Applier refuses a mismatch (brick-safety); empty on either side = skip.\n89   8      base_hash        sha2-256:8 of the BASE image's BODY (== that build's EndF.body_hash). 0 if FULL.\n97   32     signer_pubkey    Ed25519 public key. 0 if not SIGNED.\n129  64     signature        Ed25519 over manifest[0, 129). 0 if not SIGNED.\n193  4      approval         FF FF FF FF = not approved; 41 50 52 56 (\"APRV\") = approved\n--- end of manifest-minus-leaves: mfl = 197 (constant); leaves_off = 8 + 197 = 205 in the container ---\n197  4*BC   leaves[]         BC = ceil(payload_size / 2^block_size_log2). sha2-256:4 each (the only variable field)\n</code></pre> <p>The signature always covers <code>manifest[0, 129)</code> (the head + <code>base_hash</code> + <code>signer_pubkey</code>). <code>approval</code> is outside the signed region so it can be flipped in place on consent without breaking the signature.</p> <p>Manifest-minus-leaves size (<code>mfl</code>) is a constant 197 bytes for every container (full or delta, signed or unsigned). At 197 bytes the manifest exceeds one packet, so <code>OTA_MANIFEST</code> is always sent multi-fragment (Section 8.4, 2 fragments) and reassembled by the fetcher.</p> <p>The two versions are deliberately disjoint. Version 2 accepts application packages only and rejects the BOOTLOADER bit. Version 3 accepts only flags exactly <code>FULL|SIGNED|BOOTLOADER</code>; a non-bootloader v3 package is invalid. Consequently, deployed v2-only application parsers reject a bootloader package before they can mistake its raw 40 KiB payload for an application image.</p>"},{"location":"ota_protocol/#41-signed-region","title":"4.1 Signed region","text":"<p><code>signature</code> covers manifest bytes <code>[0, 129)</code> - the head + <code>base_hash</code> + <code>signer_pubkey</code>. It does not cover <code>approval</code> or <code>leaves[]</code>:</p> <ul> <li><code>leaves[]</code> are verified against the signed <code>merkle_root</code> (Section 6), so they need no separate signature.</li> <li><code>approval</code> is device-local consent (Section 4.2), deliberately outside the signature.</li> </ul>"},{"location":"ota_protocol/#42-the-approval-field","title":"4.2 The <code>approval</code> field","text":"<ul> <li>Distributed and forced on ingest to <code>FF FF FF FF</code> (a peer can never pre-approve).</li> <li>The local owner's <code>ota applydelta</code> writes <code>41 50 52 56</code> (<code>\"APRV\"</code>) - a single NOR-safe write (only clears   bits from the erased word). Any partial/other value reads as not-approved (fail-safe).</li> <li>Bound to this image (lives in this <code>.mota</code>'s manifest, re-erased when a new <code>.mota</code> is staged).</li> <li>A consent marker, not a security primitive. Authenticity = <code>signature</code> + <code>image_hash</code> + <code>hw_id</code>.</li> </ul>"},{"location":"ota_protocol/#43-privileged-nrf52-bootloader-package-profile","title":"4.3 Privileged nRF52 bootloader package profile","text":"<p>A v3 bootloader package has a deliberately narrow, non-extensible profile:</p> <ul> <li>flags exactly <code>FULL|SIGNED|BOOTLOADER</code>, <code>CODEC_FULL</code>, nonzero <code>fw_version</code>, zero <code>base_hash</code>;</li> <li>a raw payload and <code>image_size</code> of exactly <code>0xA000</code> (40 KiB), split into exactly forty 1024-byte blocks;</li> <li>a target derived from the installed CRC-valid embedded manifest identity. Deployed XIAO identities keep   raw board IDs <code>0x28860044</code>/<code>0x28860045</code>; generic identities use LE32(SHA-256(canonical padded hw32));</li> <li>signed <code>hw_id</code> exactly <code>XIAO_BL_28860044</code>/<code>XIAO_BL_28860045</code> for deployed XIAO, or the zero-padded   32-byte <code>NRF_BL_&lt;BOARD_ID&gt;_&lt;DEVICE_NAME&gt;</code> for a generic target;</li> <li>a sane nRF52840 vector table, exactly one CRC-valid embedded manifest v1 with the exact board/name pair,   followed by the required CRC-covered <code>BLM2</code>/<code>SOFT</code> continuity extension (embedded boot version,   SoftDevice family/FWID, application base, and layout ABI), with that complete 76-byte envelope at the   canonical final-image offset <code>0x9FB4</code>,   and exactly one <code>MOTABLDR</code> marker advertising ABI &gt;= 3, both application codecs (<code>FULL|INPLACE</code>, mask   <code>0x0005</code>), boot-update continuity, and the exact storage flags for the application layout (<code>0x09</code>   MeshTower V2 SD, <code>0x0E</code> XIAO QSPI, or <code>0x0A</code> shared internal staging).</li> </ul> <p>The incoming embedded identity must exactly match the installed CRC-valid bootloader identity. Both scans consider every aligned structurally valid candidate so magic bytes in a literal pool cannot shadow the real manifest. Duplicate accounting counts each CRC-valid 44-byte base record before interpreting adjacent continuity metadata, so a corrupt or half-present <code>BLM2</code> extension cannot hide a second identity; after exactly one base record is selected, malformed claimed continuity fails closed. A package must be signed by a key already in the device's trusted allowlist; unlike ordinary application packages, there is no unsigned manual-install exception. The signed outer <code>fw_version</code> must equal the embedded boot version. Qualified internal/QSPI targets may bootstrap a CRC-valid legacy-v1 installed bootloader once; MeshTower SD instead requires local BLM2 provisioning because it has no safe legacy media handoff. After bootstrap every remote successor must be strictly newer and match the live SoftDevice/application layout. Low-byte zero and all-ones boot versions are invalid. Remote rollback has no override and must use local DFU/SWD.</p>"},{"location":"ota_protocol/#5-payload-codecs-delta-base","title":"5. Payload, codecs &amp; delta base","text":"<p><code>PAYLOAD</code> is either the full reconstructed image (<code>FULL</code>) or a delta (<code>!FULL</code>).</p> <code>codec_id</code> Meaning Used by 0 full / raw PAYLOAD = reconstructed image (<code>BODY||EndF</code>). ESP32 A/B or an external SD/QSPI nRF52 target. 1 detools sequential random read of base + sequential write of result -&gt; ESP32 A-&gt;B inactive slot. 2 detools in-place bounded scratch; rewrites the app region in place -&gt; nRF52 single-slot. <p>For deltas, <code>base_hash</code> = the base build's <code>EndF.body_hash</code> (sha2-256:8 of its BODY). A node applies a delta only if <code>base_hash</code> matches its own <code>EndF.body_hash</code>. After applying, the result MUST hash (sha2-256:32) to <code>image_hash</code> before it is booted - the hard security gate.</p> <p>A fetcher only requests firmware it can apply. Each node declares the codec(s) it can apply (<code>set_apply_codec</code>/<code>set_apply_codec2</code>): ESP32 accepts <code>full</code> + <code>sequential</code> (+ <code>in-place</code>). Internal-staging nRF52 targets accept only <code>in-place</code> because internal flash cannot hold a second full application image. Matched SD and raw-QSPI nRF52 targets accept <code>full</code> + <code>in-place</code> because external media holds the container. A <code>.mota</code> with an unsupported codec is rejected at discovery time, before any blocks are requested. A manual pull to an external folder may accept other codecs because that path captures bytes and never installs them.</p> <p>Compression is internal to the detools patch and must be supported by the applier. Patches are produced by detools 0.53.0 (<code>tools/mota</code> -&gt; <code>detools.create_patch</code>) and decoded on-device by detools' embeddable C decoder, vendored verbatim at <code>src/helpers/ota/detools/</code> (see its <code>README.meshcore.txt</code>). That build enables only the self-contained <code>NONE</code> + <code>CRLE</code> compressions (no malloc/liblzma/heatshrink), so MeshCore deltas use <code>--compression crle</code>. Do not reimplement the codec - use the vendored decoder.</p>"},{"location":"ota_protocol/#6-merkle-tree-sha2-2564","title":"6. Merkle tree (sha2-256:4)","text":"<p>Verifies each PAYLOAD block against the signed <code>merkle_root</code> before the whole payload exists, so corruption/forgery is localized to a block. Implemented in <code>MerkleTree.cpp</code>.</p> <ul> <li>Blocks: PAYLOAD splits into <code>BC = ceil(payload_size / B)</code> blocks, <code>B = 2^block_size_log2</code> (new   application default 2048; deployed 1024-byte application packages remain valid). The last block is its   real length (no zero padding). Format-3 bootloader packages remain fixed at 1024 bytes.</li> <li>Leaf: <code>leaves[i] = sha2-256:4( block_i_bytes )</code>.</li> <li>Internal node: <code>node = sha2-256:4( left || right )</code> (4+4 input bytes).</li> <li>Odd level: an odd count promotes the last node unchanged to the next level (no duplication).</li> <li>Root: reduce until one node remains. <code>BC == 1</code> -&gt; root = <code>leaves[0]</code>. <code>BC == 0</code> is invalid.</li> </ul>"},{"location":"ota_protocol/#61-proofs","title":"6.1 Proofs","text":"<p>A proof for block <code>i</code> is the ordered list of sibling digests from leaf to root. Promoted levels contribute no element. Verification (needs <code>BC</code> to know the tree shape):</p> <pre><code>h = leaf_i ; idx = i ; n = BC ; p = 0\nwhile n &gt; 1:\n    if (n is odd) and (idx == n-1):        # this node was promoted\n        pass\n    else:\n        sib, side = proof[p] ; p += 1\n        h = sha2-256:4( sib || h ) if side==left else sha2-256:4( h || sib )\n    idx //= 2 ; n = (n + 1) // 2\naccept iff h == merkle_root and p == len(proof)\n</code></pre> <p>Over LoRa, <code>leaves[]</code> are omitted from the manifest transfer. A serving node computes a block's proof on demand from its stored <code>leaves[]</code> and normally sends <code>OTA_PROOF</code> immediately after that block's paced <code>OTA_DATA</code>. <code>OTA_REQ_PROOF</code> remains the fallback for an older source or a lost proactive proof. The fetcher fills its own <code>leaves[i]</code> as each verified block lands.</p>"},{"location":"ota_protocol/#7-block-availability-staging-resume","title":"7. Block availability, staging &amp; resume","text":"<p>There is no separate availability structure. Block <code>i</code> is present &lt;=&gt; <code>leaves[i]</code> is non-erased (<code>!= FF FF FF FF</code>). Because <code>leaves[]</code> live in the staged flash region, availability survives reboot.</p> <p>Commit order per block (crash-safe): (1) verify proof, (2) write block payload to its offset, (3) write <code>leaves[i]</code> last. A power loss before step 3 leaves the slot erased -&gt; the block is simply re-fetched (idempotent). On boot a node rebuilds an in-RAM present-bitmap by scanning <code>leaves[]</code> for a persistent, reopenable store. A hybrid nRF52 transfer is the deliberate exception: its SRAM-backed payload suffix is volatile, so the application refuses to adopt that staged header instead of rebuilding partial progress.</p> <p>Resume (<code>OtaManager::resumeStaged</code> + <code>OtaStore::checkpoint</code>/<code>reopenFor</code>): an interrupted fetch resumes from the staged container after a reboot - re-parse the stored manifest, recompute geometry, count present blocks, continue fetching the holes (or jump straight to COMPLETE). The checkpoint cadence (persist progress every N committed blocks) is runtime-tunable (<code>ota config checkpoint &lt;N&gt;</code>, 0 = only finalized containers resume). Boot-time adoption is an automatic fetch decision: current <code>autofetch</code> must be enabled, the stored target must equal the node target, policy <code>signed</code> requires the signed bit, and an enabled running-version floor requires a strictly newer manifest. An explicit MID pull may deliberately resume an older or unsigned package and keeps target <code>0</code> as a MID-only wildcard. Stores keep <code>leaves[]</code> in RAM until flush and never auto-GC, preserving resumable progress. The debug/operator equivalent is <code>ota dev resume &lt;MID8&gt;</code>; after a reboot the MID is mandatory, while a no-argument form may only reuse a still-active session MID. It never uses the <code>nullptr</code> automatic-adoption path, so a malformed MID or no active MID fails closed. Raw ESP32/nRF52 staging scans every valid header before adoption: address order is not creation order. Explicit resume selects a unique matching MID/target; automatic resume refuses multiple valid headers without erasing them. A leaf-marker read error is never treated as a missing block: reconnectable storage pauses and re-verifies after reconnection, while other storage reports failure and permits an explicit retry. Hybrid nRF52 staging cannot enter this resume path after an application restart, even if its flash prefix still contains metadata; the complete logical container must be fetched again.</p> <p>Flash-store note (RX-safe writes): a flash page-erase halts the CPU (~85 ms on nRF52) and starves LoRa RX, so the flash stores (<code>OtaStoreFlashNrf52</code>/<code>OtaStoreFlashEsp32</code>) coalesce writes to the erase unit (4 KB page / sector) and commit each once off the per-packet path. Ordinary stores keep RAM at O(one page), not O(image); a qualified hybrid nRF52 profile additionally reserves one fixed 64 KiB staging arena. A small delta that fits page 0 does zero flash I/O until COMPLETE.</p>"},{"location":"ota_protocol/#8-lora-ota-protocol","title":"8. LoRa OTA protocol","text":"<p>Carried in MeshCore packets with <code>PAYLOAD_TYPE_OTA = 0x0C</code>. Every OTA packet payload is:</p> <pre><code>[0]    ota_msg_type      (OtaMsgType, OtaFormat.h)\n[1..]  body              (fixed per type; encode/decode in OtaProtocol.cpp)\n</code></pre> <p>Message types:</p> <code>ota_msg_type</code> val routing purpose <code>OTA_ADV</code> 0x01 discovery tiny per-node beacon (discovery tier 1) <code>OTA_QUERY</code> 0x02 discovery ask a source for its catalog (discovery tier 2) <code>OTA_HAVE</code> 0x03 discovery the catalog reply (fragmented, digest-tagged) <code>OTA_GET_MANIFEST</code> 0x04 transfer request a manifest's fragments (<code>want_mask</code>) by <code>manifest_id</code> <code>OTA_MANIFEST</code> 0x05 transfer the manifest-minus-leaves, fragmented <code>OTA_REQ</code> 0x06 transfer request fragments from an adaptive flight of 1-4 blocks (<code>want_mask</code> per block) <code>OTA_DATA</code> 0x07 transfer one self-describing fragment of a block's data <code>OTA_REQ_PROOF</code> 0x08 transfer request/re-request a missing proof <code>OTA_PROOF</code> 0x09 transfer the merkle proof for one block <code>OTA_GET_LEAVES</code> 0x0A transfer request the target's <code>leaves[]</code> fragments (<code>want_mask</code>) - warm-start only <code>OTA_LEAVES</code> 0x0B transfer a fragment of the <code>leaves[]</code> array (for host-side seed leaf-diff) <ul> <li><code>manifest_id</code> = the manifest's <code>merkle_root</code> (4 bytes) - a compact content id present in every   transfer message, so a multi-mota server dispatches each request to the right image.</li> <li>Priority: <code>OTA_ADV</code>, <code>OTA_QUERY</code>, and <code>OTA_HAVE</code> enqueue at background priority 250. Once a fetch is   active, manifest, block request, data, and proof messages enqueue at primary priority 0. Relay-only   nodes classify the wire message identically, so a transfer stays primary across the complete path.</li> <li>Reliability is eventual: the fetcher re-requests only missing fragments after an adaptive deadline   derived from packet airtime, outstanding response packets, duty pacing, and path length. The manager may   still run a one-second maintenance tick, but that tick is not itself a retry timer. No hard ACKs or global   ordering are required.</li> <li>Relay envelope: OTA still uses a bounded flood-shaped mesh header so the same packets can cross the   configured number of hops without first discovering an addressed return path. During TempRadio each node   forwards one copy; active OTA packets do not use the generic flood-retry subsystem. The fetcher verifies   every block against the signed root, and a repeater without <code>ENABLE_OTA</code> can transport   <code>PAYLOAD_TYPE_OTA</code> opaquely without the manager, staging store, installer, or destination bootloader.</li> <li>Hop limit + duty cycle: OTA floods accumulate one path-hash per relay (the mesh's flood routing). A   node with the OTA manager accepts a packet only if it arrived within <code>ota config hops</code> hops (default 3;   <code>0</code> = direct only) and relays it only while still under that limit, appending its own hash. Relay-only   repeaters instead use their ordinary flood limits and forwarding filters. Discovery relays remain   lowest-priority and may be skipped when the packet pool runs low. Active-transfer relays bypass that   background pool gate and use priority 0; operators should therefore treat TempRadio as a dedicated OTA   maintenance window because the transfer can delay unrelated mesh traffic.</li> </ul>"},{"location":"ota_protocol/#81-two-tier-discovery","title":"8.1 Two-tier discovery","text":"<p>Because a node may serve many mOTAs (its own firmware plus an external folder - Section 10), discovery is split so the periodic beacon stays tiny regardless of catalog size:</p> <p>Tier 1 - <code>OTA_ADV</code> beacon (10 bytes, constant). Flooded as a short burst at boot, then every <code>advert_mins</code> minutes (default 24h; runtime-tunable via <code>ota config advert</code>, <code>0</code> disables the periodic re-advertise). It is also emitted immediately whenever the served set changes (e.g. a <code>motatool</code> folder is attached/detached), so peers learn about newly-available firmware without waiting for the next interval:</p> <pre><code>seeder_id[4]    advertiser node id = pubkey[0:4]; the QUERY address + distinct-source id\nn_motas         uint8 - count of complete servable mOTAs (saturates at 255)\nset_digest[4]   sha2-256:4 over the SORTED set of served manifest_ids (see below)\n</code></pre> <p><code>set_digest</code> is a content hash of the offering, not a counter: canonical across nodes, and it changes iff the set of served mids changes. A peer that has already catalogued this <code>{seeder, set_digest}</code> ignores the beacon (steady state is query-free). For a single served mota, <code>set_digest = sha2-256:4(mid)</code>.</p> <p>Tier 2 - <code>OTA_QUERY</code> -&gt; <code>OTA_HAVE</code> (on interest only):</p> <pre><code>OTA_QUERY  (flood):  seeder_id[4]  set_digest[4]  filter_target(uint32) want_fragments(uint32)\n                     # filter_target 0 = everything; want_fragments 0 = every fragment\nOTA_HAVE   (flood):  seeder_id[4]  set_digest[4]  frag_idx(1) frag_total(1) n_rows(1)  rows[]\n  HaveRow (16 bytes, OTA_HAVE_ROW_BYTES): mid[4] target_id(4) fw_version(4) codec_id(1) flags(1) have_count(2)\n</code></pre> <p><code>have_count</code> is the number of blocks the source holds (<code>== block_count</code> for a complete offered image). Receivers do not advertise partial or completed downloads as new sources.</p> <p>A node interested in a source's offering schedules a QUERY; the source replies with its full catalog as <code>OTA_HAVE</code> rows (fragmented if they exceed one packet - 10 rows per fragment). A receiver marks the catalog complete only after all <code>frag_total</code> fragments arrive. If any are missing after the recovery timeout, it sends another QUERY whose <code>want_fragments</code> bitmap names only the holes. <code>want_fragments</code> is an append-only extension: an original 13-byte QUERY is still accepted and means \"send every fragment.\" The heavy manifest is fetched per-mid only on commit (Section 8.3).</p> <p>Fragment numbers are canonical pages of the complete catalog sorted by <code>manifest_id</code>. <code>filter_target</code> may remove rows from a requested page (and can therefore produce an empty fragment), but it never renumbers pages or changes <code>frag_total</code>. Receivers derive the unfiltered page count and each page's row count from the source's advertised <code>n_motas</code>. A page counts as received only if both counts match that complete geometry; filtered rows are still cached, but omitted rows leave the page eligible for an unfiltered recovery query. This also prevents legacy filtered replies which renumber pages from completing an unfiltered catalog.</p>"},{"location":"ota_protocol/#82-anti-storm-mandatory-at-mesh-scale","title":"8.2 Anti-storm (mandatory at mesh scale)","text":"<p>If 50 neighbours all queried a new beacon at once, the mesh would collapse. Mitigations (gossip/mDNS pattern), all in <code>OtaManager</code>:</p> <ul> <li><code>OTA_HAVE</code> is flooded and digest-tagged. EVERY node that overhears it caches the rows passively   (keyed by <code>{seeder, set_digest}</code>) - no query of its own needed.</li> <li>Jittered query: a peer needing a catalog schedules its <code>OTA_QUERY</code> after a random delay   <code>OTA_QUERY_MIN_MS (300) + rand(OTA_QUERY_SPREAD_MS (4000))</code>, derived from <code>id +/ digest +/ self</code>.</li> <li>Overhear suppression: during the jitter window, overhearing another QUERY that covers the same scope,   or completing the HAVE fragment set for the same <code>{seeder, set_digest}</code>, cancels the pending query.</li> <li>Per-source recovery: each seeder has independent query/retry state. One source cannot overwrite another   source's timer, and a partial reply requests only missing fragments after 15 seconds (five bounded retries,   then another source ADV or explicit <code>ota ls</code> can start a fresh series).</li> </ul> <p>Net effect: a digest change costs ~1 query + ~1 HAVE flood mesh-wide; a stable mesh is query-free.</p>"},{"location":"ota_protocol/#83-fetch-handshake","title":"8.3 Fetch handshake","text":"<pre><code>fetcher                                   server (any node that has the mid)\n  OTA_GET_MANIFEST(mid, want_mask)  &gt;     (want_mask=0xFFFF first; only missing fragments on retry)\n                               &lt;-------   OTA_MANIFEST(mid, frag_idx, frag_total, bytes)   x requested frags\n  (reassemble manifest, verify, compute geometry: BC, block_size, payload_size)\n  for each adaptive flight of missing blocks (starts at 1, grows on clean flights):\n    OTA_REQ(mid, {block_idx, want_mask}[]) &gt;  (one packet; all fragments first, only holes on recovery)\n                               &lt;-------   OTA_DATA(mid, block_idx, frag_off, data) x requested frags/block\n                               &lt;-------   OTA_PROOF(mid, block_idx, n_proof, proof) x requested blocks\n    (independently reassemble + verify each block, but remain RX-silent until the flight drains)\n    [after adaptive deadline: recover one block's holes, or OTA_REQ_PROOF for a missing proof]\n    (clean flight grows by one block; recovered flight halves the next width)\n  when all blocks present: verify full merkle_root + image_hash -&gt; COMPLETE\n</code></pre> <p>Before allocating or writing the selected store, the receiver parses the reassembled manifest and requires its <code>merkle_root</code> to equal the requested/wire <code>manifest_id</code> and its <code>target_id</code> to equal the catalog or explicit-pull target that opened the receive slot. The wire envelope and HAVE row are advisory; they cannot label and stage a different manifest.</p>"},{"location":"ota_protocol/#84-message-bodies-transfer","title":"8.4 Message bodies (transfer)","text":"<p>All offsets after the 1-byte type. Encoders/decoders in <code>OtaProtocol.cpp</code>; constants in <code>OtaManager.h</code>.</p> <pre><code>OTA_GET_MANIFEST:  manifest_id[4]  want_mask(uint16)   # bit k = send manifest fragment k; 0xFFFF = all\nOTA_MANIFEST:      manifest_id[4]  frag_idx(1)  frag_total(1)  bytes[]     # up to OTA_MF_FRAG=176 B/frag\nOTA_REQ:           manifest_id[4]  { block_idx(uint16)  want_mask(uint16) }[1..4]\n                   # legacy: bit k requests its 160-byte fragment\n                   # v2: bit15=marker, bit14=allow transport DEFLATE,\n                   #     bit13=2 KiB descriptor, bits0..12=fragment bitmap;\n                   #     bit12 must be zero when bit13 is set (0xFFFF stays legacy)\nOTA_DATA legacy:   manifest_id[4]  block_idx(uint16)  frag_off(uint16)  data[&lt;=160]\nOTA_DATA v2:       manifest_id[4]  block_idx(uint16)  descriptor(uint16)\n                   stream_id[4]  data[&lt;=171]\n                   # deployed 1 KiB descriptor: bit15=marker, bit14=DEFLATE,\n                   #   bits13..10=fragment, bits9..0=complete encoded length minus one\n                   # negotiated 2 KiB descriptor: bit15=marker, bits14..11=fragment,\n                   #   bits10..0=complete encoded length minus one; DEFLATE iff that\n                   #   length is strictly less than the manifest-derived raw block length\nOTA_REQ_PROOF:     manifest_id[4]  block_idx(uint16)\nOTA_PROOF:         manifest_id[4]  block_idx(uint16)  n_proof(1)  proof[]   # n_proof x 4 bytes\nOTA_GET_LEAVES:    manifest_id[4]  want_mask(uint16)   # bit k = send leaves fragment k; 0xFFFF = all\nOTA_LEAVES:        manifest_id[4]  frag_idx(1)  frag_total(1)  bytes[]      # up to OTA_LEAVES_FRAG=176 leaf bytes\n</code></pre> <ul> <li> <p>Warm-start / leaf-diff (<code>OTA_GET_LEAVES</code>/<code>OTA_LEAVES</code>) - motatool folder-capture only. Capturing a   device's firmware into a <code>motatool serve</code> folder is slow (a full image is hundreds of blocks). Because   builds here are non-deterministic, you cannot reproduce the exact target on the host - but a similar   build (e.g. a fresh recompile) is ~99% identical. So <code>motatool serve --seed &lt;similar.mota&gt;</code> stages that   build's payload into the destination <code>.part</code>, and <code>ota pull &lt;mid8&gt; folder validate</code> makes the fetcher (1) bulk-   fetch the target's <code>leaves[]</code> via <code>OTA_GET_LEAVES</code>/<code>OTA_LEAVES</code> (bitmap-fragmented with a <code>want_mask</code>, same   anti-burst rule as <code>OTA_MANIFEST</code>), (2) recompute the merkle root from them and check it equals the   manifest root (authenticate), then (3) keep every seeded block whose leaf matches and pull full <code>OTA_DATA</code>   only for the blocks that differ. The <code>want_mask</code> is a fixed uint16, so <code>leaves[]</code> is capped at   <code>OTA_LEAVES_MAXFRAG=16</code> fragments (<code>OTA_DIFF_MAX_BLOCKS=704</code> blocks); larger images just fall back to a full   fetch. Normal P2P nodes never use this - they target only the blocks they want; the only always-on part   is answering <code>OTA_GET_LEAVES</code> with leaves the node already holds, so any node's firmware can be captured.</p> </li> <li> <p>Negotiated 171-byte fragments: the deployed profile remains unchanged: <code>frag_off</code> is a byte offset and   <code>data[]</code> carries at most 160 bytes. A new fetcher marks an <code>OTA_REQ</code> row as v2. For a deployed 1 KiB block,   its first request also includes every fragment bit needed by the legacy representation, so an old source can   answer it completely. The extended 2 KiB profile reserves bit 12 as zero; this both fits its twelve v2   fragments and ensures the deployed <code>0xFFFF</code> legacy all-fragments request is never misclassified. Receipt of   untagged <code>OTA_DATA</code> switches the fetch session to the old geometry. If no v2 data appears by the first   adaptive deadline, the fetcher retries with an ordinary legacy mask. New sources answer v2 with a packed descriptor, a repeated 4-byte representation   ID, and exactly 171 data bytes except the final fragment. A raw 1 KiB block falls from seven data packets to   six; a raw 2 KiB block falls from thirteen to twelve. Message type IDs do not change, so multi-hop relays   continue to forward request/data/proof packets opaquely with the same priority.</p> </li> <li>Transport-only DEFLATE: a fetcher sets the v2 DEFLATE-permission bit only when its application includes   and configures the decoder. A source may encode each logical block as an independent raw RFC 1951 stream   with full stored, fixed-Huffman, and dynamic-Huffman support (<code>BTYPE=0/1/2</code>). Compression is used only when   strictly smaller, otherwise the source returns raw v2 data. The   receiver inflates to the manifest-derived block length, then performs the unchanged Merkle proof and writes   the original bytes to staging. Thus staging and bootloader apply remain uncompressed. Deployed 1 KiB   <code>.mota</code> containers remain compatible; new 2 KiB containers require a receiver advertising the extended   descriptor. Format-3 bootloader packages retain their strict 1 KiB geometry. The 4-byte <code>stream_id</code> is   SHA-256:4 of the complete raw or compressed   representation and appears in every fragment. A receiver locks <code>{encoding, encoded length, stream_id}</code> for   a block, preventing fragments from independently encoded seeders from being mixed. After one sparse retry,   a second stalled interval clears the full in-flight window and switches the session to legacy geometry, so   a vanished v2 seeder cannot prevent an older source from taking over; proof verification remains unchanged.   Every <code>ENABLE_OTA</code> MeshCore application registers the vendored tinf 1.2.1 full raw decoder; its wrapper   bounds output to the exact logical block length and rejects truncation, malformed streams, and trailing   whole bytes. Builds without OTA do not link the decoder. This application capability is independent of the   bootloader because transport data is inflated before the unchanged staged container is written.</li> <li>Adaptive flight size is not signed block size. Each slot holds one manifest-defined block: 1 KiB for   deployed application containers or 2 KiB for new ones. A clean link changes how many complete blocks one   <code>OTA_REQ</code> names: 1, then 2, then 3, then the compiled cap. It never changes block geometry. Two KiB halves   the leaf, block-request, and proof count for a payload while giving each independent DEFLATE stream a larger   history window.</li> <li>Append-only request-window compatibility: the first four-byte request row is exactly the original   <code>block_idx + want_mask</code> body. Old sources decode that row and ignore appended bytes. New sources queue all   rows. If a new fetcher meets an old source, the unserved tail rows eventually time out and are recovered as   ordinary single-row requests; the dirty flight then contracts. Old fetchers continue sending nine-byte   single-row requests, which new sources accept normally.</li> <li>Fragment-level requests (anti-deadlock + anti-congestion): <code>OTA_REQ</code>, <code>OTA_GET_MANIFEST</code>, and <code>OTA_QUERY</code>   carry fragment masks. For catalog discovery, <code>want_fragments</code> is a 32-bit bitmap and covers the protocol   maximum 255-row catalog (26 fragments at the current packet size). For block and manifest transfer, the   <code>want_mask</code> is 16 bits. A fetcher requests the full set on the first ask   (<code>(1&lt;&lt;nf)-1</code>, or <code>0xFFFF</code> before <code>frag_total</code> is known) and only the still-missing bits on any retry,   so recovering one lost fragment re-sends one fragment, not the whole block/manifest. This is essential on   half-duplex radios: re-requesting a whole multi-fragment burst let the periodic retry (a transmit) collide   with the tail of the in-flight burst and drop the same fragment forever - a hang. Requesting only the hole   removes the burst, so there is nothing to collide with. The block/manifest mask matches the 16-bit   reassembly bitmap (&lt;=16 fragments/block; 1 KiB is 7 legacy or 6 raw-v2 fragments; 2 KiB is 13 legacy or 12   raw-v2 fragments). <code>OTA_PROOF</code> is a single packet and needs no mask.</li> <li>Data and proof remain separate packets, without a normal extra round trip. A server retains requested   blocks in a bounded descriptor queue, admits at most one response per main-loop pass, and sends one   <code>OTA_PROOF</code> after each block's requested fragments. Before admitting that proactive proof, the source leaves   an airtime/duty-aware 100-3000 ms RX turnaround gap. It accounts for one active transmission plus the two   paced-response queue credits. A legacy receiver uses the gap to send its immediate   <code>OTA_REQ_PROOF</code>; receiving that explicit request bypasses the remaining gap, avoiding a proof/request   collision and an otherwise multi-second legacy retry. A newer receiver uses an airtime/path-aware proof   grace (never less than 500 ms) and defers <code>OTA_REQ_PROOF</code> while any flight slot still expects DATA. Thus a   missing early proof cannot make the receiver transmit into the rest of a legitimate half-duplex response   train. After the complete-flight deadline, only one slot's missing fragments/proof is requested at a time.</li> </ul>"},{"location":"ota_protocol/#85-sizing-against-max_packet_payload-184","title":"8.5 Sizing against <code>MAX_PACKET_PAYLOAD = 184</code>","text":"message fixed overhead payload/packet <code>OTA_DATA</code> legacy 9 B (type+mid4+idx2+off2) <code>OTA_FRAG_DATA = 160</code> -&gt; 7 raw frags/1 KiB or 13/2 KiB <code>OTA_DATA</code> v2 13 B (legacy header + stream ID) <code>OTA_FRAG_DATA_V2 = 171</code> -&gt; 6 raw frags/1 KiB or 12/2 KiB; fewer when compressed <code>OTA_MANIFEST</code> 7 B <code>OTA_MF_FRAG = 176</code> -&gt; signed manifest ~ 2 frags <code>OTA_HAVE</code> 12 B 10 rows x 16 B per fragment <code>OTA_PROOF</code> 8 B up to ~44 sibling digests (&gt;&gt; any real tree) <p>A served mota supports up to 1024 leaves in the default 4 KiB proof scratch (about 2 MiB of payload at the new 2 KiB default, or 1 MiB for a deployed 1 KiB container); larger self-images pass a bigger scratch buffer.</p>"},{"location":"ota_protocol/#86-temporary-radio-and-transfer-boundary","title":"8.6 Temporary-radio and transfer boundary","text":"<p>OTA packets may cross normal mesh relay hops, but each participating node processes or relays them only while its <code>tempradio</code> window is actually running. A receiver selects missing blocks in serial order into a bounded request flight. Every session starts with one block. A clean completed flight increases the next request by one block; a flight requiring fragment/proof recovery halves the next width (<code>4 -&gt; 2</code>, <code>3 -&gt; 2</code>, <code>2 -&gt; 1</code>). The default compiled cap is two blocks; the RAK3401 LoRa-OTA target caps at four, so it probes <code>1 -&gt; 2 -&gt; 3 -&gt; 4</code>. All rows are sent in one backward-compatible <code>OTA_REQ</code>, and no freed slot is refilled until the current flight is finished. It never serves partial blocks. A normal install receiver never re-advertises its completed download. An SD archive node is the deliberate exception: after a fully proof-verified container is published to its persistent archive, it registers that complete file as a MotaSource and advertises it as a new seeder. This keeps each active transfer as one transmitter and one receiver while still allowing active temporary-radio repeaters between them and persistent archive nodes to improve future availability.</p> <p>TempRadio is treated as a private maintenance network. Active transfer packets use priority 0, bypass the public-flood receive holdoff, use the full transmit budget without overwriting the saved normal-radio airtime factor, retain the relay role's airtime-scaled transmit collision window, and do not schedule generic flood retries. Deployed firmware predating that TempRadio budget override can be accelerated manually with a saved <code>get af</code> / temporary <code>set af 0</code> / restore sequence. The bounded serving queue admits at most two DATA/PROOF packets ahead of the radio while preserving at least four free packet-pool entries. CAD remains enabled to arbitrate the half-duplex channel, but its busy retry is scaled to one-quarter of a packet airtime and clamped to 5-50 ms instead of the ordinary 120-360 ms cadence. Discovery traffic keeps collision jitter and background priority. The fetch deadline uses the active radio's measured maximum-packet airtime, remaining DATA/PROOF packet count, dispatcher airtime factor, and longest observed path (falling back to the configured hop horizon before one is observed), with bounded guard time. Faster SF/BW settings therefore recover loss sooner; slower or multi-hop settings do not spuriously re-request a response still on air. These changes remove software waits and duplicate bursts; they do not remove the one required forwarding transmission per hop.</p>"},{"location":"ota_protocol/#9-identity-trust-versioning","title":"9. Identity, trust &amp; versioning","text":"<ul> <li><code>target_id</code> (4 B): <code>sha2-256:4(pio_env_name)</code> (little-endian uint32). The env name uniquely captures   hardware and role/partition, so a node auto-fetches only matching firmware (a companion image is not   fetched onto a repeater even though it shares <code>hw_id</code>). It is self-described in the firmware's EndF   (Section 2, written by <code>pio_endf.py</code>) and read via <code>ota_self_firmware()</code>, so it is correct on any build;   <code>-D MOTA_TARGET_ID</code> / <code>MainBoard::getOtaTargetId()</code> is the fallback when no EndF identity is present.   <code>tools/mota</code> reads it from the firmware's EndF (or <code>--target-env</code>). A manual <code>ota pull</code>/<code>want</code> can override   target (deliberate role switch); the <code>hw_id</code> brick-safety gate (Section 4) still applies at apply time.</li> <li><code>target_id</code> vs <code>hw_id</code> - complementary, not redundant: <code>target_id</code> is the fetch-routing key   (hw + role + partition); <code>hw_id</code> is the human-readable brick-safety key (hardware only). Same board, two   roles =&gt; same <code>hw_id</code>, different <code>target_id</code>.</li> <li>One-way target migration: a release may compile <code>MOTA_MIGRATION_TARGET_ID</code> into a legacy image. While   that image is running, automatic fetch accepts only the declared successor target; manual pulls remain   unchanged. The staged manifest must still match the requested successor target, the signed <code>hw_id</code>, image   hash, codec, and partition/layout checks. After reboot the successor's EndF becomes the node's normal   identity, so later updates use the canonical target. The migration alias is not used for bootloader packages.</li> <li>Naming a <code>target_id</code> locally: only the 4-byte <code>target_id</code> ever travels on the wire. To show which   board/role a target is, a node (and <code>motatool</code>) reverse-looks-it-up in <code>src/helpers/ota/OtaTargets.h</code> -   a generated <code>target_id -&gt; env-name</code> table covering every <code>ENABLE_OTA</code> env (<code>tools/mota/gen_targets.py</code>,   resolved from <code>pio project config</code>). So <code>ota ls</code> can render <code>[Heltec_v3_repeater]</code> for a neighbour's   beacon without the string being transmitted. Unknown IDs show as raw <code>hw XXXXXXXX</code> / <code>N/A</code> values.</li> <li><code>fw_version</code>: packed comparable uint32 (<code>MAJOR&lt;&lt;24 | MINOR&lt;&lt;16 | PATCH&lt;&lt;8 | pre</code>); also self-described   in EndF. <code>ota ls</code> prints the stable eight-hex manifest ID and uses <code>[same target]</code>, <code>[unsupported]</code>, or   <code>[rescue]</code> after combining target equality with the local codec, bootloader, and EndF preflight. A known   different target is rendered by environment name; an unknown/unset target remains raw or <code>?</code>. Target   equality is routing information, not by itself an assertion that an image is safe to install.</li> <li><code>hw_id</code>: 32-byte NUL-padded ASCII hardware tag inside the signed head. The applier refuses a <code>.mota</code>   whose <code>hw_id</code> differs from the device's own tag (empty on either side = permissive). Brick-safety   independent of signature.</li> <li>Signing &amp; allowlist: a node keeps a runtime allowlist of trusted Ed25519 signer pubkeys (none embedded   in firmware; <code>ota key add/list/rm</code>). A <code>.mota</code> is eligible for auto-install only if signed by an   allowlisted key, the signature verifies, <code>image_hash</code> matches, and its nonzero signed <code>fw_version</code> is   strictly greater than the running hash-valid EndF version. Both catalog admission and final automatic   apply enforce the version floor, so a lying HAVE row cannot bypass it. Manual <code>ota install</code> is the explicit   equal-version/rollback override and generally permits unsigned packages,   but a package that claims to be signed must have a valid signature from an allowlisted key or it is rejected.   The removable-SD target is stricter: every application install needs a valid allowlisted signature because   the app mints an authenticated one-reset media authorization for OTAFIX.   Transfer needs no trust - blocks are content-addressed against the manifest's merkle root.</li> <li>Policies (persisted): <code>autofetch</code> in {off, any, signed} (default off) gates automatic block fetching of   own-target (or an explicitly compiled one-way successor) adverts; <code>autoinstall</code> in {off, trusted} (default off) gates auto-apply of a COMPLETE signed +   allowlisted fetch. Conservative defaults: a fresh node discovers + announces but never fetches/installs   without operator intent.</li> <li>Supersession: a newer version announced mid-download does not abort the in-progress transfer   (finish-current).</li> </ul>"},{"location":"ota_protocol/#10-multi-mota-serve-the-external-folder-relay","title":"10. Multi-mota serve &amp; the external \"folder\" relay","text":"<p>A node serves a set of mOTAs: its own firmware plus, optionally, an external folder of <code>.mota</code> files it relays without holding them in flash. To peers it simply \"has N mOTAs\"; the relay is trustless (fetchers verify everything). The serve side (<code>OtaManager</code>) keeps a lightweight registry of what it advertises and two resident \"views\": <code>view0</code> (its own firmware) and one on-demand view loaded from a source when a request targets an external mota. Every fetch message carries <code>manifest_id</code>, so dispatch is a registry lookup.</p> <p>The USB/TCP host-folder link can also be a pull destination (the reverse direction): <code>ota pull &lt;mid8&gt; folder</code> fetches a <code>.mota</code> off the mesh and streams it onto the host as <code>&lt;mid&gt;.mota</code> via the seeder STORAGE ops (<code>OP_STAT/BEGIN/WRITE/SREAD/FIN</code>, see <code>MotaSeederProto.h</code>), using a <code>FolderMotaStore</code> as the fetch's <code>OtaStore</code> instead of RAM/flash. This captures an exact copy of a device's firmware - e.g. to build a delta against firmware you don't have. Resume is bookkeeping-free: <code>BEGIN</code> 0xFF-fills the file and, on reconnect after a link drop (the fetch PAUSES, holding progress on the host - no RAM/flash fallback), <code>STAT</code>+<code>SREAD</code> let the fetcher recompute and refill only the missing blocks. TCP disconnect preserves the selected MID, target, and destination across dynamic-context idle cleanup. Metadata initialization or seed leaf-diff restarts from the manifest on reconnect; an initialized transfer reopens and rehashes the same MID before requesting missing blocks. Host I/O failure during final verification or publication pauses too; a genuine Merkle mismatch remains a failed transfer. Explicit cancel/detach still releases the session, and a different host transport cannot take over a paused capture without cancellation. The phone-oriented BLE link is deliberately source-only and does not register a folder destination.</p>"},{"location":"ota_protocol/#101-the-motasource-abstraction-otasourceh","title":"10.1 The <code>MotaSource</code> abstraction (<code>OtaSource.h</code>)","text":"<p>Transport-agnostic provider of one or more complete <code>.mota</code> as random-access bytes. The same serve code drives USB-serial, BLE, a WiFi URL list, an NFS/samba mount, etc. - only <code>read()</code> differs.</p> <pre><code>struct MotaDesc {                      // catalog metadata + region offsets (no whole image in RAM)\n  uint8_t mid[4]; uint32_t target_id, fw_version; uint8_t codec_id, flags;\n  uint8_t block_size_log2, source_caps;\n  uint32_t total_size, leaves_off, block_count, payload_off, payload_size;\n};\nclass MotaSource {\n  virtual uint8_t count();                                  // # mOTAs offered\n  virtual bool    describe(uint8_t idx, MotaDesc&amp; out);     // metadata + offsets\n  virtual bool    read(uint8_t idx, uint32_t off, uint8_t* buf, uint32_t len);   // random-access bytes\n  virtual bool    read_deflated_block(uint8_t idx, uint16_t block,\n                                      uint8_t* buf, uint16_t cap, uint16_t* len); // optional raw RFC 1951\n};\n</code></pre> <p>To serve an external mota the node reads its manifest-minus-leaves + <code>leaves[]</code> into RAM (&lt;=4 KiB for &lt;=1024 blocks) and streams payload blocks from the source on demand; proofs are generated from the read leaves.</p>"},{"location":"ota_protocol/#102-the-mota-seeder-transport-motaseederprotoh","title":"10.2 The <code>mota-seeder</code> transport (<code>MotaSeederProto.h</code>)","text":"<p>A <code>MotaSource</code> is fed by a host that serves a folder over the device's USB serial (the same console the CLI uses - no extra hardware), on an ESP32 WiFi companion or FULL ESP32 role over WiFi (TCP), or on an nRF52 Full Companion over an encrypted BLE GATT service. The host is the standalone Rust tool <code>motatool</code> (<code>motatool serve --serial &lt;port&gt;</code> / <code>--tcp &lt;host[:port]&gt;</code>, which also builds + verifies + inspects <code>.mota</code>). The device only emits request frames while actively serving a fetch, and reads the reply synchronously, so over the shared USB console binary frames coexist with the text CLI/logs (resync on magic + checksum). Little-endian, XOR-checksummed:</p> <pre><code>request  (device -&gt; host):  'M' 'S'  op(1)  args...                 xsum(1 = XOR of op+args)\nresponse (host -&gt; device):  'm' 's'  op(1)  status(1)  payload...    xsum(1 = XOR of all prior)\n\nOP_COUNT     0x01   args: -            -&gt; payload: count(1)\nOP_DESCRIBE  0x02   args: idx(1)       -&gt; payload: MotaDesc wire (38 B)\nOP_READ      0x03   args: idx(1) off(4) len(2)  -&gt; payload: len bytes\nOP_DEFLATE_BLOCK 0x09 args: idx(1) block(2) off(2) len(2)\n                         -&gt; payload: total_encoded_len(2) + requested bytes\nMotaDesc wire (38 B): mid[4] target_id(4) fw_version(4) codec(1) flags(1)\n                      total_size(4) leaves_off(4) block_count(4) payload_off(4) payload_size(4)\n                      block_size_log2(1) source_caps(1) reserved(2)\nstatus: 0 = OK, non-zero = error (out of range / past EOF).\n</code></pre> <p><code>SerialMotaSource</code> splits logical reads into replies of at most 192 payload bytes. A manifest's leaf table can exceed 256 bytes and new payload blocks are normally 2 KiB; requesting either in one transaction can overrun common USB CDC/UART receive rings even though the host successfully wrote the complete reply. Chunking is internal to the transport and does not change <code>OP_READ</code> or the <code>MotaSource</code> random-access contract.</p> <p><code>OP_DEFLATE_BLOCK</code> lets a host-folder source perform the optional transport compression without linking an encoder into the embedded seeder. <code>len=0, off=0</code> queries the exact encoded length; subsequent chunks are at most 190 bytes, keeping the total response payload at 192 bytes. The host independently encodes each manifest payload block as ordinary raw RFC 1951 at level 9. It returns an error for an invalid range, an unsupported operation, or a result that is not smaller than the raw block; <code>SerialMotaSource</code> then serves the ordinary raw v2 representation. A supporting host sets <code>source_caps bit 0</code> in every descriptor. Older hosts leave that formerly-reserved byte zero, so upgraded firmware skips the optional request instead of waiting for an old daemon that silently ignores unknown operations.</p> <p>Manifest fragments are retained as bounded response jobs and admitted one at a time. Their source-side gap follows the active maximum packet airtime and dispatcher duty spacing, clamped to 100-1000 ms. The 100 ms floor protects fast radios' TX-to-RX turnaround; the cap keeps the receiver's one-second manifest progress/retry observation responsive. The source uses the same radio-aware 100-3000 ms drain/turnaround gap before an unsolicited block proof, but immediately serves a legacy receiver's explicit <code>OTA_REQ_PROOF</code>. Relay collision delay is a separate setting: active OTA floods honor the relay role's configured <code>txdelay</code>, and the deployment runner temporarily uses <code>0.3</code> on managed relays.</p> <p>What to plug into <code>--serial</code>. Use the USB serial console of an OTA-enabled MeshCore node built with <code>OTA_FOLDER_SERIAL</code>. The node must have a working LoRa radio plus an <code>ota folder on</code> command; that command confirms it can host and advertise the folder. A KISS modem will not work: KISS firmware exposes a TNC/KISS frame interface, not the MeshCore CLI and <code>mota-seeder</code> request/response transport. An ESP32 WiFi companion or FULL ESP32 role with active WiFi is the alternative source connection: use its dedicated seeder port with <code>motatool serve --tcp &lt;host&gt;:5001</code>. An nRF52 Full Companion can instead pair with a phone or Linux host, subscribe to its mOTA request characteristic, and use protocol-v14 <code>CMD_BLE_MOTA_SOURCE</code>. That BLE path is source-only; it does not expose the reverse <code>FolderMotaStore</code> capture operations.</p> <p>Device CLI: <code>ota folder on</code> (attach + announce), <code>ota folder</code> (list), <code>ota folder off</code>. Build flag <code>OTA_FOLDER_SERIAL</code> (default stream = console <code>Serial</code>; override <code>OTA_FOLDER_SERIAL_STREAM</code> + define <code>OTA_FOLDER_SERIAL_BEGIN</code> for a dedicated UART). ESP32 WiFi companions and FULL ESP32 roles run a <code>WiFiServer</code> on the dedicated seeder port (<code>OTA_SEEDER_TCP_PORT</code>, default <code>5001</code>) while WiFi is usable. On a companion it is separate from the app port (<code>TCP_PORT</code>, default <code>5000</code>); on infrastructure roles it is separate from WebConfig and browser OTA on port 80. The node auto-attaches the source when a seeder client connects and detaches when it closes (no <code>ota folder on</code> needed over TCP). An already-active serial folder causes a TCP client to be rejected instead of silently replacing it. Verified on hardware: a RAK4631 relays a host folder to a Heltec V3 over one USB cable, and a host feeds a Heltec V3 over WiFi (<code>:5001</code>) while the companion serves a phone on <code>:5000</code> - every block merkle-checked.</p> <p>The attach reply and bare <code>ota folder</code> report <code>host=advertised/offered</code>. The registry is RAM-bounded (<code>OTA_MAX_SERVE</code>, with the node's own firmware consuming one slot), so a host may correctly index more valid files than this particular firmware can advertise. Omitted entries are now reported instead of silently disappearing. Operators should split a large chain or use a higher-capacity/SD seeder when the two counts differ.</p> <p>Transport-agnostic by design. The request/response semantics (<code>COUNT</code> / <code>DESCRIBE(idx)</code> / <code>READ(idx, off, len)</code> over a folder catalog) are independent of the link. The 2-byte magic + XOR checksum + resync framing above exists for the shared USB-UART (an unframed byte stream); it is harmless over a reliable stream and the WiFi (TCP) transport reuses it as-is - both ends just treat the socket as a byte stream (on-device, <code>SerialMotaSource</code> runs verbatim over an Arduino <code>Stream</code>-compatible <code>WiFiClient</code>; <code>motatool</code>'s <code>TcpTransport</code> mirrors its <code>SerialTransport</code>). The nRF52 Full Companion's BLE GATT path also reuses the exact frame and checksum. Device requests are notifications on a dedicated characteristic and host responses are ordered write-with-response fragments on a second characteristic. Keeping the same framing makes retries and corruption handling identical across USB, TCP, and GATT. The Linux reference implementation is <code>tools/ble_mota/ble_mota_seeder.py</code>; a phone app can implement the same transport-free catalog operations.</p>"},{"location":"ota_protocol/#11-cli-surface-otaclicpp","title":"11. CLI surface (<code>OtaCli.cpp</code>)","text":"<p>User-facing OTA data should travel via <code>CMD_OTA_*</code> companion binary frames; the text CLI below is debug/operator oriented and replies are <code>snprintf</code>-bounded into a 160-byte buffer.</p> <p>Commands take intuitive aliases (matched by the first word; see <code>is_cmd</code> in <code>OtaCli.cpp</code>) so they're easy to type and read - <code>status</code>/<code>neighbors</code>/<code>pull</code>/<code>drop</code>/<code>applydelta</code> are the canonical names, the aliases are the recommended user-facing forms. Output is plain-language (a user-facing guide lives at ota_user_guide.md).</p> <pre><code>ota help | ? | h                   list the commands\nota status | st  (or bare `ota`)   plain-language: running fw, the one fetch session (state/%/id), serving, keys\nota ls | neighbors | nbrs | updates | n [page]   paged updates (queries sources; rows arrive async via OTA_HAVE)\nota get | pull | download &lt;mid8|#index&gt; flash [rescue] | folder [validate]\n                                      fetch by stable mid8 (preferred) or current page index\nota install | apply | applydelta   verify + approve + (ESP32) apply / (nRF52) reboot-to-bootloader\nota rescue install &lt;base_hash16&gt;  internal-flash nRF52 only: recover from failed app-side EndF validation\nota bootloader [status]           capable allowlisted nRF52 repeater: installed BL identity/caps + staged confirmation\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n                                      explicitly verify/arm one complete trusted v3 package; never automatic\nota cancel | drop | stop           drop the fetch; durably invalidate device staging, or retain a folder partial for resume\nota announce | adv                 serve self + send a beacon now\nota self | id                      print this firmware's EndF (body/image size, base_hash)\nota qspi | storage                 QSPI nRF52 only: JEDEC/SR1/stage/latched storage error (read-only)\nota folder | fold [on|off]         attach/detach an external .mota folder (host daemon) ; bare = list\nota config | cfg | set [autofetch|autoinstall|checkpoint] ...   show/set persisted policy\nota key | keys [add|rm &lt;hex&gt;]      trusted signer allowlist ; bare = list\nota dev ...                        bring-up helpers (stage/recv/serve/resume &lt;MID8&gt;/verify)\n</code></pre> <p>For a device-backed pull, current firmware returns success only after the persistent store can no longer be reopened; flash/SD/QSPI I/O or readback failure is reported as an error even though the in-memory manager session was dropped. For a <code>folder</code> pull, cancellation detaches the live transfer but deliberately leaves the host <code>.part</code> file available for a later resume. If the shared receive engine is currently performing the MeshTower SD auto-archive capture, cancellation likewise detaches that archive transfer and retains its <code>.part</code> file; it does not erase the unrelated manual-install store.</p> <p></p>"},{"location":"ota_protocol/#12-apply-bootloader-contract","title":"12. Apply &amp; bootloader contract","text":"<ul> <li>ESP32 (A/B): applied in-firmware via the detools decoder into the inactive OTA slot   (<code>OtaApply.cpp::ota_apply_detools_mota</code> + <code>OtaStoreFlashEsp32</code>), then set-boot + reboot (power-safe,   rollback-capable). No bootloader changes. Erase ranges must be sector-aligned (4096).</li> <li>nRF52 (single-slot): the running firmware never flashes the app. <code>ota install</code> verifies the   container fully (<code>image_hash</code>, codec, signature/allowlist, <code>hw_id</code>, and <code>base_hash</code> for a delta), writes   <code>approval = \"APRV\"</code>, then reboots into the modified bootloader   (<code>Adafruit_nRF52_Bootloader_OTAFIX</code>). The bootloader:</li> <li>locates the staged <code>.mota</code> in the approved internal, raw-SD, or raw-QSPI store without trusting an      unchecked stored size,</li> <li>re-checks <code>TRAILER</code>, <code>image_hash</code>, and <code>approval == \"APRV\"</code>; for a delta it also checks that      <code>base_hash</code> equals the running firmware's <code>EndF.body_hash</code> (recomputed by scanning for <code>EndF</code> - never      trust <code>bank_0_size</code>),</li> <li>writes a full external-media payload or applies the in-place codec over the app region, then boots only      if the result hashes to <code>image_hash</code>.</li> <li>nRF52 internal staging ceiling: an internal-store application derives the ceiling from facts available   in every build, not a board-name list. A companion that actually links the internal ExtraFS datastore stays   below <code>0xD4000</code>; a default linker region or a role that does not mount ExtraFS can reclaim the unused   100 KiB through <code>0xED000</code>. A qualified internal bootloader-self-update target keeps that normal flash   ceiling and does not reserve a second boot-package or flash-scratch region, but it uses a dedicated   application linker that reserves the top 64 KiB of SRAM (<code>0x20030000..0x20040000</code>) plus a 72-byte   retained authorization record after the existing persistent clock bytes. Application deltas larger than   one flash page use a deterministic page-aligned flash prefix ending at <code>0xED000</code> and place up to 64 KiB   of the logical container tail in that SRAM. Packages of one page or less, and bootloader-update packages,   remain wholly in flash. Hybrid staging is enabled only when the installed bootloader contains exactly one   valid <code>MOTARAMA</code> capability marker; otherwise a larger hybrid-profile fetch fails before erase. Immediately   before a software reset the application publishes a valid-last <code>MOTAHYB1</code> record binding the split geometry   and normalized container hash. The bootloader consumes it once and rejects power-loss, stale-reset, corrupt,   or mismatched-RAM cases before its first application write. A hybrid transfer cannot resume after an   application restart because its suffix is deliberately volatile. The bootloader treats every unknown/legacy   GPREGRET2 handoff value as <code>0xD4000</code>, and accepts a flash-only container only at the bottom-aligned position   for the selected ceiling.</li> <li>nRF52 dynamic apply window: the post-build hook records the resolved app base, linked app end,   internal-ExtraFS/SD/QSPI/hybrid-RAM storage flags, and desired staging ceiling immediately before <code>EndF</code>.   <code>motatool</code> reads that authenticated firmware record and chooses <code>memory_size</code> from the actual patch size   and bottom-aligned stage address. For a hybrid base it charges only the deterministic flash prefix against   that workspace; the retained-RAM suffix is still part of the same hashed logical container.   Firmware without the record retains the conservative <code>0x98000</code> default. Before writing <code>APRV</code>, an   internal-store app validates the staged-address bound; an external SD/QSPI app validates the full detools   geometry against the application workspace. The bootloader independently parses and validates the same   geometry before its first application write. Expanded auto-sized packages require a bootloader   with the ceiling-handoff capability; use <code>--inplace-memory 0x98000</code> when intentionally targeting an older   bootloader and the images still fit that window.</li> <li>nRF52 EndF rescue: <code>ota rescue install &lt;base_hash16&gt;</code> is a pre-provisioned recovery path for an   internal-flash nRF52 application that still runs but cannot validate its own EndF identity. It refuses   when normal EndF validation succeeds, requires the operator hash to exactly equal the staged delta's   <code>base_hash</code>, requires the package <code>target_id</code> to match and its <code>hw_id</code> to pass the normal hardware gate,   and retains the normal payload and signature/allowlist gates. Approval only delegates the base decision:   OTAFIX independently   locates the physical EndF, hashes the running app, and compares that value with the package before its   first app write. A physically absent/corrupt EndF or wrong base therefore returns to the unchanged app;   it still requires USB recovery if that app does not already contain this command.   A chain intended to cross historical firmware must introduce this command in its first bridge and retain   it in every later bridge. Manual pulls still use the build-provided target ID when app-side EndF parsing   fails, so a rescue-capable bridge can fetch its exact successor before invoking the guarded command. Such   a node must acknowledge the condition up front with <code>ota pull &lt;mid8&gt; flash rescue</code>; an ordinary flash pull   refuses before altering staged data. Firmware that predates both rescue commands still requires USB recovery.   Internal-bootloader-self-update builds are a stricter exception: because their ordinary linker may extend   through <code>0xED000</code>, an absent/corrupt live <code>EndF</code> disables every internal staging pull before erase instead   of trusting the legacy 608 KiB estimate.</li> <li>MeshTower V2 SD nRF52: the application stores a contiguous <code>/meshcore-ota.mota</code> on microSD. After   authenticating one exact signed manifest and verifying the leaves/payload/image, it hashes the exact full   container with only <code>APRV</code> normalized to zero and publishes a 72-byte reset-retained <code>MOTASDA2</code> record.   That record binds app-vs-boot purpose, format, raw sector range, total/card geometry, and normalized digest;   OTAFIX consumes and clears it before reading the card. There is no normal sector-1 handoff or additional   OTA-specific partition-layout requirement beyond what the bundled SdFat can mount. The matching   bootloader reads the authorized sectors without mounting FAT, supports either a full image or an in-place delta,   verifies the staged/full result hash, and never writes through <code>0xED000</code> where InternalFS begins. The   exact SD repeater also accepts a manually selected, signed v3 bootloader package when installed and   candidate markers are exactly <code>0x09</code> (<code>SD|BOOT_UPDATE</code>). MeshCore streams the same strict identity,   CRC, vector, signature, MID/hash-confirmation, and complete-image checks from the SD file. GPREGRET   <code>0x6B</code> plus GPREGRET2 <code>0x53</code> selects this privileged path. Both MeshCore and OTAFIX require a hash-valid   live <code>EndF</code> ending by <code>0xE0000</code>; when a nonzero boot-settings bank CRC is active, its recorded size must   also cover that complete live image and stop by <code>0xE0000</code>. For fmt3 MeshCore additionally writes a readback-checked   <code>MOTASDBL</code> token at <code>0xE0000</code> containing the exact total and signed <code>image_hash</code>. OTAFIX binds the parsed manifest,   streamed payload, and final scratch image to that   token, so a removable-media change can only fail closed. OTAFIX then uses <code>0xE0000..0xEA000</code> as temporary scratch; the normal   application linker remains at <code>0xED000</code> and ordinary application updates do not inherit this scratch   headroom restriction. Both fmt2 application apply and fmt3 bootloader apply require installed BLM2   continuity matching the live S140 FWID/application layout. Preview.12 must be upgraded locally over   USB/BLE DFU or SWD. MeshCore never writes a raw sector-1 handoff.</li> <li>Matched external-QSPI nRF52 repeaters: the application reserves the board's dedicated QSPI NOR as a   raw store beginning at offset zero. It obtains a 1-16 MiB capacity from JEDEC, checkpoints payload before   leaf metadata, and verifies each erased/programmed page. GPREGRET2 <code>0x51</code> selects QSPI only when the   matching bootloader advertises the QSPI storage bit; legacy markers retain the internal scan path. The   bootloader pre-hashes a full payload before invalidating the app, or applies an in-place delta with the   complete internal application region as workspace. Companion builds never enable this raw store: some use   QSPI as a filesystem, while others simply leave that chip outside OTA ownership. See   the nRF52 QSPI guide.</li> <li>XIAO bootloader self-update (explicit only): selected XIAO-module QSPI repeater builds link the   ordinary application below <code>0xE0000</code>, reserving <code>0xE0000..0xEA000</code> as a 40 KiB internal scratch bank.   They accept a v3 bootloader package only through an exact manual MID pull. Ordinary <code>ota install</code>,   autofetch, autoinstall, and every application apply backend reject it. The operator then copies the   staged package's exact values from <code>ota bootloader</code> into   <code>ota bootloader install &lt;MID8&gt; &lt;HASH16&gt;</code>. The app repeats the strict v3 geometry, installed/candidate   identity, vectors, embedded CRC/capabilities, complete payload/image hashes, signature, and trusted-key   gates before writing <code>APRV</code>. GPREGRET <code>0x6B</code> plus GPREGRET2 <code>0x51</code> hands the QSPI package to OTAFIX.   <code>APRV</code> carries the app's authenticated and explicitly confirmed authorization decision; OTAFIX does not   repeat Ed25519/allowlist, Merkle, or typed operator confirmation. It independently rechecks the strict v3   structure, canonical identity/capabilities, vectors, payload SHA, embedded CRC, and scratch/copy hashes,   uses the scratch bank to preserve the running application while replacing <code>0xF4000..0xFE000</code>, and reports   boot-update results in GPREGRET2 <code>0xC0..0xCF</code>   (<code>0xC8</code> success). This mechanism cannot bootstrap a stock/older bootloader; install an ABI-3,   boot-update-capable exact-board OTAFIX over USB/BLE DFU or SWD once first.</li> <li>Internal-flash bootloader self-update (explicit only): curated nRF52840 lean repeater/bridge targets   without an OTA-owned SD/QSPI store share the normal bottom-aligned internal store below <code>0xED000</code>.   It holds either an ordinary app delta or the exact 41,330-byte v3 container, never both. The boot package   bottom-aligns at <code>0xE2000</code>; a hash-valid live <code>EndF</code> must prove the complete running image ends at or below   that address before the first erase. OTAFIX reads each source window before erasing and compacts the   payload forward in the same eleven pages to raw <code>0xE2000..0xEC000</code>; no separate flash scratch bank exists.   The qualified application linker reserves a 64 KiB SRAM arena only for hybrid application deltas; the   bootloader package remains wholly in flash. GPREGRET <code>0x6B</code> plus GPREGRET2 <code>0xED</code> selects boot update,   while ordinary app apply uses GPREGRET <code>0x6A</code> plus the same storage source. Exact installed/candidate   capability flags are <code>0x0A</code> (<code>STAGE_CEILING|BOOT_UPDATE</code>). Ordinary deltas remain dynamically sized, may start below   <code>0xE2000</code>, and reconstruct only below the normal <code>0xED000</code> app ceiling. The same signature, explicit   confirmation, exact identity, vector, CRC, and single-marker rules as the XIAO path apply. Bootloader FULL   admission is isolated from ordinary application FULL policy, and privileged partials are never resumed   automatically after an application reboot. See   the nRF52 bootloader-update guide for the exact target inventory.</li> </ul> <p>A signature, when present, proves author authenticity and must pass the device allowlist. Unsigned v2 application packages remain installable when local policy permits them. A v3 bootloader package is always signed and trusted. The one-shot <code>approval</code> marker records local consent before the bootloader may apply it.</p> <p>Bootloader testing note: always test apply with a real different image (base != target). A same-image (X-&gt;X) \"delta\" trivially reproduces the target and gives a false positive.</p>"},{"location":"ota_protocol/#13-versioning-of-this-spec","title":"13. Versioning of this spec","text":"<p>The fixed byte layout has two intentionally disjoint profiles: <code>format_ver = 2</code> for ordinary application packages and <code>format_ver = 3</code> only for the exact privileged bootloader profile in Section 4.3. A parser must reject v2+BOOTLOADER, v3 without exact <code>FULL|SIGNED|BOOTLOADER</code>, and every other version. The multihash <code>hash_algo</code> separately allows swapping the digest family without a format bump. Unknown <code>codec_id</code> / <code>ota_msg_type</code> values are ignored (a node simply will not fetch what it cannot apply).</p>"},{"location":"ota_user_guide/","title":"Updating your node over the air (OTA) - user guide","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>This guide is for node operators: how to update your MeshCore device's firmware over the radio, in 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.)</p> <p>LoRa OTA download and installation are present only in supported Keymind destination artifacts; the receiver must already be running one of those install-capable builds. Some internal-staging nRF52 targets use a lean <code>lora_ota_no_external_sensors</code> target, while matched external-QSPI boards can retain their normal full-sensor repeater features. Release filenames include an OTA marker, but capability must still be confirmed on the running device. A source can be an OTA-enabled infrastructure node or a source-only Full Companion backed by <code>motatool</code>. Intermediate repeaters do not need OTA-enabled firmware: current repeater builds transport OTA floods opaquely, subject to their normal forwarding filters, duplicate checks, and flood limits. OTA radio traffic is accepted, generated, and relayed only while <code>tempradio</code> is actually running on that node. Every source, receiver, and intermediate repeater must therefore have an overlapping temporary-radio window.</p> <p>The recommended temporary OTA settings use 250 kHz bandwidth, SF5, CR5, and a 120-minute window. For a North American node currently configured for 910.525 MHz, run this on every participating node:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>Use the node's current permitted regional frequency in place of <code>910.525</code> when necessary.</p> <p>The scripted updater checks the firmware version of the receiver and every sender before deciding whether RX power saving can remain active. At SF5/BW250, an all-v1.17.1.5-or-newer path can use effective RXPS level 8 with the tuple-selected 64-symbol physical preamble. SF5/BW500 can use level 8 with 128 symbols. Other fast tuples remain at the shortest viable preamble, normally 32. A mixed, older, or unknown long-preamble path is put in continuous receive for the update, then the receiver's exact saved RXPS setting is restored. This preserves the RX benefit without risking missed packets from a legacy 32-symbol sender.</p> <p>Can my node install the update? Choose a release-table artifact explicitly labelled LoRa-OTA capable, then confirm <code>ota self</code> and <code>ota status</code> expose install support; do not infer support from the filename alone. 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. An intermediate repeater only relays packets and needs neither an install-capable image nor OTAFIX. Check the bootloader release for an exact board match before attempting an update.</p> <p>The following nRF52 repeater families gained firmware-side LoRa OTA targets in this release. Their ordinary repeater keeps its complete declared sensor recipe; the install-capable <code>lora_ota_no_external_sensors</code> sibling is smaller:</p> <ul> <li>Heltec Mesh Solar, T1, and Tower V2</li> <li>Keepteen LT1, LilyGo T-Impulse Plus, Mesh Pocket, and Nano G2 Ultra</li> <li>Minewsemi ME25LS01, RAK3401, SenseCAP Solar, and Wio WM1110</li> </ul> <p>The RAK3401 <code>RAK_3401_repeater_lora_ota_no_external_sensors</code> image trims selected optional environmental/ranging drivers but does not disable I2C. It retains the INA219, INA226, INA260, and INA3221 voltage/current monitors, board display and RTC support, and both RAK12500 I2C and RAK12501/L76K UART GPS paths. The four INA drivers are only the retained voltage/current entries in the optional environmental-sensor table; they are not the only I2C users. The SSD1306 OLED, autodiscovered DS3231/RV3028/PCF8563/RX8130CE RTCs, and RAK12500 GPS use I2C as separate board peripherals. Install one GPS module in sensor slot A. Slot D's reset/PPS lines conflict with the RAK13302 radio's BUSY/DIO1 lines.</p> <p>The firmware-configured INA3221 address and the RAK12500 address are both <code>0x42</code>, so those devices cannot share one bus at those addresses. To install both, leave the RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a firmware build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>.</p> <p>The reduced RAK4631 profiles likewise retain the four INA monitors. The plain repeater and Serial2 bridge retain GPS: a RAK12501 can use sensor slot A or D, and a RAK12500 can use slot A or C. The runtime RS-232 bridge defaults to Serial2 so the UART RAK12501 can retain Serial1. The merged runtime image always reserves Serial1: a bounded silent probe cannot prove that a cold RAK12501 is absent, and turning the GPS setting off cannot stop a fitted module from driving the shared UART while WB_IO2/3V3_S remains powered. Use Serial2. Serial1 requires an explicit no-GPS/dedicated image. The reservation remains fail-closed even when an I2C RAK12500 is detected. The explicitly compiled <code>RAK_4631_repeater_bridge_rs232_serial1_lora_ota_no_external_sensors</code> target omits the combined GPS provider because its bridge owns the UART used by RAK12501; consequently that legacy image does not expose the I2C RAK12500 path either, even though RAK12500 itself does not use the UART.</p> <p>Selected nRF52 repeaters with dedicated external QSPI can now stage the complete package off-chip, so their normal full-sensor repeater build can install a full image or an in-place delta. The current matched families are XIAO nRF52840 and its XIAO-module derivatives, original LilyGo T-Echo, ThinkNode M1/M6, Wio Tracker L1, SenseCAP Solar, and the dedicated RAK4631 + RAK15001 slot-C target. The list also includes a separately wired W25Q16JV on RAK19007 with either RAK4631 or RAK3401 + RAK13302. These require the corresponding exact QSPI-aware OTAFIX bootloader; see the nRF52 QSPI guide.</p> <p>The W25Q16 option uses one permanent RAK19007 wiring for either core: CLK/MISO/ MOSI tap IO-connector pins 26/27/28, flash CS uses J11 AIN1, and power uses J12 VDD (3.3 V) and GND. Add an approximately 10 kOhm CS-to-VDD pull-up and never power the flash from VBAT. The three SPI signals require underside pads or an IO-connector interposer; the easy J10/J11/J12 headers do not expose them. The flash consumes no WisBlock slot, so a supported GPS can remain in slot A.</p> <p>The ordinary full-sensor <code>RAK_4631_repeater</code> image remains too large for the safe internal in-place update limit. Without external flash, use <code>RAK_4631_repeater_lora_ota_no_external_sensors</code>; it trims selected optional environmental/ranging drivers while retaining generic I2C, battery monitoring, the four INA monitors, and target-compatible GPS. A RAK4631 fitted with RAK15001 in sensor slot C can instead use <code>RAK_4631_repeater_rak15001_slot_c_lora_ota</code> to retain the full sensor/GPS set and stage full images or deltas off-chip.</p> <p>For the external Winbond breakout, use <code>RAK_4631_repeater_w25q16_lora_ota</code> on RAK4631 or <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code> on RAK3401 + RAK13302. They retain the full sensor/GPS recipe and require exactly a 2 MiB <code>EF4015</code> W25Q16 plus the bootloader for that same core/radio/flash combination. Install <code>wiscore_rak4631_w25q16</code> for RAK4631 or <code>wiscore_rak3401_rak13302_w25q16</code> for RAK3401 + RAK13302 as a one-time prerequisite. The physical wiring is shared, but the two firmware identities are deliberately different and cannot be substituted for one another.</p>"},{"location":"ota_user_guide/#the-important-part-first-its-safe","title":"The important part first: it's safe","text":"<ul> <li>Nothing installs by itself. Your node can discover and download an update, but   it only installs when you say so (unless you deliberately turn on auto-install - see below).</li> <li>Bad downloads can't sneak in. Every piece of the firmware is checked against a cryptographic   fingerprint as it arrives, and the whole image is verified again before install. A corrupt or tampered   download is rejected, not installed.</li> <li>You choose who to trust. Updates can be signed by their author. You can tell your node to only   auto-install firmware signed by keys you've added.</li> <li>Discovery stays quiet; a transfer is deliberate. Periodic update discovery uses background priority.   Once a download starts, its transfer packets are primary traffic across every relay hop, so use   TempRadio as an OTA maintenance window when delaying unrelated mesh traffic would matter.</li> <li>It can recover. If an install ever fails, the node falls back to a safe recovery mode (you can   re-flash a known-good firmware over USB) - it won't be left bricked.</li> </ul>"},{"location":"ota_user_guide/#how-to-talk-to-your-node","title":"How to talk to your node","text":"<p>Connect to your node's console - usually a USB serial terminal at 115200 baud (or whatever tool you already use to manage the node). You type <code>ota ...</code> commands and the node replies in plain words.</p> <p>The commands have short, friendly names (and most accept aliases, so you don't have to remember exact spelling): type <code>ota help</code> any time to see the list, or just <code>ota</code> for a status summary.</p>"},{"location":"ota_user_guide/#common-tasks","title":"Common tasks","text":""},{"location":"ota_user_guide/#1-see-what-im-running-and-whether-anything-is-going-on","title":"1. See what I'm running and whether anything is going on","text":"<pre><code>ota status\n</code></pre> <p>Shows your current firmware version, your node's update \"target\" (its hardware/role id), and whether a download is in progress.</p> <p>For a denser admin view - your firmware's content id (<code>mid</code>) and its body hash, the fingerprint of the set you're serving, live download progress, and the current policy - use:</p> <pre><code>ota stats\n</code></pre> <p>On a remote node this is admin-only (the remote command console requires the admin password) - send it from the app's repeater command screen, or the WiFi/serial OTA console.</p>"},{"location":"ota_user_guide/#2-find-updates-available-near-me","title":"2. Find updates available near me","text":"<pre><code>ota ls\nota ls 2                 # page 2 when more than two updates are available\n</code></pre> <p>Your node asks around and lists the firmware updates other nodes nearby are offering, in plain words - each with a temporary number, a stable eight-hex manifest ID, its version, whether it's a full image or a small delta, how many nodes have it, and how recently it was seen. For example:</p> <pre><code>Updates 1/1 (2 src; refreshing):\n 1) 838B8169 v1.2.3 delta [same target] 3n 5s\n 2) BF0AB0C4 v1.2.0 full [unsupported] 1n 12s\n</code></pre> <p>Each row shows the version, full-vs-delta, whether it fits your node, how many nodes have it, and how long ago it was seen. The fit marker:</p> <ul> <li>[same target] - the advertised target ID matches this hardware-and-role build. Download and apply   still enforce codec, bootloader, signed hardware tag, base hash, and integrity checks.</li> <li>[unsupported] - the target may match, but this build or its bootloader cannot apply that codec. A common   example is the source node's self-served full image on an internal-staging nRF52, which needs an   in-place delta. A matched external-QSPI nRF52 can accept that full codec.</li> <li>[rescue] - an installable in-place nRF52 delta for the same target, but this running firmware has no   valid app-side EndF. It requires the explicit rescue download and install flow below.</li> <li>[name] - a different known board or role (for example <code>[ProMicro_companion_radio_usb]</code>). Don't install it.</li> <li>[?] - can't tell (a build with no target id set, e.g. a bare IDE build rather than a release build).</li> </ul> <p>Run it again after a few seconds - discovery happens in the background, so the list fills in. Nothing is downloaded yet; this is just looking around. <code>refreshing</code> means the command has just sent asynchronous catalog queries, so run it again even when an older row is already visible. Two updates fit in each remote CLI reply; use <code>ota ls 2</code>, <code>ota ls 3</code>, and so on for later pages. Catalog rows can change while replies arrive, so use the displayed manifest ID for scripts and important operations rather than a numeric position. (<code>ota neighbors</code> / <code>ota updates</code> also work.)</p>"},{"location":"ota_user_guide/#3-download-an-update","title":"3. Download an update","text":"<p>Pick one from the list by its stable manifest ID (a number also works for interactive use), and say where to put it:</p> <pre><code>ota pull 838B8169 flash            # stage it in this node's flash, to install here\nota pull 838B8169 folder           # capture it onto a connected motatool folder as &lt;id&gt;.mota\nota pull 838B8169 folder validate  # warm-start capture from a motatool --seed build (much faster; below)\n</code></pre> <p>The destination is required - <code>ota pull 838B8169</code> on its own just shows the choices. <code>flash</code> is always available (stage here, then <code>ota install</code>). <code>folder</code> appears only while a <code>motatool serve</code> link is attached (it shows the link, e.g. <code>folder: tcp 192.168.4.5</code>); it streams the firmware straight onto the host folder - nothing is staged on this node. That's how you grab an exact copy of another device's firmware off the mesh (to a <code>.mota</code> file) so you can later build a delta against firmware you don't otherwise have. (<code>ota get</code> is an alias.)</p> <p><code>validate</code> (warm-start, advanced). Capturing a full image over the radio is slow. If you have a similar build on the computer (e.g. a fresh recompile of the same firmware), run motatool with <code>--seed &lt;that.mota&gt;</code> and add <code>validate</code>: the node fetches just the target's block fingerprints, keeps every block your seed already matches, and pulls over the radio only the handful that actually differ - turning a ~30-minute capture into seconds. The result is still a byte-exact, verified copy of the target.</p> <p>Where the seed comes from: it is the <code>--seed &lt;file&gt;</code> you pass to <code>motatool serve</code> - not a file you drop into the capture (<code>--dir</code>) folder, which is only the destination and starts empty. There is exactly one configured seed. When you run <code>... folder validate</code>, the node asks motatool to begin the capture and motatool stamps that seed's payload into the fresh <code>.part</code> in the same step - so it is always the file you named, with no guessing. <code>validate</code> is the switch: a plain <code>folder</code> pull ignores any seed and fetches from scratch; re-running a <code>validate</code> pull re-begins fresh (it never resumes a stale partial). Nothing about the seed is trusted - every kept block is checked against the target's own fingerprints, so a mismatched or missing seed just means those blocks are fetched over the radio (correct result, only slower).</p> <p>The node fetches from one source as primary traffic, with bounded adaptive request flights. Every session probes with one manifest block, then clean flights grow <code>1 -&gt; 2 -&gt; 3 -&gt; 4</code> blocks on RAK3401 OTA builds. New application packages use 2 KiB blocks; deployed 1 KiB packages remain supported. All blocks in a flight share one request packet, and the receiver stays silent until the source/relays finish returning them. A recovery halves the next flight. Retry timing follows the active SF/BW airtime, duty budget, and path length, so faster settings recover sooner without a fixed one-second request colliding with a valid multi-hop response. Mesh repeaters carry the packets only while their temporary-radio windows are active. Check progress with <code>ota status</code>.</p> <p>If a <code>folder</code> pull loses its link mid-transfer, <code>ota status</code> shows paused - the host keeps the partial and the pull resumes (filling only what's missing) the moment you reconnect motatool; it never falls back to flash. A TCP disconnect preserves the selected image even if it happens before its manifest arrives or during the final save. Reconnect through the same transport; an interrupted manifest or seed comparison restarts initialization, while a partial transfer rechecks its stored blocks. The paused capture keeps its OTA workspace until reconnection or cancellation. To stop a download you no longer want:</p> <pre><code>ota cancel\n</code></pre> <p>For a download staged on the node, success means current firmware also invalidated the persistent flash/SD/QSPI copy; it reports an error if that media operation cannot be verified. For a <code>folder</code> capture, cancel only detaches the live session and retains the host partial so it can be resumed or removed on the host deliberately. On a MeshTower SD auto-archive capture, cancel also detaches the live archive session and retains its card partial for the archive service to resume later; use <code>ota cache off</code> to stop new archive captures.</p>"},{"location":"ota_user_guide/#4-install-a-downloaded-update","title":"4. Install a downloaded update","text":"<p>Once <code>ota status</code> shows the download is ready to install:</p> <pre><code>ota install\n</code></pre> <p>The node verifies the firmware one last time, and if everything checks out it installs it and reboots into the new version. If the check fails, it tells you why and does not install. Unsigned images normally install only through this explicit command. The MeshTower V2 SD target is stricter and requires an allowlisted signature even for a manual application install, because it authorizes removable-media bytes for the bootloader. A signed image whose signer is not in the device allowlist is rejected; trusted signed images can auto-install only when that policy is enabled and the signed version is strictly newer than the running hash-valid EndF version. Manual <code>ota install</code> remains the deliberate equal-version/rollback override.</p> <p>After it reboots, run <code>ota status</code> to confirm the new version.</p>"},{"location":"ota_user_guide/#updating-an-nrf52-bootloader-advanced-explicit-only","title":"Updating an nRF52 bootloader (advanced, explicit only)","text":"<p>This is available on specially marked no-external-flash nRF52840 lean repeater/bridge builds, on the legacy XIAO nRF52840/Sense raw-QSPI builds, and on the exact <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code> microSD build, after a one-time exact-board ABI-3 OTAFIX installation over USB/BLE DFU or SWD. It is not the normal firmware update path. Check support first:</p> <pre><code>ota bootloader\n</code></pre> <p>The reply must show a CRC-valid installed identity plus ABI 3 and the exact storage/boot-update capability bits for that build (<code>0x09</code> for MeshTower V2 microSD, <code>0x0A</code> for the shared internal store, or <code>0x0E</code> for XIAO raw QSPI). A bootloader package appears as <code>bootloader</code> in <code>ota ls</code>. It is never downloaded or installed automatically, even if both OTA automation settings are enabled. Use its stable ID explicitly:</p> <pre><code>ota pull &lt;MID8&gt; flash\n# wait until ota status says this bootloader download is ready\nota bootloader\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Copy both confirmation values exactly from the second <code>ota bootloader</code> reply. Ordinary <code>ota install</code> deliberately refuses this package. The privileged command requires an exact 40 KiB candidate payload in the fixed 41,330-byte container, a valid exact embedded identity/CRC and vector table, continued boot-update support, required <code>BLM2</code>/<code>SOFT</code> continuity metadata at canonical raw-image offset <code>0x9FB4</code>, a boot version that exactly matches the package and is newer than installed BLM2, and a valid signature from a key already in <code>ota key</code>'s trusted allowlist. It preserves the running application while OTAFIX replaces itself; <code>blup:C8</code> in post-reboot <code>ota status</code> means success. Remote rollback is refused. Any node lacking this command or those capabilities must update its bootloader locally instead.</p> <p>On an internal-flash target, the package shares the ordinary store below <code>0xED000</code> and bottom-aligns at <code>0xE2000</code>; there is no separate reserved scratch bank. A valid live <code>EndF</code> must prove the current image ends at or below that address before any page is erased. If <code>EndF</code> is missing/corrupt or the app is too large, the pull is refused and local DFU/SWD is required. On the MeshTower V2 SD target, the application linker remains at <code>0xED000</code>, but bootloader replacement needs temporary scratch beginning at <code>0xE0000</code>. A hash-valid live <code>EndF</code> must therefore prove the complete current image ends by <code>0xE0000</code>. A CRC-bound boot-settings bank must cover that complete image while also ending by <code>0xE0000</code>. MeshCore binds both application and bootloader SD approval to purpose, exact raw geometry, and a normalized SHA-256 in a reset-retained <code>MOTASDA2</code> record. Boot updates also bind the exact authenticated signed image hash in the E0000 token. OTAFIX consumes the retained record before media access, so a later card change or power cycle fails instead of authorizing different bytes. MeshCore never claims or writes raw sector 1. Both application and bootloader OTA wait until a matching BLM2 bootloader has been provisioned locally; preview.12 requires USB/BLE DFU or SWD first. Larger applications can continue to use normal application mOTA; only bootloader self-update is refused. See the nRF52 bootloader-update guide for the complete target inventory, storage layouts, and safety contract.</p>"},{"location":"ota_user_guide/#5-if-something-goes-wrong","title":"5. If something goes wrong","text":"<ul> <li>A download that stalls or gets interrupted just resumes later. Use   <code>ota cancel</code> to durably discard device staging; a folder capture keeps its   host partial for a later resume.</li> <li>A legacy app-only internal-flash nRF52 that still runs but reports <code>no EndF</code> can use the pre-provisioned rescue path   if its physical EndF is intact and only app-side validation is failing. Fetch the exact <code>[rescue]</code>   in-place delta with an explicit acknowledgement, obtain its 16-hex-digit <code>base_hash</code> from the package   metadata, then run:</li> </ul> <p><code>text   ota pull &lt;mid8&gt; flash rescue   # wait for ota status to say ready to install   ota rescue install &lt;base_hash16&gt;</code></p> <p>This is not a force option. It refuses a normally valid EndF, a different package hash, hardware or   target mismatch, corrupt payload, and invalid/untrusted signatures. The bootloader independently hashes   the running app and rejects a wrong base before writing the app. If the physical EndF is absent or the   rescue commands were not already in the running firmware, recover over USB.   Release chains should put this command in their first bridge and keep it in every bridge after that.   The shared-internal bootloader-update builds are intentionally excluded:   without valid live <code>EndF</code>, they refuse every internal pull before erase   because their normal application can extend through <code>0xED000</code>. Recover one   of those builds over USB/BLE DFU or SWD. - If an install fails, the node won't boot a broken image - it lands in recovery mode:   - nRF52: it appears as a USB drive; drag a known-good firmware <code>.uf2</code> for that exact board onto it     to recover.   - ESP32: it keeps the previous firmware in the other slot and rolls back. - When in doubt, you can always re-flash over USB the normal way.</p>"},{"location":"ota_user_guide/#adjust-lora-ota-speed","title":"Adjust LoRa OTA speed","text":"<p>Use one saved speed factor for this node's LoRa OTA traffic:</p> <pre><code>get ota.speed\nset ota.speed 0.5\nset ota.speed .05\nset ota.speed 3\nset ota.speed 1\n</code></pre> <p>The range is 0.05 through 3, including decimals. 1 is the existing timing. At <code>0.5</code>, adjustable OTA delays are twice as long; at <code>0.05</code>, they are twenty times as long. At <code>3</code>, adjustable delays are divided by three. Actual transfer speed also depends on packet airtime, the configured airtime budget, relays, and packet loss; <code>3</code> does not guarantee three times the throughput.</p> <p>The factor covers OTA requests and responses (catalog, manifest, leaves, DATA, and proofs), OTA relay delays, discovery jitter, and automatic OTA adverts. Below <code>1</code>, the transmit queue also spaces out every OTA packet, including both profile copies, while letting ordinary messages run. Recovery waits grow for slower transfers; faster settings retain the existing retry allowance so they do not retry before a physical response train can finish. The radio's frequency, bandwidth, SF, coding rate, preamble, and airtime budget stay as set. The proof turnaround allowance also keeps its existing physical minimum. Dual-profile timing accounts for the participating profiles and reply copies; it does not vary with the scanner's current visit. Deliberate slow pacing is excluded from observer builds' stale-packet age, while congestion still ages queued packets normally.</p> <p>Set the same factor on the source, destination, and OTA relays. It is a local setting, not a value negotiated with peers. A slow source paired with a receiver at <code>1</code> can cause unnecessary retries. The setting takes effect during an active session, survives reboot and temporary-radio expiry, and applies to OTA on either radio profile. <code>set ota.speed 1</code> restores the previous pace. Ordinary chat, node adverts, and USB/WiFi source transfers keep their timing. Local verification of a staged image and leaf comparisons keep their normal maintenance rate even when LoRa pacing is slow. If the local transmit queue cannot accept a catalog, manifest, or leaf request, OTA keeps it pending without consuming a network retry. Successfully queued requests that receive no answer still have bounded retries. Blocked block requests also preserve the v2 transfer format and fragments already received; queue congestion alone does not trigger legacy fallback. Retry timing includes the primary channel when an RX-only temporary radio2 uses crossover to send requests there.</p> <p><code>ota config speed 0.5</code> is an equivalent setter. <code>ota config speed</code> and <code>ota speed</code> read the current factor; the <code>ota config</code> summary also includes it. The setting is available on OTA-enabled repeaters, rooms, sensors, Companions, and seeder-only builds. Its separate <code>/ota_speed</code> settings file preserves the existing preference layouts and does not need an active OTA workspace.</p>"},{"location":"ota_user_guide/#optional-let-it-update-automatically","title":"Optional: let it update automatically","text":"<p>By default your node only discovers updates - it won't download or install on its own. If you want more automation (e.g. for a remote node you can't easily reach), you can opt in. These settings are saved.</p> <pre><code>ota config autofetch any        # auto-DOWNLOAD any compatible update for this node (still won't install)\nota config autofetch signed     # auto-download only signed updates\nota config autofetch off        # back to manual (default)\n\nota config autoinstall trusted  # auto-INSTALL only a trusted signed version newer than the running EndF\nota config autoinstall off      # never auto-install (default)\n\nota config advert 1440          # re-advertise every N minutes while temp radio is running\nota config advert 0             # only advertise when a temp-radio window starts\n\nota config hops 3               # how far OTA travels: accept from / relay up to N repeater hops (default 3)\nota config hops 0               # only exchange OTA with directly-connected nodes (never relay)\n\nota config                      # show the current settings\n</code></pre> <p>These policies also govern automatic adoption of an interrupted staged download after reboot. <code>off</code> leaves it untouched, <code>signed</code> requires the stored manifest's signed flag, and automatic resume requires the stored target to match this node and its version to be newer than the running valid EndF. Reissuing an explicit <code>ota pull &lt;MID8&gt;</code> remains the deliberate override for an older or unsigned partial. For bring-up/debugging, <code>ota dev resume &lt;MID8&gt;</code> performs the same explicit MID-bound re-adoption without starting a new network fetch. After reboot it requires the MID; bare <code>ota dev resume</code> is accepted only while an active/requested session MID still exists, and malformed or missing identifiers are rejected. If raw flash contains multiple valid staged headers, automatic resume leaves them untouched rather than guessing which is newest. Specify the intended MID to select its unique checkpoint; ambiguous matches are rejected. Temporary storage read failures no longer consume a download slot indefinitely: host storage pauses for reconnection, while non-reconnectable storage reports a storage error and can be retried.</p> <p>Recommended for most people: leave both off and update by hand. Use <code>autoinstall trusted</code> only once you've added the signer's key (next section) and you trust them to push updates unattended. Automatic admission and final apply both reject zero, equal, or older signed versions; a dishonest catalog version cannot bypass the manifest check. Use manual <code>ota pull</code> plus <code>ota install</code> for an intentional rollback.</p> <p>The MeshTower V2 SD OTA target has a separate, default-on archive policy. It saves all mOTAs it sees to the SD card so the repeater can seed them later; this does not install them and does not change the install-oriented <code>autofetch</code> default above. Use <code>ota cache</code> for status and <code>ota cache off</code> or <code>ota config cache off</code> to stop new archive captures. Already cached files remain available to peers. Manual <code>ota pull</code> commands take priority and an interrupted archive capture resumes later. See Preload many mOTAs from a computer for the required <code>/mota/&lt;manifest-id&gt;.mota</code> filenames and the complete TempRadio seeding workflow.</p>"},{"location":"ota_user_guide/#optional-only-trust-updates-from-specific-people","title":"Optional: only trust updates from specific people","text":"<p>If you'll use auto-install, tell your node which signing keys to trust. The firmware author shares their public key (a hex string); you add it:</p> <pre><code>ota key add &lt;public-key-hex&gt;    # trust this signer\nota key list                    # show trusted signers\nota key rm &lt;public-key-hex&gt;     # stop trusting one\n</code></pre> <p>Only strictly newer updates signed by a trusted key are eligible for auto-install. Manual <code>ota install</code> permits an unsigned package after all integrity, hardware, base, and bootloader checks pass, except on the MeshTower V2 removable-SD path where all application installs must be signed and allowlisted. A signed package whose signer is not in the device allowlist is rejected rather than silently treated as unsigned.</p>"},{"location":"ota_user_guide/#sharing-updates-with-others-advanced","title":"Sharing updates with others (advanced)","text":""},{"location":"ota_user_guide/#relay-a-folder-of-firmware-from-a-computer","title":"Relay a folder of firmware from a computer","text":"<p>If your node is connected to a computer (e.g. a gateway on a Raspberry Pi), it can hand out a whole folder of firmware files to the mesh - without storing them itself. Useful for seeding a new release to a remote area.</p> <ol> <li>Put the firmware files (<code>.mota</code> files - see below) in a folder on the computer.</li> <li>Install the helper tool once - the standalone <code>motatool</code> CLI (https://github.com/vk496/motatool) -    then point it at your node and the folder - over the node's USB serial, over WiFi if it is    an ESP32 WiFi companion or FULL ESP32 node, or over encrypted Bluetooth if it is an nRF52 Full Companion:    <code>git clone https://github.com/vk496/motatool &amp;&amp; cargo install --path ./motatool    # over USB serial:    motatool serve --dir ./my_firmware/ --serial /dev/ttyACM0 -v    # ...or over WiFi: the seeder is on dedicated TCP port 5001:    motatool serve --dir ./my_firmware/ --tcp 192.168.1.50:5001 -v    # ...or over paired BLE to an nRF52 Full Companion (protocol v14):    python3 tools/ble_mota/ble_mota_seeder.py \\      --device MeshCore-MyCompanion --dir ./my_firmware/</code>    It answers the node's requests; your node then advertises those updates to neighbours, who can    <code>ota get</code> them like any other. (A WiFi node prints its IP + seeder port to the serial log on connect.    Details: https://github.com/vk496/motatool.)</li> </ol> <p>Check the device's attach reply or run <code>ota folder</code>: <code>host=X/Y</code> means the firmware is advertising <code>X</code> of the <code>Y</code> valid entries reported by the host. Serve registries are deliberately RAM-bounded on smaller builds, and the node's own firmware also consumes a slot. If <code>X &lt; Y</code>, split the chain across seeders/folders or use a higher-capacity seeder; <code>motatool</code> saying that every file is valid does not mean every file fit on-device.</p> <p>To stop, just stop the daemon - over WiFi the node auto-detaches when the connection closes; over USB you can also run <code>ota folder off</code> on the node. <code>ota folder</code> on its own lists what your node is offering. On a FULL repeater or room server, run <code>start webconfig</code> first if WiFi is not already active. Other FULL roles with browser OTA support can use the <code>MeshCore-OTA</code> access point from <code>start ota</code> and connect to <code>192.168.4.1:5001</code>. Every LoRa participant still needs an overlapping <code>tempradio</code> window.</p>"},{"location":"ota_user_guide/#everyone-helps-share","title":"Everyone helps share","text":"<p>You don't have to be a gateway to help. Once any node finishes downloading an update, it automatically offers it to its neighbours too. So a new firmware spreads outward node-to-node, instead of everyone hammering the one node that had it first. Discovery remains background traffic; an actual transfer is primary traffic for the duration of its TempRadio maintenance window.</p>"},{"location":"ota_user_guide/#where-firmware-files-come-from","title":"Where firmware files come from","text":"<p>OTA distributes <code>.mota</code> files - a packaged, verifiable firmware image (full image or a small \"delta\" that only contains what changed). You get them by:</p> <ul> <li>Downloading a build. This fork publishes a rolling <code>dev-latest</code> release on GitHub with the   current firmware for many boards, each accompanied by a <code>.full.mota</code> and a tiny <code>.delta.mota</code>. Grab the   one for your board to test.</li> <li>Building your own with the <code>mota</code> packaging tool - see tools/mota/README.md   (this is for people distributing updates, not everyday operators).</li> </ul>"},{"location":"ota_user_guide/#quick-reference","title":"Quick reference","text":"I want to... Command List all commands <code>ota help</code> See my firmware + any download <code>ota status</code> (or just <code>ota</code>) Admin: ids/hashes + serving + policy <code>ota stats</code> (admin-only remotely) Find updates nearby <code>ota ls</code> Download a listed update for installation <code>ota get &lt;mid8&gt; flash</code> Cancel a download <code>ota cancel</code> Install a finished download <code>ota install</code> Recover app-side <code>no EndF</code> on a legacy app-only internal nRF52 <code>ota rescue install &lt;base_hash16&gt;</code> Turn on auto-download <code>ota config autofetch any</code> Turn on auto-install (trusted only) <code>ota config autoinstall trusted</code> Trust a signer <code>ota key add &lt;hex&gt;</code> Relay a folder (gateway) <code>ota folder on</code> + the seeder daemon List what I'm offering <code>ota folder</code> <p>(Older names still work too: <code>neighbors</code>/<code>updates</code> = <code>ls</code>, <code>pull</code> = <code>get</code>, <code>applydelta</code>/<code>apply</code> = <code>install</code>, <code>drop</code>/<code>stop</code> = <code>cancel</code>.)</p>"},{"location":"ota_user_guide/#a-few-terms","title":"A few terms","text":"<ul> <li>Firmware - the software running your node. Updating it can add features or fix bugs.</li> <li><code>.mota</code> - a packaged firmware update file, with built-in integrity checks.</li> <li>Target - your node's hardware + role identity. Your node only auto-fetches updates built for the   same target, so it won't grab firmware meant for a different board.</li> <li>Delta - a small update containing only the changes from your current firmware (faster to send than a   full image). Your node rebuilds the complete firmware from it and verifies the result before installing.</li> <li>Signed - the update carries the author's cryptographic signature, so you can verify who made it.</li> </ul> <p>For the full technical details (the file format and the radio protocol), see the OTA protocol spec.</p>"},{"location":"packet_format/","title":"Packet Format","text":"<p>This document describes the MeshCore packet format.</p> <ul> <li><code>0xYY</code> indicates <code>YY</code> in hex notation.</li> <li><code>0bYY</code> indicates <code>YY</code> in binary notation.</li> <li>Bit 0 indicates the bit furthest to the right: <code>0000000X</code></li> <li>Bit 7 indicates the bit furthest to the left: <code>X0000000</code></li> </ul>"},{"location":"packet_format/#version-1-packet-format","title":"Version 1 Packet Format","text":"<p>This is the current version-1 MeshCore wire packet structure. Older firmware may support only a subset of the path encodings and payload types described here.</p> <pre><code>[header][transport_codes(optional)][path_length][path][payload]\n</code></pre> <ul> <li>header - 1 byte<ul> <li>8-bit Format: <code>0bVVPPPPRR</code> - <code>V=Version</code> - <code>P=PayloadType</code> - <code>R=RouteType</code></li> <li>Bits 0-1 - 2-bits - Route Type<ul> <li><code>0x00</code>/<code>0b00</code> - <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> - Flood Routing + Transport Codes</li> <li><code>0x01</code>/<code>0b01</code> - <code>ROUTE_TYPE_FLOOD</code> - Flood Routing</li> <li><code>0x02</code>/<code>0b10</code> - <code>ROUTE_TYPE_DIRECT</code> - Direct Routing</li> <li><code>0x03</code>/<code>0b11</code> - <code>ROUTE_TYPE_TRANSPORT_DIRECT</code> - Direct Routing + Transport Codes</li> </ul> </li> <li>Bits 2-5 - 4-bits - Payload Type<ul> <li><code>0x00</code>/<code>0b0000</code> - <code>PAYLOAD_TYPE_REQ</code> - Request (destination/source hashes + MAC)</li> <li><code>0x01</code>/<code>0b0001</code> - <code>PAYLOAD_TYPE_RESPONSE</code> - Response to <code>REQ</code> or <code>ANON_REQ</code></li> <li><code>0x02</code>/<code>0b0010</code> - <code>PAYLOAD_TYPE_TXT_MSG</code> - Plain text message</li> <li><code>0x03</code>/<code>0b0011</code> - <code>PAYLOAD_TYPE_ACK</code> - Acknowledgment</li> <li><code>0x04</code>/<code>0b0100</code> - <code>PAYLOAD_TYPE_ADVERT</code> - Node advertisement</li> <li><code>0x05</code>/<code>0b0101</code> - <code>PAYLOAD_TYPE_GRP_TXT</code> - Group text message (unverified)</li> <li><code>0x06</code>/<code>0b0110</code> - <code>PAYLOAD_TYPE_GRP_DATA</code> - Group datagram (unverified)</li> <li><code>0x07</code>/<code>0b0111</code> - <code>PAYLOAD_TYPE_ANON_REQ</code> - Anonymous request</li> <li><code>0x08</code>/<code>0b1000</code> - <code>PAYLOAD_TYPE_PATH</code> - Returned path</li> <li><code>0x09</code>/<code>0b1001</code> - <code>PAYLOAD_TYPE_TRACE</code> - Trace a path, collecting SNR for each hop</li> <li><code>0x0A</code>/<code>0b1010</code> - <code>PAYLOAD_TYPE_MULTIPART</code> - Packet is part of a sequence of packets</li> <li><code>0x0B</code>/<code>0b1011</code> - <code>PAYLOAD_TYPE_CONTROL</code> - Control packet data (unencrypted)</li> <li><code>0x0C</code>/<code>0b1100</code> - <code>PAYLOAD_TYPE_OTA</code> - OTA-over-LoRa firmware distribution</li> <li><code>0x0D</code>/<code>0b1101</code> - reserved</li> <li><code>0x0E</code>/<code>0b1110</code> - reserved</li> <li><code>0x0F</code>/<code>0b1111</code> - <code>PAYLOAD_TYPE_RAW_CUSTOM</code> - Custom packet (raw bytes, custom encryption)</li> </ul> </li> <li>Bits 6-7 - 2-bits - Payload Version<ul> <li><code>0x00</code>/<code>0b00</code> - v1 - 1-byte src/dest hashes, 2-byte MAC</li> <li><code>0x01</code>/<code>0b01</code> - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)</li> <li><code>0x02</code>/<code>0b10</code> - v3 - Future version</li> <li><code>0x03</code>/<code>0b11</code> - v4 - Future version</li> </ul> </li> </ul> </li> <li><code>transport_codes</code> - 4 bytes (optional)<ul> <li>Only present for <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> and <code>ROUTE_TYPE_TRANSPORT_DIRECT</code></li> <li><code>transport_code_1</code> - 2 bytes - <code>uint16_t</code> - calculated from region scope</li> <li><code>transport_code_2</code> - 2 bytes - <code>uint16_t</code> - reserved</li> </ul> </li> <li><code>path_length</code> - 1 byte - Encoded path metadata<ul> <li>Bits 0-5 store path hash count / hop count (<code>0-63</code>)</li> <li>Bits 6-7 store path hash size minus 1<ul> <li><code>0b00</code>: 1-byte path hashes</li> <li><code>0b01</code>: 2-byte path hashes</li> <li><code>0b10</code>: 3-byte path hashes</li> <li><code>0b11</code>: reserved / unsupported</li> </ul> </li> </ul> </li> <li><code>path</code> - <code>hop_count * hash_size</code> bytes - Path to use for Direct Routing or flood path tracking<ul> <li>Up to a maximum of 64 bytes, defined by <code>MAX_PATH_SIZE</code></li> <li>Effective byte length is calculated from the encoded hop count and hash size, not taken directly from <code>path_length</code></li> <li>v1.12.0 firmware and older only handled legacy 1-byte path hashes and dropped packets whose path bytes exceeded 64 bytes</li> </ul> </li> <li><code>payload</code> - variable length - Payload Data<ul> <li>Up to a maximum 184 bytes, defined by <code>MAX_PACKET_PAYLOAD</code></li> <li>Generally this is the remainder of the raw packet data</li> <li>The firmware parses this data based on the provided Payload Type</li> <li>v1.12.0 firmware and older drops packets with <code>payload</code> sizes larger than 184</li> </ul> </li> </ul>"},{"location":"packet_format/#packet-format_1","title":"Packet Format","text":"Field Size (bytes) Description header 1 Contains routing type, payload type, and payload version transport_codes 4 (optional) 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) path_length 1 Encodes path hash size in bits 6-7 and hop count in bits 0-5 path up to 64 (<code>MAX_PATH_SIZE</code>) Stores <code>hop_count * hash_size</code> bytes of path data if applicable payload up to 184 (<code>MAX_PACKET_PAYLOAD</code>) Data for the provided Payload Type <p>NOTE: see the Payloads documentation for more information about the content of specific payload types.</p>"},{"location":"packet_format/#header-format","title":"Header Format","text":"<p>Bit 0 means the lowest bit (1s place)</p> Bits Mask Field Description 0-1 <code>0x03</code> Route Type Flood, Direct, etc 2-5 <code>0x3C</code> Payload Type Request, Response, ACK, etc 6-7 <code>0xC0</code> Payload Version Versioning of the payload format"},{"location":"packet_format/#route-types","title":"Route Types","text":"Value Name Description <code>0x00</code> <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> Flood Routing + Transport Codes <code>0x01</code> <code>ROUTE_TYPE_FLOOD</code> Flood Routing <code>0x02</code> <code>ROUTE_TYPE_DIRECT</code> Direct Routing <code>0x03</code> <code>ROUTE_TYPE_TRANSPORT_DIRECT</code> Direct Routing + Transport Codes"},{"location":"packet_format/#path-length-encoding","title":"Path Length Encoding","text":"<p><code>path_length</code> is not a raw byte count. It packs both hash size and hop count:</p> Bits Field Meaning 0-5 Hop Count Number of path hashes (<code>0-63</code>) 6-7 Hash Size Code Stored as <code>hash_size - 1</code> <p>Hash size codes:</p> Bits 6-7 Hash Size Notes <code>0b00</code> 1 byte Legacy / default mode <code>0b01</code> 2 bytes Supported in current firmware <code>0b10</code> 3 bytes Supported in current firmware <code>0b11</code> 4 bytes Reserved / invalid <p>Examples:</p> <ul> <li><code>0x00</code>: zero-hop packet, no path bytes</li> <li><code>0x05</code>: 5 hops using 1-byte hashes, so path is 5 bytes</li> <li><code>0x45</code>: 5 hops using 2-byte hashes, so path is 10 bytes</li> <li><code>0x8A</code>: 10 hops using 3-byte hashes, so path is 30 bytes</li> </ul>"},{"location":"packet_format/#payload-types","title":"Payload Types","text":"Value Name Description <code>0x00</code> <code>PAYLOAD_TYPE_REQ</code> Request (destination/source hashes + MAC) <code>0x01</code> <code>PAYLOAD_TYPE_RESPONSE</code> Response to <code>REQ</code> or <code>ANON_REQ</code> <code>0x02</code> <code>PAYLOAD_TYPE_TXT_MSG</code> Plain text message <code>0x03</code> <code>PAYLOAD_TYPE_ACK</code> Acknowledgment <code>0x04</code> <code>PAYLOAD_TYPE_ADVERT</code> Node advertisement <code>0x05</code> <code>PAYLOAD_TYPE_GRP_TXT</code> Group text message (unverified) <code>0x06</code> <code>PAYLOAD_TYPE_GRP_DATA</code> Group datagram (unverified) <code>0x07</code> <code>PAYLOAD_TYPE_ANON_REQ</code> Anonymous request <code>0x08</code> <code>PAYLOAD_TYPE_PATH</code> Returned path <code>0x09</code> <code>PAYLOAD_TYPE_TRACE</code> Trace a path, collecting SNR for each hop <code>0x0A</code> <code>PAYLOAD_TYPE_MULTIPART</code> Packet is part of a sequence of packets <code>0x0B</code> <code>PAYLOAD_TYPE_CONTROL</code> Control packet data (unencrypted) <code>0x0C</code> <code>PAYLOAD_TYPE_OTA</code> OTA-over-LoRa firmware distribution <code>0x0D</code> reserved reserved <code>0x0E</code> reserved reserved <code>0x0F</code> <code>PAYLOAD_TYPE_RAW_CUSTOM</code> Custom packet (raw bytes, custom encryption)"},{"location":"packet_format/#payload-versions","title":"Payload Versions","text":"Value Version Description <code>0x00</code> 1 1-byte src/dest hashes, 2-byte MAC <code>0x01</code> 2 Future version (e.g., 2-byte hashes, 4-byte MAC) <code>0x02</code> 3 Future version <code>0x03</code> 4 Future version"},{"location":"pair_4p6_300us_validation/","title":"SF7/62.5 + SF8/500: 4.6 slow chirps, 0.3 ms reserve","text":"<p>User-requested follow-up to the original pair test. Completed 2026-09-15 00:21:27\u201300:23:52 UTC (September 14 local time).</p>"},{"location":"pair_4p6_300us_validation/#result","title":"Result","text":"Profile Requested dwell Stationary control Scanning received Slow: SF7 / 62.5 kHz 9.421 ms, approximately 4.6 chirps 100/100 97/100 Fast: SF8 / 500 kHz 21.847 ms, approximately 42.67 chirps 100/100 100/100 <p>Full scan: 197/200 (98.5%), not lossless. All three misses were slow-profile timeouts with no device error and the chip still in RX. The collector completed every scheduled probe, with no RF retry, retune/reset on a miss, or early stop. The two controls plus the scan contain 400 unique probes; each fixed transmitter acknowledged exactly 200 packets. There were no USB result replays.</p> <p>This is one finite sample. It does not establish that 4.6 is inherently worse than 4.1 or better than 5.1, nor identify the cause of the three losses.</p>"},{"location":"pair_4p6_300us_validation/#timing-and-unchanged-conditions","title":"Timing and unchanged conditions","text":"<ul> <li>Reserve: 300 us; nominal switching allowance: 600 us per hop. Neither is an   added settling delay. Nominal cycle: 9.421 + 21.847 + 1.200 = 32.468 ms.</li> <li>Actual switching across 3,957 hops: 0.582 ms mean, 0.827 ms maximum.   Direction means: 0.586 ms toward slow, 0.578 ms toward fast.</li> <li>Five-second RX-only switching window: 0.559 ms mean, 0.779 ms maximum.</li> <li>Non-packet-held cycle: 32.428 ms mean, 34.242 ms maximum. These samples can   still include USB/loop scheduling overruns; the reserve is not a hard bound.</li> <li>Observed non-held dwell means: slow 9.426 ms, fast 21.855 ms; maxima 10.480   and 23.474 ms respectively. No per-loss timing trace was collected.</li> <li>Successful-packet mean SNR: slow +12.27 dB, fast +13.47 dB; mean RSSI:   -20.87 and -18.99 dBm. These remain strong-signal lab conditions.</li> </ul> <p>Same V4 RX, RAK4631 slow TX and T1000-E/LR1110 fast TX; 909.5/910.5 MHz, CR4/5, explicit header, CRC, 32-symbol preambles, 16-byte synthetic payloads, -9 dBm chip TX power, normal RX gain 0x94, randomized interleaving and 10\u2013180 ms arrival delays. Only one transmitter sends at a time. Each TX configures once; every packet has zero frequency/modulation writes.</p> <p>The single-pass production guarded switching path uses warm XOSC and buffered 8 MHz SPI. Each hop issued exactly one frequency and one modulation command, with one optimized RX restart. No double writes, detours, rollback, added settling, off-channel acceptance, cache errors, RX errors or retune failures. As before, this is a small HIL application, not full production UI/network load.</p>"},{"location":"pair_4p6_300us_validation/#verification-and-artifacts","title":"Verification and artifacts","text":"<p>Only the V4 application was updated. Exact USB identity/MAC, idle ownership and existing partition metadata were checked before writing. The nRF52 transmitter images, bootloaders, SoftDevices, gateway and unrelated radios were not flashed. All three test radios were rebooted and verified idle afterward; HIL firmware was left installed. ModemManager was restored active, gateway and host CLI services are active, and the previously paused memory soak remains inactive.</p> <ul> <li>Raw capture, SHA-256   <code>1c2e0eae3f304fcaeb6addfeef4f2f09a3c2bec8d78c60d3f151c952d0f6d5f5</code>.</li> <li>Independent offline validation   checks complete samples, unique sequences, sender lifetime counts, actual   RX frequency/SF/BW/payload, command counts, policies and idle cleanup.</li> <li>Manifest records the   receiver image/source hashes and prior transmitter-manifest hash. Bundle   SHA-256 <code>fb7a08536ed06e36cf7d5c29babbe2affb30183de05918c4db271b98b796e579</code>.</li> <li>Remote records remain under   <code>/home/mikec/hwtest/runs/pair-sf8-32-4p6-300us-20260914</code>.</li> <li>Receiver build passed. HIL host regression suite: 64/64 passed; new plan   guards and the exact dwell/budget arithmetic are covered. Python compile and   scoped whitespace checks passed. Collector/wrapper exit zero.</li> </ul> <p>No production timing defaults changed, and no commit or push was made.</p>"},{"location":"pair_preamble32_validation/","title":"SF7/62.5 + SF8/500, fast switching and preamble 32","text":"<p>User-requested hardware validation, 2026-09-14. This is a finite HIL experiment, not a production reliability guarantee. No production timing defaults or automatic-preamble overrides are changed by this test.</p>"},{"location":"pair_preamble32_validation/#fixture-and-method","title":"Fixture and method","text":"<ul> <li>Heltec V4 receiver, USB serial <code>44:1B:F6:69:CF:98</code>, normal chip RX gain (0x94).</li> <li>RAK4631 <code>9AB3B64C641BA927</code>: stationary transmitter at 909.5 MHz, SF7/62.5 kHz.</li> <li>T1000-E/LR1110 <code>34A9141999729D5D</code>: stationary transmitter at 910.5 MHz, SF8/500 kHz.</li> <li>CR4/5, explicit header, CRC, 32-symbol preamble, synthetic 16-byte sequence-tagged   payloads. -9 dBm chip output. Only one transmitter sends at a time on host request.</li> <li>Each transmitter initializes its assigned settings once. RF-frequency and   modulation-command counters must remain unchanged for every TX call.</li> <li>100 fixed-channel controls per profile before scanning. Require 100/100 on   both before making a scan-timing inference.</li> <li>Three scanner settings, 100 packets per profile per setting, randomized   interleaving and 10\u2013180 ms arrival delays. A miss does not cause a retry,   retune, reset, or early end of the finite sample. The scan expectation expires   after 1000 ms, far longer than the test frame and randomized host delay.</li> </ul> Case Loop reserve (not a delay) Slow visit Fast visit 4.1-chirp floor 0 ms 8.397 ms 23.171 ms Spare time used for 5.1 slow chirps 0 ms 10.445 ms 21.123 ms Previous reserve comparison 4 ms 8.397 ms 19.171 ms <p>The 5.1 case reallocates 2.048 ms from the fast visit to the slow visit; it does not increase the nominal cycle. The 4 ms reserve is omitted from the first two cases. The theoretical switch allowance is 0.6 ms per hop; actual switching is measured, never forced to equal that allowance. Changed SF/BW requires one modulation command per hop; frequency-only cache-hit timings do not apply.</p> <p>The scheduler uses the same asymmetric two-profile visit budget and the actual production guarded <code>tuneProfile()</code> / fast RX implementation, but runs in a small RAM-only HIL application, without the full production networking/UI load. All retunes are single-pass, warm-XOSC, buffered 8 MHz SPI, zero added settling; double frequency writes, detours and rollback experiments are off. Packet/busy ownership guards are retained. Explicit 32 on both sides bypasses the historical automatic SF8/500 88-symbol rule without removing it from production.</p> <p>The selected radios already had disposable HIL firmware. Updates are application-only: matching nRF52 SoftDevice IDs/address ranges and exact USB serial/topology are checked. V4 partition metadata is read back and compared before its application-only write. No bootloader, SoftDevice, settings backup, gateway firmware or unrelated radio is changed. Prior images/captures remain.</p>"},{"location":"pair_preamble32_validation/#results","title":"Results","text":"<p>Finished all 800 unique probes, 2026-09-15 00:04:54\u201300:11:19 UTC (September 14 local time). Both stationary controls passed 100/100. All three scans completed their full 100-packet sample per profile. No scan achieved 200/200.</p> Case SF7/62.5 received SF8/500 received Total Switch mean / max Idle cycle mean / max 4.1 chirps, no loop reserve 99/100 100/100 199/200 0.581 / 0.829 ms 32.717 / 34.733 ms 5.1 chirps, no loop reserve 100/100 97/100 197/200 0.572 / 0.834 ms 32.706 / 34.978 ms 4.1 chirps, 4 ms loop reserve 97/100 99/100 196/200 0.567 / 0.836 ms 28.701 / 31.195 ms <p>Switch timing includes every successful hop during each stage, including post-reception hops. The RX-only five-second windows averaged 0.554 ms per hop. The largest observed switch was 0.836 ms: 0.6 ms is a nominal allowance, not a measured worst-case bound. Direction-specific timing is in the validated capture. Idle-cycle samples exclude packet-held visits but still include USB command/loop scheduling; their occasional roughly 2 ms overshoots are real.</p> <p>Every scan hop issued exactly one RF-frequency and one modulation command, with one optimized RX restart. There were zero added settling delays, double passes, frequency repeats, RF retries, USB result replays, device errors, retune failures, RX mode errors, cache errors or off-channel acceptances. All eight missed packets were sequence-matched RX timeouts with the receiver still in RX mode and no device error. Both transmitters acknowledged exactly 400 transmissions and zero frequency/modulation writes during every packet.</p> <p>Successful scan packets had mean SNR approximately +12.0 to +12.1 dB on the slow profile and +12.8 dB on the fast profile. Mean RSSI was approximately -20.4 to -20.7 dBm and -18.5 to -18.9 dBm, respectively. These are strong-signal bench results; the controls passed, but weak-signal performance and possible strong-signal/front-end effects are not established by this test.</p>"},{"location":"pair_preamble32_validation/#what-the-extra-chirp-changes","title":"What the extra chirp changes","text":"<p>An extra SF7/62.5 symbol is 2.048 ms, equivalent to four SF8/500 symbols. Increasing the slow dwell from 4.1 to 5.1 preserves the full-sweep budget by shortening the fast dwell, but increases the fast profile's uninterrupted blind interval. With the nominal 0.6 ms hops, the 32-symbol fast preamble's remaining time after the slow visit plus two hops falls from 6.787 to 4.739 ms (13.26 to 9.26 fast symbols), before acquisition and scheduling overruns. This is a timing-budget calculation, not an experimentally proven acquisition threshold or a per-miss trace.</p> <p>The observed 5.1 sample improved the slow result from 99 to 100, while the fast result fell from 100 to 97. This is consistent with a dwell/acquisition tradeoff; one finite sample per setting does not isolate the cause or establish a statistically reliable ranking. Simply fitting a sweep inside a preamble does not establish lossless acquisition. The 4 ms reserve is an allowance, not a sleep; retaining it also did not produce a lossless result here.</p> <p>Using genuine spare time above the 4.1 floor remains a reasonable policy to investigate, but allocation must protect both profiles' acquisition/return budgets and measured switching/scheduling overruns. Do not automatically spend all of the reserve on longer slow visits, or treat the historic 88-symbol rule as disproven by this nearly-lossless sample. No production defaults or warning formula were changed by this hardware-test turn.</p>"},{"location":"pair_preamble32_validation/#capture-integrity-deployment-and-cleanup","title":"Capture integrity, deployment and cleanup","text":"<ul> <li>Raw capture: profile_pair_sf8_32_results.json,   SHA-256 <code>3472883ade89494b64657486efd1645a04b0a3bebfd0a2e31bbf914341ad792f</code>.</li> <li>Independent offline checks: profile_pair_sf8_32_validated.json.   Checks all 800 unique sequences, 100/profile/phase, sender lifetime counts,   actual RX frequency/SF/BW/payload identity, command counts, policies and cleanup.</li> <li>Manifest records source and image hashes.   Bundle SHA-256 <code>d6cb9ff36be109af8906eddbbe8a4657ca793d1351ec4bf50ebbd4909eed2bba</code>.   Local bundle is <code>out/pair-sf8-32-20260914</code>; remote capture remains under   <code>/home/mikec/hwtest/runs/pair-sf8-32-20260914</code>.</li> <li>Initial RAK USB reset returned EPROTO before any firmware write. The preserved   pre-write record   has an empty writes list. Inspection confirmed the exact RAK serial/topology   in its documented CDC-only bootloader PID 0x002A. Deployment was revised to   accept that identity (and reset-time disconnect only after exact bootloader   re-enumeration); no permission check or board-identity check was bypassed.   The revision hash and all three successful application-only writes are saved   in the deployment records. No bootloader or SoftDevice was replaced.</li> <li>All three radios were rebooted and live-verified idle, with test firmware left   installed. ModemManager was restored active; gateway and host CLI services   remained active. The preexisting memory soak remains inactive. No unrelated   radio was flashed. Wrapper exit was zero.</li> <li>All three HIL firmware builds passed, run sequentially. The HIL host regression   suite passed 63/63 tests, including the new plan and packet-policy tests.   Python compile checks and scoped <code>git diff --check</code> passed. No commit or push.</li> </ul>"},{"location":"pair_preamble32_validation/#follow-up","title":"Follow-up","text":"<p>The requested 4.6-chirp / 0.3 ms reserve follow-up completed 197/200 scanning packets: slow 97/100, fast 100/100, after fresh 100/100 controls on both profiles. Its captures are separate from this run.</p>"},{"location":"payloads/","title":"Payload Format","text":"<p>Inside each MeshCore Packet is a payload, identified by the payload type in the packet header. The types of payloads are:</p> <ul> <li>Request, response, and plain text (<code>0x00</code>-<code>0x02</code>).</li> <li>Acknowledgment and node advertisement (<code>0x03</code>-<code>0x04</code>).</li> <li>Group text and group datagram (<code>0x05</code>-<code>0x06</code>).</li> <li>Anonymous request and returned path (<code>0x07</code>-<code>0x08</code>).</li> <li>Trace, multipart, control, and OTA (<code>0x09</code>-<code>0x0C</code>).</li> <li>Custom raw data (<code>0x0F</code>).</li> </ul> <p>This document describes the shared payload envelopes implemented by the core. Application-specific request, response, control, and custom bodies can add their own formats.</p> <p>NOTE: all 16 and 32-bit integer fields are Little Endian.</p>"},{"location":"payloads/#important-concepts","title":"Important concepts:","text":"<ul> <li>Node hash: the first byte of the node's public key</li> </ul>"},{"location":"payloads/#node-advertisement","title":"Node advertisement","text":"<p>This kind of payload notifies receivers that a node exists, and gives information about the node</p> Field Size (bytes) Description public key 32 Ed25519 public key of the node timestamp 4 unix timestamp of advertisement signature 64 Ed25519 signature of public key, timestamp, and app data appdata rest of payload optional, see below <p>Appdata</p> Field Size (bytes) Description flags 1 specifies which of the fields are present, see below latitude 4 (optional) decimal latitude multiplied by 1000000, integer longitude 4 (optional) decimal longitude multiplied by 1000000, integer feature 1 2  (optional) reserved for future use feature 2 2  (optional) reserved for future use name rest of appdata name of the node <p>Appdata Flags</p> Value Name Description <code>0x01</code> is chat node advert is for a chat node <code>0x02</code> is repeater advert is for a repeater <code>0x03</code> is room server advert is for a room server <code>0x04</code> is sensor advert is for a sensor server <code>0x10</code> has location appdata contains lat/long information <code>0x20</code> has feature 1 Reserved for future use. <code>0x40</code> has feature 2 Reserved for future use. <code>0x80</code> has name appdata contains a node name"},{"location":"payloads/#acknowledgement","title":"Acknowledgement","text":"<p>An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the \"extra\" payload (see Returned Path) instead of as a separate acknowledgement packet. Current <code>CLI_DATA</code> commands do not cause acknowledgement responses, neither discrete nor extra; their text reply is the application-level result. Repeaters still ACK the legacy plain-text form before processing it.</p> <p>Repeater remote CLI keeps one volatile copy of the most recently completed reply, keyed by the authenticated sender, request timestamp, and command text. Repeating that same logical request re-sends the text reply without executing the command again. A retry must therefore preserve the original timestamp and command text. The cache is cleared by reboot and replaced by the next completed remote command; commands that intentionally produce no text reply remain silent.</p> Field Size (bytes) Description checksum 4 CRC checksum of message timestamp, text, and sender pubkey"},{"location":"payloads/#returned-path-request-response-and-plain-text-message","title":"Returned path, request, response, and plain text message","text":"<p>Returned path, request, response, and plain text messages are all formatted in the same way. See the subsection for more details about the ciphertext's associated plaintext representation.</p> Field Size (bytes) Description destination hash 1 first byte of destination node public key source hash 1 first byte of source node public key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted message, see subsections below for details"},{"location":"payloads/#returned-path","title":"Returned path","text":"<p>Returned path messages provide a description of the route a packet took from the original author. Receivers will send returned path messages to the author of the original message.</p> Field Size (bytes) Description path descriptor 1 low 6 bits are the hash count; high 2 bits encode hash size minus one path count \u00d7 size encoded node-hash prefixes, each 1-3 bytes; the four-byte code is reserved extra type 1 low nibble is the bundled payload type, such as acknowledgment or response; high nibble is reserved extra rest of data extra, bundled payload content, follows same format as main content defined by this document"},{"location":"payloads/#request","title":"Request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) request data rest of payload application-defined request payload body <p>For the common chat/server helpers in <code>BaseChatMesh</code>, the current request type values are:</p> Value Name Description <code>0x01</code> get stats get stats of repeater or room server <code>0x02</code> keepalive keep-alive request used for maintained connections"},{"location":"payloads/#get-stats","title":"Get stats","text":"<p>Gets information about the node, possibly including the following:</p> <ul> <li>Battery level (millivolts)</li> <li>Current transmit queue length</li> <li>Current free queue length</li> <li>Last RSSI value</li> <li>Number of received packets</li> <li>Number of sent packets</li> <li>Total airtime (seconds)</li> <li>Total uptime (seconds)</li> <li>Number of packets sent as flood</li> <li>Number of packets sent directly</li> <li>Number of packets received as flood</li> <li>Number of packets received directly</li> <li>Error flags</li> <li>Last SNR value</li> <li>Number of direct route duplicates</li> <li>Number of flood route duplicates</li> <li>Number posted (?)</li> <li>Number of post pushes (?)</li> </ul>"},{"location":"payloads/#get-telemetry-data","title":"Get telemetry data","text":"<p>Not defined in <code>BaseChatMesh</code>. Sensor- and application-specific request payloads may be implemented by higher-level firmware.</p>"},{"location":"payloads/#get-telemetry","title":"Get Telemetry","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-minmaxave-sensor-nodes","title":"Get Min/Max/Ave  (Sensor nodes)","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-access-list","title":"Get Access List","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-neighbors","title":"Get Neighbors","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-owner-info","title":"Get Owner Info","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#response","title":"Response","text":"Field Size (bytes) Description content rest of payload application-defined response body <p>Response contents are opaque application data. There is no single generic response envelope beyond the encrypted payload wrapper shown above.</p>"},{"location":"payloads/#plain-text-message","title":"Plain text message","text":"Field Size (bytes) Description timestamp 4 send time (unix timestamp) txt_type + attempt 1 upper six bits are txt_type (see below), lower two bits are attempt number (0..3) message rest of payload the message content, see next table <p>txt_type</p> Value Description Message content <code>0x00</code> plain text message the plain text of the message <code>0x01</code> CLI data CLI command OR reply text <code>0x02</code> signed plain text message first four bytes is sender pubkey prefix, followed by plain text message <code>0x03</code> CLI command (since v1.18+) CLI command text (explicit) <p>For a room post, companion firmware uses its own monotonic clock for the on-air timestamp and preserves that timestamp across application retries. Room servers track post timestamps separately from login, request, and CLI traffic. They also remember recent accepted posts by sender, timestamp, and text: an exact retry is ACKed again without storing a duplicate, while stale or same-timestamp mismatches are rejected.</p>"},{"location":"payloads/#anonymous-request","title":"Anonymous request","text":"Field Size (bytes) Description destination hash 1 first byte of destination node public key public key 32 sender's Ed25519 public key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted message, see below for details"},{"location":"payloads/#room-server-login","title":"Room server login","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) sync timestamp 4 sender's \"sync messages SINCE x\" timestamp password rest of message password for room"},{"location":"payloads/#repeatersensor-login","title":"Repeater/Sensor login","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) password rest of message password for repeater/sensor"},{"location":"payloads/#repeater-regions-request","title":"Repeater - Regions request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) req type 1 0x01 (request sub type) reply path len 1 path len for reply reply path (variable) reply path"},{"location":"payloads/#repeater-owner-info-request","title":"Repeater - Owner info request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) req type 1 0x02 (request sub type) reply path len 1 path len for reply reply path (variable) reply path"},{"location":"payloads/#repeater-clock-and-status-request","title":"Repeater - Clock and status request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) req type 1 0x03 (request sub type) reply path len 1 path len for reply reply path (variable) reply path"},{"location":"payloads/#group-text-message","title":"Group text message","text":"Field Size (bytes) Description channel hash 1 first byte of SHA256 of channel's shared key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted message, see below for details <p>The plaintext contained in the ciphertext matches the format described in plain text message. Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be <code>0x00</code> because it is a \"plain text message\". The message will be of the form <code>&lt;sender name&gt;: &lt;message body&gt;</code> (eg., <code>user123: I'm on my way</code>).</p> <p>The sender name is unverified message text. Group messages contain no sender signature, so any channel-key holder can choose any sender name.</p>"},{"location":"payloads/#group-datagram","title":"Group datagram","text":"Field Size (bytes) Description channel hash 1 first byte of SHA256 of channel's shared key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted data, see below for details <p>The data contained in the ciphertext uses the format below:</p> Field Size (bytes) Description data type 2 Identifier for type of data. (See number_allocations.md) data len 1 byte length of data data rest of payload (depends on data type)"},{"location":"payloads/#control-data","title":"Control data","text":"Field Size (bytes) Description flags 1 upper 4 bits is sub_type data rest of payload typically unencrypted data"},{"location":"payloads/#discover_req-sub_type","title":"DISCOVER_REQ (sub_type)","text":"Field Size (bytes) Description flags 1 0x8 (upper 4 bits), prefix_only (lowest bit) type_filter 1 bit for each ADV_TYPE_* tag 4 randomly generate by sender since 4 (optional) epoch timestamp (0 by default)"},{"location":"payloads/#discover_resp-sub_type","title":"DISCOVER_RESP (sub_type)","text":"Field Size (bytes) Description flags 1 0x9 (upper 4 bits), node_type (lower 4) snr 1 signed, SNR*4 tag 4 reflected back from DISCOVER_REQ pubkey 8 or 32 node's ID (or prefix)"},{"location":"payloads/#trace","title":"Trace","text":"<p>Trace packets use direct routing. Their normal direct-path header is empty; instead, the intended route follows a fixed nine-byte trace header in the payload. Each forwarding node appends its received SNR multiplied by four to the packet's route-accumulator field.</p> Field Size (bytes) Description tag 4 Sender-selected trace identifier. auth code 4 Application-defined authentication/correlation value. flags 1 Low two bits encode the route hash size. Current senders use the legacy <code>1 &lt;&lt; value</code> interpretation (1, 2, 4, or 8 bytes); receivers also accept the packed 1-4-byte interpretation where it is unambiguous. route rest Concatenated node-hash prefixes for the requested direct route. <p>At the destination, the application receives the tag, auth code, flags, accumulated SNR bytes, and original route bytes. Trace therefore differs from a normal direct packet whose path is carried entirely in the packet route field.</p>"},{"location":"payloads/#multipart","title":"Multipart","text":"<p>The first payload byte identifies the inner payload and how many packets remain:</p> Field Size (bytes) Description remaining + type 1 Upper nibble is the remaining-packet count; lower nibble is the inner payload type. inner data rest Data for the inner payload type. <p>The core currently creates and consumes multipart acknowledgments. For that form, the low nibble is <code>0x03</code> and the next four bytes are the acknowledgment CRC. Other multipart inner types are reserved for application or future use.</p>"},{"location":"payloads/#ota","title":"OTA","text":"<p>An OTA payload contains one OTA protocol message and is normally sent by flood. Its message types, integrity fields, and transfer state are defined in the OTA-over-LoRa protocol. Builds without OTA support can still relay an opaque OTA packet when their routing policy permits it.</p>"},{"location":"payloads/#custom-packet","title":"Custom packet","text":"<p>Custom packets have no defined format.</p>"},{"location":"pr7_review_validation/","title":"PR #7 review and validation","text":"<p>Validated on 2026-09-10 against integration commit <code>fa010196b130dee9a8a6fc6325d794e2f4fb9ede</code>, which combines base <code>01cc7b8a</code> with PR head <code>c002966c</code> and the review fixes. This includes the stacked ESP32 memory changes already present in PR #7.</p>"},{"location":"pr7_review_validation/#review-fixes","title":"Review fixes","text":"<ul> <li>Use the published ExpressLRS Linkflow calibration,   expose 17\u201330 dBm, and retain the fixed +2 dBm radio drive and correct RF output   after radio recovery. Propagate startup and radio-setting failures.</li> <li>Keep Linkflow LoRa OTA enabled, as intended by the added repeater target.</li> <li>Preserve stored ACLs and flood filters when allocation fails. Release owned   buffers and prevent accidental shallow copies of their owners.</li> <li>Release heap OTA workspaces after self-serving windows; retain them for active   transfers, manual staging, folder operations, and pending application. Service   cleanup on Companions and reset staged-resume flags when a context disappears.</li> <li>Count dynamically allocated clients, filters, and OTA workspaces in the RAM   budget. Respect explicit OTA storage ownership in PlatformIO flags.</li> </ul>"},{"location":"pr7_review_validation/#automated-validation","title":"Automated validation","text":"<ul> <li><code>pio test -e native -e native_kiss_modem</code>: 1,393/1,393 cases passed.</li> <li>Real C++ radio-power, heap-context, ACL persistence/CLI, and shared OTA queue   tests passed. The applicable radio-power, heap-context, and shared-queue tests   also passed on Linux with AddressSanitizer and UndefinedBehaviorSanitizer.</li> <li>Display/inbox, radio receive, static DRAM, and runtime RAM regression tests   passed. ACL allocation-failure coverage verifies that stored clients survive.</li> <li>Sequential firmware builds and their memory gates passed for:   <code>GEPRC_Linkflow_900_repeater</code>, <code>Heltec_v2_companion_radio_ble</code>,   <code>Tbeam_SX1262_repeater_observer_mqtt</code>,   <code>heltec_v4_r8_repeater_observer_mqtt</code>, <code>RAK_4631_repeater</code>, and   <code>SenseCapIndicator-LoRa_companion_radio_full</code>.</li> </ul>"},{"location":"pr7_review_validation/#indicator-hardware-validation","title":"Indicator hardware validation","text":"<p>The original SenseCAP Indicator LoRa with 8 MiB flash and 8 MiB octal PSRAM was reached through the MercerWoodMesh Pi over Wi-Fi. Its MAC, public identity, board reply, and existing partition layout were checked before updating. USB interfaces were absent, so this run does not qualify USB behavior.</p> <p>The Full profile was applied to <code>SenseCapIndicator-LoRa_comp_radio_usb_wifi</code>. The exact application is 2,149,208 bytes:</p> <ul> <li>Application SHA-256:   <code>7a2b11e731f946af79d1104818c7993d3897e6d8ec1f0121d27284c0f0c8c665</code></li> <li>ELF SHA-256, also verified in the application descriptor:   <code>24e60c7785a7aefe3fb0536b0b595bf19e1264e4d5f100d201290dc95eb1761a</code></li> </ul> <p>This direct profile build uses the repository's default <code>v1.17.1</code> version text and <code>14 Aug 2026</code> build-date text; the hashes above identify the tested image.</p> <p>The Wi-Fi updater returned HTTP 200 and booted the application in <code>app1</code> at <code>0x400000</code>. The previous application remains in <code>app0</code> at <code>0x10000</code>; the partition table, NVS, and SPIFFS were not rewritten. Public identity, radio parameters, and USB logging preference matched their pre-update values.</p> <p>The existing Companion stress harness, using a TCP socket adapter, completed 100 persistent cycles and 100 reconnects in 109.9 seconds: 501 requests and 501 validated responses, with no discarded bytes, malformed frames, or device error flags. Device info, time, storage, and core statistics were exercised. The text terminal exposed all four display-power controls and <code>display.inbox</code>. The OTA folder service issued a valid <code>COUNT</code> request, received an empty-folder reply, and returned to its disconnected state after the client closed.</p> <p>After these checks, four memory snapshots showed 69,548\u201369,996 bytes of free internal heap and a 61,428-byte largest block. PSRAM availability stayed at 6,408,731 bytes. Final uptime was 262 seconds, with zero error flags and an empty outbound queue. This is a short regression check, not a long-term soak. Raw baseline, upload, stress, and final-state records are retained on the Pi under <code>/home/mikec/hwtest/runs/pr7-review/</code>.</p> <p>No Linkflow module or RF power meter was available in this run. Linkflow power calibration is supported by the pinned upstream table and executable driver tests, not a physical RF output measurement. The Indicator's ESP32-S3 does not exercise the classic ESP32 heap-OTA default; host tests and classic ESP32 builds cover that path. Physical display readability was not inspected.</p>"},{"location":"preamble_detection_investigation/","title":"Off-channel preamble investigation","text":"<p>Measured 2026-09-14. The SF8 off-channel preamble indication reproduces with a stationary, fully initialized receiver, without profile hopping or fast RX reuse. Both boards reproduce it when their transmitter/receiver roles are reversed. This is evidence of transmitter-associated off-channel detection in this close-range bench setup, not evidence that the channel jump needs more settling time.</p> <p>The earlier SF8 scan's long software guard explains its missed listening opportunity. The earlier SF6 scan miss remains unresolved: its trace had no preamble indication or guard hold. No production guard or acquisition policy was changed during this investigation.</p>"},{"location":"preamble_detection_investigation/#controlled-experiment","title":"Controlled experiment","text":"<ul> <li>XIAO ESP32-S3 + WIO SX1262 (COM31) and SenseCAP Indicator ESP32-S3 LoRa   (COM28). The Indicator RP2040 and RAK4631 were not modified.</li> <li>Receiver fixed at 910.000 MHz. Transmitter silent, on frequency, or offset   by +/-250, +/-500 or +/-1,000 kHz. These are offsets, not bandwidths.</li> <li>125 kHz bandwidth, SF8 or SF6, CR4/5, 32 programmed preamble symbols,   -9 dBm, one 16-byte sequence-tagged synthetic payload per transmitting case.</li> <li>Each case fully initializes both radios. RX uses ordinary <code>startReceive()</code>;   profile-switch optimization and experimental omission masks are disabled.   Buffered 8 MHz SPI remains enabled. No hops, warm-retune reuse, CAD, or   <code>isReceiving()</code> software guard runs during these controls.</li> <li>TX is prepared before RX is armed. Each receive window lasts 450 ms;   all eight cases are shuffled within each balanced round, seed 814910.   The full RX window completes even when an off-frequency packet is not   received, as expected. An on-frequency positive-control failure stops the   experiment. No RF retransmissions are used to repair a result.</li> <li>The HAL records actual outgoing <code>SetRfFrequency</code> bytes on both boards,   and the frequency word present at <code>SetTx</code>. The host verifies these words   against the requested frequencies. This checks commands sent to the chip,   not an independent measurement of the emitted RF spectrum.</li> <li>Existing IRQ replies are observed and IRQs additionally polled at a nominal   64 us interval. Events are buffered in RAM; timestamps are software   observations, not synchronized RF arrival times. Unknown payload contents   are not exported.</li> </ul> <p>The three completed matrices contain 128 windows: 112 transmitted probes and 16 silent controls. A separate initial 450 ms receiver-only smoke check was also performed. These are bounded diagnostic controls, not another 100-packets-per-channel capacity sweep.</p>"},{"location":"preamble_detection_investigation/#results","title":"Results","text":"<p>Entries below are windows with a preamble indication / tested windows. Each positive window reported one indication; latched IRQs do not count continuous detector activity or prove a valid packet.</p> Transmitter offset SF8, XIAO RX SF8, Indicator RX SF6, XIAO RX Silent 0/8 0/4 0/4 On frequency 8/8 4/4 4/4 -250 kHz 8/8 4/4 1/4 +250 kHz 8/8 4/4 0/4 -500 kHz 5/8 3/4 0/4 +500 kHz 1/8 3/4 0/4 -1,000 kHz 5/8 4/4 0/4 +1,000 kHz 5/8 3/4 0/4 <p>All 16 on-frequency probes delivered valid payloads. None of the 96 off-frequency probes delivered a valid payload. No silent control detected a preamble. Completed windows ended in RX mode with zero device errors; there were no foreign valid payloads or trace overflows.</p> <p>Most off-frequency detections stopped at <code>PreambleDetected</code> (0x0004). Four progressed further but failed CRC (<code>seen_irq=0x0056</code>: preamble, header, RxDone, CRC error): two at +250 kHz with XIAO RX, and one each at +250 and +1,000 kHz with Indicator RX. Therefore HeaderValid alone would not prove that these off-frequency indications are legitimate traffic.</p> <p>In forward SF8 on-frequency controls, instantaneous RSSI at the first preamble was -42 to -41 dBm; at +/-250 kHz it was -91 to -88 dBm. These are instantaneous receiver readings, not calibrated measurements of transmitted leakage or a sensitivity test. Board positions and attenuation were not systematically varied. Reversing roles reproduces the behavior but does not isolate its physical path.</p>"},{"location":"preamble_detection_investigation/#what-this-explains","title":"What this explains","text":"<p>The earlier SF8 four-channel scan missed probe 13 on 910.250 MHz after detecting a bare preamble while tuned to 910.000 MHz. The existing <code>CustomSX1262::isReceiving()</code> guard allowed 91 ms for preamble progression, consistent with the observed 92.257 ms from first preamble observation to the stale-bit clear. That produced approximately 102 ms total occupancy on the wrong channel and a 135.145 ms target-channel revisit gap. The programmed 32-symbol preamble lasted only 65.536 ms.</p> <p>The delayed retune itself took 550 us. These controls reproduce the suspect off-frequency indication with no retunes at all. Together the evidence supports off-channel acquisition plus a long guard hold as the SF8 failure mechanism, rather than slow SPI or a demonstrated need for a longer post-jump delay. It does not independently prove the RF source of that one historical scan event.</p> <p>The controlled-transmitter association and quiet silent controls make random ambient RF alone an inadequate explanation of the repeated bench result. Exact RF cause remains unmeasured: receiver selectivity/false acquisition, transmitter spectral leakage, and coupling between the nearby boards are not separated by these tests. No spectrum-analyzer capture or calibrated attenuation sweep was performed. Increasing channel spacing is not established as a fix: SF8 indications also occurred at +/-1 MHz.</p> <p>The earlier SF6 miss had no observed nonzero IRQ or guard hold. The four successful stationary SF6 positive controls show the fixed-channel link works, but do not establish the acquisition time needed after a retune. These small, differently sized samples are not packet-error rate estimates or proof of a zero-loss channel count.</p>"},{"location":"preamble_detection_investigation/#follow-up-candidates-not-implemented-fixes","title":"Follow-up candidates, not implemented fixes","text":"<p>Semtech documents that false LoRa detections can occur and describes <code>SetLoRaSymbNumTimeout</code> as validating reception over multiple symbols before continuing when the modem locks. This is a candidate to investigate, not a drop-in verified fix. Its behavior in continuous RX and through each retune must be measured. See section 13.4.9, page 99 of the Semtech SX1261/2 datasheet, revision 2.2.</p> <p>Useful next experiments would qualify/revalidate preambles before granting a long scan hold, and repeat the controls with lower signal levels or increased physical isolation. Any candidate must preserve legitimate weak signals and long preambles. Blindly shortening the current guard, or requiring only a header indication, is not justified by these results. No production radio change was made in this diagnostic turn.</p>"},{"location":"preamble_detection_investigation/#reproduction-provenance-and-checks","title":"Reproduction, provenance, and checks","text":"<p>See the stationary diagnostic instructions. The same diagnostic firmware binaries were used for all three matrices. Base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus local changes; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL targets built and uploaded successfully. All 29 selected host/native tests passed after testing.</p> <p>Raw results and SHA-256:</p> <ul> <li>Forward SF8, eight rounds:   <code>e876a8b1727c5584aa67cb4fcdcae5ca30701e90f7ed998b5df36c37d245f7b0</code></li> <li>Reverse SF8, four rounds:   <code>83b576544f807c6b81ee83a7db487137ef2584cb4981e475c7e7ac50e4fa2363</code></li> <li>Forward SF6, four rounds:   <code>bdb65b4e23d8b05c8523cec092533509021f878518a38523b02135b810da991b</code></li> <li>Aborted initial SF6 launch   is retained: no trials and no RF probes. A host reboot-command quoting   failure left the diagnostic image unready after the preceding run. After   correcting the command and rebooting both boards, the complete SF6 matrix   was recorded to the separate <code>run2</code> path. A subsequent host cleanup change   ensures an already-opened receiver port is closed if opening TX fails.</li> </ul> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>f89da2a2e542df481ff6c26d2492dcc46db8794b5549d3b4f73217767130a21d</code></li> <li>Indicator: <code>e58207c7e63de625bee2d4e4400eb934b2737f51e8babc7c1fddd85c48efdda6</code></li> </ul>"},{"location":"preamble_detection_investigation/#device-handoff","title":"Device handoff","text":"<p>Fresh full 8 MiB backups were taken and separately verified before flashing, in the private current-user MeshCore backup directory. No backup contents or identity/channel secrets are in the diagnostic results.</p> <ul> <li>XIAO backup: <code>5e5825b625a0e6ded65aafa72658eb3b15b466316a9efe8239b2f09de9418e63</code></li> <li>Indicator backup: <code>6f834296d4e29e4fe17297aad0a9e2bf2adcf0a1391cf645de1bc51aebfd70de</code></li> </ul> <p>Both original images were restored after the controls, separately verified against the complete 8 MiB flash with matching digests, and hardware-reset. The RAK4631 and Indicator RP2040 were untouched; the XIAO soak logger was not restarted. The temporary HIL build overlay was removed. Investigation source, tests, and results were initially handed off locally before publication.</p>"},{"location":"preset_test/","title":"Temporary radio test builder","text":"<p>Choose a window and radio tuple to create a shareable temporary-radio test URL.</p> <p>MeshCore \u00b7 default 48-hour temporary preset test</p> Scheduled Starts in \u2014 \u2014 Start End Display time zone Need to leave the test early? <p>Send this command to return to your saved radio settings in one minute:</p> Copy leave command KeyMind firmware and advanced commands <p>         Use these only if your firmware supports the listed commands or you need         dual-radio operation, scheduling, or clock correction.       </p> <p>Firmware schedule epochs: </p> <p>         Primary scheduling requires a Simple Repeater build. Companion         <code>tempradio2</code> and <code>tempradioat2</code> require dual-profile         firmware. If a command is unknown, use only the method your installed         firmware supports.       </p> <p>         Enter the test times in the selected time zone and choose the radio         tuple. The generated URL converts the times to exact UTC instants, keeps         the date punctuation readable, and keeps <code>tz</code> so the page         displays them in the organizer's local time zone.           </p> Start date and time End date and time Selected time zone Detecting browser time zone\u2026                    Use browser time zone                  <p>                 Loading time zone map\u2026               </p>                  Click a region to select its IANA time zone. The initial selection                 comes from <code>tz=</code> when present; otherwise it uses your                 browser's time zone. Map design inspired by                 zones.arilyn.cc;                 boundaries from                 Timezone Boundary Builder                 and \u00a9 OpenStreetMap contributors.                Test radio profile Frequency (MHz) Bandwidth (kHz) 7.810.415.6 20.831.2541.7 62.5125250500 Spreading factor 5678 9101112 Coding-rate denominator 5678 TX output for estimate (dBm) This estimate-only value does not change the TempRadio commands. Generate test URL <p></p> <pre><code></code></pre> Copy generated URL Open generated page <p>         Advanced use: <code>start</code> and <code>end</code> also accept ISO-8601         timestamps with explicit UTC offsets or Unix epoch seconds. If         <code>tz</code> is omitted, the page uses the browser's time zone. The         other URL parameters are <code>freq</code>, <code>bw</code>,         <code>sf</code>, <code>cr</code>, and estimate-only <code>tx</code>.           </p>"},{"location":"preset_test/#preset-test-title","title":"910.100 MHz /             500 kHz /             SF8 /             CR7","text":""},{"location":"preset_test/#stock-test-title","title":"Stock firmware: copy this <code>tempradio</code> command","text":"Copy tempradio command <p>           Before sending it, run <code>get radio</code> and save the result.           No clock setup is needed. Your saved settings return automatically.         </p>"},{"location":"preset_test/#continuity-plan-title","title":"Bridges and early-revert plan","text":"<p>         The test will include bridges. If the Puget Sound area experiences a         widespread power outage or loss of cellular service, we will end the         test early. A stock node's one-minute temporary test profile then ends         on that node's own saved radio settings.       </p>"},{"location":"preset_test/#save-settings-title","title":"Before changing a radio","text":"<p>         Run <code>get radio</code> and record the saved primary tuple. Both         primary TempRadio methods return to that saved tuple; they do not store         a return tuple inside the temporary command. On a Companion, also run         <code>get radio2</code> and <code>get radio2.cross</code> so you can restore         any non-default secondary-profile setup.       </p>"},{"location":"preset_test/#clock-check-title","title":"Check the node clock before scheduling","text":"<p>         The primary <code>tempradioat</code> and Companion         <code>tempradioat2</code> schedulers use UTC Unix time. Run         <code>clock</code> on every node that will be scheduled and compare it         with the browser UTC time below. It should agree to within about a minute.         A wrong clock can start late, start immediately, or cause the schedule to         be rejected.       </p> Browser UTC now \u2014 Browser Unix time \u2014 Node clock reported by <code>clock</code> (UTC, optional)              Paste the node's <code>clock</code> reply immediately after it arrives.             The firmware form <code>02:42 - 22/9/2026 UTC</code> is also accepted.             Leave this blank to keep the normal UTC schedule epochs unchanged.            Apply clock conversion <p>         No node-clock correction is applied. Scheduled commands use the normal UTC epochs.       </p> <p>         This changes only the absolute <code>tempradioat</code> and         <code>tempradioat2</code> epochs shown on this page; it does not issue a         clock-setting command. The correction is for this node and this open page         only: it is never added to generated URLs, and is cleared on reload. If         the node clock later syncs or jumps, delete and queue the schedule again.       </p> Remote admin session <p>             In a MeshCore client that supplies the sender timestamp, sync and             then verify:           </p> <pre><code>clock sync\nclock</code></pre> Local USB or browser console <p>Copy this fresh, run it immediately, and then verify with <code>clock</code>:</p> <pre><code>time 0\nclock</code></pre> Copy current clock command If the clock is ahead and cannot move backward <p>             If setting the correct time returns <code>ERR: clock cannot go backwards</code>,             run the command below. It resets the clock to an older fallback date and             reboots the node immediately, so it sends no reply. After the node reconnects,             copy and run the fresh local clock command above, verify with <code>clock</code>,             and then add the Companion <code>tempradioat2</code> schedule again. The             reboot clears any pending scheduled entries.           </p> <p>             If resetting or correcting this remote node's clock is not safe, leave             it unchanged and use the optional node-clock conversion above instead.           </p> <pre><code>clkreboot</code></pre> Copy clock reset command <p>         The Companion schedule must be queued while both its start and end are         in the future and within the firmware's roughly 24-day scheduling         horizon. Scheduled entries are held in RAM and disappear if the node         reboots.       </p>"},{"location":"preset_test/#join-now-title","title":"Companion: use both frequencies","text":"<p>         These commands become available one hour before the official start.         Their timeout shrinks so the Companion returns at the same end time.       </p> Companion using both frequencies Dual profile Copy commands <p> <code>rxtx</code> permits transmission on the second profile;             <code>radio2.cross on</code> copies ordinary Companion traffic across             the primary and temporary profiles.           </p>"},{"location":"preset_test/#schedule-title","title":"Schedule a supported node in advance","text":"<p>         A Simple Repeater build can schedule its primary radio with         <code>tempradioat</code>. A Companion can instead schedule its second         profile with <code>tempradioat2</code>. Both commands use the exact UTC         epochs below, switch at the common start, and restore saved settings at         the common end. A node-clock conversion above replaces only those command         epochs with its per-node translated values. Room-server and sensor roles         use the stock join command above instead.       </p> Room server or sensor No advance schedule <p>             Use the stock <code>tempradio</code> command above after             its setup window opens.           </p> Simple Repeater primary radio Primary schedule <pre><code></code></pre> Copy schedule commands <p>             This is available only on a Simple Repeater build with primary             scheduled-radio support. It changes the primary tuple at the start             and restores the saved tuple at the end. If <code>get tempradioat</code>             returns <code>Error: unsupported</code>, use the stock join command             above instead.           </p> Companion using both frequencies Dual-profile schedule <pre><code></code></pre> Copy schedule commands <p>             Crossing is saved independently and remains <code>on</code> after the             temporary second profile ends. Restore its previous value after the             test; <code>auto</code> is the normal default.           </p>"},{"location":"preset_test/#cancel-title","title":"Cancel a schedule or adjust the timeout","text":"<p>         For a primary or Companion schedule, the <code>all</code> form removes every temporary         schedule in that family. To preserve another schedule, first run the         corresponding <code>get</code> command and replace <code>all</code> with         its displayed entry number.       </p> Stock: leave in 30 minutes <pre><code></code></pre> Copy 30-minute command <p>             This replaces the current temporary timeout with 30 minutes, then             restores the saved primary tuple automatically.           </p> Simple Repeater \u00b7 scheduled primary radio <pre><code></code></pre> Copy cancel commands <p>             Before the start, this removes the queued temporary schedule. While             it is running, it also restores the saved primary tuple after the             command reply drains.           </p> Companion \u00b7 before it starts <pre><code></code></pre> Copy cancel commands Companion \u00b7 while it is running Leave now <pre><code></code></pre> Copy restore commands <p>             If <code>get radio2.cross</code> was not <code>auto</code> before the             test, restore that recorded value instead.           </p> Leave in 30 minutes <pre><code></code></pre> Copy 30-minute commands <p>             These commands clear any absolute second-profile schedule and give             the test profile a fresh 30-minute lease. The saved second profile             returns at expiry, but crossing remains <code>on</code>; afterward,             restore the value you recorded before the test (<code>auto</code> is             the normal default).           </p>"},{"location":"preset_test/#share-title","title":"Build a temporary radio test URL","text":""},{"location":"preset_test/#radio-estimates-title","title":"Radio estimates","text":"Nominal LoRa bitrate\u2014 Estimated sensitivity\u2014 TX output used\u2014 Estimated link budget\u2014 <p>             The bitrate is the nominal LoRa physical-layer rate; usable payload             throughput is lower. Sensitivity assumes a 6 dB receiver noise figure             and the standard LoRa SNR threshold for the selected spreading factor.             Link budget is TX output minus that sensitivity, before antenna gain,             cable loss, path loss, interference, and implementation differences.           </p>"},{"location":"qr_codes/","title":"QR Codes","text":"<p>This document provides an overview of QR Code formats that can be used for sharing MeshCore channels and contacts. The formats described below are supported by the MeshCore mobile app.</p>"},{"location":"qr_codes/#add-channel","title":"Add Channel","text":"<p>Example URL:</p> <pre><code>meshcore://channel/add?name=Public&amp;secret=8b3387e9c5cdea6ac9e5edbaa115cd72\n</code></pre> <p>Parameters:</p> <ul> <li><code>name</code>: Channel name (URL-encoded)</li> <li><code>secret</code>: 16-byte secret represented as 32 hex characters</li> <li><code>region_scope</code>: Region Scope (optional, URL-encoded if provided)<ul> <li>Supported by MeshCore App v1.47.0+</li> </ul> </li> </ul>"},{"location":"qr_codes/#add-contact","title":"Add Contact","text":"<p>Example URL:</p> <pre><code>meshcore://contact/add?name=Example+Contact&amp;public_key=9cd8fcf22a47333b591d96a2b848b73f457b1bb1a3ea2453a885f9e5787765b1&amp;type=1\n</code></pre> <p>Parameters:</p> <ul> <li><code>name</code>: Contact name (URL-encoded if needed)</li> <li><code>public_key</code>: 32-byte public key represented as 64 hex characters</li> <li><code>type</code>: numeric contact type<ul> <li><code>1</code>: Companion</li> <li><code>2</code>: Repeater</li> <li><code>3</code>: Room Server</li> <li><code>4</code>: Sensor</li> </ul> </li> </ul>"},{"location":"radio_chirp_math_validation/","title":"Shared radio/radio2 chirp timing and preamble warnings","text":"<p>Historical validation record: the nominal 600 us policy described below has been replaced by the activation self-test and 10% guarded measured budget. See radio profiles for current behavior.</p> <p>Implemented in the <code>keymindCascade</code> working tree, 2026-09-14. The initial 4.1/4000-us implementation record below is retained as history; the 4.6/300-us policy update is now current. No radios were flashed or RF experiments started for either function-only change.</p>"},{"location":"radio_chirp_math_validation/#initial-implementation-scope","title":"Initial implementation scope","text":"<ul> <li>One portable timing function in <code>src/RadioProfiles.h</code> calculates both profiles   from their own SF/BW symbol times, optional dwell times and explicit budgets.</li> <li>The production dwell minimum is now 4.1 chirps on both profiles, rounded up to   a whole microsecond. The slow visit changed from 4.8 to 4.1; the old four-chirp   fast minimum changed to 4.1. The existing asymmetric scheduler may allocate   a longer fast-channel visit from the slow preamble's return deadline.</li> <li>Automatic preambles and diagnostics share the same requirement calculation.   The hot retune path computes only the requested profile, not a full diagnostic   structure or extra hardware reads.</li> <li>Round recommendations upward to multiples of eight, minimum 32. Preserve   the prior measured 88-symbol SF8/500-versus-SF7/62.5 floor.</li> <li>Warn by profile name with the recommended preamble when the requirement is   above 32 or above an explicitly selected short value. Successful radio-setting   replies include <code>WARN recommended preamble: radio=...</code> and/or <code>radio2=...</code>.   Existing explicit values are not overwritten.   Existing unsafe-airtime and infeasible-return-deadline rejection stays intact.</li> <li><code>get radio2.timing</code> / <code>get radio.timing</code> is read-only. It reports both dwell   values and requirements in <code>radio,radio2</code> order. Settings/getters and scheduling   acknowledgments include warnings; successful primary-setting responses use a   preview of the requested SF/BW, not stale live settings.</li> </ul>"},{"location":"radio_chirp_math_validation/#evidence-and-limits","title":"Evidence and limits","text":"<p>The five-radio single-pass bench received 392/400 at 5.1 chirps. The longer-dwell repeats scored 342/348 before the user stopped 6.1, and 395/400 at 7.7. They do not establish any lossless four-channel dwell. They also do not justify treating one full sweep fitting inside the preamble as proof of acquisition.</p> <p>The function retains the earlier production two-profile policy: two return opportunities on the slower channel, blind time plus sixteen acquisition symbols on the faster channel. Its 4.1 floor is the requested policy boundary, not an experimentally established detection minimum. This change requires RF qualification before describing it as a reliability improvement.</p> <p>Single-pass V4 switching peaked at 804 us including post-reception cache refresh. Indicator reached 8428 us in the prior receive-only study. The pure function can model either allowance. Per the follow-up request, runtime scheduling now uses a nominal 600 us switch / 4000 us loop budget; advisory calculations raise the switch allowance if the observed maximum exceeds 600 us. The 0.6 ms nominal value does not cover all measured switches. They do not dynamically retune the production scheduler or silently lengthen already configured preambles.</p> <p>See the formula and CLI examples.</p>"},{"location":"radio_chirp_math_validation/#verification","title":"Verification","text":"<ul> <li>Portable C++ property sweep: 1,600 SF/BW pairs (SF5 through SF12, five bandwidths   on each side), minimum dwell, rounding, automatic/diagnostic consistency and   the two-return deadline for accepted tuples.</li> <li>Exact SF10/125 symbol duration and 4.1 floor; SF6/125 comparison using 1000 us   versus 9000 us switching; reversed profile order; invalid/non-finite inputs;   explicit long/short preambles; advisory-only overrun handling.</li> <li>Production CLI tests cover warnings before delayed publication, named profiles,   both timing aliases, single-profile off, explicit short overrides, saved versus   temporary primary settings, read-only enforcement and bounded reply buffers.</li> <li>Production scan/transition harness retains packet ownership, busy deferral,   failed-retune rollback, receive restoration and oscillator-policy checks.</li> <li> <p>Native <code>test_trace_retry</code>: 63/63 tests passed, including the updated automatic   preamble expectations and profile routing/retry/scheduling tests.</p> </li> <li> <p>Host regression suites: 22/22 tests passed across chirp math, profile CLI,   scan transitions, setting contracts, temporary-reply delivery, STM32 float   formatting, local/LoRa CLI access and repeater timing integration. The CLI   fixtures include the new warning method. Windows MinGW runs the local-access   assertions without unavailable ASan/UBSan runtimes; Linux retains those flags.</p> </li> <li>Full <code>heltec_v4_repeater</code> build after the 0.6 ms follow-up: passed;   RAM 125,344 bytes, flash 1,597,789 bytes, runtime-RAM checks passed.</li> <li>Full <code>heltec_v4_companion_radio_usb</code> build after the follow-up: passed;   RAM 62,460 bytes, flash 828,589 bytes, runtime-RAM checks passed.</li> <li>The rerun passed all 22 host tests and 63 native cases, including actual   primary-setting reply dispatch (local and LoRa), requested-tuple previews,   a recommended 32-symbol preamble for an explicit 16-symbol override, and   the nominal 600 us allowance. The 4.1-symbol floor and 4000 us loop margin   remain unchanged.</li> <li><code>git diff --check</code>: passed. No firmware was uploaded and no commit or push   was made for this change.</li> </ul>"},{"location":"radio_chirp_math_validation/#automatic-46-chirp-300-us-policy-update","title":"Automatic 4.6-chirp / 300-us policy update","text":"<p>After the separate 4.6/0.3 ms hardware test, the user requested this policy in the shared production function. That sample was 197/200 (slow 97/100, fast 100/100), not evidence of lossless operation.</p> <ul> <li>Slow-profile dwell is now <code>ceil(4.6 * symbol_us)</code>; the fast floor remains   <code>ceil(4.1 * symbol_us)</code>. Slow/fast is selected by symbol duration, not profile   index (primary wins equal-symbol ties). Single-profile mode is unchanged.</li> <li>Keep 600 us per switch and use 300 us of loop reserve. Allocate the fast   visit from half the configured slow preamble duration minus the slow visit,   two switches and the reserve. The reserve is not an added delay.</li> <li>The pure calculator, automatic preamble calculation, real scheduler and   acceptance checks all use the same role-specific rounded minima. Advisory   warnings still account for measured switch overruns without rewriting   explicit preambles or persisted configuration.</li> <li>SF7/62.5 + SF8/500 with a slow preamble of 32 yields 9,421 us slow and   21,847 us fast, matching the tested plan, in either profile order.</li> <li>Preserve unsafe-airtime/short-slow-preamble rejection, eight-symbol rounding,   the 32-symbol recommendation minimum, and the historical SF8/500 88-symbol   floor. For SF7/500 paired with SF7/62.5, the automatic fast preamble changes   from 72 to 64 because the reserve is smaller. Explicit 32 remains explicit,   with the existing short-override warning.</li> </ul> <p>Verification covers 1,600 SF/BW pairs with exact role-dependent rounding and fast-dwell arithmetic, profile reversal, equal-symbol ties, larger explicit slow preambles, infeasible short slow preambles, single-profile off, long explicit visits, and advisory-only switch overruns. Production CLI checks assert the actual <code>4.60,42.67</code> chirp readout, <code>loop=300us</code>, warning values and unchanged explicit 32 on the tested SF8/500 pair. The frozen HIL plan now checks equality against the production 4.6/300-us allocation.</p> <ul> <li>Host production regression suites: 15/15 passed.</li> <li>Native production radio/routing/retry suite: 63/63 passed.</li> <li>HIL host regression suites: 64/64 passed.</li> <li>Full V4 repeater build: passed; RAM 125,344 bytes, flash 1,597,881 bytes.</li> <li>Full V4 USB companion build: passed; RAM 62,460 bytes, flash 828,657 bytes.   Both passed runtime-RAM checks; builds ran sequentially in one process.</li> <li>Scoped <code>git diff --check</code>: passed.</li> <li>No hardware upload, commit or push for this policy update.</li> </ul>"},{"location":"radio_dwell_policy_validation/","title":"Automatic dwell policy: 4.6 chirps on both profiles","text":"<p>Historical validation record: the nominal 600 us switch allowance below has been replaced by the activation self-test and a 10% guarded measured budget. See radio profiles for current behavior.</p> <p>The shared <code>RadioProfiles</code> function uses a 4.6-symbol minimum for both logical profiles of one physical transceiver, rounded upward to a whole microsecond. The slower profile is selected by symbol duration, with primary winning ties. The fast visit receives the remaining half-slow-preamble budget, subject to the same 4.6-symbol minimum. The nominal allowances are 600 us per switch and 300 us per cycle, not added delays.</p> <p>The scheduler, automatic preambles, configuration acceptance and diagnostic calculator use the same minima. Preserve explicit preambles, safe-airtime validation, too-short slow-preamble rejection, recommendation rounding to multiples of eight (minimum 32), and the existing SF8/500 versus SF7/62.5 88-symbol recommendation floor. Measured switching overruns raise advisory warnings without rewriting configured values. Single-profile RX still does not perform a scan.</p> <p>For SF7/62.5 plus SF8/500 with slow preamble 32, the allocation remains 9,421 us slow and 21,847 us fast, in either profile order. The fast visit already exceeds 4.6 fast symbols. Raising the fast minimum matters when less budget is available: equal SF7/500 profiles with slow preamble 30 no longer fit, because only 1,162 us would remain versus the new 1,178 us floor. Slow preamble 32 fits with a 1,418 us fast visit.</p>"},{"location":"radio_dwell_policy_validation/#hardware-context","title":"Hardware context","text":"<p>The preceding V4 RX / fixed RAK4631 and T1000-E TX bench used explicit 32-symbol preambles on both profiles, 100 stationary controls per profile and a complete 100/profile scan. Controls passed 100/100 each; scanning received slow 97/100 and fast 100/100 (197/200 total). Switching averaged 582 us and peaked at 827 us. Successful-packet mean SNR was +12.27/+13.47 dB. No RF retry or USB result replay was used. Radios were left idle.</p> <p>That test used the same 9,421/21,847 us windows, so the higher fast floor does not change this particular allocation. It does not establish lossless performance or qualify other SF/BW combinations. Raw capture SHA-256: <code>1c2e0eae3f304fcaeb6addfeef4f2f09a3c2bec8d78c60d3f151c952d0f6d5f5</code>. No additional RF run is required to apply the user-requested policy change.</p>"},{"location":"radio_dwell_policy_validation/#software-verification","title":"Software verification","text":"<p>The portable C++ test sweeps 1,600 SF/BW pairs and checks both 4.6-symbol minima, exact fast-window allocation, preamble/diagnostic consistency and accepted return deadlines. It also covers reversed/equal symbol times, explicit preambles, newly infeasible short settings, long requested visits, invalid parameters and advisory-only switching overruns. CLI tests exercise warnings, both timing aliases, saved/temporary configuration, persistence and bounded replies. Native integration covers routing, retries and packet ownership alongside the timing model.</p> <p>Verification completed on 2026-09-14 (local date):</p> <ul> <li>Exact commit snapshot: 24/24 host production tests passed, including primary   CLI settings, shared timing, command dispatch, persistence and reply checks.</li> <li>Native radio/routing/retry integration: 63/63 passed.</li> <li>Existing HIL host regressions: 64/64 passed in the working checkout.</li> <li>Both firmware builds passed from the isolated commit snapshot, without the   unrelated local lab/Wi-Fi/extra modulation-cache edits: V4 repeater RAM   125,336 bytes / flash 1,597,497 bytes; USB companion RAM 62,452 bytes /   flash 828,257 bytes. Both passed runtime-RAM checks.</li> <li>Staged whitespace and documentation-link checks passed. No radios were   flashed for this function update.</li> </ul>"},{"location":"radio_profile_switch_validation/","title":"SX1262 profile-switch validation","text":"<p>Measured locally on 2026-09-13 using an XIAO ESP32-S3 with WIO SX1262. Later tests also use the SenseCAP Indicator ESP32-S3 LoRa processor. The V8 integration is the current implementation; V1-V7 sections/captures document the development history.</p>"},{"location":"radio_profile_switch_validation/#initial-result-v1","title":"Initial result (V1)","text":"<p>The production retune path averaged 1.434 ms with XOSC held, versus 3.166 ms with RC standby. Holding the oscillator saved 1.732 ms per retune (54.7%). Warm-mode maximum was 1.467 ms across 6,000 measured retunes. The 6 ms switch allowance and 4 ms loop allowance are unchanged.</p> <p>Each row combines both directions and two reversed-order trials, with 2,000 measured retunes per standby policy. Times run from production <code>tuneProfile</code> entry until BUSY is observed low. GetStatus confirmed RX after every timed hop.</p> Secondary profile RC mean / maximum XOSC mean / maximum SF7 / 500 kHz 3.161 / 3.199 ms 1.434 / 1.467 ms SF8 / 500 kHz 3.166 / 3.209 ms 1.435 / 1.464 ms SF9 / 500 kHz 3.171 / 3.193 ms 1.433 / 1.437 ms <ul> <li>Primary: 909.5 MHz, SF7 / 62.5 kHz, CR 4/5.</li> <li>Secondary: 910.5 MHz, CR 4/5, automatic production preamble calculation.</li> <li>TCXO configuration remained 1.8 V and 1,600 us startup delay.</li> <li>12,000 measured retunes; zero retune failures, BUSY timeouts, or RX-mode errors.</li> <li>109 packet/busy deferrals were excluded from hop timings (57 RC, 52 XOSC).   Deferral preserves the existing packet and radio ownership checks.</li> <li>The first eight successful hops of every trial were excluded from   steady-state statistics, including the initial oscillator transition.</li> <li>All 12 trials returned to RC standby after disabling the second profile.</li> </ul>"},{"location":"radio_profile_switch_validation/#scope-and-reproducibility","title":"Scope and reproducibility","text":"<p>The timing harness compiles the actual production wrapper, not the earlier fast/minimal RX benchmark. RC and XOSC use the same executable: the baseline changes only the standby policy after entering dual-profile mode. No TCXO supply or initial startup delay is disabled. The normal guard checks and frequency/SF/BW/CR/preamble setters remain active.</p> <p>This isolates radio switching from UI, Wi-Fi, BLE, mesh dispatch, and scan-loop scheduling. BUSY polling/timer overhead is included; the RX status query is outside the timing. This is not a packet-delivery test, first-startup timing, power measurement, wide-frequency image-recalibration test, or proof of analog RF settling beyond BUSY/RX status. Indicator I/O-expander latency and nRF52 timing still need their own measurements before reducing common budgets.</p> <p>Raw results: profile_switch_results.json. The collector requires all requested samples, zero failure/timeout/mode-error counts, and successful RC restoration before accepting a trial.</p> <p>Build provenance:</p> <ul> <li>Base commit: <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code>, with the local warm-standby patch.</li> <li>Environment: <code>profile_switch_xiao</code>; Espressif32 6.11.0 / Arduino 2.0.17.</li> <li>RadioLib: pinned <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code> (7.7.1).</li> <li>Test <code>firmware.bin</code> SHA-256:   <code>629d39bba80ad97c434fbaab61bc7c3c302b5ac8180cb2cb12806508b2d111e0</code>.</li> <li>Existing unrelated Companion/repeater/Wi-Fi soak changes were not included   in this minimal timing executable.</li> </ul> <p>Host regression checks also passed: profile scan/CLI (3 tests), receive contract (2 tests), and SX126x RX-status decoding (1 test). A normal <code>heltec_v4_companion_radio_usb</code> build and the XIAO timing build succeeded.</p> <p>The XIAO's original 8 MiB flash snapshot was verified against the device while held in the bootloader before the timing firmware was uploaded. Raw flash backups stay in the current user's private backup directory, outside Git. After testing, the entire original snapshot was restored and verified again against the device before reboot. The live USB CLI then confirmed <code>Xiao S3 WIO</code> running <code>v1.17.1-soak-xiao-B</code> (11-Sep-2026). Its soak logger was left stopped; existing logs were preserved. The Indicator and RAK Tag were not flashed.</p>"},{"location":"radio_profile_switch_validation/#follow-up-batched-modulation","title":"Follow-up: batched modulation","text":"<p>On the same date, a second 12,000-retune experiment held XOSC warm in both cases and compared the old three-setter sequence with one combined LoRa modulation update. Both paths ran in the same V2 executable, with the second round reversing their order. Each mode completed 6,000 timed hops.</p> Secondary profile Separate setters: mean / maximum Batched: mean / maximum SF7 / 500 kHz 1.442 / 1.473 ms 1.159 / 1.198 ms SF8 / 500 kHz 1.444 / 1.480 ms 1.158 / 1.192 ms SF9 / 500 kHz 1.446 / 1.478 ms 1.156 / 1.163 ms <p>Overall: 1.444 ms to 1.158 ms, saving 0.286 ms (19.8%) per retune. Use this matched V2 baseline for the batching comparison; the earlier V1 warm-standby numbers came from a different executable layout.</p> <p>There were zero retune failures, BUSY timeouts, RX-mode errors, or SF/BW/CR cache mismatches. All 12 trials restored RC standby after disabling profile 2. 84 packet/busy deferrals were excluded (54 separate-setter, 30 batched). First eight successful hops per trial were excluded as before.</p> <p>The batching removes two repeated modem checks and two modulation writes. The helper validates a complete MeshCore bandwidth/SF/CR tuple, updates RadioLib's cached SF/BW/CR before its automatic LDRO calculation, and restores the old cache if the command fails. The wrapper's existing physical rollback and safe-transition paths are retained. Frequency changes, preamble updates, standby, IRQ/buffer setup, packet parameters, and RX restart remain unchanged. This does not qualify eliminating those other repeated operations.</p> <p>Raw results: profile_switch_batch_results.json. V2 test firmware SHA-256: <code>b4403f6f5eb0a2b0a31c2d79859122225f247296699a578ad2596ef17eaed0fd</code>. Toolchain and RadioLib pin match the first experiment. The normal <code>heltec_v4_companion_radio_usb</code> build also succeeded with batching enabled.</p> <p>The two new host tests execute the production method over 1,200 valid bandwidth/SF/CR/LDRO combinations, invalid inputs and wrong modem, command failures with cache rollback/retry, and the wrapper's failure short-circuit. All eight relevant host tests passed. RF packet delivery and application/UI scheduling remain outside this timing experiment; shared budgets are unchanged.</p>"},{"location":"radio_profile_switch_validation/#expanded-screening-redundant-rx-setup-and-spi-v5","title":"Expanded screening: redundant RX setup and SPI (V5)","text":"<p>Corrected V5 measurements on 2026-09-13 cover 28,800 timed retunes in 300 trials across XIAO S3/WIO SX1262 and the Indicator ESP32/SX1262. Each sweep uses SF7/8/9 at 500 kHz paired with SF7/62.5 kHz, both directions, reversed case order in round two, and eight excluded initial hops per trial. All 300 trials completed their sample count and restored RC standby on exit. There were zero timed switch failures, BUSY timeouts, RX-mode errors or SF/BW/CR cache mismatches. The normal packet guards deferred 175 attempted hops; these were not counted as timed retunes.</p> <p>Twenty-one distinct cases were screened: seven individual redundant-operation changes, a full manual RX control, combinations, 2/4/8 MHz SPI and whole-buffer ESP32 SPI transfers. Shared controls appear in both groups. All new shortcuts are HIL-only, not included in normal targets.</p>"},{"location":"radio_profile_switch_validation/#individual-and-combined-rx-changes","title":"Individual and combined RX changes","text":"<p>Means in milliseconds, with warm oscillator and batched modulation throughout. Each XIAO row has 768 timed hops; each Indicator row has 384.</p> RX/SPI case XIAO mean Indicator mean Production batching, 2 MHz SPI 1.182 15.190 Manual RX sequence, no omissions 1.181 15.135 Skip second standby 1.124 14.195 Skip repeated IRQ setup 1.096 14.399 Skip repeated buffer-base setup 1.146 14.437 Skip repeated packet-parameter setup 0.991 12.364 Skip RX modem query 1.145 14.427 Defer preamble to the one RX packet-parameter write 0.956 11.659 Skip wake NOP when already awake 1.146 14.576 Combined omissions, early preamble write 0.771 9.096 Combined omissions, deferred preamble 0.732 8.384 4 MHz SPI only 0.985 14.996 8 MHz SPI only 0.889 14.889 Combined/deferred, 4 MHz SPI 0.627 8.280 Combined/deferred, 8 MHz SPI 0.579 8.224 <p>The largest individual saving is programming preamble/packet parameters once. Compare individual omissions with the manual full control when attributing their isolated costs: replacing RadioLib's staging dispatch also has overhead. Individual savings are not additive; some remove overlapping work.</p>"},{"location":"radio_profile_switch_validation/#whole-buffer-spi-follow-up-same-v5-binaries","title":"Whole-buffer SPI follow-up (same V5 binaries)","text":"Case XIAO mean / maximum Indicator mean / maximum Production batching, byte loop, 2 MHz 1.184 / 1.221 ms 15.185 / 15.785 ms Bulk transfer only, 2 MHz 1.070 / 1.073 ms 15.092 / 15.134 ms Bulk transfer only, 4 MHz 0.890 / 0.903 ms 14.924 / 14.983 ms Bulk transfer only, 8 MHz 0.797 / 0.806 ms 14.836 / 14.908 ms Combined/deferred, byte loop, 8 MHz 0.579 / 0.588 ms 8.222 / 8.843 ms Combined/deferred + bulk, 2 MHz 0.671 / 0.700 ms 8.369 / 9.027 ms Combined/deferred + bulk, 4 MHz 0.582 / 0.595 ms 8.252 / 8.315 ms Combined/deferred + bulk, 8 MHz 0.535 / 0.545 ms 8.203 / 8.233 ms <p>The fastest XIAO candidate saves 0.649 ms (54.8%) versus that sweep's already-warm, already-batched production control. At 8 MHz, bulk transfers alone add about 0.043 ms of benefit to the combined RX shortcut. The Indicator remains dominated by I2C-mediated chip-select/BUSY/DIO access; the final bulk step improves its combined mean by only 0.019 ms. Small HAL effects varied between executable layouts in preliminary screens; do not generalize them.</p> <p>The Indicator exceeds the generic 6 ms switch allowance even in its fastest experimental path. These are board measurements, not a justification for reducing the shared 6 ms switch / 4 ms loop constants. Indicator scheduling and effective preambles need board-specific treatment before a production rollout. Application/display/network scheduling is still excluded here.</p> <p>Raw accepted sweeps:</p> <ul> <li>XIAO RX cases</li> <li>Indicator RX cases</li> <li>XIAO bulk SPI</li> <li>Indicator bulk SPI</li> </ul>"},{"location":"radio_profile_switch_validation/#test-corrections-and-provenance","title":"Test corrections and provenance","text":"<p>V3/V4 broad screening accidentally called <code>SX1262::startReceive()</code> instead of <code>CustomSX1262::startReceive()</code> in the fallback, omitting MeshCore's extra preamble-detection IRQ flag. Their raw files are marked superseded and are not included in the counts or conclusions above. The V4 packet sweep was stopped on discovery. V5 preserves that flag in both normal and manual RX paths; a host regression test checks the Custom fallback and mapped flags. The earlier V1/V2 warm/batching experiments did not use that experimental subclass and are unaffected.</p> <p>An initial V5 XIAO capture stopped on a partial serial JSON line during guarded mode exit. It is retained as incomplete, not counted above. The host now accumulates reads until newline, with regression coverage. Initial setup rejections are retried only for the explicit pre-measurement packet-guard reply, bounded to three seconds and counted; packet losses and timed failures are never retried away.</p> <p>Final V5 firmware SHA-256:</p> <ul> <li>XIAO: <code>5506a40ffa8240201aca519e8e24db3647f897e7a1290bba22be6e4986d8f02f</code></li> <li>Indicator: <code>dd595b2e7fa8c1ccb14fac9223f1a57277cd6a602864ee9bf090672f494fa2f6</code></li> </ul> <p>Base commit/toolchain/RadioLib pin match the earlier experiments. Thirteen unique host tests passed (eight production regressions, two HIL boundary/buffer tests, three serial-reader/setup-guard tests). The HIL tests cover all 255 nonzero omission masks, normal-path fallbacks, preserved IRQ clear/SetRx, error short-circuit and full-duplex buffer lengths 1..260. They are not full driver lifecycle tests. An additional normal <code>t1000e_companion_radio_usb</code> nRF52 build passed with the production warm/batching changes: 591,484-byte app, runtime RAM guard passed. It was not flashed to the RAK or any nRF52 board.</p>"},{"location":"radio_profile_switch_validation/#qualification-boundary","title":"Qualification boundary","text":"<p>No BUSY wait, command status validation, stale-IRQ clear, RX command or wrapper packet-ownership guard is removed. The fastest path relies on a known RX-to-RX window and established RX setup. Correct invalidation after TX, CAD, sleep, reset, failed commands, and recovery must be designed and tested before promoting these shortcuts. The per-byte/bulk HAL experiment is ESP32-specific. Sensitivity/PER, oscillator power draw, large-frequency image recalibration, and application-driven continuous scanning remain unqualified.</p>"},{"location":"radio_profile_switch_validation/#actual-packet-checks-and-limitations","title":"Actual packet checks and limitations","text":"<p>Final forward matrix: Indicator transmitter to XIAO receiver, -9 dBm, 21 cases x SF7/8/9 x both profiles x 16/64/255-byte payloads = 378 probes. 359 sequence/length/payload/profile checks succeeded, 13 receiver-declared wait timeouts occurred, and six receiver USB replies did not arrive before the host deadline. Transmitter replies returned success. Successfully read packets had RSSI -42 to -39 dBm and SNR 10.2 to 14.2 dB. Timeout diagnostics reported RX mode and no device errors; some retained a preamble IRQ. These observations do not establish why packets were missed.</p> <p>The production-batched baseline delivered 17/18 in that matrix; the fastest combined/bulk/8 MHz candidate delivered 18/18. An earlier reversed-order smoke test of the fastest candidate had one receiver timeout, so the clean 18-packet batch is not a reliability qualification. Earlier 0 dBm checks also had baseline and candidate misses. Reducing power did not eliminate them.</p> <p>Reverse direction: XIAO transmitter to Indicator receiver, -9 dBm, baseline, combined/8 MHz and combined/bulk/8 MHz, with the same SF/profile/length matrix. All 54 payloads arrived intact, 18/18 per case. However, one XIAO USB TX acknowledgement was delayed past the host deadline, after which 32 later records picked up the previous command's acknowledgement. Thus the raw file has only 21 fully matched transactions despite 54 correctly received payloads. This is sequence-correlated evidence of a host acknowledgement problem, not 33 RF losses. Subsequent collector code rejects/stores stale sequence replies instead of associating them with a new command, and now asserts DTR on Windows to match the existing <code>s3_memory_soak.py</code> HWCDC session policy. The captures above used DTR deasserted; a causal DTR A/B test was not performed. Sequence handling has host regression coverage, but these last host changes were not rerun on HIL firmware after the boards were restored.</p> <p>USB acknowledgements and actual receiver payload validity are recorded separately. Missing acknowledgements never trigger an automatic retransmit. The host drains the receiver concurrently with the transmitter's command and records timeouts without hiding them. These tests establish some real packet functionality, not a controlled packet-error-rate comparison. Fix/qualify the test transport, repeat with a stable RF reference, then test TX/CAD/reset/RXPS and continuous application scanning before promoting the shortcuts.</p> <ul> <li>Forward matrix, all 21 cases</li> <li>Reverse matrix, three cases</li> <li>0 dBm smoke</li> <li>-9 dBm reversed-order smoke</li> </ul> <p>Earlier incomplete packet captures and superseded screens are retained for audit, not counted in the 378/54 final matrices. No identity or channel secrets were transmitted: probes used synthetic sequence-tagged bytes.</p>"},{"location":"radio_profile_switch_validation/#production-integration-and-usb-recovery-v8","title":"Production integration and USB recovery (V8)","text":"<p>Normal XIAO S3 WIO and Indicator LoRa variants now opt in to buffered 8 MHz SPI and a guarded fast RX-to-RX path. Other SX1262 variants retain default SPI/full RX setup; modulation batching and warm standby remain shared.</p> <p>The fast path keeps the TCXO warm, applies one SF/BW/CR tuple and one packet tuple, clears stale IRQs and starts RX with the original BUSY handling. It reuses an established LoRa IRQ map and buffer bases only within an owned continuous-RX retune. Ordinary standby, staging/TX, CAD, sleep, reset/init, RX duty cycling and command failures invalidate that reuse. RX startup failure now fails the whole profile transaction and restores the old profile/caches with full setup; failed recovery keeps the profile marked for refresh.</p>"},{"location":"radio_profile_switch_validation/#sleep-recovery-discovered-during-integration","title":"Sleep recovery discovered during integration","text":"<p>Initial lifecycle captures found <code>XOSC_START_ERR</code> (0x20) after retained sleep, despite successful RX status. RC-policy controls reproduced the same flag: this was not established as a regression caused by the fast path. Simply waking in RC and entering standby before sleep did not clear it. Reapplying the already configured TCXO voltage and 1,600 us delay resolved it.</p> <p>The production sleep override now enters standby first, wakes in RC, and restores TCXO configuration on wake. It refuses to clear unrelated device faults. The warm policy resumes after full RX setup. This follows the standby entry requirement in section 13.1.1 of the Semtech SX1261/2 datasheet. Section 13.3.6 describes TCXO control and the XOSC error flag; it does not by itself prove the cause of this retained-sleep observation.</p> <p>Diagnostic files <code>profile_switch_v6_recovery_xiao.json</code>, <code>profile_switch_v7_recovery_xiao.json</code>, <code>profile_switch_v7_recovery_xiao_complete.json</code> (despite its filename, its <code>complete</code> field is false), and <code>profile_switch_v7_sleep_diagnostic_xiao.json</code> retain these failures. They are not counted as passing lifecycle tests.</p>"},{"location":"radio_profile_switch_validation/#usb-fix-and-scope","title":"USB fix and scope","text":"<p>The HIL host distinguishes Espressif native CDC (DTR asserted) from CH340 bridges (DTR/RTS deasserted). Replies are newline-assembled and sequence-matched. Firmware caches completed packet and timing reports before emitting and flushing them. A timeout or malformed report triggers a sequence-scoped result query, never a repeated TX or timing run. Randomized session sequence starts avoid a cached result from an earlier host session.</p> <p>V7 had successfully fixed/retested packet result replay but a long native-USB timing sweep still lost one response. V8 adds whole-report timing buffering and replay. The incomplete V7 XIAO timing capture is retained, not silently completed. The public MeshCore Companion USB protocol is unchanged; these USB fixes are for the radio-lab transport. The previous broad Windows-DTR policy described in the V5 history above has been replaced by native-device identification.</p> <p>Both boards passed 20 reopen cycles, deliberate lost timing replies, deliberate lost TX replies, stale TX reply isolation, and 18 lifecycle cases each. The cases cover TX, CAD, sleep, reset/init, RC-policy sleep and explicit TCXO-restoration controls, repeated three times. Fast counters prove one full RX fallback after invalidation and reuse only on the following retune. All command results, RX-mode checks and device-error checks passed.</p> <ul> <li>XIAO recovery</li> <li>Indicator recovery</li> </ul> <p>V8 test firmware SHA-256 (same pinned RadioLib/toolchain as above):</p> <ul> <li>XIAO: <code>e1806bbf4af5a88b31423131806a682713221082235507ff95e5beb9ef3ac067</code></li> <li>Indicator: <code>bab4009078a4fff68dfb7aa73a5afc83e84f5c47589354d8aeb8e5b8d8798442</code></li> </ul> <p>Normal USB Companion builds passed for <code>Xiao_S3_WIO_companion_radio_usb</code> (813,901 app bytes / 63,012 static RAM), <code>SenseCapIndicator-LoRa_comp_radio_usb</code> (879,809 / 62,960), and <code>t1000e_companion_radio_usb</code> (591,980 / 179,868). Runtime RAM budgets passed on all three. These normal application images were compiled, not substituted for the user's configured soak firmware during the HIL tests.</p> <p>Host/native regression coverage includes production modulation caches/LDRO, standby failure short-circuit, RX-start rollback failure, ownership guards, fast-state invalidation, TCXO wake fault preservation, buffered SPI semantics, USB result overflow/replay, partial reads and stale-sequence handling.</p>"},{"location":"radio_profile_switch_validation/#final-steady-state-timing","title":"Final steady-state timing","text":"<p>V8 ran 256 timed retunes per trial, four production configurations, SF7/8/9 at 500 kHz paired with SF7/62.5 kHz, and two reversed-order rounds on each board: 12,288 measured retunes / 48 trials. The first eight hops per trial are excluded. There were zero retune failures, BUSY timeouts, RX-mode errors or modulation-cache errors. All 48 trials restored RC policy on exit. The normal packet guards deferred 21 XIAO and 59 Indicator hops; no setup retries or naturally missing/replayed USB reports occurred in these final sweeps.</p> Production configuration XIAO mean / maximum Indicator mean / maximum Warm + batching, per-byte SPI 2 MHz 1.193 / 1.227 ms 15.174 / 15.836 ms Fast RX, per-byte SPI 2 MHz 0.744 / 0.770 ms 8.426 / 8.471 ms Full RX, buffered SPI 8 MHz 0.828 / 0.840 ms 14.816 / 15.386 ms Fast RX + buffered SPI 8 MHz 0.549 / 0.556 ms 8.263 / 8.879 ms <p>The combined production path saves 54.0% on XIAO and 45.5% on Indicator relative to each same-image warm/batched control. Small differences from V5-V7 reflect different binaries/code layout; only within-image A/Bs are compared. Both fast configurations must increment the production success counter; full RX controls must not. Mode/cache verification happens after the timed region.</p> <ul> <li>XIAO V8 timing</li> <li>Indicator V8 timing</li> </ul> <p>The common 6 ms switch and 4 ms loop allowances are unchanged, not delays inserted by the driver. Indicator still exceeds 6 ms. These measurements do not qualify continuous application scheduling, scan-overlap reception, sensitivity/PER, power use, temperature extremes, or image recalibration on frequency changes larger than this 1 MHz pair. Do not shorten common transmit preambles or advertise the XIAO number for other boards.</p>"},{"location":"radio_profile_switch_validation/#final-over-air-packet-matrix","title":"Final over-air packet matrix","text":"<p>288/288 payloads and command transactions passed: 144 Indicator-to-XIAO and 144 XIAO-to-Indicator. Each direction covers all four production cases, SF7/8/9 secondary profiles, both target profiles, 16/64/255-byte synthetic payloads and two reversed-order rounds. TX used buffered 8 MHz SPI at -9 dBm. Fast receiver readiness reports had to show actual production fast resumes.</p> <p>There were zero RX errors, receiver timeouts, missing replies, stale replies, or natural transport-recovery queries in these matrices. Deliberately lost and stale replies were separately exercised by the recovery tests above. RSSI ranged -43 to -39 dBm and SNR 10.2 to 14.5 dB. This clean short-range matrix addresses the failures seen in the earlier V5 harness; it does not identify which single change caused each historical miss or establish a field packet-error rate.</p> <ul> <li>Indicator TX / XIAO RX</li> <li>XIAO TX / Indicator RX</li> </ul> <p>All 18 host/native regression tests passed. The HIL builds do not include the unrelated pre-existing Companion/repeater/Wi-Fi soak edits; the normal application compile checks include the current working tree and preserve them.</p> <p>A subsequent requested SF6/125 kHz multi-channel test used 32-symbol preambles and 4.8-symbol visits. It stopped on the third packet at the initial four channels (two received, one timeout); no higher count was tried. That continuous scan experiment is separate from the 288/288 stationary-after-retune matrix above.</p>"},{"location":"radio_profile_switch_validation/#unchanged-modulation-tuple-follow-up","title":"Unchanged modulation tuple follow-up","text":"<p>The initial software-only checks below were followed by same-image hardware timing and separated-radio tests. Frequency-only means improved from 548.880 to 451.897 us on XIAO and from 8,263.438 to 7,601.193 us on Indicator. Four-channel SF6 reception was not loss-free. The following paragraph records the initial implementation stage, not the current hardware-test status.</p> <p>Implemented 2026-09-14 after commit <code>0e5955f8</code>, without restarting hardware tests. On opted-in fast RX-to-RX hops, <code>setLoRaModulationParams()</code> now compares the requested SF, encoded bandwidth, encoded CR and effective LDRO against the last successfully acknowledged modulation write. An exact match within a valid owned standby window omits only <code>SetModulationParams</code> (0x8B). Frequency programming, the modem query, preamble/packet parameters, IRQ clears, RF-switch control and BUSY waits remain unchanged.</p> <p>The acknowledgement is separate from RadioLib's mutable software fields. Auto/manual LDRO compares the resulting command byte, with the pinned RadioLib &gt;=16 ms symbol rule. A failed write revokes the whole fast context before rollback. Ordinary SF/BW/CR/forced-LDRO setters invalidate the saved tuple even on failure. Existing full-RX staging, ordinary standby, TX/CAD staging, reset/init, sleep, duty cycling and failed RX/standby operations also invalidate it. The first hop after lost context therefore writes again; frequency-only hops that retain the context can skip subsequent writes.</p> <p>All 30 selected host/native tests passed, including repeat-write counts for all supported bandwidth/SF/CR combinations and auto/forced LDRO modes, each independently changed field, LDRO policy transitions, failed-write retry, modem-query failure, ownership gates, ordinary setters and lifecycle invalidation. Both <code>profile_switch_xiao</code> and <code>profile_switch_indicator</code> compiled successfully against the pinned RadioLib. No firmware was uploaded, no radio command was issued, and no new RF result was collected. The temporary build overlay was removed. The earlier ~0.549 ms XIAO and ~8.263 ms Indicator timings do not measure this added optimization; its time saving and RF behavior await testing.</p>"},{"location":"radio_profile_switch_validation/#mercermesh-heltec-t096-sx1262-experiment-2026-09-21","title":"MercerMesh Heltec T096 SX1262 experiment (2026-09-21)","text":"<p>The Pi has one Heltec T096 (USB serial <code>651F8E496197F882</code>); the other Heltec-named nRF52 is a MeshTower V2, not another T096. An application-only T096 HIL image tested two further RX-to-RX shortcuts with a buffered 8 MHz SPI bus: use SX1262 <code>SetFs</code> instead of warm XOSC standby, and skip <code>SetPacketParams</code> only when the LoRa RX packet tuple is unchanged. Both switches defaulted off in this HIL image. The image explicitly enabled the existing production fast-RX path. Normal T096 firmware does not currently enable that path or use the buffered SPI HAL, so these numbers are not stock T096 switch timings.</p> <p>The same image ran 256 measured hops per configuration, after eight warm-up hops, on 909.5/909.75 MHz. <code>freq</code> held SF7/BW125/CR5; <code>both</code> alternated SF7/SF8 at BW125/CR5. Preamble was 32 symbols. The DWT cycle counter measured through RX re-entry and BUSY release. Every 8 MHz configuration had zero switch failures, mode/cache/RSSI errors, or BUSY timeouts.</p> 8 MHz HIL configuration Frequency-only mean Frequency + SF mean Fast RX baseline 467.3 us 553.6 us <code>SetFs</code> only 422.5 us 517.4 us Unchanged packet tuple skip only 357.7 us 444.0 us Both 313.0 us 407.8 us <p>Combined savings were 154.3 us (33.0%) for frequency-only and 145.8 us (26.3%) for frequency-plus-SF relative to the same-image fast-RX baseline. Command counts confirmed one frequency command, IRQ clear and RX command per hop; the optimized cases eliminated the corresponding standby and packet commands. These are controlled short-range, same-band results, not a field packet-error rate or a qualification of large frequency jumps, sleep/wake, TX/CAD interruption, BLE scheduling, or all SX1262 boards.</p> <p>A separate RAK4631 fixed transmitter sent 16-byte synthetic packets at 909.5 MHz/SF10/BW125/CR5/preamble32, -9 dBm chip power. The T096 hopped to 909.75 MHz and back before each transmission. Baseline and combined shortcuts each delivered 60/60 packets after 120 fast hops, with payload sequence and content checked. The RAK bootloader on this exact fixture enumerated as <code>239A:002A</code> (the fixture's earlier <code>0029</code> expectation was corrected).</p> <p>Doubling buffered SPI to 16 MHz gave only 12\u201321 us (about 3\u20134%) savings in comparable successful cases, while five of eight setup attempts failed. The combined shortcut had no clean 16 MHz result. Keep this T096 at 8 MHz pending a separately diagnosed and repeatable 16 MHz bring-up; no 16 MHz over-air qualification was attempted.</p> <p>Both radios were restored via app-only DFU after the experiment: the T096 to <code>Heltec_t096_repeater</code> and the RAK to <code>RAK_4631_companion_radio_full</code>, each built at <code>v1.17.1.7-hil-restore-e7160dfd</code>. The T096 answered normal <code>version</code> and <code>board</code> commands; the RAK answered the Full Companion terminal's version command. The V4 observer's memory-soak service remained active. Reproducible bench code is in <code>tools/hil/profile_switch_t096_sx1262.cpp</code> and <code>tools/hil/t096_sx1262_packet_probe.py</code>.</p> <p>Follow-up: owned fast RX, <code>SetFs</code>, and acknowledged packet-tuple reuse are now defaults for <code>CustomSX1262</code> targets, including the original XIAO S3 WIO, Station G3 KISS, and Heltec V4 KISS paths. The Seeed Indicator retains its original owned-RX path but explicitly opts out of the two new shortcuts because its radio control and BUSY/IRQ pins run through an I2C expander. The owned-RX state now remembers only an acknowledged packet tuple and revokes it on ordinary packet setters, TX/CAD staging, standby outside the hop, sleep, reset, RX duty cycling, or command failure. The T096 numbers remain lab measurements, not on-board qualification of every <code>CustomSX1262</code> target.</p>"},{"location":"radio_profiles/","title":"Two LoRa profiles on one radio","text":"<p><code>radio2</code> lets one LoRa transceiver alternate between two frequencies or modulation settings. It is useful for listening to two networks, or keeping your usual channel available during a LoRa firmware update.</p> <p>There are at most two active profiles. <code>tempradio</code> temporarily replaces <code>radio</code>; <code>tempradio2</code> temporarily replaces <code>radio2</code>. These are time-shared receive windows, not simultaneous receivers. Receiving or transmitting a packet on one profile makes the other unavailable until that packet finishes.</p> <p>The second-profile commands are shared by repeater, Companion, room server, sensor and standalone terminal-chat firmware with a LoRa radio. ESP-NOW-only devices reject LoRa profile commands. KISS is a raw host-controlled modem: it exposes equivalent RAM-only binary <code>SetRadio2</code>/<code>SetTempRadio2</code> commands and logical KISS Data ports, documented in the KISS modem protocol. It does not use the Mesh CLI's persistent profile file or Mesh retry queues.</p>"},{"location":"radio_profiles/#quick-setup","title":"Quick setup","text":"<p>Keep the primary channel configured with <code>radio</code>, then add the second:</p> <pre><code>set radio2 910.5,500,8,5,rx\nget radio2\nget radio2.status\n</code></pre> <p>The tuple is frequency in MHz, bandwidth in kHz, spreading factor, coding-rate denominator, mode, optional preamble in symbols. <code>5</code> means coding rate 4/5.</p> Mode Receive on profile 2 Transmit on profile 2 <code>rx</code> Yes Only infrastructure replies explicitly configured with <code>tx.reply ... force</code> <code>rxtx</code> (also <code>rx&amp;tx</code>) Yes Yes <code>off</code> No No <p>For transmission on both permanent profiles:</p> <pre><code>set radio2 910.5,500,8,5,rxtx\n</code></pre> <p>The same encoded message is queued separately for each allowed transmit profile. Each has its own direct/flood retry slots and channel-busy backoff. A forwarding echo on one profile cannot cancel the other profile's retry. Packet storage and the physical transceiver's airtime budget are shared; exhausted queues can still drop packets.</p>"},{"location":"radio_profiles/#keep-the-main-channel-during-an-update","title":"Keep the main channel during an update","text":"<pre><code>set tempradio2 910.5,500,8,5,rxtx,120\nget tempradio2\n</code></pre> <p>This enables the second profile for 120 minutes (2 hours). Locally generated LoRa OTA requests use the temporary second profile. Infrastructure OTA responses follow <code>tx.reply</code> below (both TX-capable profiles by default). Ordinary local traffic stays on the primary profile by default. Use an OTA-capable build and the usual OTA setup on every participating node; a temporary profile does not add OTA support to firmware built without it.</p> <p>Local settings take effect after a short reply allowance. On repeaters, immediate remote <code>radio2</code>/<code>tempradio2</code> changes (including <code>off</code>) wait until their exact reply copies finish, with at least one successfully transmitted. A reply that cannot be queued or whose copies all fail cancels the change. Queued replies have a five-minute deadline; an already-transmitting copy may finish under the normal radio watchdog. This confirms transmission, not reception by the remote client.</p> <p>Permanent remote changes are prepared in an uncommitted file before replying; the saved configuration is replaced only after reply transmission. If that replacement fails, the old channel remains active and the commit retries. Local <code>get radio2.status</code> reports this pending state. Roles without the tracked remote reply path require local USB for these immediate secondary-profile changes.</p> <p>Temporary periods and schedules live in RAM and disappear on reboot. Waiting for a reply does not extend a temporary lease. Timer expiry also uses monotonic time, so setting the clock backwards cannot extend a temporary session.</p>"},{"location":"radio_profiles/#repeater-room-server-and-sensor-replies","title":"Repeater, room-server, and sensor replies","text":"<p>These roles default to <code>tx.reply both</code>: locally generated replies are queued on <code>radio</code> and on an active <code>radio2</code> that permits TX. This includes replies to remote CLI/login/telemetry requests, ACKs, returned paths, delayed GPIO command completion, room subscription posts, and locally served LoRa OTA catalog, manifest, data, proof, and leaves responses. Each copy has its own retry state. Forwarded packets, periodic adverts, sensor pushes, and OTA requests continue to use the normal crossing rules.</p> <pre><code>get tx.reply\nset tx.reply both\nset tx.reply both force\nset tx.reply radio\nset tx.reply auto\n</code></pre> Choice Replies transmit on <code>both</code> Primary plus an active <code>rxtx</code> second profile. Default. <code>radio</code> Primary only. <code>radio2</code> Second only; no primary fallback. <code>auto</code> Normal <code>radio2.cross</code> behavior, including permanent/temporary isolation. <code>off</code> Neither profile. This also suppresses remote CLI replies and ACKs. <p>Append <code>force</code> to <code>both</code> or <code>radio2</code> to allow these replies on an active second profile configured as <code>rx</code>. Without <code>force</code>, <code>rx</code> remains receive-only. Sending the command again without <code>force</code> removes the override. It never turns on <code>radio2 off</code>, changes the saved <code>rx</code> mode, or enables ordinary forwarding/TX there. Existing crossover packet filters still apply to the extra copy.</p> <p>The explicit choices override <code>radio2.cross</code>, including <code>off</code> and mixed permanent/temporary profiles. <code>radio</code> means the active primary profile, including <code>tempradio</code>; <code>radio2</code> also includes an active <code>tempradio2</code>. For example, an OTA source can retain its normal channel while allowing OTA and management responses on a temporary receive profile:</p> <pre><code>set tempradio2 910.5,500,8,5,rx,120\nset tx.reply both force\n</code></pre> <p>The source must have OTA support and an active temporary-radio session as usual. A node fetching an update still needs <code>rxtx</code> for its OTA requests. Forcing replies does not change OTA's receive gates, scan timing, or preambles.</p> <p>This setting survives reboot; older saved profiles adopt <code>both</code> without force. The getter reports when the chosen second profile cannot transmit. Already queued replies retain their choice; disabling/changing a profile invalidates stale queued packets. A parameterized repeater <code>tempradio</code> command waits for both admitted reply copies to drain before changing the primary settings; at least one must transmit successfully. Those tracked replies omit alternate paths and transport retries so no late success copy can outlive the handoff. Queue capacity and the shared transceiver's airtime budget still limit delivery. OTA data/proof admission counts both copies against its queue credit and reserves receive capacity before allowing the response.</p> <p>Companions use the per-contact/channel choices below; <code>tx.reply</code> is an infrastructure setting.</p>"},{"location":"radio_profiles/#companion-messages-on-both-profiles","title":"Companion messages on both profiles","text":"<p>To send ordinary Companion messages on both <code>radio</code> and an active <code>tempradio2</code>, configure the temporary profile in <code>rxtx</code> mode and enable crossing:</p> <pre><code>set radio2.cross on\nget tempradio2\nget radio2.cross\nget radio2.status\n</code></pre> <p><code>rxtx</code> permits transmission on the second profile; <code>radio2.cross on</code> copies new messages between the two profiles. <code>TX=a,b</code> reports primary and secondary transmit counts. Crossing also applies to OTA traffic.</p> <p>The crossing setting is saved and remains enabled after the temporary session ends or the node reboots. Run <code>set radio2.cross auto</code> to restore the default isolation between permanent and temporary profiles. The firmware picker's Companion tempradio2 instructions include both choices and the status commands.</p>"},{"location":"radio_profiles/#companion-tx-routing-by-contact-or-channel","title":"Companion TX routing by contact or channel","text":"<p>Companions can save a transmit choice for each contact and each configured channel. The commands apply to messages sent from the phone app, USB/BLE/TCP Companion clients, and the text terminal:</p> <pre><code>set tx.user \"Alice Jones\" radio2\nget tx.user \"Alice Jones\"\nset tx.channel 0 both\nget tx.channel 0\nset tx.channel #wardriving radio\nget tx.channel #wardriving\n</code></pre> <p>Channel indices match the app and the terminal's <code>channels</code> list; Public is normally slot <code>0</code>. Names must match exactly, including capitalization and any leading <code>#</code>. Quotes always select a literal name, so <code>\"1\"</code> is a channel named <code>1</code>, while unquoted <code>1</code> selects slot 1. Quote contact names beginning with <code>key:</code> to distinguish them from public-key selectors. Duplicate names are rejected: use the channel index or a contact's public key instead.</p> Choice Locally addressed traffic transmits on <code>auto</code> Existing behavior, including <code>radio2.cross</code> and temporary-profile isolation. This is the default. <code>radio</code> The primary profile only. <code>radio2</code> The second profile only; sending fails if it is off or RX-only. <code>both</code> The primary profile and the second profile whenever the second is enabled for TX. <code>off</code> Neither profile for this contact/channel. Reception stays enabled. <p>Explicit choices override <code>radio2.cross</code>, including <code>off</code> and the isolation between a permanent and temporary profile. They do not turn on radio2 or change its <code>rx</code>/<code>rxtx</code> mode. For example, leave <code>radio2.cross auto</code> and use <code>set tx.channel 0 both</code> to send Public messages on both <code>radio</code> and an active <code>tempradio2</code>, while other channels keep their default routing.</p> <p><code>radio</code> means the currently active primary profile, whether permanent or <code>tempradio</code>; <code>radio2</code> similarly includes <code>tempradio2</code>. There are still at most two active profiles. Getters show the saved choice and <code>active=</code> for newly initiated messages with the current profile configuration. A temporarily unavailable second profile is reported explicitly.</p> <p>Contact selection uses the full stored public key after resolving a unique name or key prefix. It never routes by the short on-air destination hash. For key selection, prefix 12\u201364 hexadecimal digits (whole bytes) with <code>key:</code>:</p> <pre><code>set tx.user key:0123456789AB radio2\nget tx.user key:0123456789AB\n</code></pre> <p>Replace the example prefix with your contact's key; use more digits if it is ambiguous. <code>get tx.user</code> and <code>get tx.channel</code> report override counts and query syntax. To return a target to the global behavior:</p> <pre><code>set tx.user \"Alice Jones\" auto\nset tx.channel 0 auto\n</code></pre> <p>A user's setting covers addressed texts, login/CLI/telemetry requests, replies, ACKs, and returned paths to that contact. Thus <code>off</code> also prevents ACKs to that contact. Channel settings cover group text and group data, including an explicitly routed group datagram. Contact choices do not filter other people's messages inside a group channel. Adverts, raw traces, raw packets, and OTA packets without a contact/channel destination retain global routing. Packets and their retries already queued retain the choice used when created; changing or disabling the radio profile still invalidates stale queued work. Message timeout estimates use the selected profiles' airtime, independently of the scanner's current receive profile.</p> <p>Choices survive reboot and normal phone-app updates to the same contact or channel key. Replacing a channel's key or deleting/replacing a contact clears its choice. They use reserved bytes in existing saved records, so record sizes and the phone protocol are unchanged. Older firmware ignores these bytes and may reset the choices when it saves the records.</p>"},{"location":"radio_profiles/#choose-whether-traffic-crosses-between-profiles","title":"Choose whether traffic crosses between profiles","text":"<pre><code>get radio2.cross\nset radio2.cross auto\nset radio2.cross on\nset radio2.cross off\n</code></pre> Active primary Active secondary <code>auto</code> (default) <code>on</code> <code>off</code> <code>radio</code> <code>radio2</code> Cross Cross Isolated <code>tempradio</code> <code>tempradio2</code> Cross Cross Isolated <code>radio</code> <code>tempradio2</code> Isolated Cross Isolated <code>tempradio</code> <code>radio2</code> Isolated Cross Isolated <p>These are the global rules used by Companion targets set to <code>auto</code>; an explicit contact/channel choice above overrides crossing for its own outbound packets. Ordinary crossing respects <code>rx</code>. The infrastructure-only <code>tx.reply ... force</code> override above permits locally generated replies on that profile. With crossing allowed, a packet received there may still be forwarded on the primary profile. Existing routing, forwarding and packet-filter settings apply. An RX-only <code>tempradio2</code> also blocks locally generated OTA requests under <code>auto</code> or <code>off</code>; they do not fall back to the normal primary channel. Use <code>rxtx</code> for a fetching node that needs to exchange requests and data. Infrastructure OTA responses follow <code>tx.reply</code> independently of this crossing table.</p>"},{"location":"radio_profiles/#preamble","title":"Preamble","text":"<p>Append the preamble to the end of a command:</p> <pre><code>set radio2 910.5,500,8,5,rxtx,88\nset tempradio2 910.5,500,7,5,rxtx,120,128\nset radio 909.5,62.5,7,5,32\nset tempradio 909.5,62.5,7,5,120,32\n</code></pre> <p>Existing primary <code>radio</code>, <code>tempradio</code>, <code>radioat</code> and <code>tempradioat</code> commands accept the optional trailing preamble where those primary commands are supported by the role. Getters include the preamble. Omit it, or use <code>auto</code>/<code>0</code>, to calculate it automatically. Explicit values are used as entered, subject to the radio's limits and safe airtime arithmetic.</p> <p>Automatic dual-profile preambles round up to a multiple of eight, with a 32-symbol minimum and a 128-symbol maximum. When a second profile activates, the radio first self-tests four successful RX-to-RX switches in each direction using the actual tuples. It defers the test while receiving, transmitting or busy, and never counts a failed switch. The 128-symbol automatic preamble is provisional until the test completes. The largest successful hop, rounded up with a 10% guard, then supplies the per-switch allowance for both the automatic preambles and the scan dwell. There is no fixed switch-time floor. The measurement is reset when either profile changes, including when a <code>tempradio2</code> session starts or ends; it is not saved to flash. The rapid startup hops briefly interrupt reception on each channel; a new packet beginning during this test may be missed. An already detected packet defers the test instead of being interrupted.</p> <p>Each idle scan starts with 4.6 symbols on the slower profile, then spends the remaining budgeted time on the faster profile, also with a 4.6-symbol floor. Slower means a longer LoRa symbol (<code>2^SF / bandwidth</code>), regardless of profile number. The slower preamble sets the return deadline. The calculation allows two slow visits within that preamble, reserving the self-tested switch time per hop and 0.3 ms of main-loop margin. Fast-channel transmit preambles include sixteen acquisition symbols. For a primary SF7 / 62.5 kHz profile with a measured 600 us guarded switch allowance:</p> Secondary profile Automatic secondary preamble Previously tested explicit preamble Primary preamble SF9 / 500 kHz 32 32 32 SF8 / 500 kHz 88 64 32 SF7 / 500 kHz 64 80 32 <p>With preamble 32 on that slower profile, its visit is 9.421 ms and the faster visit is 21.847 ms, plus the actual switching time. Increasing the slow preamble also increases the time available on the fast channel. If the symbols are equal in length, the primary profile goes first. Detected packets hold the current channel until reception finishes.</p> <p>The SF8 / 500 kHz value also retains the measured 88-symbol floor from the production V4/XIAO tests, where 72 and 80 each missed a packet. The explicit values come from the production validation: the final fast-channel attempts each received 50/50 packets at 4.8 slow symbols. Automatic values use the switching and loop-jitter allowances below. Those explicit-preamble tests used the older 4.8-symbol policy; they do not validate the new 4.6-symbol slow dwell / 0.3 ms reserve. The 4.6/0.3 ms two-profile bench received 197/200 at SF7/62.5 + SF8/500 with explicit 32-symbol preambles. The newer four-channel 5.1/6.1/7.7 tests also had misses, so this is a timing policy, not a claim of zero packet loss. The automatic fast preamble covers the blind interval during the slow visit, both switches and the acquisition margin. These settings do not guarantee reception during overlapping packets or long pauses in the firmware loop. Transmitters on each channel also need a long enough preamble. Changing the receiver's setting does not lengthen packets sent by other nodes.</p>"},{"location":"radio_profiles/#chirp-calculator-and-warnings","title":"Chirp calculator and warnings","text":"<p><code>get radio2.timing</code> (alias <code>get radio.timing</code>) reports the active pair in <code>radio,radio2</code> order: dwell in chirps, recommended preambles in symbols, and the switching/loop allowances. Before calibration it reports <code>timing self-test pending</code> and the provisional preambles. For SF7/62.5 on <code>radio</code> and SF7/500 on <code>radio2</code> after a 600 us guarded measurement:</p> <pre><code>&gt; chirps=4.60,85.34; need=32,64; switch=600us; loop=300us (estimate); test=4/4,4/4 ready; WARN recommended preamble: radio2=64\n</code></pre> <p><code>WARN recommended preamble</code> identifies each profile whose recommendation exceeds the standard 32 symbols or its explicitly selected value. For example, with SF7/62.5 on the primary profile, <code>set radio2 910.5,500,7,5,rx,32</code> initially replies with <code>timing self-test pending</code>. Once active and measured, <code>get radio2</code> warns:</p> <pre><code>&gt; 910.500,500.000,7,5,rx,32; WARN recommended preamble: radio2=64; short override: radio2\n</code></pre> <p>Successful <code>set radio ...</code> replies also include the recommended preamble for each affected profile, calculated with the requested settings. A <code>short override</code> note identifies an explicit value below the estimate; it is not silently rewritten. Warnings are also included in profile settings/getters, scan info, temporary settings and schedule acknowledgments. These preamble-bearing replies also include <code>switch=547us</code> (or the current measured value) after the self-test for that exact profile pair. The first ACK for a new pair says <code>timing self-test pending</code> instead: it is sent before activation, so it cannot contain the future measurement. Query <code>get radio2</code> after activation to see the measured value beside the resulting preamble. <code>off</code> disables the dual-profile warning. <code>get radio2.status</code> shows self-test progress and the resulting guarded switch budget; its separate <code>max</code> field remains a lifetime diagnostic that can include failed/rolled-back retunes and is not used for calibration. If the recommendation exceeds 128, it additionally reports <code>WARN need &gt;128</code>; an automatic preamble stays at 128, which may not be enough for reliable reception on that pair. Explicit preambles are not rewritten and still use the radio's ordinary validation limits. A timing readout does not change settings or transmit a packet.</p> <p>The shared <code>RadioProfiles::calculateChirpTiming()</code> function accepts both tuples, optional visit times in microseconds, a per-switch allowance and loop margin. Using microseconds throughout:</p> <pre><code>T[i] = 2^SF[i] * 1000 / BW_kHz[i]\nslow = profile with the longer T (radio wins ties)\nL[slow] = max(requested_visit_us[slow], ceil(4.6 * T[slow]))\nL[fast] = max(requested_visit_us[fast], ceil(4.6 * T[fast]))\nO    = 2 * switch_us + loop_margin_us\nC    = L[radio] + L[radio2] + O\n\nP[slow] = round_up_to_8(max(32, 2 * C / T[slow]))\nP[fast] = round_up_to_8(max(32, (L[slow] + O) / T[fast] + 16))\n</code></pre> <p>The previous SF8/500 versus SF7/62.5 measured 88-symbol floor remains in force. Automatic selection uses the minimum visits to choose a preamble, then allocates the fast visit from half the slow preamble's duration. Diagnostics feed the actual allocated visits back into the same function, including longer visits caused by an explicit slow preamble. Too-short slow preambles that cannot fit both minimum visits remain rejected by the existing configuration validation.</p> <p>The automatic scheduler uses these same role-specific minima and computes:</p> <pre><code>slow_dwell = ceil(4.6 * T[slow])\nfast_dwell = max(ceil(4.6 * T[fast]),\n                 floor(P_configured[slow] * T[slow] / 2 - slow_dwell - O))\n</code></pre> <p>For the tested SF7/62.5 + SF8/500 pair with slow preamble 32, this yields 9,421 us slow and 21,847 us fast (42.67 fast chirps). Swapping <code>radio</code> and <code>radio2</code> swaps the allocations automatically. The 0.3 ms reserve is not a sleep.</p> <p>Production scheduling and automatic preambles use the self-tested maximum successful switch plus 10%, together with 300 us per cycle. Subsequent successful hops can only raise that allowance until the next profile change. The measured recommendation is rounded up to eight symbols and capped at 128 for automatic settings. The calculator and warnings retain the uncapped recommendation so a slow board is not shown as safe merely because it hit the limit. Older V4 tests peaked at 836 us (827 us in the 4.6/0.3 ms run), and Indicator reached 8428 us; these are historical measurements, not default budgets for other boards. The model preserves two slow-profile return opportunities and the existing 16-symbol fast-profile acquisition allowance. These are conservative policies, not a fitted success curve, and neither packet overlap nor arbitrary application stalls can be made safe by a finite preamble recommendation.</p> <p>See the implementation and validation notes.</p>"},{"location":"radio_profiles/#schedule-the-second-profile","title":"Schedule the second profile","text":"<p>Use UTC Unix timestamps (seconds), or <code>+N</code> for N whole minutes from now:</p> <pre><code>set radioat2 910.5,500,8,5,rxtx,START[,PREAMBLE]\nset tempradioat2 910.5,500,8,5,rxtx,START,END[,PREAMBLE]\nget radioat2\nget radioat2 1\nget tempradioat2\nget tempradioat2 1\ndel radioat2 1\ndel tempradioat2 all\n</code></pre> <p>Replace <code>START</code> and <code>END</code> with timestamps or <code>+N</code>, and the optional <code>PREAMBLE</code> with a number; omit the square brackets. Each schedule family has four slots. Times must be in the future and within 24 days. Overlapping temporary second-profile sessions are rejected. <code>radioat2</code> changes the saved second profile when it starts; <code>tempradioat2</code> restores the saved profile at its end. Pending schedules do not survive reboot.</p> <p>For example, <code>set tempradioat2 910.5,500,8,5,rxtx,+5,+15</code> starts in 5 minutes and restores in 15 minutes (10 minutes active). Both offsets are measured from the same node-clock snapshot when accepting the command, not from each other. <code>set radioat2 910.5,500,8,5,rxtx,+5</code> schedules a saved change in 5 minutes. Offsets must be positive whole minutes. Absolute and relative endpoints can be mixed; bare numbers still mean UTC seconds. Existing clock requirements apply.</p>"},{"location":"radio_profiles/#return-to-one-profile","title":"Return to one profile","text":"<pre><code>set radio2 off\n</code></pre> <p>This saves the disabled state and cancels all second-profile temporary activity and schedules.</p> <pre><code>set tempradio2 off\n</code></pre> <p>This ends temporary second-profile activity, cancels its temporary schedules and restores saved <code>radio2</code>. If the saved second profile is off, this returns to one profile. Packets/retries bound to an expired or changed session are discarded.</p>"},{"location":"radio_profiles/#power-saving-and-diagnostics","title":"Power saving and diagnostics","text":"<p>Dual mode suspends RX power saving and MCU idle sleep so receive visits can run promptly. The saved RX power-saving setting returns when profile 2 is off. The scan uses normal receive, following the CAD/RX measurements, with the updated 4.6-symbol dwell on the slower channel, followed by the remaining fast-channel visit. It does not use CAD for scanning. The separate CAD check before an initial transmission still follows <code>cad</code>.</p> <p>SX1262 dual-profile mode keeps the oscillator running in XOSC standby between visits, so each retune does not need to restart the TCXO. It restores the prior standby policy when returning to one profile, together with the saved RXPS setting. Radio reinitialization temporarily uses RC standby until the TCXO has been configured again. Other radio families retain their existing behavior. This does not disable the TCXO supply or its initial startup delay, and it is not conditional on 500 kHz bandwidth. Keeping the oscillator on uses additional power during the short standby intervals.</p> <p>The switch-time self-test is not a forced settling delay or a proof of RF acquisition. The earlier standalone keep-warm scan experiment averaged about 1.19 ms of overhead per hop (scan-cycle time minus both receive windows, divided by two). That experiment used a leaner receive path; it is not a measurement or guarantee of the production implementation. Measure the target board before shortening its timing margins or transmit preambles.</p> <p>The production-path XIAO timing test measured 1.434 ms average / 1.467 ms maximum with warm standby, compared with 3.166 ms average using RC standby: about 1.732 ms saved per hop. It covered 12,000 retunes across SF7/8/9 at 500 kHz paired with SF7/62.5 kHz. These measurements include observing BUSY low, but exclude application/UI scheduling and are not a packet-delivery qualification or a guarantee for other boards, especially those using I/O expanders.</p> <p>A same-image follow-up batching SF/BW/CR into one modulation command reduced warm switching from 1.444 ms to 1.158 ms average (batched maximum 1.198 ms), saving another 0.286 ms / 19.8%. RadioLib's modulation caches and LDRO calculation remain synchronized; frequency, preamble, packet guards, and RX restart are unchanged. A later HIL-only screening tested redundant standby/IRQ/buffer/packet setup and SPI transfer changes. Its fastest candidate measured 0.535 ms mean on XIAO but 8.203 ms on the Indicator, whose radio GPIOs go through an I2C expander. The validated production implementation now opts XIAO S3 WIO and Indicator LoRa into buffered 8 MHz SPI and a guarded fast-RX state machine. The <code>heltec_v4_kiss_modem</code> and <code>Station_G3_ESP32_kiss_modem</code> targets use the same guarded path only for KISS dual-profile scanning; their normal board roles keep their established HAL/timing policy. V4 uses its existing 160 MHz role override and Station G3 uses its base 240 MHz setting, but both still need an exact-image hardware timing check before a nominal 600 \u00b5s target is claimed. It skips redundant standby, IRQ mapping, buffer-base writes and modem queries only during an owned continuous RX-to-RX retune. Preamble/packet parameters (including the IQ workaround), stale-IRQ clearing, RX commands and BUSY waits remain. TX, CAD, sleep, reset, RXPS and failed commands revoke reuse; failed RX startup rolls back the profile. Sleep entry uses standby and wake restores the existing TCXO voltage/delay. Other variants do not opt in to faster SPI or the fast-RX state machine. Within a valid owned fast-RX retune, identical acknowledged SF/BW/CR/LDRO settings now reuse the previous modulation command: frequency-only hops omit <code>SetModulationParams</code> (0x8B). A changed effective LDRO value also forces a write, including when automatic LDRO policy changes. Ordinary setters and lost RX context invalidate that acknowledgement; initial setup, reset, sleep, failed commands and full RX setup conservatively reapply the tuple. Frequency, preamble/packet setup, IRQ clearing and BUSY checks are unchanged. This follow-up has same-image hardware measurements: frequency-only hops averaged 0.452 ms on XIAO and 7.601 ms on Indicator. The mixed-bandwidth timing figures above predate it. Four-channel SF6 scans still missed packets; faster switching is not proof of loss-free acquisition. See production and USB validation for current measurements, lifecycle tests and limitations. The Indicator result shows why each board now measures its own switch time. That measurement adjusts automatic preambles and dwell, but it cannot verify RF acquisition or lengthen packets transmitted by other nodes.</p> <p>Single-channel noise-floor calibration and RSSI interference comparison are suspended while scanning. Retries use the radio's preamble/header activity indicators. LR2021 extra-SF side detectors are suspended and restored as well.</p> <p><code>get radio2.status</code> reports the active second-profile mode, MeshCore RX/TX counts for each profile, switch count, switch failures, longest measured switch and both effective preambles. A long switch time or rising error count indicates that the chosen settings need investigation on that board.</p> <p><code>get radio2.scan</code> shows which profile goes first, the two idle receive-window lengths in microseconds, and both effective preambles. It reports <code>off</code> in single-profile mode.</p>"},{"location":"radio_profiles_validation/","title":"Dual-profile receive validation","text":"<p>These measurements exercise the production two-profile implementation on one SX1262 transceiver, using a Heltec V4 repeater as receiver and a XIAO ESP32-S3 with a Wio LoRa module as transmitter. They follow the dedicated mixed-bandwidth scan experiment.</p> <p>Counts, diagnostic replies and firmware/source hashes are in radio_profiles_results.json.</p> <p>The primary profile is 909.5 MHz, SF7, 62.5 kHz, CR 4/5, preamble 32. The secondary is 910.5 MHz, 500 kHz, CR 4/5, with SF9, SF8 or SF7. Scanning uses normal RX, starts with the slower profile, and reserves two slow visits per slow preamble. Transmitters must use the corresponding preamble too.</p>"},{"location":"radio_profiles_validation/#method-and-limits","title":"Method and limits","text":"<p>The transmitter sends MeshCore adverts at varied intervals. The receiver's per-profile MeshCore RX counters are compared with the transmitter's completed TX counters before and after each run. Initial OTA announcements can add packets beyond the manually requested adverts; the table includes those transmissions. These are aggregate counters, not sequence-matched payload captures.</p> <p>Runs use one transmitting profile at a time and a strong signal. They do not measure simultaneous traffic, weak-signal reception, interference or months of uptime. A single transceiver remains unavailable to the other profile while receiving or transmitting a packet. A clean finite run is evidence for a timing choice, not a guarantee that it cannot drop packets.</p>"},{"location":"radio_profiles_validation/#five-symbol-baseline","title":"Five-symbol baseline","text":"<p>Slow visits were 10.240 ms and fast visits 6.528 ms, plus actual switching time. The longest observed profile switch was 4.416 ms; no switch failures were reported.</p> Fast profile Fast preamble Fast RX / TX Slow RX / TX SF9 / 500 48 54 / 54 30 / 30 SF8 / 500 72 49 / 50 \u2014 SF8 / 500 80 49 / 50 \u2014 SF8 / 500 88 50 / 50 30 / 30 SF7 / 500 120 50 / 50 30 / 30 <p>The SF8 automatic preamble retains a measured floor of 88 symbols. Automatically selected preambles always round up in steps of eight.</p>"},{"location":"radio_profiles_validation/#fractional-symbol-tuning","title":"Fractional-symbol tuning","text":"<p>The initial sweep started at 4.2 slow symbols, with an increase of 0.1 planned for any slow-channel loss. That first sweep passed all three fast settings. Each completed run used 50 requested adverts per profile. The SF8 fast run was interrupted to check SF9 preamble 32, then restarted; only its completed run is included below.</p> Slow symbols Fast profile Fast preamble Fast RX / TX Slow RX / TX 4.2 SF9 / 500 48 50 / 50 50 / 50 4.2 SF9 / 500 32 50 / 50 50 / 50 4.2 SF8 / 500 88 50 / 50 50 / 50 4.2 SF7 / 500 120 50 / 50 50 / 50 <p>The four completed pairings received 200/200 packets on the slower channel and 200/200 on the faster channel. No switch failures were reported; the longest measured switch during the 4.2-symbol sweep was 4.407 ms.</p> <p>The explicit SF9 preamble-32 check uses the same 8.602 ms slow and 8.166 ms fast windows as the preamble-48 check. Only the fast transmitter's preamble changes. The automatic SF9 calculation still reserves a 48-symbol preamble for the configured switching and loop-jitter budgets.</p>"},{"location":"radio_profiles_validation/#shorter-fast-preambles","title":"Shorter fast preambles","text":"<p>The follow-up starts with preamble 48 on both fast settings. Each miss advances the next candidate by eight symbols. The receive-window budgets stay at 4.2 slow symbols and the same remaining fast-channel time.</p> Fast profile Preamble Fast RX / TX SF8 / 500 48 49 / 50 SF8 / 500 56 50 / 50 SF7 / 500 48 42 / 50 SF7 / 500 56 41 / 50 SF7 / 500 64 45 / 50 SF7 / 500 72 50 / 50 <p>The slower channel passed 50/50 paired with SF8/56, but then received 49/50 paired with SF7/72. Across the completed 4.2-symbol slow-channel runs, that is 299/300. This later miss invalidated the provisional 4.2-symbol choice and triggered the next headroom test at 4.3 symbols. Fast-preamble baselines carry forward as 32 for SF9, 56 for SF8 and 72 for SF7, advancing by eight on a miss.</p> <p>At 4.3 symbols, the SF9/32 pairing received 100/100 slow packets and 50/50 fast packets. The next SF8/56 pairing received only 42/50 slow packets, so that candidate also failed. A control run with scanning disabled received 50/50 on the slow channel. At 4.4, SF8/56 passed 100/100 slow and 50/50 fast, but the SF7/72 pairing then received 49/50 slow packets.</p> <p>At 4.5, the SF7 pairing passed 100/100 slow packets. Fast preamble 72 received 47/50, so the next baseline increased to 80 and passed 50/50. The following SF8/56 slow run received 49/50, triggering 4.6 symbols. Baselines now carry forward as SF9/32, SF8/56 and SF7/80.</p> <p>At 4.6, both SF8/56 and SF7/80 passed 100/100 slow packets and 50/50 fast packets. The following SF9/32 slow run received 49/50, triggering 4.7 symbols. There were no switch failures; the longest observed switch was 4.414 ms.</p> <p>At 4.7, the SF9/32 slow run passed its first 50 packets but received 99/100 over the full run. This triggered 4.8 symbols, with the same fast preamble baselines. No fast-channel run was started for the 4.7 candidate.</p>"},{"location":"radio_profiles_validation/#selected-bench-baseline-48-slow-symbols","title":"Selected bench baseline: 4.8 slow symbols","text":"<p>The 4.8-symbol sweep passed all three slow-channel checks, totaling 300/300. Slow visits are 9.831 ms and fast visits 6.937 ms, plus actual switching time. The longest measured switch was 4.491 ms, with no switch failures.</p> Fast profile Fast preamble Fast RX / TX Slow RX / TX SF9 / 500 32 50 / 50 100 / 100 SF8 / 500 56 49 / 50 100 / 100 SF8 / 500 64 50 / 50 \u2014 SF7 / 500 80 50 / 50 100 / 100 <p>The SF8 miss advanced its baseline from 56 to 64, exactly eight symbols. Its slow-channel check preceded that increase; changing the fast preamble leaves the idle receive-window calculation unchanged. The final fast-channel attempts received 150/150, using explicit preambles 32 / 64 / 80 for SF9 / SF8 / SF7. These become the starting values for further tests, increasing by eight on a fast-channel miss. A slow-channel miss instead advances the listen window by 0.1 symbol.</p> <p>The production automatic preambles remain 48 / 88 / 120, retaining the switching, loop-jitter and acquisition budgets. The shorter explicit values are bench results under the conditions above, not a guarantee for other boards or traffic patterns.</p>"},{"location":"radio_profiles_validation/#transmit-policy","title":"Transmit policy","text":"<p>Hardware checks send three zero-hop adverts from the V4 with the XIAO listening on profile 2. OTA startup traffic is allowed to settle before taking the counter snapshots. The completed cases are:</p> V4 profiles and policy TX on primary / secondary Received by XIAO Permanent / permanent, <code>auto</code> 3 / 3 3 Permanent / permanent, <code>off</code> 3 / 0 0 Permanent / temporary, <code>auto</code> 3 / 0 0 Permanent / temporary, <code>on</code> 3 / 3 3 Secondary RX only, <code>on</code> 3 / 0 0 Temporary / temporary, <code>auto</code> 3 / 3 3 <p>A separate isolation check issued three explicit OTA announce commands with normal <code>radio</code>, RX-only <code>tempradio2</code> and <code>radio2.cross auto</code>. The completed TX counters stayed unchanged on both profiles (0 / 0), confirming that locally generated OTA traffic does not fall back to the normal channel in that mode.</p> <p>Turning <code>radio2</code> off stopped scanning. A one-minute <code>tempradio2</code> session also returned to one profile on expiry. Rebooting with a saved SF8 RX profile and an active temporary SF9 RX/TX profile cleared the temporary session and restored the saved SF8 profile, including its automatic 88-symbol preamble.</p>"},{"location":"radio_profiles_validation/#ota-discovery-while-retaining-the-main-channel","title":"OTA discovery while retaining the main channel","text":"<p>Both boards ran normal SF7 / 62.5 kHz on the primary and temporary SF8 / 500 kHz RX/TX on the secondary, using <code>radio2.cross auto</code> and automatic preambles 32/88. The XIAO discovered the V4's firmware catalogue over profile 2, and both boards recorded received and transmitted OTA packets there. Ten V4 zero-hop adverts then arrived on the XIAO's primary profile (10/10), with both temporary second profiles still active. The XIAO reported no switch failures and a longest switch of 4.547 ms during this check.</p> <p>This hardware check covers discovery, bidirectional OTA traffic and concurrent availability of the main channel between packets. It does not perform a complete firmware transfer or install. Byte-exact transfer validation is provided by the shared OTA software tests described below.</p>"},{"location":"radio_profiles_validation/#software-coverage","title":"Software coverage","text":"<p>Native tests cover identical-packet fanout, separate retry ownership and coding rates, channel-busy backoff, generation changes, temporary-session isolation, deferred replies and stale-packet removal. Tests using the production CLI cover parsing, persistence failures, schedules, expiry and clock rollover. A physical radio mock exercises the production scan transitions, pending RX interrupts, RX power-saving restoration and failed profile switches.</p> <p>The full native suite passed 1,422 cases after the RX-only OTA isolation fix; all eight KISS modem tests also passed. Subsequent timing changes through 4.8 symbols passed the 63-case retry/profile suite and production CLI and scan harnesses. Shared OTA transfer tests passed byte-exact checks with AddressSanitizer and UndefinedBehaviorSanitizer for ESP32 and nRF52 variants.</p> <p>Build coverage includes the Heltec V4 repeater, room server, sensor and terminal chat, the Full XIAO Companion, and the nRF52 T1000-E repeater. The nRF52 result is a build check; these receive measurements use the ESP32/SX1262 boards above.</p>"},{"location":"radio_profiles_validation/#hardware-restored-after-validation","title":"Hardware restored after validation","text":"<p>Both boards were returned to their original B soak images after the checks: <code>v1.17.1-soak-v4-B</code> and <code>v1.17.1-soak-xiao-B</code>. The V4 retained 909.5 MHz, SF7 / 62.5 kHz, CR 4/5 and TX 0; the XIAO retained 910.525 MHz with the same modulation and TX 22. Both reconnected to Wi-Fi and their custom MQTT service. The soak logs resumed under <code>B-post-radio2-soak</code>. These restored images are the earlier memory-soak firmware; the new dual-profile code is validated by the finite tests above, not by a months-long uptime run. The Pi's soak service and Indicator telemetry were also healthy after restoration.</p>"},{"location":"radio_receive_calibration/","title":"Radio receive calibration and recovery","text":"<p>Noise calibration collects 64 idle RSSI samples at least 50 ms apart. A quiet block takes about 3.2 seconds. Both continuous RX and temporary RXPS calibration windows allow up to 30 seconds; a partial block times out without publishing. Periodic requests coalesce while a block is active. RXPS resumes after a complete block, including a held block, or at timeout. Receive and transmit activity are never interrupted just to finish calibration.</p> <p>The block estimate is the 12.5th percentile: the average of the eighth and ninth sorted samples, retaining fractional dBm. A published update uses 25% of the previous floor and 75% of the new estimate, with a -120 dBm lower bound. Initial calibration and explicit gain/tuning changes seed a new baseline. The old published value remains available while collecting. An AGC reset drops partial samples while retaining a valid baseline for channel checks.</p> <p>An estimate more than 15 dB above the established floor is held twice. The third consecutive complete high block is accepted, allowing recovery after a permanent ambient rise. A normal or quieter complete block clears the hold. Partial blocks do not advance it. There is no admission threshold based on the old floor, so an old low baseline cannot reject every sample from a higher floor.</p> <p>Hardware captures with sustained different-SF/BW traffic showed the median and lower quartile following the interferer. The 12.5th percentile retained the quiet background in those captures. It needs at least nine background samples out of 64 to avoid higher-valued traffic entirely. Nearly continuous interference or enough low outliers can still mislead it. The rise hold delays large changes but cannot identify their source.</p> <p>RSSI sampling waits 20 ms after every receive re-arm, including CAD and TX completion, to avoid unsettled frontend readings. The ten-second trial window often failed to complete during heavy traffic with that settling guard; the 30-second cap allows more idle opportunities. Partial blocks still time out without publishing. Longer collection spends more time in continuous RX when RXPS is enabled. A quiet minimum is about 3.2 seconds; real completion time also depends on packet activity and main-loop scheduling.</p> <p>On radios with a mode probe, each eligible RSSI sample first checks that the chip has not silently left RX. Confirmed standby/non-RX discards the partial block without changing the published floor. Rejected attempts are also spaced 50 ms apart. BUSY and packet ownership block sampling; families without a mode probe retain their existing RSSI path.</p> <p>CAD has a bounded wait, stops RX duty cycling before scanning, and re-arms the configured receive mode on success, busy detection, or error. A completed or currently receiving packet owns the radio and blocks CAD. A packet interrupt arriving during re-arm is retained. Failed re-arm and a newly arrived packet both defer transmission.</p> <p>SX126x wrappers additionally run a recovery watchdog at most once per 10 seconds while continuous RX is expected. RXPS sleep, busy SPI, pending packets, and invalid status reads do not count as non-RX evidence. Two confirmed non-RX observations request soft recovery; a third uses the existing hard recovery path where supported. An observed healthy RX state clears the sequence. Recovery preserves tuning, TX power, receive gain, and the operator's power-saving intent. The existing radio liveness and RXPS watchdogs remain active for other failures.</p> <p>The radio liveness watchdog measures time without a successfully received packet. Only a positive <code>recvRaw()</code> result restarts its observation window; TX completion, CAD interrupts, and failed packet reads do not. Reception counts even if application parsing rejects the packet or the packet pool is full. The check runs after pending RX is drained and TX completes, before the next queued transmission, so sustained outbound traffic cannot postpone recovery.</p> <p>The default silence thresholds are 30 minutes for a soft RX/AGC re-arm and 12 hours for a radio-only hard recovery where supported. MQTT observer <code>radio.watchdog</code> settings can override the soft interval. A successful hard recovery starts a fresh observation window to limit repeated resets on a quiet mesh; a failed hard recovery remains escalated and retries after 30 seconds. Targets with <code>RADIO_LIVENESS_SOFT_ONLY</code> repeat soft recovery at the soft interval because their radio cannot be reset independently. These recoveries do not reboot the MCU. The repeater's <code>rx.watchdog</code> is a separate whole-board reboot watchdog, enabled by default with a 24-hour sliding deadline since the last received packet passed MeshCore parsing. Its timer is updated before receive delays and routing filters; raw LoRa reads rejected by the parser do not count. MeshCore parsing checks the packet structure, not sender authentication or decryption of traffic addressed to other nodes. Temporary radio windows of at least 12 hours use a 12-hour deadline; shorter windows disable that reboot watchdog until the window ends. The temporary timing overrides are held in RAM and do not replace saved normal-mode preferences.</p> <p>The status read uses the two-byte GetStatus transaction. The pinned RadioLib getStatus() helper requests zero copied data bytes, so its return value is not usable for this mode check. The dedicated read restores the normal SPI command layout afterward and does not wake a duty-cycling radio to inspect its mode.</p> <p>Validation lives in <code>test_noise_floor_estimator</code>, <code>test_rx_power_saving</code>, <code>test_radio_liveness</code>, <code>test_radio_receive_contract.py</code>, and <code>test_sx126x_receive_mode.py</code>.</p>"},{"location":"rak3401_mota_chain/","title":"RAK3401 1W repeater compact LoRa update chain","text":"<p>Status: published prerelease for controlled, recoverable lab use. On 29-Aug-2026 steps 1-9 completed on the target RAK3401 and are byte-for-byte identical to the corresponding transitions in the physically passed <code>fd98bc90</code> chain. The replacement step 10 installs the current <code>3f6eddd5</code> endpoint. That replacement package and the hardened current runner have passed offline reconstruction plus the exact deployed bootloader simulator, but have not had a new physical end-to-end run. Use the lab gate and keep local DFU/SWD recovery available. Multi-hop and alternate-bandwidth estimates remain planning data, not physical qualification.</p> <p>The prerelease is <code>rak3401-mota-v1.16.07-c1caa5ad-to-v1.17.1.6-3f6eddd5</code>. Use this asset:</p> <pre><code>RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip\n</code></pre> <ul> <li>prerelease ZIP SHA-256: <code>135783dd8777490db2422a7543f7d80e3cf03f621d5ac362da930abbc1850dc4</code></li> <li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>93835ed497c579be0a2322292e7f15ab095e7c8ab7892833fe7df3130dbdaba4</code></li> <li>endpoint image SHA-256: <code>cd1e9b819f9e918f9f2ceaf37b8a74bf242e2be78f319af2cf02a42d7729d0f4</code></li> <li>endpoint EndF body hash: <code>9BD7CF682EE065AE</code></li> </ul> <p><code>--verify-only</code> remains the safe default. Live preflight and installation of this prerelease require <code>--accept-test-candidate</code>. That switch bypasses only the prerelease-status gate; it does not bypass the archive, identity, bootloader, route, watchdog, reachability, or post-boot checks.</p>"},{"location":"rak3401_mota_chain/#exact-destination","title":"Exact destination","text":"<p>This chain is intentionally specific to one firmware lineage and hardware target:</p> <ul> <li>target ID: <code>2FA509C1</code></li> <li>hardware: <code>RAK_3401</code></li> <li>role: <code>RAK_3401_repeater_lora_ota_no_external_sensors</code></li> <li>start: <code>v1.16.7.0-c1caa5ad</code>, EndF <code>71F4026CBE4B8B74</code></li> <li>endpoint source: MeshCore <code>3f6eddd5c20f1fa3df6ba1cc208efbe3e2fffb43</code></li> <li>endpoint label: <code>v1.17.1.6-halo-keymind-cascade-dev-3f6eddd5</code></li> <li>endpoint packed version: <code>0x01110106</code></li> <li>deployment target key: <code>63d8df6387eaffd2e25db7d2a8ad967a65202182a48d681d7e7a9260f917280d</code></li> </ul> <p>The exact starting application is the <code>lora-ota-v1.16.07-halo-keymind-cascade-dev-3a6af3bf</code> RAK3401 asset. Its outer ZIP SHA-256 is <code>58ead2ea18efafda186bc9d983fe08cdf65f69b0e5a3a1c72c18fe35948a254c</code>; its 566,912-byte <code>firmware.bin</code> SHA-256 is <code>4301fc63ebd661c70f9bc40e7eca44d3cb8a358cb3c0075e700d9676a57478cb</code>. The endpoint build ZIP SHA-256 is <code>a9fca9be145a96feb650b57c43b5ed173d74d2f3194da12e31b1c54352635b56</code>.</p>"},{"location":"rak3401_mota_chain/#retained-and-omitted-hardware-support","title":"Retained and omitted hardware support","text":"<p>Despite the legacy <code>no_external_sensors</code> target name, the endpoint retains the RAK12501 GPS provider and the common INA3221, INA219, INA226, and INA260 I2C voltage/current monitors. Install RAK12501 in sensor slot A. Do not use slot D with the RAK13302 1 W radio because the GPS reset/PPS signals overlap the radio's BUSY/DIO1 wiring.</p> <p>The reduced profile omits optional external environmental and ranging devices: AHTX0, BME280, BMP280, SHTC3, SHT4x, LPS22HB, MLX90614, VL53L0X, BME680, BMP085, RAK12035, and BME680 BSEC. Board radio, display, buttons, battery telemetry, GPS, and the INA monitor family remain. No additional \u201cremove I2C temperature\u201d image is needed: the optional I2C temperature/environment drivers are already in the omitted set, while removing the remaining I2C/INA support would discard desired voltage/current monitoring and create another firmware identity without helping this route.</p> <p>Do not use the chain on another target ID, hardware family, starting image, or firmware body hash. The runner checks all four.</p>"},{"location":"rak3401_mota_chain/#why-the-deployed-otafix24-and-old-staging-ceiling-work","title":"Why the deployed OTAFIX2.4 and old staging ceiling work","text":"<p>The deployed bootloader is not changed and no package uses the newer expanded <code>0xED000</code> ceiling. Each package remains bottom-aligned below the old bootloader's <code>0xD4000</code> scan ceiling. Its detools workspace is page-aligned and must satisfy:</p> <pre><code>0x26000 + inplace_memory &lt;= staged_package_start &lt; 0xD4000\n</code></pre> <p>The old bootloader already reads and validates that encoded detools geometry before its first destructive write. The previous application receiver was the limiting part: it reserved a fixed <code>0x98000</code> workspace before accepting a download. Step 1 therefore remains byte-for-byte identical to the physically passed 89,844-byte package. Step 2 is a 46,364-byte fixed-workspace package that installs the compatibility receiver. Later receivers stage above the real EndF image extent and let the bootloader enforce each package's selected workspace.</p> <p>Every package in this candidate is an ordinary application container using format ABI 2 and in-place codec 2. The historical bridge applications scan the bootloader capability marker byte-by-byte, so they recognize the released <code>0.9.2-OTAFIX2.4</code> marker at absolute address <code>0xFCD16</code>. That immutable marker advertises ABI 2, codec mask <code>0x0004</code>, and internal storage profile 0. The <code>3f6eddd5</code> endpoint retains the matching legacy application-update fallback. Its separately compiled internal bootloader-update feature remains unavailable because privileged self-update requires a current ABI 3 marker with the exact storage profile. Installing this chain therefore does not replace the bootloader, and the final application can still accept a future valid ABI-2/codec-2 application update.</p> <p>The exact installed bootloader is the <code>0.9.2-OTAFIX2.4</code> RAK4631 asset. Its outer ZIP SHA-256 is <code>5e29e7a8982cc2ed5f8868435556eb09387250fe5b9a7e8443bac325247dfed1</code>; its 191,040-byte <code>sd_bl.bin</code> SHA-256 is <code>a97f834388db0f1da6c29f6d8f458ff6d3e6a26034709044566384838919bb23</code>. The exact simulator was compiled from release commit <code>d73de8372e89b8ef352747c8bc7a1aaeab80fbfe</code>; its executable SHA-256 is <code>9dacf24b1023fe2f4c620419417649ccc9538dd4a611b47bc19b7fedb97ceba6</code>.</p> <p>The schema-2 exhaustive search checked 1,799 candidate geometries and found 12 feasible forward edges in the declared exact 12-node inventory. It found one shortest ten-package route and selected the smallest total container bytes as the secondary objective. This minimum applies only to that declared inventory and geometry table, not every conceivable new bridge image. The selected route is:</p> Step From To Workspace Package Margin 1 1.16.7.0 1.16.7.9 <code>0x98000</code> 89,844 0 2 1.16.7.9 1.16.7.10 <code>0x98000</code> 46,364 40,960 3 1.16.7.10 1.16.8.7 <code>0x91000</code> 106,029 12,288 4 1.16.8.7 1.16.9.105 <code>0x89000</code> 149,927 0 5 1.16.9.105 1.16.9.110 <code>0x8E000</code> 111,312 16,384 6 1.16.9.110 1.16.9.113 <code>0x8F000</code> 120,624 4,096 7 1.16.9.113 1.16.9.117 <code>0x8B000</code> 139,637 0 8 1.16.9.117 1.16.10.0 <code>0x7E000</code> 174,202 20,480 9 1.16.10.0 1.17.1.3 <code>0x6B000</code> 271,569 0 10 1.17.1.3 1.17.1.6 <code>0x76000</code> 197,825 28,672 <p>Total mOTA transfer data is 1,407,333 bytes. <code>ROUTE.json</code>, <code>CHAIN.csv</code>, and <code>validation-results.json</code> in the bundle pin the exact geometry and image hash for every transition.</p> <p>Steps 1-9 are byte-for-byte identical to the transitions that passed on the physical RAK3401. The replacement step 10, from the physically reached <code>FE65A6135A1E7B3F</code> v1.17.1.3 body to <code>9BD7CF682EE065AE</code>, has offline qualification only. All ten packages passed independent container checks, zero-filled and erased-workspace reconstruction, and the exact deployed <code>0.9.2-OTAFIX2.4</code> simulator. Those results prove the package bytes and apply geometry; they are not a physical claim for the replacement step 10 or the hardened runner.</p> <p>The 171-byte transport DEFLATE support lands only in the final <code>3f6eddd5</code> application. The starting receiver and every receiver that accepts steps 1-10 lack that inflate path, so all ten legacy-chain transfers remain raw and the 1,407,333-byte total above is not automatically reduced over LoRa. A later update can negotiate transport compression after this endpoint is running; the application inflates before staging, and the immutable bootloader still applies an ordinary ABI-2/codec-2 container.</p>"},{"location":"rak3401_mota_chain/#host-requirements","title":"Host requirements","text":"<p>Install Python 3.9 or newer, <code>meshcli</code> 1.6.0 or newer, the current <code>motatool</code>, and an OTA-enabled Full Companion or repeater that can seed mOTA files.</p>"},{"location":"rak3401_mota_chain/#verify-offline","title":"Verify offline","text":"<p>No password or device is needed:</p> <pre><code>python3 tools/lora_ota/rak3401_mota_chain.py \\\n  --bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip \\\n  --work-dir ./rak3401-mota-chain-work \\\n  --motatool /path/to/motatool \\\n  --verify-only\n</code></pre> <p>When given the ZIP, the runner checks its pinned outer hash and binds the extraction cache to that exact archive. An explicitly supplied extracted root starts at the pinned inner checksum list. In either case it checks complete inner coverage, all ten manifests, continuity, image anchors, both recovery images, and every container with <code>motatool</code>. Passing this command means offline and simulator qualification only; it does not unlock live use.</p>"},{"location":"rak3401_mota_chain/#guarded-prerelease-lab-command","title":"Guarded prerelease lab command","text":"<p>These direct-link arguments match the physical transition setup, but the current package replaces step 10 and the current host runner contains later cleanup and recovery fixes. Neither has been cleanly rerun through the whole chain. Keep local USB/SWD recovery available. The candidate switch bypasses only the prerelease-status block; all identity, checksum, bootloader, route, watchdog, reachability, and post-boot gates still run.</p> <p>Restore the test start locally with <code>recovery/test-start/RAK3401-test-start-v1.16.7-c1caa5ad.uf2</code>, then run:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='password'\n\npython3 tools/lora_ota/rak3401_mota_chain.py \\\n  --bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip \\\n  --work-dir ./rak3401-mota-chain-work \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.51:5001 \\\n  --source-cli-tcp 192.168.1.51:5002 \\\n  --source-shares-controller \\\n  --target-key 63d8df63 \\\n  --temp-radio 909.950,500,5,5,120 \\\n  --ota-hops 0 \\\n  --legacy-full-airtime \\\n  --motatool /path/to/motatool \\\n  --accept-test-candidate \\\n  --yes\n</code></pre> <p>Keep the work directory. Rerunning the same command resumes only when the live EndF body hash matches an exact chain node. Never manually skip a package. <code>--legacy-full-airtime</code> temporarily sets the destination airtime factor to zero and restores it at the endpoint. Use that option only where the selected frequency and local duty-cycle rules permit a full transmit budget; omit it otherwise.</p>"},{"location":"rak3401_mota_chain/#superseded-b40d2e6c-prerelease","title":"Superseded <code>b40d2e6c</code> prerelease","text":"<p>The immediately preceding prerelease remains pinned for offline provenance:</p> <ul> <li>release: <code>rak3401-mota-v1.16.07-c1caa5ad-to-v1.17.1.5-b40d2e6c</code></li> <li>asset: <code>RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.5-b40d2e6c.zip</code></li> <li>outer ZIP SHA-256: <code>8e7f0c2565f37d4372fa51dc3ba72b591e7f38b74be09303e48641623f99bce4</code></li> <li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>29a02a6c4c83eafa80168a80562b0ded5d8432e6cc02cfaca289cb2ed426681a</code></li> <li>endpoint image SHA-256: <code>a7761da8af1f2447d7f01d72e2b1456b99c0e874a165d6483f48ab1f58e8d905</code></li> <li>endpoint EndF body hash: <code>1FA6AAA3C28D8BD8</code></li> </ul> <p>Its first nine packages are byte-for-byte identical to the current release and the physical <code>fd98bc90</code> evidence. Its different step 10 had offline qualification only. The runner recognizes this exact archive separately and keeps live use gated; it is not interchangeable with the current <code>3f6eddd5</code> asset.</p>"},{"location":"rak3401_mota_chain/#legacy-fd98bc90-physical-and-swd-qualification","title":"Legacy <code>fd98bc90</code> physical and SWD qualification","text":"<p>The earlier local candidate remains the exact physical evidence source for this route:</p> <pre><code>RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.5-fd98bc90.zip\n</code></pre> <ul> <li>candidate ZIP SHA-256: <code>c0b33f4568985e8b2b8dc99411295907212cf2bad21764b6333d5e0ba298fd61</code></li> <li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>3f8c4af8096b96a4aa6506825c387cc8a06f74d5213a29c9387bd11689546881</code></li> <li>endpoint image SHA-256: <code>31c182c888ceb1135e5afb2376610d93cee2e807b556c838e07fd4486c79d095</code></li> <li>endpoint EndF body hash: <code>9179B98432895924</code></li> </ul> <p>All ten exact <code>fd98bc90</code> transitions completed on the RAK3401 with its deployed <code>0.9.2-OTAFIX2.4</code> bootloader and a Heltec V4 source at 909.950 MHz / 500 kHz / SF5 / CR5. Every intermediate EndF hash matched. Independent SWD readback then matched the endpoint application, original bootloader, SoftDevice/MBR, and UICR byte-for-byte. Steps 1-9 are also the exact first nine packages in the <code>b40d2e6c</code> and <code>3f6eddd5</code> prereleases. All three candidates have different step 10 packages or endpoints, so the physical result and step-10 timing must not be attributed to either later prerelease.</p>"},{"location":"rak3401_mota_chain/#measured-direct-link-timing-for-fd98bc90","title":"Measured direct-link timing for <code>fd98bc90</code>","text":"<p>The first <code>ready to install</code> transfer ages were:</p> Step Blocks Transfer 1 88 598 s 2 45 42 s 3 103 81 s 4 146 105 s 5 109 76 s 6 118 94 s 7 136 102 s 8 170 127 s 9 264 187 s 10 169 193 s <p>The physically observed bulk-transfer total for those exact legacy packages is 1,605 seconds (26m45s). The log came from the pre-cleanup-fix runner revision. Step 1 was measured before the host began forcing source RXPS off and is therefore a conservative outlier. A new complete run with that fix is projected at roughly 18\u201319 minutes of bulk transfer, but that projection is not a substitute for the measured total. Allow about 70\u201375 minutes direct at BW500 for validation, ten transfers, installs/reboots, retained-store checks, and final restoration.</p> <p>The legacy step 10's longer per-block time was not a V4 TempRadio delay: the source RXPS readback was off. Its v1.17.1.3 requester uses non-overlapping adaptive flights and a five-second recovery floor and logged more block reloads than step 8. The V4 itself intentionally schedules its local radio handoff after 1.5 seconds so the normal-channel command reply can drain; the host waits three seconds and then checks the live TempRadio state.</p>"},{"location":"rak3401_mota_chain/#live-progress-and-speed-sanity-checks","title":"Live progress and speed sanity checks","text":"<p>The runner watches <code>motatool serve -v</code> locally, so its quarter-progress reports do not consume LoRa airtime. At BW500 direct, physically measured steps 2\u20139 averaged about 1.1\u20131.4 newly requested payload blocks per second; the legacy step 10 averaged about 0.88 blocks/s, and step 1's 0.15 blocks/s was the known pre-RXPS-fix outlier. Use those only as bench sanity ranges, not guarantees. Relays, narrower bandwidths, interference, and recovery reads lower the rate.</p> <p>Healthy output keeps advancing from <code>[download] passive source progress x/y</code> to <code>source read all y payload blocks</code>, followed by destination status <code>ready to install y/y (100%)</code> for the same manifest ID. Aggregate reads above the unique block count indicate recovery/retry traffic. A radio-scaled no-progress window causes one destination status check; the transfer timeout leaves the partial download staged for an exact-package resume. Stop and diagnose instead of installing if the manifest changes, progress remains flat through those checks, the final receiver count is not <code>y/y</code>, or the measured rate is far below the matching bandwidth/hop estimate without an understood RF cause.</p> <p>For planning only, scale the conservative measured <code>fd98bc90</code> 26m45s bulk baseline by the qualified adaptive-preamble airtime and by each additional relay transmission:</p> Bandwidth, SF5/CR5 Direct / 0 relays 1 relay 2 relays 500 kHz 26m45s 53m30s 1h20m15s 250 kHz 46m51s 1h33m42s 2h20m33s 125 kHz 1h27m03s 2h54m07s 4h21m11s 62.5 kHz 2h54m07s 5h48m15s 8h42m23s <p>These are transfer-only estimates, not measured alternate-bandwidth or relay results. Packet loss, relay contention, discovery, administrative commands, staged verification, and ten reboot cycles add time. The bandwidth factors are not simple powers of two because the adaptive wire preamble is 128 symbols at 500 kHz, 64 at 250 kHz, and 32 at 125/62.5 kHz.</p>"},{"location":"rak3401_mota_chain/#manual-operation","title":"Manual operation","text":"<p>The automated runner is preferred because it binds every transition to the expected MID and body hash. The manual details below document the checks used during qualification and recovery; they are not permission to skip the runner's candidate gate. Keep a written copy of each original setting and never skip a step even when a later package appears in <code>ota ls</code>.</p>"},{"location":"rak3401_mota_chain/#1-verify-and-extract-the-asset","title":"1. Verify and extract the asset","text":"<pre><code>sha256sum RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip\nunzip RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip\ncd RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5\nsha256sum -c SHA256SUMS.txt\nfor package in motas/*.mota; do motatool verify \"$package\" || exit 1; done\n</code></pre> <p>The outer hash must be <code>135783dd8777490db2422a7543f7d80e3cf03f621d5ac362da930abbc1850dc4</code>, and the SHA-256 of the extracted <code>SHA256SUMS.txt</code> must be <code>93835ed497c579be0a2322292e7f15ab095e7c8ab7892833fe7df3130dbdaba4</code>. Do not continue after any checksum or verification error.</p>"},{"location":"rak3401_mota_chain/#2-record-and-prepare-the-destination","title":"2. Record and prepare the destination","text":"<p>Before changing anything, save the complete replies from:</p> <pre><code>ver\nota self\nget bootloader.ver\nget system.watchdog\nget radio.rxps\nget powersaving\nget rxdelay\nget af\nota config\n</code></pre> <p>The starting <code>ota self</code> hash must be <code>71F4026CBE4B8B74</code>, the target must be <code>2FA509C1</code>, and the hardware must be <code>RAK_3401</code>. Disable the nRF52 system watchdog before the chain:</p> <pre><code>set system.watchdog off\n</code></pre> <p>The hardware watchdog cannot stop immediately. The RAK will reset once within about 60 seconds. Reconnect, wait at least 90 seconds from the command, and require <code>get system.watchdog</code> to report <code>&gt; off</code> before continuing.</p> <p>For a direct bench link, apply these temporary transfer guardrails to the RAK after every bridge reboot:</p> <pre><code>set powersaving off\nset radio.rxps off\nset rxdelay 0\nota config hops 0\ntempradio 909.950,500,5,5,120\n</code></pre> <p>Where local duty-cycle rules permit it, <code>set af 0</code> can also remove the legacy firmware's saved airtime wait during this bounded maintenance window. Record <code>get af</code> first and restore that exact value after the final step. Current firmware grants the bounded TempRadio transfer budget without overwriting the saved airtime factor.</p> <p><code>set powersaving off</code> is an isolation guardrail, not the fix for the observed failure. The actual source failure was an oversized USB CDC reply; current firmware splits those reads. Some historical bridge builds may report RXPS as unsupported while already operating continuously. Verify the reported state and do not substitute a normal reboot for the one-time watchdog reset. Direct tests use <code>hops 0</code>: <code>hops 1</code> makes the target echo each source response despite there being no intermediate relay, increasing half-duplex loss and legacy three-second retries.</p> <p>The exact candidate cannot use fast RXPS throughout because its historical bridge applications predate the v1.17.1.5 adaptive-preamble contract. Keep RXPS off for all ten steps whether using SF5/BW250 or the faster direct-bench SF5/BW500 tuple. After the final endpoint is proven, a later update whose target, controller, source, and relays are all v1.17.1.5 or newer can use the generic LoRa OTA runner and its qualified adaptive-preamble boundaries.</p> <p>Put the source on the identical TempRadio tuple. A current ASCII-first Full Companion recognizes <code>motatool</code>'s initial <code>ota folder on</code> line directly:</p> <pre><code>motatool serve \\\n  --dir ./motas \\\n  --serial /dev/ttyACM1 \\\n  --baud 115200 \\\n  -v\n</code></pre> <p>The same command also works with older Full Companion firmware in binary mode, where the idle parser recognizes the identical preamble. Restart <code>motatool</code> for every step so the source emits a fresh catalog advert. Leave it running during the download and stop it with Ctrl-C only after the destination reports <code>ready to install</code>.</p>"},{"location":"rak3401_mota_chain/#3-install-all-ten-packages-in-order","title":"3. Install all ten packages in order","text":"Step Manifest ID Before hash Expected version After hash 1 <code>C147BCEF</code> <code>71F4026CBE4B8B74</code> <code>1.16.7.9</code> <code>42BC53A64288E845</code> 2 <code>BEB578FC</code> <code>42BC53A64288E845</code> <code>1.16.7.10</code> <code>1AD2AA8B6C478DA6</code> 3 <code>6D8EF814</code> <code>1AD2AA8B6C478DA6</code> <code>1.16.8.7</code> <code>D709A25308BC1831</code> 4 <code>40AC4CEB</code> <code>D709A25308BC1831</code> <code>1.16.9.105</code> <code>457BEDA5E6406C81</code> 5 <code>F6C8890B</code> <code>457BEDA5E6406C81</code> <code>1.16.9.110</code> <code>E76BFA205634CAB8</code> 6 <code>82405E89</code> <code>E76BFA205634CAB8</code> <code>1.16.9.113</code> <code>65328FC8A1FBED2D</code> 7 <code>80F40DB6</code> <code>65328FC8A1FBED2D</code> <code>1.16.9.117</code> <code>AF7532E13337FADD</code> 8 <code>DBF6310D</code> <code>AF7532E13337FADD</code> <code>1.16.10.0</code> <code>22002359BBDFA76E</code> 9 <code>C2979E08</code> <code>22002359BBDFA76E</code> <code>1.17.1.3</code> <code>FE65A6135A1E7B3F</code> 10 <code>B5011420</code> <code>FE65A6135A1E7B3F</code> <code>1.17.1.5</code> <code>1FA6AAA3C28D8BD8</code> <p>For each row, first prove that <code>ota self</code> exactly matches its Before hash, then inspect the manager before changing it:</p> <pre><code>ota status\n</code></pre> <p>Proceed to discovery only after that status is reconciled. When the manager is idle, run:</p> <pre><code>ota ls\nota pull MANIFEST_ID flash\nota status\n</code></pre> <p>If the first status reports this row's MID as partial, use <code>ota pull</code> with that same MID to resume it. If this row's MID is already ready, do not pull or cancel it; continue with the install checks below. If status reports the immediately previous row's MID as <code>verifying staged blocks</code>, wait through the bounded discovery window; require either that exact MID to become <code>ready to install</code> or the manager to become <code>no download</code>, and re-prove the current Before hash. Cancel only the same previous MID while it is visibly attached and ready. If it has become idle, send no cancel. Stop on any other MID, failed or incomplete state, ambiguous reply, or timeout. Never issue a blind <code>ota cancel</code>: it can discard a resumable or unrelated session.</p> <p>Repeat <code>ota status</code> at a restrained interval until it says <code>ready to install</code>. If the manifest is initially absent, wait for a fresh source advert, run <code>ota ls</code> again, or restart <code>motatool</code>; do not pull a different ID. Stop the seeder and install:</p> <pre><code>get system.watchdog\nota install\n</code></pre> <p>The watchdog reply must still be <code>&gt; off</code>. Allow the current default five-minute readiness window for the USB/LoRa identity to return; automation probes every 10 seconds and returns early as soon as the exact body is visible. Then run <code>ver</code>, <code>ota self</code>, and <code>ota help</code>. Require the row's exact After hash, require <code>bootloader: apply OK</code>, and require <code>rescue install &lt;hash16&gt;</code> in the help before exposing that bridge to the next package. This rescue-help gate applies to steps 1-9; step 10 is the endpoint and is not exposed to another package in this chain. A normal-radio <code>ota status</code> response of <code>no download</code> proves only that the manager is idle; legacy internal-flash firmware does not durably erase a retained container by accepting an IDLE <code>ota cancel</code>. Do not claim otherwise. When the same expected manifest reports <code>verifying staged blocks</code> after the next TempRadio starts, wait only for the bounded discovery window and require that it become <code>ready to install</code> or <code>no download</code>; stop on a changed ID, failed/incomplete state, or timeout. Prove the exact running body before cancelling an attached completed session. OTAFIX consumes the approval word during a successful install, so a retained endpoint container is inert and a later valid pull replaces it. Reapply the transfer guardrails and TempRadio tuple, restart <code>motatool</code>, and continue with the next row.</p> <p>If the board boots but <code>ota self</code> says the EndF is invalid, stop. Only when <code>ota status</code> still identifies that row's complete staged package may the guarded <code>ota rescue install BEFORE_HASH</code> command be used. It is not a force option and must use that row's exact Before hash. If the board does not boot, recover the documented start/recovery UF2 locally over USB. Step 10 is the endpoint and has no successor package in this chain. If its EndF is invalid, use local DFU/SWD rather than attempting an unqualified LoRa package.</p>"},{"location":"rak3401_mota_chain/#4-intermediate-relays-and-restoration","title":"4. Intermediate relays and restoration","text":"<p>On every managed intermediate relay, save <code>get rxdelay</code> and <code>get txdelay</code>, then use the airtime-scaled collision window during the maintenance session:</p> <pre><code>set rxdelay 0\nset txdelay 0.3\n</code></pre> <p>Current OTA transfer packets honor that configured relay <code>txdelay</code>; setting <code>0.3</code> gives competing relays a small randomized, airtime-scaled forwarding window. The source's manifest-fragment gap independently follows active packet airtime and duty spacing, clamped to 100-1000 ms. These two delays solve different problems.</p> <p>After step 10 is proven, restore each saved destination and relay value exactly, including <code>rxdelay</code>, RXPS, CPU power saving, <code>af</code>, <code>ota config hops</code>, and relay timing. Current full-parser repeater firmware accepts <code>normalradio</code> and restores the saved tuple after replying on the temporary channel:</p> <pre><code>normalradio\n</code></pre> <p>The <code>b40d2e6c</code> endpoint supports that command. If a recovery build unexpectedly replies <code>Unknown command</code>, shorten its lease to one minute with the same tuple:</p> <pre><code>tempradio 909.950,500,5,5,1\n</code></pre> <p>Wait for the lease to expire, return the controller and ordinary source to their saved normal channels, and then re-enable the RAK system watchdog:</p> <pre><code>set system.watchdog on\nget system.watchdog\n</code></pre> <p>A Full Companion source is the exception: its local TCP console supports <code>normalradio</code> and the automated runner uses it before restoring the shared Binary API radio tuple.</p> <p>Final lab success requires version <code>v1.17.1.5-halo-keymind-cascade-dev-b40d2e6c</code>, body hash <code>1FA6AAA3C28D8BD8</code>, target <code>2FA509C1</code>, hardware <code>RAK_3401</code>, and <code>get system.watchdog</code> reporting <code>&gt; on</code>. If a relay cannot be restored before its TempRadio lease ends, wait for it to return to the normal channel and restore its saved <code>rxdelay</code> and <code>txdelay</code> there.</p>"},{"location":"rak3401_mota_chain/#two-relay-deployment","title":"Two-relay deployment","text":"<p>The first nine direct package transitions above were physically observed as the byte-identical first nine transitions of the legacy chain. Replacement step 10, this hardened host-runner revision, and multi-hop operation are not cleanly end-to-end physically qualified. A controlled, recoverable multi-hop lab can exercise two intermediate relays by listing them farthest-to-nearest and using three OTA hops. Run a non-mutating preflight first; even preflight requires the prerelease candidate override because the command connects to live devices:</p> <pre><code>python3 tools/lora_ota/rak3401_mota_chain.py \\\n  --bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.5-b40d2e6c.zip \\\n  --work-dir ./rak3401-mota-chain-work \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp SOURCE_IP:5001 \\\n  --source-cli-tcp SOURCE_IP:5002 \\\n  --source-shares-controller \\\n  --target-key 63d8df63 \\\n  --relay 'Far Repeater' \\\n  --relay 'Near Repeater' \\\n  --temp-radio 909.950,250,5,5,120 \\\n  --ota-hops 3 \\\n  --motatool /path/to/motatool \\\n  --accept-test-candidate \\\n  --preflight-only\n</code></pre> <p>After preflight succeeds, rerun with <code>--yes</code> in place of <code>--preflight-only</code>. Confirm that the selected frequency and bandwidth are legal at the deployment location.</p>"},{"location":"rak3401_mota_chain/#rescue-and-completion","title":"Rescue and completion","text":"<p>The guarded <code>ota rescue install &lt;base_body_hash&gt;</code> command is present after step 1 and remains available through the step-9 bridge. It is not a force command: it refuses a valid normal EndF, a base mismatch, wrong target/hardware, or invalid payload. A failure before step 1 completes still requires local USB recovery because the deployed start image predates the rescue command. The final <code>b40d2e6c</code> endpoint uses the stricter shared-slot profile; its invalid-EndF recovery is local DFU/SWD, not the rescue command.</p> <p>Before the first mutation, the runner saves the destination's RXPS periods, CPU power-saving state, RX flood delay, airtime factor, and OTA hop reach in the persistent work directory, flushing both the file and its directory entry before changing a guardrail. It also saves the managed source's exact RXPS preference in the chain-root <code>source-rxps-settings.json</code> before disabling it. Every step reuses that protected record, so a rerun after a killed host process restores the chain-start preference instead of treating the temporary off state as original. The record is accepted only for the same CLI endpoint. The runner retires that chain-root record only after it has proved the source is back on its normal radio and restored the exact preference at the verified endpoint. The runner reads the destination, controller, source, and relay versions before applying the same RXPS policy as the generic runner. The mixed historical chain therefore verifies <code>radio.rxps off</code> after every bridge reboot; a future all-v1.17.1.5-or-newer SF5/BW250 chain would instead keep RXPS on under the qualified level-8/preamble-64 boundary. It also verifies <code>set powersaving off</code> and <code>rxdelay 0</code>, plus <code>af 0</code> when <code>--legacy-full-airtime</code> was explicitly selected. It restores every original value only after the exact endpoint is proven. An interrupted run deliberately leaves those transfer guardrails active; rerun the same command with the same work directory to resume and restore them. CPU power saving was not the cause of the observed folder-source failure: that was a USB CDC receive-ring overrun fixed by bounded serial reads. The runtime settings remain conservative isolation and fast-link reliability guardrails.</p> <p>For every named <code>--relay</code>, the per-step runner also captures <code>rxdelay</code> and <code>txdelay</code>, writes them to <code>relay-timing-settings.json</code>, applies <code>rxdelay 0</code> and <code>txdelay 0.3</code> during transfer, verifies the readback, and restores both before the relay leaves TempRadio.</p> <p>The runner also keeps the watchdog off across the chain, rechecks identity and OTA reach before every package, requires the exact post-boot EndF hash, and only re-enables the watchdog after step 10. Lab success requires endpoint body hash <code>1FA6AAA3C28D8BD8</code>, target <code>2FA509C1</code>, hardware <code>RAK_3401</code>, normal radio <code>910.525 MHz / 62.5 kHz / SF7 / CR5</code>, and the watchdog verified on.</p>"},{"location":"rak3401_mota_chain/#external-radio-startup-and-manual-usb-recovery","title":"External-radio startup and manual USB recovery","text":"<p>RAK3401 is a distinct target from RAK4631. Its RAK13300/RAK13302 radio is on the WisBlock SPI bus (<code>SPI1</code> in the Adafruit nRF52 core), with BUSY and DIO1 on P0.09/P0.10. Current builds explicitly enable those NFC-capable pads as GPIO and do not advertise the radio bus as an on-board QSPI flash device.</p> <p>The RAK13302's FEM and boost supply use switched <code>3V3_S</code>, but the SX1262 core uses unswitched 3V3. An MCU reset, a 1200-baud DFU touch, or disconnecting only USB may therefore leave a battery-powered SX1262 in its previous state. At startup, current firmware quiesces the FEM, reinitializes the dedicated SPI instance, asserts NRESET, and, if BUSY remains high, sends the Semtech NSS/GET_STATUS wake sequence without waiting on RadioLib first. The one-time board startup cold-starts <code>3V3_S</code>; later radio retries leave that shared rail enabled so they do not reset GPS or sensor modules.</p> <p>If BUSY still cannot be released, firmware must not enter a reset loop:</p> <ul> <li>Companion starts its USB/BLE management services after three bounded probes,   uses nRF52 hardware entropy if it needs a first-boot identity, and retries the   radio every 60 seconds. Radio statistics remain zero until recovery.</li> <li>Repeater keeps the same USB CDC session open and prints   <code>Radio unavailable; retrying in 60 seconds</code>. It repeats the board-level probe   in place. The normal repeater CLI and mesh transport cannot start until the   radio responds.</li> </ul> <p>A permanently high BUSY after NRESET and the direct wake transaction indicates an electrically unavailable radio, loose module, or power-domain fault; an MCU reboot cannot manufacture a response. If local access is possible, disconnect the battery as well as USB and reseat the WisBlock module. Remote firmware will continue retrying without requiring that physical intervention or churning the USB device.</p> <p>For an existing deployed tower using Preview 5, do not change the bootloader as part of this application chain. Its exact local recovery package is the Preview 5 RAK4631 ZIP. For a new RAK3401 installation or local recovery, use the OTAFIX 2.4.3 RAK3401 ZIP from the OTAFIX 2.4.3 release. These are local DFU/SWD recovery assets, not mOTA chain steps.</p> <p>For a local Serial DFU recovery with the repository helper:</p> <pre><code>cd /path/to/meshfirmware\nMCFIRMWARE_NO_SUDO=1 ./mcfirmware.sh\n</code></pre> <p>Select the serial entry whose USB identity is <code>WisCore RAK3401 Board</code>, then choose Custom, nrf52, and the exact RAK3401 <code>.zip</code>. Use flash-update to preserve InternalFS preferences and identity. Use flash-wipe + flash only when erasing application data is intentional. The helper follows the same USB device into bootloader mode, so do not substitute another <code>/dev/ttyACM*</code> merely because its number appears first.</p>"},{"location":"role_feature_switches/","title":"Feature switches by role \u2014 1.17.1.5 USA Cascade","text":"<p>Use these settings with the exact board's canonical release image. Former logging, power-saving, FEM-gain, and rotated-display variants are now runtime choices where the hardware supports them. A setting cannot add missing radio hardware, MQTT code, storage, or an OTA partition. Check the download's <code>.capabilities.json</code> and the firmware picker. For exact old device/variant names, search the 1.17.1.5 variant map: it maps all 1,361 previous release entries to 1,325 covered choices or 36 excluded entries. Many old choices share one current image; the command tables below explain how to select their former behavior. Excluded entries have no download.</p> <p>Search terms are alternative wording for finding these instructions, not CLI aliases. Use the commands in the role-specific tables and examples.</p>"},{"location":"role_feature_switches/#open-the-usb-web-console","title":"Open the USB web console","text":"<p>Search terms: USB terminal, serial console, ASCII terminal, browser terminal, web serial.</p> <p>Open the MeshCore USB web console in Chrome or Edge, connect a data-capable USB cable, close other applications using that port, and select the device. Use 115200 baud when prompted. Full Companion, Repeater, Room Server, and Sensor start with an ASCII USB terminal. Run <code>board</code>, then <code>ver</code> on any role.</p> <p>If a Companion app has already switched USB to its binary protocol, send:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>To hand the port back to a Companion app or USB MOTA host, send <code>+++MESHCORE-TERM-STOP</code>, close the console, and connect the app/tool. Dedicated USB/BLE/WiFi Companion images can start in binary mode; use the start token there too. KISS firmware uses its modem protocol and is outside this release.</p> <p>The linked console runs in your computer's browser over USB. It does not need node WiFi or <code>set webui on</code>. WebConfig is a separate settings website served by supported ESP32 images. Both infrastructure and WiFi Companion WebConfig include a browser command terminal (<code>set wifi.cli on</code>), enabled by default on the LAN. The Companion browser CLI uses the same terminal commands as USB, including contact import, chat, recipient selection, and streaming replies. Full ESP32 Companion also exposes this terminal at TCP port 5002. See the terminal command guide.</p>"},{"location":"role_feature_switches/#which-old-variant-setting-should-i-use","title":"Which old variant setting should I use?","text":"<p>Search terms: old firmware variants, restore features, turn features on or off, enable MQTT, disable MQTT.</p> <p>These controls apply to every board with the corresponding compiled feature; check the hardware requirements below.</p> Former choice Current image / runtime control USB logging or Station G2/G3 logging variant Same role's canonical image; <code>set usb.logging on</code> / <code>off</code> USB logging, WiFi MQTT, or both MQTT-capable image with USB logging; <code>set logging.output usb</code>, <code>wifi</code>, <code>both</code>, or <code>off</code> Companion WiFi-MQTT variant <code>set mqtt.enabled on</code> / <code>off</code>; configure broker slots through the CLI or WebConfig <code>_ps</code> power-saving variant <code>set powersaving on</code> / <code>off</code>; check <code>get powersaving</code> on every role <code>_femoff</code> / FEM-gain variant <code>set radio.fem.rxgain on</code> / <code>off</code>; separate TX switch where controllable RX boost variant <code>set radio.rxgain on</code> / <code>off</code> on a supported radio iKOKA rotated-display variant Full Companion: <code>set display.rotation 180</code>; <code>0</code> restores the board default Separate USB, BLE, WiFi, Ethernet, or Terminal Chat Companion Exact board's Full Companion where listed; supported transports are included, with SenseCAP selection below RS232 repeater variant consolidated into the ordinary repeater <code>set bridge.enabled on</code> / <code>off</code> on a build containing the RS232 bridge ESP-NOW bridge or primary ESP-NOW radio Select the matching hardware/role image first; bridge and primary-radio channel commands differ LoRa OTA / external-storage variant Still choose the exact receiver/storage image and matching bootloader; this is not a software on/off switch <p>Companion, Repeater, Room Server, and Sensor use the same command names for shared settings. Use <code>get &lt;setting&gt;</code> to check and <code>set &lt;setting&gt; &lt;value&gt;</code> to change them. A command requires its feature to be compiled into the build. <code>set usb.logging on|off</code> changes only USB logging. On MQTT-capable builds, <code>set mqtt.enabled on|off</code> changes only MQTT and keeps broker settings; <code>set logging.output off|usb|wifi|both</code> selects both outputs together.</p>"},{"location":"role_feature_switches/#full-companion-commands","title":"Full Companion commands","text":"Setting Enable / select Disable / restore Read back Device power saving <code>set powersaving on</code> <code>set powersaving off</code> <code>get powersaving</code> LoRa RX power saving <code>set radio.rxps on</code> <code>set radio.rxps off</code> <code>get radio.rxps</code> Radio RX boost <code>set radio.rxgain on</code> <code>set radio.rxgain off</code> <code>get radio.rxgain</code> External FEM RX gain <code>set radio.fem.rxgain on</code> <code>set radio.fem.rxgain off</code> <code>get radio.fem.rxgain</code> External FEM TX gain <code>set radio.fem.txgain on</code> <code>set radio.fem.txgain off</code> <code>get radio.fem.txgain</code> ESP32 USB logging <code>set powersaving off</code>, then <code>set usb.logging on</code> <code>set usb.logging off</code> <code>get powersaving</code>, <code>get usb.logging</code> nRF52 second USB logging port <code>set usb.logging on reboot</code> <code>set usb.logging off reboot</code> <code>get usb.logging</code> MQTT master <code>set mqtt.enabled on</code> <code>set mqtt.enabled off</code> <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, <code>get mqtt.status</code> ESP32 persistent WebConfig <code>set webui on</code> <code>set webui off</code> <code>get webui</code> ESP32 WebConfig browser console <code>set wifi.cli on</code> <code>set wifi.cli off</code> <code>get wifi.cli</code> ESP32 temporary setup AP <code>start webconfig ap</code> <code>stop webconfig</code> <code>get webui</code> Display rotation <code>set display.rotation 90</code>, <code>180</code>, or <code>270</code> <code>set display.rotation 0</code> <code>get display.rotation</code> Temporary MOTA radio window <code>tempradio 910.525,250,5,5,120</code> <code>normalradio</code> <code>tempradio</code> <p>Saved settings apply immediately unless noted. Rotation and gain controls report unsupported hardware instead of creating that feature. Fresh Full Companion preferences enable device power saving and leave USB logging off; existing saved preferences win after an update.</p> <p>ESP32: logging and binary Companion traffic share one USB port. Turn logging off before handing USB to an app/MOTA host. nRF52: the optional second CDC port is for logs; use the primary port for Companion/MOTA. Adding/removing the second port requires a reboot; the optional suffix shown above requests it.</p>"},{"location":"role_feature_switches/#mqtt-controls-shared-by-companion-and-infrastructure","title":"MQTT controls shared by Companion and infrastructure","text":"<p>Search terms: Companion MQTT settings, MQTT on, MQTT off, broker configuration.</p> <p>Configure a broker through the MQTT tab or with the same commands on either role. For example:</p> <pre><code>set mqtt.iata SEA\nset mqtt1.preset custom\nset mqtt1.server broker.example.com\nset mqtt1.port 1883\nset mqtt.enabled on\nget mqtt.enabled\nget mqtt.running\nget mqtt.status\n</code></pre> <p><code>set mqtt.enabled off</code> disconnects brokers while preserving their settings. <code>set mqtt.enabled on</code> allows configured brokers to reconnect. An enabled switch is separate from a running connection: check <code>get mqtt.running</code> and <code>get mqtt.status</code>. The MQTT tab's Enable MQTT checkbox controls this same saved switch. Slot credentials and presets are available through <code>get/set mqtt1.*</code>, <code>mqtt2.*</code>, and the remaining supported slots; secrets stay masked in the browser. WiFi Companion accepts these commands through its USB terminal and browser CLI; Full Companion also accepts TCP port 5002.</p> <p><code>set mqtt1.preset none</code> disables just that slot. Publication controls such as <code>set mqtt.status off</code> do not disconnect brokers. USB logging is independent. Images without MQTT code do not show MQTT cards or accept MQTT controls.</p>"},{"location":"role_feature_switches/#companion-wifi-bluetooth-gps-and-board-exceptions","title":"Companion WiFi, Bluetooth, GPS, and board exceptions","text":"<p>Configure ESP32 WiFi with:</p> <pre><code>set wifi.ssid MyNetwork\nset wifi.pwd my-password\nget wifi.status\n</code></pre> <p><code>set wifi.powersave min</code> enables WiFi modem sleep; <code>none</code> disables it. <code>max</code> is accepted only where the BLE/WiFi coexistence policy allows it. Read back with <code>get wifi.powersave</code>. This is separate from device power saving and RXPS. The assigned WiFi button/display switch controls WiFi services on supported boards. <code>stop webconfig</code> closes only the portal; it is not a WiFi master switch. There is no universal Bluetooth-off or Ethernet-off text command.</p> <p>SenseCAP Indicator Full only: <code>set companion.transport wifi</code> followed by <code>reboot</code> selects WiFi; <code>set companion.transport ble</code> followed by <code>reboot</code> selects Bluetooth. Check <code>get companion.transport</code>. USB remains available. Primary ESP-NOW Indicator images keep their mesh radio in either selection.</p> <p>GPS-equipped builds: use <code>get gps</code>, <code>set gps on</code>, and <code>set gps off</code> on Companion and infrastructure. The Companion app's <code>gps=1</code> / <code>gps=0</code> custom setting controls the same GPS. See GPS tracking for location-sharing settings.</p>"},{"location":"role_feature_switches/#repeater-room-server-and-sensor-commands","title":"Repeater, Room Server, and Sensor commands","text":"<p>These roles use CommonCLI. Feature-dependent commands require the relevant hardware/build; MQTT is present in observer builds, and WebConfig is absent from some portable builds. The USB browser console still works without it.</p> Setting Enable Disable Read back Live USB logging ESP32 1.17.1.5: <code>set powersaving off</code>, then <code>set usb.logging on</code>; other platforms: <code>set usb.logging on</code> <code>set usb.logging off</code> <code>get powersaving</code>, <code>get usb.logging</code> Capture RX log to node storage <code>log start</code> <code>log stop</code> <code>log</code> prints the capture locally RS232 / ESP-NOW bridge master <code>set bridge.enabled on</code> <code>set bridge.enabled off</code> <code>get bridge.enabled</code>, <code>get bridge.running</code>, <code>get bridge.type</code> MQTT periodic status publication <code>set mqtt.status on</code> <code>set mqtt.status off</code> <code>get mqtt.status</code> shows connection status MQTT packet publication <code>set mqtt.packets on</code> <code>set mqtt.packets off</code> <code>get mqtt.packets</code> SNMP on supported MQTT infrastructure <code>set snmp on</code>, then <code>reboot</code> <code>set snmp off</code>, then <code>reboot</code> <code>get snmp</code> MQTT raw packet publication <code>set mqtt.raw on</code> <code>set mqtt.raw off</code> <code>get mqtt.raw</code> MQTT receive capture <code>set mqtt.rx on</code> <code>set mqtt.rx off</code> <code>get mqtt.rx</code> MQTT transmit capture <code>set mqtt.tx on</code> (or <code>advert</code>) <code>set mqtt.tx off</code> <code>get mqtt.tx</code> MQTT master <code>set mqtt.enabled on</code> <code>set mqtt.enabled off</code> <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, <code>get mqtt.status</code> ESP32 persistent WebConfig <code>set webui on</code> <code>set webui off</code> <code>get webui</code> WebConfig browser command terminal <code>set wifi.cli on</code> <code>set wifi.cli off</code> <code>get wifi.cli</code> LoRa RX power saving <code>set radio.rxps on</code> <code>set radio.rxps off</code> <code>get radio.rxps</code> Radio RX boost <code>set radio.rxgain on</code> <code>set radio.rxgain off</code> <code>get radio.rxgain</code> Controllable FEM RX / TX gain <code>set radio.fem.rxgain on</code> / <code>set radio.fem.txgain on</code> <code>set radio.fem.rxgain off</code> / <code>set radio.fem.txgain off</code> Corresponding <code>get radio.fem.rxgain</code> / <code>get radio.fem.txgain</code> GPS, when compiled <code>set gps on</code> <code>set gps off</code> <code>get gps</code> <p>Use <code>set usb.logging on|off</code> on every role. Adding the optional <code>reboot</code> suffix requests a reboot only when changing the USB interfaces requires it, as on nRF52 Full Companion. <code>log start/stop</code> records to storage independently of live USB logging. Use <code>log erase</code> to delete that capture.</p> <p>For ESP32 1.17.1.5 USB logging, run these as separate commands in the role's text terminal (or remote admin CLI on infrastructure):</p> <pre><code>set powersaving off\nset usb.logging on\nget powersaving\nget usb.logging\n</code></pre> <p>Check for power saving <code>off</code> and USB logging <code>on</code>. This avoids the released ESP32 USB sleep bug, including the G3 report. Both settings are saved; turning logging off later does not automatically restore power saving. LoRa RXPS is independent. nRF52 logging does not need this ESP32 workaround.</p> <p>With the G3 sleep correction, enabled live USB logging keeps ESP32 USB serviced and blocks light sleep, including when a host closes the port or disconnects. CPU idle/yield remains available. <code>set usb.logging off</code> removes that blocker; an attached native USB host still prevents sleep. On Full infrastructure, <code>set logging.output usb</code> and <code>both</code> enable the same USB blocker; <code>wifi</code> and <code>off</code> remove it. File capture with <code>log start</code> is independent. The original 1.17.1.5 binaries require the <code>set powersaving off</code> workaround described in the release note.</p>"},{"location":"role_feature_switches/#shared-mqtt-and-logging-output","title":"Shared MQTT and logging output","text":"<p>Search terms: MQTT settings, MQTT on, MQTT off, logging output, USB and WiFi logging.</p> <p>On any Companion or infrastructure build with both MQTT and USB logging compiled:</p> Command USB logs MQTT bridge <code>set logging.output off</code> Off Off <code>set powersaving off</code>, then <code>set logging.output usb</code> On Off <code>set logging.output wifi</code> Off On <code>set powersaving off</code>, then <code>set logging.output both</code> On On <p><code>get logging.output</code> reports the selection. Fresh unified Full infrastructure preferences select <code>both</code>; Full Companion starts with USB logging off. Saved settings override these defaults. To toggle only MQTT while keeping USB logging unchanged, use <code>set mqtt.enabled off</code> / <code>on</code>. Neither setting turns LoRa repeating off. Repeater forwarding uses <code>set repeat off</code> / <code>on</code> and <code>get repeat</code> separately.</p> <p>The <code>set powersaving off</code> step above is the 1.17.1.5 ESP32 USB workaround. WiFi/MQTT-only logging does not need it while the Repeater/Room Server MQTT bridge is running: that sleep guard already exists in the released firmware. Use <code>get mqtt.running</code> to check that MQTT is running; an enabled preference alone is not the running state. <code>set logging.output wifi</code> keeps USB logging off and uses that MQTT guard.</p> <p>For a custom broker on an MQTT-capable Companion, Repeater, or Room Server:</p> <pre><code>set wifi.ssid MyNetwork\nset wifi.pwd my-password\nset mqtt.iata SEA\nset mqtt1.preset custom\nset mqtt1.server broker.example.com\nset mqtt1.port 1883\nset mqtt.enabled on\nget mqtt.status\n</code></pre> <p>Set <code>mqtt1.username</code> / <code>mqtt1.password</code> if required by that broker. Configure only as many slots as the board supports. <code>set mqtt1.preset none</code> disables slot 1; other configured slots remain enabled, within the build's supported slot count. Disabled and partially configured slots remain saved across reboot. For a custom server URL, <code>set mqtt1.port 0</code> clears the port override so the URI supplies it. <code>set mqtt.status off</code> disables status messages, not MQTT itself. See the MQTT reference for presets, TLS, credentials, and slot limits.</p>"},{"location":"role_feature_switches/#infrastructure-power-saving-and-bridges","title":"Infrastructure power saving and bridges","text":"<p>Use <code>get powersaving</code>, <code>set powersaving on</code>, and <code>set powersaving off</code> on every role. The preference is saved. Hardware and active USB/network services decide when sleeping is possible; the command names do not change between roles. Device power saving is separate from WiFi modem sleep and LoRa RXPS.</p> <p>On RS232-capable repeater images, stop the bridge before changing its serial port or baud rate, then restart it:</p> <pre><code>set bridge.enabled off\nset bridge.baud 115200\nset bridge.enabled on\n</code></pre> <p>RAK4631: <code>set bridge.uart 2</code> selects UART2 while the bridge is stopped. Canonical GPS-enabled builds reserve UART1 for GPS; UART1 requires a dedicated GPS-free image. ESP-NOW bridge: use <code>set bridge.channel &lt;1..13&gt;</code> and <code>set bridge.format wrapped</code> / <code>raw</code> where supported. Primary ESP-NOW mesh: use <code>set espnow.channel &lt;1..13&gt;</code> and reboot; this is a different radio setting.</p> <p>For infrastructure WebConfig on the LAN, use <code>start webconfig</code> / <code>stop webconfig</code>. To force a setup AP on an observer, first run <code>set mqtt.enabled off</code>, then <code>start webconfig ap</code>. When finished, run <code>stop webconfig</code> and restore <code>set mqtt.enabled on</code> if you did not reboot.</p>"},{"location":"role_feature_switches/#updating-and-sending-mota","title":"Updating and sending MOTA","text":"<p>Search terms: mOTA, LoRa OTA, update over LoRa, wireless firmware transfer.</p> <p>All released Full Companions can serve MOTA to other nodes. Close the console and run <code>motatool serve --serial /dev/ttyACM0 --dir ./motas -v</code> on the USB host. See Full Companion instructions for WiFi/BLE source commands and the bounded temporary radio setup.</p> Role / hardware Start self-update Stop / requirement ESP32 Repeater, Room Server, Sensor with WiFi updater <code>start ota</code> or <code>start ota ap</code>; open the returned URL (normally port 80, <code>/update</code>) <code>stop ota</code>; close WebConfig first if it shares port 80 ESP32 Full Companion with two application slots <code>start ota</code> or <code>start ota ap</code>; returned URL uses port 8080, <code>/update</code> <code>stop ota</code>; single-slot Full builds use USB nRF52 infrastructure with Bluetooth DFU <code>start ota</code> enters the Bluetooth update flow Matching application DFU ZIP and board bootloader required Qualified LoRa OTA receiver Follow LoRa OTA directions Exact destination package, storage profile, and overlapping temporary radio windows <p>For nRF52 OTAFIX installations use the exact board/storage build from OTAFIX 2.4.6. Its retained-RAM handoff is required by the new internal-flash hybrid receiver images. Full Companions are sources and remain normally USB-updated.</p> <p>The complete infrastructure CLI, role/build matrix, and Full Companion feature guide provide details.</p>"},{"location":"s3_memory_soak_validation/","title":"ESP32-S3 OTA memory experiment","text":"<p>This experiment compares the current static S3 OTA workspace (A) with <code>OTA_HEAP_CONTEXT=1</code> (B), with WiFi and a real TLS MQTT connection enabled. It is isolated on <code>experiment/s3-ota-memory-soak</code>; published recipes retain their existing defaults. A short stress test cannot establish months of uptime.</p>"},{"location":"s3_memory_soak_validation/#hardware-and-scope","title":"Hardware and scope","text":"Board Role Flash PSRAM Lab identity Heltec V4.3 OLED, standard V4 Observer/MQTT repeater 16 MiB 2 MiB QSPI USB MAC <code>44:1B:F6:69:CF:98</code> Original SenseCAP Indicator LoRa Full companion plus experimental MQTT 8 MiB 8 MiB octal WiFi MAC <code>D8:3B:DA:75:23:AC</code> Seeed XIAO ESP32-S3 with WIO LoRa Observer/MQTT repeater 8 MiB 8 MiB octal MAC <code>28:84:85:B4:09:80</code>, Windows COM31 <p>This is not an R8 test. Both Indicator variants use the same 320x320 canvas; the native 480x480 Full-plus-MQTT configuration is not qualified by this run. One custom TLS MQTT slot per board publishes only to the isolated Pi broker. These results do not qualify five concurrent slots, JWT renewal, heavy RF traffic, every OTA receive/apply path, or months of operation.</p>"},{"location":"s3_memory_soak_validation/#reproducible-builds","title":"Reproducible builds","text":"<p>Base commit: <code>bc0fb2c335938c97220de51098cea6162f2f0fe0</code>, following PR #7's merge. Copy <code>tools/hil/s3_memory_soak.ini</code> to ignored <code>platformio.local.ini</code> and build the six named environments sequentially, with <code>MESHCORE_ESP32_FULL_BUILD=1</code>. Never run multiple PlatformIO processes in this checkout. Archive each image, ELF, map, partitions, bootloader, and memory report before the next build.</p> <p>The private broker's public CA must be in <code>ssl_certs</code> while generating these experimental images. Remove it and <code>platformio.local.ini</code> afterward. Private keys stay on the Pi. WiFi credentials and the Windows logger token are in private local files; do not commit them or the generated certificate bundle. Broker certificate verification remains enabled.</p> <p>The V4 and XIAO lab recipes also enable <code>MESH_SOAK_WIFI_KEY_OVERRIDE</code> and require the ignored local header <code>tools/hil/S3SoakWiFiKey.h</code>. To reproduce diagnostics using ordinary WiFi credentials, remove that define from the lab recipe; the private header is then unnecessary. Published recipes do not enable either lab flag.</p> Image Application bytes Link-time available internal bytes SHA-256 V4 A 1,910,392 237,360 <code>68c2749e0ea40db91d953f6355010bc602f85424526ca6acbe1cad7fd11c8630</code> V4 B 1,911,256 252,760 <code>6847ad4ad6bac2e558b8aed67de37417a497972391f13a71e0a42b5c9704dcff</code> Indicator A 2,313,256 244,248 <code>3d0ac27f95ddc54a32b59a3892d157713dcded285dbeb98d1bdfdb1ce0b951ab</code> Indicator B 2,314,136 255,496 <code>83045d7ec48befc43f3460c08c68b71da037a5476e14dd59def5706fc5a1b07e</code> XIAO A 1,845,000 238,448 <code>6fcc657c5ccbc5dd3d53a0cf1ceebde54479d59d329f8625e7cb7141a27d9ed8</code> XIAO B 1,845,912 253,864 <code>2b233e42e0c515b152ce83ca8fe38b1f35780970bb6350dbadf2591b6a2699a1</code> <p>All six firmware builds passed their RAM/flash gates. The linked internal capacity gain is 15,400 bytes on V4, 11,248 bytes on Indicator, and 15,416 bytes on XIAO. This is capacity returned while idle, not a reduction in peak OTA allocation needs. Both A/B variants keep the existing MQTT client reuse policy and internal MQTT task stack; this experiment does not move that stack into PSRAM.</p>"},{"location":"s3_memory_soak_validation/#instrumentation","title":"Instrumentation","text":"<p><code>MESH_SOAK_DIAGNOSTICS</code> exposes local-only <code>get soak</code>, <code>soak ota-cycle</code>, and <code>soak wifi-drop</code> commands. They report free/largest/minimum internal heap, free PSRAM, OTA context size/presence, WiFi state, and uptime. No published recipe enables these controls.</p> <p>The lab network has a valid 64-digit raw WiFi key. Production MQTT preferences currently accept only 63 characters. The V4 experiment uses a separate, test-only NVS key through <code>MESH_SOAK_WIFI_KEY_OVERRIDE</code>, without changing the production binary preference layout. This does not fix released raw-key input. The network's original nine-character passphrase was subsequently recovered from the connected Windows profile; XIAO uses it through ordinary settings. The override is compiled into both XIAO images but no override key is stored.</p> <p>The Pi logger owns one persistent V4 USB handle: opening this particular USB device resets it, even with DTR/RTS disabled. Firmware installations and logger restarts therefore begin new uptime runs. Indicator telemetry uses TCP 5002. The logger distinguishes the 49.7-day <code>millis()</code> rollover from a reboot.</p> <p>Passive samples omit <code>get mqtt.stats</code>: its outbox query can block behind the MQTT client lock during a TLS handshake and stall the CLI. The logger reads <code>get mqtt.status</code> and separately counts messages received through a verified TLS subscription. It stores topic counts, not MQTT payloads or credentials.</p> <p>Two exploratory rapid-flap runs used an overly short 90-second recovery cutoff. The first also used the blocking outbox probe. Preserve those pilot results; do not count them as successful tests. Production MQTT backoff deliberately grows to five minutes and clears after two stable connected minutes, so rapid flapping is not equivalent to repeated independent connection tests.</p>"},{"location":"s3_memory_soak_validation/#results-and-continuing-soak","title":"Results and continuing soak","text":"<p>V4 and Indicator both passed the matched A/B workload: 200 explicit OTA context acquire/release attempts, four MQTT bridge restarts, one WiFi reconnection and one five-second private-broker outage per image. An initial bridge restart preconditions each run. No unexpected uptime resets occurred in these runs. A was paused after its four bridge restarts to investigate the display report, then resumed for the network faults; its elapsed duration includes that pause.</p> <p>After the workload, with WiFi and one TLS MQTT slot connected:</p> Board A free internal bytes B free internal bytes Gain A largest block B largest block Standard V4 95,396 111,040 15,644 (15.28 KiB) 81,908 98,292 Indicator 107,168 118,520 11,352 (11.09 KiB) 94,196 106,484 XIAO (same saved settings, cold boot) 151,028 166,444 15,416 (15.05 KiB) 139,252 147,444 <p>Free heap varies with network activity; link-time capacity is the cleaner measurement of storage moved out of static RAM. PSRAM remained about 2.01 MB on V4 and 6.33 MB on Indicator. In each B run the OTA context returned to absent after the allocation workload. Neither board's largest block shrank through those 200 allocation cycles or the reconnect workload. WiFi/MQTT recovery took about 4.3 seconds on A and 3.8 seconds on B; broker recovery took about 19.5 and 21.8 seconds respectively. These are single observed recovery times.</p> <p>Workspace recreation has an observed latency cost. The 200 command cycles took approximately 189 seconds on V4 B and 379 seconds on Indicator B, versus 32 and 15 seconds on A. This includes command transport, OTA initialization, and ordinary firmware service, so it is not an allocator microbenchmark. The static comparator already owns an initialized workspace; the dynamic variant recreates it. This experiment does not claim faster OTA startup, and this cost should be checked against real session use before a default change. Code inspection shows that <code>OtaContext::begin()</code> calls <code>ota_self_firmware()</code>, which scans the running ESP32 application for its EndF identity on each call. All six experimental images contain valid EndF trailers. Caching immutable boot identity is a candidate for a separate change, not part of these results.</p> <p>The real WiFi mOTA folder endpoint was tested separately on Indicator: 20 empty-folder sessions on A and 40 on B. All completed and B released its context. During B's first batch, free internal RAM went from 118,552 to 116,316 bytes, and its largest block from 106,484 to 102,388. A second batch ended at 116,308 bytes with the same 102,388-byte largest block. This retained allocation/layout change is not explained by the now-absent OTA context; record it separately and watch it during the soak. It did not keep growing in the second batch.</p> <p>The original A folder script also tried V4, whose observer recipe has no TCP 5001 folder source. Its overall result therefore says <code>passed: false</code>, despite Indicator completing all 20 sessions. That endpoint mismatch is preserved in the evidence; it is not an OTA failure on V4. The corrected script targets only the Indicator. These empty-folder checks do not qualify a full firmware transfer.</p> <p>XIAO passed 200 context cycles, four bridge restarts and one WiFi reconnect per image, with no unexpected reset. Its largest block stayed unchanged within each workload. WiFi/TLS recovered in about six seconds for both. This local test did not inject a separate broker outage or exercise a TCP folder endpoint. Verified subscriptions on the Pi confirmed actual TLS publications for both.</p> <p>The first XIAO A run followed initial device configuration and finished with 126,140 internal bytes free, which would have overstated the OTA saving. It is preserved as <code>xiao-live/A-configuration-stress.json</code>. Reflashing A without an erase, retaining exactly the saved settings used by B, and rerunning the whole workload produced the 151,028-byte baseline above. Its resulting gain exactly matches the 15,416-byte linked-capacity change. The earlier larger gap is not credited to OTA storage; the precise retained allocation was not isolated.</p> <p>The Pi stores evidence under <code>/home/mikec/hwtest/runs/s3-memory-soak</code>:</p> <ul> <li><code>telemetry.jsonl</code>: append-only memory, WiFi/MQTT state, uptime, transport errors.</li> <li><code>latest.json</code>: latest samples plus broker-side received-message counts.</li> <li><code>A-stress.json</code> / <code>B-stress.json</code>: matched stress results and phase boundaries.</li> <li><code>A-folder.json</code> / <code>B-folder.json</code>: real WiFi mOTA empty-folder session checks.</li> <li><code>B-repeat-folder.json</code>: the extra batch checking the initial allocation change.</li> </ul> <p><code>meshcore-memory-soak.service</code> holds the USB connection and samples each minute. <code>meshcore-soak-broker.service</code> supplies the private TLS broker. Both are enabled on the Pi. The logger never reboots a board to hide a firmware failure, but reopening the V4 USB transport can itself reset it; inspect transport counts, service restarts, and uptime together when diagnosing any interruption. The final passive phase started at <code>2026-09-11T07:18:07Z</code>. Installing the final logger revision (which serializes concurrent samples) deliberately restarted the service and therefore reset V4 once. That begins its long-soak uptime run; Indicator retained its uptime. Both then reported WiFi/TLS connected, absent OTA contexts, and actual broker-side publications.</p> <p>The local XIAO logger owns COM31 and writes under <code>C:\\git\\MeshCore\\out\\s3-memory-soak\\xiao-live</code>. Its control endpoint is loopback-only with a private token. It runs while this Windows session remains alive; it is not a Pi service and will not survive a computer shutdown. A separate verified TLS subscription on the Pi confirmed XIAO publications for both images. The Pi logger's per-device counts cover V4 and Indicator only. The final XIAO B passive phase was verified at <code>2026-09-11T07:21:21Z</code>, with 166,508 free internal bytes, a 155,636-byte largest block, WiFi/TLS connected, and no active OTA context. The largest block differs from the post-stress sample because this is a fresh boot, which illustrates why comparisons must use the same workload history. A Pi subscription received its publication two seconds later.</p> <p>Read-only checks on the Pi:</p> <pre><code>systemctl is-active meshcore-memory-soak meshcore-soak-broker\ncat /home/mikec/hwtest/runs/s3-memory-soak/latest.json\n</code></pre> <p>On Windows, read <code>out/s3-memory-soak/xiao-live/latest.json</code>. Keep the computer awake for continuous local samples. Neither logger automatically reboots a radio in response to a failed sample.</p> <p>The public lab CA was removed from <code>ssl_certs</code>, and the temporary local PIO configuration and generated test trust bundle were removed after building. Archived experimental firmware and public evidence remain in ignored <code>out/s3-memory-soak</code>; no test CA enters the published build configuration.</p> <p>No published default has changed. Leave the experimental B images running to collect longer evidence before deciding whether to expand S3 heap allocation. More idle internal RAM gives WiFi/TLS useful headroom; it does not itself prove stability or eliminate the need to allocate the OTA workspace during use.</p>"},{"location":"s3_memory_soak_validation/#physical-display-checks","title":"Physical display checks","text":"<p>The user reported unresponsive screens during MQTT restart testing. The V4 lit after temporarily choosing <code>on</code>; after restoring battery and USB profiles to <code>button</code>, 15 seconds, the user confirmed that pressing the button wakes it. The synchronous reconnect/diagnostic work may have delayed UI service, but the exact cause of the original visual report was not established.</p> <p>The T096 is a separate nRF52840 board, USB identity <code>651F8E496197F882</code>. It was reflashed with current Full firmware and briefly instrumented. The trace showed the radio, sensor and UI loop advancing; the display had initialized but was marked off. Its functional CDC0 was in Binary mode after a host-session close. Sending a newline-delimited <code>+++MESHCORE-TERM-START</code> restored ASCII control. With display mode set to <code>on</code>, the user confirmed the normal screen appeared. Temporary tracing was removed by reinstalling the non-instrumented image, and battery/USB profiles were restored to <code>button-pairing</code>, 15 seconds. The user then confirmed that its button wakes the normal screen after timeout.</p> <p>T096 recovery firmware: <code>v1.17.1-t096-check</code>, Full/shared OTA queue, <code>-Os</code> size profile, available linked internal RAM 99,892 bytes (73,728 required). ZIP SHA-256 <code>f5cfcb001efda559ae9b4e7b105ac9766a604808f5fd708b7c533f8a11c64578</code>. No device-wide filesystem erase was needed for this recovery. T096 does not count as an S3 A/B test.</p> <p>Host validation: <code>python -m unittest discover -s tools/hil -p test_s3_memory_soak.py</code>. The five checks cover diagnostic filtering, missing data, resets, and counter rollover. They are not substitutes for the hardware evidence.</p>"},{"location":"separated_radio_modulation_cache_validation/","title":"Separated radios, normal XIAO RX gain, and unchanged-modulation timing","text":"<p>Measured 2026-09-14 on <code>keymindCascade</code>, base commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> plus local changes.</p> <p>The unchanged-modulation optimization reduces XIAO frequency-only retunes from 548.880 to 451.897 us (17.7%) in a same-image control. The separated four-channel SF6 test still misses packets. Separation and disabling XIAO boosted gain were changed together; their RF effects are not isolated.</p>"},{"location":"separated_radio_modulation_cache_validation/#settings-and-controls","title":"Settings and controls","text":"<ul> <li>XIAO ESP32-S3/WIO SX1262 COM31 receiver; SenseCAP Indicator ESP32-S3 COM28   reference transmitter. The user moved the radios apart; distance and   attenuation were not measured. RAK4631 and Indicator RP2040 untouched.</li> <li>XIAO HIL build has <code>SX126X_RX_BOOSTED_GAIN=0</code>; actual RX gain register   readback was 0x94 in initial info, every stationary arm, and every scan   status. Indicator remains 0x96. Normal XIAO production default is unchanged.</li> <li>32-symbol preamble, CR4/5, 16-byte synthetic packets, -9 dBm, buffered 8 MHz   SPI. Four scan centers 909.500/909.750/910.000/910.250 MHz.</li> <li>No guard shortening, forced retunes through packets, RF retransmissions,   new public N-channel protocol, or additional oscillator-delay bypass.</li> </ul>"},{"location":"separated_radio_modulation_cache_validation/#same-image-receive-only-timing-ab","title":"Same-image, receive-only timing A/B","text":"<p>Each board ran four three-second windows in off/on/on/off order, rebooting between windows. SF6/125 kHz, four channels, 2,612 us nominal dwell, no extra IRQ tracing, no TX. A HIL-only hook invalidates just the acknowledged modulation tuple before each baseline hop. Optimized windows use production cache behavior. The binary and all other settings remain identical per board.</p> <p>Time is entry to the production retune through BUSY-low observation. It does not include the listening dwell or full application scheduling, and is not an independent RF settling measurement. Unlike the older mixed-bandwidth tests, this frequency-only workload can skip 0x8B.</p> Board / policy Hops Mean Min\u2013max Actual 0x86 / 0x8B writes XIAO, always write 1,898 548.880 us 535\u2013663 us 1,898 / 1,898 XIAO, reuse unchanged tuple 1,957 451.897 us 441\u2013580 us 1,957 / 0 Indicator, always write 564 8,263.438 us 8,228\u20138,428 us 564 / 564 Indicator, reuse unchanged tuple 602 7,601.193 us 7,583\u20137,762 us 602 / 0 <p>Pooled means are sample-weighted from reported per-window means. Savings are 96.983 us (17.7%) for XIAO and 662.246 us (8.0%) for Indicator. All 5,021 hops passed RX-mode/software-cache checks with zero retune errors or deferrals. Counters observe outgoing SPI opcodes, not merely which software branch ran. Initial setup before counter snapshots is excluded. The Indicator remains above the common 6 ms switching allowance; no common timing budget changed.</p>"},{"location":"separated_radio_modulation_cache_validation/#stationary-rf-controls","title":"Stationary RF controls","text":"<p>Full initialization before every case, fixed RX at 910 MHz, ordinary RX with fast reuse disabled, shuffled offsets, 450 ms capture windows. Method matches the earlier investigation.</p> TX offset SF6 preamble windows SF8 preamble windows Silent 0/4 0/8 On frequency 4/4 8/8 -250 kHz 0/4 1/8 +250 kHz 0/4 1/8 -500 kHz 0/4 2/8 +500 kHz 0/4 0/8 -1,000 kHz 0/4 0/8 +1,000 kHz 0/4 0/8 <p>All 12 on-frequency probes delivered valid payloads. No off-frequency header or valid payload, silent preamble, device/read error, foreign valid payload, or trace overflow occurred. SF6 off-channel detections changed from 1/24 to 0/24; SF8 from 32/48 to 4/48. These are small bounded samples, not sensitivity or packet-error-rate estimates. On-frequency instantaneous RSSI was -41 to -40 dBm at SF6 and -42 dBm at SF8: the signal remains strong and readings are not calibrated attenuation measurements. Improvement cannot be attributed solely to separation or solely to normal gain.</p>"},{"location":"separated_radio_modulation_cache_validation/#four-channel-sf6125-51-symbol-visits","title":"Four-channel SF6/125, 5.1-symbol visits","text":"<p>Same image, baseline then optimized, reboot both boards between runs. Each requested 100 packets/channel with varied unsynchronized arrival timing and stopped at its first miss. Extra nominal 64 us IRQ polling was enabled here, unlike the receive-only timing windows. No higher channel count was tested.</p> Policy Received before first miss Failed channel Timed hops Mean retune Always write 0x8B 24, then probe 25 missed 1 / 909.750 MHz 4,746 551.253 us Reuse unchanged tuple 51, then probe 52 missed 1 / 909.750 MHz 7,748 455.157 us <p>Optimized RF run: 7,697 hops omitted 0x8B, averaging 453.081 us; 51 hops reapplied it after received packets, averaging 768.529 us. These are different RX lifecycle paths, not a pure 315 us command-cost comparison. Both runs had one frequency write per hop and no RX-mode/cache/retune errors. Successful packets read -42 to -40 dBm with SNR 10.0\u201311.5 dB. Neither met 100/100 on every channel. More packets before the first miss does not establish a reliable improvement in packet-error rate.</p> <p>The baseline miss captured a target-channel preamble at 176,194 us after arming, 1,830 us after a hop onto that channel. A guard held it there; no header or packet followed. An IRQ clear was observed at 195,025 us and the next hop completed at 195,240 us. This is not the earlier SF8 wrong-channel hold: the preamble was observed on the intended channel. Its RF source and reason for failing to progress remain unproven.</p> <p>The optimized miss captured 3,256 hops over ten seconds with no observed nonzero IRQ and no guard hold, reproducing the pre-acquisition symptom of the earlier SF6 miss. Target-channel revisit intervals were 12.249\u201312.324 ms (mean 12.286 ms), shorter than the 16.384 ms programmed preamble, yet no packet was acquired during those short individual visits. This does not establish that additional post-retune settling is needed. Trace buffers did not overflow. TX returned success for both failed probes; the MCU clocks are not synchronized and there was no independent RF capture.</p>"},{"location":"separated_radio_modulation_cache_validation/#provenance","title":"Provenance","text":"<p>RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both targets built and uploads were verified. These captures precede the subsequent SF5/250 bandwidth-selector addition.</p> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>8aa79da891409c9e600ce14c1d83a8d73c3198225a2aaf799fc884247e882fab</code></li> <li>Indicator: <code>868946d0beca882d8f215c1556c0c19bf41908baac6620dc5632c3fca85b5feb</code></li> </ul> <p>Raw files in <code>tools/hil</code>, preserved byte-for-byte:</p> File SHA-256 XIAO timing <code>45e7a640323a3c9028b6c92a5128e51307db1bd94a4846e8744d3c3ec098adfd</code> Indicator timing <code>f0a85826f500b3a9173bf22c6207fbfba3b6cb17f3d70b849a9fe7621ae3dfc5</code> Stationary SF6 <code>1d981e5af41eabbc43f92641813bf8f7c5e7015439f5ba53ce0467fe6477d3f3</code> Stationary SF8 <code>36e63da7435d0a16f61db7db7730893de392d028feca7a96960fd17ae1fa624b</code> SF6 baseline scan <code>cbfd200170891b334ef3958479694c6e318146993b94073eb9aee981f97fde97</code> SF6 optimized scan <code>d88a621ef9aa358ce52bb3efb6aa9c4bcb77c681af20b2c66e4aebf3721e17ca</code> <p>Fresh complete 8 MiB backups were saved and separately verified in the private current-user backup directory before testing. Restores had already started when the user requested leaving HIL firmware installed; those in-flight writes and verification finished safely. Both boards were subsequently loaded with the newer SF5/250 HIL build for the user's next sweep. Do not restore them again unless requested. No private backup contents were added to Git.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/","title":"SF10/125 full samples: 10 Hz versus 100 Hz first-pass detour","text":"<p>2026-09-14. Both 400-packet samples completed: 100 attempts on each of four channels, with no RF retries or early stop on misses. Payload loss was 64/400 (16.0%) at 10 Hz and 81/400 (20.25%) at 100 Hz. Strict same-channel reception was almost identical: 230/400 versus 231/400. The larger offset showed no improvement in this comparison.</p> <p>These are two sequential finite bench samples, not proof that the offset caused the difference in payload loss. The earlier stop-first tests could not provide this error-rate estimate and are not combined with these counts.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#settings-and-method","title":"Settings and method","text":"<ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, 28:84:85:B4:09:80.</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, B35E71C1C3726CE7.</li> <li>Uniform SF10, BW125 kHz, nominal CR4/5; 909.5, 910.5, 911.5, 912.5 MHz.</li> <li>32-symbol preamble; 5.1-symbol visits (41,780 us); zero added settling.</li> <li>Normal RX gain 0x94, -9 dBm chip TX request, 16-byte CHS1 payloads.</li> <li>Warm XOSC, bulk SPI, fast RX; TCXO setting 1600 us. No added IRQ tracing.</li> <li>Two full retunes per hop. First: selected positive RF offset, CR4/6.   Second: exact original RF command, CR4/5. Duplicate frequency writes   remain inside each pass: four RF commands, two modulation writes and   two optimized RX starts per completed hop.</li> <li>Requested 10 Hz = +10 integer RF-word steps, nominal 9.5367431640625 Hz.   Requested 100 Hz = +105 steps, nominal 100.13580322265625 Hz. Neither   depends on a float-MHz addition. This is programmed, not independently   spectrum-measured, frequency.</li> <li>Same receiver image for both runs; only the requested offset changed.   Order: 10 Hz, reboot, 100 Hz. TX firmware was unchanged.</li> <li>Seed 606125: shuffled channel order each round and varied arrival pauses.   Each run has 400 unique probe sequences and exactly 100 TXs per channel.</li> <li>Existing 10-second expectation timeout retained. A miss does not reset   the receiver, tune it toward TX, reset the visit clock or clear counters.   Hardware/guard/command failures still abort rather than become RF losses.</li> </ul> <p>The complete comparison ran from 21:09:11 to 21:42:39 UTC (14:09\u201314:42 PDT), about 33 minutes. The 10 Hz sample took about 15.4 minutes; 100 Hz about 18.0. The extra elapsed time is largely the additional ten-second timeouts.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#overall-results","title":"Overall results","text":"<p>\"Payload loss\" means no intact expected payload was delivered within the expectation window, regardless of reported RX channel. \"Strict error\" also counts intact payloads received while the scanner reports another channel.</p> Requested offset Attempts Correct-channel delivery Intact wrong-channel delivery Timeouts / payload loss Strict errors 10 Hz 400 230 (57.5%) 106 (26.5%) 64 (16.0%) 170 (42.5%) 100 Hz 400 231 (57.75%) 88 (22.0%) 81 (20.25%) 169 (42.25%) <p>All scored delivery failures were timeouts. The receiver also counted six packet-read errors at 10 Hz and eleven at 100 Hz. The error codes were not captured, so these cannot be identified specifically as CRC failures or mapped one-to-one to timeout probes. \"Zero invalid payloads\" in the summary does not mean there were no packet-read/CRC errors before timeout.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#per-channel-results","title":"Per-channel results","text":"<p>Each cell uses exactly 100 attempts. Loss counts therefore also equal percent.</p> Center (MHz) 10 Hz payload loss 100 Hz payload loss 10 Hz strict errors 100 Hz strict errors 909.5 10% 11% 26% 25% 910.5 23% 23% 51% 45% 911.5 19% 26% 48% 55% 912.5 12% 21% 45% 44% <p>The extra 17 payload losses at 100 Hz occurred on channels 0 (+1), 2 (+7) and 3 (+9). Correct-channel deliveries differed by only one packet overall. Neither offset eliminated wrong-channel acquisition/delivery or timeouts. This comparison does not isolate the underlying RF failure mechanism.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#switching-and-signal-measurements","title":"Switching and signal measurements","text":"Metric 10 Hz 100 Hz Completed hops 16,992 20,676 Mean complete two-pass switch 1263.765 us 1262.551 us Maximum complete switch 1533 us 1532 us Mean first pass 660.712 us 659.458 us Mean second pass 592.344 us 592.406 us RF commands 67,968 82,704 Modulation commands / RX starts 33,984 / 33,984 41,352 / 41,352 Maximum unheld four-channel cycle 174,139 us 173,722 us Maximum held channel visit 590,757 us 640,492 us Packet-read errors 6 11 <p>Unheld cycles fit within the 262,144 us programmed preamble; packet-related held visits can exceed it. Aggregate timing without IRQ traces does not prove which hold caused any particular timeout. The approximately 1.2 us difference in mean switching time is negligible here and does not explain the losses.</p> <p>All completed hops passed the internal first-offset/final-correction and CR command checks: 16,992/16,992 and 20,676/20,676, <code>detour.bad=0</code>. Second-pass blocks, retune failures, mode errors and cache errors were zero. Counts match four RF writes, two modulation writes and two RX starts per completed hop.</p> <p>Telemetry limitation: the diagnostic <code>detour.first_rf/first_mod</code> fields are updated on a guard-deferred first attempt as well as an applied attempt, while <code>final_rf/final_mod</code> retain the last completed second pass. Thus the final snapshot's displayed pair can be from different attempts and appears equal in these captures. Those fields must not be interpreted as the last verified pair. Verification itself runs only after two applied passes and increments <code>detour.n</code> only then; its per-hop comparisons, zero failures and matching counts establish the commanded sequence. Original capture bytes are retained.</p> Packet group 10 Hz mean RSSI / SNR 100 Hz mean RSSI / SNR Correct-channel delivery -34.05 dBm / +8.56 dB -34.15 dBm / +8.62 dB Intact wrong-channel delivery -105.18 dBm / -13.75 dB -105.22 dBm / -13.62 dB <p>The markedly weaker wrong-channel readings are observations, not proof of a specific filter/image/overload mechanism.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#implementation-and-verification","title":"Implementation and verification","text":"<p>The HIL scanner gained <code>scancontinue 1</code>, default off, so its ordinary completion and timeout accounting can leave scanning active. The host gained bounded <code>--continue-on-miss --max-channels 4</code> with separate delivery/strict summaries. <code>scandetouroffset 10|100</code> and <code>--first-pass-offset-hz 10|100</code> select the integer offset while stopped. Production radio defaults and receive guards were not changed. The controller is <code>tools/hil/profile_switch_offset_compare.py</code>.</p> <p>23 native profile tests and 51 host tests passed. Coverage includes continuing through all 400 attempts without restart/retry, balanced channels, separated error definitions, default first-miss behavior, aborting fixture failures, both integer offsets and exact restoration. Build/upload succeeded with hash verification: RAM 94,948 bytes, reported flash 370,213 bytes.</p> <p>There was one cached USB RX-result replay in each sample, with no RF retransmit. All TX commands returned success. Host/device strict receive and miss counters matched; both captures are complete under <code>fixed_sample_complete</code>. The master manifest is complete under <code>both_400_packet_samples_complete</code>, with no fixture or cleanup error.</p> <p>Both boards rebooted idle afterward. RX confirmed scanner inactive, zero channels, one-pass default, detour/continue disabled and normal gain 0x94. TX confirmed no autonomous TX. HIL remains installed; RAK COM29 was not opened. The temporary PlatformIO overlay was removed. No background collector remains. This work made no commits or pushes. Existing unrelated changes were preserved.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#provenance","title":"Provenance","text":"<ul> <li>Manifest: <code>tools/hil/profile_switch_sf10_10_vs_100hz_full_results.json</code>   SHA-256 <code>40ef9d70991b585abe6b99b3dc4878829412d55e0e8b5a984576b00db0326981</code></li> <li>10 Hz capture: <code>tools/hil/profile_switch_sf10_10_vs_100hz_full_results_10hz.json</code>   SHA-256 <code>889a7afeb980ec8459fccb8da5a7c496feebd433da8715f84181f02c1da613aa</code></li> <li>100 Hz capture: <code>tools/hil/profile_switch_sf10_10_vs_100hz_full_results_100hz.json</code>   SHA-256 <code>0b54a057c07f9da0b03f585aeffee960ffcfa2ecb5383914554697ca250aa071</code></li> <li>RX BIN SHA-256:   <code>bddf779208cbfd24478d39d3075f3f7537b7c9275453492748a349f3ec15b630</code></li> <li>Unchanged TX ZIP SHA-256 from the preceding validated upload:   <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> </ul> <p>Source: live keymindCascade working tree at HEAD <code>2b5a6f209835f0f67ed73fee78d36447a4566ce6</code>, plus existing dirty changes and these HIL additions. The RX image hash identifies the exact tested build. Earlier captures were not overwritten.</p>"},{"location":"sf10_10hz_cr_detour_validation/","title":"SF10/125: tiny first-pass frequency offset and coding-rate detour","text":"<p>2026-09-14. The requested offset no longer rounds to zero. Actual outgoing commands verified a +10-step RF-word change (nominal +9.536743 Hz), then exact restoration of the original word, with CR4/6 then CR4/5. Two passes averaged 1.259 ms in RX-only timing. The first packet still timed out. This is a bounded one-probe failure, not a 400-packet loss-rate estimate.</p>"},{"location":"sf10_10hz_cr_detour_validation/#scope-and-precision","title":"Scope and precision","text":"<p>The request was to apply a slightly different center frequency and coding rate on the first full retune, then the correct settings on the second, with about 0.01 kHz difference. At these centers a float in MHz advances in roughly 61 Hz increments: adding 0.00001 MHz can produce the same float.</p> <p>The HIL implementation does not make that float addition. A scoped integer offset changes the four-byte argument of the actual 0x86 frequency command by ten steps. The nominal SX1262 step is 32 MHz / 2^25; ten steps are 9.5367431640625 Hz, the nearest achievable nominal command offset to 10 Hz. See the frequency-step specifications in the Semtech SX1261/2 datasheet. Pinned RadioLib 7.7.1 also specifies this step and sets the standard sensitivity configuration bit for bandwidths other than 500 kHz. This establishes the programmed offset, not a spectrum-analyzer measurement of physical frequency.</p> <p>First pass: destination RF word + 10 and CR4/6. Second pass: original RF word and CR4/5. The offset is applied to both existing duplicate frequency writes inside the first pass. Caller buffers remain unchanged; a scoped restore prevents the offset leaking into the corrected pass or an unrelated command. Rollback applies the offset only when restoring the temporary CR4/6 tuple.</p> <p>Both passes retain ordinary packet/ownership/BUSY guards, command-result checks and RX startup. A blocked second pass fails the diagnostic rather than overriding a packet guard. Each completed hop verifies both outgoing frequency words and modulation words (0x0a040200 then 0x0a040100). The host requires a verification count equal to completed hops and zero mismatches.</p> <p>This feature is HIL-only, off on reboot. Production defaults were not changed. The earlier +31.25 kHz draft was superseded before flashing or RF testing.</p>"},{"location":"sf10_10hz_cr_detour_validation/#fixture-and-method","title":"Fixture and method","text":"<ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, 28:84:85:B4:09:80.</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, B35E71C1C3726CE7; unchanged firmware.</li> <li>Centers 909.5, 910.5, 911.5, 912.5 MHz; uniform SF10/BW125.</li> <li>32-symbol preamble, 5.1-symbol visits (41,780 us), no added settling.</li> <li>Normal RX gain 0x94; warm XOSC, bulk SPI and fast RX; TCXO setting 1600 us.</li> <li>16-byte CHS1 probes, -9 dBm chip TX request, varied arrival phase.</li> <li>Goal 100 packets/channel; stop at the first strict miss or 400/400.</li> <li>Four frequency commands, two forced modulation writes, two optimized RX   starts per completed hop. No extra IRQ tracing/polling.</li> </ul> <p>Same-image RX-only ABBA controls compare two identical full passes (A) with the first-pass detour followed by correction (B), six seconds each, rebooting between windows. This is not a comparison against the original single-pass approximately 0.53 ms cached-modulation path.</p>"},{"location":"sf10_10hz_cr_detour_validation/#timing","title":"Timing","text":"Window First-pass detour Hops Mean total (us) Maximum (us) First pass mean (us) Second pass mean (us) A1 Off 139 1230.094 1464 631.727 594.281 B1 On 139 1259.770 1490 647.165 603.245 B2 On 139 1258.806 1481 646.547 602.957 A2 Off 139 1230.597 1467 633.209 593.252 <p>Mean two-pass control 1230.346 us; detour/correction 1259.288 us, about 28.943 us additional total including configuration/verification bookkeeping. The detour passes themselves averaged 646.856 + 603.101 us. Both detour windows verified 139/139 completed hops with zero mismatches; all four windows had exactly 556 RF commands, 278 modulation commands and 278 RX starts, with zero guard blocks or RX/mode/cache errors.</p>"},{"location":"sf10_10hz_cr_detour_validation/#packet-result","title":"Packet result","text":"<p>Probe 1021099889, TX channel 3 at 912.5 MHz, timed out: 0 received / 1 attempted, then stopped. TX rc=0, setup 86,914 us, transmit call 529,297 us. RX was in receive mode, hardware device-errors=0. No payload-only diagnostic ran because this was a timeout, not an intact payload attributed to another channel. There were no RF retries.</p> <p>During that packet window:</p> <ul> <li>220 completed hops; 220 verified detour/correction pairs, zero mismatches.</li> <li>880 RF commands, 440 modulation commands, 440 optimized RX starts.</li> <li>Mean switch 1262.095 us, maximum 1507 us; first pass 652.082 us, second   601.295 us. Second-pass-blocked=0, retune failures=0, mode/cache errors=0.</li> <li>Maximum unheld four-channel cycle 172,222 us, below the 262,144 us preamble.</li> <li>Maximum held visit 542,732 us; the aggregate receive-error count was 1.   That counter means a packet read returned an error; this capture does not   retain its error code or IRQ trace, so it cannot establish CRC as the cause   or assign the hold to a particular channel. Device-errors=0 is a separate   hardware status and does not mean there were no receive errors.</li> </ul> <p>Across both detour timing windows and the packet window, 498/498 completed hops verified the nonzero first-pass RF offset, original final RF word and CR4/6-to-CR4/5 sequence. This proves the change was exercised; it did not resolve reception in this bounded test. The underlying RF failure remains unidentified.</p>"},{"location":"sf10_10hz_cr_detour_validation/#usb-setup-issue-and-verification","title":"USB setup issue and verification","text":"<p>The first controller attempt stopped before transmitting because the new 126-byte capability JSON plus CRLF formed an exact 128-byte native-USB reply. It remained buffered until another command was sent. This was preserved as a fixture failure, not counted as packet loss. A single LF-terminated write (127 bytes) fixed this specific reply; three independent reads then passed without a follow-up command, and the complete controller ran successfully.</p> <p>22 native profile tests and 49 host tests passed. Added tests cover integer carry, unchanged caller bytes, both SPI paths, observation of shifted wire bytes, exact restoration, scope exit/nesting, non-frequency commands, overflow, detour verification failures and the USB reply length. Build/upload passed with flash hash verification: RAM 94,948 bytes, reported flash 369,593 bytes. <code>git diff --check</code> passed (unrelated existing CRLF warning only).</p> <p>Both boards rebooted idle after completion. RX confirmed scanner inactive, zero channels, one-pass default, detour disabled, normal gain 0x94. TX reports no autonomous transmission. HIL firmware remains installed as requested. RAK COM29 was not opened. Temporary PlatformIO overlay removed; no collector left running. This experiment made no commits, pushes or production-default changes.</p>"},{"location":"sf10_10hz_cr_detour_validation/#provenance","title":"Provenance","text":"<ul> <li>Successful manifest: <code>tools/hil/profile_switch_sf10_10hz_cr_detour_verified_results.json</code>   SHA-256 <code>84a14c3ca3169b8afdaffbef4405a5ea25140560c799091e5f22257814713bcb</code></li> <li>Strict capture: <code>tools/hil/profile_switch_sf10_10hz_cr_detour_verified_results_strict.json</code>   SHA-256 <code>e7995b327b5a84d8fc1830ece1f4cfccd70cae9f367eefd91b7e97ade4a9fb68</code></li> <li>Setup-only failed attempt: <code>tools/hil/profile_switch_sf10_10hz_cr_detour_results.json</code>   SHA-256 <code>486dd52a4ce5f4b20fadec4e6af2e1ede9669acd3e6a09b3490ae5c8b52b82dd</code></li> <li>Installed RX BIN SHA-256:   <code>aae7fd3ffcb5226759884e4d1b41d9da67bb97e95ef89d29dd54f204412d6b48</code></li> <li>Unchanged TX ZIP SHA-256 from the preceding validated upload:   <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> </ul> <p>Successful manifest complete, stopped <code>bounded_tests_complete</code>; strict capture complete under first-miss stopping. No fixture or cleanup error in that run. The build used the live keymindCascade working tree with existing dirty changes and these HIL additions, not a clean-release image. HEAD observed at completion was <code>2b5a6f209835f0f67ed73fee78d36447a4566ce6</code>; the unrelated Companion USB commit advanced HEAD from the earlier experiment's base during this ongoing work. Its files were not reverted. The RX image hash above is the exact tested-image identifier. Prior captures were preserved.</p>"},{"location":"sf10_full_retune_twice_validation/","title":"SF10/125: apply the full radio settings twice per hop","text":"<p>2026-09-14. Two full retune passes were verified, averaging 1.276 ms per channel switch. This did not resolve reception in the bounded packet test: the first packet timed out. This is one failed probe, not a 400-packet loss measurement. No production defaults or receive guards were changed.</p>"},{"location":"sf10_full_retune_twice_validation/#requested-interpretation-and-fixture","title":"Requested interpretation and fixture","text":"<p>\"The 125 run\" was interpreted as uniform SF10/125 on four channels, not the preceding mixed-SF/BW experiment. Apply the complete retune twice to each destination: frequency, modulation, preamble/packet configuration and RX restart, retaining normal guards and command-result checks for both passes.</p> <ul> <li>Receiver: XIAO ESP32-S3 / Wio SX1262, COM31, 28:84:85:B4:09:80.</li> <li>Transmitter: XIAO nRF52840 / Wio SX1262, COM15, B35E71C1C3726CE7.</li> <li>Centers: 909.5, 910.5, 911.5, 912.5 MHz. SF10/125, CR4/5, 32-symbol   preamble, 5.1-symbol visits, 16-byte CHS1 probes, -9 dBm chip request.</li> <li>Normal RX gain 0x94; warm XOSC and fast/bulk RX path; TCXO timing 1600 us.</li> <li>No added settling and no extra IRQ tracing/polling. Goal: 100 packets per   channel, stop on the first strict miss or a complete 400/400 pass.</li> <li>The previous immediate double frequency write remains inside each   pass: four frequency commands per hop. Modulation is forced in both passes,   giving two 0x8B commands and two optimized RX starts per completed hop.</li> </ul> <p>The earlier approximately 0.53 ms path could skip unchanged modulation. This test deliberately writes those settings again, so it measures more than 0.53 + 0.53 ms. No artificial time padding was added to meet an expected value.</p>"},{"location":"sf10_full_retune_twice_validation/#same-image-rx-only-timing","title":"Same-image RX-only timing","text":"<p>Six-second windows in 1/2/2/1-pass order, with a reboot before each. Both one- and two-pass controls force modulation writes, so the comparison isolates complete repetition rather than also changing cache policy.</p> Window Passes per hop Hops Mean total (us) Max total (us) Mean first pass (us) Mean second pass (us) A1 1 141 647.284 847 644.220 \u2014 B1 2 139 1275.410 1491 648.899 622.835 B2 2 139 1276.086 1488 649.000 623.288 A2 1 141 647.858 836 644.872 \u2014 <p>Equal-weight/hop-count means: one full pass 647.571 us; two full passes 1275.748 us. The first and second passes average 648.950 + 623.062 us; the total includes approximately 3.7 us additional wrapper/BUSY bookkeeping. Both two-pass windows had 556 frequency writes, 278 modulation writes and 278 optimized RX starts. No second-pass guard block or hardware/cache error.</p>"},{"location":"sf10_full_retune_twice_validation/#packet-test","title":"Packet test","text":"<p>First probe: TX channel 3, 912.5 MHz, sequence 600920621. TX returned rc=0, setup 86,914 us, transmit call 529,297 us. RX timed out with mode=1 and device errors=0. The controller stopped without retrying or testing further packets. No separate payload-only diagnostic ran because this was a real timeout, not an intact wrong-channel delivery.</p> <p>During the packet window:</p> <ul> <li>223 channel hops; 892 frequency writes; 446 modulation writes; 446 optimized   RX starts. Both pass counters = 223, second-pass-blocked = 0.</li> <li>Mean full switch 1275.058 us, maximum 1510 us.</li> <li>First pass mean 648.812 us, second pass mean 622.601 us.</li> <li>Maximum unheld full four-channel cycle 172,262 us, below the 262,144 us   programmed preamble. Mean listening visit 41,785.719 us.</li> <li>Maximum held visit 405,102 us. No IRQ trace was taken, so the exact cause   and channel of this hold cannot be assigned from these aggregate numbers.</li> <li>Received 0, missed 1. Mode errors, cache errors, RX errors and device errors   were all zero. Normal gain remained 0x94.</li> </ul> <p>This shows that completing two real settings applications does not by itself guarantee successful reception in this fixture. It does not prove every packet would fail or independently identify the cause of this particular timeout.</p>"},{"location":"sf10_full_retune_twice_validation/#implementation-and-verification","title":"Implementation and verification","text":"<p>HIL <code>BenchWrapper::hop</code> performs the first ordinary guarded <code>tuneProfile</code>, then waits boundedly for BUSY-low and requests a refresh of the same profile before the second ordinary guarded transaction. This bypasses only the same-generation no-op, not receive ownership or packet-in-progress checks. The modulation cache is invalidated for each requested full pass.</p> <p>If the second pass is blocked by newly acquired reception, the diagnostic fails closed. Returning ordinary BUSY would wrongly imply that no channel change occurred even though pass one had completed; it is therefore treated as a fixture failure, not silently skipped or counted as an RF loss.</p> <p><code>scanretunepasses 1</code> is the reboot default. <code>scanretunepasses 2</code> and <code>--retune-passes 2 --modulation-cache off</code> select this bounded test. The standalone controller is <code>tools/hil/profile_switch_retune_repeat.py</code>. 19 native profile tests and 49 host tests passed, including real refresh, first/second failure handling, BUSY timeout, no guard override, and rejection of missing physical write/resume counts. <code>git diff --check</code> passed with only unrelated existing CRLF warnings.</p> <p>Receiver build/upload succeeded with hash verification: 94,908 bytes RAM, 368,389 bytes reported flash. Transmitter firmware was not changed or reflashed. Unrelated RAK COM29 was not opened. Both boards rebooted idle after completion, retaining HIL firmware; no autonomous TX or background collector. Temporary PlatformIO overlay removed. No commit/push requested or performed.</p>"},{"location":"sf10_full_retune_twice_validation/#provenance","title":"Provenance","text":"<ul> <li>Manifest: <code>tools/hil/profile_switch_sf10_full_retune_twice_results.json</code>   SHA-256 <code>2928955ce4b02828f3de292cdf8a18606cb56d8a5d6b65c7b50c3de1dd15f764</code></li> <li>Strict capture: <code>tools/hil/profile_switch_sf10_full_retune_twice_results_strict.json</code>   SHA-256 <code>322d1859716fbed0e42224f7bfbf71815dcc986df3ccccea37c1680a63723340</code></li> <li>Installed RX BIN SHA-256:   <code>aa7e3e96729bdb855593385a7a5ab9a22a5e186fda551db863a52a81b7cca2bb</code></li> <li>Unchanged TX ZIP SHA-256:   <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> </ul> <p>Manifest complete, stopped <code>bounded_tests_complete</code>; strict capture complete under first-miss stopping. No fixture or cleanup error. Previous captures were not rewritten. Source remains keymindCascade commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> plus existing dirty changes and these HIL-only additions, not a clean-release comparison.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/","title":"SF10 / 125 kHz, XIAO nRF52 TX, double write, 1 ms delay grid","text":"<p>2026-09-14. Fixed-channel positive control passed 100/100. The subsequent four-channel, double-write sweep failed at every 1 ms step from +0 to +23 ms.</p> <p>New sender serial B35E71C1C3726CE7 first enumerated as Zephyr CDC COM33 (2FE3:0004). A 1200-baud touch exposed Seeed XIAO bootloader COM25 (2886:0044, XIAO-BOOT). The application-only DFU ZIP was accepted with its normal compatibility checks, reported programmed successfully and reappeared as COM15 (2886:8044), with the same serial and ready XIAO nRF52840/Wio SX1262 HIL identity. No bootloader/SoftDevice replacement or full erase was performed. The unrelated RAK COM29 (4D6F77FD74011872) was not opened.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/#requested-test","title":"Requested test","text":"<ul> <li>Receiver: existing XIAO ESP32-S3/Wio SX1262 on COM31, normal RX gain 0x94.   MAC 28:84:85:b4:09:80. The host reasserts double-write mode after every reboot.</li> <li>Sender: XIAO nRF52840/Wio SX1262 COM15, serial B35E71C1C3726CE7.</li> <li>SF10/125 kHz, CR4/5, four channels, 5.1-symbol listening visits, 32-symbol   preamble, 100 packets/channel, fixed 16-byte probes at -9 dBm chip request.</li> <li>Added post-BUSY settling 0, 1, 2, ... 23 ms. Each failed setting stops at   its first miss; the entire sweep stops at its first 400/400 pass. No added   delay beyond the nominal full-sweep timing ceiling and no lower SF runs.</li> <li>Double frequency writes retained; modulation cache on; no extra IRQ trace.   No prior-transmitter or single-write measurements will be reused.</li> </ul> <p>Budget uses 539 us nominal double-write retune (ceil of the measured 538.192 us RX-only mean), 41,780 us post-settle visit and 262,144 us preamble: <code>262144 / 4 - 41780 - 539 = 23217 us</code>. Last 1 ms grid point is 23,000 us. This is a nominal ceiling, not a worst-case jitter or zero-loss guarantee.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/#preparation","title":"Preparation","text":"<p>The settling controller now accepts <code>--step-us 1000 --frequency-repeat on</code>; its existing defaults are unchanged. Capture policy checks reject mixed single/double evidence. The 42 host collector tests and 14 selected profile native tests passed, including grid/first-pass stop, nRF USB DTR behavior, transmitter replay, setup/TX failure, stationary payload integrity, zero-retune and host/device-count checks. <code>git diff --check</code> passed (unrelated CRLF warnings).</p> <p>Minimal <code>profile_switch_xiao_nrf52_tx</code> firmware compiled successfully: 95,340 bytes reported flash usage, 18,212 bytes static RAM. It uses the production XIAO pin map and CustomSX1262 initialization, exposes only reference TX and cached USB results, and has no Mesh identity or application settings writes. Includes the existing build-local bounded nRF USB READY/HFCLK fix.</p> <p>Platform: Nordic nRF52 10.8.0; Adafruit nRF52 framework 1.10701.0+sha.d5413016; ARM GCC 14.2.1; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>.</p> <p>Generated DFU ZIP contains application only, requiring SoftDevice ID 0x0123. Upload used normal DFU validation without compatibility overrides. The V4's earlier no-backup erase authorization is not treated as authority to erase this new board's bootloader or unrelated storage.</p> <p>Flashed nRF52 transmitter SHA-256:</p> <ul> <li>HEX: <code>aaee693900dedc3816a6baeca576c7449502d30c05ac48e2663b02acec9aec9a</code></li> <li>DFU ZIP: <code>7466625ef5e7bcc8f7dd16db2b843db29b4312a33b0d32bc0b1e1193d6aee03a</code></li> </ul>"},{"location":"sf10_nrf52_double_write_settling_validation/#baseline-requested-before-continuing-the-sweep","title":"Baseline requested before continuing the sweep","text":"<p>The initial four-channel run was interrupted at the user's request after 13 completed settings, added delay 0..12,000 us. Each missed its first packet: nine matched the test sequence but were reported on channel 2 when channel 3 was expected; four timed out. These are not 13 full 400-packet measurements and must not be presented as an unbiased loss rate. The incomplete original top manifest and all raw captures under <code>tools/hil/profile_switch_sf10_nrf52_double_1ms_results*</code> remain unchanged.</p> <p>Added an independent HIL-only stationary receiver: one full normal radio initialization, fixed 910.25 MHz (channel 3), normal RX rearm, no profile scheduler/fast-switch/cache shortcut. All 100 packets use the same transmitter, SF10/125, CR4/5, 32 preamble symbols, 16-byte CHS1 body and -9 dBm request. No RF retries and no early stop on an RF miss; hardware/fixture faults abort.</p> <p>Result: 100/100, CRC/read errors 0, foreign packets 0, hardware errors 0, observed frequency writes after setup 0. Normal gain register 0x94 and RX mode 1 verified. RSSI mean -33.610 dBm, range -34..-33; SNR mean +8.736 dB, range +7.8..+10.0. Baseline cleanly stopped and both devices rebooted idle. This confirms the fixed-channel link in this finite sample, not all-channel or interference immunity.</p> <p>Capture: <code>tools/hil/profile_stationary_nrf52_sf10_100_results.json</code>. SHA-256: <code>547c30efc89c29e3f60cb975f7fc34de3e9f14bed3ed4cc9f1ba01f63402bf15</code>. Receiver image with stationary capability compiled/flashed and hash-verified: SHA-256 <code>0daab2e3293359280714042492639ab8c176609143cf01996ad4ba7026704768</code>. Reported flash 364,657 bytes; static RAM 94,796 bytes. Existing double-write and four-channel switching implementation is unchanged; baseline is a separate inactive command mode during the scan.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/#post-baseline-four-channel-run","title":"Post-baseline four-channel run","text":"<p>Fresh prefix: <code>tools/hil/profile_switch_sf10_nrf52_postbaseline_double_1ms_results</code>. Command: <code>profile_switch_settling.py --receiver COM31 --sender COM15 --sf 10 --frequency-repeat on --step-us 1000 --output &lt;fresh-prefix&gt;.json</code>. No old captures are reused. Stop at the first 400/400 or after +23 ms.</p> <p>Completed all 24 settings. No 400/400 pass. At zero added delay, the first packet passed and the second timed out. Each +1..+23 ms setting failed its first packet. Total 25 probes: one valid, 17 timeouts and seven test-sequence packets reported on channel 2 while expecting channel 3. Each setting stops on its first miss; this is deliberately censored evidence, not a measured unbiased 4% packet-delivery rate. The lone valid packet was -33 dBm / +8.2 dB SNR. The wrong-channel records do not alone distinguish real off-channel acquisition from channel bookkeeping; no root cause is claimed.</p> <p>Measured 3,086 retunes, weighted mean 526.783 us (0.527 ms), maximum 876 us (0.876 ms), excluding the separately applied settling delay. Exactly 6,172 SetRfFrequency commands confirm two per hop. One modulation command was issued across the measured scan windows (after the sole received packet); no retune failures, RX-mode errors, cache errors or CRC/read errors. All gain checks remained 0x94. This measurement is from the receiver image with the new independent baseline mode, not a controlled performance A/B against the previous image's 538.192 us RX-only mean.</p> <p>At +23 ms the measured settling interval was 23,000..23,001 us and mean switch-plus-settle 23,567.2 us. That short failed window did not contain a complete unheld scan cycle, so it provides no measured final-step full-sweep latency. The ceiling remains the nominal 23,217 us calculation above.</p> <p>Post-baseline top manifest SHA-256: <code>badda7f64a7bdd445942da19dc76dea0d1aace2ae451772edf4744d4670ac28c</code>. Interrupted pre-baseline top manifest SHA-256: <code>90f7b213bc44ae73714c5d9d32216ff3f1760fafd657feb5ea9299ed1e10ddf3</code>.</p> <p>Conclusion: the fixed-channel link passes its 100-packet control, but extra post-switch settling through the nominal budget does not cure this scanner failure. Investigate acquisition/hold behavior and channel attribution next; do not claim more waiting, a second frequency write, or a transmitter swap has fixed the issue. No guard/default production timing was changed here.</p> <p>Collector exited successfully at the nominal timing limit, with no cleanup error; both radios rebooted idle. The previous follow-up automation remains paused. No commit or push requested; HIL firmware remains installed. Temporary build overlay removed. No background test collector remains running.</p>"},{"location":"sf10_rollback_failure_validation/","title":"SF10/125 rollback and wider-spacing failure isolation","text":"<p>2026-09-14. No strict four-channel 400/400 pass. Reverting the switching optimizations did not remove failures. Off-channel reception also occurs with a fixed, fully initialized receiver, without any channel switching. A traced timeout shows an off-channel preamble holding the scanner away from the intended channel until after its transmit preamble. Wider spacing did not eliminate either wrong-channel delivery or actual missing packets.</p> <p>This isolates a concrete scanner failure mechanism, not the underlying physical RF cause. Commanded frequency words are observed, but actual emitted spectrum, antenna-port power, image responses and overload have not been independently measured. Do not claim front-end saturation or a specific spur as proven. Do not treat these first-failure-censored samples as unbiased PER.</p>"},{"location":"sf10_rollback_failure_validation/#fixture-and-requested-controls","title":"Fixture and requested controls","text":"<ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, MAC 28:84:85:B4:09:80; normal RX gain   register 0x94 throughout (boosted gain off).</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, serial B35E71C1C3726CE7.</li> <li>SF10, 125 kHz BW, CR4/5, 32-symbol preamble, 16-byte sequenced CHS1 probes,   -9 dBm chip request, four channels, 5.1-symbol post-settle listening visits.</li> <li>Original centers: 909.5, 909.75, 910.0, 910.25 MHz. User-requested wider   centers: 909.5, 910.5, 911.5, 912.5 MHz (1 MHz spacing).</li> <li>Existing fixed-channel positive control was 100/100; see   <code>sf10_nrf52_double_write_settling_validation.md</code>. No failed packets retried.</li> <li>Unrelated RAK COM29 was not opened. New nRF52 upload was application-only,   using normal SoftDevice ID 0x0123 validation; no bootloader/SoftDevice erase.</li> </ul> <p>Rollback modes are runtime HIL controls on the same current source, not historical firmware checkouts. No production default or receive safety guard was changed during this investigation. Tests preserve ownership, packet-in- progress, BUSY and command-result checks. Existing unrelated working-tree changes were left intact. No commit or push was requested this turn.</p>"},{"location":"sf10_rollback_failure_validation/#maximum-practical-settling-control","title":"Maximum practical settling control","text":"<p>At SF10/125, a symbol is 8,192 us, the programmed preamble is 262,144 us, and each 5.1-symbol post-settle visit is 41,780 us. For each rollback mode:</p> <ol> <li>Measure six seconds of RX-only switching without added delay.</li> <li>Choose the largest 100 us delay step satisfying    <code>4 * (41780 + observed_max_switch_us + added_delay_us + 500) &lt;= 262144</code>.</li> <li>Measure another six seconds; require at least eight full idle cycles and    maximum observed idle cycle below the preamble before allowing TX.</li> </ol> <p>The 500 us per-hop reserve covers some observed scheduling variation, not all possible jitter. RX is active during added settling. Near-ceiling cycle timing is not itself a guarantee of acquisition for every arrival phase, especially when an IRQ causes an extended packet hold. Idle-cycle statistics exclude guard/packet-held visits; those are measured separately.</p>"},{"location":"sf10_rollback_failure_validation/#250-khz-spacing-eleven-rollback-cases","title":"250 kHz spacing: eleven rollback cases","text":"<p>Each case stopped on its first probe, TX channel 3, with a real timeout. No strict 400/400 pass, TX fault, RX mode/cache failure, or hardware error. The first nine cases used the checkout's existing 1,600 us TCXO setting; the final two explicitly restored 6,000 us. Production timing was not edited.</p> Case Added delay (us) Zero-delay mean switch (us) Max settled idle cycle (us) Fast, cached modulation, double frequency write 22500 535.88 259297 Always write modulation 22500 625.50 259682 Individual SF/BW/CR writes 22200 840.97 259346 Full normal RX restart 22200 896.89 259577 Full RX + individual modulation 22000 1113.95 259623 Above + byte-wise SPI, warm XOSC 21800 1215.79 259220 Above + RC standby, 1.6 ms TCXO 20100 2942.50 259339 Fast, cached modulation, single frequency write 22600 450.25 259341 RC/full RX/individual/byte-wise, single write, 1.6 ms TCXO 20200 2837.50 259329 RC/full RX/individual/byte-wise, double write, 6 ms TCXO 15800 7293.25 259550 RC/full RX/individual/byte-wise, single write, 6 ms TCXO 15800 7190.31 259139 <p>Actual frequency/modulation command counts and fast-RX counts verified each policy. Slower modes received less added delay to preserve the total sweep budget. These are eleven probes with eleven timeouts, not eleven complete 400-packet runs. Packet arrival pauses use the same seeded scheduling method but not hardware-synchronized identical RF phases across modes.</p>"},{"location":"sf10_rollback_failure_validation/#fixed-frequency-controls-off-channel-responses-without-switching","title":"Fixed-frequency controls: off-channel responses without switching","text":"<p>Each pair received three independent probes after full normal initialization. Positive controls were interleaved. The receiver remained at one frequency: zero observed frequency commands after setup, no hopping or cache shortcut. Payload success requires the exact expected sequence/channel/body, length 16 and clean CRC. It does not require RX center to equal TX center in this explicit offset diagnostic. Offset below means programmed RX minus TX.</p> Spacing RX-TX offset (kHz) Probes Intact expected payloads Preamble IRQ seen 250 kHz 0 6 6 6 250 kHz -250 3 2 3 250 kHz -500 3 0 3 250 kHz -750 3 0 3 250 kHz +250 3 0 2 1 MHz 0 6 6 6 1 MHz -1000 3 2 3 1 MHz -2000 3 0 0 1 MHz -3000 3 3 3 1 MHz +1000 3 3 3 <p>At 250 kHz spacing, the two valid -250 kHz-offset packets reported RSSI -91/-90 dBm and SNR -12.8/-10.8 dB. At 1 MHz spacing, valid off-channel packets reported RSSI -102..-109 dBm and SNR -11.5..-15.8 dB. Wider on-channel controls were all -33 dBm, SNR +8.0..+8.8 dB. These are radio-reported values, not calibrated measurements of transmitted spurs or receiver rejection.</p> <p>The non-monotonic offset pattern means that increasing spacing alone cannot be assumed to remove this response. These fixed-frequency tests rule out a channel-hop shortcut as a necessary condition for the observed off-channel packets; they do not establish which physical component produces them.</p>"},{"location":"sf10_rollback_failure_validation/#a-traced-real-timeout-at-250-khz-spacing","title":"A traced real timeout at 250 kHz spacing","text":"<p>Fast/double-write RX, +22,500 us settling. One channel-3 probe timed out with TX rc=0, RX mode=1 and device errors=0. The trace contains 454 events, overflow 0. Trace adds 64 us IRQ polling; use it for ordering, not an unperturbed timing A/B comparison. Times below are relative to receiver expectation arming.</p> RX time (ms) Evidence 169.190 Frequency command for channel 3, 910.25 MHz 234.032 Leaves channel 3 for channel 0 298.869 Frequency command for channel 1, 909.75 MHz 330.030 PREAMBLE_DETECTED (0x0004) while on channel 1 363.632 Requested next hop is held by receive-in-progress guard 726.734 Guard clears the lingering preamble IRQ 726.826 Frequency command for channel 2 791.654 Finally commands intended channel 3 again 814.586 Channel-3 hop/settling completes <p>TX setup was 86,914 us and its transmit call 529,297 us. Host/firmware timing places TX RF start approximately 287..289 ms after RX arming and the end of its programmed preamble around 550 ms. This estimate is not a synchronized RF measurement, but the receiver's several-hundred-millisecond absence from the intended channel is much larger than USB timestamp uncertainty.</p> <p>The held channel-1 visit measured 427,395 us, versus normal idle four- channel cycle maximum 259,358 us. The guard timeout is consistent with <code>RadioLibWrapper::calcMaxPacketMillis</code>: <code>(32 + 8 + 4.25) * 8192 = 362496 us</code>, rounded to 363 ms. <code>CustomSX1262::isReceiving()</code> starts that timer when the guard first observes the preamble, here later than the diagnostic IRQ poll.</p> <p>Thus an off-channel preamble can monopolize the scanner long enough to miss the real channel. Do not simply remove or shorten this safety guard as a production fix: it also protects legitimate weak or long-preamble reception.</p>"},{"location":"sf10_rollback_failure_validation/#1-mhz-spacing-strict-results-versus-payload-delivery","title":"1 MHz spacing: strict results versus payload delivery","text":"<p>Three strict rollback cases (fast double, fast single, fully rolled back single/6 ms) each stopped at their first probe. All three actually decoded the intact channel-3 payload while programmed for channel 2: RX 911.5 MHz, TX 912.5 MHz, RF word at read 955777024. They are channel mismatches, not lost payloads. RSSI was -102/-101/-101 dBm; SNR -11.5/-11.5/-11.2 dB.</p> <p>An explicitly separate payload-delivery diagnostic then continued through such packets while retaining strict validity in raw evidence:</p> Mode Added delay Delivered before stop Strict same-channel Stop Mean switch Max idle cycle Fast, cached, double write 22.5 ms 3 of 4 probes 0 TX channel 0 timed out 557.721 us 259381 us RC/full RX/individual/byte-wise, single write, 6 ms TCXO 15.8 ms 2 of 3 probes 0 TX channel 1 timed out 7310.510 us 259643 us <p>Every delivered packet in these two runs arrived one programmed channel below its transmitter. Both runs had zero mode/cache/RX/device errors and actual switch-policy counts matched. Neither is a 400/400 pass, even under the relaxed delivery-only criterion. The true timeout in the fully rolled-back path also shows the problem is not limited to the accelerated RX restart or 0x8B cache. No traces were enabled for these two runs, so do not assign their individual timeouts the exact IRQ timeline from the earlier traced probe.</p>"},{"location":"sf10_rollback_failure_validation/#changes-and-verification","title":"Changes and verification","text":"<ul> <li>HIL-only rollback, explicit TCXO timing, selectable 250/1000 kHz spacing,   frequency-command trace events and fixed-frequency offset controls.</li> <li>Separate opt-in payload-delivery test; strict wire validity remains intact.   Host/device counters distinguish strict from off-channel deliveries;   settling sweeps reject delivery-only captures, including reused evidence.</li> <li>16 native profile tests and 46 HIL host tests passed. Receiver and nRF52   builds/uploads succeeded with normal verification. Receiver reported   94,844 bytes RAM / 366,777 bytes flash; nRF52 18,220 / 95,572 bytes.</li> <li><code>git diff --check</code> passed; unrelated pre-existing CRLF warnings only.</li> <li>Temporary PlatformIO overlay removed. Controllers stopped, both boards   rebooted idle with HIL firmware retained. No autonomous TX or restoration.</li> </ul> <p>Next useful isolation is the physical off-channel response (controlled RF attenuation or reversed radio roles), followed by safe acquisition/hold-policy experiments. More settling delay alone does not address the demonstrated false-hold mechanism. No claim of an identified silicon defect or verified production fix is made here.</p>"},{"location":"sf10_rollback_failure_validation/#evidence-provenance-sha-256","title":"Evidence provenance (SHA-256)","text":"<p>Raw JSON files below are under <code>tools/hil/</code>; prior captures were not rewritten. Matrix manifests include per-case paths and timing controls. All listed new experiments completed under their stated stopping policies without fixture or cleanup errors. Completed first-failure runs still have incomplete 400-packet levels by design.</p> Capture SHA-256 profile_switch_sf10_rollback_results.json <code>e87c504b3c89fbafe90c18fcd0ab37df34a6aeb51d95b5c69f58d60f70de185a</code> profile_stationary_sf10_offset_results.json <code>d3d87315513a70fc3f00cc7f17369043328f53ee3028d499087b21e767370ab7</code> profile_switch_sf10_rollback_fast_trace_results.json <code>8ac9db50f0f06eb7511d7d233957119618df62afdc7112dd83eb68d292fcd725</code> profile_switch_sf10_rollback_6ms_results.json <code>74e7bfeb23bc569a5786e2322b5e3b1753cba9f628e2969bf4f5c4296ca5817a</code> profile_switch_sf10_wide_rollback_results.json <code>d79096fbe3e15e0375457b487fd40be3418789e798a978efb79d8298c880eea2</code> profile_switch_sf10_wide_payload_results.json <code>1316a2c2f32a8c0773fc56587c4220ee8f6f6cdf4ab9b87e00fd361fc9395257</code> profile_switch_sf10_wide_legacy_payload_results.json <code>fcf2123270634e2f27800787e20b9b8b7ae63bcfb03e17d26a4a4f6f4e23d32f</code> profile_stationary_sf10_wide_offset_results.json <code>4c494a59fa793d274b0366185cfe3230b6c9fce7a57dfaa61f9f29c36465bbd3</code> <p>RX firmware images used, in chronological order:</p> Stage firmware.bin SHA-256 Initial nine-mode rollback <code>5f8dbf9c4584e0de94a7aebda5a20e961b644a880ecb6a34ab5871621958696f</code> Fixed 250 kHz offsets and traced timeout <code>cd839caa33c869dd448cc55e9c8b959e39d105f80a2ac4a8029393698b993fd3</code> Explicit 6 ms TCXO rollback <code>0ba044035c4986749c9ad4f50c702dc8c57e8e0fecf9d46fc11515cad5678166</code> Wider strict rollback <code>5fc919c80438635b4a96021b39fae2ada9e767508d7bb73854e4e108f0d4920f</code> Wider delivery diagnostics and fixed offsets; final installed <code>7b313a0f8f1eb04f6fc12197af5e9481ad43154b981ab7627e50167d2a97d8c2</code> <p>The 250 kHz tests used the prior nRF52 TX ZIP hash <code>7466625ef5e7bcc8f7dd16db2b843db29b4312a33b0d32bc0b1e1193d6aee03a</code>. All wider tests used the new selectable-spacing application:</p> <ul> <li>TX ZIP: <code>c474b7598a2c0b6c529ead897f3fc7aab8caf4b7581c73d7acac6ffae081377d</code></li> <li>TX HEX: <code>b400fc53c496f4a956f88ccee5cda83b5f6679b8e2b59bfcb4b8155ea9e1e5e9</code></li> </ul> <p>Build artifacts are generated and may be replaced by a subsequent build; hashes identify the images used, not a promise that every historical binary remains in <code>.pio/build</code>. Source starts from keymindCascade commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> with the existing dirty changes and these uncommitted HIL additions; this is not a clean-release comparison.</p>"},{"location":"sf125_settling_limits_validation/","title":"Descending SF10..SF5 / 125 kHz settling limits","text":"<p>Experiment started 2026-09-14. Stopped at the user's request to replace the Indicator transmitter with a V4. No 400/400 pass was found. The saved top-level manifest remains incomplete; the SF10 manifest contains all completed settings. Original evidence is not rewritten to make an interrupted experiment look complete.</p>"},{"location":"sf125_settling_limits_validation/#results-at-user-requested-stop","title":"Results at user-requested stop","text":"<p>94 SF10/125 settings completed: every added delay from 0 through 9,300 us in 100 us increments. Each stopped on its first RF miss; none reached 400/400. The best individual setting was +1,000 us: 25 valid packets, then packet 26 failed. No lower SF was reached in this descending sweep. No result is claimed for SF10 delays above 9,300 us or for SF9..SF5 in this run.</p> <p>Across these completed settings: 641 probes, 547 valid and 94 failed. Because each setting ends at its first miss, these totals are not an unbiased packet error-rate measurement and do not establish a reliable lower/upper delay limit.</p> <p>For the 547 valid receptions, reported SNR averaged +8.311 dB, minimum +7.5 dB and maximum +9.5 dB. RSSI averaged -40.547 dBm, range -42 to -39 dBm. These are conditional on successful reception; no SNR is inferred for missing packets.</p> <p>24,055 retunes averaged 456.620 us, weighted by hop count and excluding the intentional settling delay. Reported retune failures, RX-mode errors and cache errors were all zero. Four RX errors were reported, one each at +1,100, +5,900, +6,700 and +6,900 us. These counters do not identify the transmitter as the cause. At +9,300 us, the unheld four-channel cycle averaged 206.134 ms (maximum 206.157 ms), versus a 262.144 ms programmed preamble; this nominal time margin still did not produce an all-pass setting.</p> <p>Controllers and collector were stopped, and both boards were rebooted to idle HIL. Follow-up polling is paused. Subsequent <code>info</code> checks returned ready on both boards, with XIAO gain register 0x94 and Indicator 0x96. Test firmware was retained; no original firmware was restored. Replacement-board testing has not started.</p> <p>Saved manifest SHA-256 at stop:</p> <ul> <li>Top level: <code>9cbf315704816be4d3cf7977e954e64a2033155e654cd7108919e6a17a5f8f8a</code></li> <li>SF10: <code>509f632de1a463d4f5f84c055a1570468c5752685d596f4b445aa7d7c339189d</code></li> </ul>"},{"location":"sf125_settling_limits_validation/#requested-method","title":"Requested method","text":"<p>XIAO ESP32-S3/WIO SX1262 COM31 RX, SenseCAP Indicator ESP32-S3 COM28 TX, user-separated positions, XIAO boosted gain off (actual register 0x94), Indicator gain unchanged at 0x96. Four centers 909.500/909.750/910.000/910.250 MHz; bandwidth 125 kHz, CR4/5, 5.1-symbol visits, 32 programmed preamble symbols, 16-byte synthetic packets at -9 dBm. Warm fast RX, buffered 8 MHz SPI and unchanged-modulation cache enabled. No extra IRQ polling/tracing.</p> <p>Start SF10 and descend one SF at a time through SF5. For each SF, test added post-BUSY delay in 100 us increments starting at zero. Every failed setting stops on its first invalid reception/timeout; a pass requires 100/100 on each of four channels. Latest user instruction: stop the entire sweep at the first 400/400 pass, without continuing to find an upper limit or a lower SF. Without any pass, continue to the ceiling, then lower SF. Fixture errors abort the entire experiment. No failed RF probe is retransmitted.</p> <p>This searches for a sampled all-pass setting, not proof of monotonic delay behavior, an upper delay limit, or zero PER. The RX modem remains active during the extra delay; the independent 5.1-symbol visit starts afterward. Thus extra settling is also extra RX occupancy, not a pre-SetRx blanking interval.</p> SF Visit Last 100 us delay step Programmed preamble 10 41,780 us 23,300 us 262,144 us 9 20,890 us 11,400 us 131,072 us 8 10,445 us 5,400 us 65,536 us 7 5,223 us 2,500 us 32,768 us 6 2,612 us 1,000 us 16,384 us 5 1,306 us 200 us 8,192 us <p>Budget: <code>preamble_us / 4 - dwell_us - 453</code>, using the nominal retune cost. Actual cycle means/maxima are recorded and may exceed that nominal budget. The randomized arrival pause now includes added settling when estimating two scan cycles; earlier saved captures retain their original distributions.</p> <p>The stop policy changed after SF10 delays 0..5,600 us had all failed. The old supervisors were stopped while the active 5,600 us collector finished normally. Original captures are preserved. A fresh first-pass manifest reuses completed, configuration-validated raw captures with their SHA-256 hashes, then resumes at 5,700 us; no completed setting is repeated. The earlier top-level manifest is incomplete because its upper-limit policy was superseded, not due to an RF or fixture fault.</p>"},{"location":"sf125_settling_limits_validation/#build-and-initial-checks","title":"Build and initial checks","text":"<p>Both HIL targets compiled and verified uploads succeeded. The selected 53 host/native tests passed: 36 host collectors, seven profile native, four SX1262, five radio and one receive-mode test. After the stop-rule change, all 39 host collector tests passed, including new whole-sweep first-pass stopping and matching, hash-preserving capture reuse.</p> <p>Actually loaded firmware SHA-256:</p> <ul> <li>XIAO: <code>89faa3bbc5eade5e632e0c720c75be0ba9105e595b1384de74a00e09c0b60a24</code></li> <li>Indicator: <code>fb06c52e138e5cd65fff1393e3f1208230b06977e5f824852086d4c80c89845c</code></li> </ul> <p>A one-second RX-only SF10/+23,300 us smoke check recorded 15 hops with minimum delay 23,300 us, minimum post-delay dwell 41,782 us, and zero retune/RX-mode/cache errors. Its two clean cycles averaged 262,125 us, maximum 262,127 us: only a tiny margin against the 262,144 us preamble, not a robust worst-case bound. No RF probe was transmitted during that check.</p> <p>Base <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> on <code>keymindCascade</code>, plus local changes. RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17.</p> <pre><code>python tools/hil/profile_switch_sf_limits.py --receiver COM31 --sender COM28 --output tools/hil/profile_switch_sf125_limits_results.json\n</code></pre> <p>Updated run:</p> <pre><code>python tools/hil/profile_switch_sf_limits.py --receiver COM31 --sender COM28 --output tools/hil/profile_switch_sf125_first_pass_results.json --stop-on-first-pass --reuse-prefix tools/hil/profile_switch_sf125_limits_results.json\n</code></pre> <p>The controller reboots to idle HIL after each per-SF child completes or fails; test firmware is to remain installed, per user request. Original private flash backups are retained. RAK4631, Indicator RP2040 and unrelated S3 soak work are not part of this experiment. No commit/push requested. Temporary build overlay has been removed.</p>"},{"location":"sf5_250_dwell_validation/","title":"SF5 / 250 kHz: four-channel dwell sweep","text":"<p>Measured 2026-09-14. No tested dwell from 4.1 through 8.1 chirps passed. Each setting stopped at its first invalid reception or timeout; the sweep stopped at the requested 8.1 limit. None reached 100 packets per channel.</p>"},{"location":"sf5_250_dwell_validation/#setup","title":"Setup","text":"<ul> <li>XIAO ESP32-S3/WIO SX1262, COM31, receiver; SenseCAP Indicator ESP32-S3,   COM28, reference TX. Radios remain in the user's separated positions.</li> <li>XIAO boosted RX off, verified actual gain register 0x94 before tests   and in every final scan status. Indicator 0x96, unchanged as transmitter.</li> <li>Four centers: 909.500, 909.750, 910.000, 910.250 MHz. SF5, bandwidth 250 kHz,   CR4/5, 32 programmed preamble symbols, 16 synthetic bytes, -9 dBm.</li> <li>Production warm fast RX and unchanged-modulation cache enabled, buffered   8 MHz SPI. Existing packet guards and initialization unchanged.</li> <li>Requested grid 4.1 to 8.1 in 0.5-symbol steps. Each setting starts fresh,   shuffles channel order with seed 606125 and varies arrival timing without   synchronization to RX visits. Both boards reboot between settings.</li> <li>100 packets/channel maximum; stop that setting on first failure, then move   to next dwell. No retransmission of a failed probe. Stop the entire sweep   on first complete 400/400 result or after 8.1; abort on fixture errors.</li> <li>Extra IRQ polling and packet traces disabled to avoid adding diagnostic   overhead to sub-millisecond visits. RX mode, modem software cache, gain,   SPI command counts, timing and packet identity checks remain enabled.</li> </ul> <pre><code>python tools/hil/profile_switch_dwell.py --receiver COM31 --sender COM28 --output tools/hil/sf5_250_dwell_normal_results.json\n</code></pre>"},{"location":"sf5_250_dwell_validation/#results","title":"Results","text":"<p>\"Received\" means correct sequence, payload and reported receive channel. Each row is a first-failure sample, not a 100-packet/channel PER measurement.</p> Chirps Requested dwell Received / attempted First failure Mean retune 4.1 525 us 1 / 2 channel mismatch 458.122 us 4.6 589 us 0 / 1 timeout 450.787 us 5.1 653 us 0 / 1 timeout 450.667 us 5.6 717 us 0 / 1 timeout 452.270 us 6.1 781 us 2 / 3 timeout 452.991 us 6.6 845 us 0 / 1 timeout 451.082 us 7.1 909 us 0 / 1 timeout 453.796 us 7.6 973 us 0 / 1 timeout 453.568 us 8.1 1,037 us 4 / 5 timeout 457.886 us <p>All 16 requested transmissions returned success. Seven met the full receive checks. Of nine failures, one returned a matching synthetic sequence on a different reported receive channel and eight timed out. Every timeout run also recorded one <code>rx_errors</code> increment. These are receive/read/decode errors, not retune hardware faults; without an IRQ trace their exact cause and association with the expected probe cannot be reconstructed.</p> <p>All 64,507 timed hops passed RX-mode/software-cache checks with zero retune failures. Weighted mean switch time was 452.739 us, excluding listening dwell and full application scheduling. Each hop programmed a frequency. Modulation rewrites occurred only when the prior context needed re-establishing, rather than on every frequency-only hop.</p> <p>The 4.1 second probe was transmitted for channel 2 (910.000 MHz), but its sequence was returned while the receiver reported channel 3 (910.250 MHz), 16 bytes, RSSI -66 dBm, SNR 0.5 dB. It therefore failed the channel check; the saved <code>valid=false</code> also does not independently certify all payload bytes. No synchronized RF/frequency-register capture was taken, so this is evidence of wrong-channel reporting/reception, not proof of its physical mechanism. Successful correct-channel probes read -42 to -41 dBm, SNR 7.8\u20138.8 dB.</p>"},{"location":"sf5_250_dwell_validation/#interpretation","title":"Interpretation","text":"<p>SF5/250 did not establish a solution to the close-range problem, and increasing dwell alone did not produce a clean four-channel result. The wrong-channel sequence and receive errors prevent interpreting this as a pure minimum-dwell/acquisition test. It is not evidence that 8.1 is a reliable setting merely because four probes passed before its miss.</p> <p>There is also a timing tradeoff: a symbol lasts 128 us, so 32 programmed preamble symbols occupy only 4.096 ms. A ~453 us retune costs about 3.54 symbols. At 4.1, four nominal dwells plus four such retunes consume about 3.91 ms before other loop costs; at 8.1 they consume about 5.96 ms. Longer visits give acquisition more uninterrupted time but increase the time spent away from each channel. This arithmetic motivates testing a longer preamble or fewer channels separately; it does not prove the cause of any particular failure. No such follow-up was transmitted after the 8.1 limit.</p> <p>Unlike the earlier separated SF6 run, this changes SF, bandwidth, absolute preamble duration and diagnostic polling. The RF settings also leave channel spacing unchanged at 250 kHz. It is not a matched comparison isolating receiver sensitivity or the modulation cache.</p>"},{"location":"sf5_250_dwell_validation/#provenance-and-handoff","title":"Provenance and handoff","text":"<p>Base <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> on <code>keymindCascade</code>, plus uncommitted production cache and HIL changes. RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>; Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL builds and verified uploads succeeded. All 39 selected host/native tests passed, including bandwidth/dwell calculation and bounded sweep stopping. No commit or push was requested for this work.</p> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>6ba7b4c6785ac11eb8a4ecd2f1148f4f55ce866c1cb172776757fe0a95047da9</code></li> <li>Indicator: <code>3672ca330d4b2d3e8efa39edf2dbc3b27b8804dbb9a98f29267c85c41972a028</code></li> </ul> <p>Raw manifest references all nine per-dwell captures. SHA-256 values (all files under <code>tools/hil</code>):</p> File suffix after <code>sf5_250_dwell_normal_results</code> SHA-256 <code>.json</code> <code>aaf00ef8531cb2c5c7e4dfb78d3b8b03ce61d9afe8323fb33e70be09656adf54</code> <code>_4p1.json</code> <code>a9c6baf0bece79c9b9c96bfa97e3cd9932e0c04fc76b43f61ed350512306341a</code> <code>_4p6.json</code> <code>63863b55108374011afbe555bfeb97034b010e194cdad83a212d5d286d1992fe</code> <code>_5p1.json</code> <code>ff1d2927365e3634984bc0b843a09f2934c5dcac49b60b862ff4db030e0f7e74</code> <code>_5p6.json</code> <code>33c91687d0b61dd83e2a08d8358b43f21fa27f9e80f9503feedeb657453a7efd</code> <code>_6p1.json</code> <code>5baa8d1bfcf0ccc947c92d563dc555802ac599ce1e8d260a623964936a99da4e</code> <code>_6p6.json</code> <code>90f6b4d7785add771e30da7dfa78672fd75ad13d8a5965c21ec1a37e15d8dabb</code> <code>_7p1.json</code> <code>eb99afd932a5579c765f8a6c0a18db4bacc317829b0654d11fbf2f569c3a8618</code> <code>_7p6.json</code> <code>bdb88da82437fa6e01ad90ab927d364b4d67aaadbac7597c3aacb9799b053211</code> <code>_8p1.json</code> <code>404ee179e4c10333bd6fddae9f0faa9da81f6193dcb5fff6d9bd37a466c319a3</code> <p>Both boards were rebooted after the sweep and answered ready with correct HIL capabilities; XIAO gain remained 0x94. Per user request, HIL firmware is left installed, idle with no autonomous test transmissions. Private original flash backups remain available. The RAK4631, Indicator RP2040 and unrelated S3 soak work were not modified. The temporary build overlay was removed.</p>"},{"location":"sf6_125_settling_validation/","title":"SF6/125 four-channel post-switch settling sweep","text":"<p>Measured 2026-09-14. No setting from +0.0 through +1.0 ms passed 400/400. The requested delay was applied after BUSY went low without consuming the subsequent 5.1-symbol listening visit. Each run stopped on its first miss; the sweep would have stopped at the first 400/400 pass, but reached its nominal timing limit instead. No RF probes were sent beyond that limit.</p>"},{"location":"sf6_125_settling_validation/#method-and-timing-budget","title":"Method and timing budget","text":"<ul> <li>XIAO ESP32-S3/WIO SX1262 COM31 receiver, SenseCAP Indicator ESP32-S3 COM28   transmitter, unchanged user-separated positions. XIAO boosted gain off,   actual register 0x94 verified; Indicator 0x96. Original backups retained.</li> <li>SF6 / 125 kHz / CR4/5, four centers 909.500/909.750/910.000/910.250 MHz,   32-symbol preamble, 16-byte synthetic packets, -9 dBm.</li> <li>Warm fast RX, buffered 8 MHz SPI, unchanged-modulation reuse enabled.   Same XIAO image for every delay; unchanged Indicator reference image.</li> <li>100 packets/channel requested, balanced shuffled channel order (seed 606125),   varied unsynchronized arrival timing. Both HIL boards reboot between delays.</li> <li>No extra IRQ polling or packet traces; ordinary ownership/preamble guards   remain enabled. No RF retries, shorter channel count or altered preamble.</li> </ul> <p>At SF6/125, a symbol is 512 us. The requested listening visit rounds up to ceil(5.1 * 512) = 2,612 us; 32 programmed preamble symbols last 16,384 us. Using the user's nominal 453 us retune, the extra per-hop budget is:</p> <p><code>16,384 / 4 - 2,612 - 453 = 1,031 us</code></p> <p>Thus the 100 us grid runs from 0 through 1,000 us; 1,100 us would exceed the nominal full-sweep calculation. Sync/header time is not spent as extra scan budget. This is not a worst-case scheduling or acquisition guarantee.</p> <p>The delay is HIL-only: after a successful guarded production retune and BUSY-low observation, the CPU waits without SPI/IRQ operations, then starts a separate 2,612 us listening clock. The SX1262 is already receiving throughout that delay and may acquire a packet. This tests extra RX occupancy/settling, not a pre-SetRx delay or a period with RX disabled. Ordinary RX restarts after processing packets reset the visit clock without another channel delay. Zero delay preserves the previous production RX-start clock.</p> <p>An initial receive-only, 300 ms smoke check at +1,000 us measured 74 hops, minimum applied delay 1,000 us and minimum subsequent dwell 2,612 us. Its 17 clean full cycles averaged 16,235.941 us, maximum 16,260 us. No RF probe was transmitted in this check. The longer packet experiments below capture more scheduling variability, including host command handling.</p>"},{"location":"sf6_125_settling_validation/#results","title":"Results","text":"<p>All times in the last two columns are measured means, not target values. \"Received\" is successes before the next probe timed out; every row ended in one timeout. These first-failure samples do not estimate comparable PERs.</p> Added delay Received before miss Switch + delay Clean full cycle 0.0 ms 44 0.452381 ms 12.256886 ms 0.1 ms 4 0.548387 ms 12.669976 ms 0.2 ms 34 0.650424 ms 13.074105 ms 0.3 ms 53 0.753410 ms 13.485859 ms 0.4 ms 47 0.850830 ms 13.868454 ms 0.5 ms 66 0.952289 ms 14.273736 ms 0.6 ms 14 1.050333 ms 14.671156 ms 0.7 ms 21 1.151351 ms 15.076094 ms 0.8 ms 63 1.255113 ms 15.482272 ms 0.9 ms 19 1.352843 ms 15.880361 ms 1.0 ms 25 1.452750 ms 16.283488 ms <p>All 401 transmissions returned success: 390 valid receptions and 11 timeouts, spread across the eleven independently stopped settings. None completed 100/100 on each channel. All 52,609 timed hops passed RX-mode and software-cache checks, with one observed frequency write per hop and zero retune failures. Each positive-delay hop waited at least the requested time; every run's minimum subsequent idle dwell was 2,612 us. No receive-error counter increment or device error was reported. Successful RSSI was -42 to -40 dBm and SNR 9.5\u201311.8 dB.</p> <p><code>switch</code> measures production retune entry through BUSY-low observation; <code>settling</code> measures the following wait, including timer overhead; <code>switch_and_settle</code> combines them. Even zero requested delay records roughly 1\u20132 us of timer/bookkeeping overhead in the combined boundary. Listening dwell and full application scheduling are not included in retune time.</p> <p><code>idle_cycle</code> measures consecutive channel-0 return times, excluding initial cycles and cycles containing packet/guard-held visits. It still includes loop and USB work encountered during otherwise unheld visits. At +1.0 ms its mean is 100.512 us inside the preamble budget, but its maximum was 17.475 ms, exceeding 16.384 ms. At +0.9 ms the observed maximum was 16.153 ms. Therefore the last grid point fits only the nominal/mean calculation, not every observed full cycle. Legitimate packet holds can extend scan timing further.</p>"},{"location":"sf6_125_settling_validation/#conclusion-and-limits","title":"Conclusion and limits","text":"<p>Extra post-switch settling through the available timing budget did not establish loss-free four-channel reception. The 66 successes at +0.5 ms are not evidence that it is an optimum; the results are small, first-failure samples with different uncontrolled RF arrival phases. The added delay also extends total RX occupancy, so any improvement would not isolate analog settling from longer acquisition time.</p> <p>Every failure here was a timeout without a reported receive/decode error. Without an IRQ trace or synchronized independent RF capture, that does not prove absence of a preamble/header indication or identify the precise cause. It does not justify changing production packet guards or adding a permanent settling penalty. No production default was changed by this experiment.</p>"},{"location":"sf6_125_settling_validation/#reproduction-provenance-and-handoff","title":"Reproduction, provenance and handoff","text":"<pre><code>python tools/hil/profile_switch_settling.py --receiver COM31 --sender COM28 --output tools/hil/sf6_125_settling_normal_results.json\n</code></pre> <p>See harness instructions. Base <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> on <code>keymindCascade</code> plus local changes. RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL targets compiled; only XIAO needed an upload for the new receiver-side delay. All 45 selected host/native tests passed, including delay/visit separation, packet restart, timer wraparound, clean-cycle accounting, bounded grid and first-pass stop.</p> <p>Actually loaded firmware SHA-256:</p> <ul> <li>XIAO: <code>a0dbc113dcb297be34e22c0bc058db71c4108659e1e289679ecdbfc5c0009f8e</code></li> <li>Indicator, unchanged from SF5/250 sweep:   <code>3672ca330d4b2d3e8efa39edf2dbc3b27b8804dbb9a98f29267c85c41972a028</code></li> </ul> <p>Raw manifest and per-delay captures are preserved byte-for-byte. SHA-256, file suffixes after <code>tools/hil/sf6_125_settling_normal_results</code>:</p> Suffix SHA-256 <code>.json</code> <code>41a20c3d5b809cd225772980fbe0d305c14391659f10d685bf78f8bdf326e61c</code> <code>_0us.json</code> <code>47a73a35ed72ebc61b88bfe315e86bf7e15ba1d2d93e68ce92ce681e1ef73cef</code> <code>_100us.json</code> <code>b585ea01f605bc876da86ba2a35fbe6e7cc6543eb5e827ba190c51dca10dcb85</code> <code>_200us.json</code> <code>6ce378cd079eefae8450c7f5672281095b9b99e28e0c7920f024a4396606bb40</code> <code>_300us.json</code> <code>d93e7a258dddb6731c030e395e09c3f06b4d5988638cc85dc5cd0745256c6202</code> <code>_400us.json</code> <code>56bfe4cb7cbab2a660a232a2bf85b9bb87221ffade7c9bbce6d1116e6c30fcbf</code> <code>_500us.json</code> <code>fffb6c33a506f537913084fc4f5cc9f8009a4f0f61e4f290dd81a7409f53d1bd</code> <code>_600us.json</code> <code>7bc6dd41f0079f37bdbf77fc48c4113e26589bcce704850b106c33d057e34659</code> <code>_700us.json</code> <code>54170f5b63bbe8ffa231852bf892ea55d8579c33631775f29fb7c127197afb2a</code> <code>_800us.json</code> <code>f7c53375b29764b4369b84e8ac3244aa37e385c8738a9dfd7f3257d85a64a705</code> <code>_900us.json</code> <code>56bc3691f2046cafcf2115b2f6b7bd164e9c9039733ea51028db292deea10230</code> <code>_1000us.json</code> <code>f708af37caee8f689f2436567382458d63aba1269e8306ac6e4d0079677b9115</code> <p>Both boards rebooted to idle HIL after testing and answered ready. XIAO gain remained 0x94 and settling policy was returned to zero. Test firmware stays installed, per user request; no restore, commit or push was performed this turn. RAK4631, Indicator RP2040 and unrelated S3 soak work were untouched. The temporary build overlay was removed; no autonomous test TX remains.</p>"},{"location":"sf6_5p1_trace_validation/","title":"SF6 / 125 kHz: four channels at 5.1 chirps","text":"<p>Measured 2026-09-14. Seven packets received, then packet 8 missed. The run stopped at that first miss. No RF retry, other dwell, or higher/lower channel count was tested. The target of 100 packets per channel was not reached.</p> <p>Follow-up: SF8/125 at the same 5.1-chirp dwell missed on packet 13 and captured an off-channel preamble hold. That differs from the absence of observed preamble in this SF6 failure.</p>"},{"location":"sf6_5p1_trace_validation/#setup","title":"Setup","text":"<ul> <li>XIAO ESP32-S3 + WIO SX1262 scanner, COM31.</li> <li>SenseCAP Indicator ESP32-S3 reference transmitter, COM28.</li> <li>Four centers: 909.500, 909.750, 910.000, 910.250 MHz.</li> <li>SF6 / 125 kHz / CR4/5, 32-symbol programmed TX preamble.</li> <li>User-corrected dwell: 5.1 symbols, ceil(5.1 * 512) = 2,612 us.</li> <li>Same warm production fast retune, buffered 8 MHz SPI, packet guards.</li> <li>16-byte synthetic payloads at -9 dBm; balanced randomized channel order,   seed 606125; varied arrival timing, not synchronized to scan phase.</li> <li>IRQ changes, IRQ clears, hops and first guard deferrals buffered in RAM.   Additional read-only IRQ polling at nominal 64 us intervals while armed.   No per-event serial printing during capture. Trace read after each result.</li> </ul> <pre><code>python tools/hil/profile_switch_channels.py --receiver COM31 --sender COM28 --output tools/hil/sf6_125_5p1_trace_results.json --samples 100 --preamble 32 --max-channels 4 --dwell-symbols 5.1 --trace\n</code></pre>"},{"location":"sf6_5p1_trace_validation/#results-and-what-the-trace-establishes","title":"Results and what the trace establishes","text":"<p>Probes 1\u20137 succeeded on channels 3, 2, 1, 0, 2, 3, 1. Probe 8, sequence <code>944962150</code>, missed on channel 0 (909.500 MHz). Thus channel 0 had already received a valid probe; this was not a channel that never worked at all. Successful packets had RSSI -42 to -40 dBm and SNR 9.5 to 10.8 dB.</p> <p>The failed probe has a complete, non-overflowed 3,160-event trace:</p> <ul> <li>Expectation armed on channel 3 without selecting the expected channel.</li> <li>3,158 completed hops during the bounded 10-second confirmation interval.</li> <li>No observed nonzero IRQ bits: no preamble, header, RxDone or CRC event.</li> <li>No guard-held visit on any channel during that expectation.</li> <li>Receiver timeout at 10,000,369 us, with RX mode and zero device errors.</li> <li>Reference TX returned success. All USB sequence acknowledgements matched;   no stale replies, missing acknowledgements or cached transport recovery.</li> </ul> <p>The scanner was not stuck on the wrong channel by a false preamble. It also did not acquire a header and then fail a CRC check. The evidence locates the failure before observed preamble acquisition, not at payload decoding. It does not prove why acquisition failed: a short-visit/arrival-phase issue remains a candidate, as does an unobserved RF/reference issue. There was no independent RF capture, and the two MCU clocks were not synchronized.</p>"},{"location":"sf6_5p1_trace_validation/#actual-timing-during-the-failed-expectation","title":"Actual timing during the failed expectation","text":"Measurement Minimum Mean Maximum Receive dwell, 3,158 hops 2,613 us 2,628.706 us 2,646 us Retune, trace hop rows 526 us 538.700 us 630 us Channel 0 revisit interval, 789 cycles 12,643 us 12,666.829 us 12,705 us <p>The repeatable scan timing rules out a large software scheduling stall in the failed capture. The 32 programmed symbols occupy 16.384 ms, longer than that idle scan cycle; nevertheless, revisiting within the preamble did not ensure successful acquisition during these short individual visits.</p>"},{"location":"sf6_5p1_trace_validation/#successful-acquisition-traces","title":"Successful acquisition traces","text":"<p>Times below are relative to the logged hop completion onto the eventual receive channel, not a precisely captured RF edge or hardware RX-start edge. The trace observed the following progression for every successful probe: PreambleDetected (0x0004), HeaderValid (0x0014), RxDone (0x0016), consumption.</p> Probe Channel First observed preamble after hop RxDone after hop 1 3 1,838 us 32,982 us 2 2 1,836 us 35,470 us 3 1 1,844 us 35,151 us 4 0 2,332 us 37,329 us 5 2 1,847 us 35,532 us 6 3 1,831 us 30,731 us 7 1 1,329 us 32,567 us <p>After detecting preamble, the production guard kept those visits on-channel until reception completed. The failed probe never reached that observed state. This is not evidence that 5.1 symbols always suffice, nor does 7/8 estimate a stable packet-error rate or establish a channel-capacity limit.</p>"},{"location":"sf6_5p1_trace_validation/#instrumentation-and-reporting-caveats","title":"Instrumentation and reporting caveats","text":"<p>The failed capture made 115,783 diagnostic IRQ polls, costing a total 2,821,617 us (about 24.4 us each; maximum 61 us). These reads are not free: they alter loop load, although actual dwell and revisit timing were measured. This is not a matched A/B against the earlier untraced 4.8-symbol run, so seven successes versus two cannot be attributed solely to the extra dwell.</p> <p>The run used <code>channel_trace: 1</code>. During analysis, a reporting bug was found in the newly added <code>held_dwell</code> aggregate: production <code>startRecv()</code> resets the visit timestamp after reading a packet. That aggregate therefore omitted the preceding held reception time. Do not use its 2.709 ms mean as total held occupancy. The timestamped IRQ/hop trace above is the evidence for the actual 30.7\u201337.3 ms hop-to-RxDone intervals. The failed capture had no RX restart, so its dwell rows are unaffected.</p> <p>The source now keeps a separate channel-occupancy timestamp (<code>channel_trace: 2</code>, <code>trace_format: 2</code>). Both HIL targets compiled with this reporting-only correction; it was not flashed or RF-tested, and the saved raw result was not rewritten. Scheduler, packet guard and radio commands were not changed by that correction. Regression coverage includes passive SPI observation, bounded/frozen capture, occupancy accounting, page identity, requested dwell, and stopping at the first miss.</p>"},{"location":"sf6_5p1_trace_validation/#provenance-and-device-handoff","title":"Provenance and device handoff","text":"<ul> <li>Unmodified raw result and all eight traces</li> <li>Harness and trace format</li> <li>Earlier 4.8-symbol result</li> </ul> <p>Raw result SHA-256: <code>7caa16483b7b0000b388a1906395fe3d381bd0e40de73f48cd5c876d96deab3b</code>.</p> <p>Actually tested firmware SHA-256 (trace version 1, before reporting fix):</p> <ul> <li>XIAO: <code>35c201f367b0aaa693be03542a4c115024d1a70a2be2fbdbef2c94da5a6053ae</code></li> <li>Indicator: <code>8a25d84fc99f6aeaf8318bf4533767e16a9afc0de51394fce27d3a610c63b352</code></li> </ul> <p>Base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus local changes; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. No normal production firmware change this turn.</p> <p>Fresh full 8 MiB snapshots were saved and digest-verified before flashing:</p> <ul> <li>XIAO: <code>35aa2deeb8a8145bc54435c9f87b3db1c65f320f2568ee0b489305db1a6330c2</code></li> <li>Indicator: <code>dba59cde1df3c69dd2e5995950315951f75cd43886b21be8b14e261ec4b57309</code></li> </ul> <p>Both snapshots were restored afterward, separately verified against the full flash, and hardware-reset. Snapshots remain in the private current-user backup directory. The RAK4631 and Indicator RP2040 were not modified; the XIAO soak logger was not restarted. Changes were initially handed off locally before publication.</p>"},{"location":"sf6_channel_scan_validation/","title":"SF6 / 125 kHz channel-count test","text":"<p>Measured 2026-09-13. The run stopped on the third packet at the initial four channels: two arrived intact, then the receiver timed out. No five-channel test, lower-channel test, retry or retransmission was performed. Consequently this run does not establish a maximum channel count with 100% reception.</p> <p>Follow-up: four channels at 5.1 symbols with an IRQ trace stopped at packet 8 and observed no preamble acquisition during the miss.</p>"},{"location":"sf6_channel_scan_validation/#requested-setup","title":"Requested setup","text":"<ul> <li>Receiver: XIAO ESP32-S3 + WIO SX1262, COM31.</li> <li>Reference transmitter: SenseCAP Indicator ESP32-S3 LoRa processor, COM28.</li> <li>SF6 / 125 kHz / CR4/5, fixed 32-symbol programmed preamble.</li> <li>4.8-symbol receive visits: 2,457.6 us, rounded up to 2,458 us.</li> <li>Buffered 8 MHz SPI and the production fast retune/packet-ownership guards.</li> <li>Start at four channels and add one only after 100/100 packets on every channel.</li> <li>Stop at the first missing/corrupt packet; USB/reference/scanner faults are   reported separately as inconclusive fixture errors.</li> <li>16-byte synthetic payloads at -9 dBm. No identity/channel secrets transmitted.</li> <li>Four channel centers: 909.500, 909.750, 910.000 and 910.250 MHz.</li> <li>Balanced randomized channel order, seed 606125; varied arrival timing across   approximately two idle scan cycles. Arming an expectation does not select   the receiver's channel or reset its visit clock.</li> </ul> <p>The 100-packet-per-channel target was not reached: the explicit first-miss stop rule ended the run during its first shuffled pass.</p>"},{"location":"sf6_channel_scan_validation/#observations","title":"Observations","text":"Probe Channel center Outcome 1 910.250 MHz Valid 16 bytes, RSSI -40 dBm, SNR 10.8 dB 2 910.000 MHz Valid 16 bytes, RSSI -40 dBm, SNR 11.0 dB 3 909.750 MHz Receiver timeout; transmitter returned success <p>All three transmit acknowledgements and receiver reports matched their sequence IDs, with no missing/replayed/stale USB replies. On the miss, the receiver reported RX mode and zero device errors. The scanner recorded zero retune failures, RX-mode errors, modulation-cache errors or CRC/read errors. No probe was sent on 909.500 MHz before the stop condition.</p> Timing Minimum Mean Maximum Production retune to BUSY low, 3,467 hops 504 us 514.652 us 726 us Idle receive dwell, 3,463 visits 2,458 us 2,462.480 us 2,468 us <p>These samples include scanning during the bounded 10-second wait that confirmed the missing packet. There were 2,451 deferred attempts while production preamble/header/packet ownership held a visit; this is not a count of packets or failed retunes. Held visits are excluded from idle-dwell timing. All 3,467 successful retunes used the production fast-RX path.</p> <p>The means imply about 11.91 ms per four-channel idle cycle, excluding packet-held visits and small loop bookkeeping. Fast retuning alone did not produce 100% reception in this setup. This short stop-on-first-miss experiment does not identify the exact acquisition/phase cause, estimate a stable PER, prove that three channels would pass, or establish a universal board limit.</p>"},{"location":"sf6_channel_scan_validation/#implementation-and-reproduction","title":"Implementation and reproduction","text":"<p>This is a lab-only N-channel scheduler over the real <code>tuneProfile()</code> path. It reuses the two production profile slots as staging slots for the next frequency. Normal MeshCore <code>radio2</code> remains two-profile. The explicit test schedule intentionally does not use the normal two-profile automatic-preamble fit calculation or generic 6 ms switch / 4 ms loop allowances. It keeps the existing packet-protection guards and measures real dwell/retune overhead.</p> <pre><code>python tools/hil/profile_switch_channels.py --receiver COM31 --sender COM28 --output results.json --samples 100 --preamble 32\n</code></pre> <p>The controller has regression tests for balanced samples, starting at four, incrementing only after a perfect level, stopping without another TX, and distinguishing fixture failure from an RF miss. A separate RX-only 0.5-second setup check verified the scan timing before any capacity-test packets were sent. The capacity run itself was not repeated.</p> <ul> <li>Raw result, including the failing probe</li> <li>Host controller</li> <li>Firmware scheduler</li> <li>Harness instructions</li> <li>Earlier USB and fast-switch qualification</li> </ul> <p>Build provenance: base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus the local fast-switch and HIL changes; Arduino ESP32 2.0.17, Espressif32 6.11.0, RadioLib 7.7.1 pinned at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>. This is the extended V8 harness with <code>channel_sweep: 1</code>; its binaries differ from the earlier two-profile V8 measurements, so timings should not be treated as a same-image A/B.</p> <p>Firmware SHA-256:</p> <ul> <li>XIAO: <code>b0a6dd216be8a638fe088219801290d4632afcf63048f8597037650d68cd2301</code></li> <li>Indicator: <code>f0aa43a46e5e59ebf4768a255bd8c31d7a72c0038e11173314f78908b725786d</code></li> </ul>"},{"location":"sf6_channel_scan_validation/#device-handoff","title":"Device handoff","text":"<p>After the first-miss stop, both original 8 MiB flash snapshots were restored. Separate full-flash verification matched each backup's digest, followed by hardware reset. The private backups remain in the current-user backup directory. The Indicator RP2040 and RAK4631 were not modified. The interrupted XIAO soak logger remains stopped, and the temporary PlatformIO HIL overlay was removed. Implementation, tests and reports were initially handed off locally before publication.</p>"},{"location":"sf8_5p1_trace_validation/","title":"SF8 / 125 kHz: four-channel comparison at 5.1 chirps","text":"<p>Measured 2026-09-14. 12 packets received, then packet 13 missed. The first three balanced rounds passed (3/3 on every channel); the next probe on channel 3 failed. The run stopped at that miss. The target of 100 packets per channel was not reached. No RF retry or other channel count was tested.</p>"},{"location":"sf8_5p1_trace_validation/#setup-and-comparison","title":"Setup and comparison","text":"<p>Same XIAO ESP32-S3 + WIO SX1262 scanner (COM31) and SenseCAP Indicator ESP32-S3 reference transmitter (COM28). Four centers: 909.500, 909.750, 910.000 and 910.250 MHz. CR4/5, 32-symbol programmed preamble, 16-byte synthetic packets, -9 dBm, warm production fast RX and buffered 8 MHz SPI. Same production packet guards and read-only 64 us nominal IRQ polling; events buffered until each result. Randomized balanced channel order, seed 606125, varied arrival timing.</p> Setting Earlier SF6/125 This SF8/125 One symbol 512 us 2,048 us Requested 5.1-symbol dwell, rounded up 2,612 us 10,445 us 32 programmed preamble symbols 16.384 ms 65.536 ms Whole-run average measured retune 539.427 us 524.124 us Outcome before first miss 7 received, packet 8 missed 12 received, packet 13 missed Miss trace No observed preamble or hold Off-channel preamble and prolonged hold <p>Changing SF increases real listening and preamble durations together. This is not a matched same-image A/B or an isolated post-retune settling experiment. The small retune-time difference must not be treated as a new optimization; no extra settling delay was inserted. The earlier reporting-only held-visit timestamp correction is included in this trace-version-2 run.</p>"},{"location":"sf8_5p1_trace_validation/#failed-probe-an-off-channel-hold","title":"Failed probe: an off-channel hold","text":"<p>Failed sequence <code>388715032</code> targeted channel 3 / 910.250 MHz. The scanner instead observed PreambleDetected on channel 2 / 910.000 MHz, then its normal packet guard deferred the intended jump to channel 3. It never observed a valid header, header error, CRC event, or RxDone for that preamble.</p> <p>Times are software observations relative to expectation arming:</p> Time Event 207.649 ms Last hop onto target channel 3 before the long gap 240.542 ms Hop onto channel 2 250.030 ms PreambleDetected (0x0004) observed on channel 2 251.013 ms Guard defers channel 2 \u2192 3 at the 5.1-symbol deadline 342.287 ms Guard issues a clear of the still-latched preamble bit 342.794 ms Hop onto channel 3 finally completes 342.851 ms IRQ read confirms zero bits 9,999.270 ms Expectation timeout, RX mode, zero device errors <p>Channel-2 occupancy was about 102 ms. The target channel's revisit gap grew to 135.145 ms, compared with its ordinary ~43.875 ms cycle and the 65.536 ms programmed preamble. The delayed retune itself took only 550 us.</p> <p>The preamble-to-header budget from <code>calcMaxPacketMillis()</code> is ceil((32 + 8 + 4.25) * 2.048) = 91 ms. The strict millisecond timeout in <code>CustomSX1262::isReceiving()</code> clears a preamble that does not advance to a header. The observed 92.257 ms from the first IRQ observation to that clear is consistent with this existing protection mechanism.</p> <p>This identifies a prolonged off-channel hold that removed the next listening opportunity. It does not show that the ~0.52 ms jump needs more settling time. The RF source of that preamble is not proven: adjacent-channel pickup/ false detection or unrelated RF are possibilities. There was no independent RF capture or synchronized MCU clock. The earlier SF6 miss had no observed preamble or hold; this result does not establish the same cause for that miss.</p> <p>Simply shortening the guard risks cutting off valid long-preamble packets. Successful traces show that reception legitimately keeps a channel occupied well past 10.445 ms. No production guard change was made in this diagnostic.</p> <p>Follow-up: the stationary preamble investigation reproduced transmitter-associated off-frequency indications with full RX initialization and no hopping, on both boards. It strengthens the off-channel detection explanation without independently identifying the RF source of this historical missed probe. The SF6 miss remains a separate unresolved case.</p>"},{"location":"sf8_5p1_trace_validation/#measurements-and-checks","title":"Measurements and checks","text":"<ul> <li>All 12 successful payloads were valid; RSSI -42 to -41 dBm, SNR 12.0 to   14.2 dB. First observed preamble after logged hop completion ranged   7.433\u20139.485 ms; hop-to-RxDone ranged 105.056\u2013146.836 ms.</li> <li>Entire run: 1,167 fast hops, mean retune 524.124 us, maximum 774 us. Idle   dwell mean 10,452.444 us; held visits separately accounted for.</li> <li>Failed expectation: 910 trace events, zero overflow, 903 completed hops.   The 902 unheld dwells were 10,445\u201310,480 us, mean 10,450.424 us.</li> <li>Excluding the one held cycle, target-channel revisit intervals were   43,847\u201343,928 us, mean 43,874.580 us (224 intervals).</li> <li>Failed-expectation retunes: 511\u2013617 us, mean 520.443 us. The held occupancy   accounts for the anomalous target-channel revisit gap.</li> <li>Zero retune failures, RX-mode errors, modulation-cache errors, CRC/read   errors, USB stale replies or cached transport recovery. Reference TX rc=0.</li> <li>133,217 extra IRQ polls during the failed capture; total cost 3,241,509 us,   maximum 55 us. Polls add load; timestamps are observations, not exact IRQ   edges. No per-event serial output occurs during capture.</li> </ul> <p>This first-miss sample neither estimates a stable packet-error rate nor establishes a channel count with 100% reception.</p>"},{"location":"sf8_5p1_trace_validation/#reproduction-and-provenance","title":"Reproduction and provenance","text":"<pre><code>python tools/hil/profile_switch_channels.py --receiver COM31 --sender COM28 --output tools/hil/sf8_125_5p1_trace_results.json --samples 100 --preamble 32 --max-channels 4 --dwell-symbols 5.1 --trace --sf 8\n</code></pre> <ul> <li>Raw result and all 13 traces</li> <li>Earlier SF6/125 at 5.1 chirps</li> <li>Harness instructions</li> </ul> <p>Raw result SHA-256: <code>0d7e97173937f42708febf8276cdadc36578740735058d5da39b1b576e9ca49e</code>.</p> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>a68ab9834f62d0a5fb3f10c7a0b312c17d7d62795885cac4ea0dce483d6bf1ea</code></li> <li>Indicator: <code>bca1514bc6e09af6b1a9daed5bf4d3dbeeab988bcb856acbc73f59334395280d</code></li> </ul> <p>Base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus local changes; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL targets built successfully. All 27 selected host/native tests passed, including SF scaling, propagation to both RX staging slots and TX, cache checks, trace handling and first-miss stop.</p>"},{"location":"sf8_5p1_trace_validation/#device-handoff","title":"Device handoff","text":"<p>Fresh full 8 MiB backups were saved and digest-verified before flashing:</p> <ul> <li>XIAO: <code>e9533742103c9d7af11a3dc0c40496ca412b072e11880c2be785c92ef80e4310</code></li> <li>Indicator: <code>d4f39a0be1339f142ed329b68606347adeb514d26d6cc8bad43fb3d343ac1e2a</code></li> </ul> <p>Both were restored after the test, separately full-flash digest-verified, and hardware-reset. Backups remain in the private current-user backup directory. No identity or channel secrets were used in the synthetic RF probes. The RAK4631 and Indicator RP2040 were not modified; the XIAO soak logger was not restarted. The temporary HIL build overlay was removed. Source, tests and results were initially handed off locally before publication.</p>"},{"location":"spiffs_regular_file_reads/","title":"SPIFFS regular-file reads and login replay state","text":"<p>Arduino-ESP32 SPIFFS can return a truthy directory handle from a read-open of a nonexistent filename. <code>File::operator bool()</code> alone does not prove that a regular file exists. A directory's <code>size()</code> and <code>read()</code> are zero.</p> <p>The first privileged login on an upgraded G2 encountered this in <code>ClientACL::writeClientLoginReplayCeiling()</code>: opening the not-yet-created <code>/s_login_replay</code> appeared successful, then subtracting the eight-byte trailer from size zero underflowed. Copying the supposed records failed and login was rejected. Waiting or changing the repeater clock cannot fix that file-open bug.</p>"},{"location":"spiffs_regular_file_reads/#fix","title":"Fix","text":"<p>Use <code>mesh::openFileRead()</code> for regular-file reads. It checks existence and rejects directory handles, while preserving real empty files. Replay record counts also validate the minimum trailer size, record alignment, and maximum count before subtraction. An existing replay file that becomes unreadable is not treated as a new store.</p> <p>No replay records are cleared and authentication is not weakened. Invalid or unwritable replay state still fails closed. The first successful privileged login creates a 44-byte file: one 36-byte identity/ceiling record plus its eight-byte integrity trailer.</p> <p>Setting the repeater clock must not clear this file. Admission compares the sender's timestamp with that sender's saved boundary, not with the repeater's current time. Clearing the boundary could make captured requests reusable. A sender clock rollback is a separate condition and remains subject to the saved boundary after this fix.</p> <p>Companion directory enumeration uses the separate <code>openDirectory()</code> API, which deliberately permits SPIFFS virtual directories. Regular-file reads are also enforced for companion data, repeater/room logs, flood-rule verification, and HTTP packet-log downloads (missing logs return 404; real empty logs 200).</p>"},{"location":"spiffs_regular_file_reads/#audit-boundary","title":"Audit boundary","text":"<p>The audit covered file opens and size arithmetic in <code>src</code> and <code>examples</code>. Identity, region, clock, and common preference loaders already gate reads with filesystem existence checks; SPIFFS's <code>exists()</code> explicitly excludes directory handles. Relevant MQTT length subtraction follows validated headers and exact reads. ESP32 OTA staging uses partition APIs, not these SPIFFS file handles. Intentional directory enumeration must not be changed to a regular-file read.</p>"},{"location":"spiffs_regular_file_reads/#regression-checks","title":"Regression checks","text":"<ul> <li><code>test/test_client_acl_spiffs.py</code> compiles the actual <code>ClientACL.cpp</code> against   a filesystem that reproduces the misleading missing-file directory handle.   It covers first creation, fresh/stale login, reboot ceilings, corrupt and   unreadable state, short writes, failed publication, and truncated sources.</li> <li><code>test/test_regular_file_reads.py</code> executes production companion readers,   flood-file verification, and HTTP log delivery with the same filesystem   behavior, including platform-specific file API differences.</li> <li><code>test/test_esp32_tinyusb_cooperative_output.py</code> exercises both real role log   pumps, including missing logs and bounded output.</li> <li>Native ACL transaction, login persistence, and client-path persistence suites   retain the existing security and recovery coverage.</li> </ul> <p>The pre-fix actual ACL code was reproduced as <code>first_login=rejected</code>, one missing read-open, and no replay file. The fixed code accepted that identical scenario without a missing read-open and created the valid 44-byte record. Host simulations do not replace a post-flash LoRa login test on the G2.</p>"},{"location":"stats_binary_frames/","title":"Stats Binary Frame Structures","text":"<p>Binary frame structures for companion radio stats commands. All multi-byte integers use little-endian byte order.</p>"},{"location":"stats_binary_frames/#command-codes","title":"Command Codes","text":"Command Code Description <code>CMD_GET_STATS</code> 56 Get statistics (2-byte command: code + sub-type)"},{"location":"stats_binary_frames/#stats-sub-types","title":"Stats Sub-Types","text":"<p>The <code>CMD_GET_STATS</code> command uses a 2-byte frame structure: - Byte 0: <code>CMD_GET_STATS</code> (56) - Byte 1: Stats sub-type:   - <code>STATS_TYPE_CORE</code> (0) - Get core device statistics   - <code>STATS_TYPE_RADIO</code> (1) - Get radio statistics   - <code>STATS_TYPE_PACKETS</code> (2) - Get packet statistics</p>"},{"location":"stats_binary_frames/#response-codes","title":"Response Codes","text":"Response Code Description <code>RESP_CODE_STATS</code> 24 Statistics response (2-byte response: code + sub-type)"},{"location":"stats_binary_frames/#stats-response-sub-types","title":"Stats Response Sub-Types","text":"<p>The <code>RESP_CODE_STATS</code> response uses a 2-byte header structure: - Byte 0: <code>RESP_CODE_STATS</code> (24) - Byte 1: Stats sub-type (matches command sub-type):   - <code>STATS_TYPE_CORE</code> (0) - Core device statistics response   - <code>STATS_TYPE_RADIO</code> (1) - Radio statistics response   - <code>STATS_TYPE_PACKETS</code> (2) - Packet statistics response</p>"},{"location":"stats_binary_frames/#resp_code_stats-stats_type_core-24-0","title":"RESP_CODE_STATS + STATS_TYPE_CORE (24, 0)","text":"<p>Total Frame Size: 11 bytes</p> Offset Size Type Field Name Description Range/Notes 0 1 uint8_t response_code Always <code>0x18</code> (24) - 1 1 uint8_t stats_type Always <code>0x00</code> (STATS_TYPE_CORE) - 2 2 uint16_t battery_mv Battery voltage in millivolts 0 - 65,535 4 4 uint32_t uptime_secs Device uptime in seconds 0 - 4,294,967,295 8 2 uint16_t errors Error flags bitmask - 10 1 uint8_t queue_len Outbound packet queue length 0 - 255"},{"location":"stats_binary_frames/#example-structure-cc","title":"Example Structure (C/C++)","text":"<pre><code>struct StatsCore {\n    uint8_t  response_code;  // 0x18\n    uint8_t  stats_type;     // 0x00 (STATS_TYPE_CORE)\n    uint16_t battery_mv;\n    uint32_t uptime_secs;\n    uint16_t errors;\n    uint8_t  queue_len;\n} __attribute__((packed));\n</code></pre>"},{"location":"stats_binary_frames/#resp_code_stats-stats_type_radio-24-1","title":"RESP_CODE_STATS + STATS_TYPE_RADIO (24, 1)","text":"<p>Total Frame Size: 14 bytes</p> Offset Size Type Field Name Description Range/Notes 0 1 uint8_t response_code Always <code>0x18</code> (24) - 1 1 uint8_t stats_type Always <code>0x01</code> (STATS_TYPE_RADIO) - 2 2 int16_t noise_floor Radio noise floor in dBm -140 to +10 4 1 int8_t last_rssi Last received signal strength in dBm -128 to +127 5 1 int8_t last_snr SNR scaled by 4 Divide by 4.0 for dB 6 4 uint32_t tx_air_secs Cumulative transmit airtime in seconds 0 - 4,294,967,295 10 4 uint32_t rx_air_secs Cumulative receive airtime in seconds 0 - 4,294,967,295"},{"location":"stats_binary_frames/#example-structure-cc_1","title":"Example Structure (C/C++)","text":"<pre><code>struct StatsRadio {\n    uint8_t  response_code;  // 0x18\n    uint8_t  stats_type;     // 0x01 (STATS_TYPE_RADIO)\n    int16_t  noise_floor;\n    int8_t   last_rssi;\n    int8_t   last_snr;       // Divide by 4.0 to get actual SNR in dB\n    uint32_t tx_air_secs;\n    uint32_t rx_air_secs;\n} __attribute__((packed));\n</code></pre>"},{"location":"stats_binary_frames/#resp_code_stats-stats_type_packets-24-2","title":"RESP_CODE_STATS + STATS_TYPE_PACKETS (24, 2)","text":"<p>Total Frame Size: 26 bytes (legacy) or 30 bytes (includes <code>recv_errors</code>)</p> Offset Size Type Field Name Description Range/Notes 0 1 uint8_t response_code Always <code>0x18</code> (24) - 1 1 uint8_t stats_type Always <code>0x02</code> (STATS_TYPE_PACKETS) - 2 4 uint32_t recv Total packets received 0 - 4,294,967,295 6 4 uint32_t sent Total packets sent 0 - 4,294,967,295 10 4 uint32_t flood_tx Packets sent via flood routing 0 - 4,294,967,295 14 4 uint32_t direct_tx Packets sent via direct routing 0 - 4,294,967,295 18 4 uint32_t flood_rx Packets received via flood routing 0 - 4,294,967,295 22 4 uint32_t direct_rx Packets received via direct routing 0 - 4,294,967,295 26 4 uint32_t recv_errors Receive/CRC errors (RadioLib); present only in 30-byte frame 0 - 4,294,967,295"},{"location":"stats_binary_frames/#notes","title":"Notes","text":"<ul> <li>Counters are cumulative from boot and may wrap.</li> <li><code>recv = flood_rx + direct_rx</code></li> <li><code>sent = flood_tx + direct_tx</code></li> <li>Clients should accept frame length &gt;= 26; if length &gt;= 30, parse <code>recv_errors</code> at offset 26.</li> </ul>"},{"location":"stats_binary_frames/#example-structure-cc_2","title":"Example Structure (C/C++)","text":"<pre><code>struct StatsPackets {\n    uint8_t  response_code;  // 0x18\n    uint8_t  stats_type;     // 0x02 (STATS_TYPE_PACKETS)\n    uint32_t recv;\n    uint32_t sent;\n    uint32_t flood_tx;\n    uint32_t direct_tx;\n    uint32_t flood_rx;\n    uint32_t direct_rx;\n    uint32_t recv_errors;    // present when frame size is 30\n} __attribute__((packed));\n</code></pre>"},{"location":"stats_binary_frames/#command-usage-example-python","title":"Command Usage Example (Python)","text":"<pre><code># Send CMD_GET_STATS command\ndef send_get_stats_core(serial_interface):\n    \"\"\"Send command to get core stats\"\"\"\n    cmd = bytes([56, 0])  # CMD_GET_STATS (56) + STATS_TYPE_CORE (0)\n    serial_interface.write(cmd)\n\ndef send_get_stats_radio(serial_interface):\n    \"\"\"Send command to get radio stats\"\"\"\n    cmd = bytes([56, 1])  # CMD_GET_STATS (56) + STATS_TYPE_RADIO (1)\n    serial_interface.write(cmd)\n\ndef send_get_stats_packets(serial_interface):\n    \"\"\"Send command to get packet stats\"\"\"\n    cmd = bytes([56, 2])  # CMD_GET_STATS (56) + STATS_TYPE_PACKETS (2)\n    serial_interface.write(cmd)\n</code></pre>"},{"location":"stats_binary_frames/#response-parsing-example-python","title":"Response Parsing Example (Python)","text":"<pre><code>import struct\n\ndef parse_stats_core(frame):\n    \"\"\"Parse RESP_CODE_STATS + STATS_TYPE_CORE frame (11 bytes)\"\"\"\n    response_code, stats_type, battery_mv, uptime_secs, errors, queue_len = \\\n        struct.unpack('&lt;B B H I H B', frame)\n    assert response_code == 24 and stats_type == 0, \"Invalid response type\"\n    return {\n        'battery_mv': battery_mv,\n        'uptime_secs': uptime_secs,\n        'errors': errors,\n        'queue_len': queue_len\n    }\n\ndef parse_stats_radio(frame):\n    \"\"\"Parse RESP_CODE_STATS + STATS_TYPE_RADIO frame (14 bytes)\"\"\"\n    response_code, stats_type, noise_floor, last_rssi, last_snr, tx_air_secs, rx_air_secs = \\\n        struct.unpack('&lt;B B h b b I I', frame)\n    assert response_code == 24 and stats_type == 1, \"Invalid response type\"\n    return {\n        'noise_floor': noise_floor,\n        'last_rssi': last_rssi,\n        'last_snr': last_snr / 4.0,  # Unscale SNR\n        'tx_air_secs': tx_air_secs,\n        'rx_air_secs': rx_air_secs\n    }\n\ndef parse_stats_packets(frame):\n    \"\"\"Parse RESP_CODE_STATS + STATS_TYPE_PACKETS frame (26 or 30 bytes)\"\"\"\n    assert len(frame) &gt;= 26, \"STATS_TYPE_PACKETS frame too short\"\n    response_code, stats_type, recv, sent, flood_tx, direct_tx, flood_rx, direct_rx = \\\n        struct.unpack('&lt;B B I I I I I I', frame[:26])\n    assert response_code == 24 and stats_type == 2, \"Invalid response type\"\n    result = {\n        'recv': recv,\n        'sent': sent,\n        'flood_tx': flood_tx,\n        'direct_tx': direct_tx,\n        'flood_rx': flood_rx,\n        'direct_rx': direct_rx\n    }\n    if len(frame) &gt;= 30:\n        (recv_errors,) = struct.unpack('&lt;I', frame[26:30])\n        result['recv_errors'] = recv_errors\n    return result\n</code></pre>"},{"location":"stats_binary_frames/#command-usage-example-javascripttypescript","title":"Command Usage Example (JavaScript/TypeScript)","text":"<pre><code>// Send CMD_GET_STATS command\nconst CMD_GET_STATS = 56;\nconst STATS_TYPE_CORE = 0;\nconst STATS_TYPE_RADIO = 1;\nconst STATS_TYPE_PACKETS = 2;\n\nfunction sendGetStatsCore(serialInterface: SerialPort): void {\n    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_CORE]);\n    serialInterface.write(cmd);\n}\n\nfunction sendGetStatsRadio(serialInterface: SerialPort): void {\n    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_RADIO]);\n    serialInterface.write(cmd);\n}\n\nfunction sendGetStatsPackets(serialInterface: SerialPort): void {\n    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_PACKETS]);\n    serialInterface.write(cmd);\n}\n</code></pre>"},{"location":"stats_binary_frames/#response-parsing-example-javascripttypescript","title":"Response Parsing Example (JavaScript/TypeScript)","text":"<pre><code>interface StatsCore {\n    battery_mv: number;\n    uptime_secs: number;\n    errors: number;\n    queue_len: number;\n}\n\ninterface StatsRadio {\n    noise_floor: number;\n    last_rssi: number;\n    last_snr: number;\n    tx_air_secs: number;\n    rx_air_secs: number;\n}\n\ninterface StatsPackets {\n    recv: number;\n    sent: number;\n    flood_tx: number;\n    direct_tx: number;\n    flood_rx: number;\n    direct_rx: number;\n    recv_errors?: number;  // present when frame is 30 bytes\n}\n\nfunction parseStatsCore(buffer: ArrayBuffer): StatsCore {\n    const view = new DataView(buffer);\n    const response_code = view.getUint8(0);\n    const stats_type = view.getUint8(1);\n    if (response_code !== 24 || stats_type !== 0) {\n        throw new Error('Invalid response type');\n    }\n    return {\n        battery_mv: view.getUint16(2, true),\n        uptime_secs: view.getUint32(4, true),\n        errors: view.getUint16(8, true),\n        queue_len: view.getUint8(10)\n    };\n}\n\nfunction parseStatsRadio(buffer: ArrayBuffer): StatsRadio {\n    const view = new DataView(buffer);\n    const response_code = view.getUint8(0);\n    const stats_type = view.getUint8(1);\n    if (response_code !== 24 || stats_type !== 1) {\n        throw new Error('Invalid response type');\n    }\n    return {\n        noise_floor: view.getInt16(2, true),\n        last_rssi: view.getInt8(4),\n        last_snr: view.getInt8(5) / 4.0,  // Unscale SNR\n        tx_air_secs: view.getUint32(6, true),\n        rx_air_secs: view.getUint32(10, true)\n    };\n}\n\nfunction parseStatsPackets(buffer: ArrayBuffer): StatsPackets {\n    const view = new DataView(buffer);\n    if (buffer.byteLength &lt; 26) {\n        throw new Error('STATS_TYPE_PACKETS frame too short');\n    }\n    const response_code = view.getUint8(0);\n    const stats_type = view.getUint8(1);\n    if (response_code !== 24 || stats_type !== 2) {\n        throw new Error('Invalid response type');\n    }\n    const result: StatsPackets = {\n        recv: view.getUint32(2, true),\n        sent: view.getUint32(6, true),\n        flood_tx: view.getUint32(10, true),\n        direct_tx: view.getUint32(14, true),\n        flood_rx: view.getUint32(18, true),\n        direct_rx: view.getUint32(22, true)\n    };\n    if (buffer.byteLength &gt;= 30) {\n        result.recv_errors = view.getUint32(26, true);\n    }\n    return result;\n}\n</code></pre>"},{"location":"stats_binary_frames/#field-size-considerations","title":"Field Size Considerations","text":"<ul> <li>Packet counters (uint32_t): May wrap after extended high-traffic operation.</li> <li>Time fields (uint32_t): Max ~136 years.</li> <li>SNR (int8_t, scaled by 4): Range -32 to +31.75 dB, 0.25 dB precision.</li> </ul>"},{"location":"telemetry_decoder/","title":"Telemetry decoder","text":"<p>Paste raw hexadecimal packet data copied from the Let's Mesh packet analyzer to decode a repeater's scheduled temperature, battery-voltage, or external I2C-voltage snapshot. The decoder also accepts the payload hex without its MeshCore packet header and the Base64 pages returned by repeater or room-server CLI commands. Decoding happens entirely in this browser; pasted data is not uploaded or sent anywhere.</p> <p>The Source ID in a raw-packet result is the first eight bytes of the sending repeater's public key. Match that 16-character hex value against the public-key prefix recorded for your repeaters. It comes from the telemetry payload itself, so it is available even when only the payload was copied.</p>"},{"location":"telemetry_decoder/#send-raw-telemetry-packets","title":"Send raw telemetry packets","text":"<p>From an administrator CLI session, first configure a direct route to the MQTT observer that will receive and upload the raw packets. Use <code>direct</code> when the observer is a zero-hop neighbor:</p> <pre><code>set data.tx path direct\nsend telemetry.tx now\n</code></pre> <p>For a routed observer, provide its comma-separated hop hashes instead:</p> <pre><code>set data.tx path A1B2,C3D4\nsend telemetry.tx now\n</code></pre> <p>The shared route does not enable telemetry. Automatic telemetry is off on a fresh install; to explicitly keep the route manual-only before sending:</p> <pre><code>set telemetry.tx schedule off\nsend telemetry.tx now\n</code></pre> <p>The <code>send telemetry.tx now</code> command queues one <code>TTB1</code> temperature packet, one <code>TVB1</code> battery-voltage packet, and <code>IVB1</code> chunks for every connected I2C voltage channel. <code>TTB1</code> and <code>TVB1</code> carry up to 165 samples. Each <code>IVB1</code> carries 64, so a full 192-point/four-day channel takes three packets. Channels whose retained history is entirely zero are treated as disconnected and are not sent. The command requires at least one collected base sample and works even when the automatic schedule is off.</p>"},{"location":"telemetry_decoder/#decode-a-packet","title":"Decode a packetDecoded telemetry","text":"Try an analyzer example: Temperature packet Voltage packet I2C voltage packet I2C voltage CLI page Raw packet or payload hex <p>     Spaces, line breaks, colons, dashes, a leading <code>0x</code>, and a quoted     JSON field are accepted. CLI Base64 replies are also auto-detected. Paste     multiple compatible packet or reply lines together to merge them by     timestamp before downloading one CSV. Press Ctrl/Command+Enter to decode.   </p> Decode telemetry Clear        Show browser-local time      Download CSV Decode notes"},{"location":"telemetry_decoder/#analyzer-hex-examples","title":"Analyzer hex examples","text":"<p>The buttons load synthetic, protocol-valid zero-hop RAW_CUSTOM packets. A real scheduled snapshot normally has 165 samples and is much longer. Routed packets also contain path bytes before the <code>TTB1</code> or <code>TVB1</code> payload magic; the decoder finds and validates the payload automatically.</p>"},{"location":"telemetry_decoder/#temperature","title":"Temperature","text":"<pre><code>3E00545442311122334455667788800092651E0008000102354A4E5082\n</code></pre>"},{"location":"telemetry_decoder/#battery-voltage","title":"Battery voltage","text":"<pre><code>3E00545642311122334455667788800092651E000800010264C8FEFFDC\n</code></pre>"},{"location":"telemetry_decoder/#external-i2c-voltage","title":"External I2C voltage","text":"<pre><code>3E00495642311122334455667788800092651E00020800000004019026927109C427107FFF\n</code></pre> <p>All three examples identify the source as <code>1122334455667788</code>.</p>"},{"location":"telemetry_decoder/#cli-history-pages","title":"CLI history pages","text":"<p>The same page continues to decode the padded Base64 returned by these administrator commands:</p> Data Newest page Older-page example Samples per page MCU temperature <code>get telemetry.temp</code> <code>get telemetry.temp 2</code> 48 (24 hours) Battery voltage <code>get telemetry.volt</code> <code>get telemetry.volt 3</code> 48 (24 hours) I2C voltage <code>get telemetry.volt.i2c 2</code> <code>get telemetry.volt.i2c 2 4</code> 48 (24 hours) GPS position <code>get telemetry.gps</code> <code>get telemetry.gps 2</code> 24 (12 hours) <p>Paste either the complete reply beginning with <code>&gt;</code> or Base64 alone. For example:</p> <pre><code>get telemetry.volt 1\n&gt; EkDUcWoeMAAB5+bl5eTj4uLh4ODf3t7d3Nvb2tnZ2NfX1tXU1NPS0tHQ0M/Ozc3My8vKycnI/w==\n</code></pre> <p>Run <code>get telemetry.volt.i2c</code> without a channel first to list connected channels. For each channel, collect pages <code>1</code> through <code>4</code>. Paste all four reply lines into the decoder at once; it merges their timestamps into one 192-point, four-day table and downloads them as one CSV. The same merging works for the three <code>IVB1</code> analyzer packets from a full channel. Inputs must have the same telemetry type, source, LPP channel, and sample interval.</p> <p>An INA3221 exposes its three enabled hardware inputs as three consecutive LPP channels. When it is the only external sensor these are normally <code>2</code>, <code>3</code>, and <code>4</code>, in hardware-input order. Other sensors can shift the numbers, so copy the IDs reported by <code>get telemetry.volt.i2c</code> rather than assuming them.</p>"},{"location":"telemetry_decoder/#reading-the-table","title":"Reading the table","text":"<ul> <li>Timestamps default to UTC. Select Show browser-local time to convert   them for display and CSV export.</li> <li><code>TTB1</code> means a raw temperature snapshot, <code>TVB1</code> a raw battery-voltage   snapshot, and <code>IVB1</code> a packed external I2C-voltage chunk. The input summary   also reports the MeshCore route and path-hop count when a complete packet was   pasted.</li> <li>Temperature preserves exact whole degrees from <code>-50 C</code> through <code>+77 C</code>, plus   missing, below-range, and above-range states.</li> <li>Voltage preserves hundredths of a volt from <code>1.88 V</code> through <code>4.40 V</code>, plus   missing and out-of-range states.</li> <li>External I2C voltage uses a 15-bit code at <code>0.02 V</code> resolution. Code <code>0</code> is   missing/disconnected; codes <code>1</code> through <code>32767</code> cover <code>0.02 V</code> through   <code>655.34 V</code>. The LPP channel remains part of every page and raw chunk so   multiple monitor inputs cannot be mixed accidentally.</li> <li>GPS positions are reconstructed from signed 10-meter differentials. A zero   differential after the page origin is inherently ambiguous: it can represent   an unchanged fix, movement below the encoded resolution, or no fix. The table   labels those rows rather than inventing a coordinate.</li> <li>A GPS clipping warning means at least one movement exceeded the differential   range, so positions after that point can be less accurate.</li> </ul> <p>GPS history remains available through the administrator CLI, but <code>telemetry.tx</code> never puts GPS in RAW_CUSTOM packets. Location data therefore must come from a CLI Base64 page rather than analyzer hex.</p> <p>For the byte-level layouts, see Read repeater telemetry history.</p>"},{"location":"terminal_chat_cli/","title":"Terminal Chat CLI","text":"<p>Below are the commands you can enter into the Terminal Chat clients:</p> <p>For a timed RF carrier test on SX1262 or LR1110, use <code>cw on 2.5</code> or <code>cw2 on 2.5</code>, then <code>cw off</code> to stop early. See carrier-wave RF checks for profile selection, limits, and status commands.</p>"},{"location":"terminal_chat_cli/#companion-wifi-browser-terminal","title":"Companion WiFi browser terminal","text":"<p>On ESP32 WiFi Companions with WebConfig, open the node's LAN IP address and select CLI. The browser runs the same commands as the USB terminal and Full Companion's TCP terminal on port 5002, including contact import, contact selection, messages, remote login/commands, and delayed RF replies. Run <code>help</code> to list commands compiled into the device. Enable the tab with <code>set wifi.cli on</code>; the open setup AP does not expose it.</p> <p>For example, copy the complete <code>meshcore://...</code> string from <code>card</code> on another Companion, then run these commands on the receiving Companion:</p> <pre><code>import meshcore://&lt;full-contact-card-data&gt;\nlist\nto &lt;contact-name-or-prefix&gt;\n</code></pre> <p>Replace the placeholders; a bare public key is not a contact card. Import is queued for signature validation, so use <code>list</code> to confirm the contact appears. Explicit import works with manual contact addition enabled and bypasses the automatic discovery type/hop filters. It still respects contact storage limits; a full contact table follows the configured overwrite policy. <code>to</code> remains selected for subsequent <code>send</code>, <code>path</code>, <code>login</code>, and <code>cmd</code> commands within this terminal session.</p> <p>Only one USB, TCP, or browser text terminal owns the session at a time. An idle startup USB prompt can be borrowed by WiFi. Use <code>disconnect</code> or the browser's disconnect button to release it. Closing the page releases the session; if the connection disappears, it expires after 60 seconds without a poll. Long replies page into the browser automatically, and incoming replies continue appearing after a command finishes. Terminal scrollback starts at 4 KiB and can grow to 32 KiB for unread output, preferring PSRAM; it shrinks after reading and is freed when the session expires. If output exceeds the available buffer while unread, the browser reports the missing output.</p> <p>USB protocol-switch and USB MOTA ownership commands still apply to the USB connection. Use the WiFi MOTA seeder on port 5001 for a host folder over WiFi.</p>"},{"location":"terminal_chat_cli/#local-maintenance-commands","title":"Local maintenance commands","text":"<p>Local means a connection directly to the node: USB, BLE or WiFi/Ethernet Companion protocol, a TCP terminal, or the browser CLI on the LAN. These connections can use the following commands when the role and build include the corresponding feature:</p> Command Result <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code> Runtime diagnostics <code>get prv.key</code> Node identity private key; Companion requires private key export enabled in the build <code>get password</code> Infrastructure admin password; Companion reports that it has no admin password <code>erase</code> Erase stored identity and settings; reboot for a fresh node <code>get wifi.pwd</code> Stored WiFi password on WiFi builds <code>get mqttN.password</code>, <code>get mqttN.token</code> Stored credentials for MQTT slot N <code>get acl</code>, <code>log</code> Infrastructure ACL or captured packet log; these stores do not exist on Companion <p>The command text is the same for direct connections. A binary Companion app can send <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>) followed by the ASCII command, without switching into terminal mode. The response is <code>0x1D</code> (<code>RESP_CODE_CLI_REPLY</code>) followed by the reply text. For example, payload <code>42 67 65 74 20 70 61 73 73 77 6f 72 64</code> runs <code>get password</code>. USB framing remains the normal Companion frame; BLE and TCP use their existing Companion transport framing.</p> <p><code>set freq &lt;MHz&gt;</code> is available on these local connections and through authorized LoRa administration, just like <code>set radio</code>. It saves the frequency without changing bandwidth, spreading factor, or coding rate and requires a reboot to apply. Infrastructure roles also apply the board's transmit-power limit.</p> <p>Commands relayed to another node using <code>cmd</code> travel over LoRa and retain the remote restrictions on local-only maintenance and secret reads. These local permissions do not add an ACL or packet-log store to Companion. Use <code>list</code> or the binary contacts operations for Companion contacts. Interactive chat commands still use the text terminal or their corresponding binary protocol operations.</p> <p>The browser CLI requires station/LAN mode and <code>wifi.cli on</code>. Infrastructure uses its admin login; Companion uses the trusted LAN. Configuration forms keep password fields masked; explicit local CLI getters return their values.</p>"},{"location":"terminal_chat_cli/#companion-contact-and-channel-tx-profiles","title":"Companion contact and channel TX profiles","text":"<p>Choose where the Companion transmits to a contact or group channel:</p> <pre><code>set tx.user \"Alice Jones\" radio2\nget tx.user \"Alice Jones\"\nset tx.channel 0 both\nset tx.channel #wardriving radio\nget tx.channel 0\n</code></pre> <p>Values are <code>auto</code>, <code>radio</code>, <code>radio2</code>, <code>both</code>, and <code>off</code>. <code>auto</code> follows <code>radio2.cross</code>; explicit choices override it. Radio2 must still be in <code>rxtx</code> mode, and a <code>radio2</code>-only send fails when it cannot transmit. These settings persist and also apply to messages sent by the phone app. Use exact names, a channel index, or <code>key:&lt;unique public-key prefix&gt;</code> for a contact. See the routing guide for which requests/replies are covered and how to reset a choice.</p>"},{"location":"terminal_chat_cli/#companion-usb-mode","title":"Companion USB mode","text":"<p>Updated 1.17.1.6 USB Companion builds, including ordinary and Full builds, start in ASCII at 115200 baud. A valid framed app command automatically selects Binary Companion. You can open a terminal without a start token:</p> <pre><code>picocom --baud 115200 /dev/ttyACM0\n</code></pre> <p>Current source waits for input before printing the USB banner. Press Enter or type a command. This preserves the clean first response needed by binary apps; see USB client validation for release status.</p> <p>For older firmware or a port already in Binary mode, use:</p> <pre><code>picocom --baud 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre> <p><code>--initstring</code> sends this exact terminal-start line automatically:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>The carriage return is required in Binary mode. Control tokens are recognized only as complete CR/LF-delimited lines, so the same text embedded in unrelated unframed input cannot switch modes accidentally.</p> <p>Binary Companion frames can contain terminal control bytes. The <code>spchex</code> input map renders those bytes as bracketed hexadecimal during the short transition instead of allowing them to change the local terminal's character set or display state. It leaves high-bit bytes unchanged so a UTF-8 terminal displays emoji and non-ASCII text normally. Do not add <code>8bithex</code> unless you explicitly want UTF-8 bytes displayed as sequences such as <code>[f0][9f][91][8b]</code>. Once the terminal banner appears, the start sequence has already succeeded; do not enter it again as a terminal command.</p> <p>Send the following exact sequence to return to the binary protocol:</p> <pre><code>+++MESHCORE-TERM-STOP\n</code></pre> <p>If logging shares the primary USB port (ESP32), first run <code>set usb.logging off</code>. With logging still on, the stop token reports an error and keeps ASCII logging active. nRF52 Full's separate logging port can remain enabled.</p> <p>An observable USB session reset restores ASCII after clearing the previous client's state. Native USB with DTR can detect a terminal closing; ESP32 hardware USB Serial/JTAG detects bus resets and physical host loss. USB-to-UART bridges usually cannot detect a terminal closing. Use the start token on ports that remain in Binary mode; idle time does not select ASCII.</p> <p>Both modes use the same port at 115200. Selecting 57600 is not a portable mode switch: native USB CDC devices ignore the requested baud, while USB-to-UART devices really change the UART timing and receive corrupt data. Binary mode is the framed Companion API used by apps and <code>meshcli</code>; close the terminal before opening that port from an app.</p> <p>All USB Companion builds automatically switch when they see a complete <code>&lt;</code>-prefixed Companion frame at an empty prompt. The explicit start/stop tokens remain available. See Companion USB CLI and binary switcher for the state machine and limitations.</p>"},{"location":"terminal_chat_cli/#commands","title":"Commands","text":"<p>ESP32 and nRF52 Full Companions include an offline World English Bible lookup:</p> <pre><code>get reader 3:16\n</code></pre> <p>This returns a single complete verse from the embedded corpus, using plain ASCII punctuation with unchanged wording and capitalization, through the local USB/TCP terminal. See Reader lookup and compression for the source, supported build profiles and memory costs.</p> <pre><code>set freq {frequency}\n</code></pre> <p>Set the saved LoRa frequency. Example: <code>set freq 915.8</code>. Available over local connections and authorized LoRa CLI; reboot to apply.</p> <pre><code>set tx {tx-power-dbm}\n</code></pre> <p>Sets LoRa-chip transmit power in dBm. The firmware rejects values outside the radio/board limit; external-PA boards can have a lower input-power ceiling than the radio chip itself.</p> <pre><code>set name {name}\n</code></pre> <p>Sets your advertisement name.</p> <pre><code>get bluetooth.name\nset bluetooth.name {name|default}\n</code></pre> <p>Shows or changes the complete Bluetooth device name without changing the mesh advertisement identity. A custom name may contain spaces and is limited to 31 valid UTF-8 bytes. <code>default</code> restores <code>MeshCore-&lt;node name&gt;</code>. The saved change takes effect after reboot. <code>get ble.name</code> and <code>set ble.name</code> are short aliases.</p> <pre><code>get bluetooth.mac\nset bluetooth.mac {address|random|random-every-boot|random-after-connect|default}\nget bluetooth.stealth\nset bluetooth.stealth {on|off}\n</code></pre> <p>Shows or changes the Bluetooth identity on Companion builds with BLE. A literal address must be BLE random-static, such as <code>C2:11:22:33:44:55</code>. <code>random</code> generates and saves one address; <code>random-every-boot</code> generates a new one on each startup (<code>random everyboot</code> is also accepted). <code>random-after-connect</code> keeps its address across unused power cycles, then rotates on the next boot after an authenticated connection. <code>default</code> or <code>clear</code> restores the factory address without changing the stealth flag. Reboot, forget the old phone entry, and pair again after an address change. <code>get ble.mac</code> and <code>set ble.mac</code> are short aliases.</p> <p>The independent <code>bluetooth.stealth</code> flag defaults off and preserves the chosen address policy. With it on, the node is discoverable until its first authenticated pairing, then accepts only that bonded peer. Custom and saved random addresses keep the bond across boots; rotating modes reopen pairing when the address rotates, leaving stealth enabled. It still transmits the directed or allowlisted packets BLE requires for reconnection. Repeating <code>on</code> keeps the bond. Send <code>off</code>, then <code>on</code>, then reboot to reopen pairing manually. <code>ble.stealth</code> is the short alias. Flag changes require reboot.</p> <pre><code>set lat {latitude}\n</code></pre> <p>Sets your advertisement map latitude. (decimal degrees)</p> <pre><code>set lon {longitude}\n</code></pre> <p>Sets your advertisement map longitude. (decimal degrees)</p> <pre><code>set af {air-time-factor}\n</code></pre> <p>Sets the transmit air-time-factor. Deprecated - use <code>set dutycycle</code> instead.</p> <pre><code>get powersaving\nset powersaving {on|off}\n</code></pre> <p>Shows or changes Companion device power saving. On ESP32 this controls CPU and GPS idle behavior; it does not change LoRa RXPS or WiFi modem sleep.</p> <pre><code>get usb.logging\nset usb.logging {on|off} [reboot]\n</code></pre> <p>Shows or changes persistent live USB debug and packet output in an ordinary USB-loggable Companion or Full Companion. USB Companion and Full start off on a fresh install with logging disabled to protect framed traffic. nRF52 Full changes its interface count after a reboot and keeps Companion on interface <code>00</code>. Every ESP32 Full Companion has one TTY and needs no reboot: logging uses the active text terminal, disables framed Binary Companion on USB, and continues accepting <code>set usb.logging off</code>. Turning logging off leaves the port in the normal ASCII terminal, matching fresh firmware. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch it to Binary Companion afterward.</p> <pre><code>reboot\n</code></pre> <p>Sends an acknowledgement, then reboots the Companion one second later. The delay gives either the USB terminal or the Full Companion TCP terminal on port 5002 time to deliver the reply before its transport disappears.</p> <pre><code>get radio.rxps\nget radio.rxps.config\nset radio.rxps {off|on|level 1-10 [preamble 16|32]|rx_us sleep_us}\n</code></pre> <p>Shows or changes LoRa receive duty cycling on supported radios. <code>get radio.rxps.config</code> also reports the saved level and preamble assumption so automation can restore a level-based preference exactly. Fresh Cascade builds select level 8 with a 16-symbol timing assumption. The <code>preamble</code> argument controls the RXPS calculation; it does not change the physical wire preamble. A configured level is the minimum: when faster SF/BW settings shorten the timing window, firmware raises the effective level only as far as needed, up to level 10. Starting with v1.17.1.5, SF5-SF8 packets normally use a 32-symbol physical preamble. Firmware selects 64, then 128, only when every shorter choice fails to enable RXPS at any level. The configured values remain unchanged, so every radio change recalculates from the saved minimum. A slower tuple returns to that exact level and the shortest viable wire preamble.</p> <p>If neither adjustment leaves enough time for the radio to wake, RXPS stays logically enabled but receives continuously instead of rejecting the radio setting or starting an invalid duty cycle. The Companion terminal's <code>get radio.rxps</code> reports this as <code>mode=continuous-fast</code> and reports any <code>effective-level</code> or <code>effective-preamble</code> adjustment; <code>get radio.rxps.config</code> reports the persisted preference. A later compatible SF/BW change resumes duty cycling without another RXPS command.</p> <p>For the SX1262+TCXO boards tested here, these fast combinations are the useful RXPS boundary profiles (CR does not change the RXPS preamble timing):</p> SF BW (kHz) Wire preamble Effective preamble Minimum effective level RX / sleep 7 500 32 32 7 2731 / 6101 us 6 250 32 32 7 2731 / 6101 us 5 125 32 32 7 2731 / 6101 us 5 250 64 64 8 1252 / 6424 us 6 500 64 64 8 1252 / 6424 us 5 500 128 128 8 626 / 6398 us 5 62.5 32 16 10 4096 / 6272 us <p>The 64- and 128-symbol rows require the v1.17.1.5-or-newer adaptive-preamble contract on every sender that may reach the RXPS receiver. Cascade/USA builds on a Heltec V4 and WisMesh Tag (RAK4631 target) passed 16/16 packets in each direction at both SF5/BW250/64 and SF5/BW500/128, CR5, 909.950 MHz. An older sender makes a long-preamble timing window unsafe, so use continuous RX for a mixed deployment. Retry packets use the same physical preamble as other packets.</p> <pre><code>get wifi.powersave\nset wifi.powersave {none|min|max}\n</code></pre> <p>Shows or changes the persisted WiFi modem-sleep policy on ESP32 WiFi Companion builds. Full Companion requires at least <code>min</code> while BLE is present and rejects <code>none</code>. The WebConfig WiFi card and the normal binary Companion protocol expose the same setting; binary clients do not need the terminal-start token. On an ESP32 Full Companion whose primary mesh radio is ESP-NOW, <code>max</code> is also unavailable because maximum modem sleep can make the station miss ESP-NOW broadcasts, which the access point does not buffer. A previously saved <code>max</code> value is capped to and reported as <code>min</code>, and a new <code>max</code> selection is rejected. Such a WiFi/BLE/primary-ESP-NOW build therefore uses <code>min</code>.</p> <pre><code>get espnow.channel\nset espnow.channel &lt;1-13&gt;\n</code></pre> <p>On builds whose primary mesh radio is ESP-NOW, this shows or saves the primary radio's channel. The default is channel 1. Use only a channel permitted in your region, and restart or power-cycle the node after changing it. Every primary ESP-NOW peer must use the same channel.</p> <p>On Full Companion, the setup AP and infrastructure-WiFi station also share that channel, so the router's 2.4 GHz radio must remain fixed to it. Power saving does not permit separate channels. <code>wifi.powersave max</code> is unavailable on these ESP32 Full builds and <code>min</code> is the coexistence setting. This channel setting is also distinct from <code>bridge.channel</code>, which controls the optional ESP-NOW bridge transport. An updated LoRa-primary ESP-NOW bridge can join this raw primary transport by selecting the same channel and running <code>set bridge.format raw</code>; its default <code>wrapped</code> format remains the bridge-to-bridge protocol.</p> <pre><code>get radio.rxgain\nset radio.rxgain {on|off}\nget radio.fem.rxgain\nset radio.fem.rxgain {on|off}\nget radio.fem.txgain\nset radio.fem.txgain {on|off}\n</code></pre> <p><code>radio.rxgain</code> changes the radio chip's boosted receive-gain mode. The FEM settings control the external receive-path LNA or transmit-path gain on supported boards. Changes are applied immediately and saved across reboots; changing either receive-gain path also recalibrates the radio noise floor. Boards without the respective control report it as unsupported.</p> <pre><code>time {epoch-secs}\n</code></pre> <p>Set the device clock using UNIX epoch seconds. Example:  time 1738242833</p> <pre><code>advert\n</code></pre> <p>Sends an advertisement packet</p> <pre><code>clock\n</code></pre> <p>Displays current time per device's clock.</p> <pre><code>ver\n</code></pre> <p>Shows the device version and firmware build date.</p> <pre><code>card\n</code></pre> <p>Displays your 'business card', for others to manually import</p> <pre><code>import {card}\n</code></pre> <p>Imports the given card to your contacts.</p> <pre><code>list {n}\n</code></pre> <p>Lists favorite contacts first, then all remaining contacts. Each group is ordered by the most recent advertisement. Optional <code>{n}</code> limits the displayed contacts after applying that order.</p> <pre><code>show\nshow adverts {on|off}\nshow channels {on|off}\nshow emergency {on|off}\n</code></pre> <p>Controls unsolicited receive output in the USB terminal. Plain <code>show</code> reports the current settings, and <code>show {category}</code> reports one category. At boot, advertisements and ordinary channel messages are hidden while <code>#emergency</code> messages are shown. The three controls are independent, so <code>show channels on</code> does not override <code>show emergency off</code>.</p> <p>These filters affect terminal printing only. Messages still enter the offline queue and are delivered through the binary Companion protocol. Changes remain active when switching between terminal and binary mode and reset to their defaults after reboot.</p> <pre><code>to\n</code></pre> <p>Shows the name of current recipient contact. (for subsequent 'send' commands)</p> <pre><code>to {name-prefix}\n</code></pre> <p>Sets the recipient to the first matching contact (in 'list') by the name prefix. (ie. you don't have to type whole name)</p> <pre><code>path\n</code></pre> <p>Shows the saved outgoing path for the current <code>to</code> recipient. This command and all path changes require a recipient to be selected first.</p> <pre><code>path direct\npath clear\npath {hop-hash...}\n</code></pre> <p>Sets the outgoing path used by subsequent <code>login</code>, <code>send</code>, and <code>cmd</code> commands. <code>direct</code> selects a zero-hop route. <code>clear</code> forgets the saved route, causing the next operation to use flood routing and allowing normal path discovery to learn a replacement.</p> <p>Explicit paths use spaces, commas, or a mixture of both between hop hashes. Each hop must contain exactly 2, 4, or 6 hexadecimal digits, and every hop in one path must use the same width. Whitespace and hexadecimal letter case do not matter. The setting is saved with the selected contact.</p> <p>For example:</p> <pre><code>to Hilltop Repeater\npath A1B2C3,D4E5F6\npath 7773D0 7E7662\npath\nlogin my-admin-password\n</code></pre> <pre><code>login {admin-password}\n</code></pre> <p>Sends a remote login request to the current recipient. Select a repeater, room, or other remotely managed node with <code>to {name-prefix}</code> first. The password is masked with <code>*</code> while it is entered and must be 1-15 UTF-8 bytes; longer passwords are rejected instead of truncated. Login uses the route shown by <code>path</code>: a known or explicitly set route is direct, while an unknown route is flooded.</p> <p>Login results arrive asynchronously. A successful modern response displays the remote ACL permissions byte and server protocol level. A wrong password, an unreachable target, or a server that does not support remote login normally produces a timeout because those nodes do not send a rejection packet.</p> <pre><code>cmd {remote-command}\n</code></pre> <p>Sends CLI data to the current recipient. Wait for the login result before sending the first command. The remote node applies its own ACL permissions, and any reply appears asynchronously as <code>CLI -&gt; from {name}</code>. The response window is 300% of the route estimate. A routed send is displayed as <code>DIRECT via path {hop,...}</code> with the exact prefixes copied into the packet; in MeshCore, <code>DIRECT</code> is the route class for an explicit path, not a synonym for zero hops. A matched reply also shows its local round-trip time, measured from queueing the command through receiving the result. This includes both radio directions and remote execution; it is not execution-only CPU time. Only one terminal <code>cmd</code> can be pending at a time.</p> <p>For example:</p> <pre><code>to Hilltop Repeater\nlogin my-admin-password\nLOGIN -&gt; Hilltop Repeater accepted (ACL permissions 0x03, server v13)\ncmd ver\ncmd get radio\n</code></pre> <p>The exact commands and permissions depend on the target firmware. <code>cmd</code> does not run a command on the local Companion; it sends the text over LoRa to the selected node.</p> <p>Incoming direct-route messages are labeled <code>ROUTED</code>, not <code>DIRECT</code>. Forwarders consume direct-route prefixes as the packet travels, so the destination cannot recover the reply's actual hop history from the received packet. Use <code>trace</code> when the return route itself must be verified.</p> <pre><code>send {text}\n</code></pre> <p>Sends the text message (as DM) to current recipient.</p> <pre><code>trace\n</code></pre> <p>Traces the saved round-trip route to the current recipient and displays the SNR at each hop. Select the recipient first with <code>to {name-prefix}</code>.</p> <pre><code>trace {name-prefix}\n</code></pre> <p>Traces a recipient directly without changing the current <code>to</code> selection. A trace requires a known direct path; use normal messaging or path discovery first if the terminal reports that no valid path is available. Only one terminal trace can be pending at a time, and a missing response is reported as a timeout.</p> <p>For example:</p> <pre><code>to Hilltop Repeater\ntrace\ntrace Downtown\n</code></pre> <p>The displayed route uses one- or two-byte node hashes and per-hop SNR values. Saved three-byte paths are traced with two-byte prefixes because the trace packet format has no three-byte hash-size mode.</p> <p>To trace an explicit route instead of a saved contact path, provide the prefix size followed by the complete ordered route:</p> <pre><code>trace path 1 12 34 56 34 12\ntrace path 2 1234,ABCD,5678,ABCD,1234\ntrace path 4 12345678, ABCDEF01 89ABCDEF, ABCDEF01,12345678\n</code></pre> <p>Prefix separators may be spaces, commas, or any mixture of them. Each prefix must contain exactly 2, 4, or 8 hexadecimal digits for a 1-, 2-, or 4-byte trace respectively. Three-byte traces are not supported.</p> <p>The prefixes are used exactly in the order entered. To receive the trace result, enter the complete outward route followed by its return route, as in the mirrored examples above. A route that does not return to this node will eventually report a timeout.</p> <pre><code>reset path\n</code></pre> <p>Resets the path to current recipient, for new path discovery. This is retained as an alias for <code>path clear</code>.</p> <pre><code>public {text}\n</code></pre> <p>Sends the text message to the built-in <code>Public</code> group channel.</p> <pre><code>channels\n</code></pre> <p>Lists the configured channel slots and names without exposing their secrets.</p> <pre><code>channel {name-or-slot} {text}\n</code></pre> <p>Sends a message to any configured channel by its exact name or numeric slot. Use the slot shown by <code>channels</code> when a channel name contains spaces.</p> <p>For example:</p> <pre><code>channels\nchannel #rgdata Hello from Eugene\nchannel 2 Another message\nshow channels on\n</code></pre> <p>Messages are UTF-8. Emoji use multiple bytes toward the available message length, which also includes the sender-name prefix added over the air.</p>"},{"location":"usb_serial_backpressure/","title":"Native USB backpressure and radio liveness","text":"<p>ESP32-S2/S3 builds using native TinyUSB CDC (<code>ARDUINO_USB_MODE=0</code> and CDC-on-boot) must not wait for a computer to read USB output. In the bundled Arduino-ESP32 2.0.17 core, <code>USBCDC::write()</code> can wait indefinitely for transmit space; its configured timeout bounds a mutex, not that wait. This can stop the same loop that services LoRa, even while the USB connection still appears open.</p>"},{"location":"usb_serial_backpressure/#firmware-behavior","title":"Firmware behavior","text":"<ul> <li>Native CDC output uses a single FIFO attempt, not Arduino's wait-for-space   write or flush. TinyUSB's internal short mutex operations still apply; this   is a no-host-progress-wait guarantee, not a lock-free driver replacement.</li> <li>Functional text and diagnostics share one ordered 4 KiB queue. Diagnostics   leave 3 KiB reserved for commands. A diagnostic backlog alone does not prevent   command input. A stalled host may lose diagnostic records; radio work continues.</li> <li>A connected terminal that exceeds its bounded output capacity gets an explicit   dropped-byte notice when transmission resumes. Large local file dumps and   recent-repeater listings advance between radio service passes instead.</li> <li>File dumps stop at their initial file size and emit <code>-&gt; EOF</code> only after the   final accepted record. Corrupt stored lines exceeding 640 bytes are omitted   with a visible notice. Recent-repeater output is a live, bounded-cursor view;   incoming packets can change its ordering while it is being printed.</li> <li>Disconnects discard pending old-session text and reset the role's partial   command/listing state. Binary/mOTA transitions suppress pending text notices.   Bytes already transmitted cannot be recalled.</li> <li>Companion frames retain and retry short writes. An mOTA request is admitted   only when its complete, at-most-11-byte record fits.</li> <li>nRF52, UART, and USB-Serial-JTAG behavior is not changed by this native-CDC path.</li> </ul> <p>Host software must also keep reading independently of command writes. A serial relay should start its reader before the first command, use finite write and response deadlines, avoid discarding received packet logs, and cancel I/O during shutdown. A response timeout must not allow a late reply to satisfy another command: the CLI has no transaction identifiers. Updating firmware alone does not correct an indefinite host-side serial write.</p>"},{"location":"usb_serial_backpressure/#regression-checks","title":"Regression checks","text":"<p>Run only one PlatformIO process in the checkout at a time.</p> <pre><code>python test/test_esp32_tinyusb_nonblocking.py\npython test/test_esp32_tinyusb_role_hygiene.py\npython test/test_esp32_tinyusb_cooperative_output.py\npython test/test_esp32_usb_serial_hygiene.py\npython test/test_nrf52_usb_logging_contract.py\npio test -e native -f test_nrf52_debug_output -f test_serial_packet_log -f test_serial_mode_switch -f test_mesh_tables\n</code></pre> <p>The first test compiles the real USB facade against a simulated 64-byte FIFO, including stopped readers, reconnects, protocol transitions, and other-platform fallbacks. Host simulations cannot establish that every real USB driver or endpoint failure has recovered.</p> <p>A Full Station G2 validation build with USA Cascadia radio settings and the Cascade profile can be made using the normal build entry point. The portable <code>standard</code> recipe preserves the deployed partition layout but omits LoRa OTA; it still has the browser firmware uploader. The <code>auto</code>/<code>full</code> recipe instead enables the expanded feature set and partition layout: its merged image is not an app-only update for a device with the legacy layout.</p> <pre><code>MESHDEBUG_OVERRIDE=on PACKET_LOGGING_OVERRIDE=on \\\n  bash build.sh build-firmware Station_G2_repeater --build-profile full \\\n  --radio-preset usa-cascadia --profile cascade\n</code></pre> <p>Before installing on hardware, preserve the device identity, preferences, and existing partition layout. Then verify USB command responses and repeated LoRa logins with the relay running, paused, and stopped, including a host that leaves USB open without reading. Check LoRa recovery separately from USB OUT recovery; fixing transmit backpressure does not prove an unrelated OUT endpoint fault is resolved. Do not erase or repartition the radio as part of this test.</p>"},{"location":"v4_pixel5_font_trial/","title":"Small-screen message fonts","text":"<p>Small-screen Companion builds automatically select a compact font for received message text and the channel/sender line, including <code>Ch 0 Public</code>. SSD1306 and SH1106 OLEDs and the U8g2 T-Echo Card display use this on panels smaller than 160 pixels on both axes. ST7735 TFTs now use their native 160x80 dimensions and normal font. The shared renderer selects by panel dimensions, including rotation:</p> Panel size Font Capital height Line spacing At least 128 x 64, or 64 x 128 rotated; both axes below 160 Squeezed Regular 6 6 pixels 8 pixels Smaller panels, including 72 x 40, 128 x 32 and 64 x 48 Picopixel 5 pixels 7 pixels Either axis at least 160 Normal display font Depends on panel Depends on panel <p>Both fonts allow one pixel for descenders and one blank pixel row between lines. Character widths vary: most letters advance by 4 pixels, with narrow letters taking less space and <code>M</code> and <code>W</code> taking 6 pixels. Squeezed Regular 6 is a public-domain font by Oliver Kraus. Its bitmap data is stored as constants without heap allocation.</p> <p>On a 128 x 64 OLED with the single-button message reader, the compact channel/sender line starts at y=8 and message text at y=16. The header uses the same small font. Five complete 6px-font rows fit above the navigation hint at y=56. The software comparison fits three representative 160-character messages in those five rows. Capacity depends on the characters; messages with many wide letters can still overflow. Text wraps at character boundaries, with <code>...</code> on the last line if necessary. Unsupported characters appear as <code>?</code>. Long channel/sender names are ellipsized to stay on their own line. An enabled channel footer reserves its own space. Readers without the button hint retain the y=14 origin and y=22 message text.</p> <p>On V4 and other single-button builds using this reader, the home screen says <code>hold button: inbox</code>. Hold the user button for about 1.2 seconds to open it. The bottom continuously shows <code>4 &lt;&lt;-  2 &lt;- tap -&gt; 1  -&gt;&gt; 3  hold: Exit</code> without alternating or blinking. Double tap goes to the previous message, one tap advances, three taps select the next channel, and four taps select the previous channel. Channel selection cycles through All, configured channels, and direct messages, starting at the newest message in each filter. The header shows <code>All</code>, <code>Ch N</code>, or <code>DM</code>, including when a channel is empty. Hold to return home; advancing past the last message also returns home. The complete hint fits in the V4's existing 8-pixel footer at y=56, leaving five message rows. The footer keeps the same 6px font, using 108 pixels with 10-pixel margins on the V4. Narrower screens first use the compact <code>hold:X</code> hint without the extra spaces or arrow dashes, then split the same controls across fixed lines. The hint appears even when the inbox is empty. These are button taps. Touchscreen and joystick builds retain instructions appropriate to their controls. During the first eight seconds after startup, holding the button on an ordinary home page enters CLI rescue instead; wait for that startup window to finish before opening the inbox. Exiting a message preview and the WiFi setup page's hold action remain available immediately.</p> <p>The hidden Reader, opened by a long press on the radio page, uses the same button hints. Three taps jump to the first verse of the next chapter; four taps jump to the first verse of the previous chapter. Chapter navigation stops at the beginning and end of the book. It reserves the hint before pagination and resumes saved bookmarks at the page containing the same text, even after the available page size changes.</p> <p>Larger display classes keep their existing font. Menus, Bluetooth PINs and WiFi setup QR codes keep their normal layout. TFT drivers use native panel coordinates; the SenseCAP Indicator retains its existing scaling. The normal OLED font uses 7-pixel letters, 8-pixel line spacing and 6-pixel character advances.</p> <p>The preview buffer holds a complete 160-byte MeshCore message plus its terminator. Previously the main message UI allocated 78 bytes, leaving room for only 77 bytes of text. It still retains 32 previews; larger records add about 2.8 KB of RAM. The firmware RAM guard includes that increase. This history is separate from the offline queue and its mOTA policy.</p> <p>The tiny 72 x 40 T-Echo Card interface now previews the latest received message below its status bar, with three small-font message rows. A button press dismisses it. It stores one full message, and shows <code>...</code> when the screen fills. Incoming text does not replace an active Bluetooth pairing PIN.</p>"},{"location":"v4_pixel5_font_trial/#v4-hardware-trial","title":"V4 hardware trial","text":"<p>Enable <code>platformio.nimble.ini</code> in the ignored <code>platformio.local.ini</code> as shown in the NimBLE trial guide, then run:</p> <pre><code>OUTPUT_DIR=.releases/v4-smallfont bash build.sh build-firmware \\\n  heltec_v4_2_v4_3_companion_radio_full_femon_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-squeezed6-trial \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n</code></pre> <p>This build keeps NimBLE, 350 contacts, 40 channels, the V4's 512-frame PSRAM queue, USB mOTA sending and WiFi OTA support. The smaller font is also the default in ordinary small-screen Companion builds from this source. The older <code>_nimble_pixel5</code> environment name remains available, but also uses the automatic 5px/6px selection.</p> <p>Use the application <code>.bin</code> for WiFi OTA. A clean USB install uses the merged image at address 0. When manually writing the application at <code>0x10000</code>, an existing OTA selector may still boot app1. Check the running <code>ver</code> afterward. On the matching V4 16 MB layout only, clearing the 8 KB <code>otadata</code> partition at <code>0xe000</code> selects the newly written app0 without clearing NVS/settings. Confirm the partition table and verify the app write before changing that selector.</p> <p>A custom build can set <code>-D UI_SMALL_MESSAGE_FONT=0</code> to restore the old font and spacing. Remove any explicit <code>UI_MSG_PREVIEW_SIZE</code> flag too if the old preview capacity is desired. These are compile-time options, not CLI commands. No settings erase is necessary when changing between matching V4 layouts.</p>"},{"location":"v4_pixel5_font_trial/#verification","title":"Verification","text":"<pre><code>python3 -B test/test_ssd1306_picopixel.py\npython3 -B test/test_firmware_ram.py\npio test -e native -f test_display_driver -f test_companion_message_history\n</code></pre> <p>The native tests exercise both capital heights, automatic font selection, 160-character messages, complete rows at display edges, long sender lines, navigation hints, reserved footers, overflow markers and tiny/rotated screen geometry. The additional rendering comparison checks all 95 printable ASCII glyphs in each font, under address/undefined-behavior sanitizers. Picopixel is compared pixel for pixel with Adafruit GFX; Squeezed Regular 6 is compared with the upstream BDF fixture independently of the converted C++ tables. This needs a cached PlatformIO Adafruit GFX library; set <code>MESHCORE_GFX_LIBRARY</code> to its directory if needed. It reports a skip when the library is absent. The native tests do not require that dependency. Run only one PlatformIO command at a time.</p>"},{"location":"v4_pixel5_font_trial/#automatic-5px6px-results-2026-09-08","title":"Automatic 5px/6px results, 2026-09-08","text":"<p>Source revision <code>469b47d1</code> passed five representative firmware builds. All five retained the same static RAM usage and startup heap margin as their earlier 5px builds. The four Full profiles also passed required OTA packaging.</p> Hardware/profile Display Selected capital height RAM beyond the required startup budget, bytes V4.2/V4.3 Full NimBLE SSD1306 6 pixels 88,072 T096 Full, FEM on ST7735 6 pixels 24,778 Station G3 ESP32 Full SH1106 6 pixels 82,080 RAK3401 Full SSD1306 6 pixels 46,108 T-Echo Card BLE Companion U8g2, 72 x 40 5 pixels 30,992 <p>The native display/history suites passed 36 tests. The Python font, RAM, pairing, display-profile, queue and QR checks passed 38 tests, including pixel comparisons for all 95 ASCII glyphs in each font. The actual SSD1306 software rendering matches the approved 6px comparison image pixel for pixel.</p> <p>Both <code>NimBLE-V4-VM</code> and <code>NimBLE-V4-Trial</code> were flashed with <code>v1.17.1.5-halo-keymind-cascade-squeezed6-trial-469b47d1</code>. Their partition tables and application hashes were verified, their settings retained, and running versions confirmed. Each passed 201 USB protocol requests without error flags. The Mercerwood V4 reconnected over bonded Bluetooth at MTU 179 and retained the factory-address policy.</p> <p>The XIAO sent a private 160-byte LoRa message to the Mercerwood V4. All bytes arrived, and the V4 stayed responsive through 20 seconds of display refreshes with no uptime reset or error flags. Both temporary channel settings were restored. After that interval the V4 had 147,196 bytes of free internal heap, a minimum of 146,328 bytes, and a largest free block of 139,252 bytes.</p> <p>These are short functional checks. Physical readability remains a user judgment. A message with many wide characters can still need truncation.</p> <p>V4 application size: 1,778,936 bytes (1,152 bytes larger than the earlier 5px trial). SHA-256: <code>8e6797b90741bf013b3757668e5a23378ac8c0b0ed9c75830939f13305c56a68</code>.</p>"},{"location":"v4_pixel5_font_trial/#earlier-5px-hardware-and-build-results-2026-09-08","title":"Earlier 5px hardware and build results, 2026-09-08","text":"<p>Source revision <code>eeea15ef</code> passed seven representative firmware builds:</p> Hardware/profile Display RAM beyond the required startup budget, bytes V4.2/V4.3 Full NimBLE Picopixel SSD1306 88,072 T096 Full, FEM on ST7735 24,778 Station G3 ESP32 Full SH1106 82,080 RAK3401 Full SSD1306 46,108 Wireless Tracker Full NimBLE capacity trial ST7735 28,022 Wio Tracker L1 Full SH1106 45,744 T-Echo Card BLE Companion U8g2 30,992 <p>These are linked-capacity checks before runtime allocation, not live free heap measurements. The six Full profiles also passed their required OTA packaging checks. The T-Echo Card row is a BLE Companion build.</p> <p>Both physical V4.3 nodes, <code>NimBLE-V4-VM</code> and <code>NimBLE-V4-Trial</code>, were flashed, their image hashes verified, and their running versions confirmed. Each passed 201 USB protocol requests with zero reported error flags. The Mercerwood V4 also reconnected over authenticated, bonded Bluetooth with MTU 179 and the existing factory-address policy.</p> <p>A private XIAO-to-V4 LoRa test delivered all 160 message bytes. The V4 continued responding during 20 seconds of message redraws, with zero error flags. Both temporary channel configurations were restored. Free internal heap after that interval was 147,200 bytes, minimum 146,340 bytes, and the largest free block was 139,252 bytes. These are short functional checks; physical readability remains a user judgment.</p> <p>A matching pre/post-boot Mercerwood measurement showed the longer preview using 2,816 additional PSRAM bytes, with unchanged internal free heap. Boards without PSRAM use their ordinary RAM for the larger preview records.</p> <p>The native display/history suites passed 31 tests. The Python font, RAM, pairing, display-profile, queue and QR checks passed 38 tests. The Adafruit comparison covers all 95 printable ASCII glyphs.</p> <p>V4 application SHA-256: <code>d914d80124b499d7b719f8427f3794ab1b6d15fd0112e3ef89ba2fac26b5a974</code>.</p>"},{"location":"releases/1.17.1.5-doc-audit/","title":"Markdown audit \u2014 1.17.1.5 USA Cascade","text":"<p>Audited on 2026-09-05 against firmware source <code>26303793</code>, the resolved build configuration, and the qualified 1.17.1.5 staging manifests. The scope was all 71 tracked Markdown files present at the start, including root documents, docs, examples, tools, tests, variants, and vendored library documentation. Generated/ignored build directories and external repositories were outside that scope.</p>"},{"location":"releases/1.17.1.5-doc-audit/#corrections","title":"Corrections","text":"<ul> <li>Added role-specific feature switches, exact   Companion/infrastructure MQTT and logging controls, board exceptions, SNMP,   and the USB web console.</li> <li>Added an exact-name variant map; every one of its   1,325 covered entries resolves to a staged firmware file. The 36 excluded   entries are identified rather than linked to substitute hardware.</li> <li>Corrected universal 254-neighbor claims, Full Companion MQTT filename/CLI   assumptions, TLora Full WebConfig availability, and partition/NVS guidance.</li> <li>Documented the power-saving guards present at audit time; current instructions   now use the shared <code>get powersaving</code> / <code>set powersaving on|off</code> command set.   Corrected the RS232 baud range and SNMP environment list.</li> <li>Linked OTAFIX 2.4.6 and its board/storage requirements from operator guides;   aligned the two manual USA OTA quickstarts with 910.525 MHz.</li> <li>Marked old provider catalogs and dated hardware results as historical;   documented the legacy tag workflow that also matches <code>repeater-room-*</code>.</li> <li>Fixed the vendored MQTT documentation link and documentation-site links   that incorrectly treated repository source files as generated site pages.</li> </ul>"},{"location":"releases/1.17.1.5-doc-audit/#verification-and-limits","title":"Verification and limits","text":"<p>All original Markdown files were scanned for relative links, section anchors, source-path references, version/default claims, and role/OTA terminology. Flagged operator instructions were checked against CommonCLI, its observer extension, Companion command handlers, board configuration, and release manifests. Brace-expanded source references and SDK-relative paths were retained as such. Historical measurements, changelogs, upstream findings, contribution/security policies, and licenses were not rewritten as new validation results.</p> <p>The documentation site passed a strict MkDocs Material build. Relative repository links and section anchors were checked separately, including documents outside the MkDocs source directory. Console and current bootloader links were checked on their primary sites. This was not a crawl of every third-party URL or a new hardware/firmware qualification; no claim is made that every board was physically tested or every protocol statement independently re-proved.</p>"},{"location":"releases/1.17.1.5-doc-audit/#original-file-coverage","title":"Original file coverage","text":"<p>\u201cRetained\u201d means no correction was identified by this documentation audit; it does not certify all historical statements as current hardware behavior.</p> File Disposition AGENTS.md Scanned; retained ALERTS.md Scanned; retained CHANGELOG.md Historical record retained CONTRIBUTING.md Scanned; retained MEMORY_MONITORING.md Scanned; retained MQTT_IMPLEMENTATION.md Corrected or clarified MQTT_INTERNALS.md Corrected or clarified MQTT_OWNERSHIP.md Historical record retained MQTT_SNMP.md Corrected or clarified README.md Corrected or clarified RELEASE.md Corrected or clarified RESTORE_UPSTREAM_NOTES.md Historical record retained SECURITY.md Scanned; retained STABILITY_TESTABILITY_HANDOFF.md Historical record retained UPSTREAM_BUGS.md Scanned; retained WEB_CONFIG_REVIEW.md Corrected or clarified arch/stm32/Adafruit_LittleFS_stm32/README.md Vendored documentation/license retained arch/stm32/Adafruit_LittleFS_stm32/src/littlefs/LICENSE.md Vendored documentation/license retained arch/stm32/Adafruit_LittleFS_stm32/src/littlefs/README.md Vendored documentation/license retained docs/WiFi.md Corrected or clarified docs/cli_build_matrix.md Corrected or clarified docs/cli_command_availability.md Corrected or clarified docs/cli_commands.md Corrected or clarified docs/companion_offline_queue.md Scanned; retained docs/companion_protocol.md Scanned; retained docs/companion_radio_full.md Corrected or clarified docs/docs.md Scanned; retained docs/esp32_memory_budget.md Scanned; retained docs/faq.md Corrected or clarified docs/filter_tool.md Scanned; retained docs/firmware_picker.md Corrected or clarified docs/flood_filtering.md Scanned; retained docs/full_companion_features.md Corrected or clarified docs/full_companion_usb_switcher.md Corrected or clarified docs/gps_tracking.md Scanned; retained docs/halo_keymind_settings.md Corrected or clarified docs/hardware_validation_checklist.md Corrected or clarified docs/host_cli_service.md Scanned; retained docs/index.md Corrected or clarified docs/kiss_modem_protocol.md Scanned; retained docs/lora_ota_automation.md Corrected or clarified docs/mbedtls-tls-footprint.md Scanned; retained docs/nrf52_companion_storage_recovery.md Scanned; retained docs/nrf52_power_management.md Scanned; retained docs/number_allocations.md Scanned; retained docs/ota_easy.md Corrected or clarified docs/ota_meshtower_v2_sdcard.md Corrected or clarified docs/ota_nrf52_bootloader_update.md Corrected or clarified docs/ota_nrf52_qspi.md Corrected or clarified docs/ota_protocol.md Corrected or clarified docs/ota_user_guide.md Corrected or clarified docs/packet_format.md Scanned; retained docs/payloads.md Scanned; retained docs/qr_codes.md Scanned; retained docs/rak3401_mota_chain.md Historical record retained docs/releases/1.17.1.5.md Corrected or clarified docs/spiffs_regular_file_reads.md Scanned; retained docs/stats_binary_frames.md Scanned; retained docs/telemetry_decoder.md Scanned; retained docs/terminal_chat_cli.md Scanned; retained docs/usb_serial_backpressure.md Scanned; retained examples/host_cli_service/README.md Scanned; retained lib/PsychicMqttClient/CHANGELOG.md Vendored documentation/license retained lib/PsychicMqttClient/README.md Corrected or clarified mesh-america/README.md Corrected or clarified test/README.md Scanned; retained test/test_mqtt_prefs_codec/FIXTURES.md Historical record retained tools/mota/README.md Scanned; retained tools/sensecap_indicator_font/README.md Scanned; retained tools/sensecap_indicator_rp2040/README.md Scanned; retained variants/sensecap_indicator-espnow/README.md Scanned; retained"},{"location":"releases/1.17.1.5/","title":"MeshCore 1.17.1.5 Dev - USA Cascade","text":"<p>Use feature switches by role for exact on/off commands for Companion, Repeater, Room Server, and Sensor, including MQTT, logging, power saving, GPS, and board exceptions. Open the USB web console for the default ASCII terminal on Full Companion and infrastructure images.</p> <p>The firmware identifier and main release tag follow <code>v1.17.1.5-halo-keymind-cascade-dev-&lt;commit&gt;</code>, matching the 1.17.1.4 naming convention. Supplemental pages retain the <code>repeater-room-</code>, <code>utility-</code>, <code>logging-</code>, <code>lora-ota-</code>, and <code>full-profiles-</code> prefixes where those outputs exist. The Companion page is marked Latest; the supplemental pages remain development prereleases.</p> <p>This release uses the USA/Canada radio preset and Cascade runtime defaults. The release build records the resolved frequency, bandwidth, spreading factor, and coding rate. The offline USA Cascadia fallback is 910.525 MHz, BW62.5, SF7, CR5. Saved node settings survive ordinary firmware updates.</p>"},{"location":"releases/1.17.1.5/#memory-corrections-in-aa20e927","title":"Memory corrections in <code>aa20e927</code>","text":"<p>All 583 published profiles (the 540-profile matrix plus 43 supplemental Full repeaters) were checked against the new runtime RAM policy. All 11 failing profiles have replacements, and the same queue sharing has been applied to the other 41 nRF52 Full profiles: 52 corrected profiles in total, initially built from <code>aa20e927</code>. The existing release tags stay in place; corrected filenames end in <code>aa20e927</code>, except Wireless Paper Full's capacity-restoring follow-up, <code>1e4d1e16</code>. Companion remains Latest. Both Mesh America catalogs and the firmware picker point to the replacement files.</p> <p>All 43 nRF52 Full Companions keep 256 offline frames normally and lend 128 slots to mOTA while needed. Wireless Paper Full now also shares its queue and keeps 350 contacts and 40 channels. The other six corrected ESP32 Full profiles below use 150 contacts, preserving their 256-frame queue and Full transports. Export contacts before upgrading if you have more than 150; entries beyond that limit may be unavailable and a later save may omit them. This warning applies to those six profiles and the superseded <code>aa20e927</code> Wireless Paper image.</p> <p>Wireless Paper Full's <code>1e4d1e16</code> update has 256 message slots normally and 128 while an mOTA session borrows its workspace. Idle WiFi listening leaves all 256 slots available. If more than 128 unread messages are queued, sync them with an app before starting mOTA. Source stop/disconnect restores all 256 slots and frees ESP32 scratch buffers. USB, Bluetooth, WiFi, the display and the partition layout are retained. The application is 1,869,976 bytes; use its app-only <code>.bin</code> for a compatible WiFi update, or its merged image for USB installation.</p> <p>The T096 and T1 LoRa OTA repeater corrections allocate the diagnostic manual staging buffer only when requested, recovering about 4 KiB at startup. Ordinary mOTA uses its existing staging store. <code>ota dev clear</code> releases a manual stage; allocation failure reports an error before writing. These same-version repairs require an explicit exact-target manual LoRa installation or USB; forward-only trusted autoinstall does not select an equal-version repair.</p> <p>Available RAM below means capacity before startup allocations, not free heap after boot. The Wireless Paper row includes its latest <code>1e4d1e16</code> update:</p> Failing original profile Original bytes Replacement bytes Required bytes <code>Generic_ESPNOW_companion_radio_full</code> 101,920 139,456 136,192 <code>Heltec_Wireless_Paper_companion_radio_full</code> 150,144 161,336 152,576 <code>Heltec_Wireless_Tracker_companion_radio_full</code> 148,496 186,032 169,986 <code>Heltec_ct62_companion_radio_full</code> 99,104 136,640 136,192 <code>Heltec_t096_companion_radio_full_femon</code> 54,724 74,060 73,728 <code>Heltec_t1_companion_radio_full</code> 55,044 74,380 73,728 <code>Heltec_v3_companion_radio_full</code> 143,840 181,376 173,056 <code>Xiao_C3_companion_radio_full</code> 98,880 136,416 136,192 <code>heltec_tracker_v2_companion_radio_full_femon</code> 133,136 170,672 169,986 <code>Heltec_t096_repeater_lora_ota_no_external_sensors</code> 61,588 65,676 65,538 <code>Heltec_t1_repeater_lora_ota_no_external_sensors</code> 61,964 66,052 65,538 <p>Each replacement has a matching <code>.memory.json</code> with its ELF hash, RAM budget and firmware-file hashes. The complete audit distinguishes original binary/log calculations from new ELF checks. All 52 exact firmware builds, their native file pairs, and 150 native mOTA tests passed, alongside memory, allocation-failure, shared-queue and picker regressions. Wireless Paper's follow-up also passed complete TCP mOTA transfers with address/leak sanitizers, repeated disconnects, queue-full refusal, idle listening and USB/TCP ownership changes. Physical boot/load/soak validation remains pending.</p>"},{"location":"releases/1.17.1.5/#g3-usb-disappearance-with-power-saving-enabled","title":"G3 USB disappearance with power saving enabled","text":"<p>The published <code>26303793</code> firmware has an ESP32 native-USB sleep bug that matches a Station G3 report: USB disappears from the connected Pi after a few minutes, the display button stops responding, but the repeater still answers over LoRa. Hardware confirmation of this report is pending.</p> <p>Cascade enables device power saving by default on fresh settings. After two minutes, the repeater can enter light sleep when no serial terminal is open, even though the Pi has enumerated the USB device. Light sleep stops USB service; the radio GPIO can still wake the CPU, while the G3 display button is only polled. Closing a terminal must not be treated as unplugging the USB host. Espressif documents the underlying native USB sleep limitation.</p> <p>To enable USB logging on an ESP32 1.17.1.5 image with logging support, disable power saving first. Use the role's text terminal, or the repeater's remote admin CLI if USB has already disappeared:</p> <pre><code>set powersaving off\nset usb.logging on\nget powersaving\nget usb.logging\n</code></pre> <p>The read-back commands should report power saving <code>off</code> and USB logging <code>on</code>. For an image without USB logging, use just <code>set powersaving off</code> and <code>get powersaving</code> to apply/check the sleep workaround. Disabling power saving saves the setting and takes effect immediately; it does not erase the node or change LoRa RX power saving (<code>radio.rxps</code>). If USB does not reappear after disabling sleep remotely, power-cycle once and check that the port and display button remain usable beyond the two-minute mark. Ordinary reflashing can retain the saved power-saving setting, so check it during comparisons with another firmware build too.</p> <p>On unified Full infrastructure, also run <code>set powersaving off</code> before enabling USB through <code>set logging.output usb</code> or <code>set logging.output both</code>. These are separate commands. Turning logging off does not automatically restore the saved power-saving setting. nRF52 logging does not need this ESP32 workaround.</p> <p>WiFi/MQTT-only logging does not need <code>set powersaving off</code> while the Repeater/Room Server MQTT bridge is running. The original <code>26303793</code> code already prevents device sleep in that state. Select <code>set logging.output wifi</code> where supported and check <code>get mqtt.running</code>; <code>get mqtt.enabled</code> alone only checks the saved preference. MQTT-capable Full Companion now uses the same <code>mqtt.enabled</code> and <code>logging.output</code> commands as infrastructure. Disabling MQTT preserves broker settings; the MQTT tab exposes the same master switch.</p> <p>The source correction keeps native USB serviced while a host is enumerated, including when its terminal is closed. Enabled live USB logging also blocks ESP32 light sleep, even without a host. FreeRTOS can still idle/yield; this does not disable the saved power-saving setting or Companion CPU scaling. With logging off, USB power from a charger still permits sleep.</p> <p>The corrected G3 uses its user button as a light-sleep wake source alongside LoRa. Button activity keeps the CPU and display awake for at least two minutes; holding or pressing the button again extends the interval. The usual display timeout can keep the screen on longer. An intentional long-press power-off retains its existing action. After the wake interval, sleep is allowed when power saving is enabled, logging is off, no native USB host is attached, and no running bridge or pending work needs service.</p> <p>Host simulations cover both native USB modes, terminal close/reconnect, logging toggles, OTA inhibition, simultaneous button/LoRa wake configuration, and the two-minute interval across timer rollover. The Station G3 repeater download remains the original <code>26303793</code> build; continue to use the logging workaround above on that image.</p>"},{"location":"releases/1.17.1.5/#t096-full-companion-bluetooth-and-menu-freeze-report","title":"T096 Full Companion Bluetooth and menu freeze report","text":"<p>A report against <code>Heltec_t096_companion_radio_full_femon</code> describes no usable Bluetooth despite a displayed PIN, followed by a freeze while stepping through the device menu. Reflashing both with and without a full wipe gave the same result. The exact freeze and Bluetooth behavior still need confirmation on a physical T096 with the source correction below.</p> <p>The published <code>26303793</code> Full image leaves only 54,724 bytes (53.4 KiB) between the linked heap boundaries. Its static RAM check did not account for the allocations made at startup: the 160x80 color framebuffer alone needs 25,602 bytes, followed by task stacks, the packet pool, filesystem buffers, and message previews. This leaves inadequate runtime headroom. The pinned Bluefruit library also ignores failure to create its BLE/SOC worker tasks, and the sensor menu could write through a failed CayenneLPP allocation. Those are code paths consistent with this report; a PIN is not proof of a working Bluetooth radio.</p> <p>The correction applies to every nRF52 Full Companion, keeping its offline queue at 256 frames during normal use. mOTA borrows the upper 128 slots for its roughly 19 KiB session state only when needed, leaving 128 message slots during mOTA use. Starting a source or a TempRadio discovery session acquires this workspace. Stopping or disconnecting the USB/Bluetooth source restores all 256 slots, even if the temporary radio window is still open. A discovery-only session returns the slots when its TempRadio window ends. No heap resizing is involved.</p> <p>Unread messages keep their order across both transitions. If more than 128 frames are pending, mOTA refuses to start and asks you to sync unread messages with a Companion app first; it does not discard them to make room. OTA configuration and signer keys survive reuse of the workspace. While mOTA owns it, the normal queue overflow policy applies to the remaining 128 slots.</p> <p>The T096 profile requires at least 72 KiB of heap space at link time. It retains 350 contacts, 40 channels, the color display, sensors, USB, Bluetooth, Bluetooth DFU, and USB/Bluetooth mOTA sending. This reserve is space for runtime allocations, not a measurement of free heap after boot. Bluetooth startup now checks both worker tasks and all registered services; a failed partial initialization does not repeat every five seconds. The sensor page reports low memory if its buffer could not be allocated.</p> <p>Regression tests transfer complete mOTA containers through the actual shared context, check queue wraparound and message order, and cover source stop, disconnect, conflicting USB/Bluetooth ownership and repeated sessions. They also inject worker-task and GATT-service failures, verify that retries do not initialize the stack again, open the sensor path with a failed allocation, and use the real linker assertion to reject the old heap budget. The original T096 Full download has been replaced by the corrected <code>aa20e927</code> image on the same release page. Another wipe is not a fix for the old compiled memory budget.</p> <p>For the corrected T096 build, use its matching application UF2 through the existing USB bootloader. Preserve the bootloader and node data. Check Bluetooth discovery, pairing and message exchange on battery power and with USB attached; then step through every menu page, return from screen-off, and check USB and Bluetooth mOTA sending. Hardware validation is pending.</p>"},{"location":"releases/1.17.1.5/#firmware-roles-and-update-support","title":"Firmware roles and update support","text":"<p>Use the exact board's Full Companion image when available. Every Full Companion must pass linked-firmware checks for MOTA sending, its text terminal, and the platform's source transports. ESP32 supplies USB and WiFi sources; nRF52 supplies USB and encrypted Bluetooth sources. Full Companions remain USB-updateable and do not require LoRa self-installation. Optional ESP32 WiFi self-update uses port 8080 where the existing partition layout has two application slots; nRF52 retains Bluetooth DFU with a compatible bootloader.</p> <p>Read Full Companion feature switches for on/off commands, USB logging, power saving, WiFi/Bluetooth selection, GPS, MQTT, MOTA sending, and update directions.</p> <p>Infrastructure artifacts must have a verified wireless self-update path. Option 3 reports and omits infrastructure on platforms without a wireless updater. The report is <code>ota-excluded-targets.txt</code>. Source/seeder capability alone does not count as self-update support. ESP32 qualification checks both application slots and OTA metadata; nRF52 Bluetooth qualification checks the linked DFU service and its application ZIP. LoRa installation on nRF52 still requires the exact matching OTAFIX bootloader and storage arrangement.</p> <p>Classic ESP32 capacity limits are recorded in each artifact's capability manifest. Generic E22, Heltec V2, Meshadventurer, and T-Beam OTA repeaters, plus the TLora MQTT repeater, use 50 neighbors where needed to preserve the required internal RAM reserve. T-Beam MQTT repeater profiles retain the full rule engine with 31 flood rules; constrained classic ESP32 ESP-NOW bridges with logging use 47. Meshadventurer Full uses 100 contacts, 30 group channels, and a 16-frame offline queue while retaining its MOTA and transport features.</p> <p>Since 1.17.1.4, this branch also includes USB session and contact-persistence fixes, automatic nRF52 ExtraFS recovery, improved Indicator setup/display handling, compressed MOTA transport, and measured ESP32 memory limits. Qualified internal-flash nRF52840 receivers now reserve 64 KiB of retained RAM to extend application MOTA staging beyond the available flash prefix. This handoff requires the exact board's OTAFIX 2.4.6 bootloader. Install that bootloader before relying on LoRa updates from these new hybrid receiver images: they reject application containers larger than one flash page when the installed bootloader lacks the retained-RAM capability. QSPI/microSD roles and Full Companions retain their existing storage layouts. An interrupted hybrid download must be fetched again after an application restart or power cycle. See the protocol for the exact admission and reset checks.</p>"},{"location":"releases/1.17.1.5/#build-using-option-3","title":"Build using option 3","text":"<p>The equivalent reproducible command is:</p> <pre><code>OUTPUT_DIR=.releases/1.17.1.5-halo-keymind-cascade-dev \\\nbash build.sh build-firmwares-logging-matrix \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-dev \\\n  --radio-preset usa-cascadia --profile cascade \\\n  --require-ota --skip-kiss --resume --background\n</code></pre> <p>Or run <code>bash build.sh</code>, select option 3, set version <code>v1.17.1.5-halo-keymind-cascade-dev</code>, and retain USA Cascadia/Cascade. Option 3 enables the infrastructure OTA requirement by default. It merges supported runtime USB logging into canonical artifacts and builds the expanded ESP32 profiles. It runs one PlatformIO process at a time.</p> <p>The background launcher prints its persistent log and status paths. Each target also gets a log in <code>OUTPUT_DIR/build-logs/</code>. Resume accepts only artifacts with the current capability schema and a successful qualification; infrastructure also needs a verified update method. Any failed target leaves the matrix unsuccessful and must be resolved before publication.</p> <p><code>--allow-no-ota</code> is an explicit development override for cable-only infrastructure. Those outputs do not belong in this OTA-required release. Use a separate output directory when changing the radio or settings profile. Use a fresh release output directory after changing the source revision or firmware version so packaging cannot mix old and new binaries.</p>"},{"location":"releases/1.17.1.5/#local-release-staging","title":"Local release staging","text":"<p>After the matrix completes successfully, <code>scripts/package_cascade_release.py</code> groups the qualified images using the previous GitHub release naming. Each group includes the firmware files, capability manifests, TSV/JSON inventory, checksums, build notes, and Full Companion directions. The staging directory's root <code>FIRMWARE-PICKER-1.17.1.5.html</code> opens the local downloads; the copies inside each release group use the planned GitHub download URLs. Staging does not push commits, create remote tags, or publish a GitHub release.</p>"},{"location":"releases/1.17.1.5/#published-release-set-and-small-slot-heltec-v4-updates","title":"Published release set and small-slot Heltec V4 updates","text":"<p>The capability JSON and target inventories now report both Bluetooth DFU and LoRa mOTA for all 60 nRF52 receiver profiles. The original report omitted the nRF52 LoRa method. Each affected manifest includes <code>ota_update_requirements.lora</code> with its storage type, accepted package types, exact-base requirement for deltas, and the matching OTAFIX bootloader link. Internal-flash receivers accept in-place deltas; supported QSPI/SD receivers also accept full application packages. The 20 retained-RAM receivers require OTAFIX 2.4.6's matching handoff support. These reports verify the released application bytes and storage layout; they do not certify the bootloader installed on a physical device. Firmware binaries and tags are unchanged. Full Companion mOTA sending remains separate from self-update capability.</p> <p>Published firmware tags remain at source commit <code>26303793</code>. Documentation can advance independently. The original matrix qualified 540 profiles (1,080 firmware files) from 551 attempts; 11 oversized portable attempts have expanded Full replacements. The variant map maps all 1,361 previous-release choices to 1,325 covered choices and 36 excluded entries. Multiple old choices map to the same current artifact.</p> <p>For Heltec V4 with an existing compatible 1.25 MiB OTA application slot, the standard <code>heltec_v4_repeater</code> application is 1,179,200 bytes and the lean <code>heltec_v4_repeater_lora_ota_no_external_sensors</code> application is 1,232,024 bytes. Both fit that slot. Start the WiFi uploader with <code>start ota ap</code>, join <code>MeshCore-OTA</code>, and open <code>http://192.168.4.1/update</code>. Upload the application <code>.bin</code>; use <code>stop ota</code> to close an unused uploader. Their merged USB installers write two 6.25 MiB application slots. Expanded Full V4 applications require the larger layout and do not fit a 1.25 MiB slot.</p> <ul> <li>Companion firmware</li> <li>Repeater and Room Server firmware</li> <li>Sensor firmware</li> <li>LoRa OTA repeater firmware</li> <li>Expanded Full infrastructure</li> </ul>"},{"location":"releases/1.17.1.6/","title":"MeshCore 1.17.1.6 Dev - USA Cascade","text":"<p>This release builds the current <code>keymindCascade</code> source after repairing the unit-test regressions. Its firmware identifier is <code>v1.17.1.6-halo-keymind-cascade-dev-&lt;commit&gt;</code>. The recorded commit identifies the source for every firmware file; binaries from earlier releases are not reused.</p> <p>Use the firmware picker to match the exact board, radio, display and flash variant. The Companion release is marked Latest. Supporting release pages retain the <code>repeater-room-</code>, <code>utility-</code>, <code>logging-</code>, <code>lora-ota-</code> and <code>full-profiles-</code> prefixes where those outputs exist, and remain development prereleases.</p> <p>The build uses the USA/Canada radio preset and Cascade runtime defaults. Build records include the resolved radio settings; the offline USA Cascadia fallback is 910.525 MHz, BW62.5, SF7, CR5. Ordinary updates retain saved node settings.</p>"},{"location":"releases/1.17.1.6/#published-matrix","title":"Published matrix","text":"<p>The GitHub release contains 553 qualified firmware profiles across five release pages. The initial matrix completed all 565 attempts: 537 passed, 16 failed, and 12 standard ESP32 profiles exceeded the 1.25 MiB portable slot. All 16 failures have passing repair builds; all 12 portable exclusions have qualified expanded Full alternatives. Smaller profiles that fit remain available.</p> <p>The initial firmware uses <code>306feebe</code>, the 14 nRF52 repairs use <code>283acd27</code>, and the two Tracker MQTT repairs use <code>1274956f</code>. Each firmware filename and target manifest records its source. Existing firmware assets and release tags were preserved when the repairs were added.</p> <p>See the failure and repair report and portable-profile exclusions. Full alternatives require their matching expanded partition layout; they do not fit a deployed 1.25 MiB slot.</p>"},{"location":"releases/1.17.1.6/#two-lora-profiles","title":"Two LoRa profiles","text":"<p><code>radio2</code>, <code>tempradio2</code>, <code>radioat2</code> and <code>tempradioat2</code> add a second profile to LoRa-equipped Companion, Repeater, Room Server, Sensor and terminal firmware. The second profile starts disabled. It supports receive-only or receive/transmit operation, separate retry ownership and backoff, and explicit off commands.</p> <p>One transceiver alternates between at most two active profiles. Reception and transmission occupy that transceiver, so a packet on one profile interrupts listening on the other. This does not provide two simultaneous receivers.</p> <p>By default, traffic can cross between two permanent profiles or two temporary profiles. A permanent/temporary pair stays isolated. <code>radio2.cross auto|on|off</code> controls this policy; receive-only still forbids transmission on profile 2. <code>tempradio2</code> can carry LoRa OTA traffic while the primary profile remains available between packets. Use a firmware profile that supports the required OTA role.</p> <p>Radio commands accept an optional trailing preamble, and their getters include the effective preamble. Automatic preambles round up in steps of eight. Paired with SF7/BW62.5/preamble 32, the automatic BW500 values are 48 symbols at SF9, 88 at SF8 and 120 at SF7. Configure transmitters with matching preambles too.</p> <p>Dual-profile receive uses normal RX with the slower profile visited first. RX power saving and device sleep are suspended while scanning, then the saved settings apply again in single-profile mode. See the setup guide and command matrix and hardware measurements.</p>"},{"location":"releases/1.17.1.6/#other-changes-since-11715","title":"Other changes since 1.17.1.5","text":"<ul> <li>Restores <code>set path.hash.mode 0|1|2</code> on infrastructure firmware, with CLI   dispatch and get/set regression coverage. Unsupported <code>extra.sf</code> commands   report an explicit error on radios without that capability.</li> <li>Uses received MeshCore packets to feed the repeater RX watchdog. Fresh   settings default to 24 hours; temporary primary-radio sessions lasting at   least 12 hours use 12 hours, while shorter sessions disable that watchdog.   Temporary-session adverts and watchdog settings revert when the session ends   or the node reboots. See CLI commands.</li> <li>Adds separate battery and USB display modes, with timeouts in seconds.   Companion inbox settings distinguish retained history, pending delivery and   the local unread count. Read previews remain browseable in Unread mode.</li> <li>Includes native-USB sleep/wake corrections, nRF52 USB startup fixes,   receive recovery and noise-calibration improvements, and the reviewed   ExpressLRS board/power changes.</li> <li>Consolidates redundant Full infrastructure builds while retaining useful   smaller-slot variants. Full profiles and smaller portable images continue   to require their matching partition and update method.</li> </ul> <p>Feature switches and update commands are documented in feature switches by role, Full Companion features and the ESP-NOW bridge guide.</p>"},{"location":"releases/1.17.1.6/#validation-and-installation","title":"Validation and installation","text":"<p>The release is gated on the unit-test workflow for its source commit. CI repairs replace stale display assertions with compiled tests of bookmark saves across battery/USB transitions and message summaries in each inbox mode. The sleep harness checks both MQTT and dual-profile scanning.</p> <p>The release packager checks each published profile's capability manifest, firmware-file hashes, native file pairs and runtime RAM budget. Infrastructure must have a verified wireless update path. The target manifests and exclusion report describe the actual published matrix; a build check is not a physical-board test.</p> <p>Dual-profile timing was measured on a Heltec V4 with a XIAO ESP32-S3/Wio LoRa transmitter. Finite strong-signal tests and an OTA catalogue exchange passed; these tests do not establish weak-signal performance, simultaneous traffic reliability, a complete hardware OTA installation, or months of uptime.</p> <p>ESP32 WiFi updates use the application <code>.bin</code>. The <code>-merged.bin</code> image includes boot and partition data for USB installation. nRF52 uses the board's <code>.uf2</code> or native application DFU <code>.zip</code>; LoRa OTA also needs the exact destination package and a compatible OTAFIX bootloader. Check the per-profile capability manifest before choosing an update method.</p>"},{"location":"releases/1.17.1.6/#reproduce-the-release","title":"Reproduce the release","text":"<p>Follow-up builds repair the constrained profiles without relaxing qualification:</p> <ul> <li>nRF52 repeaters use <code>-Os</code> instead of <code>-Ofast</code>, retaining their sensor drivers   and protocol features while reducing flash use.</li> <li>T096 and T1 LoRa OTA repeaters retain their board-defined 50 neighbors and   use 16 flood-rule slots. The complete rule engine, color display, GPS and OTA   remain enabled. The T096's available startup heap rises from 72,492 to 81,468   bytes, and the T1's from 72,868 to 81,844 bytes. Required startup allocations   fall from 88,410 to 79,010 bytes. These are linked capacity checks, not soak   measurements. Full Companion capacities are unchanged.</li> <li>Tracker v1.1 and v2 Full MQTT repeaters retain their board-defined 50   neighbors so the color display, MQTT/TLS and OTA fit in internal RAM.   Their radio, display, sensor and update features remain enabled; ordinary   Tracker repeater and Companion capacities are unchanged. Tracker v2's   available startup heap rises from 184,640 to 222,992 bytes against the   unchanged 190,386-byte requirement. Both corrected Tracker profiles pass.</li> <li>Size-failure detection keeps its temporary output log outside PlatformIO's   build tree, so SCons cleanup cannot erase the evidence needed by the measured   size fallback. CI exercises cleanup, ordinary compiler failures and log errors.</li> </ul> <p>Use a clean checkout of the release commit and a fresh output directory:</p> <pre><code>OUTPUT_DIR=.releases/1.17.1.6-halo-keymind-cascade-dev \\\nbash build.sh build-firmwares-logging-matrix \\\n  --firmware-version v1.17.1.6-halo-keymind-cascade-dev \\\n  --radio-preset usa-cascadia --profile cascade \\\n  --require-ota --skip-kiss --resume --background\n</code></pre> <p>Run only one PlatformIO process in that checkout. Let the matrix finish even when individual targets fail. The packager normally requires a successful full matrix. For an initial release with gaps, <code>scripts/package_cascade_release.py</code> accepts <code>--allow-partial</code> with <code>--version 1.17.1.6</code>, the original completed build status and source commit. It lists every failed attempt in <code>BUILD-FAILURES.md</code> and <code>BUILD-FAILURES.json</code>; each published file must still pass all qualification and memory checks. Repair the failures and add the corrected profiles afterward. <code>PORTABLE-PROFILE-EXCLUSIONS.md</code> and <code>.json</code> separately list standard ESP32 profiles that exceed the 1.25 MiB slot and are redirected to the expanded Full pass. Those size deferrals are not compiler failures. Qualified smaller images remain available; Full alternatives require their matching partition layout.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Introduction","text":"<p>Welcome to the MeshCore documentation.</p> <p>Below are a few quick start guides.</p> <ul> <li>1.17.1.5 Markdown audit</li> <li>1.17.1.5 USA Cascade release</li> <li>Feature switches by role: Companion, Repeater, Room Server, Sensor</li> <li>USB web console</li> <li>Full Companion feature switches</li> <li>Frequently Asked Questions</li> <li>Firmware Picker</li> <li>Temporary Radio Test Command Generator</li> <li>CLI Commands</li> <li>LoRa CLI Host Service</li> <li>Filter Policy Playground</li> <li>Telemetry Decoder</li> <li>Management Report Decoder</li> <li>CLI Availability by Firmware Build</li> <li>Classic ESP32 image memory budget</li> <li>Full Companion contact caches and capacity trials</li> <li>Easy LoRa OTA: ESP32 and nRF52 firmware updates</li> <li>Scripted LoRa OTA: Bash and PowerShell</li> <li>nRF52 repeater OTA with external QSPI</li> <li>nRF52 bootloader updates over LoRa</li> <li>MeshTower V2 microSD self-updates</li> <li>GPS Tracking</li> <li>Companion Protocol</li> <li>Companion Offline Message Queue</li> <li>Full Companion: ESP32 and nRF52</li> <li>Full Companion USB CLI and binary switcher</li> <li>Packet Format</li> <li>QR Codes</li> </ul> <p>If you find a mistake in any of our documentation, or find something is missing, please feel free to open a pull request for us to review.</p> <ul> <li>Documentation Source</li> </ul>"},{"location":"WiFi/","title":"WiFi and MQTT by Firmware Type","text":"<p>MeshCore itself does not require WiFi or the internet. LoRa packet exchange, repeating, room servers, companions, and sensors can all operate without either. WiFi is added by particular ESP32 firmware targets for one or more of these purposes:</p> <ul> <li>a TCP connection between a WiFi companion and a phone or computer;</li> <li>the WebConfig browser interface;</li> <li>MQTT uplinking from the radio to internet or LAN brokers;</li> <li>WiFi-assisted OTA services on builds that include them;</li> <li>ESP-NOW bridging, which uses the ESP32's 2.4 GHz radio but is not a connection   to a WiFi access point.</li> </ul> <p>The firmware role and the build profile are separate choices. USB logging does not itself provide MQTT. MQTT-capable Full Companions include that feature without <code>mqtt</code> in their filename; check the artifact capability manifest. See feature switches by role for the different Companion and infrastructure controls and the USB web console.</p>"},{"location":"WiFi/#quick-reference","title":"Quick reference","text":"Firmware target or role Infrastructure WiFi MQTT What WiFi does <code>*_repeater</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_repeater_observer_mqtt</code> Yes Yes Uplinks heard and selected transmitted LoRa packets; repeating remains enabled by default <code>*_room_server</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_room_server_observer_mqtt</code> Yes Yes Runs the room server and uplinks radio traffic <code>*_companion_radio_wifi</code> Yes No Exposes the MeshCore companion protocol on TCP port 5000 <code>*_companion_radio_wifi_mqtt</code> Yes Yes Runs both the TCP companion interface and the MQTT uplink <code>*_companion_radio_full*</code> ESP32, subject to board/transport selection Where compiled on ESP32 Includes supported USB/wireless transports; configure MQTT through WebConfig Dedicated USB, BLE, or serial companion (not Full) No No Uses the transport named by the target instead <code>*_repeater_bridge_espnow</code> Build-dependent on ESP32 No Uses ESP-NOW for its bridge; <code>bridge.format wrapped|raw</code> selects legacy bridge framing or primary-ESP-NOW compatibility; a FULL build also exposes the TCP 5001 LoRa-OTA seeder whenever WiFi is usable RS232 bridge No No Bridges through a serial interface Ethernet repeater/room server No WiFi No Uses wired Ethernet for its role-specific network interface <code>*_sensor</code> Build-dependent on ESP32 No A FULL ESP32 sensor can expose the TCP 5001 LoRa-OTA seeder through its browser-OTA setup AP Terminal-chat or KISS modem No in current targets No Uses LoRa and its role-specific local interface <code>*_lora_ota_no_external_sensors</code> On demand on ESP32 No Lean LoRa-OTA repeater image; ESP32 builds retain the compact <code>start ota</code> browser uploader <p>Direct on-device WiFi and MQTT are currently ESP32 features. nRF52, STM32, and the currently enabled RP2040 targets do not run this MQTT bridge. An nRF52 connected to a Raspberry Pi can still be logged or uplinked by software on the Pi, but that is a separate host-side bridge rather than MQTT running in the radio firmware.</p>"},{"location":"WiFi/#how-the-mqtt-bridge-works","title":"How the MQTT bridge works","text":"<p>The MQTT bridge is an outbound observer. It does not subscribe to MQTT topics and does not inject broker messages into LoRa.</p> <p>For a received packet, the flow is:</p> <pre><code>LoRa radio -&gt; successful packet parse -&gt; MQTT capture queue -&gt; broker slots\n                                  \\----&gt; normal MeshCore filtering/handling\n</code></pre> <p>Packets transmitted by the node can also be queued according to <code>mqtt.tx</code>. Receive capture happens before the packet is passed to the normal MeshCore flood filters and forwarding decision. A packet may therefore be observed on MQTT even when a later scope, path, region, duplicate, or repeat rule prevents the node from forwarding it over LoRa.</p> <p>On infrastructure observer builds, MQTT publication and LoRa repetition are separate:</p> <ul> <li><code>set repeat on|off</code> controls whether an observer repeats eligible LoRa   packets;</li> <li><code>set mqtt.enabled on|off</code> starts or stops MQTT and preserves broker settings;</li> <li><code>set mqtt.rx on|off</code> controls uplinking of received packets;</li> <li><code>set mqtt.tx off|advert|on</code> controls uplinking of transmitted packets.</li> </ul> <p>Fresh MQTT observer settings are:</p> <ul> <li>bridge and repeating enabled;</li> <li>received packet uplinking enabled;</li> <li>transmitted packet uplinking set to <code>advert</code>, meaning only the node's own   adverts are included;</li> <li>packet and status publishing enabled;</li> <li>raw publishing disabled;</li> <li>slot 1 set to <code>analyzer-us</code>;</li> <li>slot 2 set to <code>analyzer-eu</code>;</li> <li>slots 3 through 6 disabled;</li> <li>WiFi modem power saving set to <code>min</code> in the Cascade profile and <code>none</code> in   target-default builds;</li> <li>WiFi SSID and IATA code empty.</li> </ul> <p>Up to six broker configurations can be saved. The number that can be active at once depends on the target and available memory. A non-PSRAM ESP32 should normally use no more than two TLS/WSS brokers; some classic ESP32 targets are reliable with only one. Excess configured slots remain saved but show as inactive in <code>get mqtt.status</code>.</p> <p>The bridge has a bounded packet queue for broker or WiFi outages and reconnects automatically. A non-PSRAM build holds 6 packets and a PSRAM build holds 50. When the queue is full, the oldest item is replaced; after five minutes with no broker connected, stale queued packets are flushed. MQTT packet delivery is best effort rather than durable storage. Each enabled slot publishes independently, so one failed broker does not intentionally stop the other slots.</p> <p>See MQTT_IMPLEMENTATION.md for the complete preset list, custom broker configuration, topic formats, authentication, diagnostics, and memory limits.</p>"},{"location":"WiFi/#mqtt-observer-setup","title":"MQTT observer setup","text":"<p>Most full-size ESP32 MQTT observer builds have the shared WebConfig portal. On a fresh device with no saved SSID:</p> <ol> <li>Join the open <code>MeshCore-Setup-XXXX</code> access point.</li> <li>If the captive page does not open, browse to <code>http://192.168.4.1/</code>.</li> <li>Enter WiFi, radio, identity, and MQTT settings.</li> <li>Select Save &amp; Reboot.</li> <li>After reboot, check <code>get wifi.status</code> and <code>get mqtt.status</code>.</li> </ol> <p>The setup AP is unauthenticated unless the firmware was built with <code>WEBCONFIG_AP_PASSWORD</code>. It uses plain HTTP, so provision it in a trusted location. When WebConfig is running on the normal LAN, repeater and room-server builds require the node's admin password.</p> <p>On an expanded FULL profile with no saved SSID, this automatic setup AP has an absolute 30-minute window. Browser activity or a phone left associated with the AP does not extend it. If no SSID has been saved when the window expires, WebConfig closes and the ESP32 WiFi radio remains off automatically for the remainder of that boot. A reboot or power cycle starts a new 30-minute setup window; the timeout is deliberately not written to preferences. An administrator can still override the automatic cutoff with an explicit <code>start webconfig</code> command.</p> <p>Once an SSID is saved, the provisioning cutoff no longer applies. When WiFi is selected by <code>logging.output wifi|both</code>, the station stays enabled and keeps trying the saved network indefinitely: ESP automatic reconnect remains on and the explicit fallback advances through 15, 30, 60, 120, then 300-second retry intervals, remaining at five minutes until it reconnects. MQTT broker retries use their own backoff; a repeatedly failing broker eventually receives one probe every 30 minutes. Selecting <code>logging.output off|usb</code> keeps the MQTT bridge off, so saved credentials alone do not force WiFi on unless WebConfig is also enabled explicitly.</p> <p>The equivalent MQTT observer CLI setup is:</p> <pre><code>set wifi.ssid Your WiFi Name\nset wifi.pwd Your WiFi Password\nset mqtt.iata SEA\nset name MyObserver\nreboot\n</code></pre> <p>The SSID and password values are the rest of the command line. Spaces are allowed and quotes must not be added. SSIDs may contain at most 31 characters and passwords at most 63. Leave the password value empty for an open network.</p> <p>Useful checks are:</p> <pre><code>get wifi.ssid\nget wifi.status\nget wifi.powersave\nget wifi.cli\nget mqtt.enabled\nget mqtt.rx\nget mqtt.tx\nget mqtt.status\nget mqtt1.diag\nget mqtt2.diag\n</code></pre> <p>To change a configured observer through WebConfig without leaving the portal enabled after every reboot:</p> <pre><code>start webconfig\n</code></pre> <p>This uses the LAN when WiFi is connected. To force the setup AP, the MQTT bridge must release WiFi first:</p> <pre><code>set mqtt.enabled off\nstart webconfig ap\n</code></pre> <p>After provisioning, use Save &amp; Reboot, or stop the temporary portal and restart the bridge:</p> <pre><code>stop webconfig\nset mqtt.enabled on\n</code></pre> <p>Current MQTT observer artifacts use the expanded FULL partition profile so WebConfig and the complete role CLI are retained. Install the matching merged image over USB once when moving a device from the legacy partition layout.</p>"},{"location":"WiFi/#wifi-companion-setup","title":"WiFi companion setup","text":"<p>A <code>*_companion_radio_wifi</code> build replaces the BLE or USB companion link with the MeshCore companion protocol over TCP port 5000. The phone or computer must be able to reach the device on the same LAN.</p> <p>Most ESP32 <code>*_companion_radio_full</code> targets keep all three Companion links at once: USB, BLE, and TCP port 5000. The two SenseCAP Indicator Full targets are the exception: USB remains available, while a saved next-boot selector starts exactly one secondary wireless Companion transport, either BLE or infrastructure WiFi/TCP. On the ESP-NOW Indicator, this selector never stops the primary ESP-NOW mesh radio. Full ESP32 images also provide a source-only LoRa mOTA service on ports 5001 and 5002 whenever their WiFi transport is active. See the full Companion guide for its build, terminal mode, and complete update-source workflow.</p> <p>The LilyGo T-Beam 1W Full Companion maps one press of the physical <code>BOOT</code> button (GPIO0) to a persistent WiFi on/off toggle. Turning WiFi off closes WebConfig, Companion TCP, mOTA, and MQTT network services while USB, BLE, the display, GPS, and LoRa remain available. Another BOOT press turns WiFi back on even after reboot. WiFi/WebConfig starts first; BLE starts two seconds later so the ESP32-S3 can reserve the setup server's internal heap before both radios run together.</p> <p>The companion loads runtime credentials saved in NVS. A non-placeholder compile-time <code>WIFI_SSID</code>/<code>WIFI_PWD</code> can be used as a first-boot fallback, but saved credentials take priority. With no credentials, its WebConfig portal starts in setup-AP mode. With credentials, the WebUI is enabled by default on the station IP.</p> <p>Full Companion can also be provisioned from its USB terminal or TCP port 5002:</p> <pre><code>get wifi.ssid\nget wifi.status\nset wifi.ssid SlowFi\nset wifi.pwd your-password\n</code></pre> <p>Credential writes are persisted immediately. After the reply has drained, the Companion restarts its WiFi station with the saved pair. A port-5002 client is expected to disconnect and can reconnect at the new LAN IP. USB masks the password as it is entered; <code>get wifi.pwd</code> is intentionally unavailable. The standalone credential store accepts an empty password, ordinary passphrases up to 63 characters, or an exact 64-character hexadecimal WPA/WPA2 PSK. A non-hexadecimal 64-character value and every longer value are rejected.</p> <p>After the saved station first connects following boot, every ESP32 WiFi Companion requests a fresh UTC time from NTP. A verified reply updates both the MeshCore clock and any detected hardware RTC; the next explicit refresh is due 24 hours after that success. A failed request times out without blocking the radio loop and retries after five minutes. While WiFi is disconnected or only the setup AP is available, the request waits for a station connection. Builds with a configured MQTT bridge use its boot-and-daily NTP owner instead, so two firmware services never reconfigure the ESP32 SNTP client at the same time. A later WiFi reconnect does not add another successful-sync request; it preserves the existing 24-hour deadline. Until a fresh internet reply succeeds, LoRa clock consensus remains available as the fallback.</p> <p>On Full Companion targets whose primary mesh radio is ESP-NOW, ESP-NOW, the setup AP, and the infrastructure-WiFi station must share one 2.4 GHz channel. The persisted channel defaults to 1 and can be inspected or changed from the text terminal:</p> <pre><code>get espnow.channel\nset espnow.channel 6\nreboot\n</code></pre> <p>Valid values are 1 through 13; use only a channel permitted in your region and supported by the router. <code>set espnow.channel</code> saves the new value but does not move the running radio; reboot the node to apply it. Every primary ESP-NOW node that should communicate with it must use the same channel, and the configured router's 2.4 GHz radio must be fixed to that channel as well. A router left on automatic channel selection can move the infrastructure connection away from the ESP-NOW mesh.</p> <p><code>espnow.channel</code> configures the node's primary ESP-NOW mesh radio. It is distinct from <code>bridge.channel</code>, which applies only to the separate ESP-NOW bridge feature. WiFi power saving does not let ESP-NOW and infrastructure WiFi operate on different channels. On an ESP32 Full build whose primary radio is ESP-NOW, <code>wifi.powersave max</code> is unavailable because a station using maximum modem sleep can miss ESP-NOW broadcasts; use <code>min</code> for coexistence. The primary mesh transport holds the driver's RF wake reference continuously, so <code>min</code> does not suspend its ESP-NOW receiver.</p> <p>ESP-NOW compatibility also depends on the bytes and PHY used above the common Espressif transport. The historical <code>*_repeater_bridge_espnow</code> firmware wraps each MeshCore packet with a magic value, checksum, and secret-based XOR, while <code>Generic_ESPNOW</code> and <code>SenseCapIndicator-ESPNow</code> send the serialized MeshCore packet directly using the ESP-NOW LR PHY. Updated bridge firmware can select either behavior without changing the board target:</p> <pre><code>get bridge.format\nset bridge.channel 1\nset bridge.format raw\n</code></pre> <p>On a Heltec V4, the ordinary <code>companion_radio_full</code> image remains a LoRa-primary Companion and does not instantiate this bridge. Select and flash the existing <code>heltec_v4_repeater_bridge_espnow</code> role before using these commands. Treat that Companion-to-repeater change as a role/partition migration: back up the node and use the exact V4 merged install artifact.</p> <p><code>wrapped</code> remains the default and interoperates with existing bridge nodes that use the same channel and <code>bridge.secret</code>. <code>raw</code> interoperates with primary-ESP-NOW nodes and other raw bridges; it requires channel 1-13, enables LR reception, forces LR transmission, and ignores <code>bridge.secret</code>. Receive parsing is strict to the selected format, so migrate peers deliberately rather than expecting one bridge to accept both. Match <code>bridge.channel</code> on the LoRa gateway to the primary nodes' <code>espnow.channel</code>; a primary-node channel change takes effect after its reboot.</p> <p>Raw mode retains MeshCore's normal packet parsing, authentication/encryption, and the bridge's duplicate suppression, but it does not provide the wrapper's secret-based network isolation. That XOR wrapper is itself only lightweight isolation, not cryptographic security. Multiple LoRa/ESP-NOW gateways covering the same nodes can temporarily amplify duplicates, even though seen-packet tracking prevents an individual bridge from immediately echoing a packet back.</p> <p>If the configured network remains unavailable for two minutes, the companion opens its setup AP so the credentials can be repaired. It continues retrying the saved network. WiFi modem sleep has its own persisted <code>wifi.powersave</code> setting and is independent of the Companion device power-saving setting. The WiFi card in Companion WebConfig exposes <code>none</code>, <code>min</code>, and <code>max</code>. Fresh Cascade-profile builds select <code>min</code>; target-default builds select <code>none</code>. A saved setting takes precedence after an upgrade.</p> <p>WiFi-only Companions can use all three modes. A Full Companion that runs WiFi and BLE simultaneously requires at least minimum modem sleep. It reports <code>min</code> when an old or target-default <code>none</code> value is found and rejects a new <code>none</code> selection. When ESP-NOW is also the primary mesh radio, <code>max</code> is unavailable: the access point does not buffer ESP-NOW broadcasts for a sleeping station, so maximum modem sleep can lose them. Firmware caps a previously saved <code>max</code> value to and reports it as <code>min</code>, and rejects a new <code>max</code> selection.</p> <p>The SenseCAP Indicator Full targets select BLE or infrastructure WiFi instead of running both. On a WiFi-selected boot, the LoRa layout accepts <code>none|min|max</code>, while the ESP-NOW layout accepts <code>none|min</code> and still rejects <code>max</code>. On a BLE-selected boot infrastructure WiFi is off; the LoRa layout accepts <code>min|max</code> for the saved WiFi setting, while ESP-NOW + BLE requires <code>min</code>. Device power saving remains independent of this modem policy.</p> <p>WiFi companions do not have the repeater/room-server admin CLI password model, so their LAN WebConfig page is intentionally unauthenticated. Use them only on a trusted LAN.</p> <p>The WebConfig Advanced card exposes device power saving on WiFi Companion, repeater, and room-server builds. It also exposes RX power saving on radio chips that support receive duty cycling. RXPS can select continuous receive, levels 1-10, automatic or explicit 16/32-symbol timing assumptions, or manual receive/sleep windows. The timing assumption does not change the radio's actual wire preamble. The WebConfig WiFi card exposes WiFi modem power saving. All three settings are persisted across reboots.</p> <p>The three settings are independent. A WiFi Companion keeps its transports available while device power saving reduces CPU and GPS idle power. An infrastructure node can sleep when device power saving is enabled, so its WiFi services may be temporarily unavailable. RXPS only duty-cycles the LoRa receiver. Fresh Cascade-profile builds default to device power saving on, RXPS on at level 8 with a 16-symbol preamble, and WiFi modem power saving at <code>min</code> on every build that includes ESP32 WiFi. The RXPS preamble value is a saved timing assumption, not the wire length: starting with v1.17.1.5, SF5-SF8 packets normally use a 32-symbol physical preamble. Firmware selects 64 for the whole SF/BW tuple only when 32 cannot enable RXPS at any level and 64 can (SF5/BW250 and SF6/BW500), then 128 only when neither shorter length works (SF5/BW500).</p> <p>When <code>ENABLE_OTA</code> is included, a WiFi companion also listens on:</p> <ul> <li>TCP 5001 for the OTA folder seeder used by <code>motatool serve --tcp</code>;</li> <li>TCP 5002 for a text management console.</li> </ul> <p>These ports do not replace the companion protocol on TCP 5000. On a <code>companion_radio_full</code> build, port 5002 is the same role-specific text terminal available over USB, including chat, remote administration, radio and power settings, WiFi/WebConfig management, <code>tempradio</code>, and the source-only <code>ota</code> commands. Other OTA-enabled Companion builds expose the same local maintenance commands as binary command <code>0x42</code>, plus <code>ota ...</code> commands. LoRa staging and installation on the Full Companion itself remain disabled.</p> <p>Port 5002 is plaintext and has no independent login gate. Use it only on a trusted LAN or temporary setup network, especially when entering a remote-node admin password with the terminal's <code>login</code> command.</p> <p>FULL ESP32 builds share the port 5001 folder seeder. It starts whenever that role has a usable WiFi station or setup access point and stops when WiFi stops. For example, a FULL repeater can run <code>start webconfig</code> to join its saved network, then accept:</p> <pre><code>motatool serve --dir ./motas --tcp &lt;repeater-ip&gt;:5001 -v\n</code></pre> <p>The TCP connection supplies <code>.mota</code> files for the node to advertise and relay over LoRa; it is not a raw <code>.bin</code> uploader. <code>start ota</code> continues to provide the direct browser uploader on HTTP port 80. A FULL role without WebConfig but with browser OTA support can use the <code>MeshCore-OTA</code> access point raised by <code>start ota</code>; its seeder address is <code>192.168.4.1:5001</code>.</p> <p>Only one external folder link can be active. A TCP client is rejected while <code>ota folder on</code> is using USB serial, and disconnecting <code>motatool</code> automatically removes the TCP folder. Port 5001 has no login layer, so expose it only on a trusted LAN or temporary setup network. Firmware target and hash checks still apply at the receiving node, along with its configured signature/trust policy.</p> <p>When the shared seeder is running, <code>get wifi.status</code> appends its live state:</p> <pre><code>OTA TCP 5001: listening\nOTA TCP 5001: client connected\n</code></pre> <p>The first state means WiFi is usable and the node is waiting for <code>motatool serve --tcp</code>. The second means a <code>motatool</code> folder is currently attached and available for LoRa OTA service.</p>"},{"location":"WiFi/#wifi-companion-with-mqtt","title":"WiFi companion with MQTT","text":"<p>A <code>*_companion_radio_wifi_mqtt</code> build combines both systems:</p> <ul> <li>the companion protocol remains available to the phone/computer on TCP 5000;</li> <li>the same WiFi station connection is shared with the MQTT bridge;</li> <li>received and selected transmitted LoRa packets can be published to the   configured MQTT slots.</li> </ul> <p>The companion owns WiFi connection and recovery in this build. The MQTT bridge waits for that connection rather than creating a second one. Stopping MQTT does not disable the TCP companion service.</p> <p>MQTT-capable Full Companions also combine these services. The WebConfig page contains MQTT settings, and the USB/TCP and browser terminals accept the same <code>mqtt.*</code> settings as infrastructure for shared features. Use <code>set mqtt.enabled on|off</code> to control MQTT without discarding broker settings. Use <code>set logging.output off|usb|wifi|both</code> to select both outputs together.</p>"},{"location":"WiFi/#webconfig-without-mqtt","title":"WebConfig without MQTT","text":"<p>Full-size ESP32 repeater and room-server builds can include WebConfig even when MQTT is absent. The portal then shows node, radio, and WiFi-related controls but removes the MQTT wizard step and MQTT tab.</p> <p>In this case WebConfig owns WiFi only while it is needed. Stopping the portal disconnects WiFi and turns the WiFi radio off. There is no persistent MQTT connection keeping WiFi active.</p> <p>Unified FULL USB + WiFi and FULL logging-fallback repeater/room-server builds both provide these CLI controls and status checks. The unified profile includes the MQTT bridge; the fallback is used only where no matching MQTT environment exists:</p> <pre><code>get wifi.ssid\nget wifi.status\nget wifi.powersave\nget wifi.cli\nget webui\nset wifi.ssid SlowFi\nset wifi.pwd your-password\nset wifi.powersave none\nset wifi.cli on\n</code></pre> <p><code>get wifi.status</code> distinguishes an unconfigured node, an inactive WiFi radio, a station connection attempt, the setup AP, a connection failure, and a working LAN connection. For a LAN connection it reports the SSID, IP address, and RSSI. If the shared OTA seeder is active, the same reply also reports whether TCP port 5001 is listening or has a <code>motatool</code> client attached. <code>get wifi.powersave</code> reports the saved standalone WebConfig setting as <code>none</code>, <code>min</code>, or <code>max</code>. An inactive status is normal when <code>webui</code> is off: run <code>start webconfig</code> to connect temporarily. Standalone credentials can be changed through WebConfig or with the listed CLI commands. Changing the SSID or password stops an active WebConfig session; start it again to connect with the new values. Use <code>set wifi.pwd</code> with no value for an open network. <code>get wifi.pwd</code> returns the saved password on a local connection; LoRa callers cannot read it. Standalone WiFi accepts ordinary passphrases up to 63 characters and exact 64-character hexadecimal WPA/WPA2 PSKs; other 64-character values and all longer values are rejected. MQTT observer WiFi passwords remain limited to 63 characters by their fixed persisted layout.</p> <p><code>get webui</code> starts with the saved boot setting, then reports the current session. For example, <code>&gt; off, http://192.168.1.130/</code> means automatic WebConfig startup is saved as off, but a temporary session started by <code>start webconfig</code> is currently active at that URL.</p>"},{"location":"WiFi/#webconfig-cli-terminal","title":"WebConfig CLI terminal","text":"<p>The terminal defaults to on. Enable or disable it from an existing admin CLI:</p> <pre><code>set wifi.cli on\nset wifi.cli off\nget wifi.cli\n</code></pre> <p>The saved <code>on</code> setting becomes active only when the WiFi station client is connected and WebConfig is running in LAN mode. It is never exposed on the open setup access point. When active, the WebConfig page has a CLI tab. Repeater and room-server commands use their local CLI after admin authentication. The browser can run <code>get password</code>, <code>get prv.key</code>, <code>erase</code>, <code>set freq</code>, <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code>, and explicit WiFi/MQTT credential getters. It also streams <code>get acl</code> and raw <code>log</code> dumps back to the browser. Log reads pause for slow clients and resume as output is read, using a fixed 160-byte file chunk. A dump snapshots the file length, so live logging cannot extend it indefinitely. The browser keeps the complete requested dump, including files larger than 64 KiB.</p> <p>Companion uses the same complete terminal as USB and Full Companion TCP port 5002, including <code>card</code>, <code>import meshcore://...</code>, <code>list</code>, <code>to</code>, messages, remote login, and delayed replies. It uses the Companion's trusted LAN. See Companion browser terminal for contact import, terminal ownership, and disconnect behavior.</p> <p>Type a command at the prompt, or paste multiple lines and confirm the sequence. Blank lines and comments are ignored. The device reports the supported batch limit. The browser sends each line after the previous command finishes and continues polling for incoming text after the sequence. <code>help</code> lists the device's actual terminal commands; Tab completes command names and settings.</p> <p>The up/down arrow keys recall commands entered during the current browser session. Commands available in the terminal still depend on the firmware role and build profile. Commands such as <code>stop webconfig</code>, <code>set wifi.cli off</code>, WiFi credential changes, and reboot operations stop the remaining block and can disconnect the page before it receives their final reply.</p>"},{"location":"WiFi/#build-profiles","title":"Build profiles","text":"<p><code>build.sh</code> produces several profiles. A profile changes the features compiled into a selected target; it does not change that target into another firmware role.</p> <p>This fork defaults every <code>build.sh</code> target to the USA Cascadia radio preset and the Cascade firmware profile. The script resolves the live <code>USA/Canada</code> entry by name, so its changing number in the downloaded menu does not affect builds. If the preset service is unavailable, it falls back to <code>910.525 MHz / BW62.5 / SF7 / CR5</code>. Use <code>--radio-preset target --profile default</code> only when a build intentionally needs the target's original radio and profile defaults. <code>--radio-preset usa-cascadia</code> is the stable explicit name; legacy numbered choices remain accepted but their meaning can change when the service reorders or adds presets.</p> Build profile WiFi/MQTT behavior Standard Uses the selected target's role. Where USB is a safe plaintext console, the same artifact embeds debug/packet logging behind persistent <code>get/set usb.logging</code>. Ordinary legacy-slot ESP32 repeater/room-server artifacts omit WebConfig when needed to fit. ESP32 MQTT observer and ESP-NOW bridge targets are automatically promoted to FULL; WiFi-companion targets keep their companion partition profile. Legacy logging No separate artifact is emitted; USB logging is part of the ordinary image. Logging output itself is not a direct MQTT uplink. MQTT Builds explicit MQTT observer or WiFi-companion-MQTT targets with USB packet logging off. Non-companion ESP32 MQTT observers always use FULL expanded partitions. FULL ESP32 USB + WiFi Uses the board's MQTT target with USB packet logging and direct WiFi MQTT together, expanded dual-OTA partitions, up to 254 neighbors, LoRa OTA, and full-size ESP32 features such as WebConfig where supported. <code>get/set logging.output off\\|usb\\|wifi\\|both</code> persists the active paths. Classic T-Beam MQTT observers retain their 50-entry table because their persistent discovery state exhausts internal DRAM at 254. FULL ESP32 logging fallback Uses the board's non-MQTT target only when no matching WiFi MQTT environment exists. It keeps debug and packet logging, expanded dual-OTA partitions, up to 254 neighbors, and LoRa OTA. Persistent <code>usb.logging off</code> also provides normal output-off operation, so ESP-NOW FULL roles need no second non-logging image. LoRa-OTA no-external-sensors A lean repeater image with no MQTT; ESP32 builds retain the compact on-demand browser WiFi uploader and up to 254 neighbors, subject to target RAM limits. <p>Repeater profiles use up to 254 neighbors. Selected Generic E22, Heltec V2, Meshadventurer, T-Beam OTA/MQTT, and TLora MQTT profiles use 50 to preserve internal-DRAM reserves. Consult the artifact capability manifest and ESP32 memory budget for the exact target.</p> <p>The interactive Option 1 FULL everything choice and the standalone FULL command select the unified USB + WiFi image when a matching MQTT target exists; otherwise they select the logging fallback. The build matrix no longer emits any separate standard logging image, or a non-MQTT FULL twin for a role covered by the unified image. Expanded Full infrastructure profiles include LoRa OTA, WebConfig where supported, up to 254 neighbors, and expanded dual-OTA partitions. Target-specific internal-DRAM limits still apply.</p> <p>FULL images change the ESP32 partition layout. Flash the matching <code>*-merged.bin</code> once when installing that layout. A partition-layout change can invalidate NVS, including saved WiFi, MQTT, name, and admin settings. Later updates using the same layout normally preserve them.</p>"},{"location":"WiFi/#wifi-power-behavior","title":"WiFi power behavior","text":"<p>MQTT observers and FULL standalone ESP32 repeater/room-server builds support:</p> <pre><code>set wifi.powersave none\nset wifi.powersave min\nset wifi.powersave max\n</code></pre> <p>Fresh Cascade-profile builds default to <code>min</code>; target-default builds use <code>none</code>, which gives the most predictable MQTT and radio performance at the highest power use. <code>min</code> and <code>max</code> reduce power but may add latency or reduce reliability on busy nodes. A saved operator setting takes precedence on an upgrade. ESP32 WiFi Companions expose the same values in their WebConfig WiFi card and USB text terminal. Full Companion also accepts the text commands from TCP port 5002. The normal binary Companion protocol can read or write the setting over USB, BLE, or TCP port 5000 without entering terminal mode. A Full Companion that runs BLE and infrastructure WiFi simultaneously rejects <code>none</code> because coexistence requires WiFi modem sleep. An ESP32 Full Companion whose primary mesh radio is ESP-NOW also rejects <code>max</code>; maximum modem sleep can cause the station to miss ESP-NOW broadcasts because the access point does not buffer them. A previously saved <code>max</code> value is capped to and reported as <code>min</code>. The SenseCAP Indicator exception uses the active-mode rules above rather than assuming BLE and infrastructure WiFi are active together. ESP-NOW and infrastructure WiFi still must use the same fixed channel.</p> <p>MQTT observer targets normally limit ESP32 WiFi transmit power to 11 dBm unless the board configuration overrides <code>MQTT_WIFI_TX_POWER</code>. This setting affects WiFi only, not LoRa transmit power.</p>"},{"location":"WiFi/#recognizing-the-wrong-firmware","title":"Recognizing the wrong firmware","text":"<p><code>get wifi.status</code>, <code>get wifi.ssid</code>, <code>get wifi.powersave</code>, and <code>get wifi.cli</code> are available on MQTT observers and on FULL non-MQTT repeater/room-server builds with WebConfig. ESP32 WiFi Companions also expose all four commands, credential setters, and <code>start webconfig [ap]</code> through their USB text terminal. Their browser CLI defaults to on in station/LAN mode. Full Companion also exposes its complete role-specific text terminal on TCP port 5002, including chat and streaming commands. MQTT commands such as <code>get mqtt.status</code> and <code>set mqtt1.preset ...</code> require MQTT code in the image, on Companion or infrastructure. Unknown settings return <code>Error: unknown setting: &lt;name&gt;</code>. Older firmware that used the discontinued compact CLI can instead report <code>Unsupported in this firmware</code> when a command was cut for space.</p> <p>Check the complete firmware filename and role. In particular:</p> <ul> <li><code>logging</code> does not mean MQTT;</li> <li><code>ota</code> does not mean MQTT;</li> <li><code>companion_radio_wifi</code> does not mean MQTT;</li> <li><code>observer_mqtt</code> and <code>wifi_mqtt</code> identify explicit MQTT targets, but Full   Companion can include MQTT without either marker; inspect its capabilities.</li> </ul> <p>Rolling firmware back does not restore settings erased by a full flash or a partition-table change. If the correct MQTT target still has no configuration, provision WiFi and MQTT again.</p>"},{"location":"WiFi/#troubleshooting","title":"Troubleshooting","text":"<p>For an MQTT observer:</p> <pre><code>get wifi.status\nget mqtt.enabled\nget mqtt.status\nget mqtt1.diag\nget mqtt2.diag\n</code></pre> <p>Common causes are:</p> <ul> <li>no saved SSID or a changed password;</li> <li>blank/invalid IATA for a preset that requires it;</li> <li>the bridge disabled;</li> <li>all MQTT slots disabled;</li> <li>too many TLS/WSS slots for the available internal memory;</li> <li>WiFi power saving being too aggressive;</li> <li>the wrong firmware role or an older compact-CLI build without WebConfig.</li> </ul> <p>For a WiFi companion, find its station IP in the router, connect the client to TCP port 5000, and use the open <code>MeshCore-Setup-XXXX</code> AP at <code>http://192.168.4.1/</code> if it cannot join the saved network. Current firmware normalizes both ESP32 WiFi interfaces to standard b/g/n before advertising the setup AP. Full Companion targets whose primary mesh radio is ESP-NOW use b/g/n+LR instead and keep the setup AP, infrastructure station, and mesh on the persisted <code>espnow.channel</code> (channel 1 by default). Their configured 2.4 GHz router and every other primary ESP-NOW node must use that same channel. MQTT-capable Companions also accept <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, and <code>get mqtt.status</code> in their USB/TCP and browser terminals. Extended slot and NTP diagnostics remain infrastructure features.</p>"},{"location":"cad_scan_validation/","title":"SX1262 channel-scanning hardware results","text":"<p>Hardware test on September 12, 2026 (America/Los_Angeles). Heltec V4 transmitter; XIAO ESP32-S3 with Wio SX1262 receiver. Both used standalone diagnostic firmware.</p> <p>The best tested scan setting was four channels with four-symbol RX-preamble windows. Three-symbol windows were unreliable even in the single-channel re-arm control. In the longer four-symbol runs, four channels received 80/80 packets, five received 79/80, and six received 52/60. These are measured limits of this implementation and test setup, not universal SX1262 channel-count limits.</p>"},{"location":"cad_scan_validation/#configuration-and-counting","title":"Configuration and counting","text":"<p>SF5, 125 kHz, coding rate 4/5, explicit header, payload CRC, and 32 preamble symbols. The programmed preamble is 8.192 ms. Channels start at 909.5 MHz and increase in 1 MHz steps; tests use the first N channels, up to 920.5 MHz. Test packets are transmitted individually with varied timing relative to the scanner. There are no overlapping transmitters in this experiment.</p> <p>A success requires a CRC-valid packet with the expected sequence, channel, length, and test payload. Every included transmission has its own successful transmitter acknowledgement; delayed serial acknowledgements are recovered by sequence, without retransmitting. The one exploratory RX scan trial with shifted acknowledgements is excluded.</p>"},{"location":"cad_scan_validation/#completed-trials","title":"Completed trials","text":"Trial Method/window Channels Payload bytes Received / sent Mean complete scan baseline-fixed Fixed-channel RX 4 64 16 / 16 \u2014 cad-standard CAD + software RX 4 64 7 / 32 14.469 ms cad-auto CAD + automatic RX 4 64 16 / 32 14.468 ms rxfast-4 rxfast 4 4 64 32 / 32 6.100 ms rxfast-4-maxpayload rxfast 4 4 255 35 / 35 6.098 ms matrix-cad1-1 cad 1 1 64 7 / 8 2.643 ms matrix-cad1-10 cad 1 10 64 2 / 20 28.389 ms matrix-cad1-11 cad 1 11 64 5 / 22 31.297 ms matrix-cad1-12 cad 1 12 64 3 / 24 34.145 ms matrix-cad2-10 cad 2 10 64 3 / 40 31.040 ms matrix-fixed-12 Fixed-channel RX 12 64 24 / 24 \u2014 matrix-rx1-10 rxfast 1 10 64 0 / 20 7.555 ms matrix-rx1-11 rxfast 1 11 64 0 / 22 8.316 ms matrix-rx1-12 rxfast 1 12 64 0 / 24 9.072 ms matrix-rx2-10 rxfast 2 10 64 0 / 40 10.133 ms matrix-rx3-7 rxfast 3 7 64 2 / 35 8.892 ms matrix-rx3-8 rxfast 3 8 64 1 / 40 10.160 ms matrix-rx4-5 rxfast 4 5 64 39 / 40 7.630 ms boundary-rx3-1 rxfast 3 1 64 4 / 24 1.268 ms boundary-rx3-4 rxfast 3 4 64 2 / 24 5.080 ms boundary-rx3-5 rxfast 3 5 64 0 / 25 6.350 ms boundary-rx3-6 rxfast 3 6 64 2 / 30 7.621 ms boundary-rx4-4 rxfast 4 4 64 80 / 80 6.104 ms boundary-rx4-5 rxfast 4 5 64 79 / 80 7.630 ms boundary-rx4-6 rxfast 4 6 64 52 / 60 9.158 ms <p><code>rxfast N</code> means a continuous-RX preamble observation window of N symbols, with minimal reconfiguration between frequencies. It is not CAD. <code>cad N</code> uses the SX1262 CAD detector with N symbols and automatic handoff to RX. CAD has no three-symbol mode.</p> <p>Scan times describe uninterrupted sweeps. When reception starts, the radio stays on that frequency through the packet and cannot hear packets on the other frequencies. Serial status requests can add occasional timing outliers.</p> <p>The maximum-payload trial ended after 35 confirmed transmissions when a serial acknowledgement was delayed. Its last TX acknowledgement and matching RX were subsequently recovered from the serial logs; all 35 were received. It is not a completed 64-packet trial.</p>"},{"location":"cad_scan_validation/#interpretation-and-limits","title":"Interpretation and limits","text":"<p>The initial four-channel fast-RX test received 32/32 64-byte packets and 35/35 255-byte packets. That is a successful strong-signal bench result, not a guarantee of zero loss. Ordinary four-symbol CAD took approximately 14.47 ms to cover four frequencies and was unreliable with an 8.192 ms preamble.</p> <p>Reducing the observation window also reduces the time available for the modem to recognize a preamble. Dividing preamble duration by scan duration alone overestimates the number of usable channels. One- and two-symbol RX windows produced no preamble detections in the tested high-channel-count cases.</p> <p>The three-symbol single-channel control repeatedly re-arms RX, just as a scan would, and received only 4/24 packets. It is distinct from continuous fixed-channel reception, which passed its baseline. This isolates a detection-window limitation even without a long multi-channel sweep.</p> <p>CAD detection peak 18 and minimum 10 were held constant. These are the datasheet four-symbol SF5 thresholds; the one- and two-symbol CAD tests do not establish optimized thresholds or weak-signal sensitivity. CAD activity followed by no decoded packet can be a late packet detection, not necessarily a noise false positive.</p> <p>Received signals were strong. These tests do not establish weak-signal range, adjacent-channel rejection, simultaneous-packet capacity, production firmware scheduling performance, power consumption, FCC compliance, or months of uptime.</p>"},{"location":"cad_scan_validation/#reproduction-and-evidence","title":"Reproduction and evidence","text":"<p>See the test harness. Compact validated results, timing counters, and final firmware/source hashes are in cad_scan_results.json. Detailed sequence-level logs and private lab transport helpers are retained locally under <code>out/cad-scan/</code>.</p>"},{"location":"carrier_wave/","title":"Carrier-wave RF checks","text":"<p><code>cw</code> and <code>cw2</code> transmit a continuous, unmodulated carrier at the selected profile's frequency and the configured TX power. They are available in the shared ASCII CLI on SX1276-family, SX1262-family, and LR1110 builds, including repeaters, Companions, room servers, and sensors that use that CLI.</p> Command Action <code>cw on</code> Use the active primary frequency for 10 seconds. <code>cw on 2.5</code> Use the active primary frequency for 2.5 seconds. <code>cw2 on 0.75</code> Use the active second profile for 0.75 seconds. <code>cw off</code> or <code>cw2 off</code> Stop the carrier immediately. Either name stops it. <code>get cw</code> or <code>get cw2</code> Show which carrier is active and its remaining seconds. <p><code>set cw ...</code> and <code>set cw2 ...</code> are also accepted. Durations range from 0.001 to 60 seconds, rounded to milliseconds. The deadline runs in the main loop, so it is not a precision pulse generator or a hardware cutoff.</p> <p><code>cw2</code> requires an active <code>radio2</code> or <code>tempradio2</code> profile in <code>rxtx</code> mode. An <code>rx</code> or disabled second profile cannot transmit a carrier. <code>cw</code> uses <code>tempradio</code> when that is the current primary profile. There is one physical transmitter: a carrier uses one profile at a time and ignores the cross-TX setting. Stop it before selecting the other carrier. Repeating <code>on</code> on the same profile restarts the duration.</p> <p>Packet transmission, reception, profile scanning, CAD, and receive recovery checks pause during the carrier. The firmware keeps the MCU awake to service the deadline, controls the board's external amplifier, and resumes normal reception and profile scanning afterward. It rejects entry during a packet or a busy radio. Profile retuning waits until the carrier stops; replacement or expiry of the active second profile stops its carrier. Nothing about CW is saved across reboot.</p> <p>The normal <code>set tx &lt;dBm&gt;</code> command also works during CW for meter sweeps. It keeps the board's power limits and PA calibration, resumes the carrier after changing power, and does not extend the CW timeout. TX power retains its usual saved behavior. SX1276 temporarily uses FSK with zero frequency deviation, then rebuilds the LoRa configuration before resuming reception.</p> <p>Use the local USB or BLE console for immediate replies and manual stopping. An on-air CLI reply must wait until the carrier ends because LoRa packets cannot transmit during the test.</p> <p>A second radio on the same frequency can detect the carrier using instantaneous RSSI. Compare readings before, during, and after transmission; CAD and packet counters are not carrier detectors. This confirms RF activity, not calibrated output power, frequency accuracy, antenna match, or SWR. Afterward, exchange ordinary LoRa packets to verify both RX and TX recovery.</p> <p>The reproducible bench witness is <code>tools/hil/cw_observer.cpp</code>, built with <code>tools/hil/cw_observer.ini</code> on a separate RAK4631. It never transmits on its own. See the hardware validation for measured results, reproduction steps, and the tested preamble settings.</p>"},{"location":"carrier_wave_validation/","title":"CW and CW2 validation","text":"<p>Tested on the MercerWoodMesh lab Pi on September 14, 2026 (Pacific), using base commit <code>9241ccc253ad2f8ac2c9a2fe756f59ba2f52505d</code> plus the CW changes. Test images are marked <code>v1.17.1.6-cw-test-9241ccc2</code>; they are development images.</p> <p>A separate RAK4631 sampled instantaneous RSSI every approximately 10 ms. The transmitting boards ran the Full V4 repeater and Full T1000-E Companion builds. Both were configured for \u22129 dBm chip TX power, with profiles at 909.5 and 919.5 MHz, BW125, SF7, CR5, and 32-symbol preambles.</p> Check V4 / SX1262 T1000-E / LR1110 <code>cw on 0.25</code> measured duration 0.25 s 0.25 s <code>cw on 1.25</code> measured duration 1.25 s 1.25 s Manual stop approximately 1 s into a 5 s request 1.01 s 1.01 s <code>cw on 1.25</code> after enabling RXPS 1.26 s 1.25 s <code>cw2 on 1.25</code> on the second frequency 1.25 s 1.25 s Primary-frequency RSSI change while CW2 transmits 0 dB 0 dB Paired RX and TX recovery checks 5/5 passed 5/5 passed <p>The observer saw roughly \u221256 to \u221257 dBm during V4 carriers and \u221267 to \u221271 dBm during T1000-E carriers, against a \u2212112 to \u2212113 dBm baseline. Readings returned to baseline after timeout and manual stop. These are received signal readings, not calibrated transmitter output measurements.</p> <p>RX recovery used CRC-valid LoRa test payloads and the DUT's receive counter. TX recovery used each DUT's MeshCore advertisement, received with valid CRC by the observer. Both DUTs finished in RX, with CW and radio2 disabled and no outbound packet pending. The observer has no autonomous transmission.</p>"},{"location":"carrier_wave_validation/#software-checks","title":"Software checks","text":"<ul> <li>1,436 native tests passed, including new checks that CW holds queued packets,   services its deadline, and prevents transmission in the same loop where a   received command starts CW.</li> <li>Compiled production-method tests cover fractional input, malformed durations,   bounds, timer rollover, busy/IRQ rejection, RXPS cleanup, board TX/RX callbacks,   profile selection and replacement, failed TX entry, stop retries, and failed   RX restart. An ESP32 sleep test covers a carrier with USB disconnected.</li> <li>Full V4 repeater, Full T1000-E Companion, and ordinary STM32   <code>RAK_3x72_companion_radio_usb</code> builds passed. The STM32 build is a compilation   check, not an RF test of that board.</li> <li>An additional existing OTA sleep test still expects the old   <code>ota::ota_ctx().apply_pending</code> spelling. It fails against unchanged HEAD   <code>src/Mesh.cpp</code> and test-file contents; the actual implementation uses   <code>ota_context_if_active()</code>. This is separate from the CW changes.</li> </ul>"},{"location":"carrier_wave_validation/#sx1276-follow-up","title":"SX1276 follow-up","text":"<p>The SX1276 carrier feature from PR #11 is included alongside SX1262 and LR1110 support. It switches to FSK with zero deviation, applies the board's calibrated TX power, and rebuilds the runtime LoRa configuration when stopped. External-PA settings pass through the same DAC/drive-power mapping used for packets, including RFO selection.</p> <p>The normal TX power command can adjust a running carrier for meter sweeps. RadioLib's SX1276 power setter enters standby, so the carrier is restarted afterward without extending the deadline. Failed power changes stop the carrier and restore the previous cached power.</p> <p>Follow-up checks use base <code>9dd9881d520b4b791600a00fff1f8e1436921054</code> plus the SX1276 changes. Production-method regression tests cover both profiles, zero deviation, external-PA calibration, RFO, power sweeps, timeout, failed FSK entry, failed restoration, retry guards, and return to LoRa. The native CW paths and existing radio/profile/sleep/PA checks pass as well. Both <code>GEPRC_Linkflow_900_repeater</code> (external PA) and <code>Heltec_v2_companion_radio_usb</code> firmware builds pass, including size checks.</p> <p>SX1276 RF output has not been measured in this follow-up. The physical RF results above apply to SX1262 and LR1110.</p>"},{"location":"carrier_wave_validation/#bench-qualifications","title":"Bench qualifications","text":"<p>The first CW2 request arrived before radio2's existing delayed activation. The harness now polls <code>get radio2.status</code> for the active mode before testing.</p> <p>An initial V4 dual-profile packet probe used a 120-symbol preamble against 32-symbol profiles. A comparison around another CW2 burst received 0/8 before and 1/8 afterward with that mismatched probe, versus 8/8 before and 8/8 afterward with a matching 32-symbol probe. The configured preamble also sets the driver's preamble-detection hold timeout, so a much longer incoming preamble can outlast that hold and be interrupted by scanning. The final dual-profile recovery checks use matched preambles. This finding does not establish general packet-loss performance for every scan combination.</p> <p>These checks establish RF activity, selected-frequency behavior, and recovery on the tested boards. They do not measure spectral purity, frequency error, SWR, calibrated power, or months of uptime. Carrier timeouts are serviced by the main loop and depend on that loop remaining responsive.</p>"},{"location":"carrier_wave_validation/#reproduction","title":"Reproduction","text":"<p>Append <code>tools/hil/cw_observer.ini</code> to <code>extra_configs</code> in <code>platformio.local.ini</code>, preserving existing entries, and build <code>pio run -e cw_observer_rak4631</code>. Flash that application onto a separate lab RAK4631. Do not run PlatformIO concurrently with another build or upload in the checkout.</p> <p>Configure the lab DUT's primary profile as above, disable radio2, set TX power to \u22129 dBm, and reboot to apply saved primary settings. Then run:</p> <pre><code>python3 tools/hil/carrier_wave.py --dut /dev/serial/by-id/DUT \\\n  --observer /dev/serial/by-id/OBSERVER --role repeater --output cw-results.json\n</code></pre> <p>Use <code>--role companion</code> for the T1000-E. The harness changes lab radio2/RXPS settings and emits short RF bursts and packet probes. It is for test boards.</p> <p>Compact evidence: carrier_wave_results.json. Command guide: carrier-wave RF checks.</p>"},{"location":"cli_build_matrix/","title":"CLI Availability by Firmware Build","text":"<p>MeshCore command availability is determined in three layers:</p> <ol> <li>Role - repeater, room server, sensor, companion, bridge, or KISS modem.</li> <li>Build profile - standard, logging, OTA, or FULL.</li> <li>Compiled hardware features - WiFi, MQTT, GPS, external sensors, PSRAM,    Ethernet, and similar optional support.</li> </ol> <p>The complete command descriptions are in CLI Commands. This page describes the commands intentionally omitted or limited by build profile. The CLI Command Availability Matrix expands this summary into separate nRF52 and ESP32 command tables.</p>"},{"location":"cli_build_matrix/#selecting-a-build-profile","title":"Selecting a build profile","text":"<p>The runtime settings profile and the feature profile are separate switches:</p> <pre><code>bash build.sh build-firmware RAK_3401_repeater \\\n  --profile cascade \\\n  --build-profile auto\n</code></pre> <p><code>--profile default|cascade</code> selects saved-setting defaults. It does not select which code is linked. <code>--build-profile auto|standard|full</code> controls features and partition policy:</p> Selection Behavior <code>auto</code> For one explicit target, pass 1 builds the complete supported LoRa-OTA-capable recipe. ESP32 boards with a qualified expanded profile use it; other standalone repeaters and room servers attempt the complete recipe in their current application region. Other roles keep every capability declared by their resolved PlatformIO recipe, including LoRa OTA, and fail instead of silently removing one that does not fit. A measured repeater or room-server flash/partition overflow starts the standard <code>no_external_sensors</code> LoRa OTA pass. Internal-flash nRF52 repeaters and room servers publish that reduced pass even when the complete image fits, because the smaller running image leaves more room to stage a delta; matched QSPI/SD roles do not need the redundant artifact. Compiler errors and missing-capability checks never trigger or conceal a reduced build. Canonical bulk commands keep their established standard partition contract. <code>standard</code> Immediately uses the deployed/portable partition contract and its documented reductions. This is useful when the operator already knows the expanded or complete image is unsuitable. <code>full</code> Requires a qualified ESP32 expanded-partition target (or an explicitly named Full Companion). Install a matching merged image when this changes the partition table. <p>Successful builds also emit <code>&lt;firmware&gt;.capabilities.json</code>. The sidecar records the effective profile, logical OTA target, actual PlatformIO base, artifact name target, promised capabilities, and every reduction selected by the script. The build fails if a promised linked marker is absent. Current invariants include <code>retry.preset</code> for repeater/room-server roles, WebConfig for the Indicator and ESP32 Full Companion, TempRadio/OTA controls for install-capable Companions, host-mOTA controls for Full Companion, and the advanced flood-rule engine for Full room servers. Resume mode will not accept an old or failed artifact without a verified sidecar.</p> <p>For a single ESP32 repeater or room-server target, <code>auto</code> selects its matching combined Full MQTT/USB/WiFi image when that image covers the plain Full recipe. The direct observer and Full-matrix paths use the same <code>full-usb-wifi-ota</code> artifact and runtime output controls. Plain Full T-Beam SX1262/SX1276 profiles and the TLora V2 repeater remain alternatives because their MQTT siblings have lower routing-table capacities.</p> <p>Standard and reduced OTA images, including images that fit the 1.25 MiB portable application slot, remain available and remain in the standard matrix pass. Select <code>--build-profile standard</code> to retain the original target and partition contract. Moving from a plain target to its MQTT sibling changes the LoRa OTA target identity; existing nodes need an appropriate wired migration. For the normal-role partition migrations, the matrix also publishes a canonical Full image under the normal target identity. Install its matching merged image over USB once; mOTA rejects the incompatible partition signature until that migration is complete, then later Full updates use the normal target ID. The portable image remains available while deployed nodes move.</p> <p>Legacy supported ESP32 Wi-Fi repeaters can use the Wi-Fi partition migration bridge to preserve their identity and install an expanded Full image without a USB flash. The default <code>cascade</code> settings profile enables device and LoRa RX power saving; saved preferences take precedence, and active USB/network services can prevent device sleep. <code>--profile default</code> instead uses the upstream power-saving defaults.</p>"},{"location":"cli_build_matrix/#role-comes-first","title":"Role comes first","text":"Role Text administration CLI Repeater Full repeater administration surface, subject to the profile differences below Room server Room-server administration surface, subject to the profile differences below Sensor Sensor command surface; it does not acquire the repeater administration tree Full, serial, Ethernet, USB, BLE, or WiFi companion Uses the companion protocol; Full combines every qualified transport for that exact board KISS modem Uses the KISS/TNC frame interface, not the repeater text CLI Bridge Uses its base role plus commands for the bridge transport compiled into that target <p>A command belonging to a different role is not considered a profile cut. For example, adding FULL features to a sensor does not turn it into a repeater administrator.</p> <p>Repeater profiles use up to 254 neighbor entries. Measured internal-DRAM limits reduce selected Generic E22, Heltec V2, Meshadventurer, T-Beam OTA/MQTT, and TLora MQTT profiles to 50. Check the artifact capability manifest and ESP32 memory budget for the exact target.</p> <p>See local maintenance commands for USB, BLE/binary Companion, TCP/Ethernet, and browser CLI privileges. A direct connection can access local diagnostics and explicit credential getters; relaying a command over LoRa keeps its remote restrictions.</p>"},{"location":"cli_build_matrix/#profile-matrix","title":"Profile matrix","text":"Build/profile Command availability Standard non-MQTT repeater or room server Keeps the normal role CLI and, where USB is a safe plaintext console, embeds debug/packet logging behind persistent <code>get/set usb.logging</code>. The explicitly selected portable policy can omit WebConfig and browser WiFi OTA, so those commands are unavailable and the omission is recorded in the capability manifest. Legacy standard logging No longer emitted separately. Its behavior is compiled into the ordinary artifact. Size-constrained STM32 targets embed packet logging without verbose <code>MESH_DEBUG</code>. LoRa-OTA (<code>-ota-</code>) LoRa OTA adds the <code>ota ...</code> commands; it does not otherwise reduce the role CLI. ESP32 <code>no_external_sensors</code> artifacts retain the compact browser WiFi uploader, the complete CLI, and up to 254 neighbors, subject to recorded internal-DRAM reductions. Internal-flash nRF52 repeater/room-server auto pair <code>full-ota</code> retains the board's external-sensor drivers; <code>reduced-ota</code> omits the declared optional sensors to leave additional internal-flash staging room. RAK3401 and RAK4631 reduced builds retain INA219, INA226, INA260, and INA3221 I2C voltage/current monitors at a measured cost below 5 KiB. Both artifacts carry the same stable OTA target identity and are checked for <code>ota ...</code> and <code>retry.preset</code>; RAK artifacts also verify the retained monitor drivers. ESP32 MQTT observer or ESP-NOW bridge Always uses the expanded FULL partition profile. The build never substitutes a reduced CLI to fit the legacy application slot. FULL ESP32 USB + WiFi Uses the matching MQTT target with packet logging on, verbose debug off, and the complete command surface supported by that role and hardware. <code>get/set logging.output off\\|usb\\|wifi\\|both</code> selects and persists the active output paths. FULL ESP32 logging fallback Uses the matching non-MQTT target only when no WiFi MQTT sibling exists, with debug and packet logging enabled and the complete command surface supported by that role and hardware. Its persistent USB gate also covers output-off operation, avoiding a second FULL ESP-NOW image. nRF52 dual-CDC Full Companion Fresh installs expose only interface <code>00</code>; it starts as an ASCII terminal and automatically hands a complete <code>&lt;</code> frame to framed Companion. The same interface also carries exclusive serial mOTA traffic. Enabling logging and rebooting adds interface <code>02</code> for plaintext logs. BLE and source-only LoRa OTA remain available. <code>get/set usb.logging</code> persistently controls whether the logging interface is present. ESP32 single-TTY Full Companion Every ESP32 Full image starts with the ASCII terminal on its one USB TTY and automatically hands a complete <code>&lt;</code> frame to framed Companion. On 1.17.1.5, run <code>set powersaving off</code> first. <code>set usb.logging on</code> switches that TTY to an input-capable plaintext logging terminal and makes framed Companion unavailable on USB; <code>set usb.logging off</code> stops logging but leaves the TTY in normal ASCII mode. The terminal stop token or a valid incoming framed probe then performs the ordinary switch to Binary Companion. A saved logging-on setting starts directly in that logging terminal and disables automatic frame detection. BLE, WiFi, and source-only LoRa OTA remain available. ESP32 Full uses Arduino-ESP32 2.x where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but still expose only one TTY. <code>no_external_sensors</code> Trims selected optional environmental/ranging drivers and their settings; it does not remove generic I2C, core repeater discovery, routing, or runtime RS-232 commands. RAK3401 and RAK4631 profiles retain the four common INA I2C voltage/current monitors. GPS-preserving RAK nRF52 OTA profiles retain their GPS commands and provider; RAK4631 defaults the bridge to UART 2 because RAK12501/L76K GPS uses UART 1. Legacy target suffixes remain stable for OTA identity compatibility. <p>The four retained INA drivers are entries in the optional environmental-sensor table, not the complete set of RAK I2C consumers. Compatible reduced profiles also retain the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 I2C GPS as separate board peripherals. RAK12501/L76K GPS uses UART Serial1. The explicit RAK4631 Serial1 bridge omits the combined GPS provider, including the otherwise non-UART RAK12500 path.</p> <p>The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>. To use both devices on one bus, leave RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>.</p> <p><code>logging</code>, <code>OTA</code>, and <code>FULL</code> describe independent build features in historical filenames. Current standard artifacts use no <code>-logging-</code> infix because their USB logging is runtime controlled.</p>"},{"location":"cli_build_matrix/#canonical-bulk-build-policy","title":"Canonical bulk-build policy","text":"<p>Bulk and release-matrix commands omit legacy names whose behavior is already available from a canonical image:</p> <ul> <li>Companion <code>_ps</code> names are replaced by the ordinary Companion image plus the   persisted <code>set powersaving on|off</code> setting.</li> <li>Companion <code>_femoff</code> names are replaced by the matching controllable-FEM   image plus <code>radio.fem.rxgain on|off</code>. The old names remain explicit build   targets for compatibility.</li> <li><code>Station_G2_logging_*</code> and <code>Station_G3_ESP32_logging_*</code> hardware names are   replaced by their ordinary Station target. G2 boosted receive gain is the   persisted <code>radio.rxgain on|off</code> setting; the G3 alias changed only the   advertised default name.</li> <li> <p>When a board has a Full Companion, that one artifact replaces its   separate USB, BLE, ordinary WiFi, hardware-serial, Ethernet Companion, and   USB packet-logging Companion artifacts.   It provides BLE and source-only LoRa OTA; ESP32 also provides ordinary WiFi.   nRF52 keeps framed traffic on interface <code>00</code> and can add logging on interface   <code>02</code> after a reboot. Every ESP32 Full build instead switches its one USB TTY   into an input-capable logging terminal. Turning logging off restores the   normal ASCII terminal; the usual stop token or a valid framed probe then   switches it to Binary Companion.   Its LoRa OTA support is source-only: it can serve a host file to another node   but has no staging store and cannot update itself over LoRa.   Installing an ESP32 Full Companion may require one merged-image erase/flash   to adopt its expanded partition table. Once migrated, later Full Companion   releases use normal app updates. The transport-specific non-Full images stay   available as explicit build targets, but are not canonical release artifacts   when the qualified Full image fits.</p> </li> <li> <p>Standalone Terminal Chat is omitted when the same exact hardware has either   Full Companion or a USB Companion, because their local text terminal supplies   the same role. Heltec E290 and T190 similarly publish one combined USB + BLE   Companion. RAK4631 repeater and room-server Ethernet builds stay separate;   only the RAK4631 Ethernet Companion is folded into Full Companion.</p> </li> <li>Matching RS-232 bridge roles are compiled into the normal repeater and   selected at runtime with <code>bridge.enabled</code>, <code>bridge.baud</code>, and <code>bridge.uart</code>.   Historical bridge names remain directly buildable but are omitted from bulk   releases. Wio-E5 remains separate because its normal image has only 916   bytes free, while the combined image exceeds the fixed 240 KiB application   partition by 2,192 bytes.</li> </ul> <p>The old aliases still work with <code>build-firmware</code> and <code>build-matching-firmwares</code>. Dedicated LoRa OTA repeater images are not collapsed; they retain their exact storage, bootloader, role, and target identity contracts. Companion boards keep transport-specific canonical images only when no exact Full recipe has passed the combined flash/RAM qualification. ESP32 deliberately uses one TTY: Binary Companion and plaintext USB logging are mutually exclusive there. nRF52 retains its optional second CDC port.</p>"},{"location":"cli_build_matrix/#complete-cli-policy","title":"Complete CLI policy","text":"<p>The compact ESP32 CLI has been removed. <code>retry.preset</code> is a checked invariant for every repeater and room-server artifact, not a FULL-only command. MQTT observers and ESP-NOW bridges are automatically promoted to FULL builds with expanded partitions rather than dropping administration commands. This keeps <code>tempradio</code>, LoRa OTA, power saving, RXPS, logging, statistics, sensor, ACL, routing, and advanced radio commands whenever the role and compiled hardware support them.</p> <p>Some commands still have hardware or feature limits. MQTT neighbor-table publishing and <code>discover.scopes</code> require the compiled <code>WITH_MQTT_NEIGHBORS</code> feature. PSRAM boards enable it automatically, and selected non-PSRAM variants opt in with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>. <code>discover.neighbors</code> does not require MQTT or PSRAM.</p>"},{"location":"cli_build_matrix/#discovery-invariant","title":"Discovery invariant","text":"<p><code>discover.neighbors</code> sends the zero-hop node-discovery request used to refresh the repeater neighbor table. It is available in every repeater build profile, including standard, logging, OTA, unified FULL, and FULL logging-fallback builds.</p> <p>The exact command is:</p> <pre><code>discover.neighbors\n</code></pre> <p>It accepts no options and returns:</p> <pre><code>OK - Discover sent\n</code></pre> <p>Some MQTT room-server targets also expose the command as part of their compiled neighbor-table feature. It is not a cross-role guarantee: companion, KISS, sensor, and ordinary room-server firmware use different interfaces or do not maintain the repeater administrator neighbor table.</p>"},{"location":"cli_build_matrix/#feature-dependent-commands","title":"Feature-dependent commands","text":"<p>Even in a FULL build, a command can be unavailable when its underlying feature does not exist on that target:</p> <ul> <li>WebConfig and the <code>wifi.ssid</code>, <code>wifi.status</code>, and <code>wifi.powersave</code> command   family require an ESP32 WebConfig build. FULL standalone repeater and   room-server builds support the corresponding WiFi setters and status   commands. ESP32 WiFi Companions with WebConfig expose WiFi credentials,   connection status, WebConfig, and power-save controls from their USB   text terminal as well as power saving through WebConfig and the binary   protocol. All ESP32 WiFi Companions with WebConfig also expose the browser   CLI tab and <code>wifi.cli</code> switch, enabled by default in station/LAN mode. Older   Companion firmware needs an update to support it. Full Companion additionally   exposes its complete chat and streaming text terminal on TCP port 5002.</li> <li>MQTT commands require an MQTT observer target.</li> <li><code>discover.scopes</code> requires an MQTT observer with compiled neighbor support;   it does not independently require PSRAM or the FULL parser.</li> <li>GPS and external-sensor commands require their drivers and pins.</li> <li>Ethernet and bridge commands require the corresponding transport.</li> <li>LoRa OTA commands require an artifact with OTA enabled.</li> <li><code>uf2reset</code> applies only to nRF52.</li> </ul> <p>When diagnosing an unavailable command, check the role first, then the filename profile, then the target's compiled hardware features and its adjacent <code>.capabilities.json</code> file. A current artifact that promises the command but does not contain its linked marker is rejected during the build.</p>"},{"location":"cli_command_availability/","title":"CLI Command Availability Matrix","text":"<p>This page is the command-by-command companion to CLI Availability by Firmware Build. Each command name links to its detailed documentation.</p> <p>The tables cover the text administration CLI used by repeater, room-server, sensor, and bridge firmware. Full Companion also has its own ASCII USB/TCP terminal; see feature switches by role. Companion apps use the companion protocol, KISS firmware uses framed KISS/TNC commands, and terminal-chat firmware has its own interface, so those build roles are not represented in the main matrices. The Companion section below lists its framed maintenance commands. Infrastructure <code>get password</code> is available locally in every profile; LoRa requests cannot read it. <code>get acl</code> and stored packet <code>log</code> are infrastructure features, not Companion contact or live USB-logging commands.</p> <p>Build columns mean:</p> <ul> <li>Standard - the ordinary non-MQTT artifact, without an explicit <code>ota</code>   filename marker. Safe plaintext-USB roles embed runtime USB logging.</li> <li>Logging - the legacy <code>-logging-</code> profile, now represented by the same   ordinary artifact and retained as a comparison column only.</li> <li>LoRa OTA - the explicit <code>-ota-</code> repeater or repeater-bridge artifact. A   legacy <code>no_external_sensors</code> profile trims selected optional environmental   and ranging drivers; it does not disable the generic I2C bus or unrelated   board-integrated peripherals. Reduced RAK3401 and RAK4631 profiles retain   INA219/INA226/INA260/INA3221 as voltage/current entries in the optional sensor   table. The SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS are   separate I2C peripherals in compatible recipes. RAK12501/L76K GPS instead   uses UART Serial1. The plain RAK profiles and RAK4631 Serial2 bridge retain   the combined GPS provider; the explicit RAK4631 Serial1 bridge omits that   provider, including RAK12500, because the bridge owns the RAK12501 UART.</li> <li>FULL unified - the expanded-partition ESP32 artifact with LoRa OTA, the   complete parser, USB packet logging, and direct WiFi MQTT. Its saved output   mode can be off, USB, WiFi, or both. MQTT observers use this profile.</li> <li>FULL fallback - the expanded-partition ESP32 non-MQTT artifact used only   where there is no MQTT sibling. It has the complete parser and a saved   USB-logging on/off gate. ESP-NOW bridges use this profile.</li> </ul> <p>The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>; they cannot coexist on one bus at those addresses. Leave RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both are installed.</p> <p>Cell values mean:</p> <ul> <li>Yes - the parser includes the command. The Scope column still applies.</li> <li>No - the profile does not expose the command.</li> <li>Feature - available only when the target compiles the feature or hardware   named in Scope.</li> <li>Local - a direct USB, BLE/binary Companion, TCP/Ethernet, or LAN browser   connection, when that transport and command exist on the role; unavailable   over LoRa.</li> <li>Manifest - available only when the MQTT target defines   <code>OTA_MANIFEST_BASE</code>.</li> <li>Limited - the family exists, but the limitation in Scope applies.</li> </ul> <p>Runtime state can still make an included command fail. Examples include no GPS fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without <code>.mota</code> apply support.</p>"},{"location":"cli_command_availability/#companion-framed-cli","title":"Companion framed CLI","text":"<p>Companion builds are not represented by the role/profile matrices below. Their local terminal and command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>) expose these settings over the normal binary USB, BLE, or TCP connection:</p> Command Availability <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code> Local terminal and binary command <code>0x42</code> <code>erase</code> Local terminal and binary command <code>0x42</code>; reboot after erasing stored settings <code>set freq &lt;MHz&gt;</code> Local terminal, binary command <code>0x42</code>, and authorized LoRa CLI; reboot to apply <code>get prv.key</code> Local terminal and binary command <code>0x42</code>; requires private key export enabled <code>get password</code> Reports that Companion has no admin password; infrastructure returns its password locally <code>get wifi.pwd</code>, <code>get mqttN.password</code>, <code>get mqttN.token</code> Local terminal and binary command <code>0x42</code>; corresponding WiFi/MQTT feature required <code>board</code> Every Companion text terminal and command <code>0x42</code> <code>version</code> Every Companion text terminal and protocol-v14 command <code>0x42</code>; returns the untruncated build identity <code>get storage.layout</code> Every Companion text terminal and command <code>0x42</code>; reports the running platform's storage layout <code>memory</code> ESP32 Full Companion text terminal and command <code>0x42</code> <code>get/set radio.rxgain</code> Companion with a supported radio <code>get/set radio.fem.rxgain</code> Companion on a board with controllable LoRa FEM LNA <code>get/set wifi.powersave</code> ESP32 WiFi Companion; active transport constraints still apply <code>get/set bluetooth.name</code> Companion firmware <code>get/set bluetooth.mac</code> Every Companion build with Bluetooth <code>get/set display.touch</code> Touchscreen Companions using the shared UI; text terminal and framed CLI; off after reboot <code>get/set display.inbox</code> Shared Companion UI; <code>history</code> (default), <code>pending</code>, or <code>unread</code>; saved across reboot <code>uf2reset</code> Every nRF52 Companion text terminal and local command <code>0x42</code>; local only <p>Deprecated binary aliases remain receive-only for older clients; new clients should use command <code>0x42</code>. See Companion radio binary protocol.</p>"},{"location":"cli_command_availability/#nrf52","title":"nRF52","text":"Area Command Scope Standard Logging LoRa OTA Operational <code>reboot</code> All text CLI roles Yes Yes Yes Operational <code>poweroff</code>; <code>shutdown</code> Board power-off support Yes Yes Yes Operational <code>uf2reset</code> Local connection; supported UF2 boards Local Local Local Operational <code>clkreboot</code> All text CLI roles Yes Yes Yes Operational <code>clock sync</code> All text CLI roles Yes Yes Yes Operational <code>clock</code> All text CLI roles Yes Yes Yes Operational <code>time &lt;epoch_seconds&gt;</code> Clock only moves forward Yes Yes Yes Operational <code>advert</code> Advert-capable role Yes Yes Yes Operational <code>advert.zerohop</code> Advert-capable role Yes Yes Yes Operational <code>erase</code> Local connection Local Local Local Information <code>ver</code> All text CLI roles Yes Yes Yes Information <code>board</code> All text CLI roles Yes Yes Yes Diagnostics <code>get storage.layout</code> Internal layout and configured QSPI or SD storage Yes Yes Yes Diagnostics <code>memory</code> ESP32 only No No No Diagnostics <code>sensor</code> Hardware wiring summary Yes Yes Yes Diagnostics <code>powerlog</code> Reset, shutdown, and boot-voltage summary Yes Yes Yes Neighbors <code>neighbors</code> Role with a neighbor table Yes Yes Yes Neighbors <code>neighbor.remove [pubkey_prefix]</code> Role with a mutable neighbor table; omit prefix to clear all Yes Yes Yes Neighbors <code>discover.neighbors</code> Repeater; some MQTT room servers Yes Yes Yes Neighbors <code>discover.scopes</code> MQTT observer with compiled neighbor support No No No Statistics <code>clear stats</code> All full-parser text CLI roles Yes Yes Yes Statistics <code>stats-core</code> Local connection Local Local Local Statistics <code>stats-radio</code> Local connection Local Local Local Statistics <code>stats-radio-diag</code> Local connection Local Local Local Statistics <code>stats-packets</code> Local connection Local Local Local Statistics <code>get telemetry.temp/volt/volt.i2c</code>; optional GPS history Non-STM32 repeater or room server; I2C command requires a detected voltage monitor; GPS requires a provider; remote access requires administrator Yes Yes Yes Statistics <code>set telemetry.gps</code>; <code>get/set/send telemetry.tx</code> Non-STM32 repeater; GPS setting requires a provider; remote access requires administrator Yes Yes Yes Logging <code>log start</code>; <code>log stop</code>; <code>log erase</code> Storage-backed roles retain data; other roles can return empty data Yes Yes Yes Logging <code>log</code> Local connection Local Local Local Logging <code>get/set usb.logging</code>; unified FULL <code>get/set logging.output</code> Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; nRF52 Full Companion can add a reboot-controlled second CDC Yes Yes No Radio <code>get radio</code>; <code>set radio ...</code> All text CLI roles Yes Yes Yes Radio <code>get tx</code>; <code>set tx &lt;dbm&gt;</code> Board TX-power limits apply Yes Yes Yes Radio <code>tempradio ...</code>; <code>normalradio</code> Full parser Yes Yes Yes Radio <code>get/set/del radioat</code>; <code>get/set/del tempradioat</code> Full parser Yes Yes Yes Radio <code>get freq</code>; <code>set freq &lt;mhz&gt;</code> Local or authorized LoRa CLI Yes Yes Yes Radio <code>get/set radio.rxgain</code> Supported radio Feature Feature Feature Radio <code>get/set radio.fem.rxgain</code> Controllable LoRa FEM Feature Feature Feature Radio <code>get/set radio.fem.txgain</code> Controllable LoRa FEM Feature Feature Feature Radio <code>get/set radio.rxps</code>; <code>get rxps.wd</code> RX power-saving support Feature Feature Feature System <code>get/set name</code> All text CLI roles Yes Yes Yes System <code>get/set lat</code> All text CLI roles Yes Yes Yes System <code>get/set lon</code> All text CLI roles Yes Yes Yes System <code>get/set prv.key</code> <code>get</code> requires a local connection Yes Yes Yes System <code>get password</code>; <code>password &lt;new_password&gt;</code> <code>get</code> requires a local connection; setter requires administrator Yes Yes Yes System <code>get/set guest.password</code> Role with guest administration Yes Yes Yes System <code>get/set owner.info</code> All text CLI roles Yes Yes Yes System <code>get/set adc.multiplier</code> Board ADC override support Feature Feature Feature System <code>send text.flood &lt;message&gt;</code> Repeater Yes Yes Yes System <code>host &lt;text&gt;</code>; <code>get host</code> Repeater with host bridge; <code>host</code> requires a remote administrator and a USB/MQTT service Yes Yes Yes System <code>get/set battery.alert</code>; <code>get battery.alert.region</code> Repeater Yes Yes Yes System <code>get/set battery.alert.low</code>; <code>get/set battery.alert.critical</code> Repeater Yes Yes Yes System <code>get/set rx.watchdog</code> Repeater Yes Yes Yes System <code>get/set system.watchdog</code> nRF52 Yes Yes Yes System <code>get public.key</code> All text CLI roles Yes Yes Yes System <code>get role</code> All text CLI roles Yes Yes Yes System <code>get powersaving</code>; <code>set powersaving on/off</code> Supported repeater board Feature Feature Feature System <code>get/set reboot.interval</code> Full parser Yes Yes Yes Clock sync <code>get/set clock.sync.*</code>; <code>clock.sync.mesh now</code> Repeater, sensor, and room server; <code>clock.sync.internet</code> needs MQTT repeater Yes Yes Yes Routing <code>get/set repeat</code> Forwarding-capable role Yes Yes Yes Routing <code>get/set path.hash.mode</code> Role that supports path-hash selection Yes Yes Yes Routing <code>get/set loop.detect</code> Repeater Yes Yes Yes Routing <code>get/set txdelay</code> All text CLI roles, including bridges Yes Yes Yes Routing <code>get/set direct.txdelay</code> Full parser Yes Yes Yes Routing <code>get/set rxdelay</code> All text CLI roles, including bridges Yes Yes Yes Routing <code>get/set dutycycle</code> Full parser Yes Yes Yes Routing <code>get/set af</code> Full parser Yes Yes Yes Routing <code>get/set int.thresh</code> All text CLI roles Yes Yes Yes Routing <code>get/set cad</code> Radio CAD support Feature Feature Feature Routing <code>get/set agc.reset.interval</code> All text CLI roles Yes Yes Yes Routing <code>get/set radio.watchdog</code> MQTT observer No No No Routing <code>get/set multi.acks</code> Full parser Yes Yes Yes Routing <code>get/set flood.advert.interval</code> Repeater Yes Yes Yes Routing <code>get/set advert.interval</code> Advert-capable role Yes Yes Yes Routing <code>get/set flood.max</code> Repeater Yes Yes Yes Routing <code>get/set flood.max.unscoped</code> Repeater Yes Yes Yes Routing <code>get/set flood.max.advert</code> Repeater Yes Yes Yes Routing <code>get/set flood.channel.data</code>; <code>get/set flood.channel.data.hops</code> Repeater Yes Yes Yes Routing <code>get/set/del flood.channel.scope*</code> Repeater Yes Yes Yes Routing <code>get/set/del flood.channel.scope.require*</code> Repeater Yes Yes Yes Routing <code>get/set/del flood.rule*</code>; <code>get/set/del flood.filter*</code>; <code>get/set/del flood.filter.blacklist*</code> Repeater; <code>flood.rule</code>/<code>flood.filter</code> also on FULL ESP32 room server (no blacklist) Yes Yes Yes Routing <code>get/set/del flood.moderation*</code> Repeater Yes Yes Yes Routing <code>get/set outpath</code> Repeater remote-client context Yes Yes Yes Routing <code>get/set altpath</code> Repeater remote-client context Yes Yes Yes ACL <code>setperm &lt;pubkey&gt; &lt;permissions&gt;</code> Repeater, room server, or sensor Yes Yes Yes ACL <code>get acl [page]</code> Repeater, room server, or sensor; admin over LoRa Yes Yes Yes ACL <code>get/set allow.read.only</code> Room server Yes Yes No Regions <code>region load</code>; <code>region save</code> Role with region storage Yes Yes Yes Regions <code>region allowf</code>; <code>region denyf</code> Role with region storage Yes Yes Yes Regions <code>region get</code>; <code>region list</code>; <code>region</code> Role with region storage Yes Yes Yes Regions <code>region home</code>; <code>region default</code> Role with region storage Yes Yes Yes Regions <code>region put</code>; <code>region def</code>; <code>region remove</code> Role with region storage Yes Yes Yes Retry <code>get/set direct.retry</code>; <code>get/set direct.retry.heard</code> Role with basic retry support Yes Yes Yes Retry <code>get/set retry.preset</code> Role with retry support Yes Yes Yes Retry <code>get/set flood.retry.count</code>; <code>get/set flood.retry.path</code>; <code>get/set flood.retry.group.path</code> Repeater Yes Yes Yes Retry <code>get/set flood.retry.advert</code>; <code>get/set flood.retry.prefixes</code>; <code>get/set flood.retry.ignore</code> Repeater Yes Yes Yes Retry <code>get/set flood.retry.bridge</code>; <code>get/set flood.retry.bucket</code> Repeater bridge retry support Feature Feature Feature Retry <code>get/set direct.retry.count</code>; <code>get/set direct.retry.base</code>; <code>get/set direct.retry.step</code> Role with retry support Yes Yes Yes Retry <code>get/set direct.retry.margin</code>; <code>get/set direct.retry.cr</code> Role with retry support Yes Yes Yes Retry <code>get/set/clear recent.repeater</code>; <code>get recent.repeaters</code> Repeater Yes Yes Yes GPS <code>get gps</code>; <code>set gps on/off</code> Compiled GPS Feature Feature Feature GPS <code>gps sync</code> Compiled GPS Feature Feature Feature GPS <code>gps setloc</code> Compiled GPS Feature Feature Feature GPS <code>gps advert [none/share/prefs]</code> Compiled GPS Feature Feature Feature Sensors <code>get/set telemetry.access</code> Sensor-capable role Feature Feature Limited Sensors <code>sensor list [start]</code> Compiled sensor manager; reduced OTA trims target-selected optional environmental/ranging drivers Feature Feature Limited Sensors <code>sensor get</code>; <code>sensor set</code> Compiled sensor setting; reduced OTA trims target-selected optional environmental/ranging drivers Feature Feature Limited Sensors <code>io [r/s/t]&lt;hex&gt;</code> Simple sensor role with board GPIO support Feature Feature No Bridge <code>get bridge.type</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.enabled</code>; <code>get bridge.running</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.delay</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.source</code> Compiled bridge Feature Feature Feature Bridge <code>get/set bridge.baud</code> RS-232 bridge Feature Feature Feature Bridge <code>get/set bridge.uart</code> RS-232 bridge Feature Feature Feature Bridge <code>get/set bridge.channel</code> ESP-NOW is ESP32 only No No No Bridge <code>get/set bridge.format</code> ESP-NOW bridge No No No Bridge <code>get/set bridge.secret</code> ESP-NOW is ESP32 only No No No Board <code>get bootloader.ver</code> nRF52 bootloader metadata Yes Yes Yes Board <code>get pwrmgt.support</code>; <code>get pwrmgt.source</code>; <code>get pwrmgt.bootreason</code>; <code>get pwrmgt.bootmv</code> Board power-management implementation Feature Feature Feature Ethernet <code>eth.status</code> Ethernet target Feature Feature No Browser OTA <code>start ota [ap]</code>; <code>stop ota</code> ESP32 browser uploader No No No WebConfig <code>start webconfig [ap]</code>; <code>stop webconfig</code>; <code>get/set webui</code> ESP32 WebConfig No No No WiFi <code>get/set wifi.ssid</code>; <code>set wifi.pwd</code>; <code>get wifi.status</code>; <code>get/set wifi.powersave</code> ESP32 WiFi No No No WiFi <code>get/set wifi.cli</code> ESP32 WebConfig No No No LoRa OTA <code>ota help</code>; <code>ota ?</code>; <code>ota h</code> LoRa OTA build No No Yes LoRa OTA <code>ota</code>; <code>ota status</code>; <code>ota st</code> LoRa OTA build No No Yes LoRa OTA <code>ota stats</code> LoRa OTA build No No Yes LoRa OTA <code>ota ls</code>; <code>ota neighbors</code>; <code>ota nbrs</code>; <code>ota updates</code>; <code>ota n</code> LoRa OTA build No No Yes LoRa OTA <code>ota get</code>; <code>ota pull</code>; <code>ota download</code> LoRa OTA build; internal-store nRF52 installs in-place deltas, while matched SD/QSPI nRF52 also accepts full images No No Yes LoRa OTA <code>ota install</code>; <code>ota apply</code>; <code>ota applydelta</code> Compatible bootloader and completed update No No Yes LoRa OTA <code>ota rescue install &lt;base_hash16&gt;</code> Legacy internal-flash nRF52 LoRa OTA build with failed app-side EndF validation; shared bootloader-update builds require valid EndF No No Feature LoRa OTA <code>ota bootloader</code>; <code>ota bootloader install &lt;MID8&gt; &lt;HASH16&gt;</code> Allowlisted internal-flash, XIAO-QSPI, or exact MeshTower V2 microSD nRF52 repeater with ABI-3 exact-board OTAFIX No No Feature LoRa OTA <code>ota cancel</code>; <code>ota drop</code>; <code>ota stop</code> LoRa OTA build No No Yes LoRa OTA <code>ota announce</code>; <code>ota adv</code> LoRa OTA build No No Yes LoRa OTA <code>ota self</code>; <code>ota id</code> Firmware with EndF trailer No No Yes LoRa OTA <code>ota qspi</code>; <code>ota storage</code> nRF52 build with raw-QSPI OTA staging Feature Feature Feature LoRa OTA <code>ota folder</code>; <code>ota fold</code> <code>on</code> needs compiled folder transport No No Feature LoRa OTA <code>ota config</code>; <code>ota cfg</code>; <code>ota set</code> LoRa OTA build No No Yes LoRa OTA <code>ota key</code>; <code>ota keys</code> LoRa OTA build No No Yes LoRa OTA <code>ota dev ...</code> Developer diagnostics No No Yes MQTT <code>get/set mqttN.preset</code> MQTT observer No No No MQTT <code>get/set mqttN.server</code>; <code>get/set mqttN.port</code>; <code>get/set mqttN.username</code>; <code>get/set mqttN.password</code> MQTT observer No No No MQTT <code>get/set mqttN.token</code>; <code>get/set mqttN.topic</code>; <code>get/set mqttN.audience</code> MQTT observer No No No MQTT <code>get mqttN.diag</code> MQTT observer No No No MQTT <code>get/set mqtt.origin</code>; <code>get/set mqtt.iata</code>; <code>get mqtt.presets</code> MQTT observer No No No MQTT <code>get mqtt.stats</code> MQTT observer No No No MQTT <code>get/set mqtt.status</code>; <code>get/set mqtt.packets</code>; <code>get/set mqtt.raw</code>; <code>get/set mqtt.interval</code> MQTT observer No No No MQTT <code>get/set mqtt.rx</code>; <code>get/set mqtt.tx</code> MQTT observer No No No MQTT <code>get/set mqtt.neighbors</code>; <code>get/set mqtt.neighbors.interval</code> MQTT observer with compiled neighbor support No No No MQTT <code>get/set mqtt.ntp</code> MQTT observer No No No MQTT <code>get mqtt.ntp.diag</code> Full MQTT observer No No No MQTT <code>get/set timezone</code>; <code>get/set timezone.offset</code> MQTT observer No No No MQTT <code>get/set mqtt.analyzer.us</code>; <code>get/set mqtt.analyzer.eu</code> Legacy MQTT aliases No No No MQTT <code>get/set mqtt.owner</code>; <code>get/set mqtt.email</code> MQTT observer; <code>get</code> requires a local connection No No No MQTT <code>get mqtt.config.valid</code> MQTT observer No No No SNMP <code>get/set snmp</code>; <code>get/set snmp.community</code> MQTT target compiled with SNMP No No No Alerts <code>get/set alert</code>; <code>get/set alert.psk</code>; <code>get/set alert.hashtag</code>; <code>get/set alert.region</code>; <code>get/set alert.wifi</code>; <code>get/set alert.mqtt</code>; <code>get/set alert.interval</code> MQTT observer No No No Alerts <code>alert test [message]</code> MQTT observer with configured alert channel No No No TLS <code>tls.bundletest &lt;host&gt;</code> MQTT target with embedded certificate bundle No No No Manifest OTA <code>ota check</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No Manifest OTA <code>ota update</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No"},{"location":"cli_command_availability/#esp32","title":"ESP32","text":"Area Command Scope Standard Logging LoRa OTA FULL unified FULL fallback Operational <code>reboot</code> All text CLI roles Yes Yes Yes Yes Yes Operational <code>poweroff</code>; <code>shutdown</code> Board power-off support Yes Yes Yes Yes Yes Operational <code>uf2reset</code> nRF52 only No No No No No Operational <code>clkreboot</code> Full parser Yes Yes Yes Yes Yes Operational <code>clock sync</code> All text CLI roles Yes Yes Yes Yes Yes Operational <code>clock</code> All text CLI roles Yes Yes Yes Yes Yes Operational <code>time &lt;epoch_seconds&gt;</code> Clock only moves forward Yes Yes Yes Yes Yes Operational <code>advert</code> Advert-capable role Yes Yes Yes Yes Yes Operational <code>advert.zerohop</code> Advert-capable role Yes Yes Yes Yes Yes Operational <code>erase</code> Local connection Local Local Local Local Local Display <code>get/set display.mode</code>; <code>display.timeout</code>; <code>display.usb.mode</code>; <code>display.usb.timeout</code> Display-equipped roles; pairing modes require BLE Companion Feature Feature Feature Feature Feature Display <code>get/set display.flip</code> MQTT observer with supported display driver No No No Feature No Information <code>ver</code> All text CLI roles Yes Yes Yes Yes Yes Information <code>board</code> All text CLI roles Yes Yes Yes Yes Yes Diagnostics <code>get storage.layout</code> Detected flash size and live partition table Yes Yes Yes Yes Yes Diagnostics <code>memory</code> ESP32 heap and PSRAM summary Yes Yes Yes Yes Yes Diagnostics <code>sensor</code> Hardware wiring summary Yes Yes Yes Yes Yes Diagnostics <code>powerlog</code> Reset-reason summary Yes Yes Yes Yes Yes Neighbors <code>neighbors</code> Role with a neighbor table Yes Yes Yes Yes Yes Neighbors <code>neighbor.remove [pubkey_prefix]</code> Role with a mutable neighbor table; omit prefix to clear all Yes Yes Yes Yes Yes Neighbors <code>discover.neighbors</code> Repeater; some MQTT room servers Yes Yes Yes Yes Yes Neighbors <code>discover.scopes</code> MQTT observer with compiled neighbor support No No No Feature No Statistics <code>clear stats</code> Full parser Yes Yes Yes Yes Yes Statistics <code>stats-core</code> Local connection Local Local Local Local Local Statistics <code>stats-radio</code> Local connection Local Local Local Local Local Statistics <code>stats-radio-diag</code> Local connection Local Local Local Local Local Statistics <code>stats-packets</code> Local connection Local Local Local Local Local Statistics <code>get telemetry.temp/volt/volt.i2c</code>; optional GPS history Non-STM32 repeater or room server; I2C command requires a detected voltage monitor; GPS requires a provider; remote access requires administrator Yes Yes Yes Yes Yes Statistics <code>set telemetry.gps</code>; <code>get/set/send telemetry.tx</code> Non-STM32 repeater; GPS setting requires a provider; remote access requires administrator Yes Yes Yes Yes Yes Logging <code>log start</code>; <code>log stop</code>; <code>log erase</code> Storage-backed roles retain data Yes Yes Yes Yes Yes Logging <code>log</code> Local connection Local Local Local Local Local Logging <code>get/set usb.logging</code>; unified FULL <code>get/set logging.output</code> Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; every ESP32 Full Companion uses an input-capable single-TTY logging terminal with framed USB Companion disabled while logging Yes Yes No No Yes Radio <code>get radio</code>; <code>set radio ...</code> All text CLI roles Yes Yes Yes Yes Yes Radio <code>get tx</code>; <code>set tx &lt;dbm&gt;</code> Board TX-power limits apply Yes Yes Yes Yes Yes Radio <code>tempradio ...</code>; <code>normalradio</code> Full parser Yes Yes Yes Yes Yes Radio <code>get/set/del radioat</code>; <code>get/set/del tempradioat</code> Full parser Yes Yes Yes Yes Yes Radio <code>get freq</code>; <code>set freq &lt;mhz&gt;</code> Local or authorized LoRa CLI Yes Yes Yes Yes Yes Radio <code>get/set radio.rxgain</code> Supported radio Feature Feature Feature Feature Feature Radio <code>get/set espnow.channel</code> Primary ESP-NOW mesh radio Feature Feature Feature Feature Feature Radio <code>get/set radio.fem.rxgain</code> Controllable LoRa FEM Feature Feature Feature Feature Feature Radio <code>get/set radio.fem.txgain</code> Controllable LoRa FEM Feature Feature Feature Feature Feature Radio <code>get/set radio.rxps</code>; <code>get rxps.wd</code> Full parser and RX power-saving support Feature Feature Feature Feature Feature System <code>get/set name</code> All full-parser text CLI roles Yes Yes Yes Yes Yes System <code>get/set lat</code> All full-parser text CLI roles Yes Yes Yes Yes Yes System <code>get/set lon</code> All full-parser text CLI roles Yes Yes Yes Yes Yes System <code>get/set prv.key</code> <code>get</code> requires a local connection Yes Yes Yes Yes Yes System <code>get password</code>; <code>password &lt;new_password&gt;</code> <code>get</code> requires a local connection; setter requires administrator Yes Yes Yes Yes Yes System <code>get/set guest.password</code> Role with guest administration Yes Yes Yes Yes Yes System <code>get/set owner.info</code> Full parser Yes Yes Yes Yes Yes System <code>get/set adc.multiplier</code> Board ADC override support Feature Feature Feature Feature Feature System <code>send text.flood &lt;message&gt;</code> Repeater Yes Yes Yes Yes Yes System <code>host &lt;text&gt;</code>; <code>get host</code> Repeater with host bridge; <code>host</code> requires a remote administrator and a USB/MQTT service Yes Yes Yes Yes Yes System <code>get/set battery.alert</code>; <code>get battery.alert.region</code> Repeater Yes Yes Yes Yes Yes System <code>get/set battery.alert.low</code>; <code>get/set battery.alert.critical</code> Repeater Yes Yes Yes Yes Yes System <code>get/set rx.watchdog</code> Repeater Yes Yes Yes Yes Yes System <code>get/set system.watchdog</code> nRF52 only No No No No No System <code>get public.key</code> Full parser Yes Yes Yes Yes Yes System <code>get role</code> All text CLI roles Yes Yes Yes Yes Yes System <code>get powersaving</code>; <code>set powersaving on/off</code> Supported repeater board Feature Feature Feature Feature Feature System <code>get/set reboot.interval</code> Full parser Yes Yes Yes Yes Yes Clock sync <code>get/set clock.sync.*</code>; <code>clock.sync.mesh now</code> Repeater, sensor, and room server; <code>clock.sync.internet</code> needs MQTT repeater Yes Yes Yes Yes Yes Routing <code>get/set repeat</code> Forwarding-capable role Yes Yes Yes Yes Yes Routing <code>get/set path.hash.mode</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set loop.detect</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set txdelay</code> All text CLI roles, including bridges Yes Yes Yes Yes Yes Routing <code>get/set direct.txdelay</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set rxdelay</code> All text CLI roles, including bridges Yes Yes Yes Yes Yes Routing <code>get/set dutycycle</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set af</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set int.thresh</code> All text CLI roles Yes Yes Yes Yes Yes Routing <code>get/set cad</code> Radio CAD support Feature Feature Feature Feature Feature Routing <code>get/set agc.reset.interval</code> All text CLI roles Yes Yes Yes Yes Yes Routing <code>get/set radio.watchdog</code> MQTT observer No No No Yes No Routing <code>get/set multi.acks</code> Full parser Yes Yes Yes Yes Yes Routing <code>get/set flood.advert.interval</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set advert.interval</code> Full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.max</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.max.unscoped</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.max.advert</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set flood.channel.data</code>; <code>get/set flood.channel.data.hops</code> Repeater, full common parser Yes Yes Yes Yes Yes Routing <code>get/set/del flood.channel.scope*</code> Repeater role handler Yes Yes Yes Yes Yes Routing <code>get/set/del flood.channel.scope.require*</code> Repeater role handler Yes Yes Yes Yes Yes Routing <code>get/set/del flood.rule*</code>; <code>get/set/del flood.filter*</code>; <code>get/set/del flood.filter.blacklist*</code> Repeater role handler; <code>flood.rule</code>/<code>flood.filter</code> also on FULL ESP32 room server (no blacklist) Yes Yes Yes Yes Yes Routing <code>get/set/del flood.moderation*</code> Repeater role handler Yes Yes Yes Yes Yes Routing <code>get/set outpath</code> Repeater remote-client context Yes Yes Yes Yes Yes Routing <code>get/set altpath</code> Repeater remote-client context Yes Yes Yes Yes Yes ACL <code>setperm &lt;pubkey&gt; &lt;permissions&gt;</code> Repeater, room server, or sensor Yes Yes Yes Yes Yes ACL <code>get acl [page]</code> Repeater, room server, or sensor; admin over LoRa Yes Yes Yes Yes Yes ACL <code>get/set allow.read.only</code> Room server Yes Yes No Yes Yes Regions <code>region load</code>; <code>region save</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region allowf</code>; <code>region denyf</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region get</code>; <code>region list</code>; <code>region</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region home</code>; <code>region default</code> Role with region storage Yes Yes Yes Yes Yes Regions <code>region put</code>; <code>region def</code>; <code>region remove</code> Role with region storage Yes Yes Yes Yes Yes Retry <code>get/set direct.retry</code>; <code>get/set direct.retry.heard</code> Role with basic retry support Yes Yes Yes Yes Yes Retry <code>get/set retry.preset</code> Role with retry support Yes Yes Yes Yes Yes Retry <code>get/set flood.retry.count</code>; <code>get/set flood.retry.path</code>; <code>get/set flood.retry.group.path</code> Repeater Yes Yes Yes Yes Yes Retry <code>get/set flood.retry.advert</code>; <code>get/set flood.retry.prefixes</code>; <code>get/set flood.retry.ignore</code> Repeater Yes Yes Yes Yes Yes Retry <code>get/set flood.retry.bridge</code>; <code>get/set flood.retry.bucket</code> Repeater bridge retry support Feature Feature Feature Feature Feature Retry <code>get/set direct.retry.count</code>; <code>get/set direct.retry.base</code>; <code>get/set direct.retry.step</code> Role with retry support Yes Yes Yes Yes Yes Retry <code>get/set direct.retry.margin</code>; <code>get/set direct.retry.cr</code> Role with retry support Yes Yes Yes Yes Yes Retry <code>get/set/clear recent.repeater</code>; <code>get recent.repeaters</code> Repeater Yes Yes Yes Yes Yes GPS <code>get gps</code>; <code>set gps on/off</code> Compiled onboard GPS Feature Feature Feature Feature Feature GPS <code>gps sync</code> Compiled onboard GPS Feature Feature Feature Feature Feature GPS <code>gps setloc</code> Compiled onboard GPS Feature Feature Feature Feature Feature GPS <code>gps advert [none/share/prefs]</code> Compiled onboard GPS Feature Feature Feature Feature Feature Sensors <code>get/set telemetry.access</code> Sensor-capable full parser Feature Feature Limited Feature Feature Sensors <code>sensor list [start]</code> Compiled sensor manager; <code>no_external_sensors</code> trims target-selected environmental/ranging drivers, not generic I2C Feature Feature Limited Feature Feature Sensors <code>sensor get</code>; <code>sensor set</code> Compiled sensor setting; <code>no_external_sensors</code> trims target-selected environmental/ranging drivers, not generic I2C Feature Feature Limited Feature Feature Sensors <code>io [r/s/t]&lt;hex&gt;</code> Simple sensor role with board GPIO support Feature Feature No No Feature Bridge <code>get bridge.type</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.enabled</code>; <code>get bridge.running</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.delay</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.source</code> Compiled bridge Feature Feature Feature Yes Feature Bridge <code>get/set bridge.baud</code> RS-232 bridge Feature Feature Feature No Feature Bridge <code>get/set bridge.uart</code> RS-232 bridge Feature Feature Feature No Feature Bridge <code>get/set bridge.channel</code> ESP-NOW bridge No No No Feature Feature Bridge <code>get/set bridge.format</code> ESP-NOW bridge No No No Feature Feature Bridge <code>get/set bridge.secret</code> ESP-NOW bridge No No No Feature Feature Board <code>get bootloader.ver</code> nRF52 only No No No No No Board <code>get pwrmgt.support</code>; <code>get pwrmgt.source</code>; <code>get pwrmgt.bootreason</code>; <code>get pwrmgt.bootmv</code> nRF52 only No No No No No Ethernet <code>eth.status</code> Ethernet target Feature Feature No No Feature Browser OTA <code>start ota [ap]</code>; <code>stop ota</code> Compiled browser uploader No No Yes Feature Feature WebConfig <code>start webconfig [ap]</code>; <code>stop webconfig</code>; <code>get/set webui</code> Compiled WebConfig No No No Feature Feature WiFi <code>get/set wifi.ssid</code>; <code>set wifi.pwd</code>; <code>get wifi.status</code>; <code>get/set wifi.powersave</code> MQTT WiFi, or standalone FULL WebConfig; standalone has no <code>get wifi.pwd</code> No No No Yes Feature WiFi <code>get/set wifi.cli</code> Compiled WebConfig No No No Feature Feature LoRa OTA <code>ota help</code>; <code>ota ?</code>; <code>ota h</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota</code>; <code>ota status</code>; <code>ota st</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota stats</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota ls</code>; <code>ota neighbors</code>; <code>ota nbrs</code>; <code>ota updates</code>; <code>ota n</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota get</code>; <code>ota pull</code>; <code>ota download</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota install</code>; <code>ota apply</code>; <code>ota applydelta</code> Compatible completed update No No Yes Yes Yes LoRa OTA <code>ota rescue install &lt;base_hash16&gt;</code> Legacy internal-flash nRF52 LoRa OTA build with failed app-side EndF validation; shared bootloader-update builds require valid EndF No No Feature No No LoRa OTA <code>ota bootloader</code>; <code>ota bootloader install &lt;MID8&gt; &lt;HASH16&gt;</code> Allowlisted nRF52 internal/QSPI repeater feature No No No No No LoRa OTA <code>ota cancel</code>; <code>ota drop</code>; <code>ota stop</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota announce</code>; <code>ota adv</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota self</code>; <code>ota id</code> Firmware with EndF trailer No No Yes Yes Yes LoRa OTA <code>ota qspi</code>; <code>ota storage</code> nRF52 build with raw-QSPI OTA staging No No No No No LoRa OTA <code>ota folder</code>; <code>ota fold</code> <code>on</code> needs compiled serial or TCP folder transport No No Feature Feature Feature LoRa OTA <code>ota config</code>; <code>ota cfg</code>; <code>ota set</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota key</code>; <code>ota keys</code> LoRa OTA build No No Yes Yes Yes LoRa OTA <code>ota dev ...</code> Developer diagnostics No No Yes Yes Yes MQTT <code>get/set mqttN.preset</code> MQTT observer No No No Yes No MQTT <code>get/set mqttN.server</code>; <code>get/set mqttN.port</code>; <code>get/set mqttN.username</code>; <code>get/set mqttN.password</code> MQTT observer No No No Yes No MQTT <code>get/set mqttN.token</code>; <code>get/set mqttN.topic</code>; <code>get/set mqttN.audience</code> MQTT observer No No No Yes No MQTT <code>get mqttN.diag</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.origin</code>; <code>get/set mqtt.iata</code>; <code>get mqtt.presets</code> MQTT observer No No No Yes No MQTT <code>get mqtt.stats</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.status</code>; <code>get/set mqtt.packets</code>; <code>get/set mqtt.raw</code>; <code>get/set mqtt.interval</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.rx</code>; <code>get/set mqtt.tx</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.neighbors</code>; <code>get/set mqtt.neighbors.interval</code> MQTT observer with compiled neighbor support No No No Feature No MQTT <code>get/set mqtt.ntp</code> MQTT observer No No No Yes No MQTT <code>get mqtt.ntp.diag</code> MQTT observer No No No Yes No MQTT <code>get/set timezone</code>; <code>get/set timezone.offset</code> MQTT observer No No No Yes No MQTT <code>get/set mqtt.analyzer.us</code>; <code>get/set mqtt.analyzer.eu</code> Legacy MQTT aliases No No No Yes No MQTT <code>get/set mqtt.owner</code>; <code>get/set mqtt.email</code> MQTT observer; <code>get</code> requires a local connection No No No Yes No MQTT <code>get mqtt.config.valid</code> MQTT observer No No No Yes No SNMP <code>get/set snmp</code>; <code>get/set snmp.community</code> MQTT target compiled with SNMP No No No Feature No Alerts <code>get/set alert</code>; <code>get/set alert.psk</code>; <code>get/set alert.hashtag</code>; <code>get/set alert.region</code>; <code>get/set alert.wifi</code>; <code>get/set alert.mqtt</code>; <code>get/set alert.interval</code> MQTT observer No No No Yes No Alerts <code>alert test [message]</code> MQTT observer with configured alert channel No No No Yes No TLS <code>tls.bundletest &lt;host&gt;</code> MQTT target with embedded certificate bundle No No No Feature No Manifest OTA <code>ota check</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No Manifest No Manifest OTA <code>ota update</code> MQTT target with <code>OTA_MANIFEST_BASE</code> No No No Manifest No"},{"location":"cli_command_availability/#supplemental-command-notes","title":"Supplemental command notes","text":"<p>These short entries cover implemented commands that do not yet have their own section in the primary command reference.</p>"},{"location":"cli_command_availability/#memory","title":"<code>memory</code>","text":"<p>ESP32 only. Prints free heap, minimum heap, largest allocation, queue depth, internal heap, and PSRAM totals.</p>"},{"location":"cli_command_availability/#sensor-hardware-summary","title":"<code>sensor</code> hardware summary","text":"<p>Prints the configured I2C pins and GPS serial pins. This is a wiring/build diagnostic, distinct from <code>sensor list</code>, <code>sensor get</code>, and <code>sensor set</code>.</p>"},{"location":"cli_command_availability/#powerlog","title":"<code>powerlog</code>","text":"<p>Prints the last reset reason. nRF52 also prints the captured shutdown reason and boot voltage.</p>"},{"location":"cli_command_availability/#stats-radio-diag","title":"<code>stats-radio-diag</code>","text":"<p>Local-serial diagnostic that prints the extended radio diagnostic counters.</p> <p></p>"},{"location":"cli_command_availability/#radiorxps-and-rxpswd","title":"<code>radio.rxps</code> and <code>rxps.wd</code>","text":"<p><code>get radio.rxps</code> reports RX power-saving state and timing. <code>set radio.rxps ...</code> changes that configuration. <code>get rxps.wd</code> reports the soft and hard RX power-saving watchdog counters.</p> <p></p>"},{"location":"cli_command_availability/#rebootinterval","title":"<code>reboot.interval</code>","text":"<p><code>get reboot.interval</code> shows the scheduled reboot interval. Use <code>set reboot.interval &lt;hours&gt;</code> for 1-255 hours, or <code>set reboot.interval 0</code> to disable it.</p> <p></p>"},{"location":"cli_command_availability/#sensor-io","title":"Sensor <code>io</code>","text":"<p>The simple-sensor role exposes its board GPIO word as hexadecimal. <code>io</code> reads it; <code>io &lt;hex&gt;</code> replaces it; and <code>io r&lt;hex&gt;</code>, <code>io s&lt;hex&gt;</code>, or <code>io t&lt;hex&gt;</code> clear, set, or toggle selected bits.</p> <p></p>"},{"location":"cli_command_availability/#get-mqttndiag","title":"<code>get mqttN.diag</code>","text":"<p>Prints the runtime diagnostic summary for MQTT slot N, including its connection state and failure history.</p> <p></p>"},{"location":"cli_command_availability/#get-mqttstats","title":"<code>get mqtt.stats</code>","text":"<p>Prints the MQTT bridge runtime statistics summary.</p> <p></p>"},{"location":"cli_command_availability/#get-mqttconfigvalid","title":"<code>get mqtt.config.valid</code>","text":"<p>Reports whether the saved MQTT configuration has the minimum values needed to run.</p> <p></p>"},{"location":"cli_command_availability/#tlsbundletest","title":"<code>tls.bundletest</code>","text":"<p><code>tls.bundletest &lt;host[:port]|url&gt;</code> tests the embedded TLS certificate bundle against a remote host without changing the MQTT configuration.</p> <p></p>"},{"location":"cli_command_availability/#manifest-ota-check-and-ota-update","title":"Manifest <code>ota check</code> and <code>ota update</code>","text":"<p>On MQTT targets with <code>OTA_MANIFEST_BASE</code>, <code>ota check</code> fetches and checks the target manifest. <code>ota update</code> downloads and applies the compatible update selected by that manifest.</p>"},{"location":"cli_commands/","title":"CLI Commands","text":"<p>See two LoRa profiles for <code>radio2</code>, <code>tempradio2</code>, scheduling, RX-only mode, cross-transmission policy, and optional radio preambles.</p> <p>See carrier-wave RF checks for <code>cw on [seconds]</code>, <code>cw2 on [seconds]</code>, and stopping a carrier with <code>off</code>.</p> <p>For copy/paste on/off recipes and the differences from Full Companion, see feature switches by role. The USB web console opens the default ASCII terminal at 115200 baud; it does not require on-device WebConfig or WiFi.</p> <p>This document provides an overview of CLI commands that can be sent to MeshCore Repeaters, Room Servers and Sensors.</p> <p>See CLI Availability by Firmware Build for the role and profile matrix. Commands depend on compiled features; some portable builds omit WebConfig while retaining the complete role CLI and compact WiFi updater.</p> <p>See CLI Command Availability Matrix for the command-by-command nRF52 and ESP32 build tables.</p> <p>The first word of a command is case-insensitive, so <code>set</code>, <code>Set</code>, and <code>SET</code> are equivalent, as are <code>get</code>, <code>Get</code>, and the other command verbs. The case of arguments such as node names, passwords, and keys is left unchanged.</p> <p>Repeater retries carrying the same logical request ID and original command bytes reuse the cached result, even when command parsing trims whitespace or splits arguments in place. Changing the timestamp alone does not execute the operation again. Normal authentication and stale-request checks still apply. Deferred commands and host-service replies remain bound to the full authenticated public key, even if permission changes move ACL entries. Removing or revoking the requester cancels pending execution; a running <code>setperm</code> can still acknowledge its own completed change to the original sender.</p> <p>Use the site search or your browser's Find command with everyday wording such as tx retries, retry attempts, serial logging, or tx power. Search terms below are alternative wording to help find a command, not additional CLI aliases. Enter the syntax shown under Usage; supported command aliases are listed there explicitly.</p>"},{"location":"cli_commands/#navigation","title":"Navigation","text":"<ul> <li>Operational</li> <li>Neighbors</li> <li>Statistics</li> <li>Logging</li> <li>Information</li> <li>Configuration</li> <li>Radio</li> <li>System<ul> <li>GPIO</li> </ul> </li> <li>Routing</li> <li>Flood Rules</li> <li>Group Text Moderation</li> <li>ACL</li> <li>Region Management<ul> <li>Region Examples</li> </ul> </li> <li>GPS</li> <li>Sensors</li> <li>Bridge</li> <li>Ethernet</li> </ul>"},{"location":"cli_commands/#operational","title":"Operational","text":""},{"location":"cli_commands/#reboot-the-node","title":"Reboot the node","text":"<p>Search terms: restart, restart node, reboot device.</p> <p>Usage:  - <code>reboot</code></p> <p>Note: No reply is sent.</p>"},{"location":"cli_commands/#power-off-the-node","title":"Power-off the node","text":"<p>Search terms: turn off device, shut down, power off.</p> <p>Usage: - <code>poweroff</code>, or - <code>shutdown</code></p> <p>Note: No reply is sent.</p>"},{"location":"cli_commands/#enter-the-uf2-bootloader-nrf52-only","title":"Enter the UF2 bootloader (nRF52 only)","text":"<p>Search terms: bootloader mode, USB firmware update, UF2 mode.</p> <p>Usage: - <code>uf2reset</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p>Note: Reboots directly into the UF2 bootloader on supported nRF52 boards. This includes the Repeater, Room Server, Sensor, Companion, and Terminal Chat local serial command surfaces. It is never accepted as a remote mesh command.</p>"},{"location":"cli_commands/#reset-the-clock-and-reboot","title":"Reset the clock and reboot","text":"<p>Usage: - <code>clkreboot</code></p> <p>Note: No reply is sent.</p>"},{"location":"cli_commands/#sync-the-clock-with-the-remote-device","title":"Sync the clock with the remote device","text":"<p>Usage:  - <code>clock sync</code></p>"},{"location":"cli_commands/#display-current-time-in-utc","title":"Display current time in UTC","text":"<p>Usage: - <code>clock</code></p>"},{"location":"cli_commands/#set-the-time-to-a-specific-timestamp","title":"Set the time to a specific timestamp","text":"<p>Usage:  - <code>time &lt;epoch_seconds&gt;</code></p> <p>Parameters: - <code>epoch_seconds</code>: Unix epoch time</p>"},{"location":"cli_commands/#send-a-flood-advert","title":"Send a flood advert","text":"<p>Usage:  - <code>advert</code></p>"},{"location":"cli_commands/#send-a-zero-hop-advert","title":"Send a zero-hop advert","text":"<p>Usage: - <code>advert.zerohop</code></p>"},{"location":"cli_commands/#ask-a-usb-connected-host-service-over-lora-repeater-only","title":"Ask a USB-connected host service over LoRa (Repeater Only)","text":"<p>Usage:</p> <ul> <li><code>host &lt;text&gt;</code> - authenticated remote administrator only</li> <li><code>get host</code> - show bridge state and byte limits</li> </ul> <p><code>host</code> hands one remote LoRa CLI request to a service on the repeater's USB host and returns that service's reply over LoRa. It does not execute the text inside the firmware. The service has 4 seconds to prove the exact request is still pending, then 6 seconds to execute and reply. A second remote command receives busy while either phase is pending.</p> <p>Request text is limited to 155 UTF-8 bytes, or 152 bytes when a companion uses its legacy three-byte correlation prefix. The complete LoRa reply is limited to 162 bytes. USB records use Base64URL text, a random 64-bit nonce, and the repeater identity's Ed25519 signature. Before executing anything, the service must return a random one-time challenge and receive the repeater's signed live proof. This avoids any dependency on repeater/Pi clock agreement. Every <code>host.reply</code> USB command must carry the matching request ID and nonce; it is not accepted from LoRa or the Ethernet CLI.</p> <p>The included Raspberry Pi endpoint supports exact commands for <code>help</code>, <code>cpu-temp</code>, <code>hostname</code>, <code>uptime</code>, <code>load</code>, <code>memory</code>, <code>disk-free</code>, and <code>clock status</code>. It also provides strictly validated <code>clock sync</code> and <code>clock set &lt;unix_epoch&gt;</code> recovery actions, opt-in <code>network restart</code> and <code>reboot</code> actions, <code>action status &lt;operation_id&gt;</code>, and <code>run &lt;alias&gt; [arguments]</code> for locally allowlisted executables with typed arguments. Clock changes and host recovery actions are disabled by default, arbitrary executables are never accepted, and no action uses a shell. Clock set accepts only canonical unsigned decimal epochs from 2020 through 2099; a root-owned Unix-socket service revalidates the request and authenticates the local service account with <code>SO_PEERCRED</code> before changing system time. Network restart and reboot use a separate root-owned Unix-socket broker with fixed systemd units; installing clock control does not grant those actions. The endpoint never uses <code>sudo</code> for privileged host actions. See LoRa CLI host service for the complete <code>meshcoretomqtt</code> setup and security model.</p>"},{"location":"cli_commands/#lora-ota-speed","title":"LoRa OTA speed","text":"<pre><code>get ota.speed\nset ota.speed &lt;0.05..3&gt;\n</code></pre> <p><code>1</code> preserves the current OTA timing. Values below <code>1</code> slow OTA traffic; values above <code>1</code> shorten adjustable delays. For example, <code>0.5</code> doubles those delays and <code>3</code> divides them by three. Decimal values such as <code>.05</code> work. <code>ota config speed &lt;factor&gt;</code> is an equivalent setter, and <code>ota config</code> shows the value. The setting is saved and can be changed during a transfer.</p> <p>Apply it on the source, destination, and relays. It controls all LoRa OTA packet types on both profiles, relay timing, discovery, and OTA adverts. Slower settings extend recovery waits and space queued OTA packets while allowing ordinary traffic through. Faster settings retain the physical retry allowance and the configured airtime budget, so throughput is not guaranteed to rise in direct proportion. Proof turnaround keeps its physical allowance. Ordinary messages, node adverts, and local staged-image verification keep their timing. Available in OTA-enabled builds for all roles, including Companions. See the OTA guide.</p>"},{"location":"cli_commands/#start-or-stop-an-over-the-air-ota-firmware-update","title":"Start or stop an Over-The-Air (OTA) firmware update","text":"<p>Search terms: WiFi OTA, wireless firmware update, OTA uploader, update firmware.</p> <p>Usage: - <code>start ota</code> - <code>start ota ap</code> - <code>stop ota</code></p> <p>On nRF52, <code>start ota</code> invokes Bluetooth DFU with the matching bootloader and application DFU ZIP. The WiFi/AP instructions below apply to ESP32.</p> <p>On ESP32, <code>start ota</code> serves the web upload page on the station IP when connected to WiFi; otherwise it raises the <code>MeshCore-OTA</code> access point. <code>start ota ap</code> always raises the access point, which is useful when the normal network uses client isolation.</p> <p>On an ESP32 build with WebConfig, the manual OTA uploader and WebConfig both use HTTP port 80 and cannot run together. Stop WebConfig before <code>start ota</code>, or stop OTA before <code>start webconfig</code>.</p> <p>FULL ESP32 builds also expose the <code>.mota</code> folder seeder on TCP port 5001 whenever WiFi is usable. This listener is independent of port 80, so a host can run <code>motatool serve --dir ./motas --tcp &lt;node-ip&gt;:5001</code> while WebConfig is active. The TCP connection auto-attaches and detaches the folder; do not run <code>ota folder on</code> at the same time because that command selects the USB-serial folder transport.</p>"},{"location":"cli_commands/#browser-configuration-portal-esp32-repeater-and-room-server","title":"Browser configuration portal (ESP32 repeater and room server)","text":"<p>Search terms: web UI, web interface, WiFi settings page, configuration website, WebConfig.</p> <p>Usage:</p> <ul> <li><code>start webconfig</code></li> <li><code>start webconfig ap</code></li> <li><code>stop webconfig</code></li> <li><code>set webui on</code></li> <li><code>set webui off</code></li> <li><code>get webui</code></li> <li><code>get wifi.ssid</code></li> <li><code>get wifi.pwd</code></li> <li><code>get wifi.status</code></li> <li><code>get wifi.powersave</code></li> <li><code>get wifi.cli</code></li> <li><code>set wifi.ssid &lt;network name&gt;</code></li> <li><code>set wifi.pwd [password]</code></li> <li><code>set wifi.powersave &lt;none|min|max&gt;</code></li> <li><code>set wifi.cli &lt;on|off&gt;</code></li> </ul> <p><code>set webui on</code> is the persistent master switch. It starts the portal now and again after future reboots; <code>set webui off</code> closes it and disables that boot start. <code>get webui</code> reports the saved on/off state plus whether the portal is inactive, joining WiFi, serving a setup AP, or serving a LAN URL. The default is <code>off</code> on repeater and room-server builds. On display-equipped repeaters, an otherwise-unused triple click toggles the same saved setting. Consequently, <code>&gt; off, http://192.168.1.130/</code> means the saved boot setting is off while a temporary WebConfig session is currently active at that URL.</p> <p><code>start webconfig</code> is a temporary start that does not change the saved switch. It serves the shared WiFi, radio, flood, loop, and status page and reports its URL. MQTT builds also show the MQTT tab and wizard step; non-MQTT builds remove them entirely. Sign in with the node's admin password. If the node has no saved WiFi SSID, the command starts the open <code>MeshCore-Setup-XXXX</code> captive AP at http://192.168.4.1/ instead.</p> <p><code>start webconfig ap</code> forces captive-AP mode. It will not interrupt an active MQTT bridge, so run <code>set mqtt.enabled off</code> first. Use <code>stop webconfig</code> to close either mode for the current boot. (<code>stop webconfig</code> does not change a saved <code>webui on</code>.) LAN mode otherwise remains active until reboot. On expanded FULL builds, an unconfigured automatic setup AP receives one absolute 30-minute window per boot, then powers WiFi off even if a client remains attached; rebooting starts a new automatic window. An administrator can explicitly run <code>start webconfig</code> again without rebooting. Once an SSID is saved, the cutoff no longer applies and the selected WiFi/MQTT mode keeps reconnecting. Other setup sessions retain their profile's idle timeout.</p> <p>Every ESP32 build with WebConfig supports the browser command terminal, including WiFi Companion and Full Companion. Companions use their complete USB/TCP terminal on the trusted LAN, including contact import, chat, recipient selection, and delayed replies. Repeater and Room Server use their local CLI after admin authentication.</p> <p>To add a Companion contact, run <code>import meshcore://&lt;full-contact-card-data&gt;</code>, then <code>list</code> to confirm it appears. Get the complete card with <code>card</code> on the other Companion. A public key alone is insufficient. See the terminal command guide for <code>to</code>, <code>send</code>, <code>login</code>, and <code>cmd</code> examples and session ownership.</p> <p>The saved <code>wifi.cli</code> setting defaults to <code>on</code>. Use <code>set wifi.cli off</code> to disable the CLI tab. <code>get wifi.cli</code> reports <code>off</code>, <code>on, waiting for WiFi client</code>, or <code>on, active</code>. The saved setting becomes active only in station/LAN mode while the WiFi client is connected. It is deliberately unavailable on the open setup access point. The tab displays each reply in the browser, including local diagnostics, <code>get password</code>, private-key and WiFi/MQTT credential reads, and <code>erase</code>. Infrastructure <code>get acl</code> and raw <code>log</code> stream to the requesting browser, with backpressure for slow clients. These maintenance commands retain their LoRa restrictions. <code>set freq</code> works both here and through authorized LoRa CLI. The bounded <code>/api/cli</code> endpoint accepts local maintenance commands; use <code>/api/terminal</code> for complete ACL and log listings. Select Command block to paste up to 100 commands with one command per line. Blank lines are ignored, and every nonblank line must fit the normal 159-byte CLI command limit. The browser sends the lines sequentially and waits for each reply before sending the next line. The queue exists only in that browser page; closing it stops any commands that have not yet been sent. A lost connection also stops the remaining block.</p> <p>Up/down arrow keys recall commands from the current browser session in single-command mode. A command that stops WebConfig, changes its WiFi connection, disables <code>wifi.cli</code>, or reboots the node stops the remaining block and can close the page before its reply is collected.</p> <p>On unified FULL USB + WiFi and FULL logging-fallback ESP32 repeater/room-server builds, <code>get wifi.ssid</code> reports the saved standalone WebConfig network and <code>get wifi.status</code> reports whether WiFi is unconfigured, off, connecting, running the setup AP, failed, or connected. A connected result includes the SSID, LAN IP, and RSSI. When the shared OTA seeder is running, the reply appends <code>OTA TCP 5001: listening</code> or <code>OTA TCP 5001: client connected</code>. WiFi being off is normal while WebConfig is inactive; run <code>start webconfig</code> when a temporary connection is wanted. <code>get wifi.powersave</code> reports the saved standalone setting as <code>none</code>, <code>min</code>, or <code>max</code>. Fresh Cascade-profile builds default to <code>min</code>; target-default builds use <code>none</code>. A saved setting takes precedence after an upgrade.</p> <p>The WiFi <code>set</code> commands work on MQTT observers and on FULL standalone ESP32 repeater/room-server builds. On a standalone build, changing the SSID or password stops an active WebConfig session; run <code>start webconfig</code> again to use the new credentials. <code>set wifi.pwd</code> with no value selects an open network. Standalone WiFi also accepts an exact 64-character hexadecimal WPA/WPA2 PSK; ordinary passphrases remain limited to 63 characters. Other 64-character values and all longer values are rejected. MQTT observer WiFi passwords retain their fixed 63-character limit. Power-save changes are applied immediately when WiFi is running and otherwise take effect on the next connection. <code>get wifi.pwd</code> returns the saved password on a local connection. It remains unavailable or masked over LoRa, and the configuration form continues to mask stored secrets.</p> <p>ESP32 WiFi Companion WebConfig exposes the same <code>wifi.powersave</code> values in its WiFi card. Every ESP32 WiFi Companion with WebConfig exposes the standalone <code>wifi.ssid</code>, <code>wifi.status</code>, <code>wifi.powersave</code>, <code>wifi.cli</code>, and WebConfig command families through its USB text terminal. Full Companion exposes the same role-specific terminal on TCP port 5002. Credential writes reply before restarting the WiFi station, so a TCP client should expect to reconnect at the new address; USB password input is masked. Binary Companion clients can use USB, BLE, or TCP port 5000 without the terminal-start token: send command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>) followed by the same CLI text, such as <code>get wifi.powersave</code>, <code>get wifi.pwd</code>, <code>stats-core</code>, or <code>set wifi.powersave min</code>. See local maintenance commands for the complete access rules. WiFi-only Companions accept all three modes. A Full Companion that runs BLE and infrastructure WiFi simultaneously rejects <code>none</code> because coexistence requires modem sleep. Companion device power saving and LoRa <code>radio.rxps</code> remain independent. On an ESP32 Full Companion whose primary mesh radio is ESP-NOW, <code>max</code> is also unavailable: a station using maximum modem sleep can miss ESP-NOW broadcasts, which the access point does not buffer for it. A previously saved conflicting value is capped to and reported as <code>min</code>, and a new conflicting selection is rejected. The primary mesh radio also holds the ESP-IDF WiFi wake reference continuously so unsolicited ESP-NOW frames remain receivable; selecting <code>min</code> does not put that primary receiver to sleep.</p> <p>SenseCAP Indicator Full is the exclusive-secondary exception. On a WiFi-selected boot, LoRa accepts <code>none|min|max</code> and ESP-NOW accepts <code>none|min</code>. On a BLE-selected boot infrastructure WiFi is not started; LoRa accepts <code>min|max</code> for the saved WiFi setting, while ESP-NOW + BLE requires <code>min</code>. USB and the primary LoRa or ESP-NOW radio remain available in every mode.</p>"},{"location":"cli_commands/#view-or-change-the-primary-esp-nowwifi-channel","title":"View or change the primary ESP-NOW/WiFi channel","text":"<p>Usage:</p> <ul> <li><code>get espnow.channel</code></li> <li><code>set espnow.channel &lt;channel&gt;</code></li> </ul> <p>Parameters:</p> <ul> <li><code>channel</code>: Shared 2.4 GHz WiFi channel from <code>1</code> through <code>13</code>; choose one   permitted in your region and supported by the router.</li> </ul> <p>Default: <code>1</code></p> <p>This command is available when ESP-NOW is the node's primary mesh radio. The setting is persisted. A <code>set</code> reply reports that reboot is required; until reboot, the running ESP-NOW radio remains on its previous channel. On builds that also provide ordinary WiFi, its station and setup AP share that channel.</p> <p>After reboot, ESP-NOW, the setup AP, and the infrastructure-WiFi station use the selected channel. Every primary ESP-NOW node that must communicate with this node, plus the configured router's 2.4 GHz radio, must use the same fixed channel. WiFi power saving does not allow the transports to use different channels. On an ESP32 Full build with primary ESP-NOW, <code>wifi.powersave max</code> is unavailable because maximum modem sleep can miss ESP-NOW broadcasts; use <code>min</code> for coexistence. The firmware keeps the primary ESP-NOW receiver awake while still using the <code>min</code> WiFi/Bluetooth coexistence policy.</p> <p><code>espnow.channel</code> is the channel of the primary ESP-NOW mesh transport. It is separate from <code>bridge.channel</code>, which configures only an ESP-NOW bridge on a firmware role whose primary mesh radio is LoRa.</p> <p>The browser portal is not compiled into the two 4 MB <code>LilyGo_TLora_V2_1_1_6_*_observer_mqtt</code> targets because it does not fit while retaining the two app slots required for LoRa OTA. Their normal CLI settings remain available.</p>"},{"location":"cli_commands/#erasefactory-reset","title":"Erase/Factory Reset","text":"<p>Search terms: factory defaults, reset settings, erase configuration.</p> <p>Usage: - <code>erase</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p>Warning: This is destructive!</p>"},{"location":"cli_commands/#neighbors-repeater-only","title":"Neighbors (Repeater Only)","text":""},{"location":"cli_commands/#list-nearby-neighbors","title":"List nearby neighbors","text":"<p>Search terms: nearby nodes, neighbor list, neighbour list.</p> <p>Usage:  - <code>neighbors</code></p> <p>Note: The output of this command is limited to the 8 most recent adverts.</p> <p>Note: Each line is encoded as <code>{pubkey-prefix}:{timestamp}:{snr*4}</code></p>"},{"location":"cli_commands/#remove-a-neighbor","title":"Remove a neighbor","text":"<p>Usage:  - <code>neighbor.remove &lt;pubkey_prefix&gt;</code> - <code>neighbor.remove</code> \u2014 remove all neighbors</p> <p>Parameters:  - <code>pubkey_prefix</code>: An even-length hexadecimal prefix (up to the full 64-character   public key). All neighbors matching it are removed. Invalid keys are rejected.</p> <p>Omitting the prefix clears the table. An empty or whitespace-only prefix is also accepted for compatibility with the mobile app's Remove All Neighbors action. Newly heard zero-hop adverts can populate the table again.</p>"},{"location":"cli_commands/#discover-zero-hop-neighbors","title":"Discover zero hop neighbors","text":"<p>Usage:  - <code>discover.neighbors</code></p> <p>This command is available in every repeater build profile, including portable MQTT, standard, logging, OTA, unified FULL, and FULL logging-fallback artifacts. It does not require MQTT or PSRAM.</p>"},{"location":"cli_commands/#discover-neighbor-scopes-mqtt-observer-neighbors-feature","title":"Discover neighbor scopes (MQTT observer, neighbors feature)","text":"<p>Refreshes the zero-hop neighbor table, then queries each neighbor for its region scopes and publishes the assembled table to the MQTT <code>neighbors</code> topic once.</p> <p>Usage: - <code>discover.scopes</code></p> <p>Note: Requires an MQTT observer build with the neighbors feature compiled in (all PSRAM boards, plus non-PSRAM boards built with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>). Elsewhere it replies <code>Err - neighbors not enabled in this build</code>. If a <code>discover.neighbors</code> refresh is already in flight, the scope pass is queued behind it.</p>"},{"location":"cli_commands/#statistics","title":"Statistics","text":""},{"location":"cli_commands/#list-rate-limited-flood-adverts","title":"List Rate-Limited Flood Adverts","text":"<p>Usage: <code>get flood.advert [page]</code> or <code>get flood.advert key &lt;index&gt;</code></p> <p>Lists tracked advert origins currently subject to a forwarding limit. Page 1 is the default, with three entries per page so replies fit both USB and admin LoRa CLI. Each row shows its index, the first 12 public-key hex characters, the limit reason, and the minimum wait before another new advert can pass the automatic limiter. Ordinary forwarding filters still apply.</p> <pre><code>get flood.advert\nget flood.advert 2\nget flood.advert key 1\n</code></pre> <p>Reasons are <code>quota</code> (the prefix's three-hour forwarding allowance is spent), <code>history</code> (distinct receive history is full), and <code>bad</code> (the full key is under the stricter one-advert-per-12-hours rule). A <code>bad</code> key remains listed when <code>wait=0s</code>: one forward is eligible, but its seven-day recovery is not complete. If several limits apply, <code>bad</code> takes precedence over <code>history</code>, then <code>quota</code>; the displayed wait accounts for all applicable limits.</p> <p>The <code>key</code> form returns the complete 64-hex public key, reason, wait, shared prefix forwarding count/quota, shortest received hop count, and remaining bad-list recovery time. Different full keys with the same 12-hex prefix remain separate entries. Indices refer to the current live list and can change as history expires; read the full key before using a targeted clear.</p> <p>Queries do not clear history, spend quota, or refresh abuse/recovery timers. Elapsed history expires normally. Origins rejected only because every table slot protects abuse history are not retained and cannot be enumerated. Available on repeaters, room servers, and forwarding sensors through their ordinary local/admin CLI. Companions do not have this table.</p>"},{"location":"cli_commands/#clear-automatic-flood-advert-history","title":"Clear Automatic Flood Advert History","text":"<p>Usage: <code>clear flood.advert all</code> or <code>clear flood.advert &lt;64-hex-full-public-key&gt;</code></p> <p>Clears automatic advert forwarding quotas, first strikes, and seven-day bad-list history for all keys or one exact full key. Available on repeaters, room servers, and forwarding sensors through their ordinary local/admin CLI (including admin LoRa CLI). A missing selector, a key prefix, or a malformed key is rejected. It does not change saved settings or manual flood rules. Reboot also clears this RAM-only history. See automatic advert limits.</p>"},{"location":"cli_commands/#clear-stats","title":"Clear Stats","text":"<p>Usage: <code>clear stats</code></p> <p></p>"},{"location":"cli_commands/#system-stats-battery-uptime-queue-length-and-debug-flags","title":"System Stats - Battery, Uptime, Queue Length and Debug Flags","text":"<p>Usage:  - <code>stats-core</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p></p>"},{"location":"cli_commands/#radio-stats-noise-floor-last-rssisnr-airtime-receive-errors","title":"Radio Stats - Noise floor, Last RSSI/SNR, Airtime, Receive errors","text":"<p>Search terms: signal strength, signal quality, RSSI, SNR, radio noise.</p> <p>Usage: <code>stats-radio</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p></p>"},{"location":"cli_commands/#packet-stats-packet-counters-received-sent","title":"Packet stats - Packet counters: Received, Sent","text":"<p>Usage: <code>stats-packets</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p> <p></p>"},{"location":"cli_commands/#read-repeater-and-room-server-telemetry-history","title":"Read repeater and room-server telemetry history","text":"<p>Repeater and room-server firmware record one UTC-aligned sample every 30 minutes. Temperature and battery voltage retain 336 samples (seven rolling days). Each detected INA219, INA226, INA260, or INA3221 voltage channel retains 192 samples (four rolling days). GPS-capable builds retain three GPS days by default; repeaters request a seven-day default at startup. Builds without a GPS provider omit the GPS history commands to conserve flash. All history and any runtime retention change are held in RAM and reset after a reboot.</p> <p>The feature is omitted from flash-constrained STM32 repeater and room images.</p> <p>Usage:</p> <ul> <li><code>get telemetry.temp [page]</code></li> <li><code>get telemetry.volt [page]</code></li> <li><code>get telemetry.volt.i2c [channel [page]]</code></li> <li><code>get telemetry.gps [page]</code></li> <li><code>set telemetry.gps &lt;days&gt;</code></li> <li><code>get telemetry.tx</code></li> <li><code>set telemetry.tx &lt;off|direct|path&gt;</code></li> <li><code>set telemetry.tx schedule &lt;off|1-30d&gt;</code></li> <li><code>send telemetry.tx now</code></li> <li><code>get data.tx</code></li> <li><code>get data.tx path</code></li> <li><code>set data.tx path &lt;direct|none|path&gt;</code></li> <li><code>get data.tx region</code></li> <li><code>set data.tx region &lt;auto|default|none|name&gt;</code></li> </ul> <p>Parameters:</p> <ul> <li><code>page</code>: Page <code>1</code> is always newest. Temperature and voltage pages each hold   24 hours and accept <code>1</code>-<code>7</code>. GPS pages each hold 12 hours and accept <code>1</code>   through twice the current GPS retention in days. Omitting the page selects   page <code>1</code>.</li> <li><code>channel</code>: Cayenne LPP channel assigned to an external voltage monitor.   <code>get telemetry.volt.i2c</code> lists channels that have at least one non-zero   sample. Supplying a channel returns 48 points (24 hours) per page; pages   <code>1</code>-<code>4</code> cover all four days. A detected input whose complete retained history   is zero is treated as disconnected and is omitted until it reports a   non-zero voltage. An INA3221 contributes three consecutive entries, in   hardware-input order. If it is the only detected external sensor these are   normally LPP channels <code>2</code>, <code>3</code>, and <code>4</code>; always use the no-argument command   as the authoritative list because earlier detected sensors shift the LPP   numbers.</li> <li><code>days</code>: Requested GPS retention from <code>1</code> through <code>30</code> days. Retention above   three days uses heap memory. The allocator reduces the requested value as   needed to leave at least 2048 bytes free and replies with the days and pages   actually available. For example, a request can return   <code>OK - telemetry.gps days=18 pages=36 requested=30</code>.</li> <li><code>direct</code>: Set the shared <code>data.tx</code> path to zero-hop and, in the legacy   combined command, enable the telemetry schedule.</li> <li><code>path</code>: A comma-separated direct route using the same one-, two-, or   three-byte hop hashes accepted by <code>set outpath</code>.</li> <li><code>schedule</code>: Automatic interval in whole days. Automatic transmission is off   on a fresh install. The retained cadence defaults to <code>2d</code>; <code>off</code> retains the   shared route for manual test sends.</li> </ul> <p>Local serial and remote administrator CLI sessions can read the history on both roles. Collection uses the MCU temperature, battery voltage, external I2C voltage monitors, and an already-valid onboard GPS fix. It does not wake GPS, so an off, sleeping, or unfixed GPS produces a missing location sample without changing its power-saving schedule.</p> <p>External voltage history allocates 360 bytes for each detected monitor channel (1,080 bytes for all three INA3221 inputs). The allocation reserves all detected inputs so a sensor connected later can start recording, but all-zero inputs are omitted from command replies and LoRa transmission.</p> <p>Replies contain <code>&gt;</code> followed by standard padded Base64. After decoding, all multi-byte integers are little-endian. Packed fields are written most significant bit first, oldest sample first.</p> <p>Use the browser-based Telemetry history decoder to turn a reply into a timestamped table or downloadable CSV without uploading the data.</p> <p><code>telemetry.tx</code> is disabled by default. Its enabled state and cadence are stored separately from the shared <code>data.tx</code> path and region. <code>data.tx</code> defaults to zero-hop <code>direct</code> plus <code>region=auto</code>, but it does not enable telemetry or any other producer. For compatibility, <code>set telemetry.tx direct|path</code> updates the shared path and enables the default <code>2d</code> schedule; new configuration should use <code>set data.tx path ...</code> followed by <code>set telemetry.tx schedule ...</code>. An automatic run waits until 165 half-hour positions are available, then sends one maximum-size temperature packet, one maximum-size battery-voltage packet, and up to three <code>IVB1</code> packets for every populated I2C voltage channel. GPS is never included in this raw transmission. The history remains boot-local, so the first scheduled run after a reboot needs about 82.5 hours to fill. On the default two-day interval, each 82.5-hour temperature or battery packet overlaps its predecessor by 34.5 hours. Packets are paced two seconds apart. A queue failure is retried after 30 minutes only for the packet that did not queue; successfully queued packets are not duplicated.</p> <p><code>send telemetry.tx now</code> is an administrator-only test action. It queues temperature and battery-voltage snapshots plus the available I2C voltage chunks over the configured path. It uses all currently available base positions up to 165 and all available I2C positions up to 192 per populated channel. It works while the schedule is off and does not move the next scheduled send time. RAW_CUSTOM direct packets do not enter the normal encrypted direct-message retry mechanism.</p> <p>Full snapshots are 184-byte RAW_CUSTOM payloads. Manual tests can be shorter while history fills. Both formats are binary, not Base64 and not encrypted:</p> Bytes Meaning <code>0</code>-<code>3</code> ASCII magic <code>TTB1</code> for temperature or <code>TVB1</code> for voltage <code>4</code>-<code>11</code> First eight bytes of the repeater public key <code>12</code>-<code>15</code> First sample UTC epoch, unsigned 32-bit little-endian <code>16</code>-<code>17</code> Sample interval in minutes, unsigned 16-bit little-endian (<code>30</code>) <code>18</code> Sample count (<code>1</code>-<code>165</code>) <code>19</code> onward Oldest-to-newest encoded samples for the selected series <p>Temperature codes reserve <code>0</code> for no reading, <code>1</code> for below <code>-50 C</code>, and <code>2</code> for above <code>+77 C</code>. Codes <code>3</code> through <code>130</code> represent exact whole degrees from <code>-50 C</code> through <code>+77 C</code>; decode them as <code>code - 53</code>. Voltage codes use the same encoding as the paged voltage payload documented below.</p> <p>External voltage snapshots use a separate packed layout. A full four-day channel takes three 140-byte <code>IVB1</code> payloads of 64 points each:</p> Bytes Meaning <code>0</code>-<code>3</code> ASCII magic <code>IVB1</code> <code>4</code>-<code>11</code> First eight bytes of the source public key <code>12</code>-<code>15</code> First sample UTC epoch, unsigned 32-bit little-endian <code>16</code>-<code>17</code> Sample interval in minutes, unsigned 16-bit little-endian (<code>30</code>) <code>18</code> Cayenne LPP voltage channel <code>19</code> Sample count (<code>1</code>-<code>64</code>) <code>20</code> onward Oldest-to-newest packed 15-bit voltage codes <p>Code <code>0</code> means missing or disconnected. Codes <code>1</code>-<code>32767</code> represent <code>0.02 V</code> through <code>655.34 V</code> in <code>0.02 V</code> steps; decode millivolts as <code>code * 20</code>.</p> <p>Match bytes <code>4</code>-<code>11</code> to the first 16 hex characters of the repeater public key shown by its advert or <code>get public.key</code>. This compact identifier is useful for association but is not authenticated and can be spoofed. An MQTT observer can upload the received raw packet to LetsMesh Analyzer <code>/packets</code>; its packet hex contains the direct-route header and path followed by this payload.</p> <p>Temperature payload (<code>0x11</code>, 61 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x11</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>48</code>) <code>7</code>-<code>18</code> 48 packed 2-bit temperature statuses <code>19</code>-<code>60</code> 48 packed 7-bit temperatures <p>Temperature status codes are <code>0</code> none, <code>1</code> value, <code>2</code> below range, and <code>3</code> above range. For status <code>1</code>, the 7-bit temperature is an exact whole-degree integer from <code>-50 C</code> through <code>+77 C</code>; decode it as <code>code - 50</code>. Low values use code <code>0</code>, and high values use code <code>127</code>. The separate status map is required because 7 bits contain exactly 128 codes, leaving no spare code for none, low, or high when the complete range is represented at 1 C resolution. No fractional temperature is stored or transmitted.</p> <p>Voltage payload (<code>0x12</code>, 55 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x12</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>48</code>) <code>7</code>-<code>54</code> 48 8-bit voltage codes <p>Voltage codes reserve <code>0</code> for no reading, <code>1</code> for below <code>1.88 V</code>, and <code>255</code> for above <code>4.40 V</code>. Codes <code>2</code>-<code>254</code> represent <code>1.88 V</code> through <code>4.40 V</code> in <code>0.01 V</code> steps; decode millivolts as <code>1880 + (code - 2) * 10</code>.</p> <p>External I2C voltage payload (<code>0x14</code>, 98 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x14</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>48</code>) <code>7</code> Cayenne LPP voltage channel <code>8</code>-<code>97</code> 48 packed 15-bit voltage codes <p>The codes have the same <code>0.02 V</code> through <code>655.34 V</code> meaning as <code>IVB1</code>.</p> <p>GPS payload (<code>0x13</code>, 101 bytes):</p> Bytes Meaning <code>0</code> Format/type <code>0x13</code> <code>1</code>-<code>4</code> First sample UTC epoch, unsigned 32-bit <code>5</code> Sample interval in minutes (<code>30</code>) <code>6</code> Sample count (<code>24</code>) <code>7</code>-<code>10</code> Page origin latitude in signed degrees times <code>10^7</code> <code>11</code>-<code>14</code> Page origin longitude in signed degrees times <code>10^7</code> <code>15</code> Origin sample index, or <code>255</code> when the page has no GPS fix <code>16</code> Flags; bit 0 means at least one differential was clipped <code>17</code>-<code>100</code> 24 records: signed 14-bit north then signed 14-bit east <p>GPS differentials use signed 14-bit two's-complement values at 10-meter resolution and are applied to the preceding decoded valid point. The origin sample begins at the header coordinates. A no-fix slot encodes <code>0,0</code> and does not advance the reference; a stationary valid fix also quantizes to <code>0,0</code>. When a page has no fixes, its origin is <code>0,0</code>, origin index is <code>255</code>, and all differentials are <code>0,0</code>. Values outside <code>-8192</code> through <code>8191</code> are clipped and set flag bit 0.</p>"},{"location":"cli_commands/#set-companion-tx-routing-per-contact-or-channel","title":"Set Companion TX routing per contact or channel","text":"<pre><code>set tx.user \"Alice Jones\" radio2\nget tx.user \"Alice Jones\"\nset tx.channel 0 both\nget tx.channel 0\nset tx.channel #wardriving radio\n</code></pre> <p>Both command families accept <code>auto</code>, <code>radio</code>, <code>radio2</code>, <code>both</code>, or <code>off</code>. <code>auto</code> uses the global crossing rules. Explicit choices override <code>radio2.cross</code>, but radio2 must still be enabled in <code>rxtx</code> to transmit there. <code>radio2</code> never falls back to the primary profile; <code>both</code> uses whichever of its selected profiles can transmit. Set a target back to <code>auto</code> to remove its override.</p> <p>Use an exact contact/channel name, a zero-based channel index, or <code>key:&lt;12-64 hex digits&gt;</code> for a unique contact public-key prefix. Duplicate names/prefixes are rejected. <code>get tx.user</code> and <code>get tx.channel</code> show override counts; queries with a target show its saved choice and current effective profile selection. Choices are saved with the contact/channel and work for phone-app and terminal messages. A contact's <code>off</code> setting also blocks its ACKs and addressed responses.</p> <p>See Companion routing details and examples for temporary profiles, persistence, and the traffic covered by each setting.</p>"},{"location":"cli_commands/#set-repeater-room-server-and-sensor-reply-profiles","title":"Set repeater, room-server, and sensor reply profiles","text":"<pre><code>get tx.reply\nset tx.reply both\nset tx.reply both force\nset tx.reply radio\nset tx.reply auto\n</code></pre> <p>Persistent choices: <code>auto</code>, <code>radio</code>, <code>radio2</code>, <code>both</code> (default), and <code>off</code>. Explicit choices override <code>radio2.cross</code> for local replies, including CLI, ACKs, telemetry, room subscription posts, and served LoRa OTA responses. Append <code>force</code> to <code>both</code> or <code>radio2</code> to permit reply TX on an active RX-only second profile. It never enables a disabled profile or ordinary forwarding. Omitting <code>force</code> removes that override. <code>off</code> suppresses remote replies too.</p> <p>See reply routing and OTA examples for temporary profiles, receive-only exceptions, and queued reply handling.</p>"},{"location":"cli_commands/#set-companion-display-rotation","title":"Set Companion display rotation","text":"<p>SSD1306 Full Companion builds support a persisted runtime orientation:</p> <pre><code>get display.rotation\nset display.rotation 0\nset display.rotation 90\nset display.rotation 180\nset display.rotation 270\n</code></pre> <p>The values are clockwise degrees. <code>0</code> clears the override and restores the board's compiled default. Unsupported display drivers return an error.</p>"},{"location":"cli_commands/#show-touchscreen-touch-areas","title":"Show touchscreen touch areas","text":"<p>All touchscreen Companion builds using the shared touch UI support temporary diagnostic outlines, including both SenseCAP Indicator rendering sizes:</p> <pre><code>get display.touch\nset display.touch on\nset display.touch off\n</code></pre> <p>The default is off at every boot. Enabling wakes the display without selecting anything. Dotted yellow borders mark the actual scaled tap targets; the area under a held finger turns green and returns to yellow on release. Disabling removes the borders on the next redraw. Pairing screens suppress the overlay while they consume navigation. This option does not change the font, touch calibration, navigation actions, or saved settings, and is not persisted.</p> <p>Use the text terminal or Companion framed CLI (<code>0x42</code>) through an available USB, BLE, or TCP connection. Non-touchscreen, missing-display, and legacy UI builds report <code>Error: touchscreen diagnostics unsupported</code>. No Indicator-only build flag is needed.</p>"},{"location":"cli_commands/#set-display-modes-and-timeouts","title":"Set display modes and timeouts","text":"<p>Display-equipped Companions, repeaters, room servers, and sensors have four saved settings. The WebConfig Display card exposes the same controls:</p> Setting CLI Default Battery mode <code>get/set display.mode</code> <code>button-pairing</code> on BLE Companions; <code>button</code> elsewhere Battery timeout, seconds <code>get/set display.timeout</code> <code>15</code> USB mode <code>get/set display.usb.mode</code> Same as battery mode USB timeout, seconds <code>get/set display.usb.timeout</code> <code>15</code> <p>Modes are <code>off</code>, <code>on</code>, <code>button</code>, <code>pairing</code>, <code>button-pairing</code>, and <code>automatic</code>. Pairing modes are available only on builds supporting BLE pairing.</p> <ul> <li><code>off</code>: stays dark, including boot and pairing.</li> <li><code>on</code>: stays on while the device is awake.</li> <li><code>button</code>: a physical button, keyboard/navigation input, or supported touch   wakes the display and restarts the timeout.</li> <li><code>pairing</code>: wakes only for an actual BLE PIN request, until pairing ends or   expires. The inactivity timeout does not shorten the pairing prompt.</li> <li><code>button-pairing</code>: combines the button and pairing behaviors.</li> <li><code>automatic</code>: shows startup briefly (at most four seconds), and wakes for   messages while the app is disconnected. An app connection blanks the screen;   buttons and pairing requests can still wake it. Disconnecting alone does not   wake it. Network traffic and screen redraws do not extend the timeout.</li> </ul> <p>Timeouts are whole seconds from <code>1</code> to <code>3600</code>. Use mode <code>on</code> for a permanent display rather than timeout <code>0</code>. The timeout is retained but unused in <code>off</code>, <code>on</code>, and <code>pairing</code> modes. Settings apply immediately, including while blanked; changing power source applies the other profile without carrying over a wake from the previous profile. Settings survive reboot and filesystem-preserving updates in <code>/display_prefs</code>; erasing the filesystem restores the defaults. An existing observer timeout that differs from its old 60-second default is migrated once to both power profiles; an old zero timeout becomes mode <code>on</code>.</p> <pre><code>set display.mode button-pairing\nset display.timeout 15\nset display.usb.mode on\nset display.usb.timeout 60\n</code></pre> <p>USB profile selection uses the board's external-power detector, with USB-host detection as a fallback. VBUS-capable boards detect chargers without a data connection. Heltec V4 R8 uses either a detected USB host or a calibrated battery voltage above 4.21 V. The voltage estimate is checked every five seconds and clears at 4.20 V or below; host detection takes effect immediately. This estimate can miss a charger while the battery is low, depends on ADC calibration, and cannot distinguish USB from solar charging. Other boards without a power detector may require a USB host to recognize USB power. Wi-Fi/MQTT connection or BLE pairing is not evidence of USB power. E-paper panels can retain their last image when powered off.</p>"},{"location":"cli_commands/#set-companion-inbox-behavior","title":"Set Companion inbox behavior","text":"<p>The shared Companion UI (including T114 and R8) defaults to History: the last 32 received text previews remain available on the radio after an app downloads them. Pending separately counts frames waiting for the app, including non-text frames. Downloading a frame clears it from Pending; it does not mean someone read it. The phone's delivery queue is independent of the 32-entry preview history and is never drained by reading on the radio.</p> <pre><code>get display.inbox\nset display.inbox history\nset display.inbox pending\nset display.inbox unread\n</code></pre> Mode Display behavior <code>history</code> (default) Shows HISTORY with the retained preview count, plus Pending. Downloaded previews remain browseable. <code>pending</code> Shows INBOX with the app queue count and limits the reader to previews still waiting for the app. Non-text frames count toward Pending but have no text preview. <code>unread</code> Shows UNREAD with the number of retained previews not yet displayed on the radio, plus Pending. Opening a preview on a lit display marks it read; app downloads do not. Read previews remain browseable. <p>All modes retain up to 32 previews internally; switching from <code>pending</code> back to <code>history</code> makes retained downloaded previews visible again. Evicted or rejected queue entries are not shown as pending. Previews and local read state are in RAM and reset on reboot. The mode applies immediately and survives reboot in <code>/display_prefs</code>; existing version-1 display settings load with <code>history</code> as the default. Legacy and tiny Companion UIs report <code>Error: inbox modes unsupported</code>.</p> <p>Incoming messages automatically open their preview only when no client is connected. While connected, new messages neither select another page nor move the preview being read; history stays accessible by button or touch. The home screen identifies connected USB and Bluetooth clients (or both), and TCP, Ethernet, or serial clients where supported. Actual BLE pairing prompts retain priority over connection status.</p>"},{"location":"cli_commands/#set-mqtt-observer-display-flip","title":"Set MQTT observer display flip","text":"<p>Supported observer displays, including the R8 OLED and ST7789 panels, can also be turned 180 degrees relative to their compiled orientation:</p> <pre><code>get display.flip\nset display.flip off\nset display.flip on\n</code></pre> <p><code>0</code> and <code>1</code> are accepted aliases for <code>off</code> and <code>on</code>. This is intentionally different from Full Companion <code>display.rotation</code>: observer <code>display.flip</code> is a relative 180-degree mounting choice and cannot switch between portrait and landscape. The value is harmless on an observer display driver that does not support flipping.</p> <p>Flip survives reboot and firmware updates that preserve the filesystem; erasing flash restores the <code>off</code> default. The boot log reports the saved flip state on display-enabled observer builds.</p>"},{"location":"cli_commands/#logging","title":"Logging","text":"<p>Builds compiled with <code>MESH_PACKET_LOGGING</code> emit one <code>RAW:</code> line for every received radio frame. Serial output uses backpressure: if a connected host temporarily stops reading, packet processing waits for USB transmit space instead of silently omitting the record. A disconnected host cannot retain an unbounded capture, so logging deployments should keep the reader attached and draining the serial port.</p> <p>Every valid received frame also emits the decoded RX summary, including signal, timing, hash, type, route, and payload information. Frames that cannot be decoded still emit their <code>RAW:</code> line. Transmitted packets emit the decoded TX summary.</p> <p>Ordinary non-OTA artifacts compile packet logging into the canonical image and control its live USB output at runtime; no separate <code>-logging-</code> artifact is emitted. Use the separately named <code>-ota-</code> artifact when LoRa OTA is required. A <code>-full-usb-wifi-ota-</code> artifact combines USB packet logging, direct WiFi MQTT, LoRa OTA, and the expanded FULL feature set. A <code>-full-logging-ota-</code> artifact is emitted only when that hardware/role has no matching WiFi MQTT environment.</p>"},{"location":"cli_commands/#control-live-usb-logging","title":"Control live USB logging","text":"<p>Search terms: serial logging, USB debug log, enable logging, disable logging, debug output.</p> <p>Usage:</p> <pre><code>get usb.logging\nset usb.logging on\nset usb.logging off\nset usb.logging on reboot\nset usb.logging off reboot\n</code></pre> <p>ESP32 1.17.1.5 USB logging procedure: disable device sleep before enabling the log stream, using separate text commands:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>Verify with <code>get powersaving</code> (expect <code>off</code>) and <code>get usb.logging</code> (expect <code>on</code>). Both settings are saved; disabling logging later does not restore power saving. This works around the released USB sleep bug. nRF52 does not need this ESP32 workaround.</p> <p>These commands are compiled into ordinary USB-loggable artifacts and every Full Companion. They control live USB debug and packet output. CommonCLI roles save the setting in <code>/com_prefs</code>, so it survives reboot; their first boot defaults to on. Full Companion and ordinary USB Companion start off on a fresh installation so diagnostics cannot corrupt framed traffic.</p> <p>On Full Companion these lines belong to its text terminal, not <code>meshcli</code>'s Binary <code>get/set</code> parameter namespace. Open interface <code>00</code>, send <code>+++MESHCORE-TERM-START</code>, and then issue the command. Running <code>meshcli ... get usb.logging</code> directly can instead return <code>Unknown var usb.logging</code> because that is a different protocol operation.</p> <p>nRF52 Full Companion defaults logging to off and enumerates only USB interface <code>00</code>, which carries Companion, terminal, and serial mOTA traffic. Enabling logging adds interface <code>02</code>, its dedicated plaintext logging port, on the next boot. Disabling it removes interface <code>02</code> on the next boot. A command without the optional <code>reboot</code> argument saves the choice and reports that a reboot is required when the USB interface count must change. The exact <code>set usb.logging on reboot</code> and <code>set usb.logging off reboot</code> forms save the choice, send their reply, and reboot one second later only when needed.</p> <p>On every ESP32 Full Companion, enter the USB text terminal and use <code>set usb.logging on</code> (preceded by <code>set powersaving off</code> on 1.17.1.5) to turn that TTY into a logging-repeater-style plaintext stream. Framed Binary Companion is unavailable on USB while logging is on. The TTY remains an input-capable CLI, so <code>set usb.logging off</code> works on the same TTY. After its reply, logging stops and the TTY remains in the normal ASCII terminal, just as it does after a fresh Full installation. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch it to Binary Companion. No reboot is needed because the USB interface count does not change.</p> <p>Turning USB logging off does not disable CLI replies. nRF52 keeps Companion frames active on interface <code>00</code>; ESP32 resumes the ordinary ASCII/Binary switcher after the logging terminal turns logging off. This setting does not change the node-storage capture controlled by <code>log start</code> and <code>log stop</code>.</p> <p>Companion, Repeater, Room Server, and Sensor builds with both MQTT and USB logging provide the same saved selector for both output paths:</p> <pre><code>get logging.output\nset logging.output off\nset logging.output usb\nset logging.output wifi\nset logging.output both\n</code></pre> <p><code>usb</code> emits <code>RAW:</code> packets for a USB-connected service such as meshcoretomqtt. <code>wifi</code> enables the direct MQTT bridge configured by the <code>wifi.*</code> and <code>mqtt.*</code> commands. <code>both</code> intentionally duplicates the radio stream to both consumers; do not point both consumers at the same broker unless the downstream setup deduplicates messages. Fresh unified Full infrastructure installs start in <code>both</code> mode; Full Companion starts with USB logging off. To change only MQTT, use <code>set mqtt.enabled on|off</code>; <code>get mqtt.enabled</code> checks the saved switch and <code>get mqtt.running</code> checks whether the MQTT service is running. Turning MQTT off preserves all broker slots and credentials.</p> <p>On 1.17.1.5 ESP32, run <code>set powersaving off</code> before selecting <code>set logging.output usb</code> or <code>set logging.output both</code>, since those modes enable USB logging. WiFi/MQTT-only logging does not need this workaround while the Repeater/Room Server MQTT bridge is running; the released code already blocks device sleep in that state. Check <code>get mqtt.running</code>, not only <code>get mqtt.enabled</code>. WiFi modem power saving is a separate setting.</p>"},{"location":"cli_commands/#begin-capture-of-rx-log-to-node-storage","title":"Begin capture of rx log to node storage","text":"<p>Search terms: save logs, record received packets, RX logging, stored packet log.</p> <p>Usage: <code>log start</code></p>"},{"location":"cli_commands/#end-capture-of-rx-log-to-node-storage","title":"End capture of rx log to node storage","text":"<p>Usage: <code>log stop</code></p>"},{"location":"cli_commands/#erase-captured-log","title":"Erase captured log","text":"<p>Usage: <code>log erase</code></p> <p></p>"},{"location":"cli_commands/#print-the-captured-log-to-the-requesting-terminal","title":"Print the captured log to the requesting terminal","text":"<p>Usage: <code>log</code></p> <p>Local connection only: USB, direct network CLI, or Companion binary command <code>0x42</code> where the role supports the command; unavailable over LoRa.</p>"},{"location":"cli_commands/#info","title":"Info","text":""},{"location":"cli_commands/#get-the-version","title":"Get the Version","text":"<p>Usage: <code>ver</code></p> <p>On Full Companion, the Binary device-info frame retains its legacy fixed-width version field. Use <code>version</code> in the text terminal, or send <code>version</code> through Binary protocol command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>), to read the complete untruncated firmware string together with protocol and build date.</p>"},{"location":"cli_commands/#show-the-hardware-name","title":"Show the hardware name","text":"<p>Usage: <code>board</code></p>"},{"location":"cli_commands/#show-the-storage-layout","title":"Show the storage layout","text":"<p>Usage: <code>get storage.layout</code></p> <p>Reports a compact, read-only summary of the storage compiled into the running firmware:</p> <ul> <li>ESP32 reports the detected internal flash size and the live partition table.   Partition addresses after <code>@</code> are hexadecimal, sizes after <code>+</code> are KiB, and   <code>*</code> marks the running application. <code>...</code> means later entries did not fit in   the CLI reply.</li> <li>nRF52 reports the physical internal flash size, linked application range,   InternalFS range, and any configured external store. Raw QSPI OTA storage   includes its detected size and JEDEC ID; SD storage includes total, used, and   free space.</li> <li>RP2040 and STM32 report their fixed internal flash and filesystem geometry.</li> </ul> <p>The command does not write, format, or resize storage. A raw-QSPI or SD build may briefly probe, wake, or mount its configured external storage to read its capacity. Remote use follows the existing administrator-command permissions.</p>"},{"location":"cli_commands/#configuration","title":"Configuration","text":""},{"location":"cli_commands/#radio","title":"Radio","text":""},{"location":"cli_commands/#view-or-change-this-nodes-radio-parameters","title":"View or change this node's radio parameters","text":"<p>Usage: - <code>get radio</code> - <code>set radio &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;</code></p> <p>Parameters: - <code>freq</code>: Frequency in MHz - <code>bw</code>: Bandwidth in kHz. Most targets allow <code>7.8</code>, <code>10.4</code>, <code>15.6</code>, <code>20.8</code>, <code>31.25</code>, <code>41.7</code>, <code>62.5</code>, <code>125</code>, <code>250</code>, <code>500</code>. LR1110 targets allow <code>62.5</code>, <code>125</code>, <code>250</code>, <code>500</code>. - <code>sf</code>: Spreading factor (5-12) - <code>cr</code>: Coding rate (5-8)</p> <p>Set by build flag: <code>LORA_FREQ</code>, <code>LORA_BW</code>, <code>LORA_SF</code>, <code>LORA_CR</code></p> <p>Default: <code>869.618,62.5,8,5</code></p> <p>Note: Requires reboot to apply. If RXPS is enabled and the saved minimum level/preamble cannot safely cover the new radio timing, the command reply reports the effective level and preamble, or <code>RXPS continuous-fast</code> when no level through 10 is safe. Slower settings recalculate from the saved RXPS minimum and return to it exactly when it is safe.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-transmit-power","title":"View or change this node's transmit power","text":"<p>Search terms: tx power, transmit strength, radio output power, dBm.</p> <p>Usage: - <code>get tx</code> - <code>set tx &lt;dbm&gt;</code></p> <p>Parameters: - <code>dbm</code>: Requested radio-chip power in dBm. The valid range depends on the   radio family, selected PA path, and any board-specific external-PA limit.</p> <p>Set by build flag: <code>LORA_TX_POWER</code></p> <p>Default: Varies by board</p> <p>Notes: This setting only controls the power level of the LoRa chip. Some nodes have an additional power amplifier stage which increases the total output. Refer to the node's manual for the correct setting to use. Setting a value too high may violate the laws in your country.</p> <p>The command strictly rejects malformed values and saves the new preference only after the active radio driver accepts it. On LR2021, the chip range is <code>-9</code> to <code>22</code> dBm below 1500 MHz and <code>-19</code> to <code>12</code> dBm above 1500 MHz. A lower board-specific external-PA limit still takes precedence. A saved profile is clamped to the applicable limit when its frequency changes; temporary radio settings use a safe effective power without replacing the saved preference.</p>"},{"location":"cli_commands/#change-the-radio-parameters-for-a-set-duration","title":"Change the radio parameters for a set duration","text":"<p>Usage:  - <code>tempradio &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;timeout_mins&gt;</code> - <code>normalradio</code></p> <p>Parameters: - <code>freq</code>: Frequency in MHz (150-2500) - <code>bw</code>: Bandwidth in kHz (same allowed values as <code>set radio</code>) - <code>sf</code>: Spreading factor (5-12) - <code>cr</code>: Coding rate (5-8) - <code>timeout_mins</code>: Duration in minutes (must be &gt; 0)</p> <p>Notes: - <code>tempradio</code> is not saved to preferences and clears on reboot. - On repeaters, remote <code>tempradio</code> and <code>normalradio</code> wait for their exact reply   copies to finish, with at least one transmitted. This also covers the <code>set</code>   alias, case-insensitive verbs, and client correlation prefixes. Failed replies   cancel an unconfirmed temporary handoff; hard lease expiry still takes priority. - <code>normalradio</code> cancels pending and active temporary-radio windows, then   restores the saved radio tuple after its CLI reply has drained on the   current channel. Permanent <code>radioat</code> entries are not removed. - On repeaters, the reply includes total minutes plus <code>NdNhNm</code> (days, hours,   minutes) and the watchdog policy for that session. For example:</p> <pre><code>OK - temp params for 1440 mins (1d0h0m); rx.watchdog=12hours\nOK - temp params for 3075 mins (2d3h15m); rx.watchdog=12hours\nOK - temp params for 180 mins (0d3h0m); rx.watchdog=off (temp&lt;12hours)\n</code></pre> <p>Repeater timing overrides apply only while a temporary window is running:</p> Temporary duration No-RX reboot watchdog Flood advert interval Direct/local advert interval Up to and including 3 hours Off Saved normal interval 1 hour More than 3, less than 12 hours Off 3 hours 1 hour 12 hours or longer 12 hours 3 hours 1 hour <p>The duration is the requested window length, not the decreasing time remaining. The first temporary adverts are scheduled from successful radio activation; hourly local adverts still run when a flood advert is also due. <code>get advert.interval</code> and <code>get flood.advert.interval</code> report the effective intervals. The web configuration form continues to show and edit the saved normal advert settings. These include any changes made during a temporary session. Expiry, cancellation, reboot, or power loss removes the temporary overrides. Normal mode uses the saved advert intervals and the 24-hour watchdog policy. An explicitly saved normal-mode <code>rx.watchdog off</code> remains off outside temporary sessions.</p>"},{"location":"cli_commands/#schedule-radio-parameter-changes","title":"Schedule radio parameter changes","text":"<p>Usage: - <code>set radioat &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;start_time&gt;</code> - <code>get radioat [n|all]</code> - <code>del radioat [n|all]</code> - <code>set tempradioat &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;start_time&gt;,&lt;end_time&gt;</code> - <code>get tempradioat [n|all]</code> - <code>del tempradioat [n|all]</code></p> <p>Parameters: - <code>freq</code>: Frequency in MHz (150-2500) - <code>bw</code>: Bandwidth in kHz (same allowed values as <code>set radio</code>) - <code>sf</code>: Spreading factor (5-12) - <code>cr</code>: Coding rate (5-8) - <code>start_time</code>: UTC Unix epoch seconds, or <code>+N</code> for N whole minutes from now - <code>end_time</code>: UTC Unix epoch seconds, or <code>+N</code> for N whole minutes from now - <code>n</code>: Scheduled entry number from <code>get radioat</code> or <code>get tempradioat</code></p> <p>Notes: - Both relative endpoints use the same command-time snapshot of the node clock.   For example, <code>set tempradioat 910.5,500,8,5,+5,+15</code> starts in 5 minutes   and reverts in 15 minutes (10 minutes active). <code>set radioat 910.5,500,8,5,+5</code>   schedules a saved change in 5 minutes. Bare numbers remain absolute timestamps;   absolute and relative endpoints can be mixed. Relative offsets must be positive.   The existing scheduler and clock behavior are unchanged. - <code>get radioat</code> and <code>get tempradioat</code> list all entries when <code>n</code> is omitted. - <code>del radioat</code> and <code>del tempradioat</code> delete all entries when <code>n</code> is omitted. - Each queue supports 3 entries. Scheduled entries are not saved across reboot. - <code>radioat</code> saves the new radio preferences when it fires. <code>tempradioat</code> applies temporarily, then reverts to the saved radio preferences. - <code>tempradioat</code> uses the repeater timing table above, with duration calculated   from <code>end_time - start_time</code>. Its acceptance reply includes total minutes, <code>NdNhNm</code>,   and the planned <code>rx.watchdog</code> setting. Queuing a future entry does not change   the running watchdog or advert intervals; the overrides start only after   the temporary radio parameters are successfully applied. If restoration   needs retries after expiry, the timing overrides still end with the window. - A successful scheduling reply notes any RXPS effective-level/preamble change   required by the scheduled tuple. <code>RXPS continuous-fast</code> means the tuple is   accepted but will use continuous receive because no safe duty-cycle level is   available. Returning to slower settings recalculates from the saved RXPS   minimum.</p> <p>With the measured RXPS model and the default 1600 us TCXO startup delay (2600 us total transition), a requested minimum level 1 gives:</p> SF BW (kHz) Wire preamble Effective timing preamble Effective RXPS level RX / sleep 7 500 32 32 2 5594 / 3022 us 6 250 32 32 2 5844 / 3022 us 5 125 32 32 2 5844 / 3022 us 5 250 64 64 1 3829 / 5100 us 6 500 64 64 1 3829 / 5100 us 5 500 128 128 1 2563 / 6647 us 5 62.5 32 16 6 11922 / 2975 us <p>These values include the actual transmitted preamble, explicit header, and a one-symbol timer margin. SF5/SF6 need two more sync symbols than SF7, so their receive windows differ even when symbol duration and sleep time match.</p> <p>The wire preamble remains compatible with the existing Cascade convention: 32 symbols at SF5-SF8, extended to 64 for SF5/BW250 and SF6/BW500, or 128 for SF5/BW500; SF9-SF12 use 16. Local RXPS settings and oscillator delays never change the sender's preamble choice. The receiver may use a shorter catch assumption, but its header timeout covers the full transmitted preamble.</p> <p>Automatic adjustment stops at guarded level 8. If no guarded timing fits, the radio receives continuously until the tuple changes. For example, a board configured with the previous 5000 us TCXO delay uses continuous RX at SF7/BW500; it cannot fit the new guard within that tuple's 32-symbol wire preamble. Experimental levels 9 and 10 require an explicit selection.</p> <p>Earlier firmware passed 16/16 packets in each direction between Heltec V4 and WisMesh Tag at SF5/BW250/64 and SF5/BW500/128, CR5, 909.950 MHz. That result established the existing wire-preamble convention; it does not validate the new timing model. All senders to an RXPS receiver must use a compatible wire preamble. LoRa OTA treats v1.17.1.5 as that capability boundary.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-frequency","title":"View or change this node's frequency","text":"<p>Search terms: radio frequency, LoRa frequency, MHz.</p> <p>Usage: - <code>get freq</code> - <code>set freq &lt;frequency&gt;</code></p> <p>Parameters: - <code>frequency</code>: Frequency in MHz</p> <p>Default: <code>869.618</code></p> <p>Note: Requires reboot to apply</p> <p>Connections: USB, browser/TCP/Ethernet CLI, Companion binary command <code>0x42</code> (USB/BLE/TCP), and authorized LoRa CLI. <code>set freq</code> saves the frequency; bandwidth, spreading factor, and coding rate stay as configured. Infrastructure roles also clamp transmit power to the board's limit for that frequency. Like <code>set radio</code>, it requires permission to configure the destination node.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-rx-boosted-gain-mode-sx12xx-and-lr1110-v1141","title":"View or change this node's rx boosted gain mode (SX12xx and LR1110, v1.14.1+)","text":"<p>Search terms: RX boost, receive gain, receiver sensitivity, boosted reception.</p> <p>Usage: - <code>get radio.rxgain</code> - <code>set radio.rxgain &lt;state&gt;</code></p> <p>Parameters:   - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: Target-specific. Most SX1262 and LR1110 targets default to <code>on</code>; Station G2/G3 targets default to <code>off</code>.</p> <p>Notes: - The saved setting is applied immediately and persists across reboots. - Periodic AGC resets restore the saved runtime setting; they do not replace it   with the target's compile-time default. - Existing installations retain their previously saved value after an upgrade.</p>"},{"location":"cli_commands/#view-or-change-rx-duty-cycle-power-saving","title":"View or change RX duty-cycle power saving","text":"<p>Search terms: RX power saving, receiver sleep, radio power saving, RXPS.</p> <p>Usage: - <code>get radio.rxps</code> - <code>get radio.rxps.config</code> - <code>get radio.rxps.rfrx_disabled</code> - <code>get rxps.wd</code> - <code>set radio.rxps.rfrx_disabled &lt;state&gt;</code> - <code>set radio.rxps off</code> - <code>set radio.rxps on</code> - <code>set radio.rxps conservative</code> - <code>set radio.rxps balanced</code> - <code>set radio.rxps max</code> - <code>set radio.rxps max preamble &lt;16|32&gt;</code> - <code>set radio.rxps overdrive</code> - <code>set radio.rxps overdrive preamble &lt;16|32&gt;</code> - <code>set radio.rxps riskyWorkingMax</code> - <code>set radio.rxps riskyWorkingMax preamble &lt;16|32&gt;</code> - <code>set radio.rxps &lt;1-10&gt;</code> - <code>set radio.rxps level &lt;1-10&gt;</code> - <code>set radio.rxps level &lt;1-10&gt; preamble &lt;16|32&gt;</code> - <code>set radio.rxps &lt;rx_us&gt; &lt;sleep_us&gt;</code></p> <p>Parameters: - <code>rx_us</code>, <code>sleep_us</code>: Receive and sleep durations in microseconds (<code>1000</code>-<code>30000000</code>). - <code>level</code>: Guarded levels <code>1</code>-<code>8</code>, followed by experimental levels <code>9</code> and <code>10</code>. Higher guarded levels allow more sleep. - <code>preamble</code>: RXPS timing assumption in symbols; <code>16</code> or <code>32</code>. This does not   change the radio's actual transmitted preamble. - <code>state</code>: <code>on</code> or <code>off</code>.</p> <p>Notes: - <code>get rxps.wd</code> reports the radio watchdogs' soft and hard recovery counts.   See receive calibration and recovery for   noise sampling, CAD handling, and the continuous-RX mode check. - <code>get radio.rxps.config</code> adds the persisted level and preamble assumption to   the on/off and timing values. Deployment tools use it to restore a   level-based preference without converting it to fixed manual timings. - <code>radio.rxps.rfrx_disabled</code> is a runtime-only diagnostic setting and resets to <code>off</code> after reboot. - Its default <code>off</code> state keeps the host-controlled SX1262 receive path enabled during RX duty-cycle mode. Setting it to <code>on</code> reproduces the old missing-RF_RX behavior and can significantly reduce receive sensitivity, making remote commands harder to receive. - <code>radio.rxps.rfrx_disabled</code> is supported only on SX1262 targets with a host-controlled RX enable pin. - <code>on</code> and <code>conservative</code> select level <code>3</code>, <code>balanced</code> selects level <code>6</code>, and   <code>max</code> selects level <code>8</code>; each named profile assumes a 16-symbol preamble. - The guarded catch ladders for levels 1-8 are <code>15,14,13,12,11,10,9,8</code> symbols   for preamble 16 and <code>24,20,16,14,12,10,9,8</code> for preamble 32 or longer.   Generated sleep leaves another 0.2 symbols of margin. The receive timer covers   the actual wire preamble, sync, explicit header, and one extra symbol. - <code>overdrive</code> selects level <code>9</code>; <code>riskyWorkingMax</code> selects level <code>10</code>. Both   operate outside the guarded timer condition. Upstream bench measurements   found packet loss at level 10; neither profile is a general guarantee of   reliable delivery. They are never selected by automatic level adjustment. - Named experimental profiles accept <code>preamble 32</code>; numeric levels keep the   existing automatic-preamble selection. Manual timings bypass the level model. - <code>MC_TCXO_DELAY_US</code> defaults to 1600 us. Initialization applies it and checks   TCXO/calibration errors. A board can override it for its oscillator. - Fresh Cascade-profile builds start with RXPS on at level <code>8</code> and a 16-symbol preamble. Saved operator settings still take precedence after an upgrade. - Level-based settings automatically recalculate their timings when the spreading factor or bandwidth changes. Custom <code>&lt;rx_us&gt; &lt;sleep_us&gt;</code> timings remain fixed. - <code>get radio.rxps</code> keeps the legacy on/off, RX, and sleep reply. The new   <code>get radio.rxps.config</code> reply adds the saved level and preamble assumption.   Radio-change replies and the Full Companion terminal status report any   effective level/preamble adjustment. Effective preamble 64 or 128 appears   only when the active tuple's physical wire preamble has that length. - The selected mode is applied immediately, persisted, and restored after reboot.</p>"},{"location":"cli_commands/#view-or-change-the-lora-fem-receive-path-gain-state-on-supported-boards","title":"View or change the LoRa FEM receive-path gain state on supported boards","text":"<p>Usage: - <code>get radio.fem.rxgain</code> - <code>set radio.fem.rxgain &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Notes: - This controls the external LoRa FEM receive-path LNA where the board supports it. - This is separate from <code>radio.rxgain</code>, which controls the radio chip receive gain mode.</p>"},{"location":"cli_commands/#view-or-change-the-lora-fem-transmit-path-gain-state-on-supported-boards","title":"View or change the LoRa FEM transmit-path gain state on supported boards","text":"<p>Usage: - <code>get radio.fem.txgain</code> - <code>set radio.fem.txgain &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Notes: - This controls a software-selectable external LoRa FEM transmit gain where the board supports it. - On Station G3, remove the PA PL1 jumper to allow software control. <code>on</code> selects PA PL1 high/short and <code>off</code> selects PA PL1 low/open. The PA PL2 hardware jumper determines whether this switches between power levels 1/3 or 2/4. - Select an operating level and SX1262 transmit power that comply with local RF limits and the Station G3 power-supply requirements. - The setting is saved immediately, but on Station G3 the level is applied to the hardware at the start of the next transmit, so that the PA supply rail is never re-targeted while the PA is being driven. <code>get</code> reports the configured state, which may lead the hardware until the node next transmits.</p>"},{"location":"cli_commands/#system","title":"System","text":""},{"location":"cli_commands/#view-or-change-this-nodes-name","title":"View or change this node's name","text":"<p>Usage: - <code>get name</code> - <code>set name &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Node name</p> <p>Set by build flag: <code>ADVERT_NAME</code></p> <p>Default: Varies by board</p> <p>Note: Advertised names can use up to 23 bytes when location is included and 31 bytes otherwise. Emoji and Unicode characters may take more than one byte. Names that exceed the available advert space are truncated at a valid UTF-8 code point boundary.</p>"},{"location":"cli_commands/#turn-wifi-esp-now-or-all-24-ghz-services-on-or-off","title":"Turn WiFi, ESP-NOW, or all 2.4 GHz services on or off","text":"<pre><code>get wifi\nset wifi off\nset wifi on\nget espnow\nset espnow off\nset espnow on\nget 2.4ghz\nset 2.4ghz off\nset 2.4ghz on\nset 2.4ghz on all\n</code></pre> Control Effect <code>wifi</code> Infrastructure WiFi, setup AP, TCP/WebUI, and WiFi MQTT services. ESP-NOW remains available. <code>espnow</code> The ESP-NOW bridge or primary ESP-NOW mesh transport in this build. Infrastructure WiFi remains available. <code>2.4ghz off</code> Stop WiFi, Bluetooth, and ESP-NOW; remember which were enabled. LoRa and wired transports remain available. <code>2.4ghz on</code> Restore the states saved by the first <code>off</code>. Repeated <code>off</code> preserves that snapshot. With no previous <code>off</code>, keep the current states. <code>2.4ghz on all</code> Enable every service available in this build and boot. <code>2.4ghz on force</code> is an alias. <p>These commands work in Companion, repeater, and room-server firmware where the services are available. Changes last until reboot; saved WiFi credentials, Bluetooth preferences, and bridge settings stay intact. <code>get 2.4ghz</code> lists each service as <code>on</code>, <code>off</code>, or <code>unavailable</code>. An nRF52 Companion controls its Bluetooth and reports WiFi/ESP-NOW as unavailable. Exclusive WiFi/Bluetooth builds retain their boot transport restriction; <code>on all</code> cannot reclaim a released Bluetooth stack.</p> <p>An <code>off</code> command requires a management connection that will survive it. Bluetooth can provide the fallback for <code>wifi off</code>; USB, Ethernet, or a CLI request over LoRa can provide it for <code>2.4ghz off</code>. WiFi association, a listening socket, and USB power alone do not count. On USB hardware without an observable open-client session, send the command through USB itself. To bypass the guard:</p> <pre><code>set wifi off force\nset espnow off force\nset 2.4ghz off force\n</code></pre> <p>Shutdown starts after the reply has had time to drain (normally 250 ms, up to two seconds for pending transport I/O). Network services stop before the shared WiFi driver. A normal shutdown is cancelled if its fallback connection disappears before it starts. The <code>get</code> commands report pending changes and startup/teardown failures. After <code>2.4ghz off</code>, use <code>2.4ghz on</code> or <code>on all</code> before enabling an individual service. The <code>all</code>/<code>force</code> suffix on on applies only to <code>2.4ghz</code>.</p> <p>WiFi and ESP-NOW share one hardware channel. A running ESP-NOW bridge pins setup and station connections to <code>bridge.channel</code>; starting the bridge alongside an existing WiFi connection requires that same channel. A mismatch reports a failed start and preserves the WiFi connection.</p>"},{"location":"cli_commands/#turn-bluetooth-on-or-off-companion","title":"Turn Bluetooth on or off (Companion)","text":"<pre><code>get bluetooth\nset bluetooth off\nset bluetooth off force\nset bluetooth on\n</code></pre> <p><code>get ble</code> and <code>set ble ...</code> are aliases. This controls the running Bluetooth service on ESP32 and nRF52 Companions: <code>off</code> stops advertising and disconnects Bluetooth clients; <code>on</code> enables it again. The change lasts until reboot.</p> <p>Plain <code>off</code> requires another active management connection. A connected USB terminal or binary client, TCP client, or browser terminal can provide that connection. WiFi association, a listening server, and USB power alone do not. On USB hardware without an observable open-host session (HWCDC or a UART bridge), issue the command through that USB client so the request itself proves it is active.</p> <p>Append <code>force</code> to <code>off</code> to permit disconnecting the only active connection. Use USB, another management transport, or reboot to regain access afterward. <code>force</code> is accepted only as the final argument to <code>off</code>.</p> <p>Commands sent through Bluetooth allow its reply to drain before shutdown (normally 250 ms, at most two seconds). <code>get bluetooth</code> shows <code>off pending</code> during that wait. A normal shutdown is cancelled if the other management connection disappears before it applies; <code>force</code> bypasses that check too.</p> <p>Bluetooth must be available in the current build and boot transport mode. An exclusive-WiFi boot still requires <code>set companion.transport ble</code> and a reboot before Bluetooth can be enabled.</p>"},{"location":"cli_commands/#view-or-change-the-independent-bluetooth-name-companion","title":"View or change the independent Bluetooth name (Companion)","text":"<p>Usage:</p> <ul> <li><code>get bluetooth.name</code></li> <li><code>set bluetooth.name &lt;name|default&gt;</code></li> </ul> <p><code>get ble.name</code> and <code>set ble.name ...</code> are accepted aliases. This command is specific to Companion firmware. The default is <code>MeshCore-&lt;advert name&gt;</code>; <code>default</code> (or <code>clear</code>) removes a custom override. Names are limited to 31 valid UTF-8 bytes without control characters and take effect after reboot.</p> <p>A binary Companion client should carry the same text in command <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>), which works over USB, BLE, or TCP without entering USB terminal mode. See Companion radio binary protocol for the frame and reply format.</p>"},{"location":"cli_commands/#view-or-change-the-bluetooth-address-ble-companion","title":"View or change the Bluetooth address (BLE Companion)","text":"<p>Usage:</p> <ul> <li><code>get bluetooth.mac</code></li> <li><code>set bluetooth.mac &lt;address|random|random-every-boot|random-after-connect|default&gt;</code></li> </ul> <p><code>get ble.mac</code> and <code>set ble.mac ...</code> are accepted aliases. The setting is available on every Companion build that includes Bluetooth.</p> Value Result after reboot <code>C2:11:22:33:44:55</code> Save and use that custom address. <code>random</code> Generate one random address now, save it, and reuse it on later boots. <code>random-every-boot</code> Generate a new address once at each boot. <code>random everyboot</code> is also accepted. <code>random-after-connect</code> Keep one random address through unused boots. After an authenticated connection, arm a new address for the next boot. <code>default</code> or <code>clear</code> Remove the override and use the chipset's factory Bluetooth address. <p>A custom value must be a valid BLE random-static address in <code>XX:XX:XX:XX:XX:XX</code> form. Its first byte must be from <code>C0</code> through <code>FF</code>, and you are responsible for keeping addresses unique. Hyphens are also accepted on input; status output uses uppercase colons.</p> <p>Every change requires a reboot and invalidates the phone's previous view of the device. Forget the old device entry and pair again. <code>random-every-boot</code> also clears the Companion's saved peer bonds during each startup, so pairing and PIN entry are expected again after every reboot.</p> <p><code>random-after-connect</code> keeps the same address across any number of reboots when nobody successfully authenticated. As soon as an authenticated BLE connection succeeds, the next boot rotates the address and clears stale bonds. The marker is saved while connected, so a normal reboot, power switch, or battery pull after that connection all produce the same next-boot rotation.</p> <p>The address setting does not enable or disable stealth. Use the separate <code>bluetooth.stealth</code> flag below. <code>default</code> changes only the address policy.</p>"},{"location":"cli_commands/#view-or-change-bluetooth-stealth-ble-companion","title":"View or change Bluetooth stealth (BLE Companion)","text":"<pre><code>get bluetooth.stealth\nset bluetooth.stealth on\nset bluetooth.stealth off\n</code></pre> <p><code>get ble.stealth</code> and <code>set ble.stealth on|off</code> are short aliases. This flag defaults to <code>off</code> and is independent of the Bluetooth address policy. Enabling or disabling it keeps the configured custom/random/factory address policy unchanged and requires a reboot. Repeating <code>on</code> keeps an existing stealth pairing; repeating <code>off</code> does not alter address settings.</p> <p>For a custom address with stealth:</p> <pre><code>set bluetooth.mac C2:11:22:33:44:55\nset bluetooth.stealth on\nreboot\n</code></pre> <p>Use <code>set bluetooth.mac random</code> instead of the first line for one saved random address. Both combinations keep their address and bond across later boots. Rotating policies still rotate: <code>random-every-boot</code> reopens pairing at every boot, while <code>random-after-connect</code> reopens it on the first boot after an authenticated connection. Stealth stays enabled; each new address begins with a fresh pairing window so it cannot get hidden behind an unusable bond.</p> <p>With stealth on, the node is normally discoverable until the first authenticated pairing. After that, nRF52 uses directed advertising to the saved peer. ESP32 uses a minimal unnamed advertisement and a controller allowlist because its common Arduino BLE API does not expose the directed-advertising peer field. Both reject connection and scan requests from other peers. BLE cannot be completely radio silent and still accept a connection, so a passive radio sniffer may still observe packets. To deliberately clear the saved stealth peer, send <code>set bluetooth.stealth off</code>, then <code>set bluetooth.stealth on</code>, then reboot over USB or an existing authenticated connection. To leave stealth, set it <code>off</code> and reboot. If the saved node-side bond is lost, recovery reopens pairing. The former <code>set bluetooth.mac stealth</code> command is no longer accepted.</p> <p>This changes only the running MeshCore Companion application. On nRF52, the OTAFIX bootloader still uses its own address, which is visible only while the board is in BLE DFU/recovery mode. USB and LoRa updates are unaffected. Bluetooth update tools must follow that separate bootloader address after the handoff; they must not assume that a custom application address remains the DFU address. See the hardware observations for the tested XIAO handoff and host-cache caveats.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-latitude","title":"View or change this node's latitude","text":"<p>Usage: - <code>get lat</code> - <code>set lat &lt;degrees&gt;</code></p> <p>Set by build flag: <code>ADVERT_LAT</code></p> <p>Default: <code>0</code></p> <p>Parameters: - <code>degrees</code>: Latitude in degrees</p>"},{"location":"cli_commands/#view-or-change-this-nodes-longitude","title":"View or change this node's longitude","text":"<p>Usage: - <code>get lon</code> - <code>set lon &lt;degrees&gt;</code></p> <p>Set by build flag: <code>ADVERT_LON</code></p> <p>Default: <code>0</code></p> <p>Parameters: - <code>degrees</code>: Longitude in degrees</p>"},{"location":"cli_commands/#view-or-change-this-nodes-identity-private-key","title":"View or change this node's identity (Private Key)","text":"<p>Usage: - <code>get prv.key</code> - <code>set prv.key &lt;private_key&gt;</code></p> <p>Parameters: - <code>private_key</code>: Private key in hex format (64 hex characters)</p> <p>Local connection only: <code>get prv.key</code>. Companion also requires <code>ENABLE_PRIVATE_KEY_EXPORT=1</code>; use binary command <code>0x42</code> or the text terminal. Infrastructure <code>set prv.key</code> retains its administrator access rules.</p> <p>Note: Requires reboot to take effect after setting</p> <p></p>"},{"location":"cli_commands/#view-or-change-this-nodes-admin-password","title":"View or change this node's admin password","text":"<p>Usage: - <code>get password</code> - <code>password &lt;new_password&gt;</code></p> <p>Parameters: - <code>new_password</code>: New admin password</p> <p>Set by build flag: <code>ADMIN_PASSWORD</code></p> <p>Default: <code>password</code></p> <p><code>get password</code> returns the current admin password only on a local connection: USB, Ethernet, or the authenticated LAN browser CLI. It is rejected over LoRa. Companion has no local admin password and reports that explicitly, including through binary command <code>0x42</code>; this command does not report the Bluetooth PIN.</p> <p>Note: The password setter replies with confirmation.</p> <p>Note: Any node using this password will be added to the admin ACL list.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-guest-password","title":"View or change this node's guest password","text":"<p>Usage: - <code>get guest.password</code> - <code>set guest.password &lt;password&gt;</code></p> <p>Parameters: - <code>password</code>: Guest password</p> <p>Set by build flag: <code>ROOM_PASSWORD</code> (Room Server only)</p> <p>Default: <code>&lt;blank&gt;</code></p>"},{"location":"cli_commands/#view-or-change-this-nodes-owner-info","title":"View or change this node's owner info","text":"<p>Usage: - <code>get owner.info</code> - <code>set owner.info &lt;text&gt;</code></p> <p>Parameters: - <code>text</code>: Owner information text</p> <p>Default: <code>&lt;blank&gt;</code></p> <p>Note: <code>|</code> characters are translated to newlines</p> <p>Note: Requires firmware 1.12+</p>"},{"location":"cli_commands/#fine-tune-the-battery-reading","title":"Fine-tune the battery reading","text":"<p>Usage: - <code>get adc.multiplier</code> - <code>set adc.multiplier &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: ADC multiplier (0.0-10.0)</p> <p>Default: <code>0.0</code> (value defined by board)</p> <p>Note: Returns \"Error: unsupported by this board\" if hardware doesn't support it</p>"},{"location":"cli_commands/#send-a-repeater-flood-text","title":"Send a repeater flood text","text":"<p>Usage: - <code>send text.flood &lt;message&gt;</code></p> <p>Parameters: - <code>message</code>: Text to send to the shared <code>#repeaters</code> flood channel, prefixed with this node's name. Any <code>:</code> in the node name is sent as <code>;</code> so the prefix delimiter stays unambiguous.</p> <p>Example:</p> <pre><code>send text.flood checking ridge link\n</code></pre>"},{"location":"cli_commands/#view-or-change-battery-alert-state","title":"View or change battery alert state","text":"<p>Usage: - <code>get battery.alert</code> - <code>get battery.alert.region</code> - <code>set battery.alert on [region]</code> - <code>set battery.alert off</code></p> <p>Parameters: - <code>region</code>: Optional named region scope. When omitted, the repeater selects the single deepest (most narrow) named region in the configured hierarchy. If multiple regions tie for deepest, specify one explicitly.</p> <p>Defaults: - <code>battery.alert</code>: <code>off</code> - <code>battery.alert.region</code>: <code>&lt;unset&gt;</code></p> <p>Notes: - Enabling fails until at least one usable named region is defined. Alerts are never sent as unscoped floods. If the selected region is later removed, alerts stop until battery alerts are enabled again with a valid region. - Region hierarchy edits are not persistent until <code>region save</code> is run. After <code>region def west pnw wa w-wa sea</code>, run <code>region save</code> before enabling the alert if the hierarchy must survive a reboot. - A region must have a usable transport key. Public named regions derive one automatically; a private region without an available key is rejected. - The first alert is suppressed until the repeater has been up for at least 30 minutes. After that, the repeater checks every 30 minutes and sends low-battery warnings to the <code>#repeaters</code> channel in the selected region. - Once an alert finishes transmitting, another battery alert is suppressed for at least 12 hours. A queue rejection, stale-queue drop, or radio send failure does not start the cooldown. Battery recovery or toggling alerts off and back on does not bypass a completed alert's cooldown during the same boot. - With <code>region def west pnw wa w-wa sea</code>, <code>set battery.alert on</code> selects <code>sea</code>; <code>set battery.alert on w-wa</code> overrides that default. - <code>get battery.alert.region</code> returns the selected scope, for example <code>&gt; sea</code>. - The battery check never requests a wake earlier than its 30-minute deadline. If the normal loop is already awake when that deadline has elapsed, the check is effectively free of an additional wake. Time in light/event sleep counts toward the startup delay, and a pending alert keeps the repeater awake until the packet is handled.</p>"},{"location":"cli_commands/#view-or-change-battery-alert-thresholds","title":"View or change battery alert thresholds","text":"<p>Usage: - <code>get battery.alert.low</code> - <code>set battery.alert.low &lt;1-100&gt;</code> - <code>get battery.alert.critical</code> - <code>set battery.alert.critical &lt;0-99&gt;</code></p> <p>Defaults: - <code>battery.alert.low</code>: <code>20</code> - <code>battery.alert.critical</code>: <code>10</code></p> <p>Note: The low threshold must be greater than the critical threshold. Alerts at or below the critical threshold use <code>CRITICAL BATTERY</code> in the message; both severities use the same 12-hour resend cooldown.</p>"},{"location":"cli_commands/#enable-or-disable-the-rx-inactivity-watchdog-repeater-only","title":"Enable or disable the RX inactivity watchdog (Repeater Only)","text":"<p>Usage: - <code>get rx.watchdog</code> - <code>set rx.watchdog on</code> - <code>set rx.watchdog off</code></p> <p>Default: <code>on</code>, with a 24-hour no-RX timeout in normal mode.</p> <p>Notes: - In normal mode, the repeater reboots after 24 hours without a received packet passing MeshCore parsing. Each such reception restarts this timeout; checks use a sliding deadline rather than waiting for another 24-hour checkpoint. - While <code>tempradio</code> or <code>tempradioat</code> is running, windows of at least 12 hours use a 12-hour no-RX timeout. Shorter windows disable this reboot watchdog for the duration of the session. This temporary policy also overrides a saved normal-mode <code>off</code> setting. - Startup, a successful temporary-radio activation/replacement, expiry, cancellation, or manually changing this setting starts a fresh observation window. Expiry is processed before the watchdog, so a temporary window ending exactly at its watchdog deadline restores normal timing first. - <code>get rx.watchdog</code> reports both the effective on/off state and timeout or short-session disabled reason. <code>set rx.watchdog on|off</code> saves the normal-mode preference; temporary-session rules remain active until that session ends. Existing saved preferences are retained when upgrading; the new default applies to fresh settings or older preference files without this field. - The check uses the last successful MeshCore parse time, recorded before receive delays and routing filters. It does not require the packet to be addressed to this repeater or its encrypted payload to be decrypted; duplicate receptions also count. This checks MeshCore packet structure, not sender authentication. - It does not poll, sample, or wake the radio or CPU. A due check waits for the next normal loop/wake. With RX power saving enabled, qualifying packets received during normal listening windows count as activity; the watchdog does not alter the RX/sleep timing. - Transmitting, radio interrupts, and raw LoRa packets rejected by the MeshCore parser do not reset the timer. Packets dropped before parsing because the packet pool is full do not count either. This whole-board reboot setting is separate from the automatic radio-only recovery watchdog, which still measures successful raw radio reads.</p>"},{"location":"cli_commands/#enable-or-disable-the-nrf52-system-watchdog","title":"Enable or disable the nRF52 system watchdog","text":"<p>Usage: - <code>get system.watchdog</code> - <code>set system.watchdog on</code> - <code>set system.watchdog off</code></p> <p>Default: <code>on</code></p> <p>Notes: - This nRF52-only hardware watchdog resets the device if the application loop stops for 60 seconds, including an indefinite SoftDevice flash-write wait. - Enabling takes effect without a reboot. - The nRF52 hardware cannot stop a watchdog after it has started. Disabling is persisted immediately, then the current firmware stops feeding it so the board performs one watchdog restart within 60 seconds. It remains off after that restart. - This setting is nRF52-only. The SoftDevice flash deadlock does not apply to ESP32, whose existing watchdog behavior is unchanged.</p>"},{"location":"cli_commands/#estimate-and-correct-infrastructure-node-time-after-startup","title":"Estimate and correct infrastructure-node time after startup","text":"<p>Usage: - <code>get clock.sync</code> - <code>get clock.sync.status</code> - <code>get clock.sync.status.table</code> - <code>get clock.sync.status.&lt;1-16&gt;</code> - <code>get clock.sync.mesh</code> - <code>set clock.sync.mesh &lt;on|off&gt;</code> - <code>get clock.sync.mesh.edge</code> - <code>set clock.sync.mesh.edge &lt;on|off&gt;</code> - <code>clock.sync.mesh now</code> - <code>get clock.sync.internet</code> - <code>set clock.sync.internet &lt;on|off&gt;</code> - <code>get clock.sync.drift</code> - <code>set clock.sync.drift &lt;30-86400&gt;</code> - <code>get clock.sync.samples</code> - <code>set clock.sync.samples &lt;3-16&gt;</code></p> <p>Defaults: - <code>clock.sync.mesh</code>: <code>on</code> for all repeater, sensor, and room-server builds - <code>clock.sync.mesh.edge</code>: <code>on</code> - <code>clock.sync.internet</code>: <code>off</code> - <code>clock.sync.drift</code>: <code>600</code> seconds (10 minutes) - <code>clock.sync.samples</code>: <code>9</code></p> <p>When either source is enabled, the node makes its first clock-bootstrap attempt after 30 minutes of uptime, or immediately when the configured number of fresh evidence sources has been collected, whichever comes first. A successful estimate changes the RTC only when the absolute difference is greater than <code>clock.sync.drift</code>; correction can move the clock forward or backward. A valid estimate within the threshold counts as a successful sync without changing the clock. Seven days after each successful estimate, the node evaluates time again; the seven-day deadline therefore starts from the last successful estimate rather than from boot. This is a lazy uptime deadline: the check runs on the first normal loop/wake after it becomes due and does not wake the device by itself. If no source or consensus is available, the node retries every 30 minutes, and newly collected evidence triggers another immediate evaluation once the configured source count is present. Every reboot starts with the initial bootstrap attempt. An existing saved setting always overrides the platform default.</p> <p><code>clock.sync.mesh now</code> bypasses the startup/seven-day deadline and queues a LoRa-only consensus evaluation on the next normal loop, even when the internet source is also enabled. It uses any currently fresh samples without clearing the 16-slot table. If there is not yet enough evidence, mesh collection remains open and the next attempt follows the normal 30-minute retry. The command requires <code>clock.sync.mesh</code> to be on and does not bypass CLI, GPS, or NTP suppression; it also retains the normal quorum, timestamp-validity, and drift checks. The separate <code>clock</code> command only displays the current RTC and does not request a synchronization attempt.</p> <p><code>clock.sync.mesh</code> collects signature-verified advert timestamps and MAC-valid, decrypted Public-channel plain-text timestamps. In normal path mode, collection occurs only after the packet passes every forwarding filter. Sources are deduplicated by advert public key or case-insensitive Public-channel display name. Every fresh sample must also have a different full received path; all direct, zero-hop receptions count as the same empty path. This prevents repeated packets or multiple names arriving over one route from increasing the vote count.</p> <p>For a node at the edge of the network where every packet arrives through one relay path, <code>set clock.sync.mesh.edge on</code> changes the evidence requirement from distinct receive paths to distinct sources. Signature-verified adverts are deduplicated by public key, and Public-channel timestamps are deduplicated by case-insensitive display name. Repeated packets from one source still count once. Edge mode observes this verified evidence on the receive path, independently of the forwarding decision, so <code>repeat off</code> and forwarding filters do not prevent clock collection. Other packet types are observed normally but cannot be clock evidence because they do not provide a suitable authenticated Unix timestamp. Changing edge mode clears the in-memory sample table so evidence collected under the other policy is not reused. The setting is persistent and defaults on.</p> <p>At least the configured number of distinct fresh evidence sources (nine by default) and a strict majority of all fresh samples must fall within ten minutes of the median. In normal mode each source must use a distinct receive path. In edge mode signed adverts are distinct by public key and Public-channel messages are distinct by display name, but all may use the same receive path. The effective quorum is therefore the larger of <code>clock.sync.samples</code> and half the fresh sample count plus one. For example, a 9-vs-7 split can succeed but an 8-vs-8 split cannot. The median is used. <code>clock.sync.samples</code> accepts <code>3</code> through <code>16</code>; samples older than two hours are ignored. Status reports <code>mode=paths</code> or <code>mode=edge</code> and labels the collected evidence as <code>paths</code> or <code>sources</code>. It reports <code>reason=need-more-paths</code> or <code>reason=need-more-sources</code> when fewer than the configured number exist, and <code>reason=no-consensus</code> when enough evidence exists but the effective quorum does not agree. Mesh collection begins immediately after boot. Following a successful estimate, it resumes two hours before the next seven-day deadline so only evidence that can still be fresh at evaluation time is processed.</p> <p><code>get clock.sync.status</code> reports whether the clock was set and a <code>reason</code> when it was not. Common reasons include <code>waiting-deadline</code>, <code>need-more-sources</code>, <code>need-more-paths</code>, <code>no-consensus</code>, <code>within-drift</code>, <code>mesh-off</code>, and suppression by CLI, GPS, or internet time. It also reports whether collection is active, the fresh evidence count, the number of occupied table slots, and the next evaluation deadline.</p> <p><code>get clock.sync.status.table</code> shows the active sample table in compact form. Each item is <code>slot:type:id-prefix:age</code>, where type <code>A</code> is a signed advert and type <code>P</code> is a Public-channel message. A trailing <code>!</code> marks a stale sample. If the compact reply is truncated, query any slot with <code>get clock.sync.status.&lt;1-16&gt;</code>. The detail view reports the full source and path hashes, age-adjusted epoch, difference from the local clock, and freshness.</p> <p>A timestamp is eligible for a clock-sync sample only when it falls between the UTC build epoch embedded by <code>build.sh</code> and that time plus ten calendar years. Direct developer builds that bypass <code>build.sh</code> fall back to the compiler timestamp. Validation happens before a slot is selected or written, so an advert or Public-channel timestamp outside that window is not recorded as a clock sample.</p> <p>Before voting, the node advances each packet timestamp by an estimated transit time. The estimate sums the radio airtime at the original packet length and at each progressively longer relay length, plus the expected midpoint of the random flood-forward delay at every prior hop. The normal elapsed time since the radio recorded local receipt is then added when consensus is evaluated, so local signature/decryption/filter processing time is included too. This is better than using hop count alone because LoRa airtime changes with packet length and radio settings. Transit compensation is capped at the ten-minute consensus window. It cannot know sender queueing, channel contention, or a remote relay's non-matching <code>txdelay</code>, so the consensus window and median still absorb residual error.</p> <p>If a <code>clock sync</code> or <code>time &lt;epoch&gt;</code> CLI command successfully sets the clock, or a GPS provider writes a valid GPS time, LoRa-derived clock collection and correction are suppressed for the rest of that boot. Turning <code>clock.sync.mesh</code> off and back on does not clear this safety latch; only a reboot does. <code>get clock.sync.mesh</code> and <code>get clock.sync.status</code> report whether CLI or GPS time caused the suppression. On a WiFi MQTT build, a successful NTP sync is authoritative and also suppresses LoRa correction for the rest of that boot. Source selection starts fresh after a reboot, so LoRa remains the fallback when NTP cannot obtain internet time during that boot.</p> <p>Public-channel display names are not authenticated and can be spoofed. Received path hashes are also truncated, unauthenticated routing hints; requiring unique paths prevents ordinary duplicate-route inflation but is not a cryptographic identity check. Signed adverts authenticate the advert contents but do not prove that the advertising node's own clock is correct. Mesh time is therefore a consensus estimate, not an authoritative time service. Edge mode intentionally gives up receive-path diversity. Public-channel display names can be spoofed, so one sender can claim multiple names and inflate the edge-mode vote count.</p> <p><code>clock.sync.internet</code> is available on WiFi MQTT repeater-observer builds. Its initial and seven-day queries run on the MQTT/WiFi task and are read-only until the repeater applies the configured drift test. Failed queries retry after 30 minutes. On other infrastructure-node builds, the preference can be stored but status reports that internet time is unavailable. MQTT builds retain their existing startup NTP behavior required for MQTT/TLS/JWT operation; this setting controls the additional delayed drift checks. Startup NTP is always preferred when it succeeds, regardless of this setting.</p> <p>Sensor and room-server builds support mesh clock consensus and report <code>clock.sync.internet</code> as unavailable. Changing any <code>clock.sync.*</code> setting starts a new attempt for the current boot. Settings are persistent in <code>/clock_sync</code>; samples and schedule state are not.</p> <p>A backward correction is intentionally allowed, but peers that already recorded a later timestamp from this node may temporarily reject its lower timestamps as replays until corrected time passes the previously observed value.</p> <p>Example:</p> <pre><code>set clock.sync.drift 600\nset clock.sync.samples 3\nset clock.sync.mesh on\nset clock.sync.mesh.edge on\nclock.sync.mesh now\nget clock.sync.status\n</code></pre>"},{"location":"cli_commands/#view-this-nodes-public-key","title":"View this node's public key","text":"<p>Usage: <code>get public.key</code></p>"},{"location":"cli_commands/#view-this-nodes-firmware-version","title":"View this node's firmware version","text":"<p>Usage: <code>ver</code></p>"},{"location":"cli_commands/#view-this-nodes-configured-role","title":"View this node's configured role","text":"<p>Usage: <code>get role</code></p>"},{"location":"cli_commands/#view-or-change-this-nodes-power-saving-flag","title":"View or change this node's power saving flag","text":"<p>Search terms: battery saver, device power saving, low power mode.</p> <p>Usage: - <code>get powersaving</code> - <code>set powersaving on</code> - <code>set powersaving off</code></p> <p>Parameters:  - <code>on</code>: enable power saving - <code>off</code>: disable power saving</p> <p>Default: <code>on</code> for fresh Cascade-profile builds and Companion firmware; <code>off</code> for other infrastructure profiles</p> <p>Note: <code>get powersaving</code>, <code>set powersaving on</code>, and <code>set powersaving off</code> are shared by Companion and infrastructure. The saved preference controls whether power saving is allowed; active USB, logging and network services may keep the hardware awake. Actual sleep depends on the board.</p> <p>For the 1.17.1.5 G3 USB-disconnect report, use <code>set powersaving off</code> as the workaround. The released ESP32 sleep code can lose native USB after two minutes when the terminal is closed, even with a computer attached. The source fix blocks ESP32 light sleep while a native USB host is attached or live USB logging is enabled; ordinary CPU idle/yield remains available. The G3 button also wakes the device for at least two minutes. See the G3 release note for verification steps and the distinction between the fix and the published binaries.</p> <p>Companion firmware defaults this setting to <code>on</code>. Full Companion accepts the command from its local USB terminal and exposes the same setting in WebConfig. On ESP32, it lowers the CPU clock to 80 MHz, enables idle yielding, and enables the configured GPS duty cycle. USB and each active wireless transport remain available; SenseCAP Indicator Full keeps only its selected BLE or infrastructure-WiFi secondary transport active. <code>set powersaving off</code> restores the board's normal CPU clock and disables the GPS duty cycle. This device setting is separate from LoRa RXPS (<code>radio.rxps</code>) and WiFi modem power save (<code>wifi.powersave</code>). Infrastructure uses the same commands; its hardware and active-service sleep guards determine when the node can sleep.</p>"},{"location":"cli_commands/#view-or-set-the-reboot-interval-repeater-and-room-server","title":"View or set the reboot interval (Repeater and room server)","text":"<p>Usage: - <code>get reboot.interval</code> - <code>set reboot.interval &lt;hours&gt;</code></p> <p>Parameters: - <code>hours</code>: <code>0-255</code>; <code>0</code> disables scheduled reboots.</p> <p>Default: <code>0</code> (disabled)</p>"},{"location":"cli_commands/#control-an-exposed-gpio","title":"Control an exposed GPIO","text":"<p>Availability: ESP32 Repeater, Room Server, Bridge, and Sensor firmware. Companion firmware does not expose these commands. On nRF52, the commands are enabled only for Sensor builds on the Heltec T096, ProMicro, RAK3401, and RAK4631. GPIO expanders are not supported.</p> <p>Usage:</p> <ul> <li><code>get gpio</code> - list the Arduino pin numbers this firmware build permits</li> <li><code>get gpio state</code>, <code>get gpio states</code>, or <code>get gpio status</code> - list every available pin currently controlled by the user (anything not in <code>reset</code>)</li> <li><code>get gpio state &lt;pin&gt;</code> - show one pin's state; <code>states</code> and <code>status</code> are accepted here too</li> <li><code>get gpio &lt;pin&gt;</code> - show <code>on</code>, <code>off</code>, or <code>reset</code>, plus any pending timed transition</li> <li><code>set gpio &lt;pin&gt; on</code></li> <li><code>set gpio &lt;pin&gt; off</code></li> <li><code>set gpio &lt;pin&gt; reset</code></li> <li><code>set gpio &lt;pin&gt; &lt;on|off&gt; &lt;duration&gt; &lt;on|off|reset&gt;</code></li> </ul> <p>Examples:</p> <ul> <li><code>set gpio 16 on 30 off</code> - drive GPIO16 high for 30 seconds, then drive it low</li> <li><code>set gpio 16 on 5ms off</code> - drive GPIO16 high for 5 milliseconds, then drive it low</li> <li><code>set gpio 16 off 5 reset</code> - drive GPIO16 low for 5 seconds, then return it to high impedance</li> </ul> <p>An integer duration has seconds as its default unit, so <code>5</code> means 5 seconds. Add <code>ms</code> for milliseconds (<code>5ms</code>); an explicit <code>s</code> suffix is also accepted (<code>5s</code>). The maximum duration is 24 hours (86,400 seconds or 86,400,000 milliseconds). <code>on</code> or <code>off</code> without a duration remains in that state until another command, reset, or reboot.</p> <p><code>reset</code> changes the pin to an input with no pull resistor (high impedance). It does not reboot the node. It also cancels any pending timer for that pin. A new timed command for the same pin cancels and replaces the previous timer. GPIOs begin in <code>reset</code>; states and timers are not saved and are lost on reboot.</p> <p>The immediate reply confirms the applied state and any pending transition. When a timed transition finishes, a command issued over the authenticated remote CLI receives a second report such as <code>&gt; GPIO 16 timer complete: off</code>. Retries of the same authenticated timed command are recognized and do not restart its countdown.</p> <p>The pin number is the Arduino pin number used by that target (the normal GPIO number on ESP32 and the board's <code>D</code>/pin index on nRF52). The available-pin list is build-specific. Radio, flash/PSRAM, USB, serial console, display, GPS, I2C, buttons, LEDs, battery measurement, power control, bridge, Ethernet, watchdog, and other pins claimed by the firmware are rejected. A pin must also be physically broken out on your board; <code>get gpio</code> cannot detect wiring or an attached peripheral that is not represented by the firmware configuration.</p> <p>Electrical warning: GPIOs use 3.3 V logic and have limited drive current. Do not power a relay, motor, solenoid, or other load directly from a GPIO. Use a suitable transistor, MOSFET, optocoupler, or driver with the required protection components.</p>"},{"location":"cli_commands/#routing","title":"Routing","text":""},{"location":"cli_commands/#view-or-set-the-direct-path-override-for-the-current-remote-client","title":"View or set the direct path override for the current remote client","text":"<p>Usage: - <code>get outpath</code> - <code>get outpath path</code> - <code>set outpath &lt;hop1_hex,hop2_hex,...&gt;</code> - <code>set outpath path</code> - <code>set outpath direct</code> - <code>set outpath clear</code> - <code>set outpath flood</code></p> <p>Parameters: - <code>hopN_hex</code>: Hop hash with <code>2</code>, <code>4</code>, or <code>6</code> hexadecimal characters. Every hop must use the same width.</p> <p>Notes: - These commands require remote client context and update the caller's ACL entry. - <code>get outpath path</code> reports the reciprocal <code>PAYLOAD_TYPE_PATH</code> received after   the caller's latest flood login without changing the selected output route.   Because that packet is asynchronous, an immediate query can report   <code>&gt; path pending</code>; retry shortly. The observation window expires after one   minute, and the captured login path is not automatically selected. - <code>set outpath path</code> copies that observed route to <code>outpath</code> and saves it. It   returns an error without changing <code>outpath</code> if no route was received. - <code>direct</code> selects a zero-hop route for a directly reachable caller. - <code>clear</code> forgets the override, replies <code>&gt; outpath cleared</code>, and allows normal   path discovery to repopulate it. - <code>flood</code> forces replies to use flood packets until the client logs in again.</p>"},{"location":"cli_commands/#view-or-change-this-nodes-repeat-flag","title":"View or change this node's repeat flag","text":"<p>Search terms: enable repeating, disable repeating, packet forwarding, stop relaying.</p> <p>Usage: - <code>get repeat</code> - <code>set repeat &lt;state&gt;</code></p> <p>Parameters:   - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>flood.channel.data on</code>; <code>flood.channel.data.hops h=all</code></p>"},{"location":"cli_commands/#view-or-change-this-nodes-advert-path-hash-size","title":"View or change this node's advert path hash size","text":"<p>1.17.1.5 infrastructure bug: affected Repeater, Room Server, and Sensor images accept <code>get path.hash.mode</code> but report <code>unknown config</code> for the setter. The command was not renamed. The source correction restores the setter; installed images need an updated build. See the setting-dispatch audit.</p> <p>Usage: - <code>get path.hash.mode</code> - <code>set path.hash.mode &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Path hash size (0-2)   - <code>0</code>: 1 Byte hash size (256 unique ids)[64 max flood]   - <code>1</code>: 2 Byte hash size (65,536 unique ids)[32 max flood]   - <code>2</code>: 3 Byte hash size (16,777,216 unique ids)[21 max flood]   - <code>3</code>: DO NOT USE (Reserved) </p> <p>Default: <code>0</code></p> <p>Note: the 'path.hash.mode' sets the low-level ID/hash encoding size used when the repeater adverts. This setting has no impact on what packet ID/hash size this repeater forwards, all sizes should be forwarded on firmware &gt;= 1.14. This feature was added in firmware 1.14</p> <p>Temporary Note: adverts with ID/hash sizes of 2 or 3 bytes may have limited flood propagation in your network while this feature is new as v1.13.0 firmware and older will drop packets with multibyte path ID/hashes as only 1-byte hashes are supported. Consider your install base of firmware &gt;=1.14 has reached a criticality for effective network flooding before implementing higher ID/hash sizes. </p>"},{"location":"cli_commands/#view-or-change-this-nodes-loop-detection","title":"View or change this node's loop detection","text":"<p>Usage: - <code>get loop.detect</code> - <code>set loop.detect &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>:    - <code>off</code>: no loop detection is performed   - <code>minimal</code>: packets are dropped if repeater's ID/hash appears 4 or more times (1-byte), 2 or more (2-byte), 1 or more (3-byte)   - <code>moderate</code>: packets are dropped if repeater's ID/hash appears 2 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)   - <code>strict</code>: packets are dropped if repeater's ID/hash appears 1 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)</p> <p>Default: <code>off</code></p> <p>Note: When it is enabled, repeaters will now reject flood packets which look like they are in a loop. This has been happening recently in some meshes when there is just a single 'bad' repeater firmware out there (probably some forked or custom firmware). If the payload is messed with, then forwarded, the same packet ends up causing a packet storm, repeated up to the max 64 hops. This feature was added in firmware 1.14</p> <p>Example: If preference is <code>loop.detect minimal</code>, and a 1-byte path size packet is received, the repeater will see if its own ID/hash is already in the path. If it's already encoded 4 times, it will reject the packet.  If the packet uses 2-byte path size, and repeater's own ID/hash is already encoded 2 times, it rejects. If the packet uses 3-byte path size, and the repeater's own ID/hash is already encoded 1 time, it rejects. </p>"},{"location":"cli_commands/#view-or-change-the-retransmit-delay-factor-for-flood-traffic","title":"View or change the retransmit delay factor for flood traffic","text":"<p>Search terms: flood forwarding delay, flood retransmit delay, flood TX delay.</p> <p>Usage: - <code>get txdelay</code> - <code>set txdelay &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Transmit delay factor (0-2)</p> <p>Default: <code>0.5</code></p> <p>Note: When multiple nearby repeaters all hear the same flood packet, each waits a random amount of time before retransmitting to avoid simultaneous collisions. This factor scales the size of that random window. Higher values reduce collision risk at the cost of added latency. <code>0</code> disables the window entirely.</p>"},{"location":"cli_commands/#view-or-change-the-retransmit-delay-factor-for-direct-traffic","title":"View or change the retransmit delay factor for direct traffic","text":"<p>Search terms: direct forwarding delay, direct retransmit delay, direct TX delay.</p> <p>Usage: - <code>get direct.txdelay</code> - <code>set direct.txdelay &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Direct transmit delay factor (0-2)</p> <p>Default: <code>0.3</code> (Repeater) - <code>0.2</code> (Room Server, Sensor)</p> <p>Note: Same collision-avoidance random window as <code>txdelay</code>, but applied to direct (non-flood, routed) traffic. The default is lower because direct packets are addressed to a specific next hop, so far fewer nodes compete to retransmit them.</p>"},{"location":"cli_commands/#experimental-view-or-change-the-processing-delay-for-received-traffic","title":"[Experimental] View or change the processing delay for received traffic","text":"<p>Usage: - <code>get rxdelay</code> - <code>set rxdelay &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Receive delay base (0-20)</p> <p>Default: <code>0.0</code></p> <p>Note: When enabled, repeaters that received a flood packet with a weak signal are held in a delay queue before processing, while those that received it with a strong signal process it immediately. This gives strong-signal paths forwarding priority. By the time weak-signal nodes process their copy, the packet may have already propagated and will be suppressed as a duplicate, reducing redundant retransmissions.</p>"},{"location":"cli_commands/#view-or-change-the-duty-cycle-limit","title":"View or change the duty cycle limit","text":"<p>Usage: - <code>get dutycycle</code> - <code>set dutycycle &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Duty cycle percentage (1-100)</p> <p>Default: <code>50%</code> (equivalent to airtime factor 1.0)</p> <p>Examples: - <code>set dutycycle 100</code> - no duty cycle limit - <code>set dutycycle 50</code> - 50% duty cycle (default) - <code>set dutycycle 10</code> - 10% duty cycle - <code>set dutycycle 1</code> - 1% duty cycle (strictest EU requirement)</p> <p>Note: Added in firmware v1.15.0</p>"},{"location":"cli_commands/#view-or-change-the-airtime-factor-duty-cycle-limit","title":"View or change the airtime factor (duty cycle limit)","text":"<p>Deprecated as of firmware v1.15.0. Use <code>get/set dutycycle</code> instead.</p> <p>Usage: - <code>get af</code> - <code>set af &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Airtime factor (0-9). After each transmission, the repeater enforces a silent period of approximately the on-air transmission time multiplied by the value. This results in a long-term duty cycle of roughly 1 divided by (1 plus the value). For example:   - <code>af = 1</code> -&gt; ~50% duty   - <code>af = 2</code> -&gt; ~33% duty   - <code>af = 3</code> -&gt; ~25% duty   - <code>af = 9</code> -&gt; ~10% duty   You are responsible for choosing a value that is appropriate for your jurisdiction and channel plan (for example EU 868 Mhz 10% duty cycle regulation).</p> <p>Default: <code>1.0</code></p>"},{"location":"cli_commands/#view-or-change-the-local-interference-threshold","title":"View or change the local interference threshold","text":"<p>Usage: - <code>get int.thresh</code> - <code>set int.thresh &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Interference threshold value</p> <p>Default: <code>0.0</code></p>"},{"location":"cli_commands/#enable-or-disable-hardware-channel-activity-detection-cad","title":"Enable or disable hardware Channel Activity Detection (CAD)","text":"<p>Usage: - <code>get cad</code> - <code>set cad &lt;on|off&gt;</code></p> <p>Description: When enabled, the radio performs a hardware Channel Activity Detection scan before transmitting and defers if the channel is busy. Runs independently of <code>int.thresh</code> - either, both, or none may be active.</p> <p>Fresh Cascade-profile builds default CAD to <code>off</code> across all roles, including Companion. Saved CAD settings take precedence after an upgrade. Use <code>set cad off</code> to disable it on an existing node or <code>set cad on</code> to enable it explicitly. The repeater applies the saved toggle to the radio during its periodic noise-floor service. With one runnable packet, a busy result uses the normal CAD retry delay and allows roughly four seconds of continuous busy results. As the runnable transmit queue grows, both delays are divided by its depth: retry spacing will not fall below 50 ms and the busy ceiling will not fall below 500 ms. Reaching the busy ceiling records a CAD-timeout error and attempts the next queued transmission rather than waiting indefinitely. Future-scheduled packets do not accelerate CAD. <code>get cad</code> includes the hardware busy-result count.</p> <p>Parameters: - <code>on|off</code>: Enable or disable hardware CAD</p> <p>Default: <code>off</code></p>"},{"location":"cli_commands/#view-or-change-the-agc-reset-interval","title":"View or change the AGC Reset Interval","text":"<p>Usage: - <code>get agc.reset.interval</code> - <code>set agc.reset.interval &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Interval in seconds rounded down to a multiple of 4 (17 becomes 16). 0 to disable.</p> <p>Default: <code>0.0</code></p>"},{"location":"cli_commands/#view-or-change-the-radio-watchdog-interval-mqtt-observer-only","title":"View or change the radio watchdog interval (MQTT observer only)","text":"<p>Usage: - <code>get radio.watchdog</code> - <code>set radio.watchdog &lt;minutes&gt;</code></p> <p>Parameters: - <code>minutes</code>: <code>0</code> to use the standard 30-minute soft recovery interval, or <code>1-120</code> minutes to override it</p> <p>Default: <code>5</code></p> <p>Note: This setting belongs to the MQTT observer runtime and is not available on a standalone FULL repeater. It sets the interval without a successfully received packet before soft radio recovery. Transmissions and interrupts alone do not restart the timer. Setting it to <code>0</code> removes the observer override; automatic radio recovery remains active. The normal hard recovery threshold is 12 hours, where the radio supports it, and recovery does not reboot the whole board. On quiet meshes, increasing the soft interval can reduce unnecessary recoveries when no traffic is expected.</p>"},{"location":"cli_commands/#enable-or-disable-multi-acks-support","title":"Enable or disable Multi-Acks support","text":"<p>Usage: - <code>get multi.acks</code> - <code>set multi.acks &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>0</code> (disable) or <code>1</code> (enable)</p> <p>Default: <code>0</code></p>"},{"location":"cli_commands/#view-or-change-the-flood-advert-interval","title":"View or change the flood advert interval","text":"<p>Usage: - <code>get flood.advert.interval</code> - <code>set flood.advert.interval &lt;hours&gt;</code></p> <p>Parameters: - <code>hours</code>: Interval in hours (3-168)</p> <p>Default: <code>47</code> (Repeater, Room Server) - <code>0</code>, disabled (Sensor)</p>"},{"location":"cli_commands/#view-or-change-the-zero-hop-advert-interval","title":"View or change the zero-hop advert interval","text":"<p>Usage: - <code>get advert.interval</code> - <code>set advert.interval &lt;minutes&gt;</code></p> <p>Parameters: - <code>minutes</code>: Interval in minutes rounded down to the nearest multiple of 2 (61 becomes 60) (60-240)</p> <p>Default: <code>2</code> on a factory-fresh node, then <code>0</code> (disabled) once configured.</p> <p>Note: A new install ships with a 2 minute zero-hop advert interval. Saving any setting resets an interval below the 60 minute minimum to <code>0</code>, on the assumption that the node has now been deliberately configured. To keep zero-hop adverts running, set an explicit value in the 60-240 range.</p>"},{"location":"cli_commands/#limit-the-number-of-hops-for-a-flood-message","title":"Limit the number of hops for a flood message","text":"<p>Search terms: hop limit, maximum hops, max hops, flood distance.</p> <p>Usage: - <code>get flood.max</code> - <code>set flood.max &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Maximum flood hop count (0-64)</p> <p>Default: <code>64</code></p>"},{"location":"cli_commands/#limit-the-number-of-hops-for-an-unscoped-flood-message","title":"Limit the number of hops for an unscoped flood message","text":"<p>Usage: - <code>get flood.max.unscoped</code> - <code>set flood.max.unscoped &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Maximum flood hop count (0-64) for a packet without a scope (no region set)</p> <p>Default: <code>0xFF</code> - indicates it hasn't been set, will track flood.max until it is.</p> <p>Note: An alternative to <code>region denyf *</code>, setting <code>flood.max.unscoped</code> to a lower value such as <code>3</code> would allow for local unscoped messages to propagate, while preventing noisy neighbors from flooding a local region.</p>"},{"location":"cli_commands/#limit-the-number-of-hops-for-an-advert-flood-message","title":"Limit the number of hops for an advert flood message","text":"<p>Usage: - <code>get flood.max.advert</code> - <code>set flood.max.advert &lt;value&gt;</code></p> <p>Parameters: - <code>value</code>: Maximum flood hop count (0-64) for an advert packet</p> <p>Default: <code>8</code></p>"},{"location":"cli_commands/#forward-flood-group-data-packets-on-repeaters","title":"Forward flood group data packets on repeaters","text":"<p>Usage: - <code>get flood.channel.data</code> - <code>get flood.channel.data.hops</code> - <code>set flood.channel.data &lt;on|off&gt;</code> - <code>set flood.channel.data.hops &lt;all|1-7&gt;</code></p> <p>Parameters: - <code>on</code>: Retransmit received flood <code>GRP_DATA</code> channel packets. - <code>off</code>: Do not retransmit received flood <code>GRP_DATA</code> channel packets. - <code>all</code>: When <code>flood.channel.data</code> is <code>off</code>, block <code>GRP_DATA</code> at any received flood hop count. - <code>1-7</code>: When <code>flood.channel.data</code> is <code>off</code>, repeat <code>GRP_DATA</code> at this hop count or lower and block longer paths.</p> <p>Default: <code>flood.channel.data on</code>; <code>flood.channel.data.hops h=all</code></p> <p>Forwarding behavior: Repeater firmware only. The repeater still receives and logs the packet when logging is enabled; this only blocks retransmission. On generalized repeaters these commands manage an ordinary visible FPF7 <code>type=grp_data</code> drop row. <code>off</code> with <code>all</code> maps to <code>hops=all</code>; <code>off</code> with <code>N</code> maps to <code>hops=N+1+</code>. The 240 KB compact FPF6 profiles retain the legacy hard gate. Because it is an ordinary FPF7 row, a matching higher-priority <code>stop</code> rule can exempt traffic from it. The compact <code>get flood.filter</code> list marks the managed row with <code>~data</code>. Flood group text (<code>GRP_TXT</code>) is unaffected by this setting.</p> <p><code>get flood.channel.data</code> includes the active hop gate as <code>h=all</code> or <code>h&gt;N</code>.</p>"},{"location":"cli_commands/#bridge-and-radio-crossover-filters","title":"Bridge and radio crossover filters","text":"<p><code>mode=</code> selects where a generalized <code>flood.rule</code> / <code>flood.filter</code> row applies:</p> Mode Where the rule applies <code>radio</code> Ordinary LoRa flood forwarding. This is the default when <code>mode=</code> is omitted. <code>bridge</code> Packets entering or leaving an RS232 or ESP-NOW bridge, and MeshCore RX/TX packet publication through MQTT. <code>cross</code> Transmissions copied to the other radio profile, including a copy's retries. The same-profile transmission remains eligible. <code>bridge,cross</code> Both transport paths using one rule. <code>cross,bridge</code> is equivalent. <p>The third built-in repeater rule blocks authenticated <code>#wardriving</code> text and data at all hops on bridge and crossover paths, including temporary-radio sessions. It leaves same-profile traffic subject to the separate four-hop rule. <code>set radio2.cross on</code> does not override this filter.</p> <pre><code># Factory slot: inspect before replacing an existing rule.\nget flood.rule.3\nset flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\n# On an existing device, add it without overwriting an occupied slot.\nset flood.rule type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>Saved tables are preserved on upgrade; new defaults are seeded only when the table is first initialized. Bridge/cross modes accept drop, rate, priority and stop actions; scope rewrites, retry actions and TX timing are rejected. These modes cover direct as well as flood packets, in both crossing directions. The default authenticates the channel key, avoiding false drops from short channel-hash collisions. FULL room servers support explicit transport rules; companions and compact FPF6 profiles do not expose this table.</p> <p>See filtering documentation for persistence, queue/rate semantics, exceptions, and how to remove one or both blocks.</p>"},{"location":"cli_commands/#block-selected-flood-channels-with-fpf7","title":"Block selected flood channels with FPF7","text":"<p>The separate <code>flood.channel.block</code> command and 15-row table have been retired. Generalized repeaters use the 63-row FPF7 forward phase for authenticated channel blocks:</p> <pre><code>set flood.rule type=any channel=#test hops=all drop\nset flood.rule.2 type=any channel=#wardriving hops=5+ drop\nset flood.rule type=any channel=9cd8fcf22a47333b591d96a2b848b73f hops=4+ drop\nget flood.rule\ndel flood.rule.2\n</code></pre> <p><code>type=any</code> with a channel condition can authenticate only <code>GRP_TXT</code> and <code>GRP_DATA</code>, so it does not match other payload types. Use <code>hops=all</code> to block at every received hop count. To preserve the old <code>h=N</code> meaning of repeating through <code>N</code> hops and blocking longer paths, use <code>hops=N+1+</code>; old <code>h=4</code> is therefore <code>hops=5+</code>.</p> <p>New generalized repeater tables seed slot 2 with the second example. Existing FCB2 rows are imported once into free FPF7 slots and the retired file is then removed. The fixed-size STM32WL FPF6 build cannot match authenticated channels.</p>"},{"location":"cli_commands/#force-a-transport-scope-onto-floods","title":"Force a transport scope onto floods","text":"<p>Usage: - <code>get flood.channel.scope</code> - <code>get flood.channel.scope.&lt;n&gt;</code> - <code>set flood.channel.scope &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]</code> - <code>set flood.channel.scope.&lt;n&gt; &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]</code> - <code>del flood.channel.scope.&lt;n&gt;</code> - <code>del flood.channel.scope all</code></p> <p>Parameters: - <code>n</code>: Slot number within the table compiled for the target. Roomy ESP32 builds   provide <code>1-255</code>; classic ESP32 repeaters and nRF52/other   normal constrained builds provide <code>1-31</code>; very-tight STM32WL repeaters provide   <code>1-15</code>; the no-PSRAM LilyGo T-LoRa V2.1 repeater/observer provides <code>1-4</code>. - <code>channel</code>: <code>public</code>, a public <code>#channel</code>, or a 128/256-bit channel key in hex. - <code>txt:*</code>: Unauthenticated fallback for otherwise-unmatched <code>GRP_TXT</code> and   <code>GRP_DATA</code>. Plain <code>*</code> is an alias for <code>txt:*</code>. - <code>login:*</code>: Type-based wildcard for the remote-login/admin family: <code>REQ</code>,   <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code> (<code>0x00</code>, <code>0x01</code>, <code>0x02</code>,   <code>0x07</code>, and <code>0x08</code>). It classifies the outer type; a transit repeater cannot   authenticate whether a packet is actually part of a login session. - <code>other:*</code>: Type-based wildcard for every remaining flood payload type,   including flood-form TRACE, ACK, advert, multipart, control, OTA, reserved   types, and raw custom. - <code>region</code>: Existing named region with a usable transport key. A unique region   name prefix is accepted; wildcard region <code>*</code> is not a scope target. - <code>scope=&lt;name&gt;</code>: Regionless alternative to <code>region</code>. The public name is   normalized with a leading <code>#</code>, and its 128-bit transport key is derived   directly from that hashtag exactly as for <code>flood.filter scope=&lt;name&gt;</code>. It   does not need to exist in the region list. Public names up to 30 characters   are accepted; private <code>$</code> scopes are not. - <code>path=blacklist</code>: Optional. Require the received path to match the passive   <code>flood.filter.blacklist</code> ID table. No <code>flood.filter</code> drop row needs to be   enabled. One exact listed ID qualifies a 3-byte path. A 2-byte path requires   two matching received path entries, while a 1-byte path never qualifies. - <code>path=bucket:&lt;1-6&gt;</code>: Optional alternative to <code>path=blacklist</code>. Match IDs in   the selected persistent <code>flood.retry.bucket</code>. Each bucket holds up to 17   three-byte IDs and remains usable when <code>flood.retry.bridge</code> is off. It uses   the same 3-byte, 2-byte, and 1-byte thresholds as <code>path=blacklist</code>.   <code>recent.repeater</code> freshness and <code>flood.retry.ignore</code> do not affect this   passive match. - <code>tx=slow</code>: Optional. Use an effective inbound <code>rxdelay</code> base of   <code>max(2, configured rxdelay * 2)</code>, keep normal outbound queue priority, and   schedule retransmission with the maximum supported <code>txdelay</code> factor of   <code>2.0</code> after changing the scope. The default is fast; <code>tx=fast</code> may be   supplied explicitly when replacing a slow row.</p> <p>Default: No forced scopes.</p> <p>Remote ACL permission <code>4</code> (region/scope manager) can use all <code>get</code>, <code>set</code>, and <code>del flood.channel.scope</code> forms. Filter managers and other non-admin roles cannot change this table.</p> <p>Without <code>.n</code>, <code>set</code> updates the row for the same exact channel key or wildcard class with the same path selector, otherwise it uses the first empty slot. This permits an ordinary fallback and separate blacklist or bridge-bucket rows for the same channel. With <code>.n</code>, it replaces that slot. The three wildcard classes are independent and consume one slot each. <code>get flood.channel.scope</code> reports active/total slot counts; use the numbered form for row detail. Keyed rows are displayed by the first four bytes of their derived channel hash because channel secrets are never returned. Regionless targets are displayed with their normalized leading <code>#</code>.</p> <p>This acts on received <code>ROUTE_TYPE_FLOOD</code> and <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> packets. An unscoped packet gains the configured scope; an already-scoped packet has its existing transport codes replaced. For <code>GRP_TXT</code> and <code>GRP_DATA</code>, all exact channel-key rows are tried first and must validate the packet MAC/decryption. Matching path-qualified exact rows are   tried before ordinary exact fallback rows. A region-backed row whose target   is missing or unusable is skipped; later exact rows and then <code>txt:*</code> are tried. Exact keyed rows with a usable target therefore beat <code>txt:*</code> regardless of slot number. Within each wildcard class, path-qualified rows similarly precede ordinary fallback rows. <code>login:*</code> and <code>other:*</code> select their non-overlapping outer-type families without decrypting the payload. The lowest usable slot wins within each priority tier.</p> <p>Standard traceroute is direct-routed and is therefore outside this flood-only table. A custom flood-form <code>TRACE</code> is treated like every other flood: an applicable wildcard may rewrite it and region/unknown-code gates still apply.</p> <p>On a match, the repeater sets the route to <code>ROUTE_TYPE_TRANSPORT_FLOOD</code>, computes transport code 0 from the selected region or direct hashtag key and packet payload, and sets transport code 1 to zero. This occurs before region enforcement, forwarding filters, and the seen-packet lookup. For an already-scoped packet, the selected code replaces both incoming transport-code fields. Direct routes are never rewritten. A packet converted from unscoped is no longer subject to <code>flood.max.unscoped</code>; all rewritten packets remain subject to normal payload handling, <code>flood.max</code>, <code>flood.filter</code>, loop detection, and moderation. Assigning a scope does not make a packet type forwardable if the core would otherwise reject it. By default, if the selected scope differs and the rewritten packet is accepted for forwarding, its initial retransmission uses zero <code>txdelay</code> and the highest outbound queue priority so the newly scoped copy can win at the next hop. Adding <code>tx=slow</code> uses an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, keeps the ordinary queue priority, and uses the maximum <code>txdelay</code> factor of <code>2.0</code> for the retransmission. As with ordinary <code>txdelay</code>, the actual transmit delay is randomized from zero through the resulting window; factor <code>2.0</code> gives a maximum of ten packet airtimes. Neither mode preempts an active radio transmission or bypasses CAD and airtime-budget limits. Selecting the scope already carried by the packet is a no-op and does not grant special transmit treatment.</p> <p>A region-backed target must be locally flood-allowed and remains subject to the normal region gate. A <code>scope=&lt;name&gt;</code> target is trusted for this matched receive pass even though it has no region-list entry, matching the behavior of <code>flood.filter scope=&lt;name&gt;</code>. It does not create a region, consume a region slot, or change the allow/deny state for unrelated packets carrying the same transport code.</p> <p>If a region-backed row's target has been removed or has no usable key, the repeater tries the next applicable row. For group packets this means later authenticated exact rows followed by <code>txt:*</code>; wildcard duplicates likewise fall through to the next usable slot. When no usable mapping exists, the packet retains its original unscoped or scoped route.</p> <p>LoRa OTA remains functional when <code>other:*</code> is configured. OTA packets are given that target's transport code, replacing an existing code when necessary, but the OTA handler still accepts and re-floods them during the temporary-radio window. A region target must allow flooding; a direct target follows the regionless trust behavior above. The OTA core itself is dormant outside that window; no default flood filter row is needed for that behavior. Forced scope does not make OTA operate outside the window.</p> <p>Capacity cost: Each rule slot retains its 36-byte runtime and persistent record. A separate 32-byte-name table holds up to the smaller of the rule count or 32 distinct regionless targets; very-tight STM32WL builds hold one reusable direct target. Region-backed targets do not consume this table. The four-slot minimum uses 272 bytes RAM and a 278-byte file; it has room for the three wildcard classes plus one exact channel mapping. Very-tight 15-slot builds use 572 bytes RAM and a 578-byte file. The 31-slot table uses 2,108 bytes RAM and a 2,114-byte file. Roomy ESP32 builds use 255 rule slots and 32 direct-target slots: 10,204 bytes RAM and a 10,210-byte file. Classic ESP32 LoRa-OTA builds that cannot afford the 255-rule table use 31 slots instead. Both configured regions and regionless targets can be reused by any number of rules.</p> <p>Duplicate behavior: Mesh dedup hashes payload type and payload bytes; it does not hash route type, transport codes, or the ordinary flood path. Adding a transport scope therefore does not create a new duplicate identity. If the same payload later arrives scoped, unscoped, or through a different region, it is still the same seen packet. <code>TRACE</code> is the exception only in that its encoded <code>path_len</code> byte is also hashed.</p> <p>While equivalent non-TRACE flood copies are waiting in <code>rxdelay</code>, the normal receive-quality timing still selects the packet to process, but that winner receives a scope from the queued scoped copies with the same dedupe identity. If the copies carry different locally allowed scopes, the scope from the shortest received path wins. Unknown and denied transport codes are not candidates and therefore cannot overwrite an unscoped winner. With equal path lengths, the deeper child region wins because it is narrower. A remaining tie keeps queue order. The winner's own path, SNR reading, and scheduled time are not changed, and an already-scoped winner may have its code replaced by the better queued scope.</p> <p>The comparison is deferred until dequeue so each copy retains its original scope and path for arbitration. It can only use copies still present in <code>rxdelay</code>; it cannot replace a packet that already won the dedupe race. Flood-form TRACE participates in this arbitration; direct traceroute does not enter the flood queue.</p> <p>A packet that matches a fast <code>flood.channel.scope</code> or <code>flood.filter scope=</code> action and needs its scope changed bypasses the inbound <code>rxdelay</code> queue. A <code>tx=slow</code> row remains in that queue with twice the configured base, floored at <code>2.0</code>, and participates in normal queued-copy scope arbitration.</p> <p>Examples:</p> <pre><code>region put west\nregion save\nset flood.channel.scope #local west\nset flood.channel.scope.2 txt:* west tx=slow\nset flood.channel.scope.3 login:* west\nset flood.channel.scope.4 other:* west\nget flood.channel.scope\nget flood.channel.scope.1\ndel flood.channel.scope.2\n</code></pre> <p>A regionless exact mapping needs no <code>region</code> command:</p> <pre><code>set flood.channel.scope #rgdata scope=BlackHole86\nget flood.channel.scope\nget flood.channel.scope.1\n</code></pre> <p>For example, if an authenticated <code>#rgdata</code> packet arrives carrying scope <code>#usa</code>, that rule replaces <code>#usa</code> with <code>#BlackHole86</code> before forwarding. The rule also assigns <code>#BlackHole86</code> when the packet is unscoped or carries any other scope; it is a channel-to-target mapping, not an incoming-scope filter.</p> <p>To use bridge bucket 1 to assign <code>east</code> to <code>public</code> packets whose received 3-byte path contains <code>7576FB</code>, while assigning <code>west</code> to every other authenticated <code>public</code> packet:</p> <pre><code>set flood.retry.bucket 1 7576FB\nset flood.channel.scope public west\nset flood.channel.scope public east path=bucket:1\n</code></pre> <p>Additional 3-byte IDs may be added to bucket 1 later; any one exact hit qualifies the <code>east</code> row. This use is passive and does not require <code>flood.retry.bridge</code> to be enabled. The separate blacklist selector remains available for tables shared with <code>flood.filter path=blacklist</code> rules.</p>"},{"location":"cli_commands/#require-valid-incoming-scopes-only-on-selected-channels","title":"Require valid incoming scopes only on selected channels","text":"<p>Usage: - <code>get flood.channel.scope.require</code> - <code>get flood.channel.scope.require.&lt;n&gt;</code> - <code>set flood.channel.scope.require &lt;public|#channel|128/256-bit-key&gt;</code> - <code>set flood.channel.scope.require.&lt;n&gt; &lt;public|#channel|128/256-bit-key&gt;</code> - <code>del flood.channel.scope.require.&lt;n&gt;</code> - <code>del flood.channel.scope.require all</code></p> <p>Default: Empty; normal global region enforcement remains active.</p> <p>Once this table contains a row, received flood <code>GRP_TXT</code> and <code>GRP_DATA</code> packets use selective region enforcement. A packet authenticating against a listed channel key must already carry a transport scope matching a locally flood-allowed region. Listed channels arriving unscoped, with an unknown code, or with a denied region are not retransmitted. This tests the original incoming scope before any <code>flood.channel.scope</code> or <code>flood.filter scope=</code> rewrite. Those rewrite actions are skipped for a rejected listed channel, so they cannot rescue it or grant special receive/transmit timing.</p> <p>Other group channels bypass the region/unknown-code gate while the table is active. They remain subject to every other forwarding control, including <code>repeat</code>, <code>flood.max*</code>, packet filters, loop detection, payload validation, and moderation. Non-channel flood payload types retain normal global region enforcement.</p> <p>Channel matching validates the packet MAC/decryption with the configured key; the visible one-byte channel hash is only a prefilter. Public hashtag channels use their derived public key. Without <code>.n</code>, setting an existing key updates it and a new key uses the first empty slot. Numbered <code>set</code> replaces that slot. <code>get ...&lt;n&gt;</code> reports a four-byte derived prefix and key size without exposing the key. The table uses the same build-dependent slot count as <code>flood.channel.scope</code>.</p> <p>Remote ACL permission <code>4</code> can manage this table. Deleting its final row restores normal global region enforcement for group channels.</p> <p>Example:</p> <pre><code>set flood.channel.scope.require #bot\nget flood.channel.scope.require\nget flood.channel.scope.require.1\n</code></pre>"},{"location":"cli_commands/#change-persistent-flood-rules-in-the-field","title":"Change persistent flood rules in the field","text":"<p>For setup guidance, interactions with the existing forwarding controls, and worked moderation examples, see Flood Filtering and Moderation.</p> <p>Usage:</p> <ul> <li><code>get flood.rule</code></li> <li><code>get flood.rule.&lt;n&gt;</code></li> <li><code>get fr[.&lt;n&gt;]</code> (numbered form returns a complete short setter for copying)</li> <li><code>set fr[.&lt;n&gt;] &lt;type&gt; [h=&lt;range&gt;] [m=r|b|c|bc] [c=&lt;channel&gt;] &lt;d|s=&lt;scope&gt;|r=&lt;region&gt;|q=&lt;N&gt;|r|s&gt; [...]</code></li> <li><code>del fr.&lt;n&gt;</code> or <code>del fr all</code></li> <li><code>set flood.rule[.&lt;n&gt;] type=&lt;type&gt; [mode=radio|bridge|cross|bridge,cross] [hops=&lt;range&gt;] [channel=&lt;channel&gt;] [prefix=&lt;path-prefix&gt;] [in=&lt;input-scope&gt;] &lt;drop|scope=&lt;name&gt;|region=&lt;name&gt;|rate=&lt;N&gt;/min|retry|stop&gt; [priority=&lt;0-255&gt;] [tx=slow] [suspend=tempradio]</code></li> <li><code>del flood.rule.&lt;n&gt;</code></li> <li><code>del flood.rule all</code></li> <li><code>get flood.filter</code></li> <li><code>get flood.filter.&lt;n&gt;</code></li> <li><code>get flood.filter.blacklist</code></li> <li><code>get flood.filter.blacklist.&lt;n&gt;</code></li> <li><code>set flood.filter.blacklist &lt;ID[,ID...]&gt;</code></li> <li><code>set flood.filter.blacklist.&lt;n&gt; &lt;ID[,ID...]&gt;</code></li> <li><code>del flood.filter.blacklist</code></li> <li><code>del flood.filter.blacklist.&lt;n&gt;</code></li> <li><code>set flood.filter &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]</code></li> <li><code>set flood.filter.&lt;n&gt; &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]</code></li> <li><code>del flood.filter.&lt;n&gt;</code></li> <li><code>del flood.filter all</code></li> </ul> <p>The extended table is available on repeaters with the rule engine enabled and on FULL-profile ESP32 room servers. A FULL room server exposes <code>fr</code>, <code>flood.rule</code>, and <code>flood.filter</code>, has 31 slots, and requires an administrator for remote changes. It does not have the repeater's passive path blacklist, so <code>flood.filter.blacklist*</code> and <code>path=blacklist</code> are repeater-only; use the ordered <code>prefix=</code> match on a room server. Standard room-server profiles do not compile this table.</p> <p>Parameters:</p> <ul> <li><code>n</code>: Forward-rule slot in the build's compiled table (<code>1-63</code> on generalized   repeaters and <code>1-31</code> on FULL room servers; compact profiles may use fewer).</li> <li><code>mode</code>: Optional; omitted means <code>radio</code>. <code>bridge</code> filters bridge admission,   <code>cross</code> filters copies to the other radio profile, and <code>bridge,cross</code> covers   both with one row. <code>cross,bridge</code> is an alias. See the   mode matrix for scope and supported actions.</li> <li><code>type</code>: Payload type name, full <code>PAYLOAD_TYPE_*</code> name, decimal value <code>0-15</code>,   hexadecimal value <code>0x00-0x0F</code>, or <code>any</code>.</li> <li><code>hops</code>: Optional; omitted means <code>all</code>.</li> <li><code>N</code>: Match only at received hop count <code>N</code>.</li> <li><code>N+</code>: Match at received hop count <code>N</code> and higher.</li> <li><code>N-M</code>: Match the inclusive received-hop range.</li> <li><code>all</code>: Match every received hop count (<code>0-63</code>).</li> <li><code>0+</code>, <code>all</code>, and an omitted hop expression are equivalent. The CLI displays     the saved range as <code>all</code>.</li> <li><code>channel=*|public|#name|hash:XX|128-bit-key|256-bit-key</code>: Optional channel match.   <code>channel=*</code> means no channel condition at all, so the row matches everything   selected by <code>type=</code> (including all flood payload types with <code>type=any</code>). It   does not authenticate a packet. <code>public</code>, <code>#name</code>, and raw keys authenticate   one channel and therefore narrow the row to <code>GRP_TXT</code>/<code>GRP_DATA</code>.   <code>hash:XX</code> matches only the visible one-byte group-channel hash; <code>short:XX</code>   and a bare two-digit byte are accepted aliases and are displayed as   <code>hash:XX</code>. This form is deliberately unauthenticated. It can collide with   another channel once in 256 hash values, and a sender can choose the byte,   so use an exact channel name or key whenever it is available. In particular,   <code>channel=hash:11</code> does not mean Public: it matches Public plus every collision   or deliberately selected <code>0x11</code> value. <code>channel=public</code> performs the deeper   MAC/decrypt check with the Public channel key. That distinguishes an ordinary   <code>0x11</code> collision, but it is channel authentication rather than sender   authentication: the group MAC is two bytes and the Public key is shared.</li> <li><code>prefix=&lt;ID[,ID...]&gt;</code>: Optional ordered source-path prefix of one to three   pbyte IDs. IDs must all be 2, 4, or 6 hex characters, matching a packet's   1-, 2-, or 3-byte pbyte width. <code>path=&lt;prefix&gt;</code> is an alias.</li> <li><code>in=any|none|scoped|allowed|unknown|scope:&lt;name&gt;|region:&lt;name&gt;</code>: Optional   condition on the original incoming scope, before any rule rewrites it.   <code>none</code> is an unscoped flood. <code>scope:name</code> is the exact public   hashtag-derived scope. <code>region:name</code> is an exact allowed region match.</li> <li><code>drop</code>: Explicit drop action. The <code>flood.rule</code> form requires an explicit   action. For compatibility, a legacy <code>flood.filter</code> row with no rewrite,   rate, or stop action is treated as drop.</li> <li><code>scope=&lt;name&gt;</code>: Direct public-name scope rewrite. It derives a transport key   from the name and does not require a configured region. For example,   <code>scope=BlackHole86</code> is a regionless sink scope; <code>region=BlackHole86</code> would   instead require a real configured, flood-allowed region with that name.</li> <li><code>region=&lt;name&gt;</code>: Rewrite using an existing locally allowed region and one of   that region's transport keys.</li> <li><code>rate=N/min</code>: Per-node, per-row fixed one-minute forwarding limit. It can be   the only action or accompany <code>scope=</code>/<code>region=</code>. Counters are charged only   for packets that pass all forwarding gates.</li> <li><code>retry</code>, <code>retry=on</code>, <code>retry=allow</code>, or <code>action=retry</code>: Allow a matching   received flood packet to enter the configured flood-retry sequence. With no   active <code>retry</code> rows, retry eligibility remains backward compatible and is   controlled by the global retry settings. Once any active <code>retry</code> row exists,   the matching rows become a retry allow-list: a received flood must match at   least one surviving <code>retry</code> row. <code>flood.retry.bridge</code> still selects ordinary   or bridge-bucket completion for the allowed packet. This action can accompany   rewrite, rate, or stop, but not <code>drop</code>; compact syntax uses <code>f=r</code>.</li> <li><code>priority=0-255</code>: Optional primary processing order. Higher values run first.   At the same numeric priority, authenticated channel matches run before raw   <code>hash:XX</code> matches, which run before <code>channel=*</code>; lower slot number breaks the   remaining tie. The default is <code>0</code>; <code>pri=</code> is an alias. An explicitly higher   numeric priority still overrides this automatic specificity ordering.</li> <li><code>stop</code> or <code>action=stop</code>: Apply this matching row, then stop lower-order FPF7   rows from processing. It can stand alone or accompany drop, rewrite, or   rate. A stop-only row acts as an exception to lower-priority FPF7 rules.   If the same row uses <code>region=</code> and that configured region is missing, denied,   wildcard, or has no usable transport key, both the rewrite and its <code>stop</code>   are inert so lower-order safety rows still run. A direct <code>scope=</code> target does   not depend on region configuration.</li> <li><code>suspend=tempradio</code>: Optional. Skip this row while either <code>tempradio</code> or   <code>tempradio2</code> is active, including scheduled temporary sessions.</li> <li><code>require=region</code>: Legacy alias for <code>in=allowed</code>. Apply the row only if the   original incoming packet already passes this repeater's   region gate. An incoming transport scope must resolve to a locally allowed   region; an unscoped flood must be allowed by the wildcard region. The check   occurs before any scope rewrite during this receive pass.</li> <li><code>tx=slow</code>: Optional and valid with <code>scope=</code> or <code>region=</code>. Use an effective inbound   <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, keep normal outbound   queue priority, and retransmit with the maximum supported <code>txdelay</code> factor   of <code>2.0</code>. Scope rows default to fast; <code>tx=fast</code> explicitly restores that   default when replacing a slow row.</li> <li><code>path=blacklist</code>: Optional unordered path condition. The persistent blacklist   is repeater-only. It contains up to 255 unique 3-byte repeater IDs on ESP32   builds and 18 on other builds, each written as six hexadecimal digits. A   packet with 3-byte path hashes matches after one exact ID hit. A packet with   2-byte path hashes matches after two path entries match the first two bytes   of listed IDs. Packets with 1-byte path hashes never match this condition.   Each received path entry is counted at most once.</li> </ul> <p>The payload names follow the MeshCore packet-format allocation:</p> Value Short name Full name <code>0x00</code> <code>req</code> <code>PAYLOAD_TYPE_REQ</code> <code>0x01</code> <code>response</code> <code>PAYLOAD_TYPE_RESPONSE</code> <code>0x02</code> <code>txt_msg</code> <code>PAYLOAD_TYPE_TXT_MSG</code> <code>0x03</code> <code>ack</code> <code>PAYLOAD_TYPE_ACK</code> <code>0x04</code> <code>advert</code> <code>PAYLOAD_TYPE_ADVERT</code> <code>0x05</code> <code>grp_txt</code> <code>PAYLOAD_TYPE_GRP_TXT</code> <code>0x06</code> <code>grp_data</code> <code>PAYLOAD_TYPE_GRP_DATA</code> <code>0x07</code> <code>anon_req</code> <code>PAYLOAD_TYPE_ANON_REQ</code> <code>0x08</code> <code>path</code> <code>PAYLOAD_TYPE_PATH</code> <code>0x09</code> <code>trace</code> <code>PAYLOAD_TYPE_TRACE</code> <code>0x0A</code> <code>multipart</code> <code>PAYLOAD_TYPE_MULTIPART</code> <code>0x0B</code> <code>control</code> <code>PAYLOAD_TYPE_CONTROL</code> <code>0x0C</code> <code>ota</code> <code>PAYLOAD_TYPE_OTA</code> (this fork's LoRa OTA extension; reserved upstream) <code>0x0D</code> <code>13</code> reserved <code>0x0E</code> <code>14</code> reserved <code>0x0F</code> <code>raw_custom</code> <code>PAYLOAD_TYPE_RAW_CUSTOM</code> <p>Route scope: <code>mode=radio</code> rules are evaluated only for the two flood route values: <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> (<code>0x00</code>, flood plus transport codes) and <code>ROUTE_TYPE_FLOOD</code> (<code>0x01</code>, unscoped flood). Direct routes <code>0x02</code> and <code>0x03</code> are unaffected by radio rules. Bridge/cross rules also cover direct routes at their respective transport boundaries.</p> <p>Behavior: Match fields within one row are ANDed. Radio rows are matched against the same immutable receive-time packet, before any rule changes its scope. Bridge/cross rows match the packet at their admission boundary; a TX packet can already have an appended hop or rewritten scope. Each mode evaluates only its applicable rows, processed in descending <code>priority</code>. At equal numeric priority, authenticated channel matches precede raw hashes, which precede an unrestricted channel matcher; lower slot wins after that. The first matching <code>stop</code> row is included and all lower-order FPF7 matches are discarded. A stop cannot undo an earlier drop or bypass hard forwarding gates or the other policy phases. A row with <code>path=blacklist</code> must meet the path condition as well as its other conditions; blacklist IDs can occur anywhere in the received path and their configured order is irrelevant. In contrast, <code>prefix=</code> begins at the first received path entry and preserves order. A matching drop row prevents retransmission. The highest-order remaining matching scope/region row wins; matching drop and rate rows remain independent and can still block the rewritten packet. Scope rewriting happens before region enforcement and is trusted even when its name is absent from the local region list. It does not bypass <code>repeat</code>, <code>flood.max</code>, other drop rows, loop detection, or moderation.</p> <p>Retry selection uses that same ordered, stop-truncated match set. With at least one active <code>retry</code> row, a received flood starts a retry sequence only when one of those matching rows includes <code>retry</code>. This selector cannot override <code>flood.retry.count</code>, path/type attempt caps, <code>flood.retry.advert</code>, disabled forwarding, a drop decision, or any other hard forwarding gate. Locally originated floods retain the normal global retry behavior.</p> <p>With <code>require=region</code>, a failed check makes that scope row ineligible. It leaves the packet unchanged and does not set the filter-scope trust bypass, so an unknown or denied incoming region is rejected normally unless another independent scope rule rewrites it. Later eligible filter scope rows may still match.</p> <p>By default, when a scope row will change the packet's transport codes, the packet bypasses inbound <code>rxdelay</code>; its retransmission then uses zero <code>txdelay</code> and the highest outbound queue priority. With <code>tx=slow</code>, the rewrite instead uses an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, normal queue priority, and the maximum <code>txdelay</code> factor of <code>2.0</code>. The actual randomized transmit wait ranges from zero to ten packet airtimes. Selecting the scope already carried is a no-op and does not grant special treatment. An active radio transmission is not preempted, and CAD and airtime-budget limits still apply.</p> <p>The packet is still received and can still be logged. Rules are persistent data and can be changed over serial or authenticated remote CLI without an OTA or reboot. <code>flood.rule</code> and <code>flood.filter</code> address the same table on extended builds; FPF6 files are migrated in memory and the next save writes FPF7. FPF1-FPF5 files are rejected and filtering fails open. FPF7 stores canonical region names rather than transient numeric region IDs. Removing, reordering, or reusing a region ID therefore cannot silently retarget a rule. If a saved input or target region name is absent, that input match or rewrite is inert; restoring the same region name reactivates it. While either <code>tempradio</code> or <code>tempradio2</code> is active, only rows explicitly marked <code>suspend=tempradio</code> are skipped. Temporary radio is a radio state, not an OTA mode; normal payload types can also use the temporary channel. Other rows remain in force, and suspended rows resume after both temporary sessions end. A malformed persisted table fails open (no general rules are applied).</p> <p>Within one receive evaluation, rows that use the same channel key share one authentication result. The cache is discarded after that packet and stores neither plaintext nor passwords; different keys are authenticated separately. Raw <code>hash:XX</code> rows skip this authentication and compare only the one visible byte.</p> <p>Per-channel retry examples:</p> <pre><code># Use bridge-bucket retry only for authenticated Public and #hamradio traffic.\nset flood.retry.bridge on\nset flood.rule.2 type=any channel=public retry\nset flood.rule.3 type=any channel=#hamradio retry\n\n# If the channel key/name is unavailable, select visible channel hash A7.\n# This is an unauthenticated 1-byte hint, not a channel identity.\nset flood.rule.4 type=any channel=hash:A7 retry\n</code></pre> <p>Because Public's visible hash is <code>0x11</code>, a bare <code>hash:11 drop</code> row also matches Public. To exempt authenticated Public while dropping other packets that carry the same visible byte, put the exact Public rule first and stop lower-priority rules after it:</p> <pre><code># Retry and preserve authenticated Public; drop other channel-hash 11 packets.\nset flood.rule.2 type=any channel=public retry stop\nset flood.rule.3 type=any channel=hash:11 drop\n</code></pre> <p>The Public row matches only after its MAC/decrypt check succeeds. A colliding channel therefore misses that <code>stop</code> and reaches the raw-hash drop row. Both rows use the default numeric priority, but authenticated-channel specificity automatically orders Public first even if its slot number is higher. Without <code>stop</code>, both rows match Public and the sticky <code>drop</code> action wins. Omit <code>retry</code> from the Public row when only the forwarding exemption is wanted. An operator can deliberately reverse this order by assigning the hash row a higher numeric <code>priority</code>.</p> <p>Deleting or replacing the last active <code>retry</code> row restores the legacy global retry eligibility. Firmware that predates the <code>retry</code>/<code>hash:XX</code> FPF7 extension cannot preserve tables containing those rows; remove them before downgrading.</p> <p>Default rows: Repeater firmware and FULL ESP32 room-server firmware seed a new flood-filter table with <code>ota all suspend=tempradio</code> in slot 1. This blocks repeated LoRa OTA (<code>0x0C</code>) floods at every received hop unless either temporary radio profile is active. The OTA core independently refuses OTA receive, relay, and transmit outside temporary radio. The row is editable and deletable; once the table is saved, deletion is persistent. Restore the exact seeded row with:</p> <pre><code>set flood.filter.1 0x0C all suspend=tempradio\n</code></pre> <p>Omitting <code>all</code> is equivalent. Omit <code>.1</code> as well to reuse an identical rule or the first empty slot instead of replacing slot 1.</p> <p>Generalized repeaters also seed slot 2 with the authenticated <code>#wardriving</code> radio hop limit and slot 3 with the bridge/crossover block:</p> <pre><code>set flood.rule.2 type=any channel=#wardriving hops=5+ drop\nset flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>These numbered commands replace those slots. Saved tables are preserved on upgrade; use the unnumbered third command to add the new rule without replacing an occupied slot. See restoring the three defaults.</p> <p>Remote-admin lockout warning: There are no hidden payload-type or short-hop exceptions. FPF7 drop and rate rows may block <code>req</code>, <code>response</code>, <code>txt_msg</code>, <code>anon_req</code>, <code>path</code>, ACK, and multipart traffic beginning at hop <code>0</code> when their match fields say so. Transit repeaters cannot decrypt these outer types to distinguish an admin exchange from ordinary peer traffic. Keep a serial or other recovery path and stage broad deny/rate rules carefully.</p> <p>Without <code>.n</code>, <code>set</code> reuses an identical rule or uses the first empty slot. With <code>.n</code>, it replaces that slot, which is the intended way to change a row's match or action. <code>get flood.filter</code> or <code>get flood.rule</code> gives a compact list. Use the numbered form for full details, including channel, prefix, original-scope condition, action, timing, rate, and temporary-radio suspension.</p> <p><code>fr</code> is a shorter alias for <code>flood.rule</code>, with the same explicit-action requirement. Short and long field names can be mixed in either command:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nset fr.3 any c=#wardriving m=bc d\nget fr.3\n</code></pre> <p>The two setters above save the same row. <code>get fr.3</code> returns the complete short setter; <code>get fr</code> lists the table. Unnumbered <code>set fr ...</code> reuses an identical row or adds one to the first empty slot. <code>del fr.N</code> and <code>del fr all</code> have the same behavior as their long forms.</p> Full token Short token <code>type=...</code> Positional type or <code>t=...</code>; <code>*</code> means <code>any</code> <code>hops=...</code> Positional range or <code>h=...</code>; <code>*</code> means <code>all</code> <code>mode=radio/bridge/cross/bridge,cross</code> <code>m=r/b/c/bc</code> (choose one value) <code>channel=...</code>, <code>prefix=...</code> <code>c=...</code>, <code>p=...</code> <code>path=blacklist</code> <code>p=bl</code> (repeater only) <code>in=any/none/scoped/allowed/unknown</code> <code>i=*/n/s/a/u</code> (choose one value) <code>in=scope:name</code>, <code>in=region:name</code> <code>i=s:name</code>, <code>i=r:name</code> <code>drop</code>, <code>stop</code>, <code>retry</code> <code>d</code>, <code>s</code>, <code>r</code> <code>scope=name</code>, <code>region=name</code> <code>s=name</code>, <code>r=name</code> <code>rate=N/min</code>, <code>priority=N</code> <code>q=N</code>, <code>pri=N</code> <code>tx=slow</code>, <code>suspend=tempradio</code>, <code>retry</code> <code>f=s</code>, <code>f=t</code>, <code>f=r</code>; combine as <code>f=str</code> <p>All existing validation and permissions apply. <code>m=cb</code>, <code>m=b,c</code>, and <code>m=c,b</code> also mean bridge and crossover. Short aliases for <code>flood.channel.scope</code>, <code>flood.moderation</code>, and blacklist management are not added.</p> <p>The numbered long getters use this complete short setter when descriptive fields would exceed a reply. Defaults are omitted and specific payload types are printed numerically. If it still cannot fit, the reply is <code>Err - compact command exceeds reply size</code>, never a partial setter. Private channel keys are shown as <code>key:XXXXXXXX</code>; that reference can be reused while an active rule on the same device holds the key. Copying it to another device requires the original key, unless that device already has a matching rule. Unknown or ambiguous references are rejected. See the shorthand guide for examples.</p> <p>On generalized repeaters, filter rows, scope-rewrite rows, the shared blacklist, and <code>flood.channel.data</code> compatibility state are committed in one atomic FPF7 image. Compact FPF6 profiles retain separate files. Replacing or deleting the blacklist does not delete rows containing <code>path=blacklist</code>; such rows remain dormant while the list is empty. Path hashes are truncated routing identifiers, not authenticated identities, so this is a forwarding signal rather than proof that a particular repeater handled a packet.</p> <p>A common use is containment of bulk internet-to-mesh dumping: list the path IDs associated with the offending gateways, then add a broad <code>type=any hops=all path=blacklist drop</code> row. This prevents this repeater from retransmitting matching floods; it does not delete them from local logs or prove who originated them.</p> <p>The unnumbered blacklist <code>set</code> replaces the whole list and accepts up to 18 IDs so it fits every CLI transport. Numbered <code>set</code> writes up to 18 consecutive entries beginning at an existing slot or exactly the next slot, allowing an ESP32 list to grow to 255 entries in batches. Numbered deletion compacts subsequent slots. The unnumbered <code>get</code> reports the total and as many leading IDs as fit in one reply; use numbered <code>get</code> to inspect entries beyond that reply.</p> <p>Standard traceroute is direct-routed and therefore outside <code>flood.filter</code> entirely. A custom flood-form trace participates normally: <code>type=any</code>, explicit <code>trace</code>, rewrite, rate, drop, and stop rows can all apply.</p> <p>Examples:</p> <pre><code>set flood.rule.2 type=grp_data hops=4+ channel=#rgdata in=none scope=BlackHole86\nset flood.rule.3 type=grp_data channel=#rgdata in=scope:usa scope=BlackHole86\nset flood.rule.4 type=any prefix=860C rate=10/min\nset flood.rule.5 type=grp_data hops=0-2 channel=#rgdata priority=200 stop\nget flood.rule.2\nset flood.filter grp_data 4+\nset flood.filter.2 PAYLOAD_TYPE_ADVERT 6+\nset flood.filter ota 2-4\nset flood.filter.1 0x0C all suspend=tempradio\nset flood.filter grp_data all suspend=tempradio\nset flood.filter grp_txt all scope=local\nset flood.filter grp_data all scope=local require=region\nset flood.filter grp_data all path=blacklist scope=local tx=slow\nset flood.filter.blacklist A1B2C3,D4E5F6,112233\nset flood.filter.blacklist.4 445566\nset flood.filter.blacklist.19 778899,AABBCC,DDEEFF\nset flood.filter any all path=blacklist\nget flood.filter.blacklist\nget flood.filter.blacklist.4\nset flood.filter any 12+\nget flood.filter\nget flood.filter.2\ndel flood.filter.2\n</code></pre> <p>The first rule authenticates <code>#rgdata</code>, requires more than three received hops, and adds <code>#BlackHole86</code> only when no scope was present. The second rewrites the exact incoming <code>#usa</code> scope. The third demonstrates a two-byte pbyte source prefix and a global per-row rate cap. The fourth authenticates <code>#rgdata</code> at zero through two hops, applies no FPF7 action of its own, and stops lower-order FPF7 forward rows; hard gates and the rewrite/moderation phases still apply.</p> <p>The fixed 240 KB STM32WL profiles leave <code>MESH_ENABLE_FLOOD_RULE_ENGINE=0</code> and retain the compact, persistent FPF6 <code>flood.filter</code> and blacklist commands. They still filter floods, but do not expose the <code>flood.rule</code> alias or its extended channel, prefix, input-scope, region-action, or rate fields. No partition size changes are required.</p>"},{"location":"cli_commands/#moderate-flood-group-text-by-channel-sender-and-source-path","title":"Moderate flood group text by channel, sender, and source path","text":"<p>Usage: - <code>get flood.moderation</code> - <code>get flood.moderation.&lt;n&gt;</code> - <code>set flood.moderation &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]</code> - <code>set flood.moderation.&lt;n&gt; &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]</code> - <code>del flood.moderation.&lt;n&gt;</code> - <code>del flood.moderation all</code></p> <p>Parameters: - <code>n</code>: Moderation slot from <code>1</code> to <code>16</code>. - <code>channel</code>:   - <code>public</code>: Built-in Public channel.   - <code>#channel</code>: Derive the well-known hashtag-channel key.   - A 128-bit or 256-bit channel key in hex, for any other/private channel. - <code>sender</code>: Exact group-text display name. Matching is ASCII case-insensitive.   Quote names containing spaces, for example <code>\"Field User\"</code>. - <code>drop</code>: Do not forward matching messages. Equivalent to <code>rate=0/min</code>. - <code>rate=X/min</code>: Forward at most <code>X</code> matching messages per 60-second local   window. This option requires an exact sender rather than <code>*</code>. - <code>hops=N</code>: Do not forward a matching message whose received flood path count   is <code>N</code> or higher. <code>hops=all</code> removes this constraint. - <code>path=H1[,H2,H3]</code>: Match the start of the flood path. One to three hashes are   accepted; every hash must have the same 1-, 2-, or 3-byte width. - <code>path=*</code>: Match any source path (the default).</p> <p>At least one of <code>drop</code>, <code>rate=X/min</code>, or <code>hops=N</code> is required. Rate and hop limits can be combined. Rate counters are local to this repeater and rule, use a 60-second window beginning with the first matching message, and reset on reboot.</p> <p>Decode and identity behavior: Moderation applies only to flood <code>PAYLOAD_TYPE_GRP_TXT</code>. The repeater first checks the packet's channel-hash byte, then validates and decrypts with the configured key. It extracts the text before the first <code>:</code> from the standard <code>&lt;sender&gt;: &lt;message&gt;</code> plaintext. The channel key is stored locally but is never printed by <code>get</code>.</p> <p>The group-text sender is an unverified display name, not a public key. It can be spoofed. Combining it with the first one to three path hashes makes a more useful moderation signal, but path hashes are truncated and are not proof of the originating user. A path-qualified rule begins matching only after the packet contains all configured starting hops; it cannot identify a first hop on a zero-hop packet.</p> <p>As with general filtering, matching messages are still received/logged; only retransmission is denied. There are no moderation rules by default.</p> <p>Examples:</p> <pre><code>set flood.moderation public \"Noisy User\" rate=5/min\nset flood.moderation #local bot drop path=A1B2C3,D4E5F6\nset flood.moderation.3 00112233445566778899AABBCCDDEEFF alice rate=10/min hops=4 path=71CE82\nget flood.moderation\nget flood.moderation.3\ndel flood.moderation.3\n</code></pre>"},{"location":"cli_commands/#acl","title":"ACL","text":""},{"location":"cli_commands/#add-update-or-remove-permissions-for-a-companion","title":"Add, update or remove permissions for a companion","text":"<p>Usage:  - <code>setperm &lt;pubkey&gt; &lt;permissions&gt;</code></p> <p>Parameters: - <code>pubkey</code>: Companion public key - <code>permissions</code>:    - <code>0</code>: Guest   - <code>1</code>: Read-only   - <code>2</code>: Read-write   - <code>3</code>: Admin   - <code>4</code>: Region/scope manager (repeater delegated region and forced-scope management)   - <code>5</code>: Filter manager (repeater delegated forwarding-filter management)</p> <p>Filter manager scope: Permission <code>5</code> can use an explicit allowlist of non-secret operational/filter status commands and can change the forwarding controls <code>repeat</code>, <code>loop.detect</code>, <code>flood.max*</code>, <code>flood.channel.data*</code>, <code>flood.filter*</code>, <code>flood.rule*</code>, <code>fr[.N]</code>, and <code>flood.moderation*</code>. It cannot read guest, WiFi, MQTT, bridge, or other credentials, and it cannot change regions, ACL entries, radio settings, or other admin configuration. Permission <code>4</code> is limited to region commands, <code>flood.channel.scope*</code>, and the same non-secret status allowlist. Both delegated manager roles are protected from least-recently-active ACL eviction like administrators.</p> <p>Note: Removes the entry when <code>permissions</code> is omitted</p>"},{"location":"cli_commands/#view-the-current-acl","title":"View the current ACL","text":"<p>Usage:</p> <ul> <li><code>get acl</code> - full listing locally; first page over LoRa</li> <li><code>get acl &lt;page&gt;</code> - a numbered page, starting at 1, locally or over LoRa</li> </ul> <p>Available on repeaters, room servers, and sensors. Over LoRa, an authenticated admin session is required; guests, read-only/read-write clients, and delegated region/filter managers cannot read the ACL.</p> <p>Each page starts with <code>ACL &lt;page&gt;/&lt;pages&gt;</code> and contains up to two entries. Each entry is a two-digit hexadecimal permission byte followed by the full 64-character public key. For example, use <code>get acl 2</code> for the second page. An empty list returns <code>ACL: empty</code>. Deleted/guest entries with permission byte <code>00</code> are omitted, matching the local listing. Pages reflect the current live ACL, so entries can move between pages if permissions or clients change.</p> <p>Bare <code>get acl</code> keeps the full streamed listing on USB and direct network CLI, or via Companion binary command <code>0x42</code> where the role supports the command. The listing contains public keys and permissions, not passwords or shared secrets, and does not change the ACL.</p>"},{"location":"cli_commands/#recover-a-repeaters-future-dated-replay-timestamp","title":"Recover a repeater's future-dated replay timestamp","text":"<p>This is an explicit recovery operation after correcting a bad clock, not a contact deletion. It lowers selected replay timestamps to the repeater's current UTC epoch only when they are later than that epoch. Earlier values, public keys, permissions, stored paths, and historical identity records remain. The replay file is committed before the live table changes. No extra 60-second login reservation is added by this command.</p> <p>First set/synchronize and verify the repeater's clock (<code>clock</code>); a build-default clock without a manual or observed synchronization is not accepted. Also fix the companion's clock before its next login.</p> <p>USB console:</p> <pre><code>replay reset &lt;full-64-hex-public-key&gt;\nreplay reset all CONFIRM\n</code></pre> <p>Authenticated LoRa admin, including a resumed admin session:</p> <pre><code>replay reset &lt;full-64-hex-public-key&gt;\n</code></pre> <p>The reply shows <code>now=&lt;epoch&gt;</code>, <code>ttl=&lt;remaining-seconds&gt;s</code>, and a confirmation command containing the same full key and a one-use 32-hex-character token. Verify the displayed time and send that command before the original 300-second deadline. During the first 120 seconds, repeated requests for the same key by the same admin return the same token without restarting either timer. From 120 through 300 seconds, the token is retained for confirmation only: requests do not resend or replace it. This leaves at least 180 seconds to deliver a confirmation after the last permitted token response is generated (radio transit time still counts toward expiry). At 300 seconds it expires and a new request can receive a new token. Confirmation can succeed immediately; there is no requirement to wait for the resend window to close. The displayed TTL decreases on retries and is measured when the reply is generated, not when it reaches the companion.</p> <p>It can target the caller's own key or another exact key; prefixes, <code>self</code>, wildcards, and <code>all</code> are not allowed over LoRa. Tokens are bound to both the requesting admin and target, expire on reboot, and are invalid after use or a clock correction outside the five-second confirmation tolerance. A failed write requires a new confirmation. Challenge requests consult live token state instead of replaying cached challenge text; completed confirmation results remain cacheable without executing the reset again. Normal packet freshness checks still apply to retries.</p> <p>Only the physical serial console grants <code>all</code> access. Ethernet, browser and internal command callbacks do not count as USB. Guest, read-only, region-manager and filter-manager roles cannot reset replay state. This command is implemented in repeater firmware; room-server and sensor CLI are unchanged.</p> <p>Normal login and command admission checks remain in force: a fully locked-out caller that cannot send an accepted admin command needs another working admin or USB access. A corrupt/unreadable replay file fails closed and is not erased or formatted by this operation. Unknown keys do not create records.</p> <p>Security trade-off: lowering a replay boundary can admit previously captured future-dated login/command packets above the new boundary, including packets that could raise it again. The one-use token prevents the recovery command itself from being repeatedly executed; it does not replace the protocol's timestamp-based replay protection. Use recovery only after verifying clocks. Setting a clock alone never automatically resets this table.</p>"},{"location":"cli_commands/#view-or-change-this-room-servers-read-only-flag","title":"View or change this room server's 'read-only' flag","text":"<p>Usage: - <code>get allow.read.only</code> - <code>set allow.read.only &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code> (enable) or <code>off</code> (disable)</p> <p>Default: <code>off</code></p> <p>Make a room read-only while allowing selected writers:</p> <pre><code>set allow.read.only on\nsetperm &lt;PUBKEY_USER_1&gt; 2\n</code></pre> <p>With read-only mode on, a client without a valid room password can join as a read-only guest. Permission <code>2</code> gives the specified public key read-write access. Replace <code>&lt;PUBKEY_USER_1&gt;</code> with the user's full public key and repeat <code>setperm</code> for every approved writer.</p> <p>This does not remove write access from clients that already know the room password. Keep that password private, or replace it, if write access should be limited to the explicitly permitted users.</p>"},{"location":"cli_commands/#region-management-v110","title":"Region Management (v1.10.+)","text":""},{"location":"cli_commands/#bulk-load-region-lists","title":"Bulk-load region lists","text":"<p>Usage:  - <code>region load</code> - <code>region load &lt;name&gt; [flood_flag]</code></p> <p>Parameters: - <code>name</code>: A name of a region. <code>*</code> represents the wildcard region</p> <p>Note: <code>flood_flag</code>: Optional <code>F</code> to allow flooding</p> <p>Note: Indentation creates parent-child relationships (max 8 levels)</p> <p>Note: <code>region load</code> with an empty name will not work remotely (it's interactive)</p>"},{"location":"cli_commands/#save-any-changes-to-regions-made-since-reboot","title":"Save any changes to regions made since reboot","text":"<p>Usage:  - <code>region save</code></p>"},{"location":"cli_commands/#allow-a-region","title":"Allow a region","text":"<p>Usage:  - <code>region allowf &lt;name&gt;</code></p> <p>Parameters:  - <code>name</code>: Region name (or <code>*</code> for wildcard)</p> <p>Note: Setting on wildcard <code>*</code> allows packets without region transport codes</p>"},{"location":"cli_commands/#block-a-region","title":"Block a region","text":"<p>Usage:  - <code>region denyf &lt;name&gt;</code></p> <p>Parameters:  - <code>name</code>: Region name (or <code>*</code> for wildcard)</p> <p>Note: Setting on wildcard <code>*</code> drops packets without region transport codes</p>"},{"location":"cli_commands/#show-information-for-a-region","title":"Show information for a region","text":"<p>Usage:  - <code>region get &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Region name (or <code>*</code> for wildcard)</p>"},{"location":"cli_commands/#view-or-change-the-home-region-for-this-node","title":"View or change the home region for this node","text":"<p>Usage:  - <code>region home</code> - <code>region home &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Region name</p>"},{"location":"cli_commands/#view-or-change-the-default-scope-region-for-this-node","title":"View or change the default scope region for this node","text":"<p>Usage:  - <code>region default</code> - <code>region default {name|&lt;null&gt;}</code></p> <p>Parameters: - <code>name</code>: Region name,  or  to reset/clear"},{"location":"cli_commands/#create-a-new-region","title":"Create a new region","text":"<p>Usage:  - <code>region put &lt;name&gt; [parent_name]</code></p> <p>Parameters: - <code>name</code>: Region name - <code>parent_name</code>: Parent region name (optional, defaults to wildcard)</p> <p>Note: In firmware v1.15.0 and later, <code>region put</code> enables flooding for that region by default (you do not need a separate <code>region allowf &lt;name&gt;</code> after each <code>put</code>). On v1.14.0 and earlier, new regions may still require <code>region allowf</code> for flooding-see <code>region allowf</code>.</p>"},{"location":"cli_commands/#define-region-hierarchy-single-line","title":"Define region hierarchy (single line)","text":"<p>Usage: - <code>region def &lt;token&gt; [&lt;token&gt; ...]</code></p> <p>Parameters (tokens): Space-separated. A logical cursor starts at the wildcard <code>*</code>.</p> <ul> <li><code>name</code> - Create <code>name</code> as a child of the current cursor (equivalent to <code>region put name</code> with the cursor as parent). Cursor moves to <code>name</code>.</li> <li><code>name|jump</code> (or <code>name,jump</code>) - Create <code>name</code> as a child of the current cursor, then move the cursor to <code>jump</code> (must already exist on the node, or have been created earlier in this command). <code>jump</code> is not the parent of <code>name</code>; use this form to pop back up and start another branch.</li> </ul> <p>Behavior: Each created region defaults to flood-allowed (same as <code>region put</code>). The reply is the resulting region tree (same format as bare <code>region</code>); review it before running <code>region save</code> to persist. The command is transactional: invalid names, unknown or ambiguous jumps, table overflow, and hierarchy cycles return <code>Err - ...</code> without changing the existing tree.</p> <p>Existing regions: <code>region def</code> does not clear the existing tree - if a name already exists, its parent is updated to the current cursor; otherwise a new region is created. To start from scratch, <code>region remove</code> the unwanted regions first.</p> <p>Limits: Repeater serial accepts one line up to 160 characters. For larger trees, split across multiple <code>region def</code> commands; the cursor resets to <code>*</code> between commands, so lead the next command with <code>child|ancestor</code> to reposition. Each token splits at most once on <code>|</code> - <code>region def a|b|c|d</code> is not a flat-list shorthand; see the flat-list example below.</p> <p>Example - linear chain (each token becomes a child of the previous):</p> <pre><code>region def a b c d e\nregion save\n</code></pre> <p>Example - branched tree (equivalent to <code>region put a</code>, <code>region put b a</code>, <code>region put c b</code>, <code>region put d c</code>, <code>region put e b</code>, <code>region put f e</code>):</p> <pre><code>region def a b c d|b e f\nregion save\n</code></pre> <p>Example - transactional error:</p> <pre><code>region def a b c|nope d\n</code></pre> <p>The reply is <code>Err - unknown or ambiguous jump: nope</code>. The existing tree is unchanged; re-run with a corrected jump.</p> <p>Example - flat list (each region a child of <code>*</code>). Use <code>|*</code> after each token to pop the cursor back to the root before the next token:</p> <pre><code>region def a|* b|* c|* d|* e|* f\nregion save\n</code></pre>"},{"location":"cli_commands/#remove-a-region","title":"Remove a region","text":"<p>Usage:  - <code>region remove &lt;name&gt;</code></p> <p>Parameters: - <code>name</code>: Region name</p> <p>Note: Must remove all child regions before the region can be removed </p>"},{"location":"cli_commands/#view-all-regions","title":"View all regions","text":"<p>Usage:  - <code>region list &lt;filter&gt;</code></p> <p>Serial Only: Yes</p> <p>Parameters: - <code>filter</code>: <code>allowed</code>|<code>denied</code></p> <p>Note: Requires firmware 1.12+</p>"},{"location":"cli_commands/#dump-all-defined-regions-and-flood-permissions","title":"Dump all defined regions and flood permissions","text":"<p>Usage:  - <code>region</code></p> <p>Serial Only: For firmware older than 1.12.0</p>"},{"location":"cli_commands/#region-examples","title":"Region Examples","text":"<p>Example 1: Using F Flag with Named Public Region</p> <pre><code>region load\n#Europe F\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates a region named <code>#Europe</code> with flooding enabled - Packets from this region will be flooded to other nodes</p> <p>Example 2: Using Wildcard with F Flag</p> <pre><code>region load \n* F\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates a wildcard region <code>*</code> with flooding enabled - Enables flooding for all regions automatically - Applies only to packets without transport codes</p> <p>Example 3: Using Wildcard Without F Flag</p> <pre><code>region load \n*\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates a wildcard region <code>*</code> without flooding - This region exists but doesn't affect packet distribution - Used as a default/empty region</p> <p>Example 4: Nested Public Region with F Flag</p> <pre><code>region load \n#Europe F\n  #UK\n    #London\n    #Manchester\n  #France\n    #Paris\n    #Lyon\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates <code>#Europe</code> region with flooding enabled - Adds nested child regions (<code>#UK</code>, <code>#France</code>) - All nested regions inherit the flooding flag from parent</p> <p>Example 5: Wildcard with Nested Public Regions</p> <pre><code>region load \n* F\n  #NorthAmerica\n    #USA\n      #NewYork\n      #California\n    #Canada\n      #Ontario\n      #Quebec\n&lt;blank line to end region load&gt;\nregion save\n</code></pre> <p>Explanation: - Creates wildcard region <code>*</code> with flooding enabled - Adds nested <code>#NorthAmerica</code> hierarchy - Enables flooding for all child regions automatically - Useful for global networks with specific regional rules</p>"},{"location":"cli_commands/#direct-retry","title":"Direct Retry","text":"<p>Direct retry resends direct-routed packets when the downstream echo is not heard. It applies to direct messages, ACK packets, multipart packets carrying ACK payloads, and TRACE packets.</p> <p>The shared state, count, base, and step controls work on repeater, room-server, and sensor firmware. Recent-repeater/SNR controls are repeater-only because the other roles do not keep the repeater reachability table they require.</p>"},{"location":"cli_commands/#view-or-change-direct-retry-state","title":"View or change direct retry state","text":"<p>Search terms: enable tx retries, disable tx retries, stop direct retries, turn off retransmissions.</p> <p>Usage: - <code>get direct.retry</code> - <code>set direct.retry &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>on</code></p> <p>Notes: - New installs and older preference files without direct retry settings default to <code>on</code> with the <code>rooftop</code> preset.</p> <p>Examples:</p> <pre><code>get direct.retry\nset direct.retry on\nset direct.retry off\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-heard-table-gate","title":"View or change direct retry heard-table gate","text":"<p>Usage: - <code>get direct.retry.heard</code> - <code>set direct.retry.heard &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>on</code></p> <p>Note: This command is repeater-only. When enabled, the recent repeater table is the direct retry eligibility gate. Prefixes missing from the table are assumed reachable; prefixes in the table below the active SNR gate are blocked.</p> <p>Examples:</p> <pre><code>get direct.retry.heard\nset direct.retry.heard on\nset direct.retry.heard off\n</code></pre>"},{"location":"cli_commands/#view-or-apply-a-retry-preset","title":"View or apply a retry preset","text":"<p>Search terms: retry profile, retry defaults, rooftop retries, mobile retries, infrastructure retries.</p> <p>Usage: - <code>get retry.preset</code> - <code>set retry.preset &lt;preset&gt;</code></p> <p>Parameters: - <code>preset</code>: <code>infra</code>|<code>rooftop</code>|<code>mobile</code></p> <p>Notes: - Applies shared direct retry and flood retry defaults. - <code>infra</code>: fewer, slower retries for stable fixed infrastructure. - <code>rooftop</code>: default long retry window for weak rooftop links. - <code>mobile</code>: long retry count with shorter spacing for moving or changing links; flood retry count is <code>15</code>. - Changing <code>direct.retry.count</code>, <code>direct.retry.base</code>, <code>direct.retry.step</code>, <code>direct.retry.margin</code>, <code>flood.retry.count</code>, <code>flood.retry.path</code>, or <code>flood.retry.group.path</code> makes the preset report as <code>custom</code>.</p> <p>Examples:</p> <pre><code>get retry.preset\nset retry.preset infra\nset retry.preset rooftop\nset retry.preset mobile\n</code></pre>"},{"location":"cli_commands/#flood-retry","title":"Flood Retry","text":"<p>Flood retry resends flood-routed packets when the same packet is not heard from another qualifying repeater.</p> <p>The count, path, group-data path, and advert controls work on repeater, room-server, and sensor firmware. Flood forwarding must also be enabled for retries to run. Prefix, ignore, bridge, and bucket controls are repeater-only.</p>"},{"location":"cli_commands/#hop-zero-flood-retry-coding-rate","title":"Hop-zero flood retry coding rate","text":"<p>Flood packets with no path hops recorded yet use the same CR escalation ladder as direct retries. The starting point is the active radio CR, since a flood has no single next-hop repeater whose SNR can select a starting CR. Each retry uses its attempt number and the active radio setting; it does not restart the ladder from the previous retry's override. Forwarded packets with one or more recorded hops use the active radio CR on every retry, including bridge retries whose effective path length discounts ignored hops.</p> <p>The initial transmission uses the active radio CR. This table lists retries after that initial transmission; any later retries remain at CR8:</p> Starting CR Retry 1 Retry 2 Retry 3 Retry 4 Retry 5+ CR4 CR4 CR5 CR7 CR7 CR8 CR5 CR5 CR7 CR7 CR8 CR8 CR6 CR6 CR7 CR7 CR8 CR8 CR7 CR7 CR7 CR8 CR8 CR8 CR8 CR8 CR8 CR8 CR8 CR8 <p>The ladder is shared across presets. Presets change the retry budget, not the CR steps. At CR5, the maximum hop-zero schedules are:</p> Preset Configured flood count Hop-zero retries CR schedule after the initial send <code>infra</code> 1 2 CR5, CR7 <code>rooftop</code> 3 6 CR5, CR7, CR7, CR8, CR8, CR8 <code>mobile</code> 15 15 CR5, CR7, CR7, then CR8 for retries 4-15 <p>These budgets apply to group text and the origin login/message family (<code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, <code>PATH</code>). Existing payload caps, echo cancellation, and retry eligibility still apply: <code>REQ</code> and OTA do not use generic flood retries; other payloads allow at most one retry. An eligible advert at CR5 therefore gets only its first CR5 retry.</p> <p><code>set flood.retry.count 0</code> continues to disable all automatic flood retries, including hop zero. It leaves the initial transmission and all direct-retry settings and CR schedules unchanged. Direct retry's <code>direct.retry.cr</code> switch and SNR thresholds continue to control direct retries only. Per-packet CR overrides are restored after transmission and do not change the saved radio setting or physical preamble.</p>"},{"location":"cli_commands/#view-or-change-flood-retry-count","title":"View or change flood retry count","text":"<p>Search terms: flood tx retries, flood retry attempts, flood retransmissions, broadcast retries.</p> <p>Usage: - <code>get flood.retry.count</code> - <code>set flood.retry.count &lt;count&gt;</code></p> <p>Parameters: - <code>count</code>: Base retry attempts after the original send, from <code>0</code> to <code>15</code>. <code>0</code> disables flood retry.</p> <p>Note: The role first calculates its retry count: path count 0 uses <code>count * 2</code>, path count 1 uses <code>count * 1.5</code> rounded up, and path count 2 and higher uses the configured base count, with a hard cap of <code>15</code>. A shared payload policy then applies to every build: <code>REQ</code> never retries; <code>GRP_TXT</code> keeps the role-calculated count; remote-login-critical <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code> packets keep up to <code>15</code> at the originating node (path count 0) and cap at <code>2</code> after entering the path; all other flood payload types cap at <code>1</code>. These caps never raise a lower role-calculated count. Setting <code>count</code> to <code>0</code> immediately removes queued and future flood retries; a packet already transmitting is allowed to finish.</p> <p>Forwarded neighbor adverts have an additional loop guard independent of the advert retry setting. After this node completes an advert transmission and hears a downstream copy with a longer path, it does not forward that same advert again while the advert's signed timestamp is less than six hours old. Self-originated adverts, adverts without a heard echo, and adverts six hours old or older are unaffected.</p> <p>An enabled self-originated advert retry waits at least one additional minute beyond the normal airtime-aware retry delay. Once a newer self advert has successfully entered the outbound queue, its retry sequence replaces queued or future retries for older self adverts; an older advert already transmitting is allowed to finish. Companion firmware permits this single slow retry for its own adverts while continuing to block retry attempts for neighbor adverts it forwards.</p> <p>Defaults: - <code>infra</code>: <code>1</code> - <code>rooftop</code>: <code>3</code> - <code>mobile</code>: <code>15</code></p> <p>Examples:</p> <pre><code>get flood.retry.count\nset flood.retry.count 0\nset flood.retry.count 15\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-path-gate","title":"View or change flood retry path gate","text":"<p>Usage: - <code>get flood.retry.path</code> - <code>set flood.retry.path &lt;count|off&gt;</code></p> <p>Parameters: - <code>count</code>: Maximum flood path hash count eligible for retry, from <code>0</code> to <code>63</code>. - <code>off</code>: Disable the path-length gate.</p> <p>Defaults: - <code>infra</code>: <code>1</code> - <code>rooftop</code>: <code>2</code> - <code>mobile</code>: <code>1</code></p> <p>Examples:</p> <pre><code>get flood.retry.path\nset flood.retry.path 1\nset flood.retry.path off\n</code></pre>"},{"location":"cli_commands/#view-or-change-the-group-data-flood-retry-path-gate","title":"View or change the group-data flood retry path gate","text":"<p>Usage: - <code>get flood.retry.group.path</code> - <code>set flood.retry.group.path &lt;count|off&gt;</code></p> <p>Parameters: - <code>count</code>: Maximum flood path hash count eligible for retry for group data packets (<code>PAYLOAD_TYPE_GRP_DATA</code>/type 6), from <code>0</code> to <code>63</code>. - <code>off</code>: Disable only the group-data-specific gate. The general <code>flood.retry.path</code> gate still applies.</p> <p>Default: <code>1</code> for <code>infra</code>, <code>rooftop</code>, and <code>mobile</code> presets.</p> <p>Note: The stricter of <code>flood.retry.path</code> and <code>flood.retry.group.path</code> is used. A value of <code>1</code> allows retry sequences at path counts <code>0</code> and <code>1</code>; group data at path count <code>2</code> or higher is still forwarded normally but does not start a flood retry sequence. A value of <code>0</code> allows retries only at the originating sender.</p> <p>Setting <code>flood.retry.path</code> to <code>0</code> also sets <code>flood.retry.group.path</code> to <code>off</code> because the general zero-hop gate is already stricter. While the general gate remains <code>0</code>, attempts to set the group-data gate keep it <code>off</code>. Applying a named retry preset restores the group-data default of <code>1</code>.</p> <p>Examples:</p> <pre><code>get flood.retry.group.path\nset flood.retry.group.path 1\nset flood.retry.group.path off\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-advert-handling","title":"View or change flood retry advert handling","text":"<p>Usage: - <code>get flood.retry.advert</code> - <code>set flood.retry.advert &lt;on|off&gt;</code></p> <p>Parameters: - <code>on</code>: Retry node advert floods. - <code>off</code>: Do not retry node advert floods.</p> <p>Default: <code>off</code></p> <p>Examples:</p> <pre><code>get flood.retry.advert\nset flood.retry.advert off\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-target-prefixes","title":"View or change flood retry target prefixes","text":"<p>Usage: - <code>get flood.retry.prefixes</code> - <code>set flood.retry.prefixes &lt;prefixes|none|off&gt;</code></p> <p>Parameters: - <code>prefixes</code>: Comma-separated 3-byte path hash prefixes, up to 8 entries. - <code>none</code> or <code>off</code>: Clear the list.</p> <p>Note: When set, non-bridge flood retry only accepts same-packet echoes whose last hop matches one of these prefixes. When unset, any non-ignored last hop can cancel the retry.</p> <p>Examples:</p> <pre><code>get flood.retry.prefixes\nset flood.retry.prefixes A58296,860CCA,425E5C\nset flood.retry.prefixes none\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-ignored-prefixes","title":"View or change flood retry ignored prefixes","text":"<p>Usage: - <code>get flood.retry.ignore</code> - <code>set flood.retry.ignore &lt;prefixes|none|off&gt;</code></p> <p>Parameters: - <code>prefixes</code>: Comma-separated 3-byte path hash prefixes, up to 8 entries. - <code>none</code> or <code>off</code>: Clear the list.</p> <p>Note: Non-bridge flood retry does not cancel on same-packet echoes whose last hop matches this list. Bridge mode also excludes these prefixes from bucket and <code>other</code> hits.</p> <p>Examples:</p> <pre><code>get flood.retry.ignore\nset flood.retry.ignore 71CE82,C7618C\nset flood.retry.ignore none\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-bridge-mode","title":"View or change flood retry bridge mode","text":"<p>Usage: - <code>get flood.retry.bridge</code> - <code>set flood.retry.bridge &lt;on|off&gt;</code></p> <p>Note: Bridge mode retries until each configured fresh bucket, plus the non-source <code>other</code> bucket, has been heard or the retry count is exhausted. If prefixes in different buckets share their first byte, configuration commands return a warning because a 1-byte path cannot distinguish those buckets. The configuration remains valid: an ambiguous source is treated as belonging to every matching source bucket, and an ambiguous echo credits every matching target bucket so it cannot force retry exhaustion.</p> <p>Flood retry timing retains its fixed maximum-frame plus 20 packet-airtime wait, then adds a random <code>0-200%</code> of one additional packet airtime on every attempt. This de-synchronizes repeaters that may have missed the same echo while capping the added wait at two frames.</p> <p>Only one active retry sequence is kept for a given logical flood packet. An identical flood can still transmit normally, but it does not create a second sequence of extra attempts. Retry state is released if a queued packet is evicted, and the final echo window retains metadata without reserving a packet-pool entry.</p> <p>Bridge reachability learned from earlier hops in a successful echo is cached separately from <code>recent.repeater</code>. Only the final RF hop updates <code>recent.repeater</code> and its SNR, so indirect path entries cannot affect direct-retry SNR gating or coding-rate selection.</p> <p>Examples:</p> <pre><code>get flood.retry.bridge\nset flood.retry.bridge on\n</code></pre>"},{"location":"cli_commands/#view-or-change-flood-retry-bridge-buckets","title":"View or change flood retry bridge buckets","text":"<p>Usage: - <code>get flood.retry.bucket.&lt;n&gt;</code> - <code>set flood.retry.bucket &lt;n&gt; &lt;prefixes|none|off&gt;</code></p> <p>Parameters: - <code>n</code>: Bucket number from <code>1</code> to <code>6</code>. - <code>prefixes</code>: Comma-separated 3-byte path hash prefixes, up to 17 entries per bucket. - <code>none</code> or <code>off</code>: Clear the bucket.</p> <p>Examples:</p> <pre><code>get flood.retry.bucket.1\nset flood.retry.bucket 1 71CE82,C7618C\nset flood.retry.bucket 2 none\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-count","title":"View or change direct retry count","text":"<p>Search terms: tx retries, transmit retries, direct retries, retry count, retry attempts, retransmission count, message retries, DM retries.</p> <p>Usage: - <code>get direct.retry.count</code> - <code>set direct.retry.count &lt;count&gt;</code></p> <p>Parameters: - <code>count</code>: Maximum retry attempts after the original send, from <code>1</code> to <code>15</code>.</p> <p>Default: <code>15</code> with the <code>rooftop</code> preset</p> <p>Note: This setting limits retries for eligible direct-routed packets such as traces, requests, responses, and ACKs. Direct-routed text messages (type 2) are an exception: they allow up to 21 retries after the original send, regardless of <code>direct.retry.count</code> or the repeater short-path cap. For example, <code>set direct.retry.count 1</code> limits eligible non-text packets to one retry, but does not reduce the text-message limit.</p> <p>These are maximums, not a fixed number of transmissions. Retries stop early when the node hears the next hop forward the packet. The special final-hop retry sends only one duplicate because the destination does not forward the packet. Repeater non-text retries are also capped at 8 for a retry path of up to 3 hops, 12 for 4 hops, and 15 for longer paths; these caps never increase a lower configured count.</p> <p>Use <code>set direct.retry off</code> to disable this node's direct retries, including text-message retries, and <code>set direct.retry on</code> to enable them again. A count of <code>0</code> is not supported. Sending apps and other nodes may have their own retry behavior; this setting does not change it.</p> <p>Examples:</p> <pre><code>get direct.retry.count\nset direct.retry.count 1\nset direct.retry.count 4\nset direct.retry.count 15\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-base-delay","title":"View or change direct retry base delay","text":"<p>Search terms: retry delay, retry timeout, retransmission timeout, wait between retries.</p> <p>Usage: - <code>get direct.retry.base</code> - <code>set direct.retry.base &lt;ms&gt;</code></p> <p>Parameters: - <code>ms</code>: First retry wait in milliseconds, from <code>10</code> to <code>5000</code>.</p> <p>Default: <code>175</code> with the <code>rooftop</code> preset</p> <p>Explanation: - The first retry waits for <code>base + packet-length add-on + random forwarding jitter</code>   after the preceding transmission completes. - TRACE and   ANON_REQ/type 7 packets use a 3x line-time add-on. TXT_MSG/type 2   packets use 7x. Other direct retry packets use 6x. - Room-server and sensor firmware use this configured base with the same   packet-type add-ons. - Larger values reduce channel pressure and give slow repeaters more time. - Smaller values recover faster but create tighter retry bursts.</p> <p>Examples:</p> <pre><code>get direct.retry.base\nset direct.retry.base 175\nset direct.retry.base 275\nset direct.retry.base 500\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-step-delay","title":"View or change direct retry step delay","text":"<p>Search terms: retry backoff, increasing retry delay, retry interval step.</p> <p>Usage: - <code>get direct.retry.step</code> - <code>set direct.retry.step &lt;ms&gt;</code></p> <p>Parameters: - <code>ms</code>: Extra milliseconds added for each subsequent retry, from <code>0</code> to <code>5000</code>.</p> <p>Default: <code>100</code> with the <code>rooftop</code> preset</p> <p>Explanation: - Retry delay is <code>base + packet-length add-on + random forwarding jitter + attempt_index * step</code>. - TRACE and ANON_REQ/type 7 packets   use a 3x packet-length add-on. TXT_MSG/type 2 packets use 7x.   Other direct retry packets use 6x. - Room-server and sensor firmware use this configured step with the same   packet-type add-ons. - With <code>base=175</code> and <code>step=100</code>, the fixed portion is <code>175</code>, <code>275</code>, <code>375</code>,   <code>475</code> ms, and so on, before the packet-length add-on and random jitter. - <code>step=0</code> keeps every retry at the same delay. - Larger steps spread retries over time and are safer on busy channels.</p> <p>Examples:</p> <pre><code>get direct.retry.step\nset direct.retry.step 0\nset direct.retry.step 50\nset direct.retry.step 100\nset direct.retry.step 250\n</code></pre>"},{"location":"cli_commands/#view-or-change-direct-retry-snr-margin","title":"View or change direct retry SNR margin","text":"<p>Search terms: retry signal threshold, retry SNR threshold, retry signal margin.</p> <p>Usage: - <code>get direct.retry.margin</code> - <code>set direct.retry.margin &lt;snr_db&gt;</code></p> <p>Parameters: - <code>snr_db</code>: Extra SNR margin above the SF receive floor, from <code>0</code> to <code>40</code>.</p> <p>Default: <code>5.00</code> with the <code>rooftop</code> preset</p> <p>Notes: - This command is repeater-only. - Unknown repeaters are still retried. - Known repeaters below the receive floor plus this margin are skipped. - Failed attempts lower the recent repeater SNR estimate by <code>0.25 dB</code>.</p> <p>Examples:</p> <pre><code>get direct.retry.margin\nset direct.retry.margin 0\nset direct.retry.margin 2.5\nset direct.retry.margin 5\nset direct.retry.margin 10\n</code></pre>"},{"location":"cli_commands/#view-or-change-adaptive-direct-retry-coding-rate","title":"View or change adaptive direct retry coding rate","text":"<p>Usage: - <code>get direct.retry.cr</code> - <code>set direct.retry.cr off</code> - <code>set direct.retry.cr on</code> (room-server and sensor) - <code>set direct.retry.cr &lt;cr4_min&gt;,&lt;cr5_min&gt;,&lt;cr7_min&gt;,&lt;cr8_max&gt;</code></p> <p>Parameters: - <code>cr4_min</code>: Minimum SNR in dB to retry at CR4. - <code>cr5_min</code>: Minimum SNR in dB to retry at CR5. - <code>cr7_min</code>: Minimum SNR in dB to retry at CR7. - <code>cr8_max</code>: Maximum SNR in dB that forces CR8.</p> <p>Default: <code>10.00,7.50,2.50,2.50</code></p> <p>Explanation: - Higher SNR uses faster coding rates. - Lower SNR uses more robust coding rates. - Repeater retry attempts escalate from the adaptive starting CR. CR4 starts as CR4, CR5, CR7, CR7, then CR8. CR5 starts as CR5, CR7, CR7, then CR8. CR7 gets two attempts, then CR8. - Repeater adaptive CR selection intentionally skips CR6. - Non-repeater retry packets start at the current radio CR and follow the same escalation pattern, clamped at CR8. With the normal CR5 radio setting this is CR5, CR7, CR7, then CR8. - Room-server and sensor firmware accept <code>on</code> or <code>off</code>; numeric SNR thresholds   are repeater-only because those roles do not keep recent-repeater SNR data. - <code>off</code> disables per-packet direct-retry CR overrides and uses the current radio CR. - Retry packets may use a different coding rate, but they keep the radio's normal physical preamble. - Unknown repeaters start at <code>+3.00 dB</code> for adaptive CR selection. - A failed unknown repeater is seeded at <code>+2.75 dB</code>. - Each later failure lowers the SNR estimate by <code>0.25 dB</code>.</p> <p>Examples:</p> <pre><code>get direct.retry.cr\nset direct.retry.cr off\nset direct.retry.cr on\nset direct.retry.cr 10.0,7.5,2.5,2.5\nset direct.retry.cr 12.0,8.0,4.0,1.0\nset direct.retry.cr 8.0,5.0,1.5,0\nset direct.retry.cr 6.0,3.0,0,-2.0\nset direct.retry.cr 20.0,12.0,6.0,2.0\nset direct.retry.cr 4.0,2.0,0,-4.0\n</code></pre> <p>Example profiles: - Conservative weak-link profile:</p> <pre><code>set direct.retry.cr 12.0,8.0,4.0,1.0\n</code></pre> <ul> <li>Balanced rooftop profile:</li> </ul> <pre><code>set direct.retry.cr 10.0,7.5,2.5,2.5\n</code></pre> <ul> <li>Faster strong-link profile:</li> </ul> <pre><code>set direct.retry.cr 6.0,3.0,0,-2.0\n</code></pre> <ul> <li>Very cautious noisy-link profile:</li> </ul> <pre><code>set direct.retry.cr 20.0,12.0,6.0,2.0\n</code></pre>"},{"location":"cli_commands/#view-seed-or-clear-the-recent-repeater-table","title":"View, seed, or clear the recent repeater table","text":"<p>Usage: - <code>get recent.repeater</code> - <code>get recent.repeater &lt;page&gt;</code> - <code>get recent.repeaters &lt;page&gt;</code> - <code>get recent.repeaters search &lt;prefix&gt; [page]</code> - <code>set recent.repeater &lt;prefix&gt; [snr_db]</code> - <code>clear recent.repeater</code></p> <p>Parameters: - <code>prefix</code>: Repeater path-hash prefix as 2, 4, or 6 hex characters. - <code>snr_db</code>: Optional SNR in dB. If omitted or invalid, defaults to <code>3.0</code>. - <code>page</code>: 1-based result page.</p> <p>Note: These commands are repeater-only.</p> <p>The default capacity is 256 entries on classic ESP32, 2,048 on other ESP32 chips, 512 on nRF52, and 64 on other platforms. Builds can override it with <code>MAX_RECENT_REPEATERS</code>. Classic ESP32's history uses 3,072 bytes of startup heap instead of 24,576 bytes, leaving more memory for the packet pool and Wi-Fi.</p> <p>Output order: - <code>get recent.repeater</code> lists 3-byte prefixes first, then 2-byte prefixes, then 1-byte prefixes. - Within each prefix length, entries are sorted from highest SNR to lowest SNR. - <code>search</code> returns every overlapping path-hash entry. For example, searching   <code>860C</code> can return <code>86</code>, <code>860C</code>, and <code>860CCA</code>; it does not return a different   branch such as <code>86D0</code>. - Search rows include the monotonic age of the entry's most recent recording,   compacted to a whole <code>s</code>, <code>m</code>, or <code>h</code> field. Search pages contain up to six   rows so the result remains within the remote CLI reply limit.</p> <p>SNR details: - Recent repeater SNR is stored internally in quarter-dB units. - Heard repeater samples update an existing table entry with a weighted blend: <code>75%</code> existing SNR and <code>25%</code> new heard SNR, rounded up. - Direct retry success also feeds the heard echo SNR back into the same weighted table. - Direct retry failure is not weighted: each final echo-timeout failure lowers that repeater's SNR by <code>0.25 dB</code>. - Unknown repeaters start at <code>+3.00 dB</code> for adaptive CR selection. - If an unknown repeater fails, it is seeded into the table at <code>+2.75 dB</code>. - <code>set recent.repeater &lt;prefix&gt; [snr_db]</code> seeds a missing prefix or adds another weighted sample for an existing prefix. - Successful <code>set recent.repeater</code> replies include the stored prefix and SNR, for example <code>OK - set A1B2C3 at 3.0 SNR</code>. - Entries strictly older than 24 hours are removed during a sweep every three hours, so an entry can remain for at most approximately 27 hours.</p> <p>Examples:</p> <pre><code>get recent.repeater\nget recent.repeater 2\nget recent.repeaters search 86\nget recent.repeaters search 860C page 2\nset recent.repeater A1B2C3 8.5\nset recent.repeater 71CE82 -3.25\nset recent.repeater A1B2C3\nclear recent.repeater\n</code></pre>"},{"location":"cli_commands/#gps-when-gps-support-is-compiled-in","title":"GPS (When GPS support is compiled in)","text":""},{"location":"cli_commands/#view-or-change-gps-state","title":"View or change GPS state","text":"<p>Search terms: enable GPS, disable GPS, turn GPS on, turn GPS off.</p> <p>Usage: - <code>get gps</code> - <code>set gps &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p>Default: <code>off</code></p> <p>Note: These command names are shared with GPS-capable Companion builds. Companion reports <code>on</code> or <code>off</code>; infrastructure includes receiver details: - <code>off</code> when the GPS hardware is disabled - <code>on, {active|deactivated}, {fix|no fix}, {sat count} sats</code> when the GPS hardware is enabled</p> <p>On repeaters, <code>gps off</code> cancels any acquisition already in progress. A later authorized location-telemetry request may wake the receiver, but only until its first valid fix is cached; the receiver then powers down again.</p>"},{"location":"cli_commands/#sync-this-nodes-clock-with-gps-time","title":"Sync this node's clock with GPS time","text":"<p>Usage:  - <code>gps sync</code></p> <p>The GPS must be enabled. When GPS power saving has put an enabled receiver to sleep, this command schedules a sync and wakes it; after <code>set gps off</code>, it reports <code>gps is off</code> without scheduling work.</p> <p>On repeaters with device power saving enabled, the automatic GPS cycle wakes for up to 10 minutes and repeats seven days after GPS sleeps. A valid GPS time can correct the RTC either forward or backward. With device power saving off, an enabled GPS refreshes the RTC every 30 minutes.</p>"},{"location":"cli_commands/#set-this-nodes-location-based-on-the-gps-coordinates","title":"Set this node's location based on the GPS coordinates","text":"<p>Usage:  - <code>gps setloc</code></p>"},{"location":"cli_commands/#view-or-change-the-gps-advert-policy","title":"View or change the GPS advert policy","text":"<p>Usage: - <code>gps advert</code> - <code>gps advert &lt;policy&gt;</code></p> <p>Parameters:  - <code>policy</code>: <code>none</code>|<code>share</code>|<code>prefs</code>    - <code>none</code>: don't include location in adverts   - <code>share</code>: share gps location (from SensorManager)   - <code>prefs</code>: location stored in node's lat and lon settings</p> <p>Default: <code>prefs</code> on every repeater, room-server, and sensor build that uses the common advert policy. A previously saved <code>none</code>, <code>share</code>, or <code>prefs</code> choice still overrides the first-boot default after an update.</p>"},{"location":"cli_commands/#sensors-when-sensor-support-is-compiled-in","title":"Sensors (When sensor support is compiled in)","text":""},{"location":"cli_commands/#view-or-change-telemetry-access-mode","title":"View or change telemetry access mode","text":"<p>Usage: - <code>get telemetry.access</code> - <code>set telemetry.access &lt;mode&gt;</code></p> <p>Parameters: - <code>mode</code>: <code>all</code>|<code>acl</code>   - <code>all</code>: allow telemetry requests using the requester-provided telemetry mask   - <code>acl</code>: require ACL read-only or higher for telemetry, including GPS</p> <p>Default: <code>all</code></p> <p>Note: <code>all</code> matches the previous sensor telemetry behavior.</p>"},{"location":"cli_commands/#view-the-list-of-sensors-on-this-node","title":"View the list of sensors on this node","text":"<p>Usage: <code>sensor list [start]</code></p> <p>Parameters: - <code>start</code>: Optional starting index (defaults to 0)</p> <p>Note: Output format: <code>&lt;var_name&gt;=&lt;value&gt;\\n</code></p>"},{"location":"cli_commands/#view-or-change-the-value-of-a-sensor","title":"View or change the value of a sensor","text":"<p>Usage:  - <code>sensor get &lt;key&gt;</code> - <code>sensor set &lt;key&gt; &lt;value&gt;</code></p> <p>Parameters: - <code>key</code>: Sensor setting name - <code>value</code>: The value to set the sensor to</p>"},{"location":"cli_commands/#bridge-when-bridge-support-is-compiled-in","title":"Bridge (When bridge support is compiled in)","text":"<p>For a complete two-repeater setup with each option explained, see the ESP-NOW bridge setup guide.</p>"},{"location":"cli_commands/#view-the-compiled-bridge-type","title":"View the compiled bridge type","text":"<p>Usage: <code>get bridge.type</code></p>"},{"location":"cli_commands/#view-or-change-the-bridge-enabled-flag","title":"View or change the bridge enabled flag","text":"<p>Search terms: enable bridge, disable bridge, serial bridge, RS232 bridge.</p> <p>Usage: - <code>get bridge.enabled</code> - <code>get bridge.running</code> - <code>set bridge.enabled &lt;state&gt;</code></p> <p>Parameters: - <code>state</code>: <code>on</code>|<code>off</code></p> <p><code>bridge.enabled</code> is the saved intent. <code>bridge.running</code> reports whether the bridge actually started in this boot; they can differ after a hardware conflict, missing credentials, or a transient initialization failure. Normal merged repeater images default to <code>off</code>; dedicated bridge images may default to <code>on</code>.</p>"},{"location":"cli_commands/#add-a-delay-to-packets-routed-through-this-bridge","title":"Add a delay to packets routed through this bridge","text":"<p>Usage: - <code>get bridge.delay</code> - <code>set bridge.delay &lt;ms&gt;</code></p> <p>Parameters: - <code>ms</code>: Delay in milliseconds (0-10000)</p> <p>Default: <code>500</code></p>"},{"location":"cli_commands/#view-or-change-the-source-of-packets-bridged-to-the-external-interface","title":"View or change the source of packets bridged to the external interface","text":"<p>Usage: - <code>get bridge.source</code> - <code>set bridge.source &lt;source&gt;</code></p> <p>Parameters: - <code>source</code>:   - <code>rx</code>: bridges received packets   - <code>tx</code>: bridges transmitted packets</p> <p>Default: <code>tx</code></p> <p>Note: For MQTT, use <code>mqtt.rx</code> and <code>mqtt.tx</code> to control each direction independently. Both can be enabled together. Use <code>mqtt.enabled</code> as the MQTT master switch; <code>bridge.*</code> configures RS232 and ESP-NOW bridges.</p>"},{"location":"cli_commands/#view-or-change-the-mqtt-master-switch","title":"View or change the MQTT master switch","text":"<p>Search terms: enable MQTT, disable MQTT, MQTT on, MQTT off, WiFi logging.</p> <p>Usage:</p> <ul> <li><code>get mqtt.enabled</code></li> <li><code>set mqtt.enabled on</code></li> <li><code>set mqtt.enabled off</code></li> <li><code>get mqtt.running</code></li> <li><code>get mqtt.status</code></li> </ul> <p>These commands are the same on MQTT-capable Companion, Repeater, Room Server, and Sensor builds. The master switch is saved; turning it off disconnects MQTT while keeping broker presets and credentials. Turning it on allows those brokers to reconnect. <code>get mqtt.running</code> checks the service's runtime state; <code>get mqtt.status</code> reports individual broker connections. Enabling MQTT does not imply that a broker is connected.</p> <p>USB logging remains independent. On images with both outputs, <code>set logging.output off|usb|wifi|both</code> selects USB and MQTT together.</p>"},{"location":"cli_commands/#view-or-change-mqtt-rx-packet-uplinking","title":"View or change MQTT RX packet uplinking","text":"<p>Search terms: MQTT receive logging, MQTT RX capture, publish received packets.</p> <p>Usage: - <code>get mqtt.rx</code> - <code>set mqtt.rx &lt;on|off&gt;</code></p> <p>Parameters: - <code>on</code>: uplink received (RX) packets to MQTT brokers - <code>off</code>: disable RX packet uplinking</p> <p>Default: <code>on</code></p>"},{"location":"cli_commands/#view-or-change-mqtt-tx-packet-uplinking","title":"View or change MQTT TX packet uplinking","text":"<p>Search terms: MQTT transmit logging, MQTT TX capture, publish sent packets.</p> <p>Usage: - <code>get mqtt.tx</code> - <code>set mqtt.tx &lt;on|off|advert&gt;</code></p> <p>Parameters: - <code>on</code>: uplink all transmitted (TX) packets to MQTT brokers - <code>advert</code>: uplink only this node's own advert packets (self-originated advertisements only - forwarded adverts from other nodes are filtered out) - <code>off</code>: disable TX packet uplinking</p> <p>Default: <code>advert</code></p> <p>Note: <code>mqtt.rx</code> and <code>mqtt.tx</code> take effect immediately - no restart required. Both can be enabled simultaneously.</p>"},{"location":"cli_commands/#view-or-change-periodic-neighbors-publishing-mqtt-observer-neighbors-feature","title":"View or change periodic neighbors publishing (MQTT observer, neighbors feature)","text":"<p>Usage: - <code>get mqtt.neighbors</code> - <code>set mqtt.neighbors &lt;on|off&gt;</code></p> <p>Parameters: - <code>on</code>: periodically discover neighbor scopes and publish the neighbor table to the <code>neighbors</code> topic - <code>off</code>: disable periodic neighbors publishing</p> <p>Default: <code>off</code></p> <p>Note: Requires a build with the neighbors feature compiled in (all PSRAM boards, plus non-PSRAM boards built with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>); elsewhere this replies <code>Err - neighbors not enabled in this build</code>. Non-PSRAM builds publish at most 20 neighbours per pass to bound internal-DRAM use, and set <code>truncated</code> with the true <code>total_neighbors</code> when the table is larger. The setting is read live by the mesh loop - no restart required; enabling it triggers a discovery on the next pass. While enabled, <code>get mqtt.status</code> gains a trailing <code>nbr: &lt;next&gt;/&lt;last&gt;</code> field (time to next publish, and how the last publish went).</p>"},{"location":"cli_commands/#view-or-change-the-neighbors-publish-interval-mqtt-observer-neighbors-feature","title":"View or change the neighbors publish interval (MQTT observer, neighbors feature)","text":"<p>Usage: - <code>get mqtt.neighbors.interval</code> - <code>set mqtt.neighbors.interval &lt;hours&gt;</code></p> <p>Parameters: - <code>hours</code>: how often to publish the neighbor table (12-336, default 24)</p> <p>Default: <code>24</code> (hours)</p> <p>Note: Out-of-range values are rejected (not clamped). Requires a build with <code>WITH_MQTT_NEIGHBORS</code>; PSRAM boards enable it automatically and selected non-PSRAM variants opt in with <code>MQTT_NEIGHBORS_WITHOUT_PSRAM</code>.</p>"},{"location":"cli_commands/#view-or-change-the-ntp-server-mqtt-observer-only","title":"View or change the NTP server (MQTT observer only)","text":"<p>Usage: - <code>get mqtt.ntp</code> - <code>set mqtt.ntp &lt;hostname&gt;</code> - <code>set mqtt.ntp none</code></p> <p>Description: Sets the primary NTP server used for clock sync (required for JWT MQTT auth). On <code>set</code>, the device attempts an immediate sync of the just-configured server (primary only, so a typo fails fast) when WiFi is connected and the MQTT bridge is running.</p> <p>Fallbacks: If the primary fails, the firmware tries <code>pool.ntp.org</code>, <code>time.google.com</code>, <code>time.cloudflare.com</code>, <code>time.aws.com</code>, and <code>time.nist.gov</code> in order (skipping duplicates).</p> <p>Default: <code>pool.ntp.org</code> (when unset or <code>none</code>)</p>"},{"location":"cli_commands/#diagnose-ntp-server-connectivity-mqtt-observer-only","title":"Diagnose NTP server connectivity (MQTT observer only)","text":"<p>Usage: - <code>get mqtt.ntp.diag</code></p> <p>Description: Probes every configured NTP server (the custom primary, if set, plus the built-in fallbacks) and reports whether each responds. This is a pure connectivity diagnostic - it does not change the system clock.</p> <ul> <li>Serial console: prints a detailed table with each server's reported UTC time (or <code>FAIL</code>).</li> <li>Over LoRa: returns a compact <code>&lt;server&gt; ok|fail</code> list, one per line.</li> </ul> <p>Requires WiFi connected and the MQTT bridge running.</p>"},{"location":"cli_commands/#view-or-change-the-speed-of-the-bridge-rs-232-only","title":"View or change the speed of the bridge (RS-232 only)","text":"<p>Usage: - <code>get bridge.baud</code> - <code>set bridge.baud &lt;rate&gt;</code></p> <p>Parameters: - <code>rate</code>: Integer baud rate from <code>9600</code> through the board's compiled   <code>BRIDGE_MAX_BAUD</code> (commonly <code>500000</code>); for example <code>115200</code>. Stop the bridge   with <code>set bridge.enabled off</code> before changing it, then enable it again.</p> <p>Default: <code>115200</code></p>"},{"location":"cli_commands/#view-or-change-the-uart-used-by-the-bridge-rs-232-only","title":"View or change the UART used by the bridge (RS-232 only)","text":"<p>Usage: - <code>get bridge.uart</code> - <code>set bridge.uart &lt;port&gt;</code></p> <p>Parameters: - <code>port</code>: Hardware UART number compiled for the board. Most boards expose one   fixed UART. RAK4631 accepts <code>1</code> or <code>2</code>; UART 2 is the default so UART 1 can   remain available to the RAK12501/L76K GPS. RAK12500 GPS uses I2C rather than   this UART, but the explicit legacy Serial1 bridge omits the combined GPS   provider and therefore does not expose either GPS path.</p> <p>The setting is persistent and restarts an enabled bridge immediately. Normal repeater artifacts start with <code>bridge.enabled off</code>; configure the UART and baud rate before running <code>set bridge.enabled on</code>. On the canonical RAK4631 runtime image, UART 1 is reserved even if the bounded boot probe hears no RAK12501. Silence cannot prove that a cold L76K is physically absent, and that module remains powered by the shared WB_IO2/3V3_S rail. Use UART 2. UART 1 requires an explicit no-GPS/dedicated Serial1 bridge image. This fail-closed reservation also applies when the detected GPS is an I2C RAK12500; that receiver does not electrically use UART 1, but its presence cannot rule out another silent UART module.</p>"},{"location":"cli_commands/#view-or-change-the-channel-used-for-bridging-espnow-only","title":"View or change the channel used for bridging (ESPNow only)","text":"<p>Usage: - <code>get bridge.channel</code> - <code>set bridge.channel &lt;channel&gt;</code></p> <p>Parameters: - <code>channel</code>: Channel number from 1 through 13 in either format. This matches   the primary-ESP-NOW policy and the default regulatory range used by the   supported ESP32 targets.</p> <p>This controls the optional ESP-NOW bridge transport; it does not change a node's primary ESP-NOW mesh channel. Primary-ESP-NOW firmware uses <code>get espnow.channel</code> and <code>set espnow.channel &lt;1-13&gt;</code> instead.</p>"},{"location":"cli_commands/#view-or-change-the-esp-now-bridge-wire-format","title":"View or change the ESP-NOW bridge wire format","text":"<p>Usage: - <code>get bridge.format</code> - <code>set bridge.format &lt;format&gt;</code></p> <p>Parameters: - <code>format</code>:   - <code>wrapped</code>: the original ESP-NOW bridge framing (magic, checksum, and XOR     using <code>bridge.secret</code>)   - <code>raw</code>: the exact serialized MeshCore packet used by primary     <code>ESPNOWRadio</code> firmware</p> <p>Default: <code>wrapped</code></p> <p>The setting is persistent and restarts an enabled bridge immediately. Receive parsing is strict: <code>wrapped</code> accepts only wrapped frames and <code>raw</code> accepts only raw MeshCore frames. Coordinate the format and channel on every ESP-NOW peer; there is no automatic dual-format receive mode because it would permit ambiguous, asymmetric bridge deployments.</p> <p>Use <code>raw</code> to connect a LoRa-primary <code>*_repeater_bridge_espnow</code> node to <code>Generic_ESPNOW</code>, <code>SenseCapIndicator-ESPNow</code>, or another primary-ESP-NOW node. Raw mode enables the ESP-NOW LR PHY and sends at the same LR rate used by those targets. All nodes must use the same 1-13 channel. On a primary-ESP-NOW node, change that side with <code>set espnow.channel &lt;1-13&gt;</code> and reboot; on the bridge, use <code>set bridge.channel &lt;1-13&gt;</code>.</p> <p>Raw mode ignores <code>bridge.secret</code> and removes the bridge wrapper's lightweight network isolation. MeshCore's own packet authentication/encryption still applies where the packet type provides it, but public frames and routing metadata remain visible. The wrapped format's XOR is isolation, not strong cryptography. Bridge duplicate tracking remains active in both formats, but deploying multiple gateways between the same LoRa and ESP-NOW coverage areas can still increase duplicate traffic while their seen-packet tables converge.</p> <p>One ESP-NOW frame carries at most 250 payload bytes. In raw mode, serialized MeshCore packets up to that size remain byte-for-byte compatible with existing raw endpoints. Updated raw endpoints split 251-255-byte transport units into two versioned fragments and reassemble them by source MAC, length, and CRC; both endpoints must include this support for those sizes. Current valid MeshCore packet geometry reaches 254 bytes, while 255 is retained as transport headroom. Wrapped mode retains its legacy 246-byte maximum after the four-byte magic and checksum overhead, and drops larger packets instead of truncating them.</p>"},{"location":"cli_commands/#set-the-esp-now-secret","title":"Set the ESP-Now secret","text":"<p>Usage:  - <code>get bridge.secret</code> - <code>set bridge.secret &lt;secret&gt;</code></p> <p>Parameters: - <code>secret</code>: ESP-NOW bridge secret, 1-15 characters</p> <p>Default: Varies by board</p> <p>This setting is used only by <code>bridge.format wrapped</code>; raw mode ignores it.</p>"},{"location":"cli_commands/#view-the-bootloader-version-nrf52-only","title":"View the bootloader version (nRF52 only)","text":"<p>Usage: <code>get bootloader.ver</code></p> <p>Applies to every nRF52 board/role that exposes this getter, including Companion, repeater, and room-server firmware. It reads the installed bootloader region selected by the MBR/UICR boot address and bounded by the chip's flash geometry; it does not search application firmware or staged update files.</p> <p>The reader preserves a complete Adafruit/UF2 version string, including OTAFIX, preview, and vendor/build suffixes. If that string is absent or ambiguous, it uses the existing whole-image CRC and unique BLMF/BLM2 validation to read the embedded OTAFIX version (for example, <code>&gt; OTAFIX2.4.6</code>). Some current release images, including MeshTower V2 SD 2.4.6, omit the UF2 text entirely. As a last fallback, the Adafruit core's startup-captured version is explicitly labelled <code>(base)</code>; it cannot identify an OTAFIX/fork revision.</p> <p><code>unknown</code> remains possible for a bootloader exposing none of these version sources, invalid geometry/vectors, or unresolved ambiguity. There is no universal version field shared by every third-party bootloader. This is diagnostic only: displaying a version neither grants OTA capability nor bypasses install checks. The fix is in MeshCore application firmware; installing another bootloader alone does not update an older application's version reader.</p>"},{"location":"cli_commands/#view-power-management-support","title":"View power management support","text":"<p>Usage: <code>get pwrmgt.support</code></p>"},{"location":"cli_commands/#view-the-current-power-source","title":"View the current power source","text":"<p>Usage: <code>get pwrmgt.source</code></p> <p>Note: Returns an error on boards without power management support.</p>"},{"location":"cli_commands/#view-the-boot-reset-and-shutdown-reasons","title":"View the boot reset and shutdown reasons","text":"<p>Usage: <code>get pwrmgt.bootreason</code></p> <p>Note: Returns an error on boards without power management support.</p>"},{"location":"cli_commands/#view-the-boot-voltage","title":"View the boot voltage","text":"<p>Usage: <code>get pwrmgt.bootmv</code></p> <p>Note: Returns an error on boards without power management support.</p>"},{"location":"cli_commands/#ethernet-when-ethernet-support-is-compiled-in","title":"Ethernet (when Ethernet support is compiled in)","text":"<p>Ethernet support is available on RAK4631 boards with a RAK13800 (W5100S) Ethernet module. Use the <code>_ethernet</code> firmware variants (e.g. <code>RAK_4631_repeater_ethernet</code>) to enable this feature.</p>"},{"location":"cli_commands/#view-ethernet-connection-status","title":"View Ethernet connection status","text":"<p>Usage: - <code>eth.status</code></p> <p>Output: - <code>ETH: &lt;ip&gt;:&lt;port&gt;</code> when connected (e.g. <code>ETH: 192.168.1.50:23</code>) - <code>ETH: not connected</code> when Ethernet is not active</p> <p>Notes: - Available on repeater and room server firmware only. Companion radio ethernet firmware does not expose a CLI. - The Ethernet interface obtains an IP address via DHCP automatically on boot. - A TCP server listens on port 23 (default) for CLI connections. - Connect with any TCP client (e.g. <code>nc</code>, PuTTY) to access the same CLI available over serial.</p>"},{"location":"cli_settings_audit/","title":"CLI setting dispatch audit","text":"<p>The 1.17.1.5 source retained <code>get path.hash.mode</code> in <code>CommonCLI</code> but lost its setter when radio preferences moved into <code>CommonRadioPrefs</code>. Infrastructure roles call <code>CommonCLI</code> directly, so the shared parser's setter was unreachable. The correction restores <code>set path.hash.mode 0|1|2</code> there, validates the value, and saves accepted changes. Missing/invalid values report a value error and leave the setting unchanged.</p> <p>The other radio setters removed by the original refactor had already been restored. A feature-guarded check found a second mismatch: <code>get extra.sf</code> exposed stored data on non-LR2021 radios while its setter was compiled out. Both commands now return <code>Error: extra.sf requires an LR2021 radio</code> there. Supported LR2021 set/get behavior is preserved. These are source corrections; existing release binaries need rebuilding/updating to receive them.</p>"},{"location":"cli_settings_audit/#coverage","title":"Coverage","text":"Surface Check Common infrastructure CLI 72 literal setter keys and 84 query keys; every query has a setter or an explicitly reviewed read-only/alternate-command exception MQTT/observer CLI 33 literal setter keys and 39 query keys, including Wi-Fi, timezone, alerts, display and watchdog settings MQTT slots All nine writable slot subkeys have query/set coverage; <code>diag</code> is intentionally read-only Repeater, Room Server, Sensor Shared CLI delegation and role-specific query/set coverage Companion Shared-radio allowlist and parser agreement, persistence wiring, terminal-specific setters, and role query exceptions Radio settings moved by the refactor All 13 shared setters remain present in infrastructure dispatch Literal command comparisons Checks key lengths so a setter cannot accidentally compare its value against the key's terminating NUL Feature guards Preprocesses common and observer handlers for minimal, nRF52 GPS/SD, ESP32 WebConfig, ESP32 MQTT, RS232/GPS, ESP-NOW, and LR2021 profiles before comparing query/set coverage <p>Read-only exceptions include runtime connection status, diagnostics, firmware role, bootloader identity and reset information. Alternate-command exceptions include the password command and <code>set battery.alert on &lt;region&gt;</code>. These exceptions are explicit in the test, rather than silently allowing all missing setters. Dynamic/delegated command families and hardware-specific features continue to use their dedicated tests; the inventory is not a claim that every build has every feature enabled.</p>"},{"location":"cli_settings_audit/#executed-behavior-tests","title":"Executed behavior tests","text":"<p>The native C++ fixture compiles the production get/set dispatch branches and the real setting bodies for 14 radio-related settings: <code>radio</code>, <code>freq</code>, <code>af</code>, <code>dutycycle</code>, <code>int.thresh</code>, <code>cad</code>, <code>radio.rxgain</code>, <code>tx</code>, <code>rxdelay</code>, <code>agc.reset.interval</code>, <code>path.hash.mode</code>, <code>multi.acks</code>, <code>txdelay</code>, and <code>direct.txdelay</code>. It runs local and authenticated on-air caller timestamps, checks round-trip values and save calls, preserves AGC interval rounding, and checks that rejected hardware applies do not save or change preferences. Hardware callbacks are mocked; these are not live-radio or flash-durability tests. The fixture also runs with and without <code>USE_LR2021</code>, checking supported <code>extra.sf</code> set/query/clear behavior, invalid values, and the unsupported-radio error.</p> <p>The focused hash-mode test checks all valid modes, missing values, negative and out-of-range values, overflow, malformed numbers, whitespace, and similarly named unknown keys. Existing transport tests exercise Companion local/framed and on-air dispatch, local-only secret reads, and browser/stream routing under AddressSanitizer and UndefinedBehaviorSanitizer on Linux.</p> <p>Run the CI checks locally with a host C++ compiler (Linux is required for the existing sanitizer-enabled transport suite):</p> <pre><code>python3 -B test/test_path_hash_cli.py\npython3 -B test/test_cli_settings_contract.py\npython3 -B test/test_local_cli_access.py\n</code></pre> <p>All 14 tests passed on the Linux VM. The workflow runs these commands on future pushes and pull requests. The new inventory and native radio tests also passed with the Windows host compiler.</p> <p><code>pio run -e heltec_v4_repeater</code> passed after both corrections, including the firmware's flash-size and runtime-RAM checks. The initial audit used host tests and build checks; subsequent hardware checks are recorded in the dual-profile validation.</p>"},{"location":"companion_contact_cache/","title":"Full Companion contact caches","text":"<p>Full Companions on ESP32 and nRF52 without PSRAM now keep 16 outgoing paths and 16 shared secrets in RAM. Every contact remains in the contact table; selecting a different contact loads its saved path as needed. This recovers about 25.4 KiB of internal RAM in the 350-contact ESP32 qualification builds.</p> <p>See the qualification results for the six-board RAM comparison, physical tests, and shared-secret timings.</p> <p>PSRAM boards retain their existing complete contact table in external RAM. Legacy USB/BLE/WiFi Companion profiles also retain their inline paths and secrets. The build flag <code>MESH_CONTACT_CACHE=0</code> or <code>1</code> overrides this policy for qualification; it is not a runtime feature switch.</p>"},{"location":"companion_contact_cache/#paths-and-persistence","title":"Paths and persistence","text":"<p>The 16 resident paths use least-recently-used replacement. Contact records keep small handles to their saved paths, including 1-, 2-, and 3-byte hop hashes. The existing 152-byte contact record and Companion app frame formats are unchanged. ESP32 uses <code>/contacts3</code>; nRF52 also supports its paged contact store and migration from <code>/contacts3</code>. An erase is not required.</p> <p>A hot path needs no flash read. A cold path is read from its existing contact record. ESP32 reuses one open contact-file reader to avoid repeated SPIFFS metadata scans during synchronization and saving. It closes that reader before replacing the file or recovering a saved transaction.</p> <p>Changing a copied contact preserves the old path for a pending app response or rollback. Dirty entries are saved before eviction. If storage cannot be read, written, or represented completely, the operation fails instead of silently losing a contact or sending along a different route. Reboot retries an incomplete load from the preserved files. The path checksum also rejects a cold path changed underneath a live handle; it does not add a new checksum to the legacy ESP32 on-disk format.</p>"},{"location":"companion_contact_cache/#shared-secrets-and-power","title":"Shared secrets and power","text":"<p>Both platforms reuse the 16 most recent secrets from RAM. Cache misses use a platform-specific policy:</p> Platform Miss behavior ESP32 Recalculate the secret without reading or writing a secret file. nRF52 Try a saved LittleFS entry, then recalculate if it is unavailable. <p>On the V4, a measured SPIFFS secret lookup took 132,427 microseconds while key exchange took 21,932 microseconds. ESP32 therefore uses recalculation on a RAM-cache miss. It avoids secret-file writes and reduces time awake for this measured workload. These are elapsed times, not measurements of energy in joules; other ESP32 hardware has not been physically benchmarked.</p> <p>On a RAK3401, a LittleFS lookup took 7,812 microseconds versus 31,250 microseconds for key exchange. The nRF52 backend therefore uses saved flash entries to avoid repeat key exchange when a usable entry exists, including after reboot. Saved entries match the full peer public key and a fingerprint of the local key pair, and have a record checksum. Importing a different private or public key invalidates old results. A corrupt or missing saved entry is recalculated. The native tests use the firmware's actual Ed25519 key-exchange library and verify agreement with the peer's independently calculated secret.</p> <p>Derived secrets are expendable. Their storage keeps a reserve for contacts, preferences and filesystem metadata; a full filesystem leaves the calculated secret usable in RAM. nRF52 packs 56 entries into a 3,844-byte page to use its 4 KiB flash blocks efficiently. Small filesystems may not have space to persist secrets for all 350 contacts. A miss without a usable saved entry still performs key exchange.</p> <p><code>MESH_CONTACT_SECRET_FLASH_CACHE=0</code> or <code>1</code> overrides the miss policy for qualification builds. The optional ESP32 flash backend groups eight entries per file. The normal ESP32 policy does not create or use those files.</p>"},{"location":"companion_contact_cache/#inspect-the-cache","title":"Inspect the cache","text":"<p>From the Full Companion's ASCII USB terminal or authenticated local CLI:</p> <pre><code>get contact.cache\n</code></pre> <p>Cached builds report <code>paths=16 secrets=16</code>, <code>miss=calculate</code> or <code>miss=flash</code>, plus these boot-session counters:</p> Field Meaning <code>ram_hits</code> Shared secret reused from RAM. <code>flash_hits</code> Shared secret loaded from flash without recalculation. <code>calculations</code> Shared-secret key exchanges performed. <code>save_skips</code> Calculated secrets that could not be persisted, including storage reserve/backoff. <p>Uncached builds report <code>paths=inline secrets=inline</code>. The normal <code>memory</code> command on supported ESP32 Full Companions shows live heap and queue capacity.</p> <p><code>get contact.cache.timing</code> reports the last successful flash lookup and last key calculation in microseconds. Zero means no such operation has completed since boot. These timings exclude secret writes and are useful for comparing the work avoided on a valid flash hit.</p>"},{"location":"companion_contact_cache/#offline-messages-during-mota","title":"Offline messages during mOTA","text":"<p>Contact caches are independent of the offline message queue. Builds using the shared mOTA queue retain 256 frames normally and 128 while mOTA owns its workspace, then restore 256. No unread frames are discarded to start mOTA: synchronize the queue and retry if it exceeds the retained capacity. PSRAM-backed queues keep their existing capacity and allocation policy.</p> <p>Each queue frame occupies 177 bytes. Retaining 32 instead of 128 would make another 16,992 bytes (16.6 KiB) available inside the shared storage. It would not increase free heap by itself: the normal 256-frame storage is statically reserved, and the current mOTA context already fits in the loaned half. More mOTA scratch data would have to share that space to obtain an additional RAM saving. These changes keep the existing 128-frame mOTA limit.</p>"},{"location":"companion_contact_cache/#build-the-six-capacity-trials","title":"Build the six capacity trials","text":"<p>The optional environments in <code>platformio.nimble.ini</code> combine NimBLE, these contact caches, and the shared mOTA queue at 350 contacts, 40 channels and 256 normal offline frames. They remain outside the ordinary release matrix. The ordinary six constrained release recipes still use their established 150-contact limits pending wider hardware qualification.</p> <p>Enable <code>platformio.nimble.ini</code> as described in the NimBLE trial guide, then build one environment at a time. For example:</p> <pre><code>OUTPUT_DIR=.releases/contact-cache-v3 bash build.sh build-firmware \\\n  Heltec_v3_ram_trial_companion_radio_full_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-cache-trial \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n</code></pre> Hardware Trial environment Heltec V3 <code>Heltec_v3_ram_trial_companion_radio_full_nimble</code> Wireless Tracker <code>Heltec_Wireless_Tracker_ram_trial_companion_radio_full_nimble</code> Tracker V2, FEM on <code>heltec_tracker_v2_ram_trial_companion_radio_full_femon_nimble</code> Heltec CT62 <code>Heltec_ct62_ram_trial_companion_radio_full_nimble</code> XIAO ESP32-C3 <code>Xiao_C3_ram_trial_companion_radio_full_nimble</code> Generic ESP-NOW <code>Generic_ESPNOW_ram_trial_companion_radio_full_nimble</code> <p>The firmware RAM guard remains enabled. A successful linked budget is distinct from live free heap and physical Bluetooth/LoRa qualification on each board.</p> <p>The smaller NimBLE applications let the CT62, XIAO C3 and Generic ESP-NOW trials use two 1.5 MiB WiFi OTA slots on 4 MiB flash. Their 896 KiB SPIFFS and coredump stay at the same addresses as the ordinary <code>huge_app.csv</code> Full layout. Install the trial's merged image over USB first to install its partition table. Subsequent WiFi updates must fit the new slots. An application-only update from the ordinary single-slot Full layout cannot change that layout or enable WiFi OTA.</p>"},{"location":"companion_contact_cache/#regression-checks","title":"Regression checks","text":"<pre><code>python3 -B test/test_contact_cache.py\npython3 -B test/test_companion_contact_persistence_contract.py\npython3 -B test/test_companion_contact_stream_contract.py\npython3 -B test/test_nrf52_extrafs_contract.py\npython3 -B test/test_shared_mota_queue.py\npython3 -B test/test_t096_full_memory.py\npython3 -B test/test_firmware_ram.py\n</code></pre> <p>The cache tests compile the production path/secret cache code and extracted production persistence, routing and request functions with filesystem/radio adapters. They exercise 350 routes, eviction, snapshot rollback, page migration, identity changes, read/write/rename faults, handle exhaustion, packet release on a failed path read, and recovery after a simulated reset between file renames. They do not simulate a physical flash power cut.</p> <p><code>tools/hil/contact_cache_serial_stress.py</code> checks all 350 paths over USB, replaces them with a different generation, and optionally exercises secret eviction. Use an otherwise empty test node and exclusive access to its Companion data port. <code>--populate</code> writes test contacts; <code>--secrets</code> transmits 23 directed LoRa datagrams to synthetic peers. For an ESP32 cache trial:</p> <pre><code>python3 tools/hil/contact_cache_serial_stress.py --port /dev/ttyACM0 \\\n  --populate --generation 1 --secrets --expect-calculate --reboot\npython3 tools/hil/contact_cache_serial_stress.py --port /dev/ttyACM0 \\\n  --generation 1 --secrets --expect-calculate\n</code></pre> <p>Use the actual device path. Omit <code>--expect-calculate</code> for the nRF52 flash policy. The second invocation verifies the persisted paths after reboot.</p>"},{"location":"companion_contact_cache_results/","title":"Contact-cache and NimBLE RAM qualification","text":"<p>Test date: 2026-09-08. Firmware source: <code>b68aa1c6</code>.</p> <p>All six constrained ESP32 Full Companion trials pass the linked RAM budget at 350 contacts, 40 channels and 256 normal offline frames. Their final capability manifests confirm compiled Bluetooth/mOTA support and valid WiFi OTA layouts. These are the optional environments in the contact-cache guide. Ordinary release recipes retain their established contact limits pending qualification on those boards.</p>"},{"location":"companion_contact_cache_results/#linked-internal-ram","title":"Linked internal RAM","text":"<p>Every column below uses 350 contacts, 40 channels and 256 normal offline frames. Values are bytes available for runtime allocations after linking. The final margin subtracts the existing conservative runtime reservation; it is not a measurement of live free heap.</p> Hardware Bluedroid NimBLE NimBLE + mOTA queue loan Plus contact caches Final margin Heltec V3 143,776 158,896 170,152 196,168 23,112 Wireless Tracker 148,432 163,536 174,792 200,824 30,838 Tracker V2, FEM on 133,064 148,168 159,416 185,456 15,470 Heltec CT62 99,040 114,096 125,312 151,344 15,152 XIAO ESP32-C3 98,816 113,888 125,120 151,152 14,960 Generic ESP-NOW 99,776 114,800 126,032 152,064 15,872 <p>NimBLE recovers about 14.7 KiB. Contact caches add about 25.4 KiB on top of NimBLE and the shared mOTA workspace. NimBLE alone fails the unchanged budget at this capacity on all six; adding the queue loan passes only on the original Wireless Tracker. Adding the contact caches passes all six, with 14.6-30.1 KiB of margin. The same Bluetooth runtime allowance is used in every comparison.</p> <p>The shared mOTA queue stays at 256 frames normally and retains 128 while mOTA borrows its workspace, then returns to 256. A queue above 128 must be synchronized before that workspace can be borrowed; unread frames are not discarded to start mOTA. PSRAM-backed queues retain their existing policy.</p> <p>The baseline builds use <code>b041fc7f</code>; the final builds use <code>b68aa1c6</code>, with the same ESP32 Arduino 2.0.17 toolchain and NimBLE-Arduino 2.5.1 where applicable.</p> <p>The CT62, XIAO C3 and Generic ESP-NOW applications fit two 1.5 MiB OTA slots on 4 MiB flash. Their explicit trial layouts retain 896 KiB SPIFFS and the existing SPIFFS/coredump addresses. Install the merged image over USB when changing from the ordinary single-slot Full layout. The other three trials also retain verified dual WiFi OTA slots. All six remain mOTA senders.</p> <p>Additional builds check the platform and default-policy branches:</p> Build Available bytes Reserved runtime bytes Margin bytes Policy T096 Full, FEM on 100,076 73,728 26,348 nRF52 path/secret caches RAK3401 Full 99,900 50,976 48,924 nRF52 path/secret caches Wireless Paper Full 187,360 152,576 34,784 ESP32 caches, existing Bluedroid V4 Full NimBLE 263,944 173,056 90,888 Complete contacts in PSRAM XIAO nRF52 legacy BLE Companion 84,368 38,688 45,680 Existing inline contact storage <p>The V4 test-only forced-cache build also passes its RAM budget. The V4 normally keeps complete contacts in PSRAM; forcing caches adds internal RAM overhead. The six-board savings above apply to boards without PSRAM.</p>"},{"location":"companion_contact_cache_results/#physical-checks","title":"Physical checks","text":"<p>The VM V4 used the test-only cache override. USB tests verified all 350 contacts and all 64 saved path bytes per contact, cold individual lookups, replacement of the complete path set, and persistence after reboot. A secret workload contacted 21 distinct synthetic peers, then the first peer twice: 22 calculations, one RAM hit, and no secret-file access under the ESP32 policy.</p> <p>A sustained send test exposed a false receive watchdog recovery. RX could occur inside the main loop between two successful transmissions, while the watchdog observed TX at both loop boundaries. It counted from the start of the whole burst and could reset a working radio during a later CAD pause. <code>468cc3cf</code> restarts the receive recovery allowance after each successful TX. The native regression fails before that change and passes afterward; it also checks that a stuck receiver still gets recovered.</p> <p>The corrected V4 passed the same 23-datagram workload with zero radio error flags. It also passed a complete 350-path replacement, another send workload and a post-reboot path check with zero radio error flags. The replacement took about 127 seconds: dirty-cache eviction still performs synchronous SPIFFS contact-file saves, so bulk path updates remain a latency workload to qualify on the other ESP32 boards. After that run it reported 133,828 bytes free internal heap, a minimum of 130,976 bytes, and a largest free block of 122,868 bytes. These readings belong to the forced-cache V4 workload, not the six other boards.</p> <p>After qualification, the VM V4 was erased to remove synthetic contacts and installed with the normal PSRAM-backed V4 NimBLE trial from <code>b68aa1c6</code>. It is named <code>NimBLE-V4-VM</code>, uses the PIN shown on its display, and has powersaving off for USB use. That clean setup reported 143,612 bytes of free internal heap and passed 201 local USB requests with zero radio error flags. The Mercer V4 and XIAO S3 were left on their previously qualified NimBLE builds.</p> <p>The Mercer RAK3401 Full Companion verified 350 paths, eviction and persistence. Its first secret workload produced 21 calculations, one flash hit and one RAM hit with no skipped saves. After reboot, the same workload produced 22 flash hits, one RAM hit and zero calculations. Both completed with zero radio error flags. The final <code>b68aa1c6</code> RAK image repeated the 350-path and saved-secret checks with zero radio errors and zero calculations. The RAK was returned to the published <code>26303793</code> repeater application with its original repeater name and USA Cascade settings; the Pi's MQTT logger was restarted after the exclusive USB tests.</p>"},{"location":"companion_contact_cache_results/#shared-secret-timing","title":"Shared-secret timing","text":"Hardware/filesystem Successful saved-secret lookup Key exchange Selected miss policy V4 / SPIFFS 132,427 us 21,932 us Recalculate RAK3401 / LittleFS 7,812-8,789 us 31,250 us Read saved entry, calculate on miss <p>The SPIFFS timing comes from the earlier forced flash-cache experiment. The final ESP32 policy does no secret-file I/O. Both platforms reuse the 16 most recent secrets from RAM. These are elapsed-time measurements, not energy measurements; timing on other ESP32/nRF52 boards remains to be measured.</p>"},{"location":"companion_contact_cache_results/#regression-checks-and-evidence","title":"Regression checks and evidence","text":"<p>The contact-cache suite exercises the production cache and persistence code under address/undefined-behavior sanitizers, with the real Ed25519 key-exchange implementation. Its cases include 350 paths, identity changes, snapshots, legacy migration, storage faults, handle exhaustion and packet release when a cold path cannot be read. The related contract suites passed 62 checks. The native queue/store suites passed 27 cases, the radio-liveness suite passed eight, and the partition-selection suite passed 11.</p> <p>Hardware reproduction commands are in the contact-cache guide. The tracked harness is <code>tools/hil/contact_cache_serial_stress.py</code>. It requires exclusive access to the specified Companion data port.</p> <p>Local evidence in the qualification workspace:</p> <ul> <li><code>.releases/nimble-six-capacity/control/results.json</code>: 18 baseline builds.</li> <li><code>.releases/contact-cache/qualified/control/results.json</code>: final build results.</li> <li><code>.releases/contact-cache/qualified/built/</code>: firmware, ELFs, maps, RAM reports,   partition tables and capability manifests.</li> <li><code>.releases/contact-cache/qualified/control/</code>: final V4 USB and flash checks.</li> <li><code>.releases/contact-cache/control/</code>: earlier experiments, RAK results and   regression logs, including the watchdog's failing/passing test runs.</li> </ul> <p>Each final RAM report is checked against its ELF hash. All 12 final builds pass their RAM and OTA capability checks. Physical testing here covers the V4 and RAK3401; the six constrained ESP32 boards still need pairing, WiFi/BLE/LoRa coexistence and sustained-load testing on their own hardware. No GitHub release assets or firmware-picker entries were replaced by these experimental builds.</p>"},{"location":"companion_offline_queue/","title":"Companion Offline Message Queue","text":"<p>Companion firmware keeps received channel data, channel messages, and direct messages in one pending queue until a Companion client requests them with the sync-next-message command. This is volatile RAM, not message history in flash. A reboot clears it.</p>"},{"location":"companion_offline_queue/#default-capacities","title":"Default capacities","text":"Platform or memory profile Pending frames ESP32 with configured PSRAM 512 ESP32 without PSRAM 256 nRF52840 256 nRF52 Full Companion with the memory correction 256 normally; 128 while mOTA owns shared storage RP2040 256 STM32 16 Known constrained classic ESP32 target override 128 Meshadventurer Full Companion 16 Constrained Full ESP32 fallback 16 <p>An explicit target <code>OFFLINE_QUEUE_SIZE</code> overrides the platform default. The Heltec V2 and TLora V2 Full Companion profiles, for example, use 16 frames so their combined WiFi, BLE, and LoRa mOTA image retains enough internal DRAM. Meshadventurer SX1262 and SX1268 Full Companion use 16 frames together with 100 contacts and 30 group channels; their ordinary transport-specific images keep 128 frames and 40 channels.</p> <p>The nRF52 Full memory correction applies queue sharing to every nRF52 Full Companion. It keeps 256 frames normally, retaining each board's contacts, channels, and all Full transports. The upper 128 slots temporarily hold the mOTA context when a source or TempRadio discovery session starts. Stopping or disconnecting the USB/Bluetooth source returns all 256 slots; a discovery-only session returns them when TempRadio ends. This shares a fixed memory region and avoids heap fragmentation from resizing.</p> <p>Existing unread messages retain their order. If more than 128 frames are pending, mOTA refuses the loan and asks you to sync messages with a Companion app first. While the loan is active, the overflow policy below applies at 128 frames. The original <code>26303793</code> 1.17.1.5 builds reserve the queue and mOTA state separately. Sharing recovers about 19 KiB on nRF52 Full. The ST7735 color-display Full profiles require at least 72 KiB of heap space at link time; OLED and headless profiles use their own memory budgets.</p> <p>Standard, logging, MQTT, and Cascade build overlays retain the selected target capacity; they do not silently shrink the queue.</p> <p>Each queue slot currently costs 177 bytes. A 256-frame queue reserves 45,312 bytes, while a 512-frame queue reserves 90,624 bytes. There is no 256-frame protocol limit: the queue length and indexes can represent 512 or more. The practical limit is available RAM and the heap and stack headroom required by the transports and display.</p> <p>On ESP32 boards marked with <code>BOARD_HAS_PSRAM</code>, the queue is allocated from PSRAM before WiFi and BLE start. A failed 512-frame allocation retries at 256, then 128, and finally uses a 16-frame internal fallback. Full Companion prints the capacity actually allocated in its startup memory line as <code>offline_queue=&lt;frames&gt;</code>.</p>"},{"location":"companion_offline_queue/#full-queue-behavior","title":"Full queue behavior","text":"<p>The capacity is shared across Public, other channels, channel data, and direct messages. It is not a per-channel count. When the queue is full, firmware replaces the oldest queued channel frame so newer traffic can still arrive. If the full queue contains only direct messages, a new frame is dropped rather than deleting a direct message.</p> <p>Queue order is preserved. Removal uses a ring index, so delivering one pending message no longer copies every remaining frame; only the less-common removal of an old channel frame from a full queue may shift entries.</p> <p>Capacity is selected when firmware is compiled. There is no CLI or Companion protocol setting to resize it at runtime.</p>"},{"location":"companion_protocol/","title":"Companion Protocol","text":"<ul> <li>Last Updated: 2026-08-26</li> <li>Protocol Version: 14 (<code>FIRMWARE_VER_CODE</code>)</li> </ul> <p>The command and response catalogs track <code>examples/companion_radio/MyMesh.cpp</code>. Applications should negotiate the protocol and validate lengths because older firmware exposes a subset.</p> <p>This document is a practical guide to MeshCore's binary companion protocol. The same protocol frames can be carried by the enabled BLE, USB serial, Wi-Fi, or Ethernet companion interface; connection details differ by build.</p> <p>On builds exposing more than one transport, delivery-required replies follow the interface which supplied the command. The multi-frame contact-list response holds that route until <code>END_OF_CONTACTS</code>; best-effort asynchronous observations may still be broadcast to enabled clients. Treat the device as one Companion session rather than as independent per-transport sessions.</p> <p>The examples focus on BLE, but the packet formats are transport-independent.</p>"},{"location":"companion_protocol/#official-libraries","title":"Official Libraries","text":"<p>Please see the following repos for existing MeshCore Companion Protocol libraries.</p> <ul> <li>JavaScript: https://github.com/meshcore-dev/meshcore.js</li> <li>Python: https://github.com/meshcore-dev/meshcore_py</li> </ul>"},{"location":"companion_protocol/#important-security-note","title":"Important Security Note","text":"<p>All secrets, hashes, and cryptographic values shown in this guide are example values only.</p> <ul> <li>All hex values, public keys and hashes are for demonstration purposes only</li> <li>Never use example secrets in production</li> <li>Always generate new cryptographically secure random secrets</li> <li>Please implement proper security practices in your implementation</li> <li>This guide is for protocol documentation only</li> </ul>"},{"location":"companion_protocol/#table-of-contents","title":"Table of Contents","text":"<ol> <li>BLE Connection</li> <li>Packet Structure</li> <li>Commands</li> <li>Channel Management</li> <li>Message Handling</li> <li>Response Parsing</li> <li>Example Implementation Flow</li> <li>Best Practices</li> <li>Troubleshooting</li> </ol>"},{"location":"companion_protocol/#ble-connection","title":"BLE Connection","text":""},{"location":"companion_protocol/#service-and-characteristics","title":"Service and Characteristics","text":"<p>MeshCore Companion devices expose a BLE service with the following UUIDs:</p> <ul> <li>Service UUID: <code>6E400001-B5A3-F393-E0A9-E50E24DCCA9E</code></li> <li>RX Characteristic (App -&gt; Firmware): <code>6E400002-B5A3-F393-E0A9-E50E24DCCA9E</code></li> <li>TX Characteristic (Firmware -&gt; App): <code>6E400003-B5A3-F393-E0A9-E50E24DCCA9E</code></li> </ul> <p>An nRF52 Full Companion also exposes a separate LoRa mOTA source service. It does not replace or multiplex the normal Companion UART service:</p> <ul> <li>mOTA Service: <code>14518FC2-7E7A-4D84-8CAE-6664B0234CF2</code></li> <li>Device Request (notify): <code>2BFAA1EE-7030-459A-B65A-E7CFD5B09735</code></li> <li>Host Response (write with response): <code>ACF38A51-DD58-4DCE-917F-0B1135E41B1A</code></li> </ul> <p>All three mOTA attributes require an encrypted, MITM-authenticated connection using the Companion's six-digit PIN. The source remains inactive until the client subscribes to Device Request and explicitly starts it with command <code>0x4B</code>. See Bluetooth LoRa mOTA source.</p> <p>ESP32 and nRF52 Companion UART characteristics require the same PIN-protected, MITM-authenticated link. ESP32 advertises DisplayOnly capability so a central must enter the PIN shown by the Companion; a Just Works bond is insufficient.</p>"},{"location":"companion_protocol/#connection-steps","title":"Connection Steps","text":"<ol> <li> <p>Scan for Devices</p> <ul> <li>Scan for BLE devices advertising the MeshCore Service UUID</li> <li>Optionally filter by device name (typically contains \"MeshCore\" prefix)</li> <li>Note the device MAC address for reconnection</li> </ul> </li> <li> <p>Connect to GATT</p> <ul> <li>Connect to the device using the discovered MAC address</li> <li>Wait for connection to be established</li> </ul> </li> <li> <p>Discover Services and Characteristics</p> <ul> <li>Discover the service with UUID <code>6E400001-B5A3-F393-E0A9-E50E24DCCA9E</code></li> <li>Discover the RX characteristic <code>6E400002-B5A3-F393-E0A9-E50E24DCCA9E</code><ul> <li>Your app writes to this, the firmware reads from this</li> </ul> </li> <li>Discover the TX characteristic <code>6E400003-B5A3-F393-E0A9-E50E24DCCA9E</code><ul> <li>The firmware writes to this, your app reads from this</li> </ul> </li> </ul> </li> <li> <p>Enable Notifications</p> <ul> <li>Subscribe to notifications on the TX characteristic to receive data from the firmware</li> </ul> </li> <li> <p>Send Initial Commands</p> <ul> <li>Send <code>CMD_APP_START</code> to identify your app to firmware and get radio settings</li> <li>Send <code>CMD_DEVICE_QUERY</code> to fetch device info and negotiate supported protocol versions</li> <li>Send <code>CMD_SET_DEVICE_TIME</code> to set the firmware clock</li> <li>Send <code>CMD_GET_CONTACTS</code> to fetch all contacts</li> <li>Send <code>CMD_GET_CHANNEL</code> multiple times to fetch all channel slots</li> <li>Send <code>CMD_SYNC_NEXT_MESSAGE</code> to fetch the next message stored in firmware</li> <li>Setup listeners for push codes, such as <code>PUSH_CODE_MSG_WAITING</code> or <code>PUSH_CODE_ADVERT</code></li> <li>See Commands section for information on other commands</li> </ul> </li> </ol> <p>Note: MeshCore devices may disconnect after periods of inactivity. Implement auto-reconnect logic with exponential backoff.</p>"},{"location":"companion_protocol/#ble-write-type","title":"BLE Write Type","text":"<p>When writing commands to the RX characteristic, specify the write type:</p> <ul> <li>Write with Response (default): Waits for acknowledgment from device</li> <li>Write without Response: Faster but no acknowledgment</li> </ul> <p>Platform-specific:</p> <ul> <li>Android: Use <code>BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT</code> or <code>WRITE_TYPE_NO_RESPONSE</code></li> <li>iOS: Use <code>CBCharacteristicWriteType.withResponse</code> or <code>.withoutResponse</code></li> <li>Python (bleak): Use <code>write_gatt_char()</code> with <code>response=True</code> or <code>False</code></li> </ul> <p>Recommendation: Use write with response for reliability.</p>"},{"location":"companion_protocol/#mtu-maximum-transmission-unit","title":"MTU (Maximum Transmission Unit)","text":"<p>The default BLE MTU is 23 bytes (20 bytes payload). For larger commands like <code>SET_CHANNEL</code> (50 bytes), you may need to:</p> <ol> <li>Request Larger MTU: Request MTU of 512 bytes if supported<ul> <li>Android: <code>gatt.requestMtu(512)</code></li> <li>iOS: <code>peripheral.maximumWriteValueLength(for:)</code></li> <li>Python (bleak): MTU is negotiated automatically</li> </ul> </li> </ol>"},{"location":"companion_protocol/#command-sequencing","title":"Command Sequencing","text":"<p>Critical: Commands must be sent in the correct sequence:</p> <ol> <li> <p>After Connection:</p> <ul> <li>Wait for BLE connection to be established</li> <li>Wait for services/characteristics to be discovered</li> <li>Wait for notifications to be enabled</li> <li>Now you can safely send commands to the firmware</li> </ul> </li> <li> <p>Command-Response Matching:</p> <ul> <li>Send one command at a time</li> <li>Wait for a response before sending another command</li> <li>Use a timeout (typically 5 seconds)</li> <li>Match response to command by type (e.g: <code>CMD_GET_CHANNEL</code> -&gt; <code>RESP_CODE_CHANNEL_INFO</code>)</li> </ul> </li> </ol>"},{"location":"companion_protocol/#command-queue-management","title":"Command Queue Management","text":"<p>For reliable operation, implement a command queue.</p> <p>Queue Structure:</p> <ul> <li>Maintain a queue of pending commands</li> <li>Track which command is currently waiting for a response</li> <li>Only send next command after receiving response or timeout</li> </ul> <p>Error Handling:</p> <ul> <li>On timeout, clear current command, process next in queue</li> <li>On error, log error, clear current command, process next</li> </ul>"},{"location":"companion_protocol/#packet-structure","title":"Packet Structure","text":"<p>The MeshCore protocol uses a binary format with the following structure:</p> <ul> <li>Commands: Sent from app to firmware via RX characteristic</li> <li>Responses: Received from firmware via TX characteristic notifications</li> <li>All multi-byte integers: Little-endian byte order (except CayenneLPP which is Big-endian)</li> <li>All strings: UTF-8 encoding</li> </ul> <p>Most packets follow this format:</p> <pre><code>[Packet Type (1 byte)] [Data (variable length)]\n</code></pre> <p>The first byte indicates the packet type (see Response Parsing).</p>"},{"location":"companion_protocol/#commands","title":"Commands","text":"<p>The first byte selects the command. This is the current protocol-v14 command catalog; bytes <code>0x2C</code>-<code>0x31</code> are parked and <code>0x35</code> is unused.</p> Byte Firmware name Purpose <code>0x01</code> <code>CMD_APP_START</code> Start an app session and request self information. <code>0x02</code> <code>CMD_SEND_TXT_MSG</code> Send text to a contact. <code>0x03</code> <code>CMD_SEND_CHANNEL_TXT_MSG</code> Send channel text. <code>0x04</code> <code>CMD_GET_CONTACTS</code> Enumerate contacts, optionally modified since a timestamp. <code>0x05</code> / <code>0x06</code> <code>CMD_GET_DEVICE_TIME</code> / <code>CMD_SET_DEVICE_TIME</code> Read or set the device clock. <code>0x07</code> / <code>0x08</code> <code>CMD_SEND_SELF_ADVERT</code> / <code>CMD_SET_ADVERT_NAME</code> Advertise self or change the advertised name. <code>0x09</code> <code>CMD_ADD_UPDATE_CONTACT</code> Add or update a contact. <code>0x0A</code> <code>CMD_SYNC_NEXT_MESSAGE</code> Dequeue the next pending message. <code>0x0B</code> / <code>0x0C</code> <code>CMD_SET_RADIO_PARAMS</code> / <code>CMD_SET_RADIO_TX_POWER</code> Set radio parameters or transmit power. <code>0x0D</code> <code>CMD_RESET_PATH</code> Reset a contact's learned path. <code>0x0E</code> <code>CMD_SET_ADVERT_LATLON</code> Set advertised coordinates. <code>0x0F</code> <code>CMD_REMOVE_CONTACT</code> Remove a contact. <code>0x10</code> / <code>0x11</code> / <code>0x12</code> <code>CMD_SHARE_CONTACT</code> / <code>CMD_EXPORT_CONTACT</code> / <code>CMD_IMPORT_CONTACT</code> Share, export, or import contact data. <code>0x13</code> <code>CMD_REBOOT</code> Reboot after the required confirmation body. <code>0x14</code> <code>CMD_GET_BATT_AND_STORAGE</code> Read battery and storage usage. <code>0x15</code> <code>CMD_SET_TUNING_PARAMS</code> Set tuning parameters. <code>0x16</code> <code>CMD_DEVICE_QUERY</code> Negotiate protocol support and read device information. <code>0x17</code> / <code>0x18</code> <code>CMD_EXPORT_PRIVATE_KEY</code> / <code>CMD_IMPORT_PRIVATE_KEY</code> Export or import identity key material when enabled. <code>0x19</code> <code>CMD_SEND_RAW_DATA</code> Send an application raw-data packet. <code>0x1A</code>-<code>0x1D</code> <code>CMD_SEND_LOGIN</code> through <code>CMD_LOGOUT</code> Manage a server connection. <code>0x1E</code> <code>CMD_GET_CONTACT_BY_KEY</code> Look up a contact by public-key prefix. <code>0x1F</code> / <code>0x20</code> <code>CMD_GET_CHANNEL</code> / <code>CMD_SET_CHANNEL</code> Read or write a channel slot. <code>0x21</code>-<code>0x23</code> <code>CMD_SIGN_START</code> through <code>CMD_SIGN_FINISH</code> Stream data for identity signing. <code>0x24</code> <code>CMD_SEND_TRACE_PATH</code> Trace a direct route. <code>0x25</code> <code>CMD_SET_DEVICE_PIN</code> Set or clear the device PIN. <code>0x26</code> <code>CMD_SET_OTHER_PARAMS</code> Set telemetry, location, ACK, and related preferences. <code>0x27</code> <code>CMD_SEND_TELEMETRY_REQ</code> Send the legacy telemetry request. <code>0x28</code> / <code>0x29</code> <code>CMD_GET_CUSTOM_VARS</code> / <code>CMD_SET_CUSTOM_VAR</code> Read or set custom variables. <code>0x2A</code> <code>CMD_GET_ADVERT_PATH</code> Read a cached advertisement path. <code>0x2B</code> <code>CMD_GET_TUNING_PARAMS</code> Read tuning parameters. <code>0x32</code> <code>CMD_SEND_BINARY_REQ</code> Send an application binary request. <code>0x33</code> <code>CMD_FACTORY_RESET</code> Factory-reset after the required confirmation body. <code>0x34</code> <code>CMD_SEND_PATH_DISCOVERY_REQ</code> Request path discovery. <code>0x36</code> <code>CMD_SET_FLOOD_SCOPE_KEY</code> Select scoped or unscoped flood behavior. <code>0x37</code> <code>CMD_SEND_CONTROL_DATA</code> Send zero-hop control data. <code>0x38</code> <code>CMD_GET_STATS</code> Read core, radio, or packet statistics. <code>0x39</code> <code>CMD_SEND_ANON_REQ</code> Send an anonymous request. <code>0x3A</code> / <code>0x3B</code> <code>CMD_SET_AUTOADD_CONFIG</code> / <code>CMD_GET_AUTOADD_CONFIG</code> Write or read automatic-contact policy. <code>0x3C</code> <code>CMD_GET_ALLOWED_REPEAT_FREQ</code> Read allowed client-repeat frequency ranges. <code>0x3D</code> <code>CMD_SET_PATH_HASH_MODE</code> Set path-hash width mode. <code>0x3E</code> <code>CMD_SEND_CHANNEL_DATA</code> Send a channel binary datagram. <code>0x3F</code> / <code>0x40</code> <code>CMD_SET_DEFAULT_FLOOD_SCOPE</code> / <code>CMD_GET_DEFAULT_FLOOD_SCOPE</code> Write or read the default flood scope. <code>0x41</code> <code>CMD_SEND_RAW_PACKET</code> Queue a fully encoded raw mesh packet. <code>0x42</code> <code>CMD_RUN_CLI_COMMAND</code> Run a local CLI command (protocol v14+). <code>0x4A</code> <code>CMD_EXEC_LOCAL_OTA_CONTROL</code> Run one bounded local TempRadio or OTA command when the Companion includes the OTA CLI. <code>0x4B</code> <code>CMD_BLE_MOTA_SOURCE</code> Query, start, or stop an nRF52 Full Companion's Bluetooth-backed LoRa mOTA source. <code>0x78</code>-<code>0x7F</code> Deprecated hardware-setting aliases Receive-only compatibility for clients shipped before command <code>0x42</code> became the canonical settings path. <p>The sections below detail the most common frames. Refer to the source named above for command bodies that are not expanded here.</p> <p><code>CMD_RUN_CLI_COMMAND</code> is followed by the local CLI text without a terminating NUL. The device returns <code>RESP_CODE_CLI_REPLY</code> (<code>0x1D</code>) followed by the reply text. This is separate from sending a remote on-air CLI command with <code>CMD_SEND_TXT_MSG</code> and <code>TXT_TYPE_CLI_COMMAND</code>. The body must contain at least one byte and must not contain an embedded NUL. An unknown command is returned as the normal CLI reply text <code>Unknown command</code>, not as an error frame. Clients may prefix the CLI text with any two-character correlation tag and <code>|</code> (for example, <code>A7|get radio.rxgain</code>); the reply preserves that prefix.</p> <p>Direct USB, BLE, WiFi TCP, and Ethernet clients can also use this command for <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code>, <code>erase</code>, and <code>get prv.key</code> (when private key export is enabled). WiFi/MQTT builds accept <code>get wifi.pwd</code>, <code>get mqttN.password</code>, and <code>get mqttN.token</code>. <code>get password</code> reports that Companion has no admin password; infrastructure roles return their own admin password on a local CLI connection. These privileges do not apply to CLI commands relayed over LoRa. <code>set freq &lt;MHz&gt;</code> works through command <code>0x42</code> and authorized LoRa CLI, like <code>set radio</code>; it saves the frequency and requires reboot to apply. See local maintenance commands for role differences and the text-terminal equivalents.</p> <p>Full Companion clients can send <code>version</code> through this command to receive the untruncated build identity, for example <code>Companion 1.17.1.5-... (protocol 14, build 31-Aug-2026)</code>. This deliberately supplements rather than changes the 20-byte legacy version field in <code>RESP_CODE_DEVICE_INFO</code>, so existing clients keep the same frame layout.</p> <p>Firmware from this fork predating the upstream <code>0x42</code> allocation used <code>0x42</code>-<code>0x49</code> for these eight settings. This firmware accepts those values as deprecated inbound aliases so existing clients continue to work. A one-byte <code>0x42</code> frame is the legacy FEM-gain GET; <code>0x42</code> followed by text is the official <code>CMD_RUN_CLI_COMMAND</code>. New clients should use <code>CMD_RUN_CLI_COMMAND</code> for all of these settings, rather than allocating additional command bytes. For example, send <code>0x42</code> followed by <code>get radio.rxgain</code> or <code>set radio.rxgain on</code>. The reply is <code>RESP_CODE_CLI_REPLY</code> followed by the normal CLI reply text.</p> <p>Two deprecated binary alias blocks remain receive-only for compatibility:</p> Setting Original alias Later fork alias GET body/reply SET body/reply FEM receive gain <code>0x42</code> / <code>0x43</code> <code>0x78</code> / <code>0x79</code> No body; <code>OK, state</code> One byte <code>0</code>/<code>1</code>; <code>OK</code> Radio receive gain <code>0x44</code> / <code>0x45</code> <code>0x7A</code> / <code>0x7B</code> No body; <code>OK, state</code> One byte <code>0</code>/<code>1</code>; <code>OK</code> WiFi power save <code>0x46</code> / <code>0x47</code> <code>0x7C</code> / <code>0x7D</code> No body; <code>OK, mode</code> One mode byte <code>0</code>-<code>2</code>; <code>OK</code> Bluetooth name <code>0x48</code> / <code>0x49</code> <code>0x7E</code> / <code>0x7F</code> No body; <code>OK, custom, name</code> Zero to 31 UTF-8 bytes; <code>OK</code> <p>Each pair lists GET then SET. Here <code>OK</code> is <code>RESP_CODE_OK</code>; the remaining reply bytes have the same meanings as the CLI settings below. A bare <code>0x42</code> is the old FEM GET, while <code>0x42</code> plus at least one text byte is <code>CMD_RUN_CLI_COMMAND</code>. New clients must use the framed CLI form; these aliases exist only so deployed clients do not break after a firmware update.</p> <p>The equivalent framed CLI commands are:</p> Setting Commands Radio receive gain <code>get radio.rxgain</code>; <code>set radio.rxgain on|off</code> FEM receive gain <code>get radio.fem.rxgain</code>; <code>set radio.fem.rxgain on|off</code> WiFi power save <code>get wifi.powersave</code>; <code>set wifi.powersave none|min|max</code> Bluetooth name <code>get bluetooth.name</code>; <code>set bluetooth.name &lt;name|default&gt;</code> Bluetooth address <code>get bluetooth.mac</code>; <code>set bluetooth.mac &lt;address|random|random-every-boot|random-after-connect|default&gt;</code> Bluetooth stealth <code>get bluetooth.stealth</code>; <code>set bluetooth.stealth on|off</code> <p>The framed form works over the normal binary USB, BLE, or TCP transport and does not need the USB terminal-start token. Unsupported settings return the same explanatory text as the local CLI.</p> <p>WiFi power-save modes are:</p> Value Mode <code>0</code> <code>min</code> - minimum modem sleep <code>1</code> <code>none</code> - no modem sleep <code>2</code> <code>max</code> - maximum modem sleep <p>A Full Companion that runs BLE and infrastructure WiFi simultaneously rejects WiFi mode <code>none</code> because coexistence requires modem sleep. A Full Companion using ESP-NOW as its primary mesh radio also rejects <code>max</code>, because maximum modem sleep can miss broadcasts that the access point cannot buffer. If an older image saved a conflicting value, the effective mode is capped to and reported as <code>min</code>. Device power saving remains independent.</p> <p>The SenseCAP Indicator Full profiles run exactly one secondary wireless Companion transport per boot. Their active-mode constraints are:</p> Indicator mode Accepted <code>wifi.powersave</code> values LoRa + infrastructure WiFi <code>none</code>, <code>min</code>, <code>max</code> LoRa + BLE <code>min</code>, <code>max</code>; infrastructure WiFi is not started ESP-NOW + infrastructure WiFi <code>none</code>, <code>min</code>; <code>max</code> conflicts with primary ESP-NOW ESP-NOW + BLE <code>min</code>; infrastructure WiFi is not started and primary ESP-NOW remains active <p>The Bluetooth name can be configured over USB, BLE, or TCP. Use <code>set bluetooth.name default</code> to restore <code>MeshCore-&lt;advert name&gt;</code>; an empty CLI value is rejected. (<code>clear</code> is also accepted as an alias for <code>default</code>.) A custom name is limited to 31 valid UTF-8 bytes and takes effect after reboot.</p> <p>Bluetooth Companion builds also accept <code>bluetooth.mac</code> (<code>ble.mac</code> is an alias). A literal address must be a BLE random-static address; <code>random</code> generates and saves one, <code>random-every-boot</code> rotates it at each startup, and <code>random-after-connect</code> retains it through unused boots but rotates it on the first boot after an authenticated connection. <code>default</code> or <code>clear</code> restores the factory address. The change takes effect after reboot.</p> <p><code>bluetooth.stealth on|off</code> (<code>ble.stealth</code> is an alias) is a separate flag, defaulting to off. It preserves the address policy and can be combined with custom, saved random, rotating random, or factory addresses. With stealth on, the node advertises normally until the first authenticated pairing, then permits only that bonded peer to reconnect. Address changes clear the saved peer and reopen pairing without disabling stealth. Rotating policies retain their normal rotation triggers. Repeating <code>on</code> does not clear an existing bond. Both flag changes require reboot. The old MAC value <code>stealth</code> is not accepted.</p> <p>BLE still transmits directed or allowlisted advertisements; stealth is not radio silence. These are application settings; an nRF52 OTAFIX bootloader continues to advertise its separate DFU identity.</p>"},{"location":"companion_protocol/#bluetooth-lora-mota-source","title":"Bluetooth LoRa mOTA source","text":"<p>Protocol v14 lets a phone control an install-capable Companion's own LoRa OTA session. An nRF52 Full Companion can additionally act as the source for a remote repeater update without a USB computer. The normal Companion service still carries contacts, repeater login, CLI messages, and these two control commands. The separate mOTA service carries only host-folder request/response frames.</p> <p><code>CMD_EXEC_LOCAL_OTA_CONTROL</code> (<code>0x4A</code>) is followed by 1-174 printable ASCII bytes. A Companion built with the OTA CLI accepts only these local command families:</p> <pre><code>tempradio &lt;freq_kHz&gt;,&lt;bw_kHz&gt;,&lt;sf&gt;,&lt;cr&gt;,&lt;minutes&gt;\nnormalradio\nota ...\n</code></pre> <p><code>ota folder ...</code> is deliberately rejected because USB and Bluetooth source ownership must not be changed through the wrong transport. Embedded NUL, CR, LF, other control bytes, non-ASCII bytes, empty commands, and oversized frames return <code>ERR_CODE_ILLEGAL_ARG</code>. A recognized command replies with <code>RESP_CODE_OK</code>, one unsigned reply-length byte, and exactly that many printable result bytes. Shell metacharacters are rejected as well; the text is dispatched only to the in-firmware parser and is never passed to a host shell. Firmware without the OTA CLI feature returns <code>ERR_CODE_UNSUPPORTED_CMD</code>.</p> <p><code>CMD_BLE_MOTA_SOURCE</code> (<code>0x4B</code>) has one action byte:</p> Action Meaning <code>0</code> Read status without changing it. <code>1</code> Attach and enumerate the subscribed Bluetooth host's <code>.mota</code> catalog. <code>2</code> Detach the Bluetooth source. <p>Current firmware returns eleven bytes (legacy protocol-v14 previews returned the seven-byte prefix only):</p> <pre><code>00 action flags offered_le16 advertised_le16 source_packets_sent_le32\n</code></pre> <p>Flag bit <code>0x01</code> means the encrypted GATT channel is connected and Device Request notifications are enabled. Bit <code>0x02</code> means the Bluetooth catalog is attached. Bit <code>0x04</code> means USB or another folder transport currently owns the source slot. Start without a ready subscription, or while another source link owns the slot, returns <code>ERR_CODE_BAD_STATE</code>. A non-nRF52 Full Companion returns <code>ERR_CODE_UNSUPPORTED_CMD</code>. <code>source_packets_sent</code> is a per-attachment count of OTA packets accepted by the Companion's LoRa transmit adapter, including catalog/manifest traffic, data, proofs, and retries. It wraps as an unsigned 32-bit value. Clients should accept the legacy seven-byte response and display the packet counter as unavailable.</p> <p>After a successful start, the device sends the same bounded seeder frames used by <code>motatool serve</code> on Device Request:</p> <pre><code>device -&gt; host: 'M' 'S' op args... xor(op || args)\nhost -&gt; device: 'm' 's' op status payload... xor(all prior bytes)\n</code></pre> <p>Device requests are at most 11 bytes. A source response is at most 197 bytes. The host may split one response across multiple write-with-response operations when the negotiated ATT payload is smaller; it must preserve byte order and must not interleave another response. Bad checksums, partial frames, overflow, unsubscribe, loss of encryption, or disconnect fail closed. The firmware then detaches the catalog and stops advertising its entries. USB and Bluetooth folder sources are mutually exclusive.</p> <p>A Linux reference controller and seeder is provided at <code>tools/ble_mota/ble_mota_seeder.py</code>. It verifies every input with <code>motatool</code> before offering it. A mobile implementation should apply the same complete container verification before serving files.</p>"},{"location":"companion_protocol/#1-app-start","title":"1. App Start","text":"<p>Purpose: Initialize communication with the device. Must be sent first after connection.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x01\nBytes 1-7: Reserved (currently ignored by firmware)\nBytes 8+: Application name (UTF-8, optional)\n</code></pre> <p>Example (hex):</p> <pre><code>01 00 00 00 00 00 00 00 6d 63 63 6c 69\n</code></pre> <p>Response: <code>PACKET_SELF_INFO</code> (0x05)</p>"},{"location":"companion_protocol/#2-device-query","title":"2. Device Query","text":"<p>Purpose: Query device information.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x16\nByte 1: Highest companion protocol version understood by the app\n</code></pre> <p>Example (hex):</p> <pre><code>16 0E\n</code></pre> <p>Response: <code>PACKET_DEVICE_INFO</code> (0x0D) with device information</p>"},{"location":"companion_protocol/#3-get-channel-info","title":"3. Get Channel Info","text":"<p>Purpose: Retrieve information about a specific channel.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x1F\nByte 1: Channel index (0 through max_channels - 1)\n</code></pre> <p>Example (get channel 1):</p> <pre><code>1F 01\n</code></pre> <p>Response: <code>PACKET_CHANNEL_INFO</code> (0x12) with channel details</p>"},{"location":"companion_protocol/#4-set-channel","title":"4. Set Channel","text":"<p>Purpose: Create or update a channel on the device.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x20\nByte 1: Channel index (0 through max_channels - 1)\nBytes 2-33: Channel Name (32 bytes, UTF-8, null-padded)\nBytes 34-49: Secret (16 bytes)\n</code></pre> <p>Total Length: 50 bytes</p> <p>Channel index: - Slot count is build-specific. Read <code>max_channels</code> from byte 3 of   <code>PACKET_DEVICE_INFO</code>; current profiles commonly expose 1, 8, or 40 slots. - No slot number has an intrinsic public/private meaning.</p> <p>Channel Name: - UTF-8 encoded - Maximum 32 bytes - Padded with null bytes (0x00) if shorter</p> <p>Secret Field (16 bytes): - Supply the exact 16-byte channel key. A private channel normally uses a   cryptographically random key; known public and hashtag channels use their   defined or derived key. - An all-zero key is not the public-channel key.</p> <p>Example (create channel \"SMS\" at index 1 with secret):</p> <pre><code>20 01 53 4D 53 00 00 ... (name padded to 32 bytes)\n    [16 bytes of secret]\n</code></pre> <p>Note: The 32-byte secret variant is unsupported and returns <code>PACKET_ERROR</code>.</p> <p>Response: <code>PACKET_OK</code> (0x00) on success, <code>PACKET_ERROR</code> (0x01) on failure</p>"},{"location":"companion_protocol/#5-send-channel-message","title":"5. Send Channel Message","text":"<p>Purpose: Send a text message to a channel.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x03\nByte 1: 0x00\nByte 2: Channel index (0 through max_channels - 1)\nBytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds)\nBytes 7+: Message Text (UTF-8, variable length)\n</code></pre> <p>Timestamp: Unix timestamp in seconds (32-bit unsigned integer, little-endian)</p> <p>Example (send \"Hello\" to channel 1 at timestamp 1234567890):</p> <pre><code>03 00 01 D2 02 96 49 48 65 6C 6C 6F\n</code></pre> <p>Response: <code>PACKET_MSG_SENT</code> (0x06) on success</p>"},{"location":"companion_protocol/#6-send-channel-data-datagram","title":"6. Send Channel Data Datagram","text":"<p>Purpose: Send a binary datagram to a channel. Unlike channel text messages, datagrams carry no built-in sender identity and no timestamp - applications needing either must encode them inside the binary payload.</p> <p>Command Format:</p> <pre><code>Byte 0:                         0x3E\nByte 1:                         Channel index (0 through max_channels - 1)\nByte 2:                         Encoded path descriptor (0xFF = flood)\nBytes 3+:                       Encoded path bytes (omitted for 0xFF)\nNext 2 bytes (little-endian):   Data Type (`data_type`, uint16)\nRemaining bytes:                Binary payload (variable length)\n</code></pre> <p>For a direct send, the descriptor's low six bits are the hash count and its high two bits are the hash size minus one. Current mesh packets accept one-, two-, or three-byte hashes; the four-byte code is reserved. The following path therefore occupies <code>hash_count * hash_size</code> bytes; the descriptor itself is not a raw byte count.</p> <p>Example (flood, <code>DATA_TYPE_DEV</code>, payload <code>A1 B2 C3</code>, channel 1):</p> <pre><code>3E 01 FF FF FF A1 B2 C3\n</code></pre> <p>Data Type / Transport Mapping: - <code>0x0000</code> (<code>DATA_TYPE_RESERVED</code>) is invalid and rejected with <code>PACKET_ERROR</code>. - <code>0xFFFF</code> (<code>DATA_TYPE_DEV</code>) is the developer namespace for experimenting and developing apps. - Registered application/community namespaces occupy <code>0x0100</code>-<code>0xFEFF</code>; the remaining nonzero ranges are reserved for internal or development use. See the Registered data_type values table below.</p> <p>Limits: - Maximum payload length is <code>MAX_GROUP_DATA_LENGTH = MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 3 = 165</code> bytes. - Larger payloads are rejected with <code>PACKET_ERROR</code> (<code>ERR_CODE_ILLEGAL_ARG</code>).</p> <p>Response: <code>PACKET_OK</code> (0x00) on success, or <code>PACKET_ERROR</code> (0x01) with one of: - <code>ERR_CODE_NOT_FOUND</code> (2) - unknown <code>channel_idx</code> - <code>ERR_CODE_ILLEGAL_ARG</code> (6) - invalid <code>path_len</code>, reserved <code>data_type</code> (<code>0x0000</code>), or payload larger than <code>MAX_GROUP_DATA_LENGTH</code> - <code>ERR_CODE_TABLE_FULL</code> (3) - outbound send queue is full; retry later</p> <p>Inbound datagrams are delivered to the host via <code>RESP_CODE_CHANNEL_DATA_RECV</code> (0x1B); see Receive Channel Data Datagram.</p>"},{"location":"companion_protocol/#registered-data_type-values","title":"Registered <code>data_type</code> values","text":"<p><code>data_type</code> is an application identifier, not a payload-format identifier. Each registered value identifies an application that owns its own internal payload schemas. The firmware does not inspect payload contents - <code>data_type</code> is transported opaquely.</p> Value Constant Purpose 0x0000 <code>DATA_TYPE_RESERVED</code> Reserved; invalid on send 0x0001 - 0x00FF - Reserved for internal use 0x0100 - 0xFEFF - Registered application namespaces (see number_allocations.md) 0xFF00 - 0xFFFE - Testing/development; no registration required 0xFFFF <code>DATA_TYPE_DEV</code> Developer/experimental namespace <p>To register a new application, submit a PR adding a row to the table in docs/number_allocations.md. Internal sub-formats within an allocated application ID are owned by that application and are not tracked in MeshCore firmware or this document.</p>"},{"location":"companion_protocol/#receive-channel-data-datagram","title":"Receive Channel Data Datagram","text":"<p>Inbound group datagrams (radio-level <code>PAYLOAD_TYPE_GRP_DATA</code>, 0x06) are forwarded to the host as <code>RESP_CODE_CHANNEL_DATA_RECV</code> notifications.</p> <p>Frame Format (<code>RESP_CODE_CHANNEL_DATA_RECV</code>, 0x1B):</p> <pre><code>Byte 0:                 0x1B (packet type)\nByte 1:                 SNR (signed int8, scaled x4 - divide by 4.0 to recover dB)\nBytes 2-3:              Reserved (clients MUST ignore)\nByte 4:                 Channel index (0 through max_channels - 1)\nByte 5:                 Path Length (actual path length when flooded, otherwise 0xFF for direct)\nBytes 6-7:              Data Type (uint16 little-endian)\nByte 8:                 Data Length\nBytes 9 .. 8+data_len:  Payload\n</code></pre> <p>Path bytes are not forwarded: Only <code>path_len</code> is reported in the receive frame - the path itself is not copied to the host. There are no path bytes between byte 5 and the data_type field at bytes 6-7, regardless of <code>path_len</code>.</p> <p>Path Length semantics differ between send and receive:</p> Direction <code>path_len = 0xFF</code> <code>path_len != 0xFF</code> Send Flood the network Direct route; the encoded path follows (low 6 bits = hash count, top 2 bits + 1 = hash size; on-wire byte count = <code>hash_count x hash_size</code>) Receive Packet arrived via direct route Packet was flooded; this is the encoded <code>pkt-&gt;path_len</code> field as observed (no path bytes follow) <p>In other words, the meaning of <code>0xFF</code> is inverted between the two directions, and on receive the field carries metadata only - never a routable path. <code>path_len</code> is an encoded byte (see <code>Packet::isValidPathLen</code> / <code>Packet::writePath</code> in <code>src/Packet.cpp</code>), not a raw byte count.</p> <p>Note: The device may also emit <code>PACKET_MESSAGES_WAITING</code> (0x83) to notify the host that datagrams are queued; poll with <code>CMD_SYNC_NEXT_MESSAGE</code> (0x0A) to retrieve them.</p> <p>Parsing Pseudocode:</p> <pre><code>def parse_channel_data_recv(data):\n    if len(data) &lt; 9:\n        return None\n    snr_byte = data[1]\n    snr = (snr_byte if snr_byte &lt; 128 else snr_byte - 256) / 4.0\n    channel_idx = data[4]\n    path_len = data[5]\n    data_type = int.from_bytes(data[6:8], 'little')\n    data_len = data[8]\n    if 9 + data_len &gt; len(data):\n        return None\n    payload = data[9:9 + data_len]\n    return {\n        'snr': snr,\n        'channel_idx': channel_idx,\n        'path_len': path_len,\n        'data_type': data_type,\n        'payload': bytes(payload),\n    }\n</code></pre>"},{"location":"companion_protocol/#7-get-message","title":"7. Get Message","text":"<p>Purpose: Request the next queued message from the device.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x0A\n</code></pre> <p>Example (hex):</p> <pre><code>0A\n</code></pre> <p>Response:  - <code>PACKET_CHANNEL_MSG_RECV</code> (0x08) or <code>PACKET_CHANNEL_MSG_RECV_V3</code> (0x11) for channel messages - <code>PACKET_CONTACT_MSG_RECV</code> (0x07) or <code>PACKET_CONTACT_MSG_RECV_V3</code> (0x10) for contact messages - <code>PACKET_CHANNEL_DATA_RECV</code> (0x1B) for channel data datagrams - <code>PACKET_NO_MORE_MSGS</code> (0x0A) if no messages available</p> <p>Note: Poll this command periodically to retrieve queued messages. The device may also send <code>PACKET_MESSAGES_WAITING</code> (0x83) as a notification when messages are available.</p>"},{"location":"companion_protocol/#8-get-battery-and-storage","title":"8. Get Battery and Storage","text":"<p>Purpose: Query device battery voltage and storage usage.</p> <p>Command Format:</p> <pre><code>Byte 0: 0x14\n</code></pre> <p>Example (hex):</p> <pre><code>14\n</code></pre> <p>Response: <code>PACKET_BATTERY</code> (0x0C) with battery millivolts and storage information</p>"},{"location":"companion_protocol/#channel-management","title":"Channel Management","text":""},{"location":"companion_protocol/#channel-types","title":"Channel Types","text":"<ol> <li>Public Channel<ul> <li>Uses a publicly known 16-byte key: <code>8b3387e9c5cdea6ac9e5edbaa115cd72</code></li> <li>Anyone can join this channel, messages should be considered public</li> <li>Used as the default public group chat</li> </ul> </li> <li>Hashtag Channels<ul> <li>Uses a secret key derived from the channel name</li> <li>It is the first 16 bytes of <code>sha256(\"#test\")</code></li> <li>For example hashtag channel <code>#test</code> has the key: <code>9cd8fcf22a47333b591d96a2b848b73f</code></li> <li>Traffic is encrypted on air, but anyone who knows or guesses the channel   name can derive the key. Hashtag channels should not be treated as private.</li> <li>Used as a topic based public group chat, separate from the default public channel</li> </ul> </li> <li>Private Channels<ul> <li>Uses a randomly generated 16-byte secret key</li> <li>Messages should be considered private between those that know the secret</li> <li>Users should keep the key secret, and only share with those you want to communicate with</li> <li>Used as a secure private group chat</li> </ul> </li> </ol>"},{"location":"companion_protocol/#channel-lifecycle","title":"Channel Lifecycle","text":"<ol> <li>Set Channel:<ul> <li>Read <code>max_channels</code> from device info, fetch those slots, and choose an   unused slot (normally an empty name and zeroed key)</li> <li>Generate or provide a 16-byte secret</li> <li>Send <code>CMD_SET_CHANNEL</code> with name and a 16-byte secret</li> </ul> </li> <li>Get Channel:<ul> <li>Send <code>CMD_GET_CHANNEL</code> with channel index</li> <li>Parse <code>RESP_CODE_CHANNEL_INFO</code> response</li> </ul> </li> <li>Delete Channel:<ul> <li>Send <code>CMD_SET_CHANNEL</code> with empty name and all-zero secret</li> <li>Or overwrite with a new channel</li> </ul> </li> </ol>"},{"location":"companion_protocol/#message-handling","title":"Message Handling","text":""},{"location":"companion_protocol/#receiving-messages","title":"Receiving Messages","text":"<p>Messages are received via the TX characteristic (notifications). The device sends:</p> <ol> <li>Channel Messages:</li> <li><code>PACKET_CHANNEL_MSG_RECV</code> (0x08) - Standard format</li> <li> <p><code>PACKET_CHANNEL_MSG_RECV_V3</code> (0x11) - Version 3 with SNR</p> </li> <li> <p>Contact Messages:</p> </li> <li><code>PACKET_CONTACT_MSG_RECV</code> (0x07) - Standard format</li> <li> <p><code>PACKET_CONTACT_MSG_RECV_V3</code> (0x10) - Version 3 with SNR</p> </li> <li> <p>Notifications:</p> </li> <li><code>PACKET_MESSAGES_WAITING</code> (0x83) - Indicates messages are queued</li> </ol>"},{"location":"companion_protocol/#contact-message-format","title":"Contact Message Format","text":"<p>Standard Format (<code>PACKET_CONTACT_MSG_RECV</code>, 0x07):</p> <pre><code>Byte 0: 0x07 (packet type)\nBytes 1-6: Public Key Prefix (6 bytes, hex)\nByte 7: Path Length\nByte 8: Text Type\nBytes 9-12: Timestamp (32-bit little-endian)\nBytes 13-16: Signature (4 bytes, only if txt_type == 2)\nBytes 17+: Message Text (UTF-8)\n</code></pre> <p>V3 Format (<code>PACKET_CONTACT_MSG_RECV_V3</code>, 0x10):</p> <pre><code>Byte 0: 0x10 (packet type)\nByte 1: SNR (signed byte, multiplied by 4)\nBytes 2-3: Reserved\nBytes 4-9: Public Key Prefix (6 bytes, hex)\nByte 10: Path Length\nByte 11: Text Type\nBytes 12-15: Timestamp (32-bit little-endian)\nBytes 16-19: Signature (4 bytes, only if txt_type == 2)\nBytes 20+: Message Text (UTF-8)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_contact_message(data):\n    packet_type = data[0]\n    offset = 1\n\n    # Check for V3 format\n    if packet_type == 0x10:  # V3\n        snr_byte = data[offset]\n        snr = ((snr_byte if snr_byte &lt; 128 else snr_byte - 256) / 4.0)\n        offset += 3  # Skip SNR + reserved\n\n    pubkey_prefix = data[offset:offset+6].hex()\n    offset += 6\n\n    path_len = data[offset]\n    txt_type = data[offset + 1]\n    offset += 2\n\n    timestamp = int.from_bytes(data[offset:offset+4], 'little')\n    offset += 4\n\n    # If txt_type == 2, skip 4-byte signature\n    if txt_type == 2:\n        offset += 4\n\n    message = data[offset:].decode('utf-8')\n\n    return {\n        'pubkey_prefix': pubkey_prefix,\n        'path_len': path_len,\n        'txt_type': txt_type,\n        'timestamp': timestamp,\n        'message': message,\n        'snr': snr if packet_type == 0x10 else None\n    }\n</code></pre>"},{"location":"companion_protocol/#channel-message-format","title":"Channel Message Format","text":"<p>Standard Format (<code>PACKET_CHANNEL_MSG_RECV</code>, 0x08):</p> <pre><code>Byte 0: 0x08 (packet type)\nByte 1: Channel index (0 through max_channels - 1)\nByte 2: Path Length\nByte 3: Text Type\nBytes 4-7: Timestamp (32-bit little-endian)\nBytes 8+: Message Text (UTF-8)\n</code></pre> <p>V3 Format (<code>PACKET_CHANNEL_MSG_RECV_V3</code>, 0x11):</p> <pre><code>Byte 0: 0x11 (packet type)\nByte 1: SNR (signed byte, multiplied by 4)\nBytes 2-3: Reserved\nByte 4: Channel index (0 through max_channels - 1)\nByte 5: Path Length\nByte 6: Text Type\nBytes 7-10: Timestamp (32-bit little-endian)\nBytes 11+: Message Text (UTF-8)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_channel_message(data):\n    packet_type = data[0]\n    offset = 1\n\n    # Check for V3 format\n    if packet_type == 0x11:  # V3\n        snr_byte = data[offset]\n        snr = ((snr_byte if snr_byte &lt; 128 else snr_byte - 256) / 4.0)\n        offset += 3  # Skip SNR + reserved\n\n    channel_idx = data[offset]\n    path_len = data[offset + 1]\n    txt_type = data[offset + 2]\n    timestamp = int.from_bytes(data[offset+3:offset+7], 'little')\n    message = data[offset+7:].decode('utf-8')\n\n    return {\n        'channel_idx': channel_idx,\n        'timestamp': timestamp,\n        'message': message,\n        'snr': snr if packet_type == 0x11 else None\n    }\n</code></pre>"},{"location":"companion_protocol/#sending-messages","title":"Sending Messages","text":"<p>Use the <code>SEND_CHANNEL_MESSAGE</code> command (see Commands).</p> <p>Important:  - The shared text envelope permits up to 160 UTF-8 bytes. For channel text,   firmware prepends <code>&lt;sender name&gt;:</code> inside that envelope, so the available   message body is <code>160 - prefix_bytes</code> and varies with the configured name. - Count encoded UTF-8 bytes, not Unicode characters. Split a longer message at   valid UTF-8 boundaries. - Include a chunk indicator (e.g., \"[1/3] message text\")</p>"},{"location":"companion_protocol/#response-parsing","title":"Response Parsing","text":""},{"location":"companion_protocol/#terminology","title":"Terminology","text":"<p>This document uses a spec-level naming convention (<code>PACKET_*</code>) for bytes the firmware sends back to the host. In the firmware source these same values are split across two <code>#define</code> families by purpose:</p> <ul> <li><code>RESP_CODE_*</code> - direct replies to a command (e.g. <code>RESP_CODE_CHANNEL_DATA_RECV</code> = <code>PACKET_CHANNEL_DATA_RECV</code> = 0x1B).</li> <li><code>PUSH_CODE_*</code> - asynchronous notifications not tied to a specific command (e.g. <code>PUSH_CODE_MSG_WAITING</code> = <code>PACKET_MESSAGES_WAITING</code> = 0x83).</li> </ul> <p>Byte values are authoritative; names are aliases. When reading firmware source, <code>RESP_CODE_X</code> / <code>PUSH_CODE_X</code> correspond to this doc's <code>PACKET_X</code> of the same numeric value.</p>"},{"location":"companion_protocol/#response-types","title":"Response types","text":"Value Firmware name Description <code>0x00</code> <code>RESP_CODE_OK</code> Command succeeded. <code>0x01</code> <code>RESP_CODE_ERR</code> Command failed; byte 1 is the error code. <code>0x02</code> <code>RESP_CODE_CONTACTS_START</code> Contact enumeration started. <code>0x03</code> <code>RESP_CODE_CONTACT</code> One contact record. <code>0x04</code> <code>RESP_CODE_END_OF_CONTACTS</code> Contact enumeration ended. <code>0x05</code> <code>RESP_CODE_SELF_INFO</code> Device self-information. <code>0x06</code> <code>RESP_CODE_SENT</code> Send accepted, with route/tag/timeout data. <code>0x07</code> / <code>0x08</code> <code>RESP_CODE_CONTACT_MSG_RECV</code> / <code>RESP_CODE_CHANNEL_MSG_RECV</code> Queued legacy-format message. <code>0x09</code> <code>RESP_CODE_CURR_TIME</code> Current device time. <code>0x0A</code> <code>RESP_CODE_NO_MORE_MESSAGES</code> Offline queue is empty. <code>0x0B</code> <code>RESP_CODE_EXPORT_CONTACT</code> Exported contact bytes. <code>0x0C</code> <code>RESP_CODE_BATT_AND_STORAGE</code> Battery and storage values. <code>0x0D</code> <code>RESP_CODE_DEVICE_INFO</code> Protocol and build information. <code>0x0E</code> <code>RESP_CODE_PRIVATE_KEY</code> Exported identity key, when enabled. <code>0x0F</code> <code>RESP_CODE_DISABLED</code> Requested sensitive feature is disabled. <code>0x10</code> / <code>0x11</code> <code>RESP_CODE_CONTACT_MSG_RECV_V3</code> / <code>RESP_CODE_CHANNEL_MSG_RECV_V3</code> Queued message with SNR fields. <code>0x12</code> <code>RESP_CODE_CHANNEL_INFO</code> Channel slot information. <code>0x13</code> / <code>0x14</code> <code>RESP_CODE_SIGN_START</code> / <code>RESP_CODE_SIGNATURE</code> Signing capacity or completed signature. <code>0x15</code> <code>RESP_CODE_CUSTOM_VARS</code> Custom-variable data. <code>0x16</code> <code>RESP_CODE_ADVERT_PATH</code> Cached advertisement path. <code>0x17</code> <code>RESP_CODE_TUNING_PARAMS</code> Tuning parameters. <code>0x18</code> <code>RESP_CODE_STATS</code> Requested statistics subtype. <code>0x19</code> <code>RESP_CODE_AUTOADD_CONFIG</code> Automatic-contact policy. <code>0x1A</code> <code>RESP_ALLOWED_REPEAT_FREQ</code> Allowed repeat-frequency ranges. <code>0x1B</code> <code>RESP_CODE_CHANNEL_DATA_RECV</code> Queued channel datagram. <code>0x1C</code> <code>RESP_CODE_DEFAULT_FLOOD_SCOPE</code> Default flood-scope data. <code>0x1D</code> <code>RESP_CODE_CLI_REPLY</code> Text returned by <code>CMD_RUN_CLI_COMMAND</code>."},{"location":"companion_protocol/#asynchronous-push-types","title":"Asynchronous push types","text":"Value Firmware name Description <code>0x80</code> <code>PUSH_CODE_ADVERT</code> Advertisement received. <code>0x81</code> <code>PUSH_CODE_PATH_UPDATED</code> A contact path changed. <code>0x82</code> <code>PUSH_CODE_SEND_CONFIRMED</code> A sent message was acknowledged. <code>0x83</code> <code>PUSH_CODE_MSG_WAITING</code> One or more offline frames are waiting. <code>0x84</code> <code>PUSH_CODE_RAW_DATA</code> Raw application data received. <code>0x85</code> / <code>0x86</code> <code>PUSH_CODE_LOGIN_SUCCESS</code> / <code>PUSH_CODE_LOGIN_FAIL</code> Server login result. <code>0x87</code> <code>PUSH_CODE_STATUS_RESPONSE</code> Server status response. <code>0x88</code> <code>PUSH_CODE_LOG_RX_DATA</code> Radio receive log data. <code>0x89</code> <code>PUSH_CODE_TRACE_DATA</code> Completed trace data. <code>0x8A</code> <code>PUSH_CODE_NEW_ADVERT</code> Newly stored contact advertisement. <code>0x8B</code> <code>PUSH_CODE_TELEMETRY_RESPONSE</code> Telemetry response. <code>0x8C</code> <code>PUSH_CODE_BINARY_RESPONSE</code> Binary request response. <code>0x8D</code> <code>PUSH_CODE_PATH_DISCOVERY_RESPONSE</code> Path-discovery response. <code>0x8E</code> <code>PUSH_CODE_CONTROL_DATA</code> Control/discovery data. <code>0x8F</code> <code>PUSH_CODE_CONTACT_DELETED</code> Oldest contact was deleted while making room. <code>0x90</code> <code>PUSH_CODE_CONTACTS_FULL</code> Contact storage is full."},{"location":"companion_protocol/#parsing-responses","title":"Parsing Responses","text":"<p>PACKET_OK (0x00):</p> <pre><code>Byte 0: 0x00\nBytes 1-4: Optional value (32-bit little-endian integer)\n</code></pre> <p>PACKET_ERROR (0x01):</p> <pre><code>Byte 0: 0x01\nByte 1: Error code (optional)\n</code></pre> <p>PACKET_CHANNEL_INFO (0x12):</p> <pre><code>Byte 0: 0x12\nByte 1: Channel Index\nBytes 2-33: Channel Name (32 bytes, null-terminated)\nBytes 34-49: Secret (16 bytes)\n</code></pre> <p>Note: The device returns the 16-byte channel secret in this response.</p> <p>PACKET_DEVICE_INFO (0x0D):</p> <pre><code>Byte 0: 0x0D\nByte 1: Firmware Version (uint8)\nBytes 2+: Variable length based on firmware version\n\nFor firmware version &gt;= 3:\nByte 2: Max Contacts Raw (uint8, actual = value * 2)\nByte 3: Max Channels (uint8)\nBytes 4-7: Active BLE PIN (32-bit little-endian; includes a generated session PIN)\nBytes 8-19: Firmware Build (12 bytes, UTF-8, null-padded)\nBytes 20-59: Model (40 bytes, UTF-8, null-padded)\nBytes 60-79: Version (20 bytes, UTF-8, null-padded)\nByte 80: Client repeat enabled/preferred (firmware v9+)\nByte 81: Path hash mode (firmware v10+)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_device_info(data):\n    if len(data) &lt; 2:\n        return None\n\n    fw_ver = data[1]\n    info = {'fw_ver': fw_ver}\n\n    if fw_ver &gt;= 3 and len(data) &gt;= 80:\n        info['max_contacts'] = data[2] * 2\n        info['max_channels'] = data[3]\n        info['ble_pin'] = int.from_bytes(data[4:8], 'little')\n        info['fw_build'] = data[8:20].decode('utf-8').rstrip('\\x00').strip()\n        info['model'] = data[20:60].decode('utf-8').rstrip('\\x00').strip()\n        info['ver'] = data[60:80].decode('utf-8').rstrip('\\x00').strip()\n\n    if fw_ver &gt;= 9 and len(data) &gt;= 81:\n        info['client_repeat'] = data[80] != 0\n    if fw_ver &gt;= 10 and len(data) &gt;= 82:\n        info['path_hash_mode'] = data[81]\n\n    return info\n</code></pre> <p>PACKET_BATTERY (0x0C):</p> <pre><code>Byte 0: 0x0C\nBytes 1-2: Battery Voltage (16-bit little-endian, millivolts)\nBytes 3-6: Used Storage (32-bit little-endian, KB)\nBytes 7-10: Total Storage (32-bit little-endian, KB)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_battery(data):\n    if len(data) &lt; 3:\n        return None\n\n    mv = int.from_bytes(data[1:3], 'little')\n    info = {'battery_mv': mv}\n\n    if len(data) &gt;= 11:\n        info['used_kb'] = int.from_bytes(data[3:7], 'little')\n        info['total_kb'] = int.from_bytes(data[7:11], 'little')\n\n    return info\n</code></pre> <p>PACKET_SELF_INFO (0x05):</p> <pre><code>Byte 0: 0x05\nByte 1: Advertisement Type\nByte 2: TX Power\nByte 3: Max TX Power\nBytes 4-35: Public Key (32 bytes, hex)\nBytes 36-39: Advertisement Latitude (32-bit little-endian, divided by 1e6)\nBytes 40-43: Advertisement Longitude (32-bit little-endian, divided by 1e6)\nByte 44: Multi ACKs\nByte 45: Advertisement Location Policy\nByte 46: Telemetry Mode (bitfield)\nByte 47: Manual Add Contacts (bool)\nBytes 48-51: Radio Frequency (32-bit little-endian, divided by 1000.0)\nBytes 52-55: Radio Bandwidth (32-bit little-endian, divided by 1000.0)\nByte 56: Radio Spreading Factor\nByte 57: Radio Coding Rate\nBytes 58+: Device Name (UTF-8, variable length, no null terminator required)\n</code></pre> <p>Parsing Pseudocode:</p> <pre><code>def parse_self_info(data):\n    if len(data) &lt; 36:\n        return None\n\n    offset = 1\n    info = {\n        'adv_type': data[offset],\n        'tx_power': data[offset + 1],\n        'max_tx_power': data[offset + 2],\n        'public_key': data[offset + 3:offset + 35].hex()\n    }\n    offset += 35\n\n    lat = int.from_bytes(data[offset:offset+4], 'little') / 1e6\n    lon = int.from_bytes(data[offset+4:offset+8], 'little') / 1e6\n    info['adv_lat'] = lat\n    info['adv_lon'] = lon\n    offset += 8\n\n    info['multi_acks'] = data[offset]\n    info['adv_loc_policy'] = data[offset + 1]\n    telemetry_mode = data[offset + 2]\n    info['telemetry_mode_env'] = (telemetry_mode &gt;&gt; 4) &amp; 0b11\n    info['telemetry_mode_loc'] = (telemetry_mode &gt;&gt; 2) &amp; 0b11\n    info['telemetry_mode_base'] = telemetry_mode &amp; 0b11\n    info['manual_add_contacts'] = data[offset + 3] &gt; 0\n    offset += 4\n\n    freq = int.from_bytes(data[offset:offset+4], 'little') / 1000.0\n    bw = int.from_bytes(data[offset+4:offset+8], 'little') / 1000.0\n    info['radio_freq'] = freq\n    info['radio_bw'] = bw\n    info['radio_sf'] = data[offset + 8]\n    info['radio_cr'] = data[offset + 9]\n    offset += 10\n\n    if offset &lt; len(data):\n        name_bytes = data[offset:]\n        info['name'] = name_bytes.decode('utf-8').rstrip('\\x00').strip()\n\n    return info\n</code></pre> <p>PACKET_MSG_SENT (0x06):</p> <pre><code>Byte 0: 0x06\nByte 1: Route Flag (0 = direct, 1 = flood)\nBytes 2-5: Tag / Expected ACK (4 bytes, little-endian)\nBytes 6-9: Suggested Timeout (32-bit little-endian, milliseconds)\n</code></pre> <p>PACKET_SEND_CONFIRMED (0x82):</p> <pre><code>Byte 0: 0x82\nBytes 1-4: ACK code (32-bit little-endian)\nBytes 5-8: Round-trip time (32-bit little-endian, milliseconds)\n</code></pre>"},{"location":"companion_protocol/#error-codes","title":"Error Codes","text":"<p><code>PACKET_ERROR</code> (0x01) carries a single-byte error code in byte 1. Values match the <code>ERR_CODE_*</code> constants defined in <code>examples/companion_radio/MyMesh.cpp</code>:</p> Code Constant (firmware) Description 1 <code>ERR_CODE_UNSUPPORTED_CMD</code> Unknown or unsupported command byte / sub-command 2 <code>ERR_CODE_NOT_FOUND</code> Target not found (channel, contact, message, etc.) 3 <code>ERR_CODE_TABLE_FULL</code> Internal queue or table is full - retry later 4 <code>ERR_CODE_BAD_STATE</code> Operation not valid in current device state (e.g. iterator already running) 5 <code>ERR_CODE_FILE_IO_ERROR</code> Filesystem or storage I/O failure 6 <code>ERR_CODE_ILLEGAL_ARG</code> Invalid argument (bad length, out-of-range value, reserved field, etc.) <p>Note: Error codes may vary by firmware version. Always check byte 1 of <code>PACKET_ERROR</code> response, and treat unknown codes as generic errors.</p>"},{"location":"companion_protocol/#frame-handling","title":"Frame Handling","text":"<p>BLE implementations enqueue and deliver one protocol frame per BLE write/notification at the firmware layer.</p> <ul> <li>Apps should treat each characteristic write/notification as exactly one companion protocol frame</li> <li>Apps should still validate frame lengths before parsing</li> <li>Future transports or firmware revisions may differ, so avoid assuming fixed payload sizes for variable-length responses</li> </ul>"},{"location":"companion_protocol/#response-handling","title":"Response Handling","text":"<ol> <li>Command-Response Pattern:</li> <li>Send command via RX characteristic</li> <li>Wait for response via TX characteristic (notification)</li> <li>Match the response by the expected response type; frames do not carry a      general command sequence number</li> <li>Handle timeout (typically 5 seconds)</li> <li> <p>Use command queue to prevent concurrent commands</p> </li> <li> <p>Asynchronous Messages:</p> </li> <li>Device may send messages at any time via TX characteristic</li> <li>Handle <code>PACKET_MESSAGES_WAITING</code> (0x83) by polling <code>GET_MESSAGE</code> command</li> <li>Parse incoming messages and route to appropriate handlers</li> <li> <p>Validate frame length before decoding</p> </li> <li> <p>Response Matching:</p> </li> <li> <p>Match responses to commands by expected packet type:</p> <ul> <li><code>APP_START</code> -&gt; <code>PACKET_SELF_INFO</code></li> <li><code>DEVICE_QUERY</code> -&gt; <code>PACKET_DEVICE_INFO</code></li> <li><code>GET_CHANNEL</code> -&gt; <code>PACKET_CHANNEL_INFO</code></li> <li><code>SET_CHANNEL</code> -&gt; <code>PACKET_OK</code> or <code>PACKET_ERROR</code></li> <li><code>SEND_CHANNEL_MESSAGE</code> -&gt; <code>PACKET_MSG_SENT</code></li> <li><code>GET_MESSAGE</code> -&gt; <code>PACKET_CHANNEL_MSG_RECV</code>, <code>PACKET_CONTACT_MSG_RECV</code>, <code>PACKET_CHANNEL_DATA_RECV</code>, or <code>PACKET_NO_MORE_MSGS</code></li> <li><code>SEND_CHANNEL_DATA</code> -&gt; <code>PACKET_OK</code> or <code>PACKET_ERROR</code></li> <li><code>GET_BATTERY</code> -&gt; <code>PACKET_BATTERY</code></li> </ul> </li> <li> <p>Timeout Handling:</p> </li> <li>Default timeout: 5 seconds per command</li> <li>On timeout: Log error, clear current command, proceed to next in queue</li> <li>Some commands may take longer (e.g., <code>SET_CHANNEL</code> may need 1-2 seconds)</li> <li> <p>Consider longer timeout for channel operations</p> </li> <li> <p>Error Recovery:</p> </li> <li>On <code>PACKET_ERROR</code>: Log error code, clear current command</li> <li>On connection loss: Clear command queue, attempt reconnection</li> <li>On invalid response: Log warning, clear current command, proceed</li> </ol>"},{"location":"companion_protocol/#example-implementation-flow","title":"Example Implementation Flow","text":""},{"location":"companion_protocol/#initialization","title":"Initialization","text":"<pre><code># 1. Scan for MeshCore device\ndevice = scan_for_device(\"MeshCore\")\n\n# 2. Connect to BLE GATT\ngatt = connect_to_device(device)\n\n# 3. Discover services and characteristics\nservice = discover_service(gatt, \"6E400001-B5A3-F393-E0A9-E50E24DCCA9E\")\nrx_char = discover_characteristic(service, \"6E400002-B5A3-F393-E0A9-E50E24DCCA9E\")\ntx_char = discover_characteristic(service, \"6E400003-B5A3-F393-E0A9-E50E24DCCA9E\")\n\n# 4. Enable notifications on TX characteristic\nenable_notifications(tx_char, on_notification_received)\n\n# 5. Send AppStart command\nsend_command(rx_char, build_app_start())\nwait_for_response(PACKET_SELF_INFO)\n</code></pre>"},{"location":"companion_protocol/#creating-a-private-channel","title":"Creating a Private Channel","text":"<pre><code># 1. Generate 16-byte secret\nsecret_16_bytes = generate_secret(16)  # Use CSPRNG\nsecret_hex = secret_16_bytes.hex()\n\n# 2. Build SET_CHANNEL command\nchannel_name = \"YourChannelName\"\nchannel_index = choose_unused_slot(max_channels)\ncommand = build_set_channel(channel_index, channel_name, secret_16_bytes)\n\n# 3. Send command\nsend_command(rx_char, command)\nresponse = wait_for_response(PACKET_OK)\n\n# 4. Store secret locally\nstore_channel_secret(channel_index, secret_hex)\n</code></pre>"},{"location":"companion_protocol/#sending-a-message","title":"Sending a Message","text":"<pre><code># 1. Build channel message command\nchannel_index = 1\nmessage = \"Hello, MeshCore!\"\ntimestamp = int(time.time())\ncommand = build_channel_message(channel_index, message, timestamp)\n\n# 2. Send command\nsend_command(rx_char, command)\nresponse = wait_for_response(PACKET_MSG_SENT)\n</code></pre>"},{"location":"companion_protocol/#receiving-messages_1","title":"Receiving Messages","text":"<pre><code>def on_notification_received(data):\n    packet_type = data[0]\n\n    if packet_type == PACKET_CHANNEL_MSG_RECV or packet_type == PACKET_CHANNEL_MSG_RECV_V3:\n        message = parse_channel_message(data)\n        handle_channel_message(message)\n    elif packet_type == PACKET_MESSAGES_WAITING:\n        # Poll for messages\n        send_command(rx_char, build_get_message())\n</code></pre>"},{"location":"companion_protocol/#best-practices","title":"Best Practices","text":"<ol> <li>Connection Management:</li> <li>Implement auto-reconnect with exponential backoff</li> <li>Handle disconnections gracefully</li> <li> <p>Store last connected device address for quick reconnection</p> </li> <li> <p>Secret Management:</p> </li> <li>Always use cryptographically secure random number generators</li> <li>Store secrets securely (encrypted storage)</li> <li> <p>Never log or transmit secrets in plain text</p> </li> <li> <p>Message Handling:</p> </li> <li>Send <code>CMD_SYNC_NEXT_MESSAGE</code> when <code>PUSH_CODE_MSG_WAITING</code> is received</li> <li> <p>Implement message deduplication to avoid displaying the same message twice</p> </li> <li> <p>Channel Management:</p> <ul> <li>Fetch all channel slots even if you encounter an empty slot</li> <li>Ideally save new channels into the first empty slot</li> </ul> </li> <li> <p>Error Handling:</p> </li> <li>Implement timeouts for all commands (typically 5 seconds)</li> <li>Handle <code>RESP_CODE_ERR</code> responses appropriately</li> </ol>"},{"location":"companion_protocol/#troubleshooting","title":"Troubleshooting","text":""},{"location":"companion_protocol/#connection-issues","title":"Connection Issues","text":"<ul> <li>Device not found: Ensure device is powered on and advertising</li> <li>Connection timeout: Check Bluetooth permissions and device proximity</li> <li>GATT errors: Ensure proper service/characteristic discovery</li> </ul>"},{"location":"companion_protocol/#command-issues","title":"Command Issues","text":"<ul> <li>No response: Verify notifications are enabled, check connection state</li> <li>Error responses: Verify command format and check error code</li> <li>Timeout: Increase timeout value or try again</li> </ul>"},{"location":"companion_protocol/#message-issues","title":"Message Issues","text":"<ul> <li>Messages not received: Poll <code>GET_MESSAGE</code> command periodically</li> <li>Duplicate messages: Implement message deduplication using timestamp/content as a unique id</li> <li>Message truncation: Send long messages as separate shorter messages</li> </ul>"},{"location":"companion_radio_full/","title":"Full Companion","text":"<p>For runtime on/off commands and board exceptions, see feature switches by role. Open the USB web console for the default ASCII terminal.</p> <p>For practical on/off commands and update directions, see Full Companion feature switches.</p> <p><code>companion_radio_full</code> combines every qualified Companion transport for its platform into one artifact and acts as a host-backed LoRa mOTA source for updating other nodes. Most targets can run those transports simultaneously; the SenseCAP Indicator exception selects one secondary wireless transport per boot as described below.</p> <p>The full Companion is deliberately not a LoRa OTA destination: it has no firmware staging store, refuses <code>ota install</code>, and never advertises its own firmware as an mOTA image.</p> <p>Preference changes through the Companion protocol, WebConfig, or USB terminal report a storage error if saving fails, and restore their previous values. Settings that also change GPS or radio power-saving state restore that state; a busy radio rollback remains pending for recovery instead of reporting success.</p> Capability ESP32 full nRF52 full USB Binary Companion Yes Yes BLE Binary Companion Yes Yes USB ASCII terminal Yes Yes Dedicated USB plaintext logging No - shares the one USB TTY Yes Host-backed LoRa mOTA source WiFi TCP 5001 Exclusive USB mode or encrypted BLE WiFi Companion/WebConfig Yes No - nRF52840 has no WiFi Hardware serial Companion On targets with assigned serial pins On targets with assigned serial pins Ethernet Companion On targets with an Ethernet module On RAK4631 with RAK13800 LoRa self-update No No Optional self-update WiFi on existing dual-app layouts; USB on single-app layouts Bluetooth DFU with a compatible bootloader; USB always supported"},{"location":"companion_radio_full/#sensecap-indicator-transport-and-rendering-exception","title":"SenseCAP Indicator transport and rendering exception","text":"<p>Both SenseCAP Indicator Full layouts keep USB available and start exactly one secondary wireless Companion transport per boot: BLE or infrastructure WiFi. The saved <code>companion.transport</code> selection takes effect after reboot. BLE mode does not start infrastructure WiFi, WebConfig, MQTT, TCP Companion, or network OTA services. WiFi mode never initializes BLE and releases its controller and host memory. LoRa remains the primary radio on the LoRa layout. ESP-NOW remains the primary mesh radio in both ESP-NOW modes, including BLE mode; only the infrastructure-WiFi services are omitted.</p> <p>The requested 4-bit internal render profiles are:</p> Primary radio Secondary Companion transport Canvas LoRa Infrastructure WiFi Native 480x480 LoRa BLE Native 480x480 ESP-NOW Infrastructure WiFi Native 480x480 ESP-NOW BLE 320x320, scaled 1.5x to the 480x480 panel <p>All four modes retain the same 160x160 logical UI. If a contiguous native DMA-capable block is unavailable, startup keeps the device usable with the 320x320 emergency fallback and reports the canvas actually retained. Such a fallback is not a successful native-480 validation result.</p>"},{"location":"companion_radio_full/#build-and-install","title":"Build and install","text":"<p>The target is synthesized by <code>build.sh</code> only for an exact board recipe that has passed the combined-transport size check:</p> <ul> <li>The normal automatic path requires matching WiFi, USB, and BLE recipes on   ESP32, or matching USB and BLE recipes on nRF52.</li> <li>A measured qualification list also promotes an exact BLE recipe when the   same board can safely add its platform's remaining transports. It never   substitutes the pin map or peripherals from another board.</li> </ul> <p>The measured ESP32 additions are M5Stack Unit C6L; XIAO C6/S3, Meshimi, WHY2025 Badge, LilyGo T-LoRa C6, T3S3 SX1262/SX1276, T-Deck, TETH Elite, classic T-Beam SX1262/SX1276, and T-Beam S3 Supreme; Heltec Wireless Tracker, Wireless Paper, E213, E290, T190, CT62, and V4 expansion-kit TFT; Generic ESP-NOW; SenseCAP Indicator ESP-NOW/LoRa; Ebyte EoRa-S3; and Meshadventurer SX1262/SX1268. The measured nRF52 additions are GAT562 Mesh Watch13, LilyGo T-Echo Lite, LilyGo T-Impulse Plus, and Wio Tracker L1 E-Ink. Their old transport-specific names remain available for explicit compatibility builds, but the Full image is the canonical release artifact.</p> <p>Every ESP32 Full image includes ordinary WiFi Companion, WebConfig, and the TCP mOTA services, even when its historical build base was USB- or BLE-only. On <code>Generic_ESPNOW</code> and <code>SenseCapIndicator-ESPNow</code>, ESP-NOW is also the primary mesh radio and shares the same 2.4 GHz hardware. Those two Full images retain B/G/N for ordinary clients alongside ESP-NOW LR. Their ESP-NOW mesh, setup AP, and infrastructure connection all use one persisted channel, which defaults to 1. Configure the router's 2.4 GHz radio and every other primary ESP-NOW node for that same fixed channel. Turning Companion WiFi off stops its TCP/AP services but deliberately leaves the ESP-NOW mesh radio running on the selected channel.</p> <p>Every ESP32 Full Companion with a station connection synchronizes its UTC clock from NTP after boot and explicitly refreshes it every 24 hours. The common WiFi path owns this for non-MQTT and runtime-unconfigured nodes; a configured MQTT bridge owns the same boot-and-daily schedule. Successful sync updates an attached hardware RTC as well as the ESP32 clock and suppresses LoRa clock fallback for that boot. Reconnecting WiFi preserves the existing daily deadline. A timeout leaves the existing clock and fallback intact and retries without blocking radio work.</p> <p>Inspect or change the shared channel from the Full Companion text terminal:</p> <pre><code>get espnow.channel\nset espnow.channel 6\nreboot\n</code></pre> <p>The accepted range is 1 through 13; use only a channel permitted in your region and supported by the router. The setter persists the selection, but the running radio stays on its current channel until reboot. Coordinate the change across every primary ESP-NOW node and the router before rebooting, or the node will lose one or both links. This primary-radio setting is not <code>bridge.channel</code>; that command belongs to the separate ESP-NOW bridge feature. To attach a LoRa-primary <code>*_repeater_bridge_espnow</code> gateway to these nodes, match its <code>bridge.channel</code> and select <code>set bridge.format raw</code>; the bridge's backward-compatible default is the distinct wrapped format. WiFi power saving cannot put infrastructure WiFi and ESP-NOW on different channels. On these two primary-ESP-NOW Full targets, <code>max</code> is unavailable because maximum modem sleep can make the station miss ESP-NOW broadcasts; use <code>min</code> for WiFi/BLE/ESP-NOW coexistence. The firmware also holds the ESP-IDF RF wake reference for the primary mesh radio, so the ESP-NOW receiver remains continuous even though the reported coexistence setting is <code>min</code>.</p> <p>List the available targets:</p> <pre><code>bash build.sh list | grep companion_radio_full\n</code></pre> <p>Build by using one exact listed name:</p> <pre><code>bash build.sh build-firmware heltec_v4_r8_companion_radio_full \\\n  --firmware-version v1.17.0\n\nbash build.sh build-firmware RAK_4631_companion_radio_full \\\n  --firmware-version v1.17.0\n</code></pre> <p>To build every canonical full Companion target, select the corresponding interactive menu item or run:</p> <pre><code>bash build.sh build-full-companion-firmwares \\\n  --firmware-version v1.17.0\n</code></pre> <p>Canonical Companion bulk builds also omit legacy <code>_ps</code> and <code>_femoff</code> aliases. Power saving and controllable FEM receive gain are persisted runtime settings; the old names remain available through an explicit <code>build-firmware</code> command for compatibility. Full Companion replaces separate USB, BLE, ordinary WiFi, hardware-serial, Ethernet Companion, Terminal Chat, and USB-only packet-logging release artifacts whenever the exact board supports those combined transports. Direct builds of the legacy targets remain available. RAK4631 repeater and room server Ethernet builds remain separate because they are different standalone roles, not Companion transports. nRF52 separates framed traffic and logs; ESP32 makes those modes mutually exclusive on its one USB TTY. In WebConfig, use the FEM RX boost switch. From the text terminal (USB, or TCP 5002 on ESP32), use:</p> <pre><code>get radio.rxgain\nset radio.rxgain off\nset radio.rxgain on\nget radio.fem.rxgain\nset radio.fem.rxgain off\nset radio.fem.rxgain on\nget radio.fem.txgain\nset radio.fem.txgain off\nset radio.fem.txgain on\n</code></pre> <p><code>radio.rxgain</code> controls the radio chip's boosted receive-gain mode; the FEM commands control the external receive and transmit paths. The selected states are applied immediately and retained after reboot. FEM TX gain is reported as unsupported on boards without software-selectable PA gain.</p> <p>SSD1306 display builds also persist a runtime orientation. This replaces the separate rotated Full Companion release image:</p> <pre><code>get display.rotation\nset display.rotation 90\nset display.rotation 180\nset display.rotation 270\nset display.rotation 0\n</code></pre> <p><code>0</code> resets the screen to that board's compiled default orientation.</p> <p>Heltec E290 and T190 now use their Full Companion artifacts for simultaneous USB, BLE, and WiFi. Their older <code>usb_ble</code>, USB-only, and BLE-only names remain available only as explicit compatibility builds.</p> <p>Heltec V3 and base OLED V4 Full Companion also include the former direct WiFi MQTT Companion capability. Configure and enable MQTT at runtime through WebConfig; the canonical release therefore publishes the Full image instead of a second <code>companion_radio_wifi_mqtt</code> image. V4 TFT and expansion-kit layouts remain separate hardware images because their display and I2C wiring differs.</p> <p>Device power saving is separate from LoRa RXPS. It can be changed in WebConfig with the Device power saving switch or from the text terminal:</p> <pre><code>get powersaving\nset powersaving on\nset powersaving off\n</code></pre> <p>On ESP32, WiFi modem power saving is a third independent setting. Select it in the WebConfig WiFi card, or use the Full Companion text terminal:</p> <pre><code>get wifi.ssid\nget wifi.status\nget wifi.powersave\nget webui\nset wifi.ssid MyNetwork\nset wifi.pwd my-password\nset wifi.powersave min\nset wifi.powersave max\nstart webconfig\nstop webconfig\n</code></pre> <p>ESP32 WiFi Companions with WebConfig, including Full Companion, expose a CLI tab at the node's LAN address. It defaults to on; use <code>get wifi.cli</code>, <code>set wifi.cli on</code>, or <code>set wifi.cli off</code>. Older builds that report the browser terminal as unavailable need a firmware update. The open setup AP does not expose this tab.</p> <p>The browser accepts Companion configuration commands, including <code>get powersaving</code>, <code>set usb.logging on|off</code>, WiFi controls, and MQTT settings. <code>set mqtt.enabled on|off</code> controls MQTT without erasing broker settings; <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, and <code>get mqtt.status</code> distinguish the saved switch from current connections. <code>set logging.output off|usb|wifi|both</code> selects both outputs together. The browser also uses the complete Companion terminal for <code>card</code>, <code>import meshcore://...</code>, <code>list</code>, <code>to</code>, <code>send</code>, <code>login</code>, <code>cmd</code>, and delayed replies, with the same syntax as USB and TCP port 5002. See the terminal command guide for contact import and session ownership. USB MOTA session commands require the USB connection; WiFi host folders use port 5001.</p> <p>On the two primary-ESP-NOW Full targets, the same terminal also provides <code>get espnow.channel</code> and <code>set espnow.channel &lt;1-13&gt;</code>. A channel change is persisted and requires a reboot, unlike a WiFi power-save change.</p> <p>SSID and password writes return their reply first, then restart the Companion WiFi station with the saved credentials. A TCP terminal therefore disconnects shortly after either write; reconnect to the IP reported by the new network. Password entry is masked over USB. <code>get wifi.pwd</code> reads the saved password from any local connection, including binary command <code>0x42</code>; LoRa cannot read it. It may be empty for an open network, an ordinary passphrase of up to 63 characters, or an exact 64-character hexadecimal WPA/WPA2 PSK. Other 64-character values and all longer values are rejected.</p> <p>The normal binary Companion connection can also read or write this setting over USB, BLE, or TCP port 5000 without entering terminal mode. The mode values are <code>0</code> for <code>min</code>, <code>1</code> for <code>none</code>, and <code>2</code> for <code>max</code>; see the Companion protocol. A Full Companion that runs WiFi and BLE simultaneously rejects <code>none</code> because coexistence requires modem sleep. A primary-ESP-NOW Full target also rejects <code>max</code>; unlike infrastructure traffic, peer ESP-NOW broadcasts cannot be buffered by the access point while the station sleeps. If an older image saved a conflicting value, firmware applies and reports <code>min</code> instead. The SenseCAP Indicator uses the active-mode constraints in the exception above: LoRa + WiFi accepts all three values, ESP-NOW + WiFi accepts <code>none|min</code>, LoRa + BLE accepts <code>min|max</code> for the inactive WiFi setting, and ESP-NOW + BLE requires <code>min</code>. Fresh Cascade builds select <code>min</code>, and an existing valid saved selection takes precedence.</p> <p>On radios with RX duty-cycle support, WebConfig and the text terminal also expose the persisted RXPS setting:</p> <pre><code>get radio.rxps\nset radio.rxps off\nset radio.rxps on\nset radio.rxps level 8 preamble 16\nset radio.rxps 65625 60000\n</code></pre> <p>Fresh Cascade-profile Full Companion builds start with RXPS on at level 8 and a 16-symbol preamble. Changing it takes effect immediately and remains selected after reboot.</p> <p>Companion firmware defaults device power saving to on. Version 1.17.1.2 also turns it on once when upgrading an older Companion preference file, including one written by the short-lived default-off regression. After that one-time migration, an explicit <code>set powersaving off</code> selection remains persistent.</p> <p>On ESP32, enabling it lowers the CPU clock to 80 MHz, enables idle yielding, and enables the configured GPS duty cycle. Disabling it restores the normal CPU clock and keeps GPS awake. Active Full Companion transports remain available in both states; on the SenseCAP Indicator this means USB plus the selected BLE or infrastructure-WiFi secondary transport. WiFi modem sleep stays enabled when BLE and the ESP32 WiFi radio are active together because coexistence requires it. Changing device power saving does not overwrite the saved WiFi power-save mode. While a native-USB host is enumerated, the platform sleep attempt is held off so USB CDC remains responsive; detaching the host releases that guard. CPU, radio-modem, and GPS power-saving settings remain active, and USB power from a charger alone does not create a Companion session. The selected state is retained after reboot.</p> <p>On the LilyGo T-Beam 1W Full Companion, press the physical <code>BOOT</code> button once to turn the ESP32 WiFi radio and all WiFi services off or on. The screen confirms <code>WiFi: OFF</code> or <code>WiFi: ON</code>, and the selected state is retained after reboot. When WiFi is off, TCP ports 5000-5002, WebConfig, and MQTT are stopped; USB, BLE, the display, GPS, and LoRa continue to operate. Press BOOT again to restore WiFi, including the saved station or setup-AP mode. On boot, BLE starts two seconds after WiFi/WebConfig so their peak startup allocations do not overlap.</p> <p>Artifacts are written to <code>out/</code> by default.</p> <p>Full Companion behavior is selected with independent capability macros for TempRadio, the OTA CLI, the TCP terminal, USB folder seeding, and memory diagnostics. The legacy <code>COMPANION_RADIO_FULL</code> flag remains an input for older target recipes, but application behavior no longer uses that umbrella as an unrelated compile guard. In particular, ESP32 WiFi/WebConfig terminal controls are compiled from their actual WiFi/WebConfig capability. On targets that run ESP32 WiFi and BLE simultaneously, BLE is started first to avoid heap fragmentation. The SenseCAP Indicator starts only its selected secondary transport. Compile-time prerequisite checks reject inconsistent feature flags. After linking, the capability sidecar verifies USB, BLE, the OTA CLI, TempRadio, and each platform's host-folder transport; it also verifies the TCP terminal, WebConfig, and WiFi seeder on ESP32, plus dedicated logging on nRF52.</p> <p>On 4 MB ESP32 boards, the full target uses a single 3 MB application partition so WiFi, BLE, WebConfig, and source-only mOTA fit in one artifact. The T-Beam 1W Full Companion uses that same LilyGo factory-compatible boot layout on its 16 MB flash because this source-only role does not install updates into a second app slot. Flash the generated <code>-merged.bin</code> when first installing this partition layout. Other boards with 8 MB or more retain dual application partitions. Heltec V2 and TLora V2 use 100 contacts, 8 group channels, and a 16-frame offline queue in this combined profile because of internal DRAM limits. Meshadventurer SX1262 and SX1268 use 100 contacts, 30 group channels, and a 16-frame queue. These capacities preserve the required 8 KiB static internal-DRAM reserve alongside MOTA and all Full transports; their ordinary transport-specific images retain 160 contacts, 40 channels, and 128 queued frames.</p> <p>The 1.17.1.5 memory replacements for Generic ESP-NOW, Heltec Wireless Paper, Wireless Tracker, CT62, V3, Tracker V2, and XIAO C3 Full Companion use 150 contacts and retain their 256-frame queue and Full transports. Export contacts before updating if you have more than 150; entries beyond the new limit may be unavailable and a later save may omit them.</p> <p>Full Companions normally retain 256 pending Companion message frames. ESP32 boards with configured PSRAM retain 512 and allocate that queue from PSRAM before WiFi and BLE start. If PSRAM is unavailable at runtime, allocation falls back through 256 and 128 frames, then to a 16-frame internal buffer. The Full Companion startup memory line reports the capacity actually allocated as <code>offline_queue=&lt;frames&gt;</code>. The queue is volatile and shared by all channels and direct messages; it is not flash-backed history. See Companion offline message queue for all platform defaults and full-queue behavior.</p> <p>Every corrected nRF52 Full profile keeps 256 offline frames normally and temporarily lends 128 slots to mOTA to leave room for Bluetooth tasks, displays and UI allocations. Queue sharing preserves the board's contacts, channels, and USB/Bluetooth mOTA sending. See the memory correction.</p> <p>The nRF52 target inherits the board's ordinary USB Companion installation format and adds BLE plus the serial mOTA source. It does not enable an SD cache or any other board-specific storage behavior; host files are streamed as they are requested. Its image is bounded by the board's normal application region, not the smaller OTAFIX in-place workspace reserved for firmware that can update itself.</p>"},{"location":"companion_radio_full/#interfaces","title":"Interfaces","text":"Platform Interface Purpose Both USB, 115200 baud ASCII after boot or observable USB session reset; automatically switches on the first complete Binary Companion frame Both BLE Binary Companion; display builds show a random session PIN, while headless builds default to <code>123456</code> ESP32 TCP 5000 Binary Companion over WiFi ESP32 HTTP 80 Companion WebConfig and first-boot WiFi setup ESP32 TCP 5001 Host <code>.mota</code> folder from <code>motatool serve --tcp</code> ESP32 TCP 5002 Full Companion text terminal; same role commands as the USB terminal nRF52 USB mOTA mode Host <code>.mota</code> folder from <code>motatool serve --serial</code> nRF52 Encrypted BLE mOTA service Paired phone/tablet/Linux host <code>.mota</code> catalog <p>Delivery-required replies are returned only to the interface which supplied the latest command. A contact-list stream keeps that route locked from <code>CONTACTS_START</code> through <code>END_OF_CONTACTS</code>; commands waiting on another interface are read after the stream finishes. Best-effort asynchronous observations such as adverts remain broadcast so passive clients can refresh their views. Companion session state is device-wide, so use one active Companion application at a time. On nRF52, BLE remains available while USB is in terminal or mOTA mode.</p> <p>On WiFi TCP port 5000, reconnecting from the same IP retains queued outgoing frames. A different IP takes over immediately, but never receives the previous IP's replies: up to four queued frames are parked separately for 30 seconds from takeover. The old IP can reconnect within that window to retrieve them. Only one displaced IP's backlog is retained; if another client also needs that slot, the older backlog is discarded so the new connection is not delayed. This reuses an existing fixed buffer instead of allocating additional frame storage. Pending commands, signing sessions, and contact streams belonging to the displaced WiFi session are canceled immediately; already accepted radio message transmissions are not canceled. Queued frames are retained, not a resumable command session, and IP matching is not authentication. Turning WiFi off clears both queues. Stored message history is unaffected.</p> <p>Ethernet also retains complete queued frames for the same IP. Unlike WiFi, it has no spare backlog buffer: a different IP cancels the old owner's pending operations and discards its queued frames before the new socket is exposed. This keeps Ethernet's existing four-frame memory limit. On both transports, a live same-IP replacement preserves pending operations; an observed disconnect, disabled transport, or rejected input cancels them. Already queued frames can still be replayed on a same-IP reconnect, but canceled operations are not resumed.</p> <p>Partial TCP writes retain the unsent bytes without interleaving later frames. After a reconnect, an incomplete frame restarts from its header; the new TCP connection must not receive only the old connection's trailing bytes.</p> <p>Binary WiFi/Ethernet frames must declare 1\u2013176 payload bytes. Illegal lengths close the connection immediately, without waiting for the announced body or executing a truncated command. An incomplete binary header or payload has a five-second deadline once reception starts; reconnect to send a fresh frame. Ethernet raw-line terminal input has no typing deadline, but an overlong line also closes the connection instead of executing its prefix.</p> <p>USB Binary output is queued as complete length-prefixed frames. Temporary CDC or UART backpressure pauses the contact stream; a frame may drain through a smaller hardware FIFO in ordered chunks, but its remainder is retained and no later frame can interleave with it or cause it to be discarded.</p> <p>When a BLE client requests pairing, a display-equipped build wakes the screen, switches to the first home page, and keeps the active six-digit PIN visible until Bluetooth connects or the two-minute pairing window expires. USB, WiFi, Ethernet, and hardware-serial connections do not suppress this screen. With no saved BLE PIN, display builds generate a new PIN at boot; builds without a physical display use <code>123456</code>. A PIN saved through the Companion protocol takes effect after reboot.</p> <p>The Bluetooth device name is independently configurable. In the text terminal, use <code>get bluetooth.name</code> and <code>set bluetooth.name &lt;name&gt;</code>; use <code>set bluetooth.name default</code> to restore <code>MeshCore-&lt;node name&gt;</code>. The WebConfig Node card exposes the same optional field on Bluetooth-capable ESP32 builds. Custom names replace the complete Bluetooth label rather than inheriting the prefix, accept up to 31 valid UTF-8 bytes, and take effect after reboot. This does not change the node's mesh advertisement name.</p> <p>Every Bluetooth Companion also supports <code>get bluetooth.mac</code> and <code>set bluetooth.mac &lt;address|random|random-every-boot|random-after-connect|default&gt;</code>. A literal address is a BLE random-static identity, <code>random</code> creates one persistent identity, <code>random-every-boot</code> rotates it on startup, and <code>random-after-connect</code> rotates it on the first boot after an authenticated connection while leaving unused boots unchanged. <code>default</code> (or <code>clear</code>) restores the chipset address. None of these values changes the stealth flag. Reboot and re-pair after changing modes or after a rotation. Address rotation clears stale local bonds. On nRF52 this affects the MeshCore application only, not the OTAFIX bootloader's separate BLE DFU identity.</p> <p><code>get bluetooth.stealth</code> and <code>set bluetooth.stealth on|off</code> control an independent flag, defaulting to off. Combine it with a custom address or <code>random</code> to retain the address and bond across boots. With stealth on, normal discovery ends after the first authenticated pairing and only the saved peer may reconnect. Rotating MAC policies still rotate and reopen first pairing when they do; stealth remains enabled. Repeating <code>on</code> keeps an existing bond. Toggle <code>off</code>, then <code>on</code>, then reboot to reset first pairing. All flag changes need reboot. The node still sends directed or allowlisted BLE packets; it is not radio silent.</p> <p>ESP32 ports 5000, 5001, 5002, and WebConfig have no independent login layer. Expose them only on a trusted LAN or temporary setup network. See WiFi setup for credential setup and reconnect behavior.</p>"},{"location":"companion_radio_full/#usb-binary-and-text-terminal-modes","title":"USB Binary and text terminal modes","text":"<p>Full Companion USB starts in the ASCII terminal after boot or an observable USB session reset. MeshCore apps and <code>meshcli</code> send a <code>&lt;</code>-prefixed framed command, which automatically hands the untouched frame to the Binary Companion parser:</p> <pre><code>meshcli -s /dev/ttyACM0 -b 115200 ver\n</code></pre> <p>The automatic probe runs only at an empty prompt. A complete frame confirms binary mode; an incomplete probe returns to ASCII after one second. Binary mode then remains selected until an observable USB session reset, reboot, or the explicit terminal start token. See Full Companion USB CLI and binary switcher for the byte-level state machine, logging and mOTA ownership, recovery paths, and known limitations.</p> <p>Immediately after boot, an ordinary terminal can issue ASCII commands without a start token. If the device is already in Binary Companion mode, open the port with the terminal start token sent automatically:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre> <p>The input map prevents any Binary Companion control bytes received during the mode transition from changing the local terminal's character set or display state while leaving UTF-8 emoji intact. The banner confirms that terminal mode is active; do not enter the start token again after it appears.</p> <p>The terminal supports Companion chat commands, including <code>channels</code>, <code>channel &lt;name-or-slot&gt; &lt;message&gt;</code>, remote administration with <code>login &lt;admin-password&gt;</code> and <code>cmd &lt;remote-command&gt;</code>, and routed <code>trace [recipient-name-or-prefix]</code>, plus local <code>ota</code>, <code>tempradio</code>, and <code>normalradio</code> controls. <code>board</code> reports the exact hardware target. ESP32 Full Companion also provides <code>memory</code>, which reports heap, internal allocation, PSRAM, and offline-queue usage; it is omitted from non-ESP32 help. ESP32 builds also provide local WiFi credential, status, WebConfig, and power-save controls. Every Full Companion provides persistent <code>get/set usb.logging</code> and starts with logging off on a fresh installation.</p>"},{"location":"companion_radio_full/#esp32-single-usb-serial-port","title":"ESP32 single USB serial port","text":"<p>Every ESP32 Full Companion exposes one USB TTY with two exclusive modes. It starts as the ASCII terminal unless a saved logging-on preference boots directly into the logging terminal. If it is already binary, enter its text terminal with <code>+++MESHCORE-TERM-START</code>. For an ESP32 1.17.1.5 USB logging session, run these separate commands:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>The first command is the release's USB power-saving workaround. The same TTY then emits plaintext packet/debug logs and continues accepting CLI commands, including <code>set usb.logging off</code>. Framed Binary Companion is unavailable on USB while logging owns the TTY. Turning logging off sends the command reply, stops the logs, and leaves that TTY in the normal ASCII terminal, matching a fresh Full installation. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch it to Binary Companion afterward. A saved logging-on preference boots directly into this input-capable logging terminal. BLE and Wi-Fi Companion remain available while USB is logging on simultaneous targets. On the SenseCAP Indicator, only the selected BLE or Wi-Fi Companion transport remains available alongside the logging terminal.</p> <p>ESP32 Full Companion uses the repository's Arduino-ESP32 2.x platform base where the board supports it. RC32 and ESP32-C6 retain their board-required Arduino 3.x platform, but follow the same one-TTY policy. No ESP32 Full image creates an optional second CDC interface. The single-TTY behavior applies to native-USB ESP32-S3 boards and boards using a USB-UART bridge.</p>"},{"location":"companion_radio_full/#nrf52-dual-usb-serial-ports","title":"nRF52 dual USB serial ports","text":"<p>Current nRF52 Full Companion firmware can expose two CDC ACM serial interfaces on one physical USB cable:</p> <ul> <li>USB interface <code>00</code> is the primary Companion, text-terminal, and serial-mOTA   source port. It is always present, starts in ASCII after boot, and   automatically hands a complete <code>&lt;</code> frame to Binary Companion.</li> <li>USB interface <code>02</code> is the optional write-only plaintext packet/debug logging   port. Host input on this interface is ignored and cannot invoke firmware   commands.</li> </ul> <p>A fresh Full Companion starts with USB logging off and therefore enumerates only interface <code>00</code>. Use <code>set usb.logging on</code> to save logging on; the reply says that a reboot is required. Use <code>set usb.logging on reboot</code> to save it and have the node reboot automatically after the reply. The second interface appears after that reboot. Likewise, <code>set usb.logging off reboot</code> removes interface <code>02</code>. The optional <code>reboot</code> word is accepted only in these exact command forms and triggers a reboot only when the descriptor actually needs to change.</p> <p>These are Full Companion text-terminal commands. The superficially similar <code>meshcli ... get usb.logging</code> command uses the Binary Companion parameter registry and can report <code>Unknown var usb.logging</code>; it does not forward that line to the text terminal. Enter terminal mode on interface <code>00</code> with the <code>+++MESHCORE-TERM-START</code> token as described above, then issue the command.</p> <p>When logging is on, Linux normally shows two <code>/dev/ttyACM*</code> devices. Match the stable <code>/dev/serial/by-id/*-if00</code> and <code>*-if02</code> links, or use a udev rule matching <code>ID_USB_INTERFACE_NUM</code>, rather than assuming which tty number is assigned. On Windows they appear as two COM ports; identify them by USB interface instead of depending on a particular COM number. The nRF52 bootloader temporarily exposes its normal DFU serial interface during an update.</p> <p>Opening the nRF52 logging port prints <code>MeshCore USB logging port</code> followed by its portable identity, <code>USB CDC 1; interface 02; Linux stable suffix: -if02</code>. <code>get usb.logging</code> reports the same endpoint. Firmware cannot print the exact <code>/dev/ttyACM*</code> or <code>COM*</code> name because Linux, macOS, or Windows assigns that name after USB enumeration; use the <code>*-if02</code> link on Linux to obtain the exact path. For example, <code>readlink -f /dev/serial/by-id/*-if02</code> prints the host-assigned <code>/dev/ttyACM*</code> name.</p> <p>Every ESP32-S3 Full Companion image uses DIO flash mode, including the RAK3112 and RC32 profiles. The S3 ROM supports DIO while loading the software bootloader, and some flash configurations fail before the application starts when a merged image inherits QIO. DIO trades some maximum flash-read throughput for compatibility; it does not change a board's PSRAM type or any ordinary non-Full firmware profile.</p> <p>On nRF52, point MeshCore Companion software, <code>meshcli</code>, and <code>motatool</code> at interface <code>00</code>. When enabled and rebooted, point a plaintext reader or USB-connected MQTT service at interface <code>02</code>. On ESP32, use its only USB TTY for Binary Companion while logging is off, or for the plaintext CLI/logger while logging is on; close one consumer before switching modes. Turning logging off returns to ASCII, so the normal stop token or a valid framed probe is still required before Binary Companion owns the port.</p> <p>ESP32 Full Companion exposes this same text terminal on TCP port 5002. Connect with <code>nc DEVICE_IP 5002</code>; no USB control token is needed. USB terminal mode and the TCP terminal share recipient, login, command, trace, and display state, so only one may own the terminal at a time. The idle startup USB prompt yields to a TCP connection when no USB data client or partial command is present, and is restored when TCP disconnects. An active USB session rejects TCP; entering USB terminal mode later closes an active TCP session. On USB-Serial-JTAG and USB-to-UART hardware, the firmware cannot observe an idle host open, so actual buffered USB activity\u2014not the physical cable alone\u2014claims ownership. Disconnecting TCP clears pending terminal-only state without cancelling Binary Companion delivery or radio retries.</p> <p>Both terminal transports accept <code>reboot</code>. The reply is sent first and the device reboots one second later, so a script can distinguish an accepted reboot from an abruptly lost connection.</p> <p>Port 5002 is plaintext and has no device-local login gate. A remote-admin password entered with <code>login</code> is sent across the LAN connection as typed even though the terminal does not echo it. Use port 5002 only on a trusted LAN or a temporary setup network.</p> <p>For example:</p> <pre><code>channels\nchannel #rgdata Hello from Eugene \ud83d\udc4b\nshow\nshow channels on\nto Hilltop Repeater\npath A1B2C3,D4E5F6\npath 7773D0 7E7662\nlogin my-admin-password\ncmd ver\ntrace\n</code></pre> <p>The terminal <code>list [n]</code> command displays favorite contacts first and orders each favorite/non-favorite group by its most recent advertisement. This does not alter the binary Companion contact-list protocol.</p> <p>Unsolicited terminal output starts in a quiet mode: advertisements and ordinary channel messages are hidden, while <code>#emergency</code> messages remain visible. Use <code>show adverts on|off</code>, <code>show channels on|off</code>, and <code>show emergency on|off</code> to control each category independently; plain <code>show</code> reports their state. These runtime filters affect terminal printing only and reset to their defaults after reboot.</p> <p>The <code>to</code> command selects the remote-administration target. <code>path</code> shows its saved outgoing route; <code>path direct</code>, <code>path clear</code>, or a list separated by spaces, commas, or both changes the route used by subsequent <code>login</code>, <code>send</code>, and <code>cmd</code> commands. Every hop must use the same 2-, 4-, or 6-digit hexadecimal width. Login passwords are masked during entry and limited by the radio protocol to 15 UTF-8 bytes. Wait for the asynchronous login result before using <code>cmd</code>; command replies appear as <code>CLI -&gt; from &lt;name&gt;</code> and use a response window of 300% of the route estimate. <code>DIRECT via path &lt;hop,...&gt;</code> displays the exact saved prefixes copied into the packet. Remote ACL permissions determine which commands the target accepts. The matching reply reports its round-trip time from local queueing through result reception, including radio transit and remote execution. Only one terminal <code>cmd</code> can be pending at a time.</p> <p>Incoming unicast replies are labeled <code>ROUTED</code>. Their exact return prefixes are not available at the destination because each forwarder consumes its prefix; use <code>trace</code> to verify the return route.</p> <p>With no argument, <code>trace</code> uses the current <code>to</code> recipient. A name-prefix argument traces that contact directly without changing the current recipient. The contact must already have a known direct path; results show the SNR at each hop, or a timeout if the round trip does not return.</p> <p>An explicit route can use 1-, 2-, or 4-byte hexadecimal prefixes. Spaces, commas, and mixed separators are accepted:</p> <pre><code>trace path 1 12 34 56 34 12\ntrace path 2 1234,ABCD,5678,ABCD,1234\ntrace path 4 12345678, ABCDEF01 89ABCDEF, ABCDEF01,12345678\n</code></pre> <p>The entered route must include both the outward and return prefixes. Exact three-byte traces are not supported.</p> <p>Return to Binary mode with:</p> <pre><code>+++MESHCORE-TERM-STOP\n</code></pre> <p>An observable USB session reset restores ASCII, including after a Binary client disconnects. Native USB with DTR can detect a terminal closing; ESP32 hardware USB Serial/JTAG detects bus resets and physical host loss. UART bridges usually cannot report a terminal closing, so use the start token if they remain in Binary mode. A different baud rate, including 57600, does not select ASCII.</p> <p>On an ESP32 Full Companion built with <code>OTA_FOLDER_SERIAL</code>, <code>motatool</code> can keep the USB serial port open as an mOTA folder source when WiFi is unavailable:</p> <pre><code>motatool serve --serial /dev/ttyACM0 --dir ./motas -v\n</code></pre> <p>The tool sends the exact completed <code>ota folder on</code> line when it opens the port. Firmware recognizes it in startup ASCII or idle Binary Companion mode, then transfers the port to exclusive USB mOTA ownership before binary request/reply frames begin. The text terminal and Binary Companion are unavailable on that TTY until <code>motatool</code> detaches the folder. This matches the nRF52 ownership behavior described below. TCP port 5001 remains the preferred unattended source transport.</p>"},{"location":"companion_radio_full/#nrf52-usb-mota-mode","title":"nRF52 USB mOTA mode","text":"<p>The nRF52 full target has a third, exclusive USB mode for the host folder. Unmodified <code>motatool serve --serial</code> sends <code>ota folder on</code> when it opens the port. The startup ASCII terminal recognizes that exact completed line, leaves terminal mode, and gives the stream directly to exclusive mOTA handling. If the port is already in Binary Companion mode, the idle binary parser recognizes the same control sequence. The sequence is not examined inside a framed Binary Companion packet. See the switcher guide for the ownership transitions.</p> <p>While mOTA mode owns USB:</p> <ul> <li>mOTA manifests and blocks stream from the computer on demand.</li> <li>USB Binary and the USB text terminal are unavailable.</li> <li>BLE Binary Companion remains available.</li> <li><code>motatool</code> sending <code>ota folder off</code>, or disconnecting the USB data session,   detaches the folder and restores Binary mode.</li> </ul> <p>No modified <code>motatool</code> build, terminal token, or preliminary mode change is required.</p>"},{"location":"companion_radio_full/#nrf52-bluetooth-mota-source","title":"nRF52 Bluetooth mOTA source","text":"<p>Protocol v14 also lets a phone, tablet, or Bluetooth-capable Linux host feed the <code>.mota</code> catalog to an nRF52 Full Companion. Normal Companion commands stay on the Nordic UART service. Firmware data uses a separate GATT service, so binary app traffic cannot be mistaken for a firmware block.</p> <p>The client must pair with the Companion PIN, subscribe to the mOTA Device Request characteristic, and send <code>CMD_BLE_MOTA_SOURCE</code> action <code>start</code> over the normal Binary Companion connection. The source is available only while that encrypted MITM-authenticated connection remains active. Disconnecting, unsubscribing, overflowing a frame, or receiving malformed data automatically detaches the catalog. USB and BLE source modes are mutually exclusive.</p> <p>The included Raspberry Pi reference client validates each <code>.mota</code> with <code>motatool</code>, schedules the local TempRadio window, serves until interrupted, then detaches and restores the normal radio tuple:</p> <pre><code>python3 tools/ble_mota/ble_mota_seeder.py \\\n  --device MeshCore-MyCompanion \\\n  --dir ./motas \\\n  --local 'tempradio 909.950,250,5,5,120'\n</code></pre> <p>Prefer this relative <code>tempradio</code> form when the phone/Pi and radio clocks may disagree. It starts a duration on the Companion and does not compare their wall clocks. Use the absolute <code>tempradioat</code> scheduler only after synchronizing the participating nodes.</p> <p>Use <code>--pair</code> when the Linux host has not already bonded. BlueZ must have an agent capable of entering or confirming the six-digit PIN. Use <code>--source status</code> without <code>--dir</code> for a read-only channel/status check. The complete UUID, frame, action, and status definitions are in the Companion protocol.</p> <p>This reference process stands in for the phone application. A mobile app can use the same sequence while retaining its normal contact and Repeater Admin UI: log in to the destination, put each required node on the same bounded TempRadio tuple, start the local Bluetooth catalog, then send the normal remote <code>ota ls</code>, <code>ota pull</code>, and <code>ota install</code> commands. The destination still checks container geometry, hardware identity, hashes, signature policy, and the OTAFIX bootloader before installation.</p>"},{"location":"companion_radio_full/#serve-mota-images-manually","title":"Serve mOTA images manually","text":"<p>First put the destination, required relays, controller, and source on the same bounded TempRadio tuple. The example frequency below is not legal everywhere; choose a legal tuple supported by every participating radio.</p>"},{"location":"companion_radio_full/#esp32-source","title":"ESP32 source","text":"<p>Use the local console to start TempRadio:</p> <pre><code>nc 192.168.1.50 5002\n</code></pre> <pre><code>tempradio 909.950,250,5,5,120\nota status\n</code></pre> <p>Then start the dedicated TCP seeder:</p> <pre><code>motatool serve --dir ./motas --tcp 192.168.1.50:5001 -v\n</code></pre>"},{"location":"companion_radio_full/#nrf52-source","title":"nRF52 source","text":"<p>Use the USB terminal briefly to schedule TempRadio, then return to Binary mode and close the terminal:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM1\n</code></pre> <pre><code>tempradio 909.950,250,5,5,120\n+++MESHCORE-TERM-STOP\n</code></pre> <p>After sending the stop token, exit <code>picocom</code> with Ctrl-A, Ctrl-X.</p> <p>Start the serial seeder on that same port:</p> <pre><code>motatool serve --dir ./motas --serial /dev/ttyACM1 --baud 115200 -v\n</code></pre> <p><code>motatool</code> switches the port into mOTA mode automatically. Stop it with Ctrl-C to detach the folder. Reopen the terminal and use <code>normalradio</code> if the source should return early; otherwise the saved radio settings return when the bounded window expires.</p> <p>As a cable-free alternative, keep the normal Companion BLE session open and run the Bluetooth reference client shown in the nRF52 Bluetooth section. Do not run the USB seeder at the same time.</p> <p>Both platforms intentionally refuse firmware installation commands such as:</p> <pre><code>ota pull &lt;id&gt; flash\nota install\nota dev ...\n</code></pre>"},{"location":"companion_radio_full/#script-a-complete-update","title":"Script a complete update","text":"<p>The Bash and PowerShell wrappers accept a release ZIP or ready <code>.mota</code>, set up TempRadio, run <code>motatool</code>, monitor the exact image, install it on the destination, and restore the radio path. Use a separate Companion as the controller.</p> <p>For an ESP32 full source:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='target-admin-password'\n\n./tools/lora_ota/lora_ota.sh ./release.zip \"Roof Node\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.50:5001 \\\n  --source-cli-tcp 192.168.1.50:5002\n</code></pre> <p>For an nRF52 full source, the script automatically detects the token-switched terminal and uses the same source port sequentially for control and seeding:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='target-admin-password'\n\n./tools/lora_ota/lora_ota.sh ./release.zip \"Roof Node\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <pre><code>$env:MESHCORE_ADMIN_PASSWORD = 'target-admin-password'\n\n&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.zip' 'Roof Node' `\n  --controller-serial COM7 `\n  --source-serial COM8\n</code></pre> <p>See the start-to-finish LoRa OTA guide for package selection, nRF52 in-place deltas, relays, trust checks, and recovery behavior.</p>"},{"location":"companion_usb_ascii_validation/","title":"USB Companion ASCII default validation","text":"<p>The updated 1.17.1.6 Companion release covers 103 USB-enabled profiles: 52 ESP32 Full, 43 nRF52 Full, four RP2040 USB, and four STM32 USB. The BLE-only WM1110 image has no USB interface and is outside this change.</p>"},{"location":"companion_usb_ascii_validation/#behavior-and-cause","title":"Behavior and cause","text":"<p>Ordinary USB Companions previously started in Binary mode. Full Companions started in ASCII, but host-session cleanup could select or retain Binary mode for the next connection.</p> <p>All USB Companions now select ASCII before framed dispatch begins. An observable USB session boundary cancels old USB operations and clears partial input, queued protocol output, frame ownership, and mOTA attachment before restoring ASCII. A network terminal can defer that restoration; a new USB binary client that connects during the deferral keeps its chosen mode. BLE and network Companion transports keep their existing binary protocol.</p> <p>A complete framed app command still selects Binary mode automatically. An incomplete initial probe returns to ASCII after one second. Explicit terminal start/stop controls remain available.</p> <p>Session detection depends on the hardware. Native USB with DTR can detect a terminal closing. ESP32 hardware USB Serial/JTAG observes bus resets and host loss, but cannot reliably observe a program closing its handle. UART bridges usually cannot observe that close either. Idle time never forces an active binary app back into ASCII; use the start token on a port that remains Binary. See the USB mode guide.</p>"},{"location":"companion_usb_ascii_validation/#automated-validation","title":"Automated validation","text":"<ul> <li>The real firmware startup and reset functions are compiled and executed for   nRF52, ESP32 TinyUSB, ESP32 hardware USB, and RP2040, with and without the   Full macro. Cases include reconnecting from Binary or ASCII, delayed cleanup,   mOTA cancellation, network ownership, and a new binary client during deferral.</li> <li>55 native serial-mode/flow-control tests and 11 terminal-session/diagnostic   tests passed locally, along with 49 USB Python tests and the picker tests.</li> <li>STM32 number formatting is tested against an Arduino API without <code>ltoa</code>.   CI also compiles an ordinary RAK 3x72 USB Companion with the real core and   RadioLib, so missing packages and GPIO API incompatibilities fail the build.</li> </ul> <p>The 99 ESP32/nRF52/RP2040 profiles use <code>d4a641ff</code>. The four STM32 profiles additionally use the compatible Arduino 2.12 platform pin and build test in <code>d2c52e4d</code>. Both source revisions passed GitHub checks: main repair and STM32 repair.</p> <p>All 103 builds passed capability and RAM qualification. Packaging checks bind each application to its capability and memory manifests, retain the original profile capabilities and download formats, and verify ESP32 application/merged image consistency. Replacement publication verifies public SHA-256 digests before deleting old images and checks that unrelated firmware assets retain their original hashes. Release manifests, checksum lists, picker links, and capacity-note source references follow the new binaries.</p> <p>Publication completed with all 430 uploaded files verified through their public download URLs. The 412 superseded firmware/manifest files were removed. The remaining 1,837 assets kept their original hashes, and all five release checksum lists matched the final GitHub asset digests.</p> <p>No USB Companion was attached to the local computer for this repair. These results are compilation and automated protocol tests, not physical USB tests across the board matrix.</p>"},{"location":"companion_usb_client_validation/","title":"USB Companion client compatibility","text":"<p>The RAK4631 report was reproduced on the MercerWoodMesh Pi with the published <code>RAK_4631_companion_radio_full-v1.17.1.6-halo-keymind-cascade-dev-d4a641ff</code> image. The fixes described here are in the source and test firmware; the existing GitHub release assets have not yet been replaced with this fix. Hardware validation was completed on 2026-09-14 with test builds labeled <code>v1.17.1.6-usb-client-test-0e5955f8</code> (base commit plus these USB fixes).</p>"},{"location":"companion_usb_client_validation/#port-selection","title":"Port selection","text":"Hardware Companion/ASCII port USB logging RAK4631 and other nRF52 Full Companions Primary CDC, Linux <code>*-if00</code> Optional second CDC, <code>*-if02</code> ESP32 Full Companions Primary USB serial port Shares that port; must be off for Binary Companion <p><code>+++MESHCORE-TERM-STOP</code> changes the primary port to Binary Companion. Its <code>OK - Binary mode</code> reply does not move the client to a second port. Close the terminal before opening that same port with <code>meshcli -s PORT infos</code>. Do not use MeshCLI's repeater-mode <code>-r</code> option for a binary Companion connection.</p>"},{"location":"companion_usb_client_validation/#two-reproduced-failures","title":"Two reproduced failures","text":"<ol> <li>Stock <code>meshcore-cli</code> 1.6.3 was tested with <code>meshcore</code> 2.3.10, whose serial client    deliberately deasserts DTR. The nRF52 primary USB gate and response route    both required DTR. A raw battery query returned a valid 14-byte response    with DTR high and no bytes with DTR low.</li> <li>The automatic ASCII banner ended in <code>&gt;</code>. MeshCLI recognized that <code>&gt;</code> as a    binary frame marker and consumed the real response's leading <code>&gt;</code> as a    length byte. Even forcing DTR high in a diagnostic client did not recover    the first <code>APP_START</code> response. Stock MeshCLI exited without node information.</li> </ol> <p>The nRF52 transport now accepts real USB input as evidence of a client, tagged with the current session generation. Close, line-coding, and device-reset events invalidate that evidence; an old reader racing cleanup cannot grant access to a newer session. The write path remains bounded and does not wait for an unread host. CDC1 logging retains its own DTR requirement.</p> <p>The default ASCII terminal now suppresses its banner and unsolicited terminal events until ASCII input arrives. Enter or a command reveals the terminal. A binary probe receives a clean first response. Explicit START/STOP remains available, and an incomplete binary probe still times out back to ASCII.</p> <p>On a shared logging port, STOP now reports <code>ERROR: set usb.logging off before Binary mode</code> while logging is enabled. It no longer acknowledges Binary mode and immediately reclaims the port for ASCII logging.</p>"},{"location":"companion_usb_client_validation/#hardware-validation","title":"Hardware validation","text":"<p>The RAK4631 Full test firmware passed with an unmodified installed MeshCLI and its normal DTR-low serial library:</p> <ul> <li>ASCII <code>ver</code> from the default mode, without START;</li> <li>explicit STOP acknowledgement followed by 10 binary battery queries;</li> <li>10 immediate close/reopen queries each with DTR low and high;</li> <li>10 stock-library reconnects and three separate <code>meshcli ... infos</code> runs;</li> <li>all of the above while the second CDC streamed logs: 598 bytes received,   no logging disconnections.</li> </ul> <p>The Heltec V4 Full Companion also passed using its ESP32-S3 USB Serial/JTAG interface, with USB logging disabled:</p> <ul> <li>default ASCII <code>ver</code>, then STOP and 10 clean binary battery replies;</li> <li>10 stock-library reconnects and three unmodified <code>meshcli ... infos</code> runs;</li> <li>a stock-client connection directly after reboot, without either mode token.</li> </ul> <p>The shared-port logging policy was exercised on the V4 as well. With logging on, STOP returned the explicit error, a binary probe could not claim the port, and stock MeshCLI could not connect. After <code>set usb.logging off</code>, STOP worked, 10 binary replies were clean, and three stock-client reconnects succeeded.</p> <p>After testing, the V4's complete original flash snapshot was restored and verified by the flasher. Its original <code>v1.17.1-soak-v4-B</code> firmware answered again, and the previously active memory-soak collector was restarted. This test interrupted that board's uptime; the restored firmware starts a new run. Fresh successful V4 telemetry was verified at <code>2026-09-14T19:46:01Z</code>. The RAK4631 remains on the patched Full Companion test build with its separate logging interface enabled. The Pi's previously active services were restored.</p> <p>The nRF52 DTR stress sequence is deliberately not used on ESP32. Changing those control lines during immediate close/reopen triggered the V4's hardware bootloader and produced an <code>ESP</code> boot message. Preselecting RTS before opening did not prevent that transition on this host. ESP32 reconnect results above use the unmodified client's normal connection sequence instead.</p> <p>The test issues local information queries only. It does not transmit test chat messages over LoRa. Firmware installation and logging configuration are separate from the reusable test runner:</p> <pre><code>python3 tools/hil/companion_usb_client.py \\\n  --port /dev/serial/by-id/PRIMARY-if00 \\\n  --logging-port /dev/serial/by-id/LOGGING-if02 \\\n  --test-dtr --cycles 10 --output usb-client-results.json\n</code></pre> <p>Replace the example paths with the device's actual stable paths. Install <code>meshcore-cli</code> in the Python environment used for the test. Start after a fresh reboot so the default-ASCII check has a new session. On ESP32, omit both <code>--logging-port</code> and <code>--test-dtr</code>, and disable USB logging first.</p>"},{"location":"companion_usb_client_validation/#automated-checks","title":"Automated checks","text":"<ul> <li>53 Python USB checks pass, including compiled execution of the real nRF52   callbacks and transport gate with DTR-low clients, cleanup races, early   input, line-coding changes, physical disconnects, full TX FIFO, CDC1 isolation,   and the 1200-baud bootloader entry.</li> <li>The real terminal methods are compiled for ordinary and Full modes to verify   that unsolicited text is suppressed before the first binary response.</li> <li>The actual STOP branch is exercised for logging off, shared-port logging on,   and dedicated-port logging on.</li> <li>63 native serial-switching, flow-control, and terminal-session tests pass.</li> <li>RAK4631 Full and Heltec V4 Full firmware compile and pass their packaged   capability checks.</li> </ul> <p>The USB workflow runs the new compiled regression tests on subsequent changes.</p>"},{"location":"docs/","title":"Local Documentation","text":"<p>This document explains how to build and view the MeshCore documentation locally.</p>"},{"location":"docs/#building-and-viewing-docs","title":"Building and viewing Docs","text":"<pre><code>pip install mkdocs\npip install mkdocs-material\n</code></pre> <ul> <li><code>mkdocs serve</code> - Start the live-reloading docs server.</li> <li><code>mkdocs build</code> - Build the documentation site.</li> </ul>"},{"location":"double_frequency_v4_validation/","title":"Double center-frequency write: V4 transmitter / XIAO receiver","text":"<p>2026-09-14. Completed bounded comparison: neither single nor duplicate frequency writes reached 400/400. The duplicate adds about 86 us per hop. No production default was changed. Both radios are idle with HIL installed; the duplicate-write toggle is off. The earlier descending-SF sweep and its follow-up remain paused; no new exhaustive settling sweep was launched.</p>"},{"location":"double_frequency_v4_validation/#hardware-and-control","title":"Hardware and control","text":"<ul> <li>RX: XIAO ESP32-S3/WIO SX1262, COM31, MAC 28:84:85:b4:09:80. Normal gain   register 0x94, unchanged-modulation cache enabled, buffered 8 MHz SPI.</li> <li>TX: newly connected Heltec V4, COM7, MAC 44:1b:f6:6a:e8:44. Hardware probe   found ESP32-S3, 2 MB embedded PSRAM and 16 MB flash. HIL detected KCT8103L   FEM and reported the amplified TX path; chip RX gain 0x96.</li> <li>User explicitly authorized erasing the V4 without backup. Its full flash   was erased and a verified HIL upload completed. XIAO's previous HIL image   was replaced with a verified same-image A/B-capable build. No private   backup contents were read; RAK and other boards were not touched.</li> <li>SF10/125 kHz, CR4/5, four centers 909.500/909.750/910.000/910.250 MHz,   5.1-symbol visits (41,780 us), 32-symbol TX preamble, zero added settling,   synthetic 16-byte packets, -9 dBm chip request. No extra IRQ polling.</li> </ul> <p>The V4 FEM uses the repository's production detection and TX/RX control. HIL restores RX after success or error on each direct transmit path. The GC1109 branch (not detected here) uses bypass according to GC1109 table 4. The detected KCT8103L uses its amplified path; antenna-port TX power was not measured. This is not a power-matched Indicator/V4 comparison.</p>"},{"location":"double_frequency_v4_validation/#exact-experiment","title":"Exact experiment","text":"<p><code>scanfreqrepeat 1</code> makes the HIL <code>ExperimentalSX1262</code> repeat the same SetRfFrequency (0x86) immediately after the first successful frequency call, before modulation, packet parameters and RX restart. The second call skips the image-calibration check, but keeps normal BUSY/status handling. Only an identified RX-to-RX hop may repeat; ordinary setup/TX does not. Either write's failure propagates through the existing failed profile-apply path. The toggle defaults off at reboot and cannot change during an active scan.</p> <p>Both modes use the same XIAO binary. Actual SPI command counts, not only software policy labels, are checked against one or two 0x86 writes per hop. The modulation cache remains on in both modes.</p>"},{"location":"double_frequency_v4_validation/#rx-only-timing","title":"RX-only timing","text":"<p>Six-second windows in single/double/double/single order, with reboot/clean setup between windows. No reference packets transmitted during this phase.</p> Frequency writes Hops Mean switch Actual 0x86 Actual 0x8B Single, first 142 451.965 us 142 0 Double, first 141 538.213 us 282 0 Double, second 141 538.170 us 282 0 Single, second 142 451.930 us 142 0 <p>Weighted means: 451.948 us single, 538.192 us double: +86.244 us / +19.1%. All 566 hops had zero retune, RX-mode and cache errors. Maximum observed switch costs were 594 us single and 674 us double; these are samples, not hard latency guarantees. Unheld full-cycle means were about 168.942 ms versus 169.285 ms.</p>"},{"location":"double_frequency_v4_validation/#packet-checks","title":"Packet checks","text":"<p>Single first, then double, each up to 100 packets/channel and stopping on its first miss; a 400/400 result would have stopped all RF testing. Neither passed.</p> Frequency writes Valid before first miss Failed packet RF-run mean switch Hops / 0x86 writes Single 1 2, channel 2 452.719 us 235 / 235 Double 4 5, channel 2 542.063 us 255 / 510 <p>Both failed packets were receiver timeouts, with TX success acknowledged, zero device-error flags and RX mode still active. Both settings reported zero retune, RX-mode, cache and RX errors. Ordinary processing after received packets caused one/four modulation rewrites respectively; pure RX-only timing above is the cleaner comparison of the duplicate cost.</p> <p>All five good V4 packets reported -19 dBm RSSI. SNR was +9.0 dB in the single-write sample and +8.2..+9.2 dB (mean +8.675 dB) for four double-write samples. The previous Indicator run had 547 good packets at average -40.547 dBm RSSI, +8.311 dB SNR. Thus this V4 setup was about 21.5 dB stronger as seen by the receiver. Hardware/antenna/placement/power differences remain confounded; neither the Indicator nor close-range effects are proven causes.</p> <p>One versus four successes before a miss is too small and stop-conditioned to establish a reliability improvement or packet-error rate. Repeating center frequency did not remove the observed failure at this setting. No results for lower SFs or added settling delays are claimed for the V4. A weaker received signal is needed before treating a transmitter swap as a clean comparison.</p>"},{"location":"double_frequency_v4_validation/#artifacts-and-checks","title":"Artifacts and checks","text":"<p>Base checkout <code>0e5955f889788a4317863e731b38ffe09e3d5441</code>, branch <code>keymindCascade</code>, plus local uncommitted changes. RadioLib 7.7.1 pinned at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both builds/uploads succeeded and uploader verified written data. The 59 selected host/native tests passed (39 collectors, ten profile, four SX1262, five radio and one receive-mode), including FEM restore on error and frequency-repeat scope/error propagation. Temporary build overlay removed.</p> <p>Actually loaded firmware SHA-256:</p> <ul> <li>XIAO: <code>9f82d86ea78cfa6bc03fef4925f10c918c8b9fc7a96a7d2b565a04bd2f281288</code></li> <li>V4: <code>2ea2ce37d9d66fb4f8ec9cf3cedfbe7d4eb6d08bfe9abe6c817e5afb04885636</code></li> </ul> <p>Raw evidence and byte-preserving SHA-256:</p> <ul> <li>RX-only ABBA:   <code>38ded968a60ff19f45618ec35d75ce46354d81f163879185e9d6ff0e68da3ae0</code></li> <li>Single-write packets:   <code>4cadeba0d22b3ec6158ff295f1becfb57fde7ef8bf7fabbdbc6295f274619557</code></li> <li>Double-write packets:   <code>46bea8d9c095847ef8ccf4a4ed51ab5404eb5bb87d9cf62b832c3298159d1525</code></li> </ul>"},{"location":"esp32_memory_budget/","title":"Classic ESP32 image memory budget","text":"<p>Classic ESP32 has 320 KiB of internal DRAM, but at most 160 KiB can hold statically allocated data. The remaining DRAM is available only through the runtime heap. Bluetooth, tracing, and SDK reservations further constrain the usable region. See Espressif's memory types documentation.</p> <p>An image can therefore approach its static limit while PlatformIO reports less than 40% of the 320 KiB total in use. PSRAM does not expand the region used by ordinary internal <code>.data</code> and <code>.bss</code> allocations.</p>"},{"location":"esp32_memory_budget/#build-enforcement","title":"Build enforcement","text":"<p>Every classic ESP32 environment inheriting <code>esp32_base</code> runs <code>scripts/check_esp32_dram.py</code>. The release builder also adds the script when an ESP32 profile replaces the inherited extra scripts. The check runs before image generation, merging, and uploading, including cached <code>nobuild</code> uploads. It requires the ELF and linker map to be present for those cached operations. The check script must load after <code>merge-bin.py</code> so the merge target retains its pre-action. A merge also requires the bootloader/partition flash layout; <code>nobuild</code> cannot create a bootable merged image when that layout is absent.</p> <p>The check reads <code>dram0_0_seg</code> from the final linker map. SDK reservations are already reflected in that region; Bluetooth's reservation is not subtracted a second time. The occupied span runs from the region origin to <code>_heap_start</code>, including <code>.data</code>, <code>.bss</code>, <code>.noinit</code>, and alignment gaps. The allowed region is the smaller of the linker's region and 160 KiB.</p> <p>Builds must leave at least 8 KiB free within that static region. This is an additional project margin against near-full images, not an Espressif hardware limit or a prediction of free heap. A profile may require a larger margin with <code>custom_esp32_static_dram_reserve</code> in bytes; values below 8192 are rejected. Missing or unrecognized map boundaries also fail the check.</p> <p>For the Heltec V2 build used to investigate the repeater report:</p> Shared repeater defaults Static span Static region Remaining Result Previous 255 scope slots 124,020 B 124,580 B 560 B Rejected Tuned 31 scope slots 108,308 B 124,580 B 16,272 B Passed <p>These measurements remove the board's existing scope-capacity override to exercise the shared defaults. The normal Heltec V2 profile already used 31 scope slots. Exact sizes vary with build flags and SDK versions.</p> <p>To inspect an existing classic ESP32 build:</p> <pre><code>python3 scripts/check_esp32_dram.py .pio/build/Heltec_v2_repeater/firmware.map\npython3 test/test_esp32_dram.py\n</code></pre> <p>ESP32-S2, S3, and C-series chips have different memory maps and do not inherit this classic ESP32 check.</p>"},{"location":"esp32_memory_budget/#boot-versus-running-memory","title":"Boot versus running memory","text":"<p>The build gate checks static placement needed to load and start the image. It never counts heap-only RAM toward that static budget. Allocations made with <code>new</code> or <code>malloc</code> in global constructors consume heap and are not included in the static span. Moving a table there changes its placement, not total RAM consumption.</p> <p>Successful build checks do not prove that every runtime configuration will boot. Hardware validation must still cover startup allocations and the enabled Wi-Fi/Bluetooth services, recording minimum free internal heap and the largest free internal block. Available heap changes during initialization; for example, the Arduino 2.x repeater releases unused Bluetooth controller RAM in <code>initArduino()</code>, after global constructors have run.</p>"},{"location":"esp32_wifi_partition_migration/","title":"ESP32 legacy-partition migration over Wi-Fi","text":"<p>The partition-migration bridge lets a supported ESP32 node move from a small dual-OTA layout to a verified larger dual-OTA layout without cable flashing. It is designed for inaccessible repeaters: the bridge itself fits a legacy 1.25 MiB slot, replaces the table from Wi-Fi, and then exposes Wi-Fi again for the full application image.</p> <p>It currently has explicit, byte-for-byte generated target plans for Arduino ESP32 <code>default_8MB.csv</code> and <code>default_16MB.csv</code>. It does not guess a table for other flash sizes. Adding a board later means adding one reviewed target plan and its generated table-prefix test; the bridge core is otherwise shared.</p> Flash size Target table app0 / app1 size Typical board 8 MiB <code>default_8MB.csv</code> 0x330000 / 0x330000 Seeed XIAO ESP32-S3 16 MiB <code>default_16MB.csv</code> 0x640000 / 0x640000 Heltec V4 / V4.3 OLED"},{"location":"esp32_wifi_partition_migration/#what-the-bridge-preserves","title":"What the bridge preserves","text":"<p>Before it touches the partition table, the bridge reads the historical <code>/identity/_main.id</code> SPIFFS file. It requires all 96 bytes (32-byte public key followed by its 64-byte private key), stages them in an NVS namespace that is unchanged by both target layouts, then changes the table. On the first boot with the expanded layout it writes the staged value into SPIFFS, reads it back byte-for-byte, and only then clears the NVS staging record and offers the final uploader.</p> <p>The private identity is the guaranteed preservation boundary. The old SPIFFS image is deliberately not raw-copied into an expanded partition: SPIFFS is not safe to resize that way. Other SPIFFS-backed settings can be recreated after the full image boots.</p>"},{"location":"esp32_wifi_partition_migration/#eligible-source-layout","title":"Eligible source layout","text":"<p>The bridge only accepts a source table that has all of the following:</p> <ul> <li>NVS at <code>0x9000</code>, size <code>0x5000</code>, and OTA metadata at <code>0xE000</code>, size <code>0x2000</code>.</li> <li>Two distinct, non-empty OTA application slots and a non-empty SPIFFS   partition, all inside the physical flash size.</li> <li>A known exact 8 MiB or 16 MiB physical flash capacity and a source table   different from that capacity's target table.</li> </ul> <p>This means the source app-slot and SPIFFS sizes can vary; the bridge validates the live geometry instead of carrying board-name rules. It also ensures it is running from one source OTA slot. If it arrived in B, it CRC-copies itself to the future A address, selects A in OTA metadata, writes the table, and restarts. It therefore works whether the browser OTA updater placed the bridge in legacy A or B.</p> <p>Keep power stable while the bridge is replacing the 4 KiB table sector. A loss of power before that point leaves the old table and source intact. After that small critical write, the selected A copy of the bridge is the recovery path.</p>"},{"location":"esp32_wifi_partition_migration/#build-and-migrate-a-seeed-xiao-esp32-s3","title":"Build and migrate a Seeed XIAO ESP32-S3","text":"<p>The production bridge is a legacy-slot application image:</p> <pre><code>&amp; \"$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe\" run -e xiao_s3_partition_migrator\n</code></pre> <p>Build the Full XIAO image with its 8 MiB table:</p> <pre><code>$env:MESHCORE_ESP32_FULL_BUILD = '1'\n&amp; \"$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe\" run -e Xiao_S3_WIO_repeater_observer_mqtt\n</code></pre> <p>Upload the bridge through the legacy node's existing Wi-Fi browser updater. Then join <code>MeshCore-Migrate</code> (password <code>meshcore-migrate</code>) and wait for Expanded layout ready. Upload the Full app-only <code>.bin</code> from the second build at <code>/update</code>. Do not upload an <code>-merged.bin</code>: merged images include bootloader and table offsets for cable flashing, not browser OTA.</p> <p><code>xiao_s3_partition_legacy_seed</code> is a disposable-hardware test image only. It models the legacy table and an identity file; it is not a deployable repeater.</p>"},{"location":"esp32_wifi_partition_migration/#heltec-v4-v43","title":"Heltec V4 / V4.3","text":"<p>Build <code>heltec_v4_partition_migrator</code>, upload it through the legacy Wi-Fi updater, then upload the Full V4 app-only image after the bridge reports ready. The 16 MiB target table creates two 6.25 MiB OTA slots. See the V4 build notes for its build command.</p>"},{"location":"espnow_bridge_setup/","title":"ESP-NOW bridge: simple setup","text":"<p>Use two ESP32 LoRa boards to join two MeshCore networks with different radio settings. Each board repeats on its own LoRa network, and the boards exchange packets directly over 2.4 GHz ESP-NOW. No router, internet connection, or manual peer pairing is needed.</p> <pre><code>LoRa network A &lt;--&gt; Repeater A &lt;-- ESP-NOW --&gt; Repeater B &lt;--&gt; LoRa network B\n</code></pre>"},{"location":"espnow_bridge_setup/#1-choose-the-firmware","title":"1. Choose the firmware","text":"<p>Install the exact board's Full ESP-NOW bridge repeater image on each board. The target name ends in <code>_repeater_bridge_espnow</code>; a standard Heltec V4 uses <code>heltec_v4_repeater_bridge_espnow</code>. Full/MQTT and Full Companion images are different choices. See the firmware picker guide.</p> <p>Open each board's USB console at 115200 baud and run:</p> <pre><code>get bridge.type\n</code></pre> <p>The answer must be <code>espnow</code>. <code>mqtt</code>, <code>rs232</code>, or <code>none</code> means that image does not provide the ESP-NOW bridge described here.</p>"},{"location":"espnow_bridge_setup/#2-set-each-boards-lora-network","title":"2. Set each board's LoRa network","text":"<p>Configure one board at a time over USB. Replace the placeholders below with the radio settings used by the network on that board's side. Use <code>Bridge-A</code> for the first board and <code>Bridge-B</code> for the second, or choose your own names.</p> <pre><code>set bridge.enabled off\nset name Bridge-A\nset radio &lt;freq&gt;,&lt;bw&gt;,&lt;sf&gt;,&lt;cr&gt;\nreboot\n</code></pre> <p>Do not type the angle-bracket placeholders literally.</p> Radio option Meaning <code>freq</code> LoRa frequency in MHz. Match the local network on this side. <code>bw</code> LoRa bandwidth in kHz. Match that network's bandwidth. <code>sf</code> Spreading factor, 5-12. Match that network's setting. <code>cr</code> Coding-rate value, 5-8. Match that network's setting. <code>name</code> A label to tell the two repeaters apart. It does not pair them. <p><code>set radio</code> requires a reboot to apply. After reconnecting, <code>get radio</code> shows the saved settings. Use permanent radio settings for this setup; <code>tempradio</code> sessions expire.</p>"},{"location":"espnow_bridge_setup/#3-configure-the-esp-now-link-on-both-boards","title":"3. Configure the ESP-NOW link on both boards","text":"<p>Run this block on both boards. Replace <code>YourSharedKey</code> with the same case-sensitive secret on each board, using 1-15 characters. Channel <code>6</code> is an example; both boards must use the same channel.</p> <pre><code>set bridge.enabled off\nset bridge.channel 6\nset bridge.format wrapped\nset bridge.secret YourSharedKey\nset bridge.source tx\nset bridge.delay 500\nset repeat on\nset bridge.enabled on\n</code></pre> <p>These settings are saved across reboot. Bridge changes apply immediately; changing an enabled bridge's channel, format, or secret restarts the bridge. Stopping it first lets you finish configuring both sides before connecting them.</p>"},{"location":"espnow_bridge_setup/#what-each-bridge-option-does","title":"What each bridge option does","text":"Option Choices and purpose <code>bridge.enabled</code> <code>on</code> starts the bridge; <code>off</code> stops it and keeps its saved settings. <code>bridge.channel</code> The 2.4 GHz channel, 1-13. Match it on both boards. This is separate from the LoRa frequency in <code>set radio</code>. <code>bridge.format</code> <code>wrapped</code> is the default for this two-repeater setup and uses the shared secret. <code>raw</code> connects to primary-ESP-NOW nodes such as <code>Generic_ESPNOW</code> or <code>SenseCapIndicator-ESPNow</code>; it ignores the secret. Both peers must use compatible formats. <code>bridge.secret</code> A matching, case-sensitive value of 1-15 characters for <code>wrapped</code> mode. It separates bridge groups; it is not strong encryption. MeshCore's own message encryption remains in place. <code>bridge.source</code> <code>tx</code> crosses packets this repeater transmits on LoRa, after its forwarding decisions; use this for the setup above. <code>rx</code> crosses received packets before those decisions and can pass traffic the local repeater would not forward. <code>bridge.delay</code> Wait before processing a packet received from the other bridge, in milliseconds. Range: 0-10000. Start with the default <code>500</code>. <code>repeat</code> <code>on</code> enables normal LoRa forwarding; <code>off</code> disables forwarding. Keep it <code>on</code> on both bridge repeaters. Normal routing, scope, and packet-filter rules still apply. <code>bridge.type</code> Read-only firmware capability. It must report <code>espnow</code> for this guide. <code>bridge.running</code> Read-only runtime state. <code>on</code> means the local bridge started; it does not prove the other board is reachable. <p>This fork uses <code>set bridge.source tx</code> or <code>rx</code>. Some upstream guides use <code>logTx</code> and <code>logRx</code>; those are not the command values used here.</p> <p>For a LoRa gateway connected to primary-ESP-NOW Companions instead of another LoRa repeater, see raw ESP-NOW compatibility.</p>"},{"location":"espnow_bridge_setup/#4-check-the-link","title":"4. Check the link","text":"<p>Run on both boards:</p> <pre><code>get bridge.enabled\nget bridge.running\nget bridge.channel\nget bridge.format\nget bridge.secret\nget bridge.source\nget bridge.delay\nget repeat\nget radio\n</code></pre> <p>Expected: enabled and running <code>on</code>, matching channel/format/secret, source <code>tx</code>, delay <code>500</code>, repeat <code>on</code>, and the intended LoRa settings on each side.</p> <p>Send a message from a Companion on network A to one on network B, then reply from B to A. Check both directions; configuration readback alone does not test delivery.</p> <p>If it does not work:</p> <ul> <li>Commands are unavailable: check <code>get bridge.type</code> and the firmware choice.</li> <li>Enabled is on but running is off: initialization failed. Reboot and   check again; ensure another WiFi service is not occupying the radio.</li> <li>Both are running but traffic does not cross: compare channel, format,   and secret; confirm each board's LoRa settings were applied with a reboot,   and check the networks' forwarding and scope rules.</li> </ul> <p>A running bridge keeps the device awake, even with device power saving enabled. For every command's full details, see the bridge CLI reference.</p> <p>For a broader comparison with a Linux-based bridge, see the MeshCore Nexus bridging guide.</p>"},{"location":"espnow_bridge_setup/#keep-wardriving-traffic-off-the-bridge","title":"Keep wardriving traffic off the bridge","text":"<p>New generalized repeater filter tables include a third built-in rule that blocks authenticated <code>#wardriving</code> text and data in both bridge directions, at every hop count. The same row blocks crossover between radio profiles:</p> <pre><code>get flood.rule.3\nset flood.rule type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>The same rule can be added with the shorter command:</p> <pre><code>set fr any c=#wardriving m=bc d\n</code></pre> <p>Both forms use the same table. <code>m=b</code> means bridge only, <code>m=c</code> means crossover only, and <code>get fr.N</code> returns a short command for copying a numbered rule.</p> <p>The unnumbered command adds the rule safely on existing devices whose saved tables predate this default. It works with either bridge packet source and both ESP-NOW formats. Nearby same-profile LoRa forwarding retains the separate four-hop default. Use <code>mode=bridge</code> for a bridge-only block, or <code>mode=cross</code> for a crossover-only block. See the mode matrix and examples.</p>"},{"location":"faq/","title":"Frequently Asked Questions","text":"<p>For this fork's 1.17.1.5 USA Cascade release, start with feature switches by role and the USB web console. For nRF52 OTAFIX use the exact board/storage build from OTAFIX 2.4.6; older bootloader links below provide upstream/background context.</p> <p>A list of frequently-asked questions and answers for MeshCore</p> <ul> <li>Frequently Asked Questions</li> <li>1. Introduction<ul> <li>1.1. Q: What is MeshCore?</li> <li>1.2. Q: What do you need to start using MeshCore?<ul> <li>1.2.1. Hardware</li> <li>1.2.2. Firmware</li> <li>1.2.3. Companion Radio Firmware</li> <li>1.2.4. Repeater</li> <li>1.2.5. Room Server</li> </ul> </li> </ul> </li> <li>2. Initial Setup<ul> <li>2.1. Q: How many devices do I need to start using MeshCore?</li> <li>2.2. Q: Does MeshCore cost any money?</li> <li>2.3. Q: What frequencies are supported by MeshCore?</li> <li>2.4. Q: What is an \"advert\" in MeshCore?</li> <li>2.5. Q: Is there a hop limit?</li> </ul> </li> <li>3. Server Administration<ul> <li>3.1. Q: How do you configure a repeater or a room server?</li> <li>3.2. Q: Do I need to set the location for a repeater?</li> <li>3.3. Q: What is the password to administer a repeater or a room server?</li> <li>3.4. Q: What is the password to join a room server?</li> <li>3.5. Q: Can I retrieve a repeater's private key or set a repeater's private key?</li> <li>3.6. Q: The first byte of my repeater's public key collides with an existing repeater on the mesh. How do I get a new private key with a matching public key that has its first byte of my choosing?</li> <li>3.7. Q: My repeater may be suffering from deafness due to high power interference near my mesh's frequency, it is not hearing other in-range MeshCore radios. What can I do?</li> <li>3.8. Q: How do I make my repeater an observer on the mesh?</li> <li>3.9. Q: What is multibyte support? What do 1-byte, 2-byte, 3-byte adverts and messages mean?</li> <li>3.9.1. Q: What path hash sizes will my repeater forward?</li> <li>3.9.2. Q: What determines a packet's path hash size?</li> <li>3.9.3. Q: How do I change my companion's path hash size?</li> <li>3.9.4. Q: What does the CLI command <code>path.hash.mode</code> do on a repeater?</li> <li>3.9.5. Q: Why use 2- or 3-byte path hash for adverts?</li> <li>3.9.6. Q: When can we move away from 1-byte path hash for channel and direct messages?</li> </ul> </li> <li>4. T-Deck Related<ul> <li>4.1. Q: Is there a user guide for T-Deck, T-Pager, T-Watch, or T-Display Pro?</li> <li>4.2. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode?</li> <li>4.3. Q: Why is my T-Deck Plus not getting any satellite lock?</li> <li>4.4. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock?</li> <li>4.5. Q: What size of SD card does the T-Deck support?</li> <li>4.6. Q: What is the public key for the default public channel?</li> <li>4.7. Q: How do I get maps on T-Deck?</li> <li>4.8. Q: Where do the map tiles go?</li> <li>4.9. Q: How to unlock deeper map zoom and server management features on T-Deck?</li> <li>4.10. Q: How to decipher the diagnostics screen on T-Deck?</li> <li>4.11. Q: The T-Deck sound is too loud?</li> <li>4.12. Q: Can you customize the sound?</li> <li>4.13. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts?</li> <li>4.14. Q: How to capture a screenshot on T-Deck?</li> </ul> </li> <li>5. General<ul> <li>5.1. Q: What are BW, SF, and CR?</li> <li>5.2. Q: Do MeshCore clients repeat?</li> <li>5.3. Q: What happens when a node learns a route via a mobile repeater, and that repeater is gone?</li> <li>5.4. Q: How does a node discover a path to its destination and then use it to send messages in the future, instead of flooding every message it sends like Meshtastic?</li> <li>5.5. Q: Do public channels always flood? Do private channels always flood?</li> <li>5.6. Q: What is the public key for the default public channel?</li> <li>5.7. Q: Is MeshCore open source?</li> <li>5.8. Q: How can I support MeshCore?</li> <li>5.9. Q: How do I build MeshCore firmware from source?</li> <li>5.10. Q: Are there other MeshCore related open source projects?</li> <li>5.11. Q: Does MeshCore support ATAK?</li> <li>5.12. Q: How do I add a node to the MeshCore Map?</li> <li>5.13. Q: Can I use a Raspberry Pi to update a MeshCore radio?</li> <li>5.14. Q: Are there projects built around MeshCore?</li> <li>5.15. Q: Are there client applications for Windows or Mac?</li> <li>5.16. Q: Are there any resources that compare MeshCore to other LoRa systems?</li> </ul> </li> <li>6. Troubleshooting<ul> <li>6.1. Q: My client says another client or a repeater or a room server was last seen many, many days ago.</li> <li>6.2. Q: A repeater or a client or a room server I expect to see on my discover list (on T-Deck) or contact list (on a smart device client) are not listed.</li> <li>6.3. Q: How to connect to a repeater via BLE (Bluetooth)?</li> <li>6.4. Q: My companion isn't showing up over Bluetooth?</li> <li>6.5. Q: I can't connect via Bluetooth, what is the Bluetooth pairing code?</li> <li>6.6. Q: My Heltec V3 keeps disconnecting from my smartphone. It can't hold a solid Bluetooth connection.</li> <li>6.7. Q: My RAK/T1000-E/xiao_nRF52 device seems to be corrupted, how do I wipe it clean to start fresh?</li> <li>6.8. Q: WebFlasher fails on Linux with failed to open</li> </ul> </li> <li>7. Other Questions:<ul> <li>7.1. Q: How to update nRF (RAK, T114, Seeed XIAO) companion, repeater and room server firmware over the air using the new simpler DFU app?<ul> <li>7.1.1 Q: Can I update Seeed Studio Wio Tracker L1 Pro using OTA?</li> </ul> </li> <li>7.2. Q: How to update ESP32-based devices over the air?</li> <li>7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?</li> <li>7.4. Q: are the MeshCore logo and font available?</li> <li>7.5. Q: What is the format of a contact or channel QR code?</li> <li>7.6. Q: How do I connect to the companion via Wi-Fi, e.g. using a Heltec V3?</li> <li>7.7. Q: I have a Station G2, or a Heltec V4, or an Ikoka Stick, or a radio with an EByte E22-900M30S or an EByte E22-900M33S module, what should their transmit power be set to?</li> <li>7.8. Q: How do I use Ethernet with a RAK4631?</li> </ul> </li> </ul>"},{"location":"faq/#1-introduction","title":"1. Introduction","text":""},{"location":"faq/#11-q-what-is-meshcore","title":"1.1. Q: What is MeshCore?","text":"<p>A: MeshCore is a multi-platform system for enabling secure text-based communications utilizing LoRa radio hardware. It can be used for Off-Grid Communication, Emergency Response &amp; Disaster Recovery, Outdoor Activities, Tactical Security including law enforcement and private security and also IoT sensor networks. (source)</p> <p>MeshCore is free and open source:</p> <ul> <li>MeshCore is the routing and firmware etc., available on GitHub under MIT license</li> <li>There are clients made by the community, such as the web clients, these are free to use, and some are open source too</li> <li>The cross-platform mobile app developed by Liam Cottle for Android/iOS/PC etc. is free to download and use</li> <li>The T-Deck firmware is developed by Scott at Ripple Radios, the creator of MeshCore, is also free to flash on your devices and use</li> </ul> <p>Some more advanced, but optional features are available on T-Deck if you register your device for a key to unlock. On the MeshCore smartphone clients for Android and iOS/iPadOS, you can unlock the wait timer for repeater and room server remote management over RF feature.</p> <p>These features are completely optional and aren't needed for the core messaging experience. They're like super bonus features and to help the developers continue to work on these amazing features, they may charge a small fee for an unlock code to utilize the advanced features.</p> <p>Anyone is able to build anything they like on top of MeshCore without paying anything.</p>"},{"location":"faq/#12-q-what-do-you-need-to-start-using-meshcore","title":"1.2. Q: What do you need to start using MeshCore?","text":"<p>A: Everything you need for MeshCore is available at:</p> <ul> <li>Main Website: https://meshcore.io</li> <li>Firmware Flasher: https://flasher.meshcore.io</li> <li>MeshCore Firmware on GitHub: https://github.com/meshcore-dev/MeshCore</li> <li>MeshCore Companion Web App: https://app.meshcore.nz</li> <li>MeshCore Map: https://map.meshcore.io</li> <li>Liam Cottle's MeshCore Technical Presentation</li> </ul> <p>You need LoRa hardware devices to run MeshCore firmware as clients or server (repeater and room server).</p>"},{"location":"faq/#121-hardware","title":"1.2.1. Hardware","text":"<p>MeshCore is available on a variety of 433MHz, 868MHz and 915MHz LoRa devices. For example, Lilygo T-Deck, T-Pager, RAK Wireless WisBlock RAK4631 devices (e.g. 19003, 19007, 19026), Heltec V3, Xiao S3 WIO, Xiao C3, Heltec T114, Station G2, Nano G2 Ultra, Seeed Studio T1000-E. More devices are being added regularly.</p> <p>For an up-to-date list of supported devices, please go to https://flasher.meshcore.io</p> <p>To use MeshCore without using a phone as the client interface, you can run MeshCore on a LilyGo T-Deck, T-Deck Plus, T-Pager, T-Watch, or T-Display Pro. MeshCore Ultra firmware running on these devices is a complete off-grid secure communication solution.</p>"},{"location":"faq/#122-firmware","title":"1.2.2. Firmware","text":"<p>MeshCore firmware is organized by role and, for companions, by host transport. The main roles are Companion, Repeater, Room Server, and Sensor. The tree also contains specialized terminal-chat and KISS-modem builds. Availability depends on the board; use the flasher or that board's PlatformIO environments as the current source of truth.</p>"},{"location":"faq/#123-companion-radio-firmware","title":"1.2.3. Companion Radio Firmware","text":"<p>Companion radios connect MeshCore client software to LoRa. Depending on the board and build profile, the companion protocol can be exposed over BLE, USB serial, Wi-Fi, or Ethernet. Some boards also provide a Full Companion profile with additional local administration features. Check the exact build name and transport before flashing. Pending messages are held in a volatile shared queue; capacity depends on the platform and memory profile. See the Companion offline message queue for the exact defaults and limitations. See https://meshcore.io and the web client at https://app.meshcore.nz.</p>"},{"location":"faq/#124-repeater","title":"1.2.4. Repeater","text":"<p>Repeaters are used to extend the range of a MeshCore network. Repeater firmware runs on the same devices that run client firmware. A repeater's job is to forward MeshCore packets to the destination device. It does not forward or retransmit every packet it receives, unlike other LoRa mesh systems.</p> <p>A repeater can be remotely administered using a T-Deck running the MeshCore firmware with remote administration features unlocked, or from a BLE Companion client connected to a smartphone running the MeshCore app.</p>"},{"location":"faq/#125-room-server","title":"1.2.5. Room Server","text":"<p>A room server is a simple BBS server for sharing posts. T-Deck devices running MeshCore firmware or a BLE Companion client connected to a smartphone running the MeshCore app can connect to a room server.</p> <p>Room servers store message history on them and push the stored messages to users. Room servers allow roaming users to come back later and retrieve message history. With channels, messages are either received when it's sent, or not received and missed if the channel user is out of range. Room servers are different and more like email servers where you can come back later and get your emails from your mail server.</p> <p>A room server can be remotely administered using a T-Deck running the MeshCore firmware with remote administration features unlocked, or from a BLE Companion client connected to a smartphone running the MeshCore app.</p> <p>When a client logs into a room server, the client will receive the previously 32 unseen messages.</p> <p>Although room server can also repeat with the command line command <code>set repeat on</code>, it is not recommended nor encouraged. A room server with repeat set to <code>on</code> lacks the full set of repeater and remote administration features that are only available in the repeater firmware.</p> <p>The recommendation is to run repeater and room server on separate devices for the best experience.</p>"},{"location":"faq/#2-initial-setup","title":"2. Initial Setup","text":""},{"location":"faq/#21-q-how-many-devices-do-i-need-to-start-using-meshcore","title":"2.1. Q: How many devices do I need to start using MeshCore?","text":"<p>A: If you have one supported device, flash the BLE Companion firmware and use your device as a client. You can connect to the device using the Android or iOS client via Bluetooth. You can start communicating with other MeshCore users near you.</p> <p>If you have two supported devices, and there are not many MeshCore users near you, flash both to BLE Companion firmware so you can use your devices to communicate with your nearby friends and family.</p> <p>If you have two supported devices, and there are other MeshCore users nearby, you can flash one of your devices with BLE Companion firmware and flash another supported device to repeater firmware. Place the repeater high above ground to extend your MeshCore network's reach.</p> <p>After you flashed the latest firmware onto your repeater device, keep the device connected to your computer via USB serial, use the console feature on the web flasher and set the frequency for your region or country, so your client can remote administer the repeater or room server over RF:</p> <p><code>set freq {frequency}</code></p> <p>The repeater and room server CLI reference is here: https://docs.meshcore.io/cli_commands</p> <p>If you have more supported devices, you can use your additional devices with the room server firmware.</p>"},{"location":"faq/#22-q-does-meshcore-cost-any-money","title":"2.2. Q: Does MeshCore cost any money?","text":"<p>A: All radio firmware versions (e.g. for Heltec V3, RAK, T-1000E, etc.) are free and open source developed by Scott at Ripple Radios.</p> <p>The native Android and iOS client uses the freemium model and is developed by Liam Cottle, developer of meshtastic map at meshtastic.liamcottle.net on GitHub and reticulum-meshchat on GitHub.</p> <p>The T-Deck firmware is free to download and most features are available without cost. To support the firmware developer, you can pay for a registration key to unlock your T-Deck for deeper map zoom and remote server administration over RF using the T-Deck. You do not need to pay for the registration to use your T-Deck for direct messaging and connecting to repeaters and room servers.</p>"},{"location":"faq/#23-q-what-frequencies-are-supported-by-meshcore","title":"2.3. Q: What frequencies are supported by MeshCore?","text":"<p>A: Supported frequencies depend on the radio hardware and the rules for the country in which it operates. Common MeshCore hardware covers portions of the 433, 868, and 915 MHz ISM bands.</p> <p>Use the current regional preset offered by the client or flasher, confirm it with the local MeshCore community, and comply with local frequency, bandwidth, duty-cycle, and power limits. Do not copy an old frequency from this FAQ. Narrow presets commonly use BW62.5 with a lower spreading factor; their exact frequency and SF are region-specific and can change as deployments coordinate.</p> <p>If you have consensus from your community in your region to update your region's preset recommendation, please post your update request on  the #meshcore-app channel on the MeshCore Discord server  to let Liam Cottle know.</p>"},{"location":"faq/#24-q-what-is-an-advert-in-meshcore","title":"2.4. Q: What is an \"advert\" in MeshCore?","text":"<p>A: Advert means to advertise yourself on the network. In Reticulum terms it would be to announce. In Meshtastic terms it would be the node sending its node info.</p> <p>MeshCore allows you to manually broadcast your name, position and public encryption key, which is also signed to prevent spoofing. When you click the advert button, it broadcasts that data over LoRa. MeshCore calls that an Advert. There's two ways to advert, \"zero hop\" and \"flood\".</p> <ul> <li>Zero hop means your advert is broadcast to anyone that can hear it, and that's it.</li> <li>Flooded means it's broadcast and then repeated by all the repeaters that hear it.</li> </ul> <p>MeshCore clients only advertise themselves when the user initiates it. A repeater sends a flood advert once every 12 hours by default. This interval can be configured using the following command:</p> <p><code>set flood.advert.interval {hours}</code></p> <p>The separate <code>set advert.interval {minutes}</code> command controls the local zero-hop advert timer.</p>"},{"location":"faq/#25-q-is-there-a-hop-limit","title":"2.5. Q: Is there a hop limit?","text":"<p>A: Internally the firmware has maximum limit of 64 hops. In real world settings it will be difficult to get close to the limit due to the environments and timing as packets travel further and further. We want to hear how far your MeshCore conversations go.</p>"},{"location":"faq/#3-server-administration","title":"3. Server Administration","text":""},{"location":"faq/#31-q-how-do-you-configure-a-repeater-or-a-room-server","title":"3.1. Q: How do you configure a repeater or a room server?","text":"<p>A: When MeshCore is flashed onto a LoRa device for the first time, it is necessary to set the server device's frequency to make it utilize the frequency that is legal in your country or region.</p> <p>Repeater or room server can be administered with one of the options below:</p> <ul> <li>After a repeater or room server firmware is flashed onto a LoRa device, go to https://config.meshcore.io and use the web user interface to connect to the LoRa device via USB serial. From there you can set the name of the server, its frequency and other related settings, location, passwords etc.</li> </ul> <p></p> <ul> <li> <p>Connect the server device using a USB cable to a computer running Chrome on https://flasher.meshcore.io, then use the <code>console</code> feature to connect to the device</p> </li> <li> <p>Use a MeshCore smartphone client to remotely administer servers via LoRa.</p> </li> <li> <p>A T-Deck running unlocked/registered MeshCore firmware. Remote server administration is enabled through registering your T-Deck with Ripple Radios. It is one of the ways to support MeshCore development. You can register your T-Deck at:</p> </li> </ul> <p>https://buymeacoffee.com/ripplebiz/e/249834</p>"},{"location":"faq/#32-q-do-i-need-to-set-the-location-for-a-repeater","title":"3.2. Q: Do I need to set the location for a repeater?","text":"<p>A: While not required, with location set for a repeater it will show up on the MeshCore map in the future. Set location with the following command:</p> <p><code>set lat &lt;GPS Lat&gt;</code></p> <p><code>set lon &lt;GPS Lon&gt;</code></p> <p>You can get the latitude and longitude from Google Maps by right-clicking the location you are at on the map.</p>"},{"location":"faq/#33-q-what-is-the-password-to-administer-a-repeater-or-a-room-server","title":"3.3. Q: What is the password to administer a repeater or a room server?","text":"<p>A: The default admin password to a repeater and room server is <code>password</code>. Use the following command to change the admin password:</p> <p><code>password {new-password}</code></p>"},{"location":"faq/#34-q-what-is-the-password-to-join-a-room-server","title":"3.4. Q: What is the password to join a room server?","text":"<p>A: The default guest password to a room server is <code>hello</code>. Use the following command to change the guest password:</p> <p><code>set guest.password {guest-password}</code></p>"},{"location":"faq/#35-q-can-i-retrieve-a-repeaters-private-key-or-set-a-repeaters-private-key","title":"3.5. Q: Can I retrieve a repeater's private key or set a repeater's private key?","text":"<p>A: You can issue these commands to get or set a repeater's private key using a USB serial connection.</p> <p><code>get prv.key</code> to print a repeater's private key on the serial console <code>set prv.key &lt;hex&gt;</code> to set a repeater's private key on the serial console</p> <p>Reboot the repeater after <code>set prv.key &lt;hex&gt;</code> command for the new private key to take effect.</p>"},{"location":"faq/#36-q-the-first-byte-of-my-repeaters-public-key-collides-with-an-existing-repeater-on-the-mesh-how-do-i-get-a-new-private-key-with-a-matching-public-key-that-has-its-first-byte-of-my-choosing","title":"3.6. Q: The first byte of my repeater's public key collides with an existing repeater on the mesh. How do I get a new private key with a matching public key that has its first byte of my choosing?","text":"<p>A: You can generate a new private key and specify the first byte of its public key here: https://gessaman.com/mc-keygen</p> <p>Having multiple repeaters with the same first byte ID does not negatively affect the mesh or its functionality. Flood and pathed packets will still reach their destinations. First byte ID collision makes traceroute and path analysis harder because these tools don't know exactly which of the two (or more) colliding repeaters is the one in the path.</p> <p>Best practice is when you set up a new repeater, choose a public key that is not in use. If it is not possible to find a unique first byte for your repeater's public key, choose one that is unique within about 10 miles (16 km) to minimize collision with nearby repeaters.</p>"},{"location":"faq/#37-q-my-repeater-may-be-suffering-from-deafness-due-to-high-power-interference-near-my-meshs-frequency-it-is-not-hearing-other-in-range-meshcore-radios-what-can-i-do","title":"3.7. Q: My repeater may be suffering from deafness due to high power interference near my mesh's frequency, it is not hearing other in-range MeshCore radios. What can I do?","text":"<p>A: This may be due to the SX1262 radio's auto gain control feature. You can use this command to periodically reset its AGC.</p> <p><code>set agc.reset.interval &lt;number&gt;</code></p> <p>The <code>&lt;number&gt;</code> unit is in seconds and is incremented by 4. <code>set agc.reset.interval 4</code> works well to cure deafness.</p> <p>The reset is skipped while a packet is pending, being received, or being transmitted. When safe, <code>RadioLibWrapper::resetAGC()</code> warm-sleeps the radio, returns the wrapper to idle so receive mode is re-armed, reapplies the cached RX boost setting, and starts a fresh noise-floor calibration.</p>"},{"location":"faq/#371-q-can-firmware-recover-an-external-radio-whose-busy-pin-is-stuck-high","title":"3.7.1. Q: Can firmware recover an external radio whose BUSY pin is stuck high?","text":"<p>A: Current firmware first attempts a non-destructive RX/AGC re-arm and then uses a physical radio reset when the board exposes one. A normal RadioLib reinitialization is not reported as a hard reset unless firmware can actually pulse NRST or cycle the radio's power rail.</p> <p>Most supported external-radio boards expose NRST directly. RAK3401 pulses its dedicated NRST while leaving the shared peripheral rail and SPI controller intact, and LilyGo T-Beam 1W can cycle the radio regulator. The generic Tenstar C3 target describes a user-wired radio and has no reset connection by default. For unattended recovery on that target, wire NRST to a free GPIO and override <code>P_LORA_RESET</code> with that GPIO in the build configuration.</p> <p>The SenseCAP T1000-E LR1110 path was hardware-qualified with 50 successful radio-only resets: 25 in continuous receive and 25 with RX power saving active. The saved radio tuple, TX power, RX gain, and RX power-saving configuration were restored after every reset, bidirectional LoRa status traffic still passed, and the nRF52840 uptime remained continuous.</p> <p>An integrated STM32WL radio has no independently resettable RF peripheral, so it intentionally remains on the bounded soft-recovery path. If its radio core cannot recover, resetting only the radio is electrically impossible; the MCU must be restarted.</p>"},{"location":"faq/#372-q-does-firmware-automatically-update-lr1110-transceiver-firmware","title":"3.7.2. Q: Does firmware automatically update LR1110 transceiver firmware?","text":"<p>A: No. A transceiver update erases and rewrites the LR1110 itself, so it is not performed as a side effect of installing ordinary device firmware. Use the hardware vendor's physical-access maintenance procedure and verify the exact LR1110 and bootloader versions before changing them.</p> <p>Full remediation of Semtech SEM-PSA-2026-001 requires LR1110 BL2 0x1001 as well as the applicable transceiver firmware. It is a separate two-stage maintenance procedure and is not performed automatically by MeshCore.</p>"},{"location":"faq/#373-q-how-does-firmware-handle-lr2021-lowhigh-band-changes","title":"3.7.3. Q: How does firmware handle LR2021 low/high-band changes?","text":"<p>A: Firmware first selects the board's matching RF path, retunes the radio, and then reapplies output power so the LR2021 selects the correct low- or high-frequency PA. It also uses the matching RF-switch mode when RX or TX is launched. LR2021 high-band output power is limited to 12 dBm; a lower board-specific limit still takes precedence.</p> <p>On Meshnology W12, the two external FEM supplies are mutually exclusive: GPIO4 powers the sub-GHz GC1109 path and GPIO3 powers the 2.4 GHz RFX2402E path. Both supplies are disabled before the selected one is enabled. Temporary radio settings preserve the saved TX power and safely clamp only the active band; returning to the saved settings restores its applicable power. A permanent frequency change clamps the saved TX power to the new band's limit.</p> <p>The external SX1262, SX1268, LLCC68, LR1110, and LR2021 drivers also bound the post-SetTx BUSY wait. A failed PA ramp therefore returns an error and can enter the physical-reset recovery path instead of hanging the node indefinitely.</p>"},{"location":"faq/#38-q-how-do-i-make-my-repeater-an-observer-on-the-mesh","title":"3.8. Q: How do I make my repeater an observer on the mesh?","text":"<p>A: The observer instruction is available here: https://analyzer.letsmesh.net/observer/onboard</p>"},{"location":"faq/#39-q-what-is-multibyte-support-what-do-1-byte-2-byte-3-byte-adverts-and-messages-mean","title":"3.9. Q: What is multibyte support? What do 1-byte, 2-byte, 3-byte adverts and messages mean?","text":"<p>A: The original MeshCore protocol design uses the first byte of a repeater's public key to denote the repeater in a path. And with 1 byte for each repeater in the path, MeshCore packets can travel as many as 64 hops.</p> <p>However, with 1 byte, there are only 254 unique IDs (exclude 00 and FF which are reserved). Many meshes group have multiple repeaters with the same first byte in their public keys. Packets continue to pass through repeaters and the mesh is not harmed in any way. It does make it harder for tools to analyze paths with duplicated repeater IDs.</p> <p>Firmware version 1.14 and newer introduces the ability for repeaters to advert with 1-, 2-, or 3-byte adverts. Companions can also send out channel and direct messages with 1-, 2-, or 3-byte path. Adverts and messages sent in 1-byte path is compatible with repeater firmware older or newer than 1.14. They will travel up to 64 hops. 2-byte adverts and messages will travel up to 32 hops. 3-byte adverts and messages will travel up to 21 hops.</p>"},{"location":"faq/#391-q-what-path-hash-sizes-will-my-repeater-forward","title":"3.9.1. Q: What path hash sizes will my repeater forward?","text":"<p>Repeaters running firmware 1.14+ repeat packets sent with 1-, 2-, or 3-byte path hash. Repeaters on firmware older than 1.14 only repeat 1-byte path hash packets and silently drop 2- and 3-byte packets.</p>"},{"location":"faq/#392-q-what-determines-a-packets-path-hash-size","title":"3.9.2. Q: What determines a packet's path hash size?","text":"<p>The original packet sender determines the path hash size. The most common original sender is a companion app. The other common original sender is a repeater, when it broadcasts its advert.</p>"},{"location":"faq/#393-q-how-do-i-change-my-companions-path-hash-size","title":"3.9.3. Q: How do I change my companion's path hash size?","text":"<p>As of firmware version 1.14 and MeshCore app version 1.41.0, in the MeshCore app, you can set your companion's message path hash size in <code>Settings (gear icon)</code>, <code>Experimental Settings</code>.</p> <p>Until your regional mesh has the vast majority of the repeaters updated to 1.14+ firmware, it is recommended to keep your companion at the default 1-byte because pre-1.14 repeaters will silently drop messages with larger path hashes.</p>"},{"location":"faq/#394-q-what-does-the-cli-command-pathhashmode-do-on-a-repeater","title":"3.9.4. Q: What does the CLI command <code>path.hash.mode</code> do on a repeater?","text":"<p>This CLI command <code>path.hash.mode</code> only controls the path hash size used in a repeater's own advert broadcasts. It does NOT affect which packets the repeater forwards. A repeater with firmware 1.14+ always forward 1-, 2-, and 3-byte packets regardless of this setting.</p> <p>Usage: <code>set path.hash.mode {0|1|2}</code>:</p> <pre><code>+----------------+-----------------------+\n| path.hash.mode | Advert path hash size |\n+----------------+-----------------------+\n| 0              | 1 byte (default)      |\n+----------------+-----------------------+\n| 1              | 2 bytes               |\n+----------------+-----------------------+\n| 2              | 3 bytes               |\n+----------------+-----------------------+\n</code></pre> <p>It is safe to set your 1.14+ repeaters to mode 1 or 2.</p> <p></p>"},{"location":"faq/#395-q-why-use-2-or-3-byte-path-hash-for-adverts","title":"3.9.5. Q: Why use 2- or 3-byte path hash for adverts?","text":"<p>A longer path hash helps tools like the LetsMesh.net Analyzer and MeshMapper disambiguate repeaters more reliably. With only 1 byte, the chance of different repeaters having the same first byte in their public key is high, making it harder to tell them apart in mesh network analysis. Since this only affects adverts, there's no downside. 2- and 3-byte adverts don't travel as far as 1-byte adverts, but it is not important for MeshCore nodes to hear a repeater's advert that is 21 or 32 hops away.</p>"},{"location":"faq/#396-q-when-can-we-move-away-from-1-byte-path-hash-for-channel-and-direct-messages","title":"3.9.6. Q: When can we move away from 1-byte path hash for channel and direct messages?","text":"<p>You should move to send 2-byte or 3-byte channel and direct messages when the vast majority of the repeaters in your regional mesh are updated to firmware version 1.14 or newer. Setting your repeater's <code>path.hash.mode</code> to 1 (for 2-byte path hash) or 2 (for 3-byte path hash) now helps the community gauge to how many repeaters have updated to 1.14+. Please work with your MeshCore community together to decide when to switch to 2-byte path or 3-byte path for channel and direct messages.</p>"},{"location":"faq/#4-t-deck-related","title":"4. T-Deck Related","text":""},{"location":"faq/#41-q-is-there-a-user-guide-for-t-deck-t-pager-t-watch-or-t-display-pro","title":"4.1. Q: Is there a user guide for T-Deck, T-Pager, T-Watch, or T-Display Pro?","text":"<p>A: Yes, it is available on https://buymeacoffee.com/ripplebiz/ultra-v7-7-guide-meshcore-users</p>"},{"location":"faq/#42-q-what-are-the-steps-to-get-a-t-deck-into-dfu-device-firmware-update-mode","title":"4.2. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode?","text":"<p>A:</p> <ol> <li>Device off</li> <li>Connect USB cable to device</li> <li>Hold down trackball (keep holding)</li> <li>Turn on device</li> <li>Hear USB connection sound</li> <li>Release trackball</li> <li>T-Deck in DFU mode now</li> <li>At this point you can begin flashing using https://flasher.meshcore.io</li> </ol>"},{"location":"faq/#43-q-why-is-my-t-deck-plus-not-getting-any-satellite-lock","title":"4.3. Q: Why is my T-Deck Plus not getting any satellite lock?","text":"<p>A: For T-Deck Plus, the GPS baud rate should be set to 38400. Also, some T-Deck Plus devices were found to have the GPS module installed upside down, with the GPS antenna facing down instead of up. If your T-Deck Plus still doesn't get any satellite lock after setting the baud rate to 38400, you might need to open the device to check the GPS orientation.</p> <p>GPS on T-Deck is always enabled. You can skip the \"GPS clock sync\" and the T-Deck will continue to try to get a GPS lock. You can go to the <code>GPS Info</code> screen; you should see the <code>Sentences:</code> counter increasing if the baud rate is correct.</p> <p>Source</p>"},{"location":"faq/#44-q-why-is-my-og-non-plus-t-deck-not-getting-any-satellite-lock","title":"4.4. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock?","text":"<p>A: The OG (non-Plus) T-Deck doesn't come with a GPS. If you added a GPS to your OG T-Deck, please refer to the manual of your GPS to see what baud rate it requires. Alternatively, you can try to set the baud rate from 9600, 19200, etc., and up to 115200 to see which one works.</p>"},{"location":"faq/#45-q-what-size-of-sd-card-does-the-t-deck-support","title":"4.5. Q: What size of SD card does the T-Deck support?","text":"<p>A: Users have had no issues using 16GB or 32GB SD cards. Format the SD card to FAT32.</p>"},{"location":"faq/#46-q-what-is-the-public-key-for-the-default-public-channel","title":"4.6. Q: What is the public key for the default public channel?","text":"<p>A: T-Deck uses the same key the smartphone apps use but in base64 <code>izOH6cXN6mrJ5e26oRXNcg==</code></p> <p>There is no <code>=</code> key on the T-Deck's hardware keyboard. You can use the on-screen software keyboard to enter <code>=</code>. Tap the text box to enable the on-screen software keyboard. The third character is the capital letter <code>O</code> (Oh), not zero <code>0</code></p> <p>The smartphone app key is in hex: <code>8b3387e9c5cdea6ac9e5edbaa115cd72</code></p> <p>Source</p>"},{"location":"faq/#47-q-how-do-i-get-maps-on-t-deck","title":"4.7. Q: How do I get maps on T-Deck?","text":"<p>A: You need map tiles. You can get pre-downloaded map tiles here (a good way to support development):</p> <ul> <li>https://buymeacoffee.com/ripplebiz/e/342543 (Europe)</li> <li>https://buymeacoffee.com/ripplebiz/e/342542 (US)</li> </ul> <p>Another way to download map tiles is to use this Python script to get the tiles in the areas you want: https://github.com/fistulareffigy/MTD-Script</p> <p>There is also a modified script that adds additional error handling and parallel downloads: https://github.com/TheBestJohn/MTD-Script</p>"},{"location":"faq/#48-q-where-do-the-map-tiles-go","title":"4.8. Q: Where do the map tiles go?","text":"<p>Once you have the tiles downloaded, copy the <code>\\tiles</code> folder to the root of your T-Deck's SD card.</p>"},{"location":"faq/#49-q-how-to-unlock-deeper-map-zoom-and-server-management-features-on-t-deck","title":"4.9. Q: How to unlock deeper map zoom and server management features on T-Deck?","text":"<p>A: You can download, install, and use the T-Deck firmware for free, but it has some features (map zoom, server administration) that are enabled if you purchase an unlock code for \\$10 per T-Deck device. Unlock page: https://buymeacoffee.com/ripplebiz/e/249834</p>"},{"location":"faq/#410-q-how-to-decipher-the-diagnostics-screen-on-t-deck","title":"4.10. Q: How to decipher the diagnostics screen on T-Deck?","text":"<p>A: Space is tight on T-Deck's screen, so the information is a bit cryptic. The format is : <code>{hops} l:{packet-length}({payload-len}) t:{packet-type} snr:{n} rssi:{n}</code></p> <p>See here for packet-type: https://github.com/meshcore-dev/MeshCore/blob/main/src/Packet.h#L19</p> Value Payload <code>0x00</code> Request <code>0x01</code> Response <code>0x02</code> Plain text message <code>0x03</code> Acknowledgment <code>0x04</code> Node advertisement <code>0x05</code> Group text <code>0x06</code> Group datagram <code>0x07</code> Anonymous request <code>0x08</code> Returned path <code>0x09</code> Trace <code>0x0A</code> Multipart <code>0x0B</code> Control/discovery data <code>0x0C</code> OTA-over-LoRa data <code>0x0D</code>-<code>0x0E</code> Reserved <code>0x0F</code> Raw custom data <p>See Packet Format and Payload Format for the maintained descriptions.</p> <p>Source</p>"},{"location":"faq/#411-q-the-t-deck-sound-is-too-loud","title":"4.11. Q: The T-Deck sound is too loud?","text":""},{"location":"faq/#412-q-can-you-customize-the-sound","title":"4.12. Q: Can you customize the sound?","text":"<p>A: You can customize the sounds on the T-Deck, by placing <code>.mp3</code> files onto the <code>root</code> dir of the SD card. The files are:</p> <ul> <li><code>startup.mp3</code></li> <li><code>error.mp3</code></li> <li><code>alert.mp3</code></li> <li><code>new-advert.mp3</code></li> <li><code>existing-advert.mp3</code></li> </ul>"},{"location":"faq/#413-q-what-is-the-import-from-clipboard-feature-on-the-t-deck-and-is-there-a-way-to-manually-add-nodes-without-having-to-receive-adverts","title":"4.13. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts?","text":"<p>A: 'Import from Clipboard' is for importing a contact via a file named 'clipboard.txt' on the SD card. The opposite, is in the Identity screen, the 'Card to Clipboard' menu, which writes to 'clipboard.txt' so you can share yourself (call these 'biz cards', that start with \"meshcore://...\")</p>"},{"location":"faq/#414-q-how-to-capture-a-screenshot-on-t-deck","title":"4.14. Q: How to capture a screenshot on T-Deck?","text":"<p>A: To capture a screenshot on a T-Deck, long press the top-left corner of the screen. The screenshot is saved to the microSD card, if one is inserted into the device.</p>"},{"location":"faq/#5-general","title":"5. General","text":""},{"location":"faq/#51-q-what-are-bw-sf-and-cr","title":"5.1. Q: What are BW, SF, and CR?","text":"<p>A:</p> <p>BW is bandwidth - width of frequency spectrum that is used for transmission</p> <p>SF is spreading factor - how much should the communication spread in time</p> <p>CR is coding rate - from: https://www.thethingsnetwork.org/docs/lorawan/fec-and-code-rate</p> <p>TL;DR: default CR to 5 for good stable links. If it is not a solid link and is intermittent, change CR to 7 or 8.</p> <p>Forward Error Correction is a process of adding redundant bits to the data to be transmitted. During the transmission, data may get corrupted by interference (changes from 0 to 1 / 1 to 0). These error correction bits are used at the receivers for restoring corrupted bits.</p> <p>The Code Rate of a forward error correction expresses the proportion of bits in a data stream that actually carry useful information.</p> <p>There are 4 code rates used in LoRaWAN:</p> <p>4/5 4/6 5/7 4/8</p> <p>For example, if the code rate is 5/7, for every 5 bits of useful information, the coder generates a total of 7 bits of data, of which 2 bits are redundant.</p> <p>Making the bandwidth 2x wider (from BW125 to BW250) allows you to send 2x more bytes in the same time. Making the spreading factor 1 step lower (from SF10 to SF9) allows you to send 2x more bytes in the same time.</p> <p>Lowering the spreading factor makes it more difficult for the gateway to receive a transmission, as it will be more sensitive to noise. You could compare this to two people talking in a noisy place (a bar for example). If you're far from each other, you have to talk slow (SF10), but if you're close, you can talk faster (SF7)</p> <p>So, it's a balancing act between speed of the transmission and resistance to noise. The Things Network is mainly focused on LoRaWAN, but the LoRa low-level stuff still checks out for any LoRa project</p>"},{"location":"faq/#52-q-do-meshcore-clients-repeat","title":"5.2. Q: Do MeshCore clients repeat?","text":"<p>A: Companion clients do not repeat by default. Supported builds can opt into bounded client repeating on permitted frequencies, and the emergency-channel path has a bounded delayed relay behavior. Dedicated repeaters remain the normal and recommended way to extend network coverage. Room servers can repeat when explicitly configured, but separating the roles is generally preferable.</p>"},{"location":"faq/#53-q-what-happens-when-a-node-learns-a-route-via-a-mobile-repeater-and-that-repeater-is-gone","title":"5.3. Q: What happens when a node learns a route via a mobile repeater, and that repeater is gone?","text":"<p>A: If you used to reach a node through a repeater and the repeater is no longer reachable, the client will send the message using the existing (but now broken) known path, the message will fail after 3 retries, and the app will reset the path and send the message as flood on the last retry by default. This can be turned off in settings. If the destination is reachable directly or through another repeater, the new path will be used going forward. Or you can set the path manually if you know a specific repeater to use to reach that destination.</p> <p>In the case if users are moving around frequently, and the paths are breaking, they just see the phone client retries and revert to flood to attempt to re-establish a path.</p>"},{"location":"faq/#54-q-how-does-a-node-discover-a-path-to-its-destination-and-then-use-it-to-send-messages-in-the-future-instead-of-flooding-every-message-it-sends-like-meshtastic","title":"5.4. Q: How does a node discover a path to its destination and then use it to send messages in the future, instead of flooding every message it sends like Meshtastic?","text":"<p>Routes are stored in sender's contact list. When you send a message the first time, the message first gets to your destination by flood routing. When your destination node gets the message, it will send back a delivery report to the sender with all repeaters that the original message went through. This delivery report is flood-routed back to you the sender and is a basis for future direct path. When you send the next message, the path will get embedded into the packet and be evaluated by repeaters. If the hop and address of the repeater matches, it will retransmit the message, otherwise it will not retransmit, hence minimizing utilization.</p> <p>Source</p>"},{"location":"faq/#55-q-do-public-channels-always-flood-do-private-channels-always-flood","title":"5.5. Q: Do public channels always flood? Do private channels always flood?","text":"<p>A: Yes, group channels are A to B, so there is no defined path. They have to flood. Repeaters can however deny flood traffic up to some hop limit, with the <code>set flood.max</code> CLI command. Administrators of repeaters get to set the rules of their repeaters.</p> <p>Source</p>"},{"location":"faq/#56-q-what-is-the-public-key-for-the-default-public-channel","title":"5.6. Q: What is the public key for the default public channel?","text":"<p>A: The smartphone app key is in hex:</p> <p><code>8b3387e9c5cdea6ac9e5edbaa115cd72</code></p> <p>T-Deck uses the same key but in base64:</p> <p><code>izOH6cXN6mrJ5e26oRXNcg==</code></p> <p>The third character is the capital letter <code>O</code>, not zero <code>0</code>.</p> <p>Source</p>"},{"location":"faq/#57-q-is-meshcore-open-source","title":"5.7. Q: Is MeshCore open source?","text":"<p>A: Most of the firmware is freely available. Everything is open source except the T-Deck firmware and Liam's native mobile apps.</p> <p>Firmware repo: https://github.com/meshcore-dev/MeshCore</p>"},{"location":"faq/#58-q-how-can-i-support-meshcore","title":"5.8. Q: How can I support MeshCore?","text":"<p>A: Provide your honest feedback on GitHub and on MeshCore Discord server. Spread the word of MeshCore to your friends and communities; help them get started with MeshCore. Support Scott's MeshCore development at https://buymeacoffee.com/ripplebiz.</p> <p>Support Liam Cottle's smartphone client development by unlocking the server administration wait gate with in-app purchase</p> <p>Support Rastislav Vysoky (recrof)'s flasher website and the map website development through PayPal or Revolut</p>"},{"location":"faq/#59-q-how-do-i-build-meshcore-firmware-from-source","title":"5.9. Q: How do I build MeshCore firmware from source?","text":"<p>A: See instructions here: https://discord.com/channels/826570251612323860/1330643963501351004/1341826372120608769</p> <p>Build instructions for MeshCore:</p> <p>For Windows, first install WSL and Python+pip via: https://plainenglish.io/python/setting-up-python-on-windows-subsystem-for-linux-wsl-26510f1b2d80</p> <p>(Linux, Windows+WSL) In the terminal/shell:</p> <pre><code>sudo apt update\nsudo apt install libpython3-dev\nsudo apt install python3-venv\n</code></pre> <p>Mac: python3 should be already installed.</p> <p>Then it should be the same for all platforms:</p> <pre><code>python3 -m venv meshcore-venv\ncd meshcore-venv &amp;&amp; source bin/activate\npip install -U platformio\ngit clone https://github.com/meshcore-dev/MeshCore.git\ncd MeshCore\n</code></pre> <p>Choose an exact environment listed by <code>pio project config</code> or in the target board's <code>variants/*/platformio.ini</code>. For example:</p> <pre><code>pio run -e RAK_4631_repeater\n</code></pre> <p>The output is under <code>.pio/build/RAK_4631_repeater/</code>. Set the radio parameters to your current regional preset after flashing; if changing build defaults, keep that local change out of commits unless it is intended for every user.</p>"},{"location":"faq/#510-q-are-there-other-meshcore-related-open-source-projects","title":"5.10. Q: Are there other MeshCore related open source projects?","text":"<p>A: Liam Cottle's MeshCore web client and MeshCore JavaScript library are open source under MIT license.</p> <p>Web client: https://github.com/liamcottle/meshcore-web JavaScript: https://github.com/meshcore-dev/meshcore.js</p>"},{"location":"faq/#511-q-does-meshcore-support-atak","title":"5.11. Q: Does MeshCore support ATAK?","text":"<p>A: This repository does not ship or document an official ATAK integration. An external integration must account for LoRa airtime, moving endpoints, stale direct paths, and the collision cost of frequent flood fallback. Optional, bounded Companion repeating does not turn every mobile client into a dedicated repeater and does not remove those capacity constraints. Check current community projects before designing a deployment.</p> <p>Source</p>"},{"location":"faq/#512-q-how-do-i-add-a-node-to-the-meshcore-map","title":"5.12. Q: How do I add a node to the MeshCore Map?","text":"<p>A:</p> <p>To add a BLE Companion radio, connect to the BLE Companion radio from the MeshCore smartphone app. In the app, tap the <code>3 dot</code> menu icon at the top right corner, then tap <code>Internet Map</code>. Tap the <code>3 dot</code> menu icon again and choose <code>Add me to the Map</code></p> <p>To add a Repeater or Room Server to the map, go to the Contact List, tap the <code>3 dot</code> next to the Repeater or Room Server you want to add to the Internet Map, tap <code>Share</code>, then tap <code>Upload to Internet Map</code>.</p> <p>You can use the same companion (same public key) that you used to add your repeaters or room servers to remove them from the Internet Map.</p>"},{"location":"faq/#513-q-can-i-use-a-raspberry-pi-to-update-a-meshcore-radio","title":"5.13. Q: Can I use a Raspberry Pi to update a MeshCore radio?","text":"<p>A: Yes. Below are the instructions to flash firmware onto a supported LoRa device using a Raspberry Pi over USB serial.</p> <p>Instructions for nRF devices like RAK, T1000-E, T114 are immediately after the ESP instructions</p> <p>For ESP-based devices (e.g. Heltec V3) you need:</p> <ol> <li>Download the firmware file from https://flasher.meshcore.io.<ul> <li>Select the exact board and role. Artifact names and release URLs include a   changing version and commit, so copy the current download URL instead of   using an example URL from a guide.</li> <li>A non-merged application image is for an already compatible bootloader   and partition table. A merged image also contains low-level flash data.   Back up settings before either operation; do not assume a merged flash   preserves configuration, pairing data, or a previous partition layout.</li> <li>To download a copied URL from the shell, use   <code>curl -L '&lt;copied-url&gt;' -o &lt;firmware&gt;.bin</code>.</li> </ul> </li> <li>Confirm the <code>ttyXXXX</code> device path on your Raspberry Pi.<ul> <li>Run <code>ls /dev/ttyACM* /dev/ttyUSB* 2&gt;/dev/null</code> before and after connecting   the board. ESP devices can appear under either name.</li> </ul> </li> <li>Install esptool in a virtual environment.<ul> <li><code>python3 -m venv .venv &amp;&amp; . .venv/bin/activate</code></li> <li><code>python -m pip install --upgrade esptool</code></li> </ul> </li> <li>Flash the firmware.<ul> <li>For non-merged bin:<ul> <li><code>python -m esptool --port /dev/ttyUSB0 --chip auto write-flash 0x10000 &lt;non-merged-firmware&gt;.bin</code></li> </ul> </li> <li>For merged bin:<ul> <li><code>python -m esptool --port /dev/ttyUSB0 --chip auto write-flash 0x00000 &lt;merged-firmware&gt;.bin</code></li> </ul> </li> </ul> </li> </ol> <p>Instructions for nRF devices:</p> <p>For nRF devices (e.g. RAK, Heltec T114) you need the following:</p> <ol> <li>Download the firmware file from https://flasher.meshcore.io.<ul> <li>Select the exact board and role, and download its current ZIP package.   Do not rename a package from another board or reuse a static versioned URL.</li> </ul> </li> <li>Confirm the <code>ttyXXXX</code> device path on your Raspberry Pi.<ul> <li>Run <code>ls /dev/ttyACM* /dev/ttyUSB* 2&gt;/dev/null</code>; nRF bootloaders commonly   appear as <code>/dev/ttyACM0</code>, but the number can change.</li> </ul> </li> <li>In a virtual environment, install adafruit-nrfutil:<ul> <li><code>python3 -m venv .venv &amp;&amp; . .venv/bin/activate</code></li> <li><code>python -m pip install --upgrade adafruit-nrfutil</code></li> </ul> </li> <li>Flash the nRF device.<ul> <li><code>adafruit-nrfutil --verbose dfu serial --package &lt;firmware-package&gt;.zip -p /dev/ttyACM0 -b 115200 --singlebank --touch 1200</code></li> </ul> </li> </ol> <p>To manage a repeater or room server connected to a Pi over USB serial using shell commands, you need to install <code>picocom</code>. To install <code>picocom</code>, run the following command:</p> <ul> <li><code>sudo apt install picocom</code></li> </ul> <p>To start managing your USB serial-connected device using picocom, use the following command:</p> <ul> <li><code>picocom -b 115200 /dev/ttyUSB0 --imap lfcrlf</code></li> </ul> <p>From here, reference repeater and room server command line commands in the MeshCore docs here:</p> <ul> <li>https://docs.meshcore.io/cli_commands</li> </ul>"},{"location":"faq/#514-q-are-there-projects-built-around-meshcore","title":"5.14. Q: Are there projects built around MeshCore?","text":"<p>A: Yes, there are many. MeshCore's protocol is open source using the MIT license. The MIT license and the open source protocol makes it very easy for the MeshCore community to build new firmware for radios, applications on mobile devices, map tools, and analysis tools, and integration with other projects like Home Assistant.</p> <p>As new MeshCore community projects become available on a weekly basis, we have stopped tracking them here in this FAQ. samuk maintains a very exhaustive list of MeshCore community project at https://github.com/samuk/awesome-meshcore/blob/main/README.md. samuk accepts PRs and merges them regularly.</p>"},{"location":"faq/#515-q-are-there-client-applications-for-windows-or-mac","title":"5.15. Q: Are there client applications for Windows or Mac?","text":"<p>A: Yes, the same iOS and Android client is also available for Windows and Mac. You can find them together with the Android APK here: https://files.liamcottle.net/MeshCore</p> <p>Both the Windows and Mac versions of the client app are fully unlocked and are free to use.</p>"},{"location":"faq/#516-q-are-there-any-resources-that-compare-meshcore-to-other-lora-systems","title":"5.16. Q: Are there any resources that compare MeshCore to other LoRa systems?","text":"<p>A: Here is a list of MeshCore comparison resources:</p> <ul> <li>The Comms Channel on YouTube: https://www.youtube.com/watch?v=guDoKGs02Us</li> <li>MeshCore Advantages by MCarper: https://github.com/mikecarper/meshfirmware/blob/main/MeshCoreAdvantages.md</li> <li>MeshCore vs Meshtastic by austinmesh.org: https://www.austinmesh.org/about/meshcore-vs-meshtastic/</li> </ul>"},{"location":"faq/#6-troubleshooting","title":"6. Troubleshooting","text":""},{"location":"faq/#61-q-my-client-says-another-client-or-a-repeater-or-a-room-server-was-last-seen-many-many-days-ago","title":"6.1. Q: My client says another client or a repeater or a room server was last seen many, many days ago.","text":""},{"location":"faq/#62-q-a-repeater-or-a-client-or-a-room-server-i-expect-to-see-on-my-discover-list-on-t-deck-or-contact-list-on-a-smart-device-client-are-not-listed","title":"6.2. Q: A repeater or a client or a room server I expect to see on my discover list (on T-Deck) or contact list (on a smart device client) are not listed.","text":"<p>A:</p> <ul> <li>If your client is a T-Deck, it may not have its time set (no GPS installed, no GPS lock, or wrong GPS baud rate).</li> <li>If you are using the Android or iOS client, the other client, repeater, or room server may have the wrong time.</li> </ul> <p>You can get the epoch time on https://www.epochconverter.com and use it to set your T-Deck clock. For a repeater and room server, the admin can use a T-Deck to remotely set their clock (clock sync), or use the <code>time</code> command in the USB serial console with the server device connected.</p>"},{"location":"faq/#63-q-how-to-connect-to-a-repeater-via-ble-bluetooth","title":"6.3. Q: How to connect to a repeater via BLE (Bluetooth)?","text":"<p>A: You can't connect to a device running repeater firmware via Bluetooth. You can connect to devices running the BLE companion firmware via Bluetooth using the Android app.</p>"},{"location":"faq/#64-q-my-companion-isnt-showing-up-over-bluetooth","title":"6.4. Q: My companion isn't showing up over Bluetooth?","text":"<p>A: Make sure that you flashed the Bluetooth companion firmware and not the USB-only companion firmware.</p>"},{"location":"faq/#65-q-i-cant-connect-via-bluetooth-what-is-the-bluetooth-pairing-code","title":"6.5. Q: I can't connect via Bluetooth, what is the Bluetooth pairing code?","text":"<p>A: The default Bluetooth pairing code is <code>123456</code> on builds without a physical display. Display-equipped Companion builds generate a six-digit PIN at boot and show it when a client requests pairing. The display stays awake on the PIN page until Bluetooth connects or the two-minute pairing window expires.</p>"},{"location":"faq/#66-q-my-heltec-v3-keeps-disconnecting-from-my-smartphone-it-cant-hold-a-solid-bluetooth-connection","title":"6.6. Q: My Heltec V3 keeps disconnecting from my smartphone. It can't hold a solid Bluetooth connection.","text":"<p>A: Heltec V3 has a very small coil antenna on its PCB for Wi-Fi and Bluetooth connectivity. It has a very short range, only a few feet. It is possible to remove the coil antenna and replace it with a 31mm wire. The BT range is much improved with the modification.</p>"},{"location":"faq/#67-q-my-rakt1000-exiao_nrf52-device-seems-to-be-corrupted-how-do-i-wipe-it-clean-to-start-fresh","title":"6.7. Q: My RAK/T1000-E/xiao_nRF52/... device seems to be corrupted, how do I wipe it clean to start fresh?","text":"<p>A: If you're able to connect to the device from your MeshCore app 1. Navigate to Gear icon(Settings) on the upper right corner 2. Click on <code>Export Settings</code> button, choose <code>Select All</code> and Confirm. This will save your Node configuration 3. Now choose <code>Factory Reset</code> option 4. Confirm that you want to reset your device 5. Go to Bluetooth System settings and remove pairing of the device, so you can connect again 6. Connect your device in the app and enter the PIN 7. Navigate to Gear icon(Settings) on the upper right corner 8. Click on <code>Import Settings</code> and choose the file from 2., click on <code>Select All</code> and Confirm 9. Find <code>Reboot</code> button on of the Settings list</p> <p>B: You're not able to connect to the App 1. Connect USB cable to your device 2. Go to https://flasher.meshcore.io 3. Search for your device in the list 4. Choose <code>Companion Bluetooth</code> 5. Press <code>Enter DFU mode</code> button, choose your USB device 6. Press <code>Erase Flash</code> button, choose the device again and wait until it completes 7. Press <code>Flash!</code> button and choose the USB device last time 8. The device is erased and newest firmware is installed 9. You might need to remove the pairing in Bluetooth System Settings in order to re-pair the app again.</p> <p>An erase application or ordinary application ZIP/UF2 does not repair a damaged or partially overwritten SoftDevice. This can happen after flashing an nRF52 image for a different board or SoftDevice layout. A characteristic failure is that the application can boot and read its filesystem, but reboots or hangs when it writes or formats internal flash. Repeating <code>Erase Flash</code> is not a recovery for that condition.</p> <p>Recover it with a combined bootloader + SoftDevice package for the exact board (including XIAO Sense versus non-Sense), installed through serial/BLE DFU or SWD. With <code>adafruit-nrfutil</code>, the serial form is:</p> <pre><code>adafruit-nrfutil dfu serial -p &lt;port&gt; \\\n  -pkg &lt;exact-board-bootloader-with-softdevice&gt;.zip -sb -t 1200\n</code></pre> <p>Then install the exact-board MeshCore application. Do not use an application- only UF2, filesystem formatter, or a similarly named package from another nRF52 board as a substitute. See the confirmed XIAO recovery in issue #3284 and obtain the matching package from the OTAFIX releases.</p> <p>Separately, starting in firmware version 1.7.0, there is a CLI Rescue mode. If your device has a user button (e.g. some RAK, T114), you can activate the rescue mode by holding down the user button of the device within 8 seconds of boot. Then you can use the 'Console' on https://flasher.meshcore.io</p>"},{"location":"faq/#68-q-webflasher-fails-on-linux-with-failed-to-open","title":"6.8. Q: WebFlasher fails on Linux with failed to open","text":"<p>A: If the usb port doesn't have the right ownership for this task, the process fails with the following error:</p> <p><code>NetworkError: Failed to execute 'open' on 'SerialPort': Failed to open serial port.</code></p> <p>Allow user access on your USB port:</p> <p><code>sudo setfacl -m u:$USER:rw /dev/ttyUSB0</code></p>"},{"location":"faq/#7-other-questions","title":"7. Other Questions:","text":""},{"location":"faq/#71-q-how-to-update-nrf-rak-t114-seeed-xiao-companion-repeater-and-room-server-firmware-over-the-air-using-the-new-simpler-dfu-app","title":"7.1. Q: How to update nRF (RAK, T114, Seeed XIAO) companion, repeater and room server firmware over the air using the new simpler DFU app?","text":"<p>A: The steps below work on both Android and iOS as nRF has made both apps' user interface the same on both platforms:</p> <ol> <li>Download nRF's DFU app from iOS App Store or Android's Play Store, you can find the app by searching for <code>nrf dfu</code>, the app's full name is <code>nRF Device Firmware Update</code></li> <li>On https://flasher.meshcore.io, download the ZIP version of the firmware for your nRF device (e.g. RAK or Heltec T114 or Seeed Studio's Xiao)</li> <li>From the MeshCore app, log in remotely to the repeater you want to update with admin privileges</li> <li>Go to the Command Line tab, type <code>start ota</code> and hit enter.</li> <li>You should see <code>OK</code> to confirm the repeater device is now in OTA mode</li> <li>Run the DFU app, then tap <code>Settings</code> in the top-right corner</li> <li>Enable <code>Packet receipt notifications</code>, and change <code>Number of Packets</code> to 10 for RAK, 8 for T114. 8 also works for RAK.</li> <li>Select the firmware zip file you downloaded</li> <li>Select the device you want to update. If the device you want to update is not on the list, try enabling <code>OTA</code> on the device again</li> <li>If the device is not found, enable <code>Force Scanning</code> in the DFU app</li> <li>Tap <code>Upload</code> to begin OTA update</li> <li>If it fails, try toggling Bluetooth on your phone. If that doesn't work, try rebooting your phone. If you keep getting failures at the \"Enabling Bootloader\" step, try forgetting the nRF board in your iOS or Android device's Bluetooth settings and re-pair it through the DFU app.</li> <li>Wait for the update to complete. It can take a few minutes.</li> <li>It is strongly recommended that you install and use the OTAFIX bootloader at https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX.</li> <li>A companion must be running a build that exposes <code>start ota</code>; consult the     current flasher release notes rather than relying on a version threshold in     this FAQ.</li> <li>Please see the MeshCore Blog for additional information on OTA firmware flashing:<ul> <li>https://blog.meshcore.io/2026/04/06/otafix-bootloader</li> <li>https://blog.meshcore.io/2026/04/02/nrf-ota-update</li> </ul> </li> </ol>"},{"location":"faq/#711-q-can-i-update-seeed-studio-wio-tracker-l1-pro-using-ota","title":"7.1.1 Q: Can I update Seeed Studio Wio Tracker L1 Pro using OTA?","text":"<p>A:  You can flash this safer bootloader to the Wio Tracker L1 Pro https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX</p> <p>After this bootloader is flashed onto the device, you can trigger an over-the-air update using Bluetooth by holding the button next to the D-Pad and then clicking the reset button. Then follow the same OTA update instructions above. You can skip the <code>start ota</code> instruction and start the update using the DFU app.</p>"},{"location":"faq/#72-q-how-to-update-esp32-based-devices-over-the-air","title":"7.2. Q: How to update ESP32-based devices over the air?","text":"<p>A: For ESP32-based devices (e.g. Heltec V3):</p> <ol> <li>On https://flasher.meshcore.io, download the current non-merged    application image for the exact ESP32 board and role (no <code>merged</code> in the    filename).</li> <li>From the MeshCore app, log in remotely to the repeater you want to update with admin privileges.</li> <li>Go to the Command Line tab, type <code>start ota</code> and hit enter.</li> <li>You should see <code>OK</code> to confirm the repeater device is now in OTA mode.</li> <li>If the ESP32 is not already joined to Wi-Fi, <code>start ota</code> starts an open hotspot named <code>MeshCore-OTA</code> at <code>192.168.4.1</code>. If it is already joined, the command reports and uses its router-assigned address instead.</li> <li>From your phone or computer, connect to the <code>MeshCore-OTA</code> hotspot when one was started.</li> <li>Open the URL reported by <code>start ota</code> and upload the non-merged bin from the flasher. When the device started <code>MeshCore-OTA</code>, the URL is http://192.168.4.1/update.</li> </ol> <p>On an MQTT observer, stop WebConfig before running <code>start ota</code>; both servers use HTTP port 80. Likewise, stop the OTA uploader before running <code>start webconfig</code>.</p>"},{"location":"faq/#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu","title":"7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?","text":"<p>A: Yes, developer <code>che aporeps</code> has an enhanced OTA DFU bootloader for nRF52 based devices. With this bootloader, if it detects that the application firmware is invalid, it falls back to OTA DFU mode so you can attempt to flash again to recover. This bootloader has other changes to make the OTA DFU process more fault tolerant.</p> <p>Refer to https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX for the latest information.</p> <p>Currently, the following boards are supported:</p> <ul> <li>Elecrow ThinkNode M1, M3, and M6</li> <li>Heltec Automation Mesh Node T114 / HT-nRF5262</li> <li>LilyGO T-Echo</li> <li>Minewsemi MX25LE01</li> <li>Nologo ProMicro NRF52840 (aka SuperMini NRF52840)</li> <li>RAK4631</li> <li>RAK WisMesh Tag</li> <li>Seeed Studio SenseCAP Card Tracker T1000-E</li> <li>Seeed Studio SenseCAP Solar Node P1</li> <li>Seeed Studio Wio Tracker L1</li> <li>Seeed Studio XIAO nRF52840 BLE</li> <li>Seeed Studio XIAO nRF52840 BLE SENSE</li> </ul>"},{"location":"faq/#74-q-are-the-meshcore-logo-and-font-available","title":"7.4. Q: Are the MeshCore logo and font available?","text":"<p>A: Yes, it is on the MeshCore GitHub repo here: https://github.com/meshcore-dev/MeshCore/tree/main/logo</p>"},{"location":"faq/#75-q-what-is-the-format-of-a-contact-or-channel-qr-code","title":"7.5. Q: What is the format of a contact or channel QR code?","text":"<p>A:</p> <p>Channel: <code>meshcore://channel/add?name=&lt;name&gt;&amp;secret=&lt;secret&gt;</code></p> <p>Contact: <code>meshcore://contact/add?name=&lt;name&gt;&amp;public_key=&lt;secret&gt;&amp;type=&lt;type&gt;</code></p> <p>Where <code>&amp;type</code> is:</p> <ul> <li><code>chat = 1</code></li> <li><code>repeater = 2</code></li> <li><code>room = 3</code></li> <li><code>sensor = 4</code></li> </ul>"},{"location":"faq/#76-q-how-do-i-connect-to-the-companion-via-wi-fi-eg-using-a-heltec-v3","title":"7.6. Q: How do I connect to the companion via Wi-Fi, e.g. using a Heltec V3?","text":"<p>A: Flash an ESP32 companion Wi-Fi build. Its shared WebUI is enabled by default. If it has no saved Wi-Fi configuration, it starts an open <code>MeshCore-Setup-XXXX</code> access point. Join it and browse to http://192.168.4.1/. The wizard configures WiFi, node identity, and radio settings; MQTT companion builds add an MQTT step and MQTT tab, while non-MQTT companions remove those controls. After saving, the page and device screen show the station IP assigned by your router.</p> <p>If a saved network remains unreachable for two minutes, the setup AP starts as a fallback. If the original network returns, the companion closes that recovery portal and resumes normal LAN operation.</p> <p>The setup AP always uses <code>192.168.4.1</code>; the companion's station IP is assigned by DHCP and can be different. A real <code>WIFI_SSID</code> and <code>WIFI_PWD</code> can still be supplied at compile time as initial defaults, but they are no longer required.</p> <p>On the LAN, the WebUI remains available at the companion's station IP and the companion protocol remains available on TCP port <code>5000</code>. Companion builds do not have an admin CLI password, so this configuration page trusts the local LAN; do not put the companion on an untrusted WiFi network.</p> <p>ESP32 repeater and room-server builds use the same page, but keep it off by default. Run <code>set webui on</code> from the admin CLI, open the reported LAN URL, and sign in with the admin password; <code>get webui</code> reports its current address. Their MQTT observer variants expose the MQTT controls, while ordinary builds do not. The two 4 MB <code>LilyGo_TLora_V2_1_1_6_*_observer_mqtt</code> builds retain CLI-only configuration so their flash can keep two app slots for LoRa OTA.</p>"},{"location":"faq/#77-q-i-have-a-station-g2-or-a-heltec-v4-or-an-ikoka-stick-or-a-radio-with-an-ebyte-e22-900m30s-or-an-ebyte-e22-900m33s-module-what-should-their-transmit-power-be-set-to","title":"7.7. Q: I have a Station G2, or a Heltec V4, or an Ikoka Stick, or a radio with an EByte E22-900M30S or an EByte E22-900M33S module, what should their transmit power be set to?","text":"<p>A: For companion radios, you can set these radios' transmit power in the smartphone app. For repeater and room server radios, you can set their transmit power using the command line command <code>set tx</code>. You can get their current value using command line command <code>get tx</code></p> <p>[WARN] WARNING: Set these values at your own risk. Incorrect power settings can permanently damage your radio hardware.</p> Device / Model Region / Description In-App Setting (dBm) Target Radio Output Notes Station G2 Reference US915 Max Output 19 dBm 36.5 dBm (4.46W) US915 Max at 1dB compression point 16 dBm 35 dBm (3.16W) 1dB compression point EU868  Max at 1dB compression point 15 dBm 34.5 dBm (2.82W) 1dB compression point US915 1W Output 10 dBm 1W Refer to your local government's requirements EU868 1W Output 9 dBm 1W Refer to your local government's requirements Ikoka Stick E22-900M30S 1W Model 19 dBm 1W DO NOT EXCEED (Risk of burn out) data sheet Ikoka Stick E22-900M33S 2W Model 9 dBm 2W DO NOT EXCEED (Risk of burn out) data sheet Refer to your local government's requirements Heltec V4 Standard Output 10 dBm 22 dBm (~0.15W) High Output 22 dBm 28 dBm (~0.5W to 0.6W)"},{"location":"faq/#78-q-how-do-i-use-ethernet-with-a-rak4631","title":"7.8. Q: How do I use Ethernet with a RAK4631?","text":"<p>A: MeshCore supports Ethernet on RAK4631 boards using the RAK13800 WisBlock Ethernet module (based on the W5100S chip).</p> <p>Hardware required: - RAK4631 WisBlock Core - RAK19007 or RAK19018 WisBlock Base Board (with an available IO slot) - RAK13800 WisBlock Ethernet module - Ethernet cable connected to a network with a DHCP server</p> <p>Firmware: Flash one of the Ethernet-enabled firmware variants: - <code>RAK_4631_repeater_ethernet</code> - Repeater with Ethernet CLI access - <code>RAK_4631_room_server_ethernet</code> - Room server with Ethernet CLI access - <code>RAK_4631_companion_radio_ethernet</code> - Companion radio over Ethernet (replaces BLE)</p> <p>Connecting: - The device obtains an IP address via DHCP automatically on boot. - For repeaters and room servers, connect to the device on TCP port 23 using any TCP client (e.g. <code>nc &lt;ip&gt; 23</code> or PuTTY in raw mode). This gives you the same CLI available over serial/USB. - For companion radio firmware, the Ethernet interface replaces BLE as the transport to companion apps. Connect on TCP port 5000 (same as the WiFi companion radio). - Use the <code>eth.status</code> CLI command to check connection status and see the assigned IP address.</p>"},{"location":"filter_tool/","title":"Filter policy playground","text":"<p>Build a forwarding policy, see its readable definition, and simulate how a repeater handles a packet. Rules match received packet facts, then apply actions such as dropping, scoping, rate-limiting, or retrying a flood.</p> <p>Everything runs locally in this browser. Channel keys, packet facts, and policy drafts are not uploaded anywhere.</p> Policy design preview <p>     The phases and core conditions model current FPF7 behavior, including its     forward rows, scope rewrites, and shared blacklist. The readable policy     language, JSON, and Base64 bundle are still a prototype: current firmware     is configured with <code>set flood.*</code> or <code>set fr</code> commands and cannot install a     bundle from this page.   </p>"},{"location":"filter_tool/#build-a-policy","title":"Build a policy","text":"<p>Start with an example or build a rule, then test the draft against packet facts in the simulator below. The examples draw from Flood Filtering and Moderation.</p> Remote login and direct routes <p>       This policy only decides whether a relay retransmits a flood. Direct       packets and local delivery are unaffected. Rules matching the login/admin       family can still reduce multi-hop remote-login reach, so the analyzer       flags them.     </p> Example policies Choose one to load its full rules into the builder and draft. <p>         Read each summary as <code>when</code> all conditions match,         <code>do</code> the actions. A match alone does not stop forwarding.       </p> Payload selectors <code>type=</code> valueMatches <code>grp_data</code>Only the named payload type; see every exact type below <code>any</code>Every payload type <code>class:group</code>GRP_TXT and GRP_DATA <code>class:login</code>REQ, RESPONSE, TXT_MSG, ANON_REQ, and PATH <code>class:other</code>Every remaining payload type that is not group or login Other conditions and actions FieldMeaning <code>hops=</code>Received hop count: <code>all</code>, <code>3+</code>, <code>2-6</code>, or <code>3</code> <code>channel=</code><code>*</code> means no channel condition; a name or key authenticates one group channel; <code>hash:XX</code> is an unauthenticated one-byte fallback <code>rx.scope=</code>Original incoming transport scope <code>path=</code>Path prefix, blacklist, bucket, or loop match <code>tempradio=</code>Temporary-radio state <code>do drop</code>Do not retransmit <code>do scope=</code>Set the outgoing transport scope <code>do rate=</code>Apply a per-minute rate and burst <code>do timing=</code>Select fast, normal, or slow scheduling <p>         There is no <code>class:txt</code>. Use <code>type=grp_txt</code> for         channel text or <code>type=txt_msg</code> for peer text.       </p> Set #BlackHole86 scope on all #rgdata group traffic <code>when type=class:group hops=all channel=#rgdata do scope=#BlackHole86 timing=fast</code> Add #BlackHole86 scope to unscoped #rgdata data <code>when type=grp_data hops=all channel=#rgdata rx.scope=none do scope=#BlackHole86 timing=fast</code> Replace #usa with #BlackHole86 on #rgdata data <code>when type=grp_data hops=all channel=#rgdata rx.scope=scope:usa do scope=#BlackHole86 timing=fast</code> Rate-limit packets whose path starts with 860C <code>when type=any hops=all path=prefix:860C do rate=10/min burst=10</code> Drop selected flood types at their hop limits <code>when type=control hops=1+ do dropwhen type=req hops=3+ do drop; same for type=grp_datawhen type=response hops=9+ do drop; same for type=anon_req and type=path</code> Rate-limit Public messages from \u201cNoisy User\u201d <code>when type=grp_txt hops=all channel=public sender=\"Noisy User\" do rate=5/min burst=5</code> Stop forwarding traffic from blacklisted internet gateways <code>when type=any hops=all path=blacklist do drop</code> Three defaults: OTA, distant #wardriving, and bridge/crossover #wardriving <code>when type=ota hops=all tempradio=inactive do dropwhen type=any channel=#wardriving hops=5+ do dropwhen type=any channel=#wardriving hops=all via=bridge,cross do drop</code> Set #BlackHole86 scope on login and bucket-matched other traffic <code>when type=class:login hops=all do scope=#BlackHole86 timing=fastwhen type=class:other hops=all path=bucket:2 do scope=#BlackHole86 timing=slow</code> <p>Rule builder</p> Reset form <p>The factory example contains all three repeater defaults.         The playground's <code>via=</code> traffic-path matcher corresponds to firmware         <code>mode=radio|bridge|cross|bridge,cross</code>; the advanced Active/Shadow/Disabled         mode is a separate playground setting. See the         firmware mode guide.         This simulator models flood packets; firmware bridge/cross rules also cover direct routes.</p> Common match settings            Payload type or class            Any payload type Class: group text and data Class: login/admin family Class: every other payload REQ RESPONSE TXT_MSG ACK ADVERT GRP_TXT GRP_DATA ANON_REQ PATH TRACE MULTIPART CONTROL OTA Reserved type 13 Reserved type 14 RAW_CUSTOM            Received hops                       Channel (optional)                       Original incoming scope                       Path matcher            No path condition Ordered 1/2/3-byte pbyte prefix Passive blacklist Path bucket 1 Path bucket 2 Path bucket 3 Path bucket 4 Path bucket 5 Path bucket 6 Own-ID loop: strict Own-ID loop: moderate Own-ID loop: minimal            Ordered pbyte prefix                       Decrypted sender (optional)                       Traffic path (firmware mode)            Normal radio forwarding Bridge entry/exit Radio profile crossover Bridge and crossover            Temporary-radio state            Either state Inactive Active Common actions <p>         Choosing a phase-specific action automatically selects a compatible         phase and ACL owner. Open the advanced section to inspect or override         those choices.       </p>            Forwarding verdict            No verdict change Drop / do not retransmit            Region-gate decision            Leave global gate unchanged Require original allowed region Bypass global gate for this packet            Scope rewrite target            Do not rewrite scope Regionless public scope Configured region            Target name                       Token rate per minute (optional)                       Burst tokens                       Rewrite timing            Inherit normal behavior Fast-track rewrite Normal queue timing Slow receive/transmit timing            Queue priority            Inherit High Normal Low            Retry path bucket            No retry action Bucket 1 Bucket 2 Bucket 3 Bucket 4 Bucket 5 Bucket 6            Retry attempts                       Decision tag (optional)            Advanced execution, ownership, and flood route <p>           Direct packets already carry a supplied path and are intentionally           outside this engine. The route condition below only distinguishes           unscoped floods from transport-scoped floods.         </p>              Stable rule ID                           Processing phase              1 - Incoming scope gate 2 - Scope rewrite 3 - Forwarding decision 4 - Decrypted content 5 - Scheduling and retry              Rule owner / capability              ACL 4 - Region/scope manager ACL 5 - Filter manager Administrator Firmware-managed system rule              Priority                           Mode              Active Shadow - observe only Disabled              Rule processing after a match              Continue to later rules Skip later rules in this phase Skip all later policy rules              Flood route              Either flood route Unscoped flood only Transport-scoped flood only Readable policy definition <code></code> <p></p> Add rule to policy Copy definition <p>Policy draft</p> Clear policy            Approximate target budget            Compact STM32 - 2 KB nRF52 - 8 KB Classic ESP32 - 16 KB Roomy ESP32 - 64 KB <p>         Rules match the same immutable packet facts. Ordering is phase, then         descending priority, then authenticated channel, raw hash, or wildcard         specificity, then stable rule ID. Drop decisions are sticky.       </p>          Add a rule or load an example to start exploring.        <p>Immutable packet simulator</p> Reset packet Read a raw MeshCore packet <p>             Paste an on-air packet as hexadecimal. The decoder follows the             MeshCore wire format, displays its             header, route, pbyte path, and clear payload envelope, then loads             only facts actually present on the wire into the simulator.           </p> Runs locally          Raw packet hex         014e912ceebb98918b86772df5dacf1bcba9e4127ffffaa8665596aa3e2903a3b1901fdc53497dfca6b5d7df2d771bea68de Decode and load packet            Packet traffic path            Normal radio forwarding Bridge entry/exit Radio profile crossover          Received route          Unscoped flood Transport-scoped flood          Payload type          REQ RESPONSE TXT_MSG ACK ADVERT GRP_TXT GRP_DATA ANON_REQ PATH TRACE MULTIPART CONTROL OTA Reserved type 13 Reserved type 14 RAW_CUSTOM          Received hops                   Channel                   Received pbyte path                   Original scope status          Unscoped Allowed region Unknown or denied scope          Original scope name                   Resolved region name                   Decrypted sender                   Passive blacklist result          No match Matched          Matching path buckets                   Own-ID loop result          No loop match Strict only Moderate and strict Minimal, moderate, and strict          Temporary radio is active        Run policy simulation <p>Import and explain</p> <p>       Accepts one-line <code>policy set ... when ... do ...</code> definitions,       playground JSON, or a playground Base64 bundle.     </p> Explain input Load into builder <p>Export</p> Readable policy Policy JSON Playground Base64 <p>Proposed human-readable definition. Current firmware does not accept it yet.</p> <p>Structured draft used by this page.</p> <p>Browser-playground interchange only. It is not the final packed firmware codec.</p> Copy visible export Download JSON"},{"location":"filter_tool/#filter-builder-title","title":"Create a policy rule","text":""},{"location":"filter_tool/#filter-policy-title","title":"Rules in execution order","text":""},{"location":"filter_tool/#filter-simulator-title","title":"Explain an evaluation","text":""},{"location":"filter_tool/#filter-import-title","title":"Paste readable policy or a saved draft","text":""},{"location":"filter_tool/#filter-export-title","title":"Move or save this design","text":""},{"location":"filter_tool/#payload-type-reference","title":"Payload type reference","text":"<p>Use an exact <code>type=</code> value when a rule should match only one payload type. The class column shows which broader selector also matches it.</p> <code>type=</code> value Payload Class <code>req</code> Request <code>class:login</code> <code>response</code> Response <code>class:login</code> <code>txt_msg</code> Peer text message <code>class:login</code> <code>ack</code> Acknowledgment <code>class:other</code> <code>advert</code> Node advertisement <code>class:other</code> <code>grp_txt</code> Group-channel text <code>class:group</code> <code>grp_data</code> Group-channel datagram <code>class:group</code> <code>anon_req</code> Anonymous request <code>class:login</code> <code>path</code> Returned path <code>class:login</code> <code>trace</code> Path trace <code>class:other</code> <code>multipart</code> One frame in a multipart sequence <code>class:other</code> <code>control</code> Control or discovery data <code>class:other</code> <code>ota</code> OTA-over-LoRa data <code>class:other</code> <code>13</code> Reserved payload type 13 <code>class:other</code> <code>14</code> Reserved payload type 14 <code>class:other</code> <code>raw_custom</code> Application-defined raw data <code>class:other</code>"},{"location":"filter_tool/#current-fpf7-command-mapping","title":"Current FPF7 command mapping","text":"Firmware command FPF7 role <code>fr</code> / <code>flood.rule</code> / <code>flood.filter</code> Forward-phase match and action rows <code>flood.channel.data</code> Compatibility view over one visible <code>type=grp_data</code> forward drop row <code>flood.channel.scope</code> Scope-rewrite phase rows <code>flood.filter.blacklist</code> One shared unordered path-ID set referenced by <code>path=blacklist</code> rows <p>Generalized repeaters expose 63 forward rows and commit those sections together. The blacklist is useful for refusing to retransmit floods associated with internet gateways dumping bulk traffic, but a path ID is truncated and unauthenticated; it identifies a routing pattern, not a person.</p> <p>The firmware accepts both full and short CLI forms for the same forward row:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nset fr.3 any c=#wardriving m=bc d\n</code></pre> <p>Use <code>get fr.3</code> on the device to obtain a short setter ready to copy. This CLI syntax is separate from the playground's proposed policy/bundle format. See the shorthand reference.</p>"},{"location":"filter_tool/#proposed-evaluation-contract","title":"Proposed evaluation contract","text":"<p>The simulator uses these rules:</p> <ol> <li>Only flood retransmission enters the policy. Direct routing and local packet    delivery remain outside it.</li> <li>Every matcher reads the same immutable receive-time packet facts.</li> <li>Rules run by phase and descending numeric priority. At an equal priority,    authenticated channel matches run before raw one-byte hash matches, which    run before wildcard channel matches; stable rule ID breaks the remaining    tie. An explicitly higher numeric priority overrides channel specificity.</li> <li>A drop decision is sticky and cannot be undone by a later rule.</li> <li>The first matching scope, timing, queue, and retry action in execution order    wins.</li> <li>All matching token-bucket rate constraints remain attached to the decision.</li> <li><code>stop=phase</code> skips later rules in that phase. <code>stop=policy</code> skips later    configurable rules, but never mandatory packet validation or radio safety.</li> <li>Shadow rules report what they would do without changing the decision or    stopping other rules.</li> <li>Expensive facts such as channel-key matching, decryption, and path-table    lookup are resolved once per packet and reused by every matching rule.</li> </ol> <p>The byte-budget display is deliberately approximate until the packed firmware codec exists. It demonstrates why simple mappings should not reserve a maximum- sized structure for every possible condition and action.</p>"},{"location":"firmware_memory_budget/","title":"Firmware memory checks","text":"<p>Every firmware environment runs <code>scripts/check_firmware_ram.py</code> against its linked ELF before producing or uploading an image. <code>build.sh</code>, including option 3, also requires a passing report before collecting release files. Native host tests do not use a microcontroller RAM budget.</p> <p>The check reserves room for enabled runtime allocations as well as static data. A firmware image fitting its board's reported RAM total is insufficient: the display, packet pool, USB, Bluetooth workers and WiFi can allocate after startup. The T096 Full 1.17.1.5 report exposed this distinction.</p>"},{"location":"firmware_memory_budget/#what-is-counted","title":"What is counted","text":"Platform Source of available runtime RAM nRF52 Actual <code>__HeapBase</code> and <code>__HeapLimit</code>; excludes SoftDevice, retained state, ISR stack and the dedicated 64 KiB mOTA arena where present ESP32, S3, C3, C6 Linked ESP-IDF memory-region, capability and reservation tables; only internal, byte-addressable heap counts RP2040/RP2350 <code>__end__</code> to <code>__HeapLimit</code>, according to the selected linker STM32 <code>_end</code> to <code>_estack</code>, minus <code>_Min_Stack_Size</code> <p>ESP32 PSRAM, instruction-only RAM and RTC RAM never increase the internal budget. On chips other than classic ESP32, the late-reclaimed ROM stack region is excluded because its silicon-specific reservations are only known at boot. Classic ESP32 additionally retains its existing 8 KiB static DRAM check.</p> <p>The policy adds allowances for task stacks, radio packet pools, screen objects and pixel buffers, filesystem/sensor allocations, enabled wireless stacks, MQTT connections, OTA scratch and transient allocations. A 160x80 ST7735 framebuffer needs 25,602 bytes; an OLED allowance is 4 KiB. nRF52 Full with that color framebuffer must have at least 72 KiB available before startup allocations. Headless and OLED devices use their own smaller totals. The JSON lists each component and checks the largest available region against the largest planned single allocation.</p> <p>The small-screen message layout retains complete 160-byte messages. Its expanded preview records add 2,816 bytes to the startup allowance and increase the contiguous history allocation budget. The V4 can allocate that history in PSRAM; the guard conservatively reserves internal capacity so that PSRAM availability cannot hide a RAM shortage. A target may replace the generic UI allowance only with <code>MESH_COMPANION_SCREEN_STARTUP_BYTES</code>; a source-side assertion then covers its actual startup screens plus ESP32 allocator overhead.</p> <p>These are engineering allowances for supported configurations, not measured free heap after boot or a guarantee against every future allocation failure. Unknown platforms, unknown display drivers and missing linker metadata fail closed. <code>MESH_MIN_RUNTIME_HEAP</code> can raise a profile's requirement; it cannot lower the calculated requirement. Add an allocation allowance when adding a display, transport or other substantial feature.</p> <p>Wireless Paper Full keeps 350 contacts and 256 offline frames by lending the upper 128 queue slots to its mOTA workspace during a session. An idle WiFi mOTA listener leaves all 256 slots available. More than 128 unread frames refuses the loan; sync messages with an app first. USB/TCP source detach or disconnect returns all 256 slots and releases the ESP32 proof/leaf scratch buffers. The display and simultaneous USB, Bluetooth and WiFi remain enabled.</p>"},{"location":"firmware_memory_budget/#release-evidence-and-regression-tests","title":"Release evidence and regression tests","text":"<p>Full Companions without PSRAM also use 16-entry path and shared-secret caches. The optional NimBLE capacity trials retain the same RAM guards at 350 contacts and 256 normal offline frames.</p> <p>Each newly built firmware has a matching <code>.memory.json</code> report. It records the linked ELF SHA-256, available internal RAM, required RAM, largest region, and SHA-256 hashes for the actual firmware files and capability manifest. Packaging and resumed builds reject absent reports, failures, stale ELFs, missing files and changed firmware. Do not reuse a report for another build.</p> <p>Run PlatformIO commands sequentially in this checkout:</p> <pre><code>python3 -B test/test_firmware_ram.py\npython3 -B test/test_t096_full_memory.py\npython3 -B test/test_nrf52_ble_startup.py\npython3 -B test/test_shared_mota_queue.py\npython3 -B test/test_cascade_release_package.py\npio test -e native -f test_ota\n</code></pre> <p>Tests cover all resolved firmware environments' hooks, real ELF parsing, allocator table formats, excluded memory, allocation failure, package/report binding and the published T096 failing budget. Shared mOTA tests exercise complete transfers, queue wraparound, unread-message order, source ownership, stop/disconnect and repeated reuse. Bluetooth tests inject task and service startup failures. The manual staging buffer also has allocation-failure and repeated release tests. ESP32 tests run the actual WiFi mOTA listener and source framing through complete transfers, idle polling, queue-full refusal, network loss, CLI detach and USB/TCP ownership changes under address/leak sanitizers.</p> <p>For older releases without saved ELFs, an audit can compare their ESP allocator tables against a matching pinned SDK ELF and read reservations from the published application itself using <code>scripts/audit_esp32_image_ram.py</code>. Unrecognized layouts require another matching reference or a historical rebuild. An audit must identify original-log/linker calculations separately from new ELF checks and verify the published firmware hashes.</p> <p>Physical validation remains necessary: boot with and without USB, pair and exchange Bluetooth messages, visit every screen, wake with the button, enable logging/MQTT, transfer mOTA, and monitor heap during a sustained workload. See memory monitoring for runtime diagnostics.</p>"},{"location":"firmware_picker/","title":"Firmware picker","text":"<p>Each result now includes Restore your settings after flashing. Its commands follow the selected logging mode and the exact image's verified role/hardware controls. Select On, Off, or Check to view and copy the commands; Companion MQTT and GPS show their app/WebConfig steps instead. See feature switches by role for the full reference. The USB web console works with the default ASCII terminal on USB Companion and infrastructure roles.</p> <p>Pick the choices in any order. Every selection narrows all the other controls to firmware combinations that were actually built in the current release set. The optional chip-family filter (ESP32, nRF52, RP2040, or STM32) can narrow the hardware list first. You can skip it: picking hardware fills it in automatically.</p> <p>The picker reads public release metadata from GitHub. It does not upload device information. Hardware names, target names, and download links come directly from the published firmware assets.</p> Current release set <p>Loading release information...</p> <p>       For a new installation, choose the exact board and role, prefer a       FULL / complete profile when it is available, and select       Full install / layout migration (merged .bin). Narrower profiles       remain available when their reduced transport or feature set is intentional.     </p> <p>     Pick in any order. Use Any to clear one choice, or clear     everything with the button below. The address bar updates with your choices;     copy its URL to reopen or share the same selection.   </p> Optional: chip family <p>Skip this if you know your board. Picking hardware selects its chip family automatically. Choose Any to clear this filter.</p> Chip family Any chip family - skip this filter Hardware Loading hardware... Hardware variant Choose hardware first Install operation          Loading install choices...        Firmware role          Loading roles...        Logging / MQTT          Loading logging choices...        OTA capability          Loading OTA choices...        Connection / bridge mode Loading modes... Feature profile          Loading profiles...        Firmware variant Loading variants... Clear all choices Copy link to settings Link to these settings <p></p>      Loading the current firmware catalog...    <p>Exact firmware match</p> Recommended download <p></p> No exact firmware matched <p></p> Browse all firmware releases Advanced: search current release filenames <p>       Use this for uncommon board suffixes or expert recovery. A filename match       is not a board-identity check.     </p>        Filename contains"},{"location":"firmware_picker/#what-the-choices-mean","title":"What the choices mean","text":"Choice Use Companion A phone, computer, or host application controls the radio Repeater Standalone mesh relay Room Server Hosts room conversations and history Sensor / telemetry Publishes supported sensor data Terminal Chat Standalone serial-terminal interface USB logging / USB-connected MQTT Node remains attached to a computer over a data-capable USB cable Wi-Fi MQTT observer Firmware connects directly to MQTT over Wi-Fi; this is not USB logging USB logging + Wi-Fi MQTT Unified FULL image sends to both paths; avoid two publishers aimed at the same broker unless messages are deduplicated No logging Normal standalone operation without the dedicated logging/MQTT profile LoRa OTA repeater Repeater profile that can stage an exact matching update received over LoRa LoRa OTA source only Full Companion serving a host-supplied update to another node without self-installing it <p>Connection and bridge choices depend on the selected role. Companion firmware may offer Full, combined USB + Bluetooth, Bluetooth, USB, Wi-Fi, serial, or Ethernet transports. Normal repeater firmware includes runtime-controlled RS-232 support where the board has room; use <code>set bridge.enabled on</code> after configuring <code>bridge.uart</code> and <code>bridge.baud</code>. The Wio-E5 remains the capacity exception and offers a separate RS-232 image. Choose Wi-Fi MQTT under Logging / MQTT; it is an output mode, not a second connection choice. Repeaters may still offer separate ESP-NOW or Ethernet bridge firmware because those paths use different compiled drivers.</p> <p>For commands and option explanations, follow the ESP-NOW bridge setup guide.</p> <p>An ESP-NOW bridge target keeps LoRa as its primary mesh radio. Expanded ESP32 Full repeater and room-server images combine ESP-NOW with WiFi MQTT in the same firmware. MQTT and ESP-NOW are independent runtime transports: use <code>set mqtt.enabled on|off</code> for MQTT and <code>set bridge.enabled on|off</code> (or <code>set espnow.enabled on|off</code>) for ESP-NOW, so either or both can run. Both use one 2.4 GHz radio, so when both are enabled the ESP-NOW bridge channel must match the connected WiFi access point's fixed channel. ESP-NOW-only mode does not require WiFi credentials. Its runtime <code>bridge.format</code> setting chooses the peer protocol: <code>wrapped</code> (the backward-compatible bridge-to-bridge default using <code>bridge.secret</code>) or <code>raw</code> (direct MeshCore ESP-NOW LR frames for <code>Generic_ESPNOW</code>, <code>SenseCapIndicator-ESPNow</code>, and other primary-ESP-NOW nodes). This is one firmware choice, not two board images. Match <code>bridge.channel</code> to the primary nodes' <code>espnow.channel</code> before selecting <code>set bridge.format raw</code>. For Heltec V4 specifically, <code>companion_radio_full</code> is still a LoRa-primary Companion; choose the existing <code>heltec_v4_repeater_bridge_espnow</code> firmware to make that board the LoRa/ESP-NOW gateway. Use its exact merged artifact when changing roles or partition layouts.</p>"},{"location":"firmware_picker/#share-a-selection","title":"Share a selection","text":"<p>Select any combination of choices, then copy the address bar or use Copy link to settings. Opening the link restores those choices after the release catalog loads. Partial selections work too, so you can share a board and role while leaving other choices open. Clear all choices removes the picker parameters from the URL. Changes update the current browser-history entry without reloading the page or adding a Back-button entry for every click.</p> <p>For example, RAK3401 repeater with internal storage preselects that board, role, OTA capability, and storage profile.</p> <p>The query parameters are <code>chipFamily</code>, <code>hardwareFamily</code>, <code>hardware</code>, <code>role</code>, <code>logging</code>, <code>ota</code>, <code>mode</code>, <code>feature</code>, <code>variant</code>, and <code>install</code>. Values use the picker's internal identifiers rather than the displayed labels. The generated link also records <code>chipAuto</code> so automatic chip-family selection or an explicit Any choice behaves the same after reopening. Existing section anchors and unrelated query parameters are preserved.</p> <p>Links use the current release catalog. If a linked choice is no longer available or conflicts with another choice, the picker identifies it and asks you to review the remaining selections. The downloadable HTML's Copy link to settings button creates a public website link that other people can open.</p>"},{"location":"firmware_picker/#full-versus-standard","title":"FULL versus standard","text":"<p>For a new installation, use the FULL / complete profile when it exists and the board has enough flash. FULL profiles keep the complete supported feature set and CLI. Standard profiles remain useful for boards without a FULL build, for an intentionally narrower transport, or when retaining an existing compatible partition layout.</p> <p>Changing between standard and FULL ESP32 layouts requires the exact-board merged image over USB. A running application cannot safely move its own active and inactive partitions.</p> <p>Current <code>full-usb-wifi</code> profiles use one binary for no external output, USB packet logging/USB-connected MQTT, direct WiFi MQTT, or both. The picker shows that same exact binary for each compatible logging choice; select the saved runtime mode with <code>set logging.output off|usb|wifi|both</code>. A FULL logging-fallback profile is listed only when no WiFi MQTT sibling exists; it appears for both the no-output and USB choices because <code>set usb.logging off|on</code> is persistent. On a fresh unified FULL install with no saved SSID, the setup AP and WiFi radio remain available for 30 minutes per boot, then turn off automatically until the next reboot or power cycle. An explicit administrator <code>start webconfig</code> remains available as an override. A saved SSID switches to the normal indefinite reconnect behavior instead.</p> <p>Full Companion profiles use one binary for USB, BLE, ordinary Wi-Fi on ESP32, source-only LoRa OTA, Terminal Chat, optional USB packet logging, and any board-qualified serial or Ethernet Companion transport. Bulk builds therefore omit separate attached-transport, Terminal Chat, and USB-logging artifacts whenever the exact Full recipe exists. RAK4631 repeater and room-server Ethernet images remain separate roles. Fresh installs default to logging off. Heltec V3 and base OLED V4 Full images also contain the former direct Wi-Fi MQTT Companion capability, configured at runtime through WebConfig, so their separate <code>companion_radio_wifi_mqtt</code> artifacts are omitted from canonical builds as well.</p> <p>When Full Companion does not fit but a matching USB Companion does, that USB artifact also supplies Terminal Chat and replaces its standalone release image. Heltec E290 and T190 now publish one Full USB + BLE + WiFi Companion; their old combined and single-transport names are explicit-build compatibility aliases. SSD1306 Full Companion builds use <code>set display.rotation 90|180|270</code>; <code>0</code> restores the board default, so a separate rotated release image is not recommended.</p> <p>Ordinary non-OTA roles also use one artifact for normal operation and USB logging. On ESP32 1.17.1.5, run <code>set powersaving off</code> before <code>set usb.logging on</code>. Select the saved mode with <code>set usb.logging off|on</code>; no <code>-logging-</code> artifact is emitted. KISS, BLE-only Companion, and constrained LoRa OTA repeater images retain their protocol/partition contracts and do not inherit plaintext USB logging.</p> <p>nRF52 Full Companion keeps the multi-role primary interface on <code>00</code>; it starts as an ASCII terminal and automatically hands a complete <code>&lt;</code> frame to Binary Companion. <code>set usb.logging on reboot</code> adds its plaintext interface <code>02</code>.</p> <p>Every ESP32 Full Companion instead exposes one USB TTY. Logging is off by default, so the TTY serves the ASCII/Binary Companion switcher. On 1.17.1.5, run these two text commands to enable USB logging:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>The second command turns that same TTY into an input-capable plaintext CLI/logging stream; framed Binary Companion is unavailable on USB while logging owns it. <code>set usb.logging off</code> stops the logs and leaves the TTY in the normal ASCII terminal, matching a fresh Full installation. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch from there to Binary Companion. BLE and Wi-Fi Companion remain usable while the USB TTY is logging. ESP32 Full builds use the repository's Arduino-ESP32 2.x base where the board supports it; RC32 and ESP32-C6 retain their board-required Arduino 3.x platform but still expose only one USB TTY. A second ESP32 CDC interface is not part of the release profile.</p> <p>The picker includes the power-saving workaround when selecting USB or USB + WiFi logging on ESP32 1.17.1.5. WiFi/MQTT-only logging does not need it while the Repeater/Room Server bridge is running; check <code>get mqtt.running</code>. The workaround is not added to nRF52 directions. See logging by role for the saved settings and the original firmware's USB sleep issue.</p>"},{"location":"firmware_picker/#companion-usb-terminal-on-linux","title":"Companion USB terminal on Linux","text":"<p>Full, USB and USB + Bluetooth Companion results include Companion USB terminal (Linux / Bash) under Restore your settings after flashing, with copyable connection and recovery commands.</p> <p>Updated 1.17.1.6 USB Companions default to ASCII at boot and after an observable USB session reset. <code>picocom -b 115200 /dev/ttyACM0</code> is sufficient for a fresh session. A valid framed app command automatically selects Binary Companion. The command below also works with older firmware or a port left in Binary mode.</p> <p>Run this in Bash on the Linux computer connected to your radio:</p> <pre><code>picocom -b 115200 --imap spchex \\\n  --initstring $'\\r+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre> <p>Replace <code>/dev/ttyACM0</code> with your radio's port, such as <code>/dev/ttyACM1</code> or <code>/dev/ttyUSB0</code>. Use the primary USB data interface (<code>00</code> when multiple interfaces appear), and close other apps using it. The init string requests the ASCII CLI; its leading carriage return clears an unfinished input line. <code>--imap spchex</code> displays binary control bytes safely during the transition.</p> <p>If the terminal display is scrambled, exit picocom with Ctrl+A, then Ctrl+X, run <code>reset</code> in your Linux shell, then reconnect with the command above. At the radio prompt, run <code>version</code> and <code>board</code> to identify the node. See the Companion USB mode guide.</p>"},{"location":"firmware_picker/#companion-tempradio2-transmit-settings","title":"Companion tempradio2 transmit settings","text":"<p>LoRa Companion results for 1.17.1.6 and newer include Companion tempradio2: transmit on both under Restore your settings after flashing. After configuring <code>tempradio2</code> in <code>rxtx</code> mode, choose Transmit on both to copy:</p> <pre><code>set radio2.cross on\n</code></pre> <p>This copies new messages to both <code>radio</code> and <code>tempradio2</code>. The setting is saved, outlasts the temporary session and reboot, and also allows OTA traffic to cross profiles. Default isolation copies <code>set radio2.cross auto</code>; Check shows the temporary profile, crossing policy and per-profile transmit counters. See the two-profile setup guide.</p>"},{"location":"firmware_picker/#installation-methods","title":"Installation methods","text":"File Use <code>-merged.bin</code> Erase/fresh install, recovery, role migration, or partition-profile change on ESP32 over USB Non-merged <code>.bin</code> Update an existing same-board, same-role, same-partition installation <code>.zip</code> Native nRF52 Serial DFU update package; it is not an extra archive <code>.uf2</code> UF2 bootloader drag-and-drop install or update <code>.hex</code> Erase/recovery flash with a supported wired programmer <p>Never send a merged ESP32 image through browser OTA or LoRa OTA. Back up the node configuration and verify every filename suffix before flashing.</p>"},{"location":"firmware_picker/#lora-ota-and-otafix","title":"LoRa OTA and OTAFIX","text":"<p>A LoRa OTA repeater build installs repeater firmware that can receive and stage updates. A later LoRa update still needs an exact target identity, compatible partition signature, matching radio settings, and the correct update package.</p> <p>nRF52 LoRa OTA requires an OTAFIX bootloader built for the exact board. There is no universal bootloader file. Use the OTAFIX 2.4.6 for this release and select the hardware-matched HEX, Serial DFU ZIP, or bootloader-update UF2.</p>"},{"location":"firmware_picker/#hardware-and-variant-names","title":"Hardware and variant names","text":"<p>Hardware families with multiple released targets get a second hardware-variant menu. It separates revisions, display type, expansion kit, radio/PA layout, pin map, and other physical differences without crowding the first menu. The firmware-variant menu separately exposes choices that still require different code or wiring, such as serial port or the legacy <code>no_external_sensors</code> target suffix. For RAK3401 and RAK4631, the picker labels that compact LoRa OTA option Internal storage (no external storage board). Its result details explain the omitted optional environmental/ranging sensor drivers; the reduction does not disable generic I2C or unrelated board-integrated peripherals. Other boards retain the Reduced optional environmental/ranging drivers label. Reduced RAK3401 and RAK4631 targets retain INA219/INA226/INA260/INA3221 as voltage/current entries in the optional sensor table. They are not the only I2C users: the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals in compatible recipes. RAK12501/L76K GPS uses Serial1 instead. The explicit RAK4631 Serial1 bridge omits the combined GPS provider because its bridge owns the RAK12501 UART, so that legacy image does not expose RAK12500 either. The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>; to install both, keep RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>. Companion power saving, controllable FEM receive gain, and radio-chip receive gain are saved settings rather than separate recommended firmware files. Do not substitute a similarly named physical target.</p> <p>The header-wired RAK19007 W25Q16 LoRa-OTA recipes are also exact hardware variants, labeled External storage board (W25Q16) in the picker. W25Q16 is the flash-memory part on the added storage board; RAK13302 identifies the radio module, not the storage board. Choose this variant for RAK4631 or for RAK3401 + RAK13302 only when that core/radio combination, the <code>EF4015</code> flash wiring, and its matching OTAFIX bootloader are all present. The common base-board wiring does not make the two firmware or bootloader identities interchangeable.</p> <p>The picker recommends one Full Companion image instead of separate USB, BLE, ordinary WiFi, and USB-logging images. On ESP32, logging is off by default so the one USB TTY starts in ASCII and automatically changes to framed Companion when a complete <code>&lt;</code> frame arrives. Enabling logging gives that TTY to the plaintext CLI/logger and disables framed USB Companion until logging is turned off and the normal ASCII-to-binary mode switch occurs. nRF52 Full Companion retains its optional dedicated interface <code>02</code>. Exact filename search still finds old aliases from earlier releases.</p> <p>For same-partition ESP32 infrastructure migrations, the picker similarly recommends the ordinary target's exact-identity Full image when it is present. The former observer-named Full image remains available through exact filename search for deployed devices that still use that mOTA identity; it is not shown as a second recommended configuration.</p> <p>Some normal ESP32 roles begin in the legacy 1.25 MiB dual-OTA layout but have a canonical Full image with a larger partition table. Their Full image keeps the ordinary target identity for future mOTA updates, but the first install is always its exact <code>-merged.bin</code> over USB: LoRa mOTA intentionally rejects a package whose partition signature differs from the running layout. During this transition the portable artifact remains published for already-installed nodes. The current migration set is LilyGo T3S3 SX1262/SX1276 repeater and room-server roles, Station G2 repeater and room-server roles, and ThinkNode M2 repeater and room-server roles. Station G2 moves to two 6.25 MiB slots; the 4 MiB T3S3 and ThinkNode M2 boards move to two 1984 KiB slots.</p>"},{"location":"firmware_picker/#maintaining-the-runtime-directions","title":"Maintaining the runtime directions","text":"<p>The online picker and downloadable HTML use the same command renderer. Hardware-specific controls are enabled only when <code>_data/firmware_controls.json</code> matches the selected release family and exact target. If that metadata is missing or belongs to another release, the picker retains basic role/logging directions and links the complete guide without inventing hardware support. For 1.17.1.6, that JSON also records the verified LoRa OTA role of each image and USB logging modes where the packaged application was checked. Logging metadata is tied to the source hash of its firmware file. The normal iKoka 30 dBm repeater has USB logging and LoRa OTA; its compact no-external-sensors image has LoRa OTA without logging. Capacity directions come from each qualified profile's recorded reductions and are tied to the source hash of the selected download. The older 1.17.1.5 USB sleep workaround stays limited to that release.</p> <p>After qualifying a new release, resolve its PlatformIO configuration with no other PlatformIO process running, then generate the controls from that source revision and its staged manifests:</p> <pre><code>pio project config --json-output &gt; /tmp/meshcore-picker-pio-config.json\npython3 scripts/generate_picker_controls.py \\\n  --stage /path/to/staged-release \\\n  --pio-config /tmp/meshcore-picker-pio-config.json\n</code></pre> <p>Refresh the <code>data-controls-url</code> version query when publishing the generated metadata so browsers fetch the new release's controls.</p> <p>For the downloadable version, save the release family's public GitHub release objects as a JSON array, then package the same picker UI and controls:</p> <pre><code>python3 scripts/package_firmware_picker.py \\\n  --releases-json /path/to/releases.json \\\n  --output /path/to/FIRMWARE-PICKER.html\n</code></pre> <p>This HTML embeds its catalog and directions, so selections work without an internet connection. Firmware downloads and the USB web console still need network access. When replacing the downloadable picker on release pages, update its entry in each page's <code>SHA256SUMS.txt</code> as well.</p>"},{"location":"firmware_picker/#memory-corrected-11715-downloads","title":"Memory-corrected 1.17.1.5 downloads","text":"<p>Corrected downloads retain the 1.17.1.5 release page and use source suffix <code>aa20e927</code>, with <code>1e4d1e16</code> for Wireless Paper Full's 350-contact follow-up. The picker accepts replacement source hashes within that exact release version. Its installation directions identify the nRF52 queue-sharing behavior, Wireless Paper Full's 350 contacts with a shared 256/128-slot queue, and the 150-contact limit on the other six affected ESP32 Full profiles. Those notices apply only to the corrected files. See the memory correction details and each replacement's <code>.memory.json</code> report before updating.</p>"},{"location":"flood_filtering/","title":"Flood Filtering and Moderation","text":"<p>This guide explains the Keymind forwarding filters. Repeaters expose the full set of channel, rule, blacklist, and moderation controls described here. FULL-profile ESP32 room servers expose the generalized <code>flood.rule</code> table (and its <code>flood.filter</code> alias) with 31 forward-rule slots, but not the repeater's scope-rewrite, passive-blacklist, or text-moderation phases. Standard room-server profiles do not compile the rule table. Filters decide whether the node retransmits a packet and can assign a transport scope before that decision. They do not stop local reception, packet logging, or MQTT observation.</p> <p>Only flood routes are filtered:</p> <ul> <li><code>0x00</code> / <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> - flood routing with transport codes</li> <li><code>0x01</code> / <code>ROUTE_TYPE_FLOOD</code> - unscoped flood routing</li> </ul> <p>Direct routes <code>0x02</code> and <code>0x03</code> are never affected by these rules. The route and payload values follow the upstream packet-format reference and payload layouts, with this fork's LoRa OTA assignment noted below.</p>"},{"location":"flood_filtering/#automatic-flood-advert-limits","title":"Automatic flood-advert limits","text":"<p>Repeaters, room servers (including non-FULL builds), and forwarding sensors automatically limit relayed <code>ADVERT</code> packets. No CLI rule is needed. Companions and the repeater's receive-only MQTT observer do not allocate this history. This is separate from discovery-response limits, self-advert timers, hop caps, and the per-rule <code>rate=N/min</code> setting below.</p> <p>The ordinary quota is shared by the first 12 public-key hex characters (six bytes of the advertised origin key, not a path hash). Each prefix has a fixed 180-minute window starting with its first tracked valid flood advert.</p> Shortest received hops in that window Distinct adverts forwarded per 180 minutes 0\u20131 10 2 9 3 8 4 6 5 5 6 4 7 3 8+ 2 <p>The minimum received hop count, before adding this relay, sets the quota; one-, two-, and three-byte path hashes have the same policy. A shorter valid duplicate may increase the quota without restarting the window or clearing its count. Longer routes never decrease the allowance during that window. The payload signature must verify before any history changes. Path metadata itself is not signed, so this is a received-distance heuristic, not proof of physical distance.</p>"},{"location":"flood_filtering/#continuing-abuse-and-recovery","title":"Continuing abuse and recovery","text":"<ul> <li>A full public key that exceeds the normal level in one window receives a   first strike. If it exceeds that level again in the immediately following   window, it enters the bad list. A quiet intervening window breaks this chain.</li> <li>Escalation is deliberately conservative: once a key enters the bad list,   a later shorter route does not undo that decision, even if the increased   quota makes the current window fall below the normal level. This applies to   shorter duplicate and new adverts, including a matching-prefix key's route.   The existing restriction remains until seven-day recovery, manual clear, or   reboot; a shorter route alone never erases a recorded violation.</li> <li>The bad list matches all 32 public-key bytes, not the prefix. Different   full keys sharing a prefix share the ordinary forwarding quota, but their   received counts are not combined to accuse an innocent key of ongoing abuse.</li> <li>A bad-listed key may have at most one distinct advert forwarded every   12 hours, measured from its last admitted forward (including before   escalation). Ordinary forwarding filters still apply.</li> <li>Removal requires seven uninterrupted days without exceeding the normal   hop-based level. Recovery is measured against received distinct adverts,   not the much smaller number allowed to be forwarded. Silence also qualifies.</li> <li>Each over-limit window restarts recovery from that window's end. Continued   abuse can therefore extend the restriction indefinitely; it does not expire   automatically seven days after the first offence.</li> </ul>"},{"location":"flood_filtering/#inspect-the-current-limits","title":"Inspect the current limits","text":"<p>Use <code>get flood.advert</code> to list rate-limited origins, three per page. Continue with <code>get flood.advert 2</code>, etc. Rows show a 12-hex public-key prefix, the reason (<code>quota</code>, <code>history</code>, or <code>bad</code>), and the wait before another new advert is eligible under the automatic limiter. <code>get flood.advert key 1</code> shows the full key and counters for row 1, including the remaining bad-list recovery time. A bad-listed key remains visible with <code>wait=0s</code> when its next single forward is due. Prefix collisions appear as separate full-key entries.</p> <p>This is a live, read-only view: expiry can change row indices between queries, but reading never resets quotas or extends recovery. Sources rejected solely because the protected-history table is full are not retained, so they cannot be listed. See the CLI reference.</p>"},{"location":"flood_filtering/#clear-history","title":"Clear history","text":"<p>All timers use rollover-safe uptime, so setting the clock forward or backward cannot clear the restriction. This history is currently RAM-only: rebooting the relay clears it, and time while powered off is not tracked. A manual clear also resets both the ordinary quota and abuse history for its selected target:</p> <pre><code>clear flood.advert all\nclear flood.advert &lt;64-hex-full-public-key&gt;\n</code></pre> <p>These use the ordinary local/admin CLI authorization, including authenticated admin LoRa CLI. A prefix is never accepted for a targeted clear; missing or invalid selectors do not clear anything. Clearing an exact key preserves other full keys even when their 12-hex prefixes match. No preferences, contacts, neighbours, replay timestamps, or manually configured flood rules are erased.</p>"},{"location":"flood_filtering/#scope-and-resource-bounds","title":"Scope and resource bounds","text":"<p>Only forwarding is suppressed. Valid adverts remain available to local contact/neighbour handling and can still appear in raw RX logs or MQTT. This cannot prevent the origin or upstream repeaters from transmitting. Direct adverts, discovery control responses, messages, OTA packets, and this node's own scheduled adverts are not charged. Existing physical retry attempts of an admitted advert are not additional distinct adverts.</p> <p>The limiter retains up to eleven 64-bit payload hashes per full key per window: ten possible ordinary admissions plus evidence of exceeding the largest quota. Paths and transport scopes do not change these hashes. Retained duplicate hashes cannot consume additional quota even if the general packet-seen cache has evicted them. Once the eleven distinct receive slots are full, additional unretained payloads are suppressed until the next window. Only packets passing all ordinary forwarding gates consume forwarding quota; valid received traffic still supplies abuse evidence when another gate blocks it.</p> <p>The default is 128 full-key slots (18,432 bytes of entry storage plus small bookkeeping), 96 on nRF52 (13,824 bytes, preserving the mOTA runtime RAM reserve), or eight on RAM-constrained STM32 builds (1,152 bytes). <code>FLOOD_ADVERT_SOURCE_SLOTS</code> overrides the capacity at compile time. When full, the least-recently-heard normal key is removed first. Valid retained duplicates update last-heard too. Evicting a normal key discards its ordinary quota history, so capacity should still be sized for the deployment's active origins. First-strike evidence and bad-list entries are protected from eviction: if every slot protects abuse history, untracked origins are not forwarded until a slot expires or an administrator clears history. Table churn cannot erase an existing bad-list penalty. No heap allocation or per-packet filesystem writes are used.</p>"},{"location":"flood_filtering/#before-making-changes","title":"Before making changes","text":"<p>On a repeater, show the current forwarding controls:</p> <pre><code>get repeat\nget flood.max\nget flood.max.unscoped\nget flood.max.advert\nget flood.channel.data\nget flood.channel.data.hops\nget flood.channel.scope\nget flood.channel.scope.require\nget flood.filter\nget flood.rule\nget flood.filter.blacklist\nget flood.moderation\n</code></pre> <p><code>flood.rule</code> is an alias for <code>flood.filter</code>, not another table. Generalized repeater FPF7 has 63 forward-rule slots plus scope-rewrite and shared-blacklist sections in the same atomic policy file. FULL room servers have 31 forward slots and empty repeater-only sections. Compact target profiles retain their separate FPF6-era controls. <code>flood.moderation</code> has 16 slots. A new repeater FPF7 table starts with <code>ota all suspend=tempradio</code> in slot 1 and an authenticated <code>#wardriving hops=5+</code> radio drop in slot 2, and an authenticated <code>#wardriving hops=all mode=bridge,cross</code> drop in slot 3. FULL room servers seed only the OTA row; their generalized engine also accepts transport-mode rules. <code>flood.moderation</code> starts empty. A row can opt into <code>suspend=tempradio</code>; temporary radio is not synonymous with OTA and can carry normal packet types too. A corrupt or truncated table fails open, so corrupt storage does not silently enable blocking.</p> <p>On a FULL ESP32 room server, use <code>get flood.rule</code> (or <code>get flood.filter</code>) for the available table. Remote rule changes require room-server administrator access. <code>flood.filter.blacklist*</code> and <code>path=blacklist</code> are repeater-only; use the ordered <code>prefix=</code> condition on a room server.</p>"},{"location":"flood_filtering/#force-floods-into-a-transport-scope","title":"Force floods into a transport scope","text":"<p><code>flood.channel.scope</code> can add a scope to a received unscoped flood or replace the scope of a transport-scoped flood before this repeater forwards it:</p> <pre><code>set flood.channel.scope &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]\nset flood.channel.scope.&lt;slot&gt; &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]\nget flood.channel.scope\nget flood.channel.scope.&lt;slot&gt;\ndel flood.channel.scope.&lt;slot&gt;\ndel flood.channel.scope all\n</code></pre> <p>The channel may be <code>public</code>, <code>#channel</code>, or a 128/256-bit hex key. A bare target names an existing region with a usable transport key. Use <code>scope=&lt;name&gt;</code> instead to derive a regionless public hashtag scope exactly as <code>flood.filter scope=&lt;name&gt;</code> does. The direct name is normalized with a leading <code>#</code>, may contain up to 30 characters, and does not need a region-list entry. Keyed rules first check the one-byte channel hash carried in the packet, then validate the MAC by decrypting with the configured channel key. A hash collision alone cannot force a scope.</p> <p>For example, this authenticates only <code>#rgdata</code> and rewrites it to <code>#BlackHole86</code> without creating a region:</p> <pre><code>set flood.channel.scope #rgdata scope=BlackHole86\nget flood.channel.scope.1\n</code></pre> <p>If that channel arrives scoped to <code>#usa</code>, the rule replaces <code>#usa</code> with <code>#BlackHole86</code>. It also handles unscoped packets and replaces any other incoming scope; the source scope is not a condition on the rule.</p> <p>Add <code>path=blacklist</code> to make a channel-scope row eligible only when the received path matches the passive <code>flood.filter.blacklist</code> ID table. It does not require an enabled <code>flood.filter</code> drop row. With 3-byte paths, one exact listed ID qualifies. With 2-byte paths, two received path entries must match the first two bytes of listed IDs. A 1-byte path never qualifies.</p> <p>Use <code>path=bucket:&lt;1-6&gt;</code> to match one of the existing <code>flood.retry.bucket</code> tables instead. Each bridge bucket holds up to 17 three-byte IDs and remains usable by channel scoping while <code>flood.retry.bridge</code> is off. Bucket matching uses the same thresholds as the blacklist: one exact hit for 3-byte paths, two qualifying entries for 2-byte paths, and no matches for 1-byte paths. Channel scoping reads the configured IDs directly; <code>recent.repeater</code> freshness and <code>flood.retry.ignore</code> do not change this match.</p> <p>There are three independent wildcard classes:</p> <ul> <li><code>txt:*</code> handles otherwise-unmatched <code>GRP_TXT</code> and <code>GRP_DATA</code>; plain <code>*</code> is   its alias.</li> <li><code>login:*</code> handles <code>REQ</code>, <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code>.</li> <li><code>other:*</code> handles every remaining flood payload type, including flood-form   TRACE and OTA.</li> </ul> <p><code>login:*</code> and <code>other:*</code> classify only the visible outer payload type; they do not authenticate its contents. Exact channel rows with usable targets always take precedence over <code>txt:*</code>, even if that wildcard has a lower slot number. Within the exact class, matching path-qualified rows are tried before ordinary fallback rows. The same qualified-then-fallback order applies within each wildcard class. A missing or unusable target is skipped, so later rows remain eligible. The lowest usable slot wins within each priority tier.</p> <p>For example, this uses bridge bucket 1 to assign <code>east</code> to <code>public</code> packets whose received 3-byte path contains <code>7576FB</code>, and assigns <code>west</code> to all other authenticated <code>public</code> packets:</p> <pre><code>set flood.retry.bucket 1 7576FB\nset flood.channel.scope public west\nset flood.channel.scope public east path=bucket:1\n</code></pre> <p>More 3-byte IDs can be added to bucket 1 later. Any one of them qualifies the <code>east</code> row. Replacing or clearing that bucket changes which paths qualify but leaves both channel-scope rows intact. Bridge retry does not need to be enabled.</p> <p>On a successful match, an unscoped route changes from <code>ROUTE_TYPE_FLOOD</code> to <code>ROUTE_TYPE_TRANSPORT_FLOOD</code>; an already-scoped route remains transport-flood but receives replacement codes. Transport code 0 is calculated with the target region or direct hashtag key over the payload type and payload, and code 1 becomes zero. The change happens before region enforcement, forwarding filters, and deduplication. Consequently <code>flood.max.unscoped</code> no longer applies to a packet converted from unscoped, while <code>flood.max</code>, <code>flood.filter</code>, loop detection, and moderation still apply to every rewritten packet. A region target must be flood-allowed. A regionless target is trusted for this matched receive pass, but it neither creates a region nor changes how unrelated packets with the same transport code pass the region gate. By default, if the selected scope differs and the rewritten packet passes those checks, its initial retransmission uses zero <code>txdelay</code> and the highest outbound queue priority so the newly scoped copy can win at the next hop. Add <code>tx=slow</code> to use an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, retain normal outbound queue priority, and force the maximum <code>txdelay</code> factor of <code>2.0</code>. The actual transmit delay is still randomized, from zero through ten packet airtimes. It does not preempt an active radio transmission or bypass CAD and airtime-budget limits. Selecting the scope already present is a no-op and does not grant special treatment.</p> <p>Direct routes are never rewritten. Standard traceroute is direct-routed and therefore remains outside this flood-only table. A custom flood-form TRACE is treated like every other flood: an applicable wildcard may rewrite it and the normal region/unknown-code gates still apply. Scope assignment does not override normal payload validation or make an otherwise non-forwardable packet type forwardable.</p> <p>LoRa OTA (<code>0x0C</code>) falls under <code>other:*</code>. A matching row adds the selected transport code or replaces the existing one, but OTA still operates normally during the temporary-radio window because the OTA handler accepts both unscoped and transport-scoped flood routes. A region target must allow flooding; a direct target uses the regionless trust behavior above. A new repeater also seeds <code>ota all suspend=tempradio</code> in flood-filter slot 1. That visible rule blocks OTA forwarding at every received hop outside temporary-radio operation and is skipped while temporary radio is active. Independently, the OTA core refuses OTA receive, relay, and transmit outside an actually active temporary-radio window, even if the seeded row is deleted or replaced.</p> <p>Capacity is selected at build time:</p> <ul> <li>Roomy ESP32 builds: 255 rewrite slots and 32 regionless-target slots, 10,204   bytes RAM.</li> <li>Classic ESP32 repeaters, nRF52, and other normal   constrained builds: 31 rewrite and regionless-target slots, 2,108 bytes RAM.</li> <li>Very-tight STM32WL builds: 15 rewrite slots and one reusable regionless-target   slot, 572 bytes RAM.</li> <li>The no-PSRAM LilyGo T-LoRa V2.1 repeater/observer: 4 rewrite and   regionless-target slots, 272 bytes RAM. This minimum holds the   three wildcard classes and one exact channel mapping.</li> </ul> <p>Classic ESP32 uses the 31-slot default even on boards with PSRAM because these tables live in internal static DRAM. The separate channel-requirement table defaults to the same capacity and uses another 34 bytes per slot. Together, the 31-slot defaults save 15,712 bytes of static RAM compared with 255 slots. Custom builds can override <code>FLOOD_CHANNEL_SCOPE_SLOTS</code> and <code>FLOOD_CHANNEL_SCOPE_REQUIRE_SLOTS</code> with build flags.</p> <p>Each rule retains its 36-byte record. A separate table holds 32-byte normalized names for up to the smaller of the rule count or 32 distinct regionless targets, except that very-tight STM32WL builds retain one reusable direct target. Both configured regions and regionless targets can be reused by any number of rules.</p> <p>On generalized builds these records are the FPF7 rewrite phase, and the file stores only through the highest occupied slot. Compact FPF6 builds retain the standalone FCS5 file and the file sizes described by their build profile.</p>"},{"location":"flood_filtering/#require-valid-incoming-scopes-only-on-selected-channels","title":"Require valid incoming scopes only on selected channels","text":"<p><code>flood.channel.scope.require</code> changes region enforcement for received flood <code>GRP_TXT</code> and <code>GRP_DATA</code> packets from a global policy to a channel opt-in policy:</p> <pre><code>set flood.channel.scope.require &lt;public|#channel|128/256-bit-key&gt;\nset flood.channel.scope.require.&lt;slot&gt; &lt;public|#channel|128/256-bit-key&gt;\nget flood.channel.scope.require\nget flood.channel.scope.require.&lt;slot&gt;\ndel flood.channel.scope.require.&lt;slot&gt;\ndel flood.channel.scope.require all\n</code></pre> <p>An empty table preserves the normal global region behavior. Once at least one row exists, a group-channel packet that authenticates against a listed key must arrive as <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> with a transport code matching a locally flood-allowed region. An unscoped packet, an unknown transport code, or a code for a denied region is not retransmitted. The check uses the original incoming scope before <code>flood.channel.scope</code> or <code>flood.filter scope=</code> can rewrite it. Those rewrite actions are skipped for a rejected listed channel, so they cannot rescue it or grant special receive/transmit timing.</p> <p>Group-channel packets that do not authenticate against any listed key bypass the region/unknown-code forwarding gate. They still pass through <code>repeat</code>, <code>flood.max*</code>, <code>flood.filter</code>, loop detection, payload validation, and moderation. Non-channel flood payload types retain the normal global region behavior. A one-byte channel-hash collision is only a prefilter; the packet must also pass MAC validation/decryption with the configured key.</p> <p>Without <code>.slot</code>, setting an existing key updates its row and a new key uses the first empty row. Numbered <code>set</code> replaces that slot. Detail output displays only the first four derived hash bytes and key size, never the secret. The table has the same build-dependent slot count as <code>flood.channel.scope</code>; each row consumes 34 bytes of RAM and storage, plus a five-byte file header. ACL permission <code>4</code> can manage it.</p> <p>For example, this requires an allowed incoming scope on <code>#bot</code>, while every other group channel bypasses region enforcement:</p> <pre><code>set flood.channel.scope.require #bot\nget flood.channel.scope.require\n</code></pre>"},{"location":"flood_filtering/#interaction-with-duplicate-detection","title":"Interaction with duplicate detection","text":"<p>The seen-packet hash contains the payload type and exact payload bytes. It does not contain the route type, either transport code, or the ordinary flood path. For <code>TRACE</code> only, the encoded <code>path_len</code> byte is also included. Therefore an unscoped packet and the same packet after this repeater adds a transport code are the same duplicate. A later copy with a different scope is also the same duplicate; changing or adding scope cannot evade the seen table.</p> <p>When equivalent non-TRACE flood copies overlap in <code>rxdelay</code>, the normal receive-quality timing still chooses the packet to process, but that winner takes a scope from the queued copies whose transport code matches an allowed region in this repeater. Unknown and denied scopes are ignored. If eligible copies have different scopes, the shortest received path supplies the scope. Equal path lengths prefer the deepest matching child region (the narrowest configured scope). A remaining tie keeps queue order. The winner keeps its own path, SNR, and delay schedule; only its route and transport codes can change, including replacement of a less-preferred scope it already carried.</p> <p>Scope selection happens at dequeue so the original scopes remain available for comparison. It applies only while copies are queued and cannot alter a copy already processed into the seen table. Flood-form TRACE participates in the same arbitration. Direct traceroute never enters this flood queue.</p> <p>A packet that already matches a configured fast <code>flood.channel.scope</code> or <code>flood.filter scope=</code> action and needs its scope changed bypasses this inbound <code>rxdelay</code> queue entirely. A <code>tx=slow</code> row remains in the queue with twice the configured base, floored at <code>2.0</code>, and participates in normal queued-copy scope arbitration.</p>"},{"location":"flood_filtering/#runtime-flood-rules","title":"Runtime flood rules","text":"<p>On repeaters with the rule engine enabled and on FULL-profile ESP32 room servers, <code>fr</code>, <code>flood.rule</code>, and <code>flood.filter</code> name the same persistent table. The evaluator is fixed firmware, but every row is data, so an authenticated operator can add, replace, inspect, or delete a row without an OTA or reboot. Existing <code>flood.filter</code> commands remain compatible. Only FPF6 and FPF7 files are accepted; FPF1-FPF5 files are rejected and filtering fails open. A row saved by the extended engine uses FPF7. Older firmware cannot preserve an FPF7 table containing the packed <code>retry</code> action, one-byte <code>hash:XX</code> matcher, or <code>mode=bridge</code>/<code>cross</code> flags; remove those rows before downgrading. Old firmware rejects such a table and fails open, which disables its other filter rows too. New firmware loads older rows as <code>mode=radio</code> without changing their behavior.</p> <p>The former <code>flood.channel.block</code> table is now represented by ordinary FPF7 rows. On a generalized repeater, an existing FCB2 file is imported once into free FPF7 slots and then removed. For example, an old <code>#wardriving h=4</code> row becomes <code>type=any channel=#wardriving hops=5+ drop</code>. The 63-row table can hold all 31 former general filter rows, all 15 legacy channel-block rows, and the migrated global <code>flood.channel.data</code> gate. Compact STM32WL FPF6 builds cannot match authenticated channels and retain the older separate gate.</p> <p>On generalized repeaters, <code>flood.channel.data*</code> is a compatibility view over one ordinary visible FPF7 <code>type=grp_data ... drop</code> row. Turning it off creates or updates that row; turning it on removes the row. Its hop setting maps to <code>hops=all</code> or <code>hops=N+1+</code>. There is no hidden GRP_DATA forwarding check ahead of FPF7. Normal ordering applies, so a matching higher-priority <code>stop</code> row can exempt selected traffic. The compact rule list marks the managed row with <code>~data</code>.</p> <p>FPF7 binds <code>in=region:&lt;name&gt;</code> and <code>region=&lt;name&gt;</code> to canonical region names, not numeric region IDs. Removing, reordering, or reusing a region ID cannot silently redirect a rule. If the saved name is missing, an input-region match does not match and a target-region rewrite is skipped. Re-adding the same name reactivates the rule.</p> <p>The extended form is:</p> <pre><code>set flood.rule[.&lt;slot&gt;] type=&lt;type&gt; [mode=radio|bridge|cross|bridge,cross]\n    [hops=&lt;range&gt;] [channel=&lt;channel&gt;]\n    [prefix=&lt;ID[,ID...]&gt;] [in=&lt;input-scope&gt;] &lt;action&gt; [rate=&lt;N&gt;/min]\n    [priority=&lt;0-255&gt;] [stop] [tx=fast|slow] [suspend=tempradio]\nget flood.rule\nget flood.rule.&lt;slot&gt;\ndel flood.rule.&lt;slot&gt;\ndel flood.rule all\n</code></pre> <p>The command must be entered on one line. Match fields in one row are ANDed. Radio rows are matched against the same immutable packet state captured on receive, before any rule rewrites its scope. Bridge/cross rows match at their transport boundary. Only rows for the current mode participate in ordering and stop processing. Matching rows are then processed by descending numeric <code>priority</code>. At an equal numeric priority, authenticated channel matches run before raw <code>hash:XX</code> matches, raw hashes run before <code>channel=*</code>, and lower slot number breaks the remaining tie. Priority defaults to <code>0</code>; an explicitly higher numeric priority overrides specificity.</p> <p>Numbered examples replace the selected slots, including factory defaults. Omit the slot number to add a rule without replacing an occupied slot.</p> <p>The first matching <code>stop</code> row ends the FPF7 forward phase after that row. Higher-order matches and the stop row still apply; lower-order matches do not. A stop-only row is therefore an exception to lower-priority FPF7 rows. It cannot undo a higher-priority drop and it does not bypass hard forwarding gates or the scope-rewrite and moderation phases. Without a stop row, matching drop and rate rows remain independent and the highest-order matching scope or region rewrite wins.</p> <p>Match fields:</p> <ul> <li><code>type=</code> accepts the same packet names and numeric values as legacy   <code>flood.filter</code>. The positional form remains accepted.</li> <li><code>hops=</code> accepts <code>all</code>, <code>N</code>, <code>N+</code>, or <code>N-M</code>. The positional form remains   accepted. Received hops over 3 are written as <code>hops=4+</code>.</li> <li><code>mode=radio|bridge|cross|bridge,cross</code> selects the admission phase; omitted   means <code>radio</code>. See bridge and crossover filtering.</li> <li><code>channel=*|public|#name|hash:XX|128-bit-key|256-bit-key</code> optionally narrows by   channel. <code>channel=*</code> is an unconstrained wildcard: it performs no channel   authentication and matches every payload selected by <code>type=</code>. Thus   <code>type=any channel=*</code> means every flood payload type. <code>public</code>, <code>#name</code>, and   raw keys authenticate one channel and narrow the row to <code>GRP_TXT</code> or   <code>GRP_DATA</code>. <code>hash:XX</code> compares only the visible one-byte group-channel hash.   <code>short:XX</code> and a bare two-digit byte are aliases; saved output uses   <code>hash:XX</code>. This matcher is unauthenticated, has a 1-in-256 collision space,   and can be selected by a sender, so prefer an exact name or key when known.   <code>hash:11</code> is not an alias for Public: it includes Public and every <code>0x11</code>   collision, while <code>public</code> verifies and decrypts with the Public key. This is   channel authentication, not sender authentication: the group MAC is two   bytes and the Public key is shared.</li> <li><code>prefix=</code> is a source-path prefix containing one to three comma-separated   pbyte IDs. Every ID must use the packet's pbyte width: 2, 4, or 6 hex   characters for 1-, 2-, or 3-byte paths. Order matters and matching begins at   the first received path entry. <code>path=&lt;prefix&gt;</code> is an alias;   <code>path=blacklist</code> retains its separate unordered-list behavior.</li> <li><code>in=any|none|scoped|allowed|unknown|scope:&lt;name&gt;|region:&lt;name&gt;</code> tests the   original incoming route before any rewrite. <code>none</code> means an unscoped flood;   <code>scoped</code> means any transport flood; <code>scope:name</code> compares the exact public   hashtag-derived scope; and <code>region:name</code> compares an allowed configured   region. <code>allowed</code> is the legacy <code>require=region</code> test and includes an   unscoped packet when the wildcard region allows it. <code>unknown</code> means a scoped   packet that does not resolve to an allowed local region.</li> </ul> <p>Actions:</p> <ul> <li><code>drop</code> prevents retransmission when the row matches. The strict   <code>flood.rule</code> form requires an explicit action. For backward compatibility,   only a legacy <code>flood.filter</code> row with no rewrite, rate, or stop action means   drop implicitly.</li> <li><code>scope=&lt;name&gt;</code> derives a public transport scope directly from the name; no   region entry is consulted. <code>scope=BlackHole86</code> is therefore a valid   regionless sink. <code>region=&lt;name&gt;</code> is different: it resolves a configured,   flood-allowed region and one of that region's transport keys.</li> <li>A <code>stop</code> on a row whose <code>region=</code> target is currently unusable is also inert,   allowing lower-priority safety rules to run. Direct <code>scope=</code> targets do not   have this configuration dependency.</li> <li><code>rate=N/min</code> is a per-node, per-row fixed one-minute forwarding limit. It can   stand alone or accompany a scope/region rewrite. Quota is charged only after   every other forwarding gate, including moderation, accepts the packet. It is   not keyed per sender; use <code>flood.moderation</code> when a group-text rate must be   tied to an exact display name.</li> <li><code>retry</code> allows a matching received flood to start the configured retry   sequence. <code>retry=on</code>, <code>retry=allow</code>, and <code>action=retry</code> are aliases. If the   table has no active <code>retry</code> rows, global retry behavior is unchanged. If it   has one or more, those rows are a retry allow-list: at least one must remain   in the ordered, stop-truncated match set. The action may accompany rewrite,   rate, or stop, but not <code>drop</code>; its compact flag is <code>f=r</code>.</li> <li><code>priority=0-255</code> controls the primary processing order. Higher values run   first. Equal values use automatic channel specificity (authenticated, then   raw hash, then wildcard) before slot order. <code>pri=</code> is the compact alias.</li> <li><code>stop</code> (or <code>action=stop</code>) applies this row and prevents lower-order FPF7 rows   from acting. It can stand alone or accompany drop, rewrite, or rate.</li> </ul> <p>When several rows use the same channel key, authentication is performed once for that packet and reused by those rows. This cache lives only for the current receive evaluation; it is not persisted and never stores plaintext or a password. A <code>hash:XX</code> row deliberately skips authentication and uses only the one visible byte.</p> <p>The global retry controls remain hard gates. A <code>retry</code> row does not override a zero <code>flood.retry.count</code>, path/type attempt caps, disabled forwarding, <code>flood.retry.advert</code>, a drop verdict, or any other forwarding rejection. <code>flood.retry.bridge</code> independently chooses ordinary retry or bridge-bucket completion for an allowed packet. The selector applies to received floods; locally originated floods retain the normal global behavior.</p> <p>The exact requested examples are:</p> <pre><code># If #rgdata arrives unscoped with more than 3 received hops, add\n# the regionless #BlackHole86 scope.\nset flood.rule.2 type=grp_data hops=4+ channel=#rgdata in=none scope=BlackHole86\n\n# Rewrite the exact incoming #usa scope to #BlackHole86 for #rgdata.\nset flood.rule.3 type=grp_data channel=#rgdata in=scope:usa scope=BlackHole86\n\n# Match a two-byte source-path prefix and cap forwarding at 10 per minute.\nset flood.rule.4 type=any prefix=860C rate=10/min\n\n# Keep authenticated #rgdata at two hops or less out of lower-priority FPF7\n# rules. Hard gates and separate tables still apply.\nset flood.rule.5 type=grp_data hops=0-2 channel=#rgdata priority=200 stop\n\n# Retry received Public and #hamradio floods, using bridge completion.\n# Once these rows exist, other received floods are not retried.\nset flood.retry.bridge on\nset flood.rule.6 type=any channel=public retry\nset flood.rule.7 type=any channel=#hamradio retry\n\n# Fall back to an unauthenticated one-byte match if only the visible hash is known.\nset flood.rule.8 type=any channel=hash:A7 retry\n\nget flood.rule.2\nget flood.rule.3\nget flood.rule.4\n</code></pre> <p>Public's visible channel hash is <code>0x11</code>, so a <code>hash:11 drop</code> row also matches Public unless an earlier exact-channel rule stops it. This standalone example preserves authenticated Public while dropping other packets that use the same visible byte:</p> <pre><code>set flood.rule.2 type=any channel=public retry stop\nset flood.rule.3 type=any channel=hash:11 drop\n</code></pre> <p>The Public rule's MAC/decrypt check must succeed before its <code>stop</code> applies. A colliding channel misses that rule and reaches the hash drop. With equal numeric priorities, authenticated-channel specificity automatically puts the Public rule first regardless of slot order. Without <code>stop</code>, both rows match Public and the sticky drop wins. Remove <code>retry</code> from the Public row if the exemption should not also opt Public into flood retry. An explicitly higher numeric priority on the hash rule remains an operator override.</p> <p>The 240 KB STM32WL profiles keep <code>MESH_ENABLE_FLOOD_RULE_ENGINE=0</code> and retain the persistent compact FPF6 <code>flood.filter</code> and blacklist syntax below. They still perform filtering, but omit the generalized <code>flood.rule</code> parser and extended fields. No partition size is changed by this feature.</p> <p>The compatible filter and blacklist commands are:</p> <pre><code>set flood.filter.blacklist &lt;ID[,ID...]&gt;\nset flood.filter.blacklist.&lt;slot&gt; &lt;ID[,ID...]&gt;\nget flood.filter.blacklist\nget flood.filter.blacklist.&lt;slot&gt;\ndel flood.filter.blacklist\ndel flood.filter.blacklist.&lt;slot&gt;\nset flood.filter &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]\nset flood.filter.&lt;slot&gt; &lt;type&gt; [hops] [path=blacklist] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]\nget flood.filter\nget flood.filter.&lt;slot&gt;\ndel flood.filter.&lt;slot&gt;\ndel flood.filter all\n</code></pre> <p>The blacklist holds up to 255 unique 3-byte repeater IDs on ESP32 builds and 18 on other builds. Each is written as six hexadecimal digits. For example:</p> <pre><code>set flood.filter.blacklist A1B2C3,D4E5F6,112233\nset flood.filter.blacklist.4 445566\nset flood.filter any all path=blacklist\n</code></pre> <p>This is intended for abuse containment, such as refusing to retransmit floods that repeatedly enter the mesh through known internet gateways dumping bulk traffic. The list is shared by every FPF7 row and scope-rewrite row that uses <code>path=blacklist</code>; it is not copied into each rule.</p> <p>An unnumbered <code>set</code> replaces the list with up to 18 IDs, the largest command that fits every CLI transport. A numbered <code>set</code> writes a batch of up to 18 IDs beginning at an existing slot or the next consecutive slot. This is how an ESP32 list grows beyond 18. Deleting a numbered entry compacts the entries after it. Unnumbered <code>get</code> reports the total and prints the leading IDs that fit; numbered <code>get</code> retrieves one specific entry.</p> <p><code>path=blacklist</code> is an unordered precondition on that row. With 3-byte path hashes, one or more exact blacklist hits qualifies the packet. With 2-byte path hashes, two or more received path entries must match the first two bytes of listed IDs. Each received entry is counted at most once. A 1-byte path never qualifies. The IDs may occur anywhere in the received path; neither their list order nor their path order matters.</p> <p>Without a slot number, <code>set</code> reuses an identical row or selects the first empty slot. Use a slot number to replace a row whose match or action is changing. Omitting the hop expression means <code>all</code> (<code>0-63</code>).</p> <p>Numbered <code>get flood.rule.N</code> and <code>get flood.filter.N</code> normally use descriptive field names. On generalized builds, a reply that would be too long uses the complete <code>set fr.N ...</code> spelling below. <code>get fr.N</code> always requests that spelling. If even the short command exceeds one reply, it returns <code>Err - compact command exceeds reply size</code> instead of a partial command. Saving such a rule still succeeds and reports that its details exceed the reply size.</p>"},{"location":"flood_filtering/#shorthand-for-copying-rules","title":"Shorthand for copying rules","text":"<p>On generalized repeaters and FULL ESP32 room servers, <code>fr</code> is a shorter name for <code>flood.rule</code>. Both forms use the same parser, validation, permissions, and saved rows. Short and full field names can be mixed in either command. <code>fr</code> requires an explicit action, just like <code>flood.rule</code>.</p> <p>These commands set exactly the same rule:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nset fr.3 any c=#wardriving m=bc d\n</code></pre> Full form Short form Meaning <code>flood.rule[.N]</code> <code>fr[.N]</code> Same rule table for <code>get</code>, <code>set</code>, and <code>del</code>. <code>type=any</code> <code>any</code> or <code>*</code> First token: any payload type. Named/numeric types also work, with optional <code>t=</code>. <code>hops=N</code>, <code>N+</code>, <code>N-M</code>, or <code>all</code> <code>h=N</code>, <code>h=N+</code>, <code>h=N-M</code>, or <code>h=*</code> Hop condition; a bare range also works. Omitted means all hops. <code>mode=radio</code>, <code>bridge</code>, <code>cross</code>, <code>bridge,cross</code> <code>m=r</code>, <code>m=b</code>, <code>m=c</code>, <code>m=bc</code> Select the admission path. Omitted means radio; <code>cb</code>, <code>b,c</code>, and <code>c,b</code> also mean both transport paths. <code>channel=...</code> <code>c=...</code> Same authenticated name/key or explicit <code>hash:XX</code> matcher. <code>prefix=...</code> <code>p=...</code> Ordered path prefix. <code>path=blacklist</code> <code>p=bl</code> Shared unordered blacklist; repeater only. <code>in=any</code>, <code>none</code>, <code>scoped</code>, <code>allowed</code>, <code>unknown</code> <code>i=*</code>, <code>i=n</code>, <code>i=s</code>, <code>i=a</code>, <code>i=u</code> Incoming scope condition. <code>in=scope:name</code>, <code>in=region:name</code> <code>i=s:name</code>, <code>i=r:name</code> Match a specific incoming scope or region. <code>drop</code> <code>d</code> Drop matching traffic. <code>scope=name</code>, <code>region=name</code> <code>s=name</code>, <code>r=name</code> Rewrite to a public scope or configured region. <code>rate=N/min</code> <code>q=N</code> Per-row forwarding allowance. <code>priority=N</code> <code>pri=N</code> Higher values run first. <code>stop</code>, <code>retry</code> <code>s</code>, <code>r</code> Stop later rules or allow the configured flood retry. <code>tx=slow</code>, <code>suspend=tempradio</code>, <code>retry</code> <code>f=s</code>, <code>f=t</code>, <code>f=r</code> Flags can combine, for example <code>f=str</code>. <p>The <code>=</code> distinguishes <code>s=name</code> (scope) from <code>s</code> (stop), and <code>r=name</code> (region) from <code>r</code> (retry). Short forms keep the same action restrictions; for example, <code>m=bc r</code> is rejected because transport rules cannot enable retries.</p> <pre><code>get fr.3\n</code></pre> <p>Returns a complete command ready to copy:</p> <pre><code>set fr.3 any m=bc c=#wardriving d\n</code></pre> <p>The compact reply omits default values and prints specific payload types as numbers. <code>get fr</code> lists the table. <code>set fr ...</code> without a slot reuses an identical rule or adds it to the first empty slot. <code>del fr.3</code> removes slot 3; <code>del fr all</code> clears the forward rules.</p> <p>Private keys are still hidden in replies. A displayed <code>c=key:XXXXXXXX</code> is a local reference to the exact key in an active rule on that device, so it can be pasted to edit or copy a rule there. On another device, or after deleting the last rule holding that key, supply the original key instead. An unknown or ambiguous reference is rejected; it never becomes an unauthenticated channel-hash match.</p> <p>The shorthand does not rename <code>flood.channel.scope</code>, <code>flood.moderation</code>, or the blacklist-management commands. Companions and compact FPF6 profiles do not expose <code>fr</code>.</p>"},{"location":"flood_filtering/#scope-actions-and-legacy-rules","title":"Scope actions and legacy rules","text":"<p>A legacy row without <code>scope=</code> is the existing drop action. On extended builds, an explicit <code>drop</code> has the same result, while <code>rate=</code> by itself creates a rate-only row. A row with <code>scope=</code> adds transport scope to an unscoped packet or replaces the codes on an already-scoped packet. The scope name is normalized with a leading <code>#</code>, and the 128-bit transport key is derived directly from that hashtag. The name does not need to exist in the region list and is not added to it. Public names up to 30 characters are accepted; private <code>$</code> scopes are not.</p> <p><code>require=region</code> is the legacy spelling of <code>in=allowed</code>. The repeater evaluates the packet's original route before any rewrite in that receive pass. An incoming transport scope must match a locally allowed region; an unscoped flood must be allowed by the wildcard region. If the check fails, that row is skipped, the filter does not grant a region bypass, and the unchanged packet is allowed to fail normal region enforcement. Other independently configured scope rows still apply in their normal order.</p> <p>When multiple scope or region rows match, the highest numeric-priority row wins. Equal priorities use authenticated channel, raw hash, then wildcard specificity before the slot-number tie-break. Rewrite rows do not approve a packet: any matching drop row and every remaining forwarding gate can still reject it. A filter-assigned scope is trusted without local region-list validation, but <code>repeat</code>, <code>flood.max</code>, loop detection, and moderation still apply. By default, a changed scope bypasses inbound <code>rxdelay</code>, then is retransmitted with zero <code>txdelay</code> and the highest outbound queue priority. Add <code>tx=slow</code> to use an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, retain normal queue priority, and force the maximum <code>txdelay</code> factor of <code>2.0</code>; the randomized transmit delay ranges from zero through ten packet airtimes. <code>tx=fast</code> explicitly restores the default. Selecting the scope already present does not grant special treatment. Active radio transmission, CAD, and airtime-budget limits are unchanged.</p> <p>On generalized repeaters, forward rules, <code>flood.channel.scope</code> rewrite rows, the shared blacklist, and the <code>flood.channel.data</code> compatibility state are one atomic FPF7 policy image. Existing <code>/flood_ch_scope</code>, <code>/flood_filter_bl</code>, FPF6, and FCB2 data is imported once; the old files are removed only after the new image verifies and commits. Compact FPF6 repeaters retain separate files. Deleting the blacklist leaves <code>path=blacklist</code> rows in place but dormant until IDs are configured again. Path hashes are truncated routing identifiers and are not authenticated proof that a particular repeater\u2014or a particular person\u2014handled a packet. FULL room servers reject blacklist commands.</p> <p>On first initialization, flood-filter slot 1 is seeded with:</p> <pre><code>set flood.filter.1 0x0C all suspend=tempradio\n</code></pre> <p>This is a normal editable row. After the table has been saved, deleting it remains persistent across reboot; the firmware does not recreate it. Run the same command to restore the exact seeded row, or omit <code>.1</code> to preserve existing slot assignments and use the first empty slot. Operators may add <code>suspend=tempradio</code> to any other row that should be skipped while either <code>tempradio</code> or <code>tempradio2</code> is active. This includes scheduled temporary profiles. The row resumes once both temporary sessions have ended.</p> <p>Suspension does not approve a packet or bypass the rest of the filter table. It skips that row, then evaluation continues with the next row and the remaining forwarding gates. An ordinary drop <code>any</code> row therefore still applies during the temporary-radio window unless an earlier matching stop row ends FPF7 processing. <code>repeat</code>, <code>flood.max*</code>, region handling, loop detection, and the OTA subsystem's own hop limit also remain in force.</p> <p>Standard traceroute uses direct routing and bypasses <code>mode=radio</code> filters. Explicit bridge/cross filters can also match direct traffic at those transport boundaries; the built-in channel rule does not match TRACE packets. For a custom flood-form trace, <code>type=any</code>, explicit <code>trace</code>, scope, region, rate, and drop rows all behave normally. The stock core does not normally flood-forward TRACE packets.</p>"},{"location":"flood_filtering/#remote-administration-lockout-warning","title":"Remote-administration lockout warning","text":"<p>There are no hidden payload-type or short-hop exemptions in FPF7. Drop and rate rules can block <code>req</code>, <code>response</code>, <code>txt_msg</code>, <code>anon_req</code>, <code>path</code>, ACK, and multipart traffic beginning at hop <code>0</code> when their match fields say so.</p> <p>A flooded login starts as <code>ANON_REQ</code>; its reply is commonly a <code>PATH</code> packet carrying an encrypted <code>RESPONSE</code>. Before a direct return path is established, administrative replies and CLI text can also be flooded. Transit repeaters do not have the session key and cannot distinguish those encrypted admin exchanges from ordinary peer packets with the same outer type. A rule therefore affects the complete outer packet class, not only packets that ultimately authenticate as administrators. Keep a serial or other recovery path and stage broad deny/rate rules carefully.</p> <p>Hop expressions are based on the path count when this repeater receives the packet:</p> <ul> <li><code>N</code> matches exactly <code>N</code> received hops.</li> <li><code>N+</code> matches <code>N</code> or more received hops.</li> <li><code>N-M</code> matches the inclusive range.</li> <li><code>all</code> matches <code>0</code> through <code>63</code> hops.</li> <li><code>0+</code>, <code>all</code>, and omitting the hop expression are equivalent. <code>get</code> reports   the stored range using the canonical spelling <code>all</code>.</li> </ul> <p>Examples:</p> <pre><code># Stop forwarding group data once it arrives with four or more path entries.\nset flood.filter grp_data 4+\n\n# Stop long adverts, while still allowing shorter adverts.\nset flood.filter.2 advert 6+\n\n# Keep LoRa OTA floods from crossing this repeater at path counts 2 through 4.\nset flood.filter.3 ota 2-4\n\n# Assign #local scope to group text without requiring #local in the region map.\nset flood.filter grp_txt all scope=local\n\n# Rewrite only packets whose incoming region was already acceptable.\nset flood.filter grp_data all scope=local require=region\n\n# Rewrite matching blacklisted paths without fast-tracking their retransmission.\nset flood.filter grp_data all path=blacklist scope=local tx=slow\n\n# Drop matching flood types after the unordered path blacklist qualifies.\nset flood.filter.blacklist A1B2C3,D4E5F6,112233\nset flood.filter any all path=blacklist\n\n# Apply a hard ceiling to flood payload types at 12 or more received hops.\nset flood.filter any 12+\n</code></pre>"},{"location":"flood_filtering/#high-traffic-mesh-example","title":"High-traffic mesh example","text":"<p>This preset limits request and group-data propagation early while allowing the login-capable response, anonymous-request, and path types to travel farther:</p> <pre><code>set flood.filter req 3+\nset flood.filter response 9+\nset flood.filter 0x06 3+\nset flood.filter 0x07 9+\nset flood.filter path 9+\nset flood.filter control 1+\nget flood.filter\n</code></pre> Rule Stops retransmission when received with <code>req 3+</code> 3 or more path entries <code>response 9+</code> 9 or more path entries <code>0x06 3+</code> (<code>grp_data</code>) 3 or more path entries <code>0x07 9+</code> (<code>anon_req</code>) 9 or more path entries <code>path 9+</code> 9 or more path entries <code>control 1+</code> 1 or more path entries <p>On a new generalized repeater table, the three factory rules occupy slots 1 through 3, so these unnumbered commands normally fill slots 4 through 9. FULL room servers and compact tables seed only OTA and use slots 2 through 7. Existing tables may choose different free slots. All six rules take effect at the thresholds shown; there are no hidden short-hop exceptions. The Control rule allows a flood received with path count <code>0</code> to be forwarded once, then stops it at the next repeater. Normal node-discovery Control packets are direct zero-hop packets and bypass these <code>mode=radio</code> rules. These rules affect only retransmission by the repeater; local reception and logging remain unchanged.</p> <p>Accepted payload names are:</p> Value Short name Full name <code>0x00</code> <code>req</code> <code>PAYLOAD_TYPE_REQ</code> <code>0x01</code> <code>response</code> <code>PAYLOAD_TYPE_RESPONSE</code> <code>0x02</code> <code>txt_msg</code> <code>PAYLOAD_TYPE_TXT_MSG</code> <code>0x03</code> <code>ack</code> <code>PAYLOAD_TYPE_ACK</code> <code>0x04</code> <code>advert</code> <code>PAYLOAD_TYPE_ADVERT</code> <code>0x05</code> <code>grp_txt</code> <code>PAYLOAD_TYPE_GRP_TXT</code> <code>0x06</code> <code>grp_data</code> <code>PAYLOAD_TYPE_GRP_DATA</code> <code>0x07</code> <code>anon_req</code> <code>PAYLOAD_TYPE_ANON_REQ</code> <code>0x08</code> <code>path</code> <code>PAYLOAD_TYPE_PATH</code> <code>0x09</code> <code>trace</code> <code>PAYLOAD_TYPE_TRACE</code> <code>0x0A</code> <code>multipart</code> <code>PAYLOAD_TYPE_MULTIPART</code> <code>0x0B</code> <code>control</code> <code>PAYLOAD_TYPE_CONTROL</code> <code>0x0C</code> <code>ota</code> <code>PAYLOAD_TYPE_OTA</code> in this fork <code>0x0D</code> <code>13</code> reserved <code>0x0E</code> <code>14</code> reserved <code>0x0F</code> <code>raw_custom</code> <code>PAYLOAD_TYPE_RAW_CUSTOM</code> <p>Decimal values <code>0</code> through <code>15</code>, hexadecimal values <code>0x00</code> through <code>0x0F</code>, the full <code>PAYLOAD_TYPE_*</code> names, and <code>any</code> are also accepted. Upstream currently reserves <code>0x0C</code>; this fork assigns it to LoRa OTA. Rows are suspended during temporary-radio operation only when explicitly configured that way.</p>"},{"location":"flood_filtering/#moderate-group-text-by-channel-and-username","title":"Moderate group text by channel and username","text":"<p>Use <code>flood.moderation</code> for flood <code>GRP_TXT</code> messages. The repeater validates and decrypts the selected channel, extracts the display name before the first <code>:</code>, then applies the rule:</p> <pre><code>set flood.moderation &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]\nset flood.moderation.&lt;slot&gt; &lt;channel&gt; &lt;sender&gt; &lt;action&gt; [action...]\nget flood.moderation\nget flood.moderation.&lt;slot&gt;\ndel flood.moderation.&lt;slot&gt;\ndel flood.moderation all\n</code></pre> <p>Channels can be specified as:</p> <ul> <li><code>public</code> for the built-in Public channel</li> <li><code>#name</code> for a well-known hashtag channel</li> <li>a 128-bit or 256-bit channel key in hexadecimal</li> </ul> <p>The key is stored locally so packets can be authenticated and decrypted. It is not included in <code>get flood.moderation</code> output.</p> <p>Available actions are:</p> <ul> <li><code>drop</code> - do not retransmit any matching message</li> <li><code>rate=X/min</code> - retransmit at most <code>X</code> messages per local 60-second window</li> <li><code>hops=N</code> - do not retransmit when the received path count is <code>N</code> or higher</li> <li><code>path=H1[,H2,H3]</code> - require the first one to three path hashes to match</li> <li><code>path=*</code> - match every path; this is the default</li> </ul> <p>At least one of <code>drop</code>, <code>rate=X/min</code>, or <code>hops=N</code> is required. Rate and hop limits can be combined. <code>rate=0/min</code> is equivalent to <code>drop</code>.</p>"},{"location":"flood_filtering/#per-user-per-channel-rate-limits","title":"Per-user, per-channel rate limits","text":"<p>Rate limits require an exact username; <code>*</code> is not accepted for a rate rule. Username comparison is ASCII case-insensitive, and names containing spaces must be quoted. A rule's counter is independent from rules for the same name on other channels, so this directly supports \"X messages per minute from user X on channel Y.\" Counters are local to this repeater and reset on reboot.</p> <pre><code># At most five Public-channel messages per minute from this display name.\nset flood.moderation public \"Noisy User\" rate=5/min\n\n# A separate limit for the same name on #local.\nset flood.moderation #local \"Noisy User\" rate=10/min\n\n# Combine a rate limit with a maximum forwarding distance.\nset flood.moderation public alice rate=4/min hops=5\n</code></pre>"},{"location":"flood_filtering/#match-the-start-of-a-path","title":"Match the start of a path","text":"<p>Path matching accepts one-, two-, or three-byte hashes. Every hash in one rule must use the same width, and matching always starts at the beginning of the received path:</p> <pre><code>set flood.moderation #local bot drop path=A1B2C3,D4E5F6\nset flood.moderation public alice rate=3/min path=71\n</code></pre> <p>A path-qualified rule cannot match a zero-hop packet and does not match until the packet contains all path entries listed by the rule.</p>"},{"location":"flood_filtering/#how-the-forwarding-controls-combine","title":"How the forwarding controls combine","text":"<p>A flood packet is retransmitted only if it passes every applicable control. In other words, the controls combine as deny rules:</p> <ol> <li><code>flood.channel.scope.require</code> evaluates a listed group channel against the    original incoming scope; unlisted group channels bypass the later region    gate while the table is active.</li> <li><code>flood.channel.scope</code> tries a path-qualified channel row before that    channel's ordinary fallback, then adds or replaces the scope from either a    configured region or a direct <code>scope=&lt;name&gt;</code> target.</li> <li>All extended <code>flood.rule</code> match fields are evaluated against the same    original incoming packet. Matches are ordered by descending numeric    priority, then authenticated/raw-hash/wildcard channel specificity, then    ascending slot. The first matching <code>stop</code> row removes every later FPF7    match. The highest-order remaining <code>scope=</code> or <code>region=</code> row may replace the    channel-scope result; a direct scope does not require a region-list entry.</li> <li><code>repeat</code> and <code>flood.max*</code> are checked.</li> <li>The FPF7 forward phase, including any row managed through    <code>flood.channel.data*</code>, applies drop and rate decisions using that saved    match result. No packet type or short-hop range is silently exempted.</li> <li>Region and loop-detection rules are checked; a regionless scope assigned by    either table is already trusted when it has no region-list match, except    that it cannot rescue a channel rejected by    <code>flood.channel.scope.require</code>.</li> <li><code>flood.moderation</code> checks decrypted group text, username, rate, hops, and    path. If it accepts the packet, matching general-rule rate counters are    charged immediately before retransmission is approved.</li> </ol> <p>The first denial is enough to prevent retransmission. A packet that is denied can still appear in local logs or MQTT output, unless a separate <code>mode=bridge</code> rule blocks MQTT packet publication. Moderation runs last because its rate counters are charged only for packets that pass every other forwarding control and will actually be retransmitted.</p>"},{"location":"flood_filtering/#delegate-filter-management","title":"Delegate filter management","text":"<p>On repeaters, ACL permission <code>5</code> is the filter-manager role:</p> <pre><code>setperm &lt;companion-public-key-hex&gt; 5\n</code></pre> <p>A filter manager can read non-secret operational status and manage <code>repeat</code>, <code>loop.detect</code>, <code>flood.max*</code>, <code>flood.channel.data*</code>, <code>flood.filter*</code>, <code>flood.rule*</code>, <code>fr[.N]</code>, and <code>flood.moderation*</code>. Delegated <code>get</code> access uses an explicit allowlist: it cannot retrieve guest, WiFi, MQTT, bridge, or other credentials, and it cannot change regions, ACL entries, radio settings, or unrelated administrator settings. Because <code>flood.filter scope=</code> derives a public hashtag key directly, a filter manager can configure that action without region-manager permission; it still cannot edit the region hierarchy.</p> <p>FULL ESP32 room servers use their existing administrator check for remote <code>fr</code>, <code>flood.rule</code>, and <code>flood.filter</code> commands; they do not grant this table through permission <code>5</code>.</p> <p>ACL permission <code>4</code>, the region/scope-manager role, can read, add, replace, and delete <code>flood.channel.scope</code> and <code>flood.channel.scope.require</code> rows and manage regions. This lets the same delegate create target regions, assign forced scopes from regions or direct hashtag names, and select the channels that require valid incoming scopes.</p>"},{"location":"flood_filtering/#security-limitations","title":"Security limitations","text":"<p>Public and hashtag channels use shared, well-known keys. A valid channel MAC proves that the sender knew the channel key; it does not identify a person. The <code>&lt;sender&gt;</code> value is an unverified display name and can be spoofed. Path hashes are truncated routing hints and can collide or be manipulated; they are not authenticated user identities.</p> <p>Use username and path rules as traffic moderation, not as an authorization boundary. For a strict network boundary, combine these tools with region ACLs, private transport/channel keys, and controlled device access.</p>"},{"location":"flood_filtering/#filter-bridge-and-radio-crossover-traffic","title":"Filter bridge and radio crossover traffic","text":"<p>The <code>mode=</code> matcher selects a separate admission phase within the same <code>flood.rule</code> / <code>flood.filter</code> table:</p> Mode Where the rule applies <code>radio</code> Ordinary LoRa flood forwarding. This is the default when <code>mode=</code> is omitted. <code>bridge</code> Packets entering or leaving an RS232 or ESP-NOW bridge, and MeshCore RX/TX packet publication through MQTT. <code>cross</code> Transmissions copied to the other radio profile, including a copy's retries. The same-profile transmission remains eligible. <code>bridge,cross</code> Both transport paths using one rule. <code>cross,bridge</code> is equivalent. <p>The third built-in repeater filter is:</p> <pre><code>set flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\nget flood.rule.3\n</code></pre> <p>The equivalent short command is <code>set fr.3 any c=#wardriving m=bc d</code>. Use <code>m=b</code> for bridge only or <code>m=c</code> for crossover only.</p> <p>It authenticates both <code>GRP_TXT</code> and <code>GRP_DATA</code> against the public <code>#wardriving</code> channel key. A different channel with the same one-byte hash is not blocked. It covers every hop count, including zero-hop/local messages, flood routes and direct routes. It remains active during temporary-radio sessions and with <code>radio2.cross on</code>: enabling crossover makes a copy eligible, but does not override the filter. The second built-in rule still permits ordinary <code>#wardriving</code> forwarding through four received hops; the third rule keeps those messages on their originating radio profile.</p> <p>Bridge filtering runs in both directions before bridge deduplication, inbound queueing, serial writes, ESP-NOW queueing, or MQTT packet publication. It applies with either <code>bridge.source rx</code> or <code>bridge.source tx</code> and with wrapped or raw ESP-NOW framing. MQTT here is the observer packet output; this does not add MQTT-to-LoRa injection or filter MQTT status/telemetry. Local reception and local packet logs remain available. Switching one radio between profiles is covered by <code>cross</code>; the bridge's WiFi channel is a separate setting.</p> <p>Transport modes support <code>drop</code>, <code>rate=X/min</code>, <code>priority=</code>, and <code>stop</code>, with the existing type, channel, hops, prefix, blacklist, incoming-scope and <code>suspend=tempradio</code> matchers. Scope/region rewrites, retry actions, and TX timing actions are rejected in these modes. Ordering and <code>stop</code> apply only to rules in the current mode: a radio exception cannot bypass a bridge/cross drop. A combined rule shares one rate counter across bridge and cross admission attempts; retries count too. A rejected queue insertion can consume an admission allowance. Queued packets already admitted are not recalled by editing a rule. Same-profile transmissions use the ordinary radio policy.</p> <p><code>get flood.rule.N</code> shows <code>mode=</code>; the overview marks each row with its mode. Modes are persistent, case-insensitive, and apply immediately to new admission attempts. <code>radio</code> cannot be combined with <code>bridge</code> or <code>cross</code> in a single row. For transport rules, hop and scope matchers see the packet at that boundary: a TX/crossover packet can already contain an appended hop or rewritten scope. The built-in rule uses all hops and any scope, so these changes cannot bypass it. On FULL room servers, add a transport rule explicitly; their factory table still has only the OTA row. Companions and compact FPF6 builds do not expose this generalized filter table.</p> <p>Saved tables, occupied slots, and deleted defaults are preserved on upgrade. To add the new default to an existing table without replacing another rule, omit the slot number (repeating the identical command reuses its row):</p> <pre><code>set flood.rule type=any channel=#wardriving hops=all mode=bridge,cross drop\nget flood.rule\n</code></pre> <p>To allow only bridge traffic while retaining the crossover block, replace the third rule with <code>mode=cross</code>. Use <code>mode=bridge</code> to retain only the bridge block. Use <code>del flood.rule.3</code> to remove both, after checking that slot 3 is still the built-in rule. Removing it does not change the separate LoRa hop-limit rule.</p>"},{"location":"flood_filtering/#restore-the-factory-seeded-rows","title":"Restore the factory-seeded rows","text":"<p>The repeater's factory-seeded forwarding rows can be restored through the CLI:</p> <pre><code>set flood.rule.1 type=ota hops=all drop suspend=tempradio\nset flood.rule.2 type=any channel=#wardriving hops=5+ drop\nset flood.rule.3 type=any channel=#wardriving hops=all mode=bridge,cross drop\n</code></pre> <p>Or use the equivalent short forms:</p> <pre><code>set fr.1 ota d f=t\nset fr.2 any 5+ c=#wardriving d\nset fr.3 any c=#wardriving m=bc d\n</code></pre> <p>These commands explicitly replace the three seeded generalized-repeater slots. Inspect them first if they may now contain other rules. Compact FPF6 builds use only the first command's <code>flood.filter.1 0x0C all suspend=tempradio</code> form.</p>"},{"location":"flood_filtering/#remove-the-custom-rules","title":"Remove the custom rules","text":"<p>To save both tables in an empty state:</p> <pre><code>del flood.filter all\ndel flood.moderation all\nget flood.filter\nget flood.moderation\n</code></pre> <p>This does not change the older <code>flood.max*</code>, loop-detection, or region settings; inspect or reset those separately when troubleshooting.</p>"},{"location":"four_fixed_tx_dwell_validation/","title":"Four fixed transmitters: longer dwell repeats","text":"<p>Same physical MercerMesh fixture and installed firmware as the completed 5.1-symbol run: RAK4631, Heltec T096, MeshTower V2 and T1000-E fixed transmitters; Heltec V4 RX. SF10 / BW125 kHz / CR4/5, four channels spaced 1 MHz apart, 32-symbol preamble, normal SX1262 RX gain, -9 dBm chip TX setting, zero added settling and one frequency write per hop. No firmware was rebuilt or reflashed for these repeats.</p>"},{"location":"four_fixed_tx_dwell_validation/#61-symbol-run-user-stopped-incomplete-sample","title":"6.1-symbol run: user-stopped, incomplete sample","text":"<p>Started 2026-09-14 22:44:47 UTC. Dwell was 49,972 us per channel. All four stationary controls passed 100/100 again.</p> <p>The user requested stopping this run and proceeding to 7.7 symbols. The collector was interrupted only after verifying its PID, command line and owner. At the last saved checkpoint, 342/348 scored scan packets were received (98.28%), with six timeouts:</p> TX / channel Scored attempts Received Timeouts RAK4631 / 0 87 87 0 Heltec T096 / 1 87 86 1 MeshTower V2 / 2 87 85 2 T1000-E / 3 87 84 3 <p>This is not a completed 400-packet run or a validated full-run timing capture. An interrupted in-flight packet can exist beyond the last saved checkpoint; it is not scored as another success or failure. No final switch timing was collected before reboot. The raw capture remains incomplete, and the separate user-stop record documents why. All five radios were then independently verified idle, and ModemManager was restored. Gateway services stayed active; the V4 memory-soak service stayed inactive.</p> <ul> <li>Partial raw capture</li> <li>User stop record</li> <li>Verified cleanup</li> <li>Run provenance</li> </ul> <p>Partial raw capture SHA-256: <code>ad199124930da19fe56c78a4ea8280a6d94b95ef408589b19a9e165155dbf7fd</code>.</p>"},{"location":"four_fixed_tx_dwell_validation/#77-symbol-run","title":"7.7-symbol run","text":"<p>Launched 2026-09-14 22:58:14 UTC; collector ran from 22:58:15 to 23:11:45 UTC with 63,079 us visits. All four fixed-channel controls passed 100/100. The full scan completed with 395/400 received (98.75%), five timeouts and zero wrong-channel or invalid payloads. Thus 7.7 symbols did not achieve a 400/400 pass.</p> TX / channel Scanning result Timeouts Mean received RSSI (dBm) Mean received SNR (dB) RAK4631 / 0 100/100 0 -21.05 +8.14 Heltec T096 / 1 99/100 1 -4.35 +8.98 MeshTower V2 / 2 97/100 3 -44.86 +8.63 T1000-E / 3 99/100 1 -18.56 +8.26 <p>All 800 baseline/scan TX sequences were unique, all transmit calls succeeded, and every TX packet reported zero frequency and modulation configuration writes. There were zero packet-response transport replays. All four final TX lifetime checks reported 200 packets and a prepared, non-failed transmitter.</p> <p>The five timeouts occurred at scan attempts 158 (T1000-E), 184 (T096), and 200, 293, 314 (MeshTower). Each reported RX mode 1 and zero device errors. Final RX failure, RX-mode-error, cache-error and receive-error counters were zero.</p>"},{"location":"four_fixed_tx_dwell_validation/#measured-switch-and-sweep-timing","title":"Measured switch and sweep timing","text":"Hop population Count Minimum (us) Mean (us) Maximum (us) All single-pass switches 5,046 438 524.146 804 Cached modulation; no 0x8B 4,651 438 502.147 686 Post-reception modulation refresh 395 760 783.180 804 <p>Exactly 5,046 RF-frequency commands and 5,046 optimized RX resumes were counted, with one retune pass and zero second passes/detours. The 395 modulation writes match the 395 post-reception cache refreshes. This is the same cache behavior as the earlier run, not double-setting the radio. The slightly higher overall mean than the 5.1 run partly reflects a larger fraction of refresh hops.</p> <p>Across 860 measured idle cycles, the four-channel sweep averaged 254.351 ms, minimum 254.208 ms and maximum 255.482 ms. Relative to the 262.144 ms programmed preamble, that leaves 7.793 ms at the mean and 6.662 ms at the maximum. Nominal dwell was 63.079 ms; measured idle dwell averaged 63.084 ms. Packet-held visits include payload/guard time and are not comparable to idle cycles.</p> <p>The 7.7 run received three more packets than the earlier 5.1 run (395 versus 392 out of 400). This small, sequential comparison does not establish a reliable improvement or a lossless dwell threshold. The 6.1 result is partial and must not be treated as an equal-size completed comparison.</p>"},{"location":"four_fixed_tx_dwell_validation/#evidence-and-cleanup","title":"Evidence and cleanup","text":"<p>Unlike the original 5.1 run's overly strict host assertion, this collector completed normally with <code>complete: true</code> and exit code 0. Independent offline validation also passed. The same collector SHA-256 was used for both repeats: <code>cceb8a570f4aedeaf45d28b4b4590b23df3c1efd490c8e8e9cd74a23ba00024f</code>. The copied deployment/manifest files are provenance for reused firmware, not records of a new flash operation. Host options and acknowledged dwell match.</p> <ul> <li>Completed raw capture</li> <li>Validated summary</li> <li>Run provenance</li> <li>Cleanup readbacks and warnings</li> </ul> <p>Raw capture SHA-256: <code>5e3f9a80af1384c3072303428b75c8550ac42d2ac95bd1234bf92cb0aea625e8</code>.</p> <p>The cleanup wrapper retained three errors from its reboot phase: the T096 primary USB interface was temporarily missing/ambiguous, and attempts to open the MeshTower/T1000-E ports returned permission denied. Its subsequent final readbacks nevertheless succeeded for all five radios: each TX was unprepared, non-failed, packet count zero and autonomous TX disabled; RX scanning was inactive with zero channels. No further radio access or permission changes were attempted after those results returned. The wrapper's <code>verified_idle</code> flag remains false because it retains any earlier cleanup error, and the outer operation returned nonzero for that reason. These warnings happened after the complete RF sample; they are not counted as RF packet losses or silently removed from the record.</p> <p>ModemManager was restored active; gateway services remained active. The V4 memory-soak service remains inactive with test firmware installed. No firmware restore, commit, push or pull was performed. Previous raw captures are unchanged.</p>"},{"location":"four_fixed_tx_dwell_validation/#dwell-budget","title":"Dwell budget","text":"<p>One chirp at SF10/125 lasts 8.192 ms. For the experiment's nominal budget of one complete four-channel idle sweep inside 32 programmed preamble symbols:</p> <p><code>maximum dwell symbols = 32 / 4 - switching_ms / 8.192</code>.</p> <p>The 5.1-symbol run's mean switch (0.513980 ms) gives about 7.937 symbols; its maximum switch (0.801 ms) gives about 7.902 symbols, before other loop overhead. These are timing ceilings, not proven lossless dwell limits or a complete acquisition model. Near the ceiling there is little timing margin. At 7.7 symbols, four nominal dwell-plus-average-switch intervals total about 254.4 ms, versus a 262.144 ms programmed preamble.</p> <p>The host keeps the same seed and arrival-randomization rule, spanning about two nominal scan cycles; absolute arrival pauses therefore scale with dwell. The fixed-channel controls, sample counts, switching policy and firmware stay unchanged. As before, external PA/LNA paths and unrelated RF traffic mean this is a finite bench comparison, not a calibrated sensitivity or interference test.</p>"},{"location":"four_fixed_tx_single_pass_validation/","title":"Four fixed transmitters / fast single-pass receiver","text":""},{"location":"four_fixed_tx_single_pass_validation/#result","title":"Result","text":"<p>MercerMesh Pi bench run, started 2026-09-14 22:18:49 UTC (15:18:49 PDT): four physically separate, fixed-channel transmitters and the Heltec V4 receiver. The full stationary controls passed 400/400. The subsequent four-channel scan received 392/400 correctly (98%), with 8 timeouts (2%) and zero wrong-channel payloads. No RF retries were used.</p> TX / assigned channel Frequency (MHz) Fixed-RX control Scanning RX Scan mean RSSI (dBm) Scan mean SNR (dB) RAK4631 / 0 909.5 100/100 96/100 -20.69 +8.63 Heltec T096 / 1 910.5 100/100 98/100 -3.84 +8.45 Heltec MeshTower V2 / 2 911.5 100/100 100/100 -45.48 +8.41 Seeed T1000-E (LR1110) / 3 912.5 100/100 98/100 -18.27 +8.51 <p>RSSI/SNR describe received packets only. Each transmitter sent 200 unique packets across its baseline and scan. All 800 transmit calls returned success, with zero frequency or modulation commands during those packet calls. There were zero recovered/replayed USB responses in the packet records.</p>"},{"location":"four_fixed_tx_single_pass_validation/#switching-timing-and-command-evidence","title":"Switching timing and command evidence","text":"Hop population Count Minimum (us) Mean (us) Maximum (us) All single-pass switches 7,206 429 513.980 801 Cached modulation; no 0x8B 6,814 429 498.602 686 Modulation cache refresh 392 763 781.291 801 <p>The receiver recorded exactly 7,206 frequency commands and 7,206 optimized RX resumes: one frequency write and one resume per hop. Second-pass count was zero. Duplicate frequency writes, frequency/CR detours and added settling were disabled. Warm XOSC, bulk 8 MHz SPI and cached modulation were enabled.</p> <p>The average switch was 0.514 ms, but not every switch was below 0.6 ms. After each received packet, ordinary RX staging invalidates the modulation cache; the next hop refreshes it. Subsequent unchanged hops omit 0x8B. The 392 refreshes match the 392 received packets. The source path is <code>RadioLibWrapper::recvRaw()</code> -&gt; <code>startRecv()</code> / <code>startReceiveMode()</code> -&gt; <code>PhysicalLayer::startReceive()</code> -&gt; <code>CustomSX1262::stageMode()</code> -&gt; <code>SX1262ProfileSwitchState::invalidate()</code>. No production cache-invalidation behavior was changed for this test.</p> <p>Mean switch-plus-settling-instrumentation time was 515.698 us, maximum 803 us. The settling measurement averaged 1.718 us of timer/measurement overhead; the configured settling delay was zero. The idle four-channel sweep averaged 169.135 ms (maximum 170.470 ms), versus 262.144 ms for the 32-symbol preamble. Packet-held visits include reception/guard time and are not idle sweep timings. The <code>deferred</code> counter counts guard-loop deferrals, not lost packets.</p>"},{"location":"four_fixed_tx_single_pass_validation/#method-and-fixture","title":"Method and fixture","text":"<ul> <li>SF10 / 125 kHz / CR4/5; 32-symbol preamble; synthetic 16-byte CHS1 packets.</li> <li>Four channels spaced 1 MHz apart; 5.1-symbol RX visits (41,780 us).</li> <li>Each physical transmitter was configured once and remained on its assigned   frequency throughout both the controls and scanning.</li> <li>Receiver was reinitialized for each fixed-channel control and once before   the scan. All 100 control packets per transmitter were retained.</li> <li>Scan used 100 packets per channel, randomized channel order and arrival   pauses (seed 606125). Transmissions were staggered, not concurrent.</li> <li>Each expected packet had a 10-second scan timeout. Misses did not stop the   run, restart the scanner, force it onto the TX channel or trigger a retry.</li> <li>SX1262 normal RX gain was verified as register 0x94. The V4's external   KCT8103L front end remains distinct from the chip's boosted-gain setting.</li> <li>Requested TX power was -9 dBm at each radio chip. The Heltec TX boards have   external PA paths, held in TX mode by this HIL firmware; these are not   calibrated equal antenna-port powers.</li> <li>High-rate channel trace was disabled; command counters and timing remained   enabled. Gateway services remained running, so unrelated RF was not excluded.</li> </ul> Role Hardware serial / MAC Pi USB topology TX0 RAK4631 9AB3B64C641BA927 1-1.3.1 TX1 Heltec T096 651F8E496197F882 1-1.2.3 TX2 Heltec MeshTower V2 9352162A72082314 1-1.2.2 TX3 Seeed T1000-E LR1110 34A9141999729D5D 1-1.2.1 RX Heltec V4 44:1B:F6:69:CF:98 1-1.3.3 <p>Board selection checked serial plus topology, not transient tty names or CDC interface count. The RAK3401 gateway, serial 0B81C9C68D8D01B4, was excluded. The earlier local XIAO radios were not modified during this run.</p>"},{"location":"four_fixed_tx_single_pass_validation/#remaining-losses-and-interpretation","title":"Remaining losses and interpretation","text":"<p>Timeouts occurred at overall scan attempts 10, 14, 55, 65, 145, 299, 304 and 384. Thus they were not confined to startup. Each timeout reported RX mode 1 and zero device errors; TX calls returned success and still reported no configuration writes. Final RX failure, RX-mode, cache and receive-error counters were all zero.</p> <p>The wrong-channel behavior did not reproduce in this configuration. The remaining misses do not require a transmitter that retunes between packets. However, this is not a controlled A/B against the earlier XIAO setup: the RX board, TX boards/chips, antennas and geometry changed. These results do not prove that the earlier transmitter was faulty or establish the cause of the eight remaining losses.</p> <p>Several received signals were very strong, particularly the T096 at about -4 dBm. The weakest link, MeshTower V2 at about -45 dBm, passed 100/100 while scanning. That makes a controlled spacing/attenuation comparison worth considering, but this sample does not prove receiver overload. The observed 98% is a finite bench result, not a reliability guarantee or sensitivity test.</p>"},{"location":"four_fixed_tx_single_pass_validation/#capture-integrity-and-post-run-validation","title":"Capture integrity and post-run validation","text":"<p>All 400 scan probes finished and final radio telemetry was returned. The original host checker then rejected that telemetry because it incorrectly required zero modulation writes over the entire run, including post-packet RX staging. Its raw capture therefore remains <code>complete: false</code>, with final status preserved verbatim inside its error string. The normal <code>sender_final</code> collector step did not run. The raw failure record was not rewritten.</p> <p>Source review established the cache-refresh behavior above. The host checker now validates modulation writes against the measured refresh-hop count, checks that cached plus refresh hops equal total hops, and still requires single frequency writes, single fast resumes, zero added delay and the other policies. It also saves final telemetry before checking it, so future failures retain that structured record.</p> <p>Separate offline validation parsed the saved telemetry, checked the full 400-probe scan and all four 100-probe controls, verified 800 unique sequences, and checked every transmitter's packet counter from 1 through 200 and its zero-retune acknowledgments. A capture regression additionally checks that each TX/RX response ID matches its probe and every accepted payload/channel matches the assigned channel. No radio was rerun to replace the failed host assertion. The derived summary explicitly reports <code>original_collector_complete: false</code> and <code>post_run_validation_passed: true</code>.</p> <p>Evidence files:</p> <ul> <li>Immutable raw capture</li> <li>Independently validated summary</li> <li>Deployment record</li> <li>Build manifest</li> <li>Verified idle/service state</li> </ul> <p>Raw capture SHA-256: <code>42de3ac0c335b2c59f35c1cab217a01ef242c9f2e7b0010c8000a908a59232e6</code>. Derived summary SHA-256: <code>316bd551eb7306dfc576f4b88ad23e82cb1d701481d1e022067c961806d31bfe</code>.</p>"},{"location":"four_fixed_tx_single_pass_validation/#build-deployment-and-final-state","title":"Build, deployment and final state","text":"<p>Built from the dirty <code>keymindCascade</code> worktree based on <code>2b5a6f209835f0f67ed73fee78d36447a4566ce6</code>. This is not a claim that HEAD alone reproduces the images. The manifest records image and HIL-source hashes. All five PlatformIO builds succeeded and ran sequentially.</p> <p>After the host-checker correction, 25 focused unit/regression tests passed, including the preserved-capture check. <code>git diff --check</code> passed; its only warning concerned a pre-existing CRLF conversion in <code>MyMesh.cpp</code>.</p> <p>RadioLib was pinned to <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code> (7.7.1). The nRF framework was <code>d5413016</code> (1.10701.0); the ESP build used platform 6.11.0 / Arduino 2.0.17. The first three nRF targets retained S140 6.1.1 (FWID 0xB6, app base 0x26000); T1000-E retained S140 7.3.0 (FWID 0x123, app base 0x27000). nRF DFU packages were application-only, with their matching SoftDevice requirements intact. No nRF bootloader/SoftDevice replacement or cross-board override was used. Runtime FWID and application base were verified.</p> <p>V4 received the normal ESP bootloader, partition table, boot_app0 and HIL app at 0x0, 0x8000, 0xE000 and 0x10000, respectively, with esptool hash checks. No whole-flash bulk erase was issued. No backup was requested for these authorized bench deployments.</p> <p>The initial bundle's collector/deployer hashes are not the final scripts used: the actual run used <code>profile_four_tx_v2.py</code> with SHA-256 <code>b762e412636076902174c76b71961cc8ab3059c2b6de3dd3b4123bafcb06545c</code> (startup-greeting fix, original strict final assertion), and deployment used <code>profile_four_tx_deploy_v3.py</code> with SHA-256 <code>8a660788e0215e6ac1aece0a5d033521f9f376c9e51c00e760e918ebfd72cca1</code>. The current local collector includes the later validation correction; firmware images were not changed after the run. Remote evidence remains under <code>/home/mikec/hwtest/runs/four-tx-sf10-20260914</code>.</p> <p>All five radios were subsequently rebooted and independently verified idle. All TXs reported unprepared, packet count zero, no failure and autonomous TX disabled; V4 reported scanning inactive and zero hops after reboot. HIL firmware remains installed. ModemManager was restored active, gateway services were left active, and the V4 memory-soak service remains inactive because its firmware is now the bench receiver. No Pi USB hub power cycle was performed.</p> <p>No commit, push or pull was performed for this test. Unrelated worktree changes were preserved.</p>"},{"location":"full_companion_features/","title":"Full Companion: turn features on and off","text":"<p>For side-by-side Companion and infrastructure commands, see feature switches by role. MQTT and logging controls differ between these roles.</p> <p>Use the exact <code>companion_radio_full</code> image for your board. Full includes its supported transports and MOTA sending in one firmware; ordinary settings do not require rebuilding it. USB remains the normal way to update the Companion itself. WiFi/Bluetooth updates are optional, and Full does not install LoRa MOTA packages on itself.</p> <p>The Wireless Paper Full memory-sharing update keeps 350 contacts and 256 queued messages normally. During an mOTA session, 128 message slots are available while the other half holds its workspace. If more than 128 unread messages are queued, sync them with an app before starting mOTA. Disconnecting the source or turning it off returns all 256 slots. Idle WiFi mOTA listening does not borrow the queue. See the 1.17.1.5 release guide for the corrected download; the earlier <code>aa20e927</code> Wireless Paper image has 150 contacts.</p>"},{"location":"full_companion_features/#open-the-text-terminal","title":"Open the text terminal","text":"<p>Close the app or serial monitor using the USB port, then open a terminal at 115200 baud, or use the USB web console. A fresh Full Companion boot or observable USB session reset starts in ASCII text mode. If it is already in Binary Companion mode, send this line once and wait for the terminal banner:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>Run <code>help</code>, <code>board</code>, and <code>version</code> to inspect the device. On ESP32 you can alternatively open the node's LAN address and select CLI, or connect with <code>nc DEVICE_IP 5002</code>. Both use the same terminal commands as USB, including <code>import meshcore://...</code>, <code>list</code>, <code>to</code>, and <code>send</code>. Use <code>disconnect</code> to release a browser/TCP session. See the terminal guide. When finished, send <code>+++MESHCORE-TERM-STOP</code>, close the terminal, and reconnect your Companion app. These are local text commands; an app's custom-variable editor does not necessarily forward them.</p>"},{"location":"full_companion_features/#common-switches","title":"Common switches","text":"Feature Turn on Turn off When it takes effect Device power saving <code>set powersaving on</code> <code>set powersaving off</code> Immediately; saved LoRa receive power saving <code>set radio.rxps on</code> <code>set radio.rxps off</code> Saved; radio applies when available Radio chip RX boost <code>set radio.rxgain on</code> <code>set radio.rxgain off</code> Immediately; saved; supported radios only External FEM RX boost <code>set radio.fem.rxgain on</code> <code>set radio.fem.rxgain off</code> Immediately; saved; controllable FEM only External FEM TX gain <code>set radio.fem.txgain on</code> <code>set radio.fem.txgain off</code> Immediately; saved; controllable PA only ESP32 USB packet/debug logging For 1.17.1.5: <code>set powersaving off</code>, then <code>set usb.logging on</code> <code>set usb.logging off</code> Immediately; saved; logging owns the USB terminal nRF52 separate USB logging port <code>set usb.logging on reboot</code> <code>set usb.logging off reboot</code> Saves and reboots to add/remove the second USB port ESP32 browser settings <code>set webui on</code> <code>set webui off</code> Saved; starts/stops WebConfig ESP32 temporary setup portal <code>start webconfig ap</code> <code>stop webconfig</code> This session; opens a setup network/QR where available ESP32 WiFi firmware uploader <code>start ota</code> or <code>start ota ap</code> <code>stop ota</code> This session; only usable with two application slots Temporary MOTA radio window <code>tempradio 910.525,250,5,5,120</code> <code>normalradio</code> Bounded window; saved normal settings return afterward <p>Check a saved switch with the corresponding <code>get</code> command, for example <code>get usb.logging</code>, <code>get radio.rxps</code>, or <code>get webui</code>. Use <code>get powersaving</code> to inspect device power saving. Fresh installations enable device power saving and leave USB logging off. Existing saved preferences take precedence.</p> <p>For an ESP32 1.17.1.5 USB logging session, use this sequence in the text terminal:</p> <pre><code>set powersaving off\nset usb.logging on\n</code></pre> <p>The power-saving step is the documented USB-session workaround for this release. It is saved separately; <code>set usb.logging off</code> does not restore power saving. nRF52 does not need the ESP32 workaround. WiFi-only MQTT logging does not need this USB step; see logging by role.</p> <p>ESP32 logging and Binary Companion share one USB port. After turning logging off, return to Binary Companion with <code>+++MESHCORE-TERM-STOP</code>. nRF52 keeps its optional logging port separate from its primary USB port and BLE connection. See the USB switching guide.</p>"},{"location":"full_companion_features/#wifi-bluetooth-gps-and-mqtt","title":"WiFi, Bluetooth, GPS, and MQTT","text":"<p>On ESP32, configure WiFi through the setup portal or these commands:</p> <pre><code>set wifi.ssid MyNetwork\nset wifi.pwd my-password\nget wifi.status\n</code></pre> <p>Credentials are saved. A credential change schedules a reconnect; a TCP terminal will disconnect. The WiFi switch on supported device displays or their assigned WiFi button controls the Companion WiFi services. Stopping WebConfig alone stops its browser service, while the Companion's TCP and MOTA services can remain available.</p> <p>WiFi modem sleep is independent of device power saving. Use <code>set wifi.powersave min</code> for normal BLE/WiFi coexistence; inspect the effective state with <code>get wifi.powersave</code>. <code>max</code> is available only where the firmware's radio coexistence policy permits it.</p> <p>Most Full Companions provide BLE alongside their other transports. There is no universal <code>set bluetooth off</code> command. SenseCAP Indicator selects one secondary wireless transport per boot:</p> <pre><code>set companion.transport wifi\nreboot\n</code></pre> <p>Use <code>set companion.transport ble</code> followed by <code>reboot</code> to select Bluetooth instead. USB stays available. The ESP-NOW layout keeps its primary ESP-NOW mesh active in either mode.</p> <p>For GPS-equipped boards, use <code>get gps</code>, <code>set gps on</code>, and <code>set gps off</code>. The Companion app's <code>gps=1</code> / <code>gps=0</code> custom setting controls the same GPS. Only boards with a compiled GPS provider expose this setting. Sharing location with contacts is a separate setting.</p> <p>When the exact Full image includes MQTT, use WebConfig's MQTT cards or the same CLI settings used by infrastructure, such as <code>set mqtt1.preset custom</code> and <code>set mqtt1.server broker.example.com</code>. <code>set mqtt.enabled on|off</code> controls MQTT without erasing the configured slots; check <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, and <code>get mqtt.status</code>. The MQTT tab's Enable MQTT checkbox controls the same saved switch. <code>set logging.output off|usb|wifi|both</code> selects USB and MQTT outputs together. Status, packets, raw, receive, and transmit switches control their individual publications. Builds without MQTT omit these controls. There is no need for a separate logging or WiFi-MQTT Companion image when that feature is included in Full.</p>"},{"location":"full_companion_features/#send-mota-from-any-full-companion","title":"Send MOTA from any Full Companion","text":"<p>Place valid, destination-specific <code>.mota</code> files in a host directory. Set the source, destination, controller, and required relays to the same bounded temporary radio tuple. For USA Cascade on LoRa hardware:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>On the computer connected to the Full Companion, run:</p> <pre><code>motatool serve --serial /dev/ttyACM0 --dir ./motas -v\n</code></pre> <p>This works on both ESP32 and nRF52 Full. Close the text terminal first. <code>motatool</code> automatically sends <code>ota folder on</code> and owns USB while serving. Stop the host tool to detach the source; use <code>normalradio</code> afterward to return early, or let the window expire. A <code>.bin</code>, <code>.uf2</code>, or DFU <code>.zip</code> is not itself a <code>.mota</code>; use motatool to prepare the package for the exact destination firmware and hardware.</p> <p>ESP32 also accepts a host over WiFi:</p> <pre><code>motatool serve --tcp DEVICE_IP:5001 --dir ./motas -v\n</code></pre> <p>nRF52 also accepts an authenticated Bluetooth host:</p> <pre><code>python3 tools/ble_mota/ble_mota_seeder.py \\\n  --device MeshCore-MyCompanion --dir ./motas \\\n  --local 'tempradio 910.525,250,5,5,120'\n</code></pre> <p>Use one MOTA source transport at a time. See the complete MOTA instructions for pairing, remote destination commands, and automation. ESP-NOW hardware uses its ESP-NOW primary radio rather than transmitting LoRa.</p>"},{"location":"full_companion_features/#update-the-companion-itself","title":"Update the Companion itself","text":"<p>USB is supported for every Full Companion. Use the exact board's UF2/DFU package or ESP32 image and the normal flasher. Preserve the target's existing partition layout unless deliberately performing a documented USB migration.</p> <p>For ESP32 with two application slots, <code>start ota</code> returns the WiFi uploader URL, normally <code>http://DEVICE_IP:8080/update</code>. <code>start ota ap</code> explicitly opens <code>MeshCore-OTA</code>; join it and use the returned URL. Upload the exact board's application <code>.bin</code>. The device reboots when the upload succeeds. Use <code>stop ota</code> to close an unused uploader. Port 8080 keeps WebConfig on port 80 available. Use a trusted local network or a temporary setup network.</p> <p>The 4 MB Full layouts and T-Beam 1W Full use a single application slot and require USB; the command reports that limitation. The artifact's <code>.capabilities.json</code> lists verified <code>ota_update_methods</code> when a wireless self-update path is usable.</p> <p>nRF52 Full exposes Bluetooth DFU to paired clients. Use the matching application DFU <code>.zip</code> with a compatible Nordic/Adafruit Legacy DFU client and the board's matching BLE-DFU-capable bootloader/SoftDevice. USB remains the fallback when the installed bootloader does not support that procedure. Bluetooth DFU updates the Companion; the separate Bluetooth MOTA source service feeds packages to other mesh nodes.</p> <p>For OTAFIX installations, use the exact board/storage profile from OTAFIX 2.4.6. It includes the Bluetooth reconnect fix from 2.4.5. Its release notes cover upgrades from older bootloaders, including the special UF2-drive precautions for version 2.4.3. The new 64 KiB retained-RAM staging feature applies to qualified internal-flash nRF52840 receivers; Full Companions continue to serve host-supplied packages without needing that receiver storage layout.</p>"},{"location":"full_companion_usb_switcher/","title":"Companion USB CLI and binary switcher","text":"<p>USB Companion uses one primary USB serial interface for two incompatible wire formats:</p> <ul> <li>a human-readable ASCII command line;</li> <li>the framed Binary Companion protocol used by MeshCore apps and <code>meshcli</code>.</li> </ul> <p>The primary interface starts in the ASCII terminal after each boot and returns to ASCII after a USB session reset that the hardware can observe. A Binary Companion client does not need to send a special mode command: its first valid frame automatically hands the interface to the binary parser.</p> <p>Current source keeps the default terminal quiet until the host sends ASCII input. Press Enter or type a command to see the banner. This prevents the ASCII <code>&gt;</code> prompt from being mistaken for the beginning of an app's first binary response. See USB client compatibility validation for the tested firmware and release status.</p> <p>These mode controls apply to Full and ordinary USB Companion builds. The explicit <code>+++MESHCORE-TERM-START</code> and <code>+++MESHCORE-TERM-STOP</code> controls remain available, including for older firmware. See the Terminal Chat CLI guide.</p>"},{"location":"full_companion_usb_switcher/#wire-formats","title":"Wire formats","text":"<p>Host-to-device Binary Companion frames use this layout:</p> <pre><code>'&lt;'  length-low  length-high  payload[length]\n</code></pre> <p>Device-to-host frames use the same little-endian length with a different marker:</p> <pre><code>'&gt;'  length-low  length-high  payload[length]\n</code></pre> <p>For example, a representative two-byte device query is:</p> <pre><code>3C 02 00 16 03\n</code></pre> <p>The ASCII terminal is line-oriented and accepts commands such as:</p> <pre><code>get radio.cad\nset display.rotation 90\nreboot\n</code></pre> <p>Changing the configured baud rate does not select a mode. Use 115200 for compatibility even though native USB CDC hardware does not use UART timing.</p>"},{"location":"full_companion_usb_switcher/#state-transitions","title":"State transitions","text":"<pre><code>                         complete '&lt;' frame\n                 +--------------------------------+\n                 |                                v\nboot ------&gt; ASCII terminal                  Binary Companion\n                 ^                                |\n                 |                                | +++MESHCORE-TERM-START\n                 | incomplete '&lt;' probe           |\n                 | (one-second timeout)            |\n                 +--------------------------------+\n\nASCII terminal -- +++MESHCORE-TERM-STOP ------&gt; Binary Companion\nany mode ------- observable USB session reset ---&gt; ASCII terminal\nESP32 logging terminal -- usb.logging off -----&gt; ASCII terminal\nany mode ------- reboot ------------------------&gt; ASCII terminal\n</code></pre> <p>Serial mOTA and single-TTY logging add exclusive ownership states described below. BLE, WiFi, Ethernet, and hardware-serial Companion transports are not switched; they remain binary.</p>"},{"location":"full_companion_usb_switcher/#how-automatic-detection-works","title":"How automatic detection works","text":"<ol> <li>Companion initializes the normal USB Binary Companion interface, then    gives its primary stream to the ASCII terminal before normal loop service    begins.</li> <li>While the prompt has no buffered input, the terminal peeks at the next byte.    It does not remove that byte.</li> <li>If the byte is <code>&lt;</code>, the terminal temporarily releases the stream and enables    the existing <code>ArduinoSerialInterface</code> frame parser.</li> <li>The parser consumes the original <code>&lt;</code>, the two-byte length, and the payload.    There is no second parser and no copied or synthetic frame.</li> <li>A monotonically increasing completed-frame counter confirms that the parser    received a complete frame. The interface then remains in Binary Companion    mode.</li> <li>If no complete frame arrives within one second, the parser state is reset    and the ASCII terminal prints a new banner and prompt.</li> </ol> <p>The switcher checks framing, not client identity. Any syntactically complete Binary Companion frame confirms binary mode; it does not require the first command to be <code>CMD_APP_START</code> or <code>CMD_DEVICE_QUERY</code>. Normal command validation still occurs after the frame parser returns the payload.</p> <p>The empty-prompt requirement prevents a literal <code>&lt;</code> in the middle of a command from silently changing modes. A literal <code>&lt;</code> typed as the first character does start a probe, but the terminal returns after the one-second timeout if no binary header and payload follow.</p>"},{"location":"full_companion_usb_switcher/#manual-controls","title":"Manual controls","text":"<p>The original controls remain available.</p> <p>From Binary Companion, send this exact unframed line while the parser is idle:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>Terminate it with CR or LF. The binary parser accepts control tokens only as complete delimiter-bounded lines; prefixes, suffixes, and partial tokens are ignored.</p> <p>From the ASCII terminal, send this exact sequence to return to binary mode:</p> <pre><code>+++MESHCORE-TERM-STOP\n</code></pre> <p>The stop sequence takes effect as soon as its last byte arrives in ASCII mode. The start sequence is recognized only as a completed line while the binary parser is idle and is not examined inside a length-prefixed frame.</p> <p><code>meshcli</code> can normally connect directly after boot:</p> <pre><code>meshcli -s /dev/ttyACM0 -b 115200 ver\n</code></pre> <p>An explicit terminal start token is still useful when the device is already in binary mode:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre>"},{"location":"full_companion_usb_switcher/#logging-and-mota-ownership","title":"Logging and mOTA ownership","text":"<p>The switcher never attempts to mix ASCII, framed Companion traffic, or binary mOTA traffic on the same stream.</p> Situation Primary USB behavior USB Companion after boot or observable session reset ASCII; a complete <code>&lt;</code> frame switches to Binary Companion nRF52 logging enabled Primary interface still follows the switcher; logs use the optional second interface ESP32 logging enabled at boot Logging terminal owns the only USB TTY; automatic <code>&lt;</code> detection is disabled nRF52 USB serial mOTA active mOTA owns primary USB; ASCII and Binary Companion are unavailable there BLE/WiFi/Ethernet/hardware serial Always Binary Companion and unaffected by the USB mode <p>On RAK4631 and other nRF52 Full Companions, ASCII and Binary Companion both use the primary interface (<code>*-if00</code> on Linux). The optional <code>*-if02</code> interface is for logging. <code>OK - Binary mode</code> acknowledges a mode change on the same primary port; it does not move the connection to the logging port.</p> <p>On every ESP32 Full Companion, use <code>set usb.logging off</code> in its logging terminal before trying to use USB with an app. That command stops logging and returns to the ordinary ASCII terminal; it does not select Binary Companion. The app's first valid framed probe can perform the normal automatic switch, or a human can send <code>+++MESHCORE-TERM-STOP</code> first. The framed/binary Companion parser is disabled while logging owns that TTY. BLE and WiFi Companion transports remain available while USB is logging. ESP32 Full builds use the Arduino-ESP32 2.x base where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but follow the same one-TTY policy. No ESP32 Full build enumerates a second CDC interface.</p> <p>With logging enabled on a shared port, the stop token is rejected with <code>ERROR: set usb.logging off before Binary mode</code>. Turn logging off first; a successful binary-mode acknowledgement must not immediately revert to logging.</p> <p>On nRF52, serial <code>motatool</code> is also text-first. Its exact initial <code>ota folder on</code> line is recognized in either startup ASCII or Binary Companion mode. From ASCII, the firmware leaves terminal mode and directly enters exclusive mOTA ownership; from binary, the idle frame parser recognizes the same control sequence. The following mOTA request/reply frames therefore cannot be consumed by the ASCII line editor. <code>motatool serve --serial</code> can be the first client after boot and does not require a terminal token or disconnect workaround.</p> <p>Only the exact completed line selects mOTA from ASCII. Extra arguments, leading/trailing whitespace, or a partial line remain ordinary terminal input.</p>"},{"location":"full_companion_usb_switcher/#shortcomings-and-edge-cases","title":"Shortcomings and edge cases","text":"<p>This mechanism is deliberately small and deterministic, but it is not a full protocol negotiation layer.</p>"},{"location":"full_companion_usb_switcher/#session-detection-depends-on-the-usb-hardware","title":"Session detection depends on the USB hardware","text":"<p>After the first complete binary frame, the device stays in Binary Companion mode for that session. Native USB with DTR/session events restores ASCII when the host closes or resets the connection. Old input, queued output and mOTA ownership are cleared before selecting the default for the next session.</p> <p>Some clients, including <code>meshcore</code> 2.3.10 used by stock MeshCLI, deliberately deassert DTR. The nRF52 primary interface also accepts actual incoming USB data as evidence of a client in the current session. Closing, changing line coding, or resetting USB invalidates that evidence. The dedicated logging interface continues to require its own connected reader.</p> <p>ESP32 hardware USB Serial/JTAG reports bus reset and physical host loss, but cannot reliably report a terminal program closing its handle. A USB-to-UART bridge also usually cannot report that close. On those ports, use the terminal start token to return from Binary mode without rebooting. Idle time alone never changes the selected protocol.</p> <p>An active network terminal temporarily delays restoring the USB ASCII prompt. If a fresh USB app sends a complete binary frame during that delay, its Binary mode remains selected when the network terminal closes.</p>"},{"location":"full_companion_usb_switcher/#detection-works-only-at-an-empty-prompt","title":"Detection works only at an empty prompt","text":"<p>If part of an ASCII command is already buffered, an incoming <code>&lt;</code> is treated as ordinary terminal input. Clear or submit the line before starting a Binary Companion client. Only one process should have the serial port open.</p>"},{"location":"full_companion_usb_switcher/#the-first-frame-has-a-one-second-deadline","title":"The first frame has a one-second deadline","text":"<p>The complete marker, length, and payload must arrive within the probe window. This is generous for local USB but may reject a heavily buffered serial proxy, a debugger that pauses the MCU, or a tool that writes the header and body with a long delay. A timed-out client can retry after the ASCII banner appears.</p>"},{"location":"full_companion_usb_switcher/#framing-confirmation-is-not-authentication","title":"Framing confirmation is not authentication","text":"<p>Any complete length-prefixed frame selects binary mode, even if its command is unknown or malformed at the application layer. This is safe for stream separation but means a random complete frame can leave the device in binary mode until an observable USB session reset or a manual switch back.</p>"},{"location":"full_companion_usb_switcher/#the-default-terminal-waits-for-input","title":"The default terminal waits for input","text":"<p>The firmware enters ASCII mode during boot but suppresses the banner and unsolicited terminal events until ASCII input identifies a terminal client. Send Enter or a harmless <code>get</code> command to display the banner. A binary client instead gets a clean first response. Older builds that immediately printed <code>&gt;</code> could consume the first binary response's marker as part of a bogus frame length; scanning past leading text alone did not reliably recover that reply.</p>"},{"location":"full_companion_usb_switcher/#text-and-binary-output-cannot-be-interleaved","title":"Text and binary output cannot be interleaved","text":"<p>Primary USB suppresses Binary Companion output while the terminal owns the stream. Packet/debug logging must use its dedicated CDC interface or the exclusive single-TTY logging mode. Writing diagnostic text directly to the primary binary stream will corrupt clients regardless of the switcher.</p>"},{"location":"full_companion_usb_switcher/#a-literal-leading-briefly-hides-the-prompt","title":"A literal leading <code>&lt;</code> briefly hides the prompt","text":"<p>Typing <code>&lt;</code> as the first terminal character begins a binary probe. With no complete frame, the prompt returns after one second and the banner is printed again. There is currently no escape syntax for entering a literal leading <code>&lt;</code>; prefix it with another character if it is needed as command text.</p>"},{"location":"full_companion_usb_switcher/#troubleshooting","title":"Troubleshooting","text":"<p>If <code>meshcli</code> cannot connect:</p> <ol> <li>close every terminal or logging reader using the primary interface;</li> <li>on ESP32, confirm that saved USB logging is off;</li> <li>reboot and let <code>meshcli</code> be the first process to open the data interface;</li> <li>use the stable <code>/dev/serial/by-id/*-if00</code> path on Linux when available;</li> <li>if a prompt appears after one second, the client's first frame was not    completed inside the probe window.</li> </ol> <p>If an ASCII terminal shows no banner, press Enter and issue a harmless query such as <code>get radio.cad</code>. If binary bytes appear, send the exact terminal start token or reboot.</p> <p>The switch policy is implemented in <code>UsbAsciiBinarySwitch.h</code>, with stream ownership in <code>main.cpp</code> and framing in <code>ArduinoSerialInterface.cpp</code>.</p>"},{"location":"full_usb_logging_validation/","title":"Full USB logging repair \u2014 1.17.1.6","text":"<p>Audit date: 2026-09-13. Release firmware source: <code>306feebe6d648a247f925894f876be9d747fc8d2</code>.</p> <p>The original Station G2 Full Repeater and Full Room Server images omitted USB packet logging. Both inherited <code>-UMESH_PACKET_LOGGING</code> from their ordinary MQTT observer recipes. Full added <code>-DMESH_PACKET_LOGGING=1</code>, but PlatformIO's <code>ProcessFlags</code> moves undefines after defines in the compiler command. The resulting image compiled successfully with its packet logger removed.</p> <p>The previous release gate checked OTA and other features without requiring USB logging in Full infrastructure. An old passing manifest could also be reused by <code>--resume</code> without the new logging evidence.</p>"},{"location":"full_usb_logging_validation/#published-image-audit","title":"Published-image audit","text":"<p>Each downloaded/cached artifact was matched to GitHub's published SHA-256. The check inspected application bytes, including the application inside nRF52 DFU ZIPs. It required the packet-log formatter and USB logging controls.</p> Release group Application images Missing USB packet logging ESP32 Full infrastructure/utility 157 2 ESP32 Full Companion 52 0 nRF52 Full Companion 43 0 Total 252 2 <p>Affected targets:</p> <ul> <li><code>Station_G2_repeater_observer_mqtt</code></li> <li><code>Station_G2_room_server_observer_mqtt</code></li> </ul> <p>V4/R8 Full builds and Station G2's Full ESP-NOW bridge passed. This audit does not count ordinary MQTT profiles that intentionally omit USB logging as broken. Artifact inspection proves compiled support, not hardware operation on every board.</p>"},{"location":"full_usb_logging_validation/#fix-and-regression-coverage","title":"Fix and regression coverage","text":"<ul> <li>Full builds that require logging remove inherited disables of   <code>MESH_PACKET_LOGGING</code> before PlatformIO parses flags. Other macros and   explicit logging-off profiles retain their policy.</li> <li>Full capability checks require the packet logger and USB controls in the   packaged application. Combined USB/WiFi profiles additionally require   the <code>logging.output</code> setter. ELF symbols or debug text cannot satisfy these   checks.</li> <li>Resumed builds must have passing application evidence for the current   logging contract, along with the existing artifact hashes and RAM checks.</li> <li>CI runs the flag, real PlatformIO/compiler, artifact, resume, and build-profile   regression suites.</li> </ul> <p>Focused verification (after installing PlatformIO and its tool-scons package):</p> <pre><code>python3 -B test/test_full_build_flag_dedup.py\npython3 -B test/test_full_logging_compile.py\npython3 -B test/test_firmware_capabilities.py\npython3 -B test/test_full_logging_resume.py\nbash test/test_build_profiles.sh\npython3 -B test/test_cascade_release_package.py\n</code></pre> <p>Both Station G2 profiles were rebuilt through <code>build.sh --full</code> with the original observer recipes, including their inherited logging undefines. They passed the new application checks, runtime RAM budgets, and both OTA slot size checks. The new checker rejects both original published images.</p> <p>On the Bellevue Station G2, the corrected Full repeater implementation also passed serial CLI and passive traffic checks: four RX and two TX packet log lines were captured. Its active temporary profile retained preamble 120 and the original schedule end time; the Pi relay services were restored.</p> <p>Corrected application SHA-256:</p> <pre><code>Repeater:    81a0a2926d4e567c069d0b10f316047881bcedce062afaa42119dddb2baadf23\nRoom Server: 7ee81f1cb65fc274bd363397c3c80ce9006d575efae50fe952c8ca246613a18c\n</code></pre>"},{"location":"gps_tracking/","title":"GPS Tracking","text":"<p>This document describes how GPS telemetry works for companion/client nodes and sensor nodes.</p>"},{"location":"gps_tracking/#scope","title":"Scope","text":"<p>GPS tracking uses the existing CayenneLPP GPS telemetry field. It does not add a new phone app protocol field.</p> <p>The GPS telemetry value contains latitude, longitude, and altitude. Speed, heading, and freshness are not sent as separate telemetry fields.</p> <p>If the firmware does not have a valid fresh GPS cache, it omits the GPS field from telemetry. This is intentional: stale or missing fixes are not reported as zero coordinates.</p>"},{"location":"gps_tracking/#freshness","title":"Freshness","text":"<p>GPS telemetry is cached separately from advert location.</p> <p>The cache behavior is:</p> <ul> <li>Refresh the cached GPS value every 2 hours only when at least one contact or   ACL client can receive location telemetry.</li> <li>Try for up to 15 minutes during a refresh.</li> <li>If the position stays within about 100 meters for 30 seconds, cache a weighted   average of the stable fixes, with newer fixes weighted more heavily.</li> <li>If the position moves outside that 100 meter circle during acquisition, cache   the latest valid fix.</li> <li>Omit GPS from telemetry if there is no fix or if the cached fix is more than   12 hours old.</li> </ul> <p>When a telemetry request asks for location, GPS is normally kept on for 2 hours after the latest location request. During that hold window, later location telemetry requests can use fresh GPS data as soon as valid fixes are available.</p> <p>If GPS is manually enabled, it stays on and valid fixes continue to update the cache.</p> <p>If no contact or ACL client can receive location telemetry, the scheduled 2-hour refresh does not run. A real location telemetry request can still turn GPS on, and manual GPS-on still keeps the cache updated.</p>"},{"location":"gps_tracking/#repeater-nodes","title":"Repeater Nodes","text":"<p>Repeaters use a shorter on-demand policy when GPS is manually off. An authorized location-telemetry request wakes the receiver only when its cached position is stale. The first valid fix is cached and the receiver immediately powers down; the next request can return that fix without another wake. <code>gps off</code> also cancels an acquisition already in progress. An acquisition that never obtains a fix retains the normal 15-minute safety timeout.</p> <p>When GPS and device power saving are both enabled, a repeater wakes GPS for up to 10 minutes to obtain a valid time and then sleeps it for seven days. A valid GPS time may correct the RTC either forward or backward. With device power saving off, an enabled GPS remains active and refreshes the RTC every 30 minutes.</p>"},{"location":"gps_tracking/#companionclient-nodes","title":"Companion/Client Nodes","text":"<p>Companion/client telemetry uses the existing companion telemetry permission system:</p> <ul> <li>base telemetry</li> <li>location telemetry</li> <li>environment telemetry</li> </ul> <p>Location telemetry is sent only when the requester's effective telemetry permissions include location. Those permissions are derived from the companion telemetry mode settings and contact flags.</p> <p>No new phone app behavior is required. Existing clients see the existing GPS telemetry field when it is present.</p> <p>The scheduled GPS cache refresh runs only when at least one stored contact has effective location telemetry access:</p> <ul> <li><code>location: allow all</code> with at least one stored contact</li> <li><code>location: allow flags</code> with at least one stored contact whose flags include   location</li> </ul>"},{"location":"gps_tracking/#sensor-nodes","title":"Sensor Nodes","text":"<p>Sensor telemetry access is controlled by:</p> <pre><code>get telemetry.access\nset telemetry.access all\nset telemetry.access acl\n</code></pre> <p><code>all</code> is the default and matches the previous sensor telemetry behavior. A request that reaches the normal sensor telemetry request path can receive the requested telemetry fields, including GPS, subject to the request mask and GPS freshness rules.</p> <p><code>acl</code> gates telemetry through the sensor ACL. A requester with read-only or higher permissions receives the existing telemetry set, including GPS. Guest or unknown requesters receive no telemetry fields.</p> <p>The scheduled GPS cache refresh follows the same access setting:</p> <ul> <li><code>all</code>: runs only when at least one ACL client exists</li> <li><code>acl</code>: runs only when at least one ACL client is read-only or higher</li> </ul> <p>Use the existing ACL command to grant access:</p> <pre><code>setperm &lt;pubkey&gt; 1\n</code></pre> <p>Permission values:</p> <ul> <li><code>1</code>: read-only, suitable for telemetry access</li> <li><code>2</code>: read-write</li> <li><code>3</code>: admin</li> </ul>"},{"location":"gps_tracking/#advert-location","title":"Advert Location","text":"<p>Advert location is separate from telemetry GPS. The advert policy is controlled with:</p> <pre><code>gps advert\ngps advert none\ngps advert share\ngps advert prefs\n</code></pre> <p>Policies:</p> <ul> <li><code>none</code>: do not include location in adverts</li> <li><code>share</code>: use the live/shared sensor manager location</li> <li><code>prefs</code>: use the stored node latitude and longitude preferences</li> </ul> <p><code>prefs</code> is the first-boot default for every repeater, room-server, and sensor build. Firmware updates retain an explicitly saved policy from the existing preferences filesystem.</p> <p>Telemetry GPS can be fresh while advert location is fixed or disabled, depending on this policy.</p>"},{"location":"gps_tracking/#recommended-setup","title":"Recommended Setup","text":"<p>For private sensor tracking:</p> <pre><code>set telemetry.access acl\nsetperm &lt;owner_pubkey&gt; 3\nsetperm &lt;trusted_pubkey&gt; 1\n</code></pre> <p>For compatibility with the older sensor behavior:</p> <pre><code>set telemetry.access all\n</code></pre> <p>For GPS telemetry behavior, leave the phone app unchanged. The firmware omits GPS when it is stale or missing and sends the existing GPS telemetry field when fresh data is available.</p>"},{"location":"halo_keymind_settings/","title":"Halo and Keymind Branch Settings","text":"<p>This file covers only CLI settings and helper commands added by the Halo or Keymind branches. Use CLI commands for the general infrastructure CLI. For MQTT, logging, and former variant controls, use feature switches by role; Full Companion uses different controls for some of these settings. See Repeater Flood Filtering and Moderation for a focused filter setup and troubleshooting guide.</p>"},{"location":"halo_keymind_settings/#quick-start","title":"Quick Start","text":"<pre><code>set retry.preset rooftop\nset direct.retry.heard on\nset flood.retry.advert off\nset flood.retry.bridge off\nset flood.retry.prefixes none\nset flood.retry.ignore none\n</code></pre> <p>Then verify:</p> <pre><code>get retry.preset\nget direct.retry.heard\nget flood.retry.advert\nget flood.retry.prefixes\nget flood.retry.ignore\n</code></pre> <p>Use prefixes from the analyzer or neighbors list or <code>get recent.repeater</code> after the repeater has been online for a few hours.</p>"},{"location":"halo_keymind_settings/#common-examples","title":"Common Examples","text":"<p>Disable retrying advert packets:</p> <pre><code>set flood.retry.advert off\nget flood.retry.advert\n</code></pre> <p>Ignore a repeater as a successful flood retry echo: Use this if you have a car repeater and a house repeater; have the house ignore the car.</p> <pre><code>set flood.retry.ignore 71CE82,C7618C\nget flood.retry.ignore\n</code></pre> <p>Only accept specific downstream relays as flood retry success: You're in a hole and need to hit a mountain top repeater to get out; keep trying till one you see one of these send out your packet.</p> <pre><code>set flood.retry.prefixes A58296,860CCA,425E5C\nget flood.retry.prefixes\n</code></pre> <p>Bridge two groups of repeaters:</p> <pre><code>set flood.retry.bridge on\nset flood.retry.bucket 1 71CE82,C7618C\nset flood.retry.bucket 2 BEEBB0,425E5C\nget flood.retry.bucket.1\nget flood.retry.bucket.2\n</code></pre> <p>Return to simple non-bridge flood retry:</p> <pre><code>set flood.retry.bridge off\nset flood.retry.prefixes none\nset flood.retry.ignore none\n</code></pre>"},{"location":"halo_keymind_settings/#added-settings","title":"Added Settings","text":"Setting What it does How to use Example <code>telemetry.temp</code>, <code>telemetry.volt</code>, <code>telemetry.volt.i2c</code>, <code>telemetry.gps</code> Repeater and room builds record 30-minute MCU temperature and battery samples for seven days. Detected INA voltage channels retain four days at 0.02 V resolution through 655.34 V; all-zero channels are omitted as disconnected. GPS-capable builds retain GPS separately. Repeater <code>telemetry.tx</code> sends temperature, battery, and per-channel I2C RAW_CUSTOM packets over the shared <code>data.tx</code> path on a persistent 1-30 day schedule or immediately for testing; automatic transmission is off by default and its retained cadence starts at two days. <code>data.tx</code> defaults to zero-hop direct plus automatic region selection without enabling any producer. GPS is never included. History resets on reboot. <code>get/set data.tx path|region</code>, <code>get telemetry.temp [page]</code>, <code>get telemetry.volt [page]</code>, <code>get telemetry.volt.i2c [channel [page]]</code>, <code>get telemetry.gps [page]</code>, <code>set telemetry.gps &lt;1-30&gt;</code>, <code>get telemetry.tx</code>, <code>set telemetry.tx schedule &lt;off|1-30d&gt;</code>, <code>send telemetry.tx now</code> <code>get data.tx</code> <code>battery.alert</code> Sends opt-in, region-scoped low-battery warnings to <code>#repeaters</code> after 30 minutes of uptime. <code>get battery.alert</code>, <code>get battery.alert.region</code>, <code>set battery.alert on [region]</code>, <code>set battery.alert off</code> <code>set battery.alert on sea</code> <code>battery.alert.low</code> Warning threshold percentage. Must be greater than <code>battery.alert.critical</code>. <code>get battery.alert.low</code>, <code>set battery.alert.low &lt;1-100&gt;</code> <code>set battery.alert.low 20</code> <code>battery.alert.critical</code> Critical threshold percentage. Critical and warning alerts use the same 12-hour resend cooldown. <code>get battery.alert.critical</code>, <code>set battery.alert.critical &lt;0-99&gt;</code> <code>set battery.alert.critical 10</code> <code>recent.repeater</code> Shows, searches, seeds, or clears the recent repeater prefix/SNR table used by direct retry and bridge freshness checks. Search results include the last-recorded age. Entries older than 24 hours are removed by a three-hour sweep. <code>get recent.repeater [page]</code>, <code>get recent.repeaters search &lt;2|4|6 hex&gt; [page]</code>, <code>set recent.repeater &lt;prefix&gt; &lt;snr_db&gt;</code>, <code>clear recent.repeater</code> <code>get recent.repeaters search A1B2</code> <code>flood.channel.data</code> Compatibility view for a visible FPF7 <code>type=grp_data</code> drop row on generalized repeaters. <code>off</code> creates the row and <code>on</code> removes it; compact FPF6 builds retain the legacy gate. Use an authenticated <code>channel=</code> row when only selected channels should be blocked. <code>get flood.channel.data</code>, <code>set flood.channel.data on/off</code> <code>set flood.channel.data off</code> <code>flood.channel.data.hops</code> Sets the compatibility row's hop range: <code>all</code> maps to <code>hops=all</code>; <code>1</code>-<code>7</code> repeats through that hop count and maps to <code>hops=N+1+</code>. <code>get flood.channel.data.hops</code>, <code>set flood.channel.data.hops &lt;all|1-7&gt;</code> <code>set flood.channel.data.hops 7</code> <code>flood.channel.scope</code> FPF7 rewrite-phase rows that add a transport scope to received unscoped floods or replace the scope of already-scoped floods. A bare target uses an existing flood-allowed region; <code>scope=&lt;name&gt;</code> derives a public hashtag target directly without creating a region, exactly like <code>flood.filter scope=</code>. By default, a changed packet bypasses inbound <code>rxdelay</code> and is forwarded at the highest outbound queue priority with zero initial <code>txdelay</code>, so the selected scope can win at the next hop. <code>tx=slow</code> uses an effective inbound <code>rxdelay</code> base of <code>max(2, configured rxdelay * 2)</code>, retains normal queue priority, and forces the maximum <code>txdelay</code> factor of <code>2.0</code>; its actual randomized transmit delay ranges from zero through ten packet airtimes. <code>path=blacklist</code> and <code>path=bucket:&lt;1-6&gt;</code> make a row path-qualified; bridge buckets remain usable while bridge retry is off. An already-matching scope is a no-op. Exact channel keys beat <code>txt:*</code>; path-qualified rows beat the ordinary channel fallback. <code>login:*</code> covers the remote-login family, and <code>other:*</code> covers every remaining flood type, including flood-form TRACE and OTA. Direct traceroute remains outside the flood table. Generalized builds commit these rows with the forward phase and blacklist; compact FPF6 builds retain separate storage. ACL permission <code>4</code> can manage the table. <code>get flood.channel.scope[.n]</code>, <code>set flood.channel.scope[.n] &lt;channel|txt:*|login:*|other:*&gt; &lt;region|scope=name&gt; [path=blacklist|path=bucket:1-6] [tx=slow]</code>, <code>del flood.channel.scope.&lt;n&gt;|all</code> <code>set flood.channel.scope #rgdata scope=BlackHole86</code> <code>flood.channel.scope.require</code> Switches group-channel region enforcement to opt-in when the table has entries. Listed authenticated <code>GRP_TXT</code>/<code>GRP_DATA</code> channels must arrive already scoped to a locally allowed region; unscoped, unknown, or denied incoming scopes are dropped before any rewrite can rescue them. Unlisted group channels bypass only the region gate and retain all other forwarding controls. An empty table preserves global region behavior; non-channel payloads are unchanged. ACL permission <code>4</code> can manage the table. <code>get flood.channel.scope.require[.n]</code>, <code>set flood.channel.scope.require[.n] &lt;public|#channel|key&gt;</code>, <code>del flood.channel.scope.require.&lt;n&gt;|all</code> <code>set flood.channel.scope.require #bot</code> <code>flood.filter</code> Persistent flood-route rules selected by payload type and optional hop range. Generalized repeaters have 63 FPF7 forward slots; FULL ESP32 room servers have 31. Repeaters store their scope-rewrite phase, shared unordered blacklist, and channel-data compatibility state in the same atomic FPF7 image. <code>path=blacklist</code> is intended for forwarding abuse containment, including bulk internet-to-mesh dumping, but truncated path IDs are not authenticated identities. Fixed 240 KB STM32WL repeaters retain compact FPF6 filtering and separate blacklist storage. New generalized repeater tables seed slot 1 with <code>ota all suspend=tempradio</code> slot 2 with an authenticated <code>#wardriving hops=5+</code> radio drop, and slot 3 with <code>#wardriving hops=all mode=bridge,cross drop</code>. <code>mode=radio</code> is the default; <code>bridge</code>, <code>cross</code>, and <code>bridge,cross</code> select separate transport admission paths, including direct packets. Local receive/logging is unchanged. See the mode guide. <code>get flood.filter[.n]</code>, <code>set flood.filter[.n] &lt;type&gt; [N|N+|N-M|all] [scope=&lt;name&gt;] [require=region] [tx=slow] [suspend=tempradio]</code>, <code>del flood.filter.&lt;n&gt;|all</code>; repeater only: <code>get/set/del flood.filter.blacklist[.n]</code> <code>set flood.filter grp_txt all scope=local tx=slow</code> <code>flood.rule</code> Live alias for extended <code>flood.filter</code> on rule-engine repeaters and FULL ESP32 room servers. A row can AND packet type, hop range, optional channel match, ordered 1/2/3-byte pbyte source prefix, and original scope/region conditions, then drop, rewrite to a direct scope or configured region, enforce a per-row rate, allow flood retry, and/or stop lower-priority FPF7 rules. <code>channel=*</code> means no channel condition; <code>public</code>, <code>#name</code>, and keys authenticate; <code>hash:XX</code> is an unauthenticated one-byte fallback with collision/spoof risk. With no <code>retry</code> rows, global retry behavior is unchanged; once any exists, matching <code>retry</code> rows allow-list received floods while the global retry gates and <code>flood.retry.bridge</code> algorithm still apply. <code>scope=BlackHole86</code> directly derives a regionless sink scope; <code>region=BlackHole86</code> would require a configured flood-allowed region. All rows match the original receive-time packet. Higher numeric <code>priority</code> runs first; equal values automatically order authenticated channels before raw hashes before <code>channel=*</code>, then use lower slot as the final tie-break. Repeated rows with one channel key share a per-packet authentication result. Persistent FPF7 stores canonical region names, so region ID reorder or reuse cannot retarget a rule. A missing saved region makes its <code>region=</code> rewrite and paired <code>stop</code> inert until the name returns, allowing lower safety rows to run. Fixed 240 KB STM32WL profiles keep FPF6 and do not expose this alias; partition sizes are unchanged. <code>get flood.rule[.n]</code>, <code>set flood.rule[.n] type=&lt;type&gt; [hops=...] [channel=...] [prefix=...] [in=...] &lt;drop|scope=...|region=...|rate=N/min|retry|stop&gt; [priority=0-255]</code>, <code>del flood.rule.&lt;n&gt;|all</code> <code>set flood.rule.2 type=any channel=#hamradio retry</code> <code>flood.moderation</code> Decrypts keyed <code>GRP_TXT</code> channels and applies drop, per-username messages/minute, and maximum-hop controls, optionally matched against the first 1-3 path hashes. Supports <code>public</code>, <code>#channel</code>, and 128/256-bit channel keys. Sender names and truncated path hashes are moderation hints, not authenticated identities. <code>get flood.moderation[.n]</code>, <code>set flood.moderation[.n] &lt;channel&gt; &lt;sender&gt; &lt;drop|rate=X/min|hops=N&gt; [path=...]</code>, <code>del flood.moderation.&lt;n&gt;|all</code> <code>set flood.moderation public \"Noisy User\" rate=5/min hops=4</code> <code>clock.sync.mesh</code> Defaults on for all repeater, sensor, and room-server builds; a saved setting overrides that default. It estimates UTC as soon as the configured number of fresh signed-advert or valid Public-channel sources is collected, with a 30-minute bootstrap/retry timer when evidence is still insufficient, then repeats lazily seven days after each successful estimate. New evidence retriggers evaluation after a no-consensus result. <code>clock.sync.mesh now</code> queues an immediate LoRa-only attempt without bypassing quorum or source suppression. Only timestamps from firmware build time through build time plus ten years are recorded. Successful CLI, GPS, or WiFi/NTP clock updates suppress LoRa time collection until reboot; after reboot LoRa is the fallback if NTP cannot sync. Status reports the reason a clock was not set; its <code>.table</code> and <code>.1</code> through <code>.16</code> forms inspect collected samples. <code>get clock.sync.mesh</code>, <code>set clock.sync.mesh &lt;on|off&gt;</code>, <code>clock.sync.mesh now</code>, <code>get clock.sync.status[.table|.1-.16]</code> <code>set clock.sync.mesh on</code> <code>clock.sync.mesh.edge</code> Defaults on so edge infrastructure nodes can collect clock evidence when all packets arrive through one relay path. Verified evidence is observed before the forwarding decision, so disabled forwarding and forwarding filters do not prevent collection. Signed adverts are deduplicated by public key and Public-channel timestamps by case-insensitive display name; all may share one receive path. Public display names are unauthenticated and can be spoofed. Changing this setting clears current clock samples. <code>get clock.sync.mesh.edge</code>, <code>set clock.sync.mesh.edge &lt;on|off&gt;</code> <code>set clock.sync.mesh.edge on</code> <code>clock.sync.internet</code> Adds a read-only internet/NTP estimate at the same initial and seven-day checks on WiFi MQTT repeater-observer builds. Other builds retain the setting but report internet unavailable. <code>get clock.sync.internet</code>, <code>set clock.sync.internet &lt;on|off&gt;</code> <code>set clock.sync.internet on</code> <code>clock.sync.drift</code> Absolute correction threshold in seconds; the default is 600 seconds (10 minutes). The clock is moved forward or backward only when the estimate differs by more than this value. <code>get clock.sync.drift</code>, <code>set clock.sync.drift &lt;30-86400&gt;</code> <code>set clock.sync.drift 600</code> <code>clock.sync.samples</code> Minimum fresh evidence count before mesh time can be used: distinct receive paths in normal mode or distinct advert keys/Public-channel display names in edge mode. A strict majority of all fresh samples is also required. Range <code>3-16</code>; default <code>9</code>. <code>get clock.sync.samples</code>, <code>set clock.sync.samples &lt;3-16&gt;</code> <code>set clock.sync.samples 9</code> <code>outpath</code> Overrides the primary direct route used for replies to the current remote client. <code>get outpath</code>, <code>set outpath &lt;hops&gt;</code>, <code>set outpath direct</code>, <code>set outpath clear</code>, <code>set outpath flood</code> <code>set outpath A1B2C3,D4E5F6</code> <code>altpath</code> Adds a secondary direct route for repeater replies to the current remote client. <code>get altpath</code>, <code>set altpath &lt;hops&gt;</code>, <code>set altpath direct</code>, <code>set altpath clear</code>, <code>set altpath flood</code> <code>set altpath 71CE82,BA09F0</code> <p>The generalized filter table also accepts <code>fr</code> as a short alias for <code>flood.rule</code>: <code>set fr.3 any c=#wardriving m=bc d</code> is the full third built-in rule. Modes can be <code>m=r</code> (radio), <code>m=b</code> (bridge), <code>m=c</code> (crossover), or <code>m=bc</code> (both transport paths). <code>get fr.N</code> returns a short setter ready to copy; <code>del fr.N</code> deletes that row. Full names and short tokens can be mixed, with the same validation and permissions. See the shorthand reference.</p>"},{"location":"halo_keymind_settings/#other-keymind-commands","title":"Other Keymind Commands","text":"Command What it does How to use Example <code>send text.flood</code> Sends a <code>#repeaters</code> flood text message formatted as <code>&lt;node_name&gt;: &lt;message&gt;</code>, with <code>:</code> in the node name sent as <code>;</code>. <code>send text.flood &lt;message&gt;</code> <code>send text.flood checking ridge link</code>"},{"location":"halo_keymind_settings/#battery-alerts","title":"Battery Alerts","text":"<p>Battery alerts are off by default. Enabling requires a named region. With no region argument, the repeater selects the single deepest (most narrow) region in the hierarchy; if multiple regions tie, the command asks for an explicit region. For example, after <code>region def west pnw wa w-wa sea</code>, <code>set battery.alert on</code> selects <code>sea</code>, while <code>set battery.alert on w-wa</code> overrides the default. Alerts are never sent as unscoped floods, and removing the selected region stops alerts until a valid scope is selected again.</p> <p>The repeater suppresses alerts for its first 30 minutes of uptime. It then checks every 30 minutes and sends a flood text warning to <code>#repeaters</code> when voltage is above <code>1 V</code> and the estimated battery percent is below <code>battery.alert.low</code>.</p> <p>Warnings and critical alerts both use a <code>12</code>-hour resend cooldown, beginning only after the radio reports that the alert transmission completed.</p> <p>Defaults:</p> Setting Default <code>battery.alert</code> <code>off</code> <code>battery.alert.region</code> <code>&lt;unset&gt;</code> <code>battery.alert.low</code> <code>20</code> <code>battery.alert.critical</code> <code>10</code> <p>Example:</p> <pre><code>set battery.alert.low 20\nset battery.alert.critical 10\nset battery.alert on\nget battery.alert\nget battery.alert.region\n</code></pre> <p>CPU power saving remains compatible with the check. The battery timer never requests a wake earlier than its 30-minute deadline; when the normal loop is already awake after that deadline, no additional wake is needed. Sleeping time counts toward the startup delay, and an outbound warning prevents another sleep until the queued packet has been handled. This is separate from RX duty-cycle power saving, which only cycles the LoRa receiver and does not stop the main loop's battery timer.</p>"},{"location":"halo_keymind_settings/#recent-repeater-table","title":"Recent Repeater Table","text":"<p>Direct retry uses the recent repeater table when <code>direct.retry.heard</code> is <code>on</code>. Bridge buckets also use this table: a configured bucket prefix is active only when it was heard within the last hour.</p> <p>Show learned rows:</p> <pre><code>get recent.repeater\nget recent.repeater 2\nget recent.repeaters 2\nget recent.repeater page 3\nget recent.repeaters search A1\nget recent.repeaters search A1B2 page 2\n</code></pre> <p>Search matches overlapping 1-, 2-, and 3-byte path hashes. Each matching row shows its stored SNR and a whole <code>s</code>, <code>m</code>, or <code>h</code> age measured from the most recent recording. Search pages contain up to six rows.</p> <p>Seed or correct a prefix:</p> <pre><code>set recent.repeater A1B2C3 8.5\n</code></pre> <p>Clear learned and manually seeded rows:</p> <pre><code>clear recent.repeater\n</code></pre> <p>Rows are sorted by prefix width, then SNR. A full direct retry failure lowers the matching row by <code>0.25 dB</code>. Unfiltered paged replies contain up to <code>10</code> rows; an unpaged local serial query prints the full table.</p>"},{"location":"halo_keymind_settings/#direct-path-overrides","title":"Direct Path Overrides","text":"<p><code>outpath</code> and <code>altpath</code> apply to the current remote client ACL entry. They need remote client context, so they are not useful from the local serial CLI.</p> <p>Set paths with comma-separated hop hashes. Each hop must be <code>2</code>, <code>4</code>, or <code>6</code> hex characters, and all hops in one path must use the same width. Hex input is case-insensitive. Replies use uppercase hex and retain the commas, so the value can be copied directly into another <code>set outpath</code> or <code>set altpath</code> command.</p> <pre><code>get outpath\nget outpath path\nset outpath A1B2C3,D4E5F6\nset outpath path\nset outpath direct\nset outpath clear\nset outpath flood\nget altpath\nset altpath 71CE82,BA09F0\nset altpath clear\n</code></pre> <p>For example, both <code>set altpath 600000,0d2784,f8dada</code> and <code>Set altpath 600000,0d2784,f8dada</code> store the same path and reply with:</p> <pre><code>&gt; 600000,0D2784,F8DADA\n</code></pre> <p>The first CLI word is case-insensitive (<code>set</code>, <code>Set</code>, and <code>SET</code> are the same, as are <code>get</code>, <code>Get</code>, and the other command verbs). Argument case is preserved.</p> <p><code>get outpath path</code> reports the reciprocal path received after the latest flood login without changing <code>outpath</code>. That packet arrives asynchronously, so retry shortly if the first query reports <code>&gt; path pending</code>; the observation window expires after one minute. The login path is not automatically selected. <code>set outpath path</code> copies the observed route into <code>outpath</code> and saves it; it leaves the current route unchanged when no observed route is available.</p> <p><code>set outpath direct</code> sets a zero-hop direct route for a client reachable without repeaters. <code>set outpath clear</code> forgets the override, replies <code>&gt; outpath cleared</code>, and lets normal path discovery fill it again. <code>set outpath flood</code> forces replies to use flood packets until the client logs in again.</p> <p>When <code>outpath</code> is a valid direct path and <code>altpath</code> is also a valid, different direct path, repeater DM replies send two packets: one on <code>outpath</code> and one on <code>altpath</code>. The secondary <code>altpath</code> copy does not create its own direct-retry state, so retry tracking stays attached to the primary <code>outpath</code> packet. <code>altpath clear</code> disables the secondary direct reply. <code>altpath flood</code> is accepted for command symmetry, but it does not create a second flood reply; only a valid direct <code>altpath</code> sends the second packet.</p>"},{"location":"halo_keymind_settings/#direct-retry-settings","title":"Direct Retry Settings","text":"<p>Direct retry applies to direct-routed packets. A queued resend is canceled when the next-hop echo is heard. Repeaters expose the settings below; non-repeater firmware uses the same packet-type timing rules with fixed shared base/step timing.</p> Setting What it does How to use Example <code>retry.preset</code> Applies shared direct and flood retry defaults. Values: <code>infra</code>, <code>rooftop</code>, <code>mobile</code> or <code>0</code>, <code>1</code>, <code>2</code>. <code>get retry.preset</code>, <code>set retry.preset &lt;value&gt;</code> <code>set retry.preset rooftop</code> <code>direct.retry.heard</code> Uses the recent repeater table as the direct retry eligibility gate. <code>get direct.retry.heard</code>, <code>set direct.retry.heard on/off</code> <code>set direct.retry.heard on</code> <code>direct.retry.margin</code> SNR margin in dB above the SF-specific receive floor. <code>get direct.retry.margin</code>, <code>set direct.retry.margin &lt;0-40&gt;</code> <code>set direct.retry.margin 5</code> <code>direct.retry.count</code> Maximum direct retry attempts after initial TX. Direct-routed type 2 text packets always use 21 attempts regardless of this setting or the short-path cap. <code>get direct.retry.count</code>, <code>set direct.retry.count &lt;1-15&gt;</code> <code>set direct.retry.count 15</code> <code>direct.retry.base</code> Base wait in milliseconds before retry; packet-length add-on is 3x for TRACE and ANON_REQ/type 7, 7x for TXT_MSG/type 2, and 6x for other direct retry packets. <code>get direct.retry.base</code>, <code>set direct.retry.base &lt;10-5000&gt;</code> <code>set direct.retry.base 175</code> <code>direct.retry.step</code> Milliseconds added per retry attempt after the base, packet-length add-on, and random forwarding jitter. <code>get direct.retry.step</code>, <code>set direct.retry.step &lt;0-5000&gt;</code> <code>set direct.retry.step 100</code> <code>direct.retry.cr</code> Adaptive coding-rate thresholds for repeater direct retry packets. Repeaters use <code>CR4</code>, <code>CR5</code>, <code>CR7</code>, or <code>CR8</code>, then escalate by attempt: CR4, CR5, CR7, CR7, then CR8 from a CR4 start; CR5, CR7, CR7, then CR8 from a CR5 start. Non-repeaters start at the current radio CR and follow the same escalation pattern, clamped at CR8. <code>get direct.retry.cr</code>, <code>set direct.retry.cr &lt;cr4_min&gt;,&lt;cr5_min&gt;,&lt;cr7_min&gt;,&lt;cr8_max&gt;</code>, <code>set direct.retry.cr off</code> <code>set direct.retry.cr 10.0,7.5,2.5,0</code> <p>The default adaptive coding-rate profile is <code>10.0,7.5,2.5,2.5</code>. SNR <code>10.0 dB</code> and up uses <code>CR4</code>, <code>7.5 dB</code> and up uses <code>CR5</code>, <code>2.5 dB</code> and down uses <code>CR8</code>, and the middle band uses <code>CR7</code>. If no recent repeater table entry is available, retry packets use <code>CR5</code>. Use <code>set direct.retry.cr off</code> to disable adaptive coding-rate overrides. Repeater attempts escalate from the adaptive starting CR: <code>CR4</code>, <code>CR5</code>, <code>CR7</code>, <code>CR7</code>, then <code>CR8</code> from a <code>CR4</code> start; <code>CR5</code>, <code>CR7</code>, <code>CR7</code>, then <code>CR8</code> from a <code>CR5</code> start. Non-repeaters use the current radio CR as the first retry CR and follow the same pattern up to <code>CR8</code>.</p> <p>Preset details:</p> Preset Base Count Step SNR gate <code>infra</code> <code>275 ms</code> <code>4</code> <code>150 ms</code> SF floor + <code>15 dB</code> <code>rooftop</code> <code>175 ms</code> <code>15</code> <code>100 ms</code> SF floor + <code>5 dB</code> <code>mobile</code> <code>175 ms</code> <code>15</code> <code>50 ms</code> SF floor <p>Example for a quiet fixed repeater:</p> <pre><code>set retry.preset rooftop\nset direct.retry.heard on\nset direct.retry.margin 5\n</code></pre> <p>Example for a moving or weak-link node:</p> <pre><code>set retry.preset mobile\nset direct.retry.margin 0\n</code></pre>"},{"location":"halo_keymind_settings/#flood-and-advert-settings","title":"Flood And Advert Settings","text":"<p>Flood retry applies to flood-routed packets. A queued retry is canceled when the same packet is heard from a qualifying, non-ignored repeater. Bridge mode uses the bucket rules below instead.</p> Setting What it does How to use Example <code>flood.retry.count</code> Base flood retry attempts after initial TX. Role path scaling happens first, then all builds apply payload caps: <code>REQ</code> is <code>0</code>; <code>GRP_TXT</code> keeps up to <code>15</code>; remote-login <code>RESPONSE</code>, <code>TXT_MSG</code>, <code>ANON_REQ</code>, and <code>PATH</code> keep up to <code>15</code> at path count 0 and cap at <code>2</code> in transit; every other flood type caps at <code>1</code>. A lower calculated value is preserved, and <code>0</code> disables flood retry. <code>get flood.retry.count</code>, <code>set flood.retry.count &lt;0-15&gt;</code> <code>set flood.retry.count 7</code> <code>flood.retry.path</code> Maximum path hash count eligible for flood retry, or <code>off</code> to disable the gate. <code>get flood.retry.path</code>, <code>set flood.retry.path &lt;0-63/off&gt;</code> <code>set flood.retry.path 1</code> <code>flood.retry.group.path</code> Additional path gate for group data (<code>type=6</code>) flood retries. The stricter of this and <code>flood.retry.path</code> applies; <code>off</code> disables only this additional gate. Setting the general path gate to <code>0</code> forces this setting to <code>off</code>; a named preset restores the default of <code>1</code>. <code>get flood.retry.group.path</code>, <code>set flood.retry.group.path &lt;0-63/off&gt;</code> <code>set flood.retry.group.path 1</code> <code>flood.retry.advert</code> Allows or blocks retry for node advert packets (<code>type=4</code>). Default is <code>off</code>. <code>get flood.retry.advert</code>, <code>set flood.retry.advert on/off</code> <code>set flood.retry.advert off</code> <code>flood.retry.prefixes</code> Target prefixes. If set, only same-packet echoes from matching last-hop prefixes cancel a retry. <code>get flood.retry.prefixes</code>, <code>set flood.retry.prefixes &lt;prefixes/none/off&gt;</code> <code>set flood.retry.prefixes BEEBB0,425E5C</code> <code>flood.retry.ignore</code> Ignored prefixes. In non-bridge retry, ignored last-hop echoes do not cancel retry. <code>get flood.retry.ignore</code>, <code>set flood.retry.ignore &lt;prefixes/none/off&gt;</code> <code>set flood.retry.ignore 71CE82,C7618C</code> <code>flood.retry.bridge</code> Enables bucket-based bridge retry logic. <code>get flood.retry.bridge</code>, <code>set flood.retry.bridge on/off</code> <code>set flood.retry.bridge on</code> <code>flood.retry.bucket.&lt;n&gt;</code> Shows one bridge bucket. Buckets are numbered <code>1</code>-<code>6</code>. <code>get flood.retry.bucket.&lt;n&gt;</code> <code>get flood.retry.bucket.1</code> <code>flood.retry.bucket</code> Sets bridge bucket prefixes. <code>set flood.retry.bucket &lt;1-6&gt; &lt;prefixes/none/off&gt;</code> <code>set flood.retry.bucket 1 71CE82,C7618C</code> <p>Extended <code>flood.rule</code> rows can select which received floods may use these settings. For example, enable bridge completion only for Public and <code>#hamradio</code> with <code>set flood.rule type=any channel=public retry</code> and a second row using <code>channel=#hamradio</code>. Adding the first active <code>retry</code> row changes received retry selection into an allow-list; deleting the last restores the legacy global selection. <code>channel=hash:XX</code> is available when only the visible one-byte hash is known, but it is not authenticated and is collision-prone. For example, <code>hash:11</code> includes Public and any other packet using <code>0x11</code>; <code>channel=public</code> alone performs the Public-key MAC/decrypt check.</p> <p>Bridge buckets may also be reused as passive <code>flood.channel.scope</code> path selectors with <code>path=bucket:&lt;1-6&gt;</code>. This does not require <code>flood.retry.bridge</code> to be enabled and does not depend on recent-repeater freshness or the retry ignore list.</p> <p>Forwarded neighbor adverts also use an automatic echo guard in every build. If this node hears a downstream, longer-path echo after transmitting an advert whose signed timestamp is less than six hours old, it will not forward that exact advert again during the six-hour age window. This guard works even when <code>flood.retry.advert</code> is off and does not affect self-originated adverts.</p> <p>Self-originated advert retries are deliberately slow: the first retry waits at least one extra minute beyond the normal airtime-aware delay. Queueing a newer self advert retires queued and future retry attempts for older self adverts without disturbing other flood retry sequences. Companion firmware allows the one slow retry for its own adverts but not for neighbor adverts it relays.</p> <p>The shared retry preset sets these flood defaults:</p> Preset Retry count Path gate Group-data path gate <code>infra</code> <code>1</code> <code>1</code> <code>1</code> <code>rooftop</code> <code>3</code> <code>2</code> <code>1</code> <code>mobile</code> <code>15</code> <code>1</code> <code>1</code> <p>Hop-zero flood retries use the direct-retry CR ladder starting at the active radio CR. With CR5, <code>infra</code> allows CR5, CR7; <code>rooftop</code> allows CR5, CR7, CR7, CR8, CR8, CR8; <code>mobile</code> allows CR5, CR7, CR7, then CR8 through retry 15. These lists exclude the initial send and remain subject to payload caps and echo cancellation. Floods with recorded hops keep the active CR. <code>flood.retry.count 0</code> still disables every automatic flood retry, including hop zero, without changing direct-retry settings or their CR schedule. See hop-zero flood retry coding rate for every starting CR and the payload limits.</p> <p>Example for path-gated retry:</p> <pre><code>set retry.preset rooftop\nset flood.retry.path 1\nset flood.retry.group.path 1\nset flood.retry.advert off\nset flood.retry.ignore 71CE82,C7618C\n</code></pre>"},{"location":"halo_keymind_settings/#north-south-buckets","title":"North South Buckets","text":"<p>Buckets describe groups of repeaters on different sides of this relay. Bucket numbers do not have built-in meanings; this example uses bucket <code>1</code> for North and bucket <code>2</code> for South.</p> <pre><code>              North bucket 1\n        +-----------------------+\n        | A1B2C3       D4E5F6   |\n        | North A      North B  |\n        +-----------+-----------+\n                    |\n                    v\n              +-----------+\n              | This node |\n              +-----------+\n                    ^\n                    |\n        +-----------+-----------+\n        | 71CE82       C7618C   |\n        | South A      South B  |\n        +-----------------------+\n              South bucket 2\n</code></pre> <p>Configure the buckets:</p> <pre><code>set flood.retry.bridge on\nset flood.retry.bucket 1 A1B2C3,D4E5F6\nset flood.retry.bucket 2 71CE82,C7618C\nset flood.retry.ignore none\n</code></pre> <p>Packet heard from the North:</p> <pre><code>     heard source\n         |\n         v\n  +--------------+        retry targets\n  | North bucket | -----&gt; South bucket\n  | bucket 1     | -----&gt; Other fresh/unbucketed relays\n  +--------------+\n</code></pre> <p>Packet heard from the South:</p> <pre><code>     heard source\n         |\n         v\n  +--------------+        retry targets\n  | South bucket | -----&gt; North bucket\n  | bucket 2     | -----&gt; Other fresh/unbucketed relays\n  +--------------+\n</code></pre> <p>Packet heard from an unbucketed or pathless source:</p> <pre><code>     heard source\n         |\n         v\n  +--------------+        retry targets\n  | Other bucket | -----&gt; North bucket\n  | implicit     | -----&gt; South bucket\n  +--------------+\n</code></pre> <p>Bridge retry stays eligible until every target bucket has been heard or <code>flood.retry.count</code> is exhausted. A configured bucket is a target only when at least one of its prefixes is fresh in <code>recent.repeater</code>. Prefixes in <code>flood.retry.ignore</code> never count as bucket hits.</p> <p>Configuration reports a warning when prefixes in different buckets, including bucket 7 (<code>flood.retry.prefixes</code>), share the same first byte. A 1-byte path cannot distinguish those buckets. Bridge mode therefore excludes every matching bucket when that short prefix is the source, and credits every matching target bucket when it is heard as an echo. This prevents an ambiguous short prefix from keeping an impossible target outstanding through every retry.</p> <p>Each flood retry wait retains the fixed maximum-frame plus 20 packet-airtime delay, then adds random jitter from zero to 200 percent of one additional packet airtime. This keeps nearby repeaters from repeating a collision on fixed timing while capping the added wait at two frames.</p> <p>Only one enhanced retry sequence can be active for the same logical flood packet. Identical floods still receive their normal transmission, but do not multiply the extra attempts. Evicted queued retries release their bridge state, and the final echo wait does not reserve a packet-pool entry.</p> <p>Earlier path hops from a successful bridge echo refresh a separate per-bucket reachability cache without an SNR value. Only the final hop, which actually sent the received RF frame, updates <code>recent.repeater</code> and its SNR. Indirect path hops therefore cannot change direct-retry SNR gating or coding-rate selection.</p>"},{"location":"halo_keymind_settings/#troubleshooting","title":"Troubleshooting","text":"<p>If advert packets are still retrying:</p> <pre><code>get flood.retry.advert\nset flood.retry.advert off\n</code></pre> <p>If ignored prefixes still appear in <code>flood retry good</code> logs:</p> <pre><code>get flood.retry.ignore\nset flood.retry.ignore &lt;prefix&gt;\n</code></pre> <p>The ignored prefix must match the last hop shown as <code>heard=&lt;prefix&gt;</code>. For example, this log needs <code>C7618C</code> in the ignore list:</p> <pre><code>flood retry good (... path=7773D0&gt;C7618C, heard=C7618C ...)\n</code></pre> <p>If retries are too aggressive:</p> <pre><code>set flood.retry.count 1\nset flood.retry.path 1\nset direct.retry.count 4\n</code></pre> <p>If retries are too sparse:</p> <pre><code>set flood.retry.count 7\nset flood.retry.path 2\n</code></pre>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/","title":"XIAO Bluetooth stealth hardware validation - 2026-09-07","text":"<p>Historical command syntax: the initial run used stealth as a MAC mode. Current firmware uses the independent <code>bluetooth.stealth on|off</code> flag instead and does not migrate that development mode. See current commands and the independent-flag follow-up below. Each observation applies only to the exact artifact listed in its section.</p> <p>This is a hardware observation report, not an all-board or phone qualification. The test host was the MercerWoodMesh Raspberry Pi Zero 2 W, accessed remotely over Tailscale. Tests used its built-in Bluetooth adapter, not USB resets or hub power switching. Local timestamps below use America/Los_Angeles.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#exact-target-and-firmware","title":"Exact target and firmware","text":"<ul> <li>Board: Seeed XIAO nRF52840; application name <code>MeshCore-4610BBD2</code>.</li> <li>Factory/bootloader address: <code>E5:C3:A8:B0:60:66</code>.</li> <li>Fresh stealth test address: <code>DC:8D:5E:45:89:6F</code>.</li> <li>Bonded test central: Mercer Pi, public address <code>B8:27:EB:F9:6E:8E</code>.</li> <li>Environment: <code>Xiao_nrf52_companion_radio_ble</code>, supported build wrapper,   target radio preset, default profile, GCC 14.2.1.</li> <li>Firmware: <code>dev-stealth3-4b400ea5</code>, including the uncommitted Bluetooth   identity changes on top of <code>4b400ea5</code>.</li> <li>Application ZIP SHA-256:   <code>acdce0af2334349c6e0a5786db5525b00d19befef340411d2e99008ce4d316ae</code>.</li> <li>Linked RAM: 183,232 / 237,568 bytes; flash: 616,504 / 708,608 bytes.</li> </ul> <p>The application was installed with Nordic Legacy BLE DFU. The tool verified the exact ZIP hash, bootloader advertisement and live DIS model <code>XIAO nRF52840</code> before transmitting 616,584 application bytes. Target image validation and target-initiated activation disconnect passed. The transfer reported about 2,223 bytes/second (about 277 seconds for payload transmission). Authenticated MeshCore device queries subsequently returned protocol 14, board <code>Seeed Xiao-nrf52</code>, and the expected unique test-version prefix.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#observed-results","title":"Observed results","text":"Check Result and evidence First-pair discovery <code>set bluetooth.mac stealth</code> saved a new random-static address; reboot returned that exact address with the normal name and Nordic UART advertisement. First authenticated pairing The Pi received a passkey request and completed pairing. BlueZ reported both Paired and Bonded. MITM-protected Nordic UART notifications and real command/reply exchanges worked at MTU 247. Pairing transition keeps the session alive The initial connection returned <code>stealth; bonded-peer-only advertising</code>, remained usable for five more seconds, and answered another command without disconnecting or pairing again. Advertising after disconnect A public-address passive scan captured <code>ADV_DIRECT_IND</code> from the exact target, with advertising data length zero. The capture contained no undirected advertisement or scan response from that address. Bonded reconnect Subsequent direct connections by saved BlueZ device identity succeeded without a new passkey, including live version, core-statistics and Bluetooth-mode replies. Warm reboot persistence Two commanded reboots retained the address and saved bond. Directed advertising was captured after reboot, followed by authenticated reconnect. Device uptime decreased from 61 seconds before the second reboot to 35 seconds at the next query; core error flags were zero. Slow advertising interval A successful bonded reconnect occurred about 61 seconds after reboot, beyond the 30-second fast-advertising interval. Reopen pairing Setting <code>stealth</code> again from an existing bonded connection generated a new address, and the next boot allowed a fresh first pairing. Restore default <code>set bluetooth.mac default</code> plus reboot restored <code>E5:C3:A8:B0:60:66</code> and normal discovery. Fresh PIN pairing, version/core-statistics queries and repeated <code>factory address (default)</code> replies passed. The bench target was left in this discoverable mode. <p>The newly completed pairing reaches Bluefruit's secured callback before its bonded flag is necessarily ready. Recording the completed pairing in the pair-complete callback as well, waiting for the deferred bond write, and deferring identity-list reconfiguration until disconnect are covered by this fresh-pair hardware run. Static source contracts also check those paths.</p> <p>The binary reboot command can reset the target before BlueZ receives its ATT write acknowledgement. One initial harness run reported <code>Unlikely Error</code> after successful pre-reboot commands. Later checks require an observed disconnect, a live post-reboot query and decreased device uptime; they do not treat the write exception or tool exit code alone as a successful reboot.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#discovery-and-dfu-cautions-found-during-testing","title":"Discovery and DFU cautions found during testing","text":"<p>An ordinary BlueZ discovery scan used a temporary random local address and did not show the directed target. A passive scan using the Pi's public identity did show it. Reconnection must use the saved peer/device identity; absence from an ordinary scan is not proof that the node stopped working. Conversely, BlueZ can retain a cached name after pairing, so a displayed name is not proof that the name is still being advertised. The packet-type and zero-length-payload capture is the relevant evidence here.</p> <p>The existing DFU handoff helper assumed the application and bootloader shared one address. That assumption is false with a custom application address: the authenticated handoff worked, but the helper timed out looking for DFU at the application address. A fresh exact-address scan found the known factory-address <code>XIAO_DFU</code> instead. An old factory-address host bond also caused the first DFU service-discovery attempt to disconnect; clearing only that old lab record allowed DFU. No bootloader code was changed for this test.</p> <p>An earlier application-address host pairing record was also removed before its saved stealth state was known. A direct, known-address connection from the same Pi identity allowed fresh PIN pairing and protected commands again. This does not prove that an arbitrary replacement phone can rediscover or recover a stealth node after forgetting its bond.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#remaining-hardware-gates","title":"Remaining hardware gates","text":"<ul> <li>True cold boot with all XIAO power sources, including battery, disconnected.   The XIAO reported a battery voltage and did not enumerate as USB on the Pi;   a Pi-only reboot or power cycle would not prove this gate.</li> <li>Unused-boot retention with <code>random-after-connect</code>, using a reboot trigger   that does not itself authenticate over BLE. The policy has native tests;   the remote BLE reboot command cannot prove this hardware gate.</li> <li>Android and iOS bonded reconnect, including a phone changing its resolvable   private address, and direct-connection behavior in the actual MeshCore app.</li> <li>Rejection of a connection from a second, unbonded physical central.</li> <li>ESP32 Bluedroid and NimBLE hardware. Those use allowlisted minimal   advertising rather than nRF52 directed advertisements.</li> <li>Node-side missing/corrupt bond and failed settings/bond-write fault injection.</li> </ul>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#repeatable-regression-procedure","title":"Repeatable regression procedure","text":"<ol> <li>Record the exact board, application version, ZIP hash, local/remote BLE    identities and original Bluetooth setting. Keep a working recovery path.</li> <li>Set the desired custom or random MAC, enable <code>bluetooth.stealth on</code>, reboot,    and capture normal discovery before pairing.</li> <li>Pair once. Require a stored bond and successful protected MeshCore commands,    then keep the original session open and issue another command.</li> <li>Disconnect. Capture the actual advertising type and payload with an    appropriate receiving identity; do not use cached scan names as evidence.</li> <li>Reconnect by the saved peer without another PIN and exchange commands.</li> <li>For custom and saved-random addresses, repeat <code>bluetooth.stealth on</code>, reboot    twice, and verify unchanged identity/bond, decreased uptime and live    commands. Include a reconnect after the fast-advertising period ends.</li> <li>Separately remove all target power and repeat the persistence checks.</li> <li>Test <code>bluetooth.stealth off</code>, then <code>on</code>, as a pairing reset, and <code>off</code> as    the exit from stealth. Verify live discovery, pairing, commands and an    unchanged MAC policy. Changing the address to <code>default</code> is a separate step.</li> <li>With each rotating MAC policy, verify that its rotation trigger still    works, stealth stays enabled, and the new address permits fresh pairing.</li> <li>Repeat relevant gates for a phone with address privacy and each BLE backend.</li> </ol> <p>Raw VM-side logs, the exact artifact and bounded test helper are in <code>/home/mesh/mercer-stealth-validation.jUDW0v/</code>. Raw Bluetooth captures are local diagnostics and should not be published without privacy review.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#mercer-crash-capture","title":"Mercer crash capture","text":"<p>During this run the Pi used its existing <code>dwc_otg.speed=1</code> full-speed USB configuration. Kernel and health logs were streamed to this VM. No new kernel errors or Pi lockup were observed during these tests; that does not establish the cause of the earlier lockup.</p> <p>The live test streams and all temporary scans were stopped at approximately 22:56 PDT. Journald remained active, the restore service remained enabled, and the test XIAO was disconnected in default mode. Disk journals occupied about 4.9 MiB at the final check.</p> <p>At 22:35 PDT, temporary persistent journaling was enabled with a 16 MiB configured disk-use limit, 2 MiB journal files, one-day retention and a 30-second normal sync interval. Recent buffered messages can still be lost in a sudden failure. The original <code>Storage=volatile</code> configuration is intact.</p> <p><code>mercer-crash-capture-restore.service</code> is enabled for the next Pi boot. It checks the armed boot ID, removes only the unchanged managed override, switches journald back to RAM and leaves the old disk journals for collection. Its same-boot no-op guard and unit syntax passed. The next-boot restoration has not yet been exercised; no Pi crash or reboot was deliberately induced.</p>"},{"location":"hardware_validation_bluetooth_stealth_2026-09-07/#independent-flag-follow-up-dev-stflag","title":"Independent-flag follow-up - dev-stflag","text":"<p>The same XIAO and Pi were used later on 2026-09-07 to test the separate <code>bluetooth.stealth on|off</code> flag, with no development-mode migration. This run used <code>Xiao_nrf52_companion_radio_ble</code>, target radio preset, default profile, and firmware <code>dev-stflag-4b400ea5</code> with the uncommitted flag changes.</p> <ul> <li>Application ZIP SHA-256:   <code>48fc0ff2c716281771f8b525c62a0015c7605b07e7c513ab854c8b3ff3113f42</code>.</li> <li>Linked RAM: 183,232 / 237,568 bytes; flash: 617,192 / 708,608 bytes.</li> <li>Nordic Legacy BLE DFU verified the exact target, hash and model, transferred   617,272 application bytes at a reported 3,522 bytes/second, passed target   validation, and observed the target activation disconnect.</li> <li>Protected live device queries returned <code>dev-stflag-4b400ea5</code>, protocol 14,   and <code>Seeed Xiao-nrf52</code>; every queried core error-flags value was zero.</li> </ul> Check Observed result Default and rejected input Initial mode was factory address with stealth off. <code>set bluetooth.mac stealth</code> and <code>set bluetooth.stealth maybe</code> returned errors, leaving both settings unchanged. Custom plus stealth <code>D2:27:5A:40:06:99</code> advertised normally before first pairing. Fresh PIN pairing, stored bond, protected commands, and a five-second held session passed with stealth on. Repeated on and warm reboot Repeating <code>set bluetooth.stealth on</code> retained the paired state. After reboot, the same custom address accepted protected commands without another PIN. Uptime decreased from 84 to 67 seconds. Actual advertising after reboot A public-address passive capture showed <code>ADV_DIRECT_IND</code> for the custom address, data length zero, and no undirected advertisement or scan response from that address. The scan was explicitly disabled afterward. Off preserves custom address <code>set ble.stealth off</code> and reboot restored normal discovery at the same custom address. A live connection returned stealth off and the unchanged custom policy. Saved random plus stealth <code>F2:2E:E5:65:18:5E</code> passed first pairing and held commands. After reboot, it retained its address, saved-random policy and stealth bond; protected reconnect needed no PIN. Uptime decreased from 55 to 30 seconds. Random-after-connect plus stealth Selecting this policy kept stealth on and reopened pairing at <code>C7:FD:29:44:4F:3E</code>. Pairing produced both bonded-peer-only status and an armed next-boot rotation. Reboot changed the address to <code>F5:F3:89:B7:B5:26</code>, where normal discovery, fresh pairing and protected commands passed with stealth still on. Random-every-boot plus stealth The first boot used <code>F9:B2:03:DD:CC:43</code>, completed fresh pairing, and answered commands with stealth on. The next commanded reboot advertised <code>F8:C7:C0:96:1E:00</code>; fresh PIN pairing and protected commands passed again with the rotating policy and stealth on. Restore the bench target Setting the MAC to <code>default</code> kept stealth on until the separate <code>set bluetooth.stealth off</code>. After reboot, factory-address discovery, fresh PIN pairing and protected commands confirmed default MAC and stealth off. The obsolete factory-address host bond was replaced during this final pairing. <p>These checks used actual encrypted BLE connections at MTU 247, not scan sightings alone. Two first-pair harness attempts stopped before connecting because their unpaired BlueZ discovery object no longer existed. A fresh bounded scan immediately followed by pairing was used for retries; this was not a firmware GATT command failure. Reboot-write/disconnect races were accepted only with an observed disconnect and subsequent live device checks.</p> <p>Local automated verification passed 39 native cases, 32 source/persistence/UI contracts, and 11 real-browser cases. Supported-wrapper builds passed for XIAO nRF52, XIAO C3, M5Stack Unit C6L and XIAO S3 WIO Full Companion, covering nRF52, ESP32 NimBLE and ESP32 Bluedroid integration. The contracts and browser suite are included in the unit-test workflow; a browser must be available for the optional browser suite to execute instead of skip.</p> <p>Exact artifacts, build logs, command logs and the private packet capture are in <code>/home/mesh/bluetooth-stealth-flag.ApLB8o/</code> on the VM. The remaining hardware gates above still apply; these results do not qualify every board or phone.</p> <p>At 23:42 PDT the XIAO was disconnected in normal discoverable mode. The Pi retained the same boot ID throughout, remained responsive, and had no new kernel messages in the streamed log. Journald was active, the next-boot volatile-log restoration service was still enabled, and disk journals used about 5.9 MiB. No USB reset, Pi reboot, or target battery removal was used.</p>"},{"location":"hardware_validation_checklist/","title":"Hardware validation checklist","text":"<p>This file records dated hardware observations and open validation tasks. Historical defaults, versions, and test frequencies below describe the tested revision, not necessarily the current release. For current ASCII USB defaults and runtime switches, use feature switches by role.</p> <p>Use this checklist for release-candidate hardware runs. A check is complete only when its log identifies the physical device, firmware artifact, artifact hash, command result, and cold/warm boot outcome. Do not infer success from a tool's exit code when the tool has a documented false-success mode.</p>"},{"location":"hardware_validation_checklist/#bluetooth-stealth-qualification-2026-09-07","title":"Bluetooth stealth qualification - 2026-09-07","text":"<p>The XIAO stealth report records exact artifacts for the initial implementation and independent-flag follow-up. The flag run covers custom/saved-random pairing and bonded reboot reconnect, idempotent <code>on</code>, <code>off</code> preserving the MAC, directed advertising, and both rotating policies with stealth still enabled. It also gives the repeatable hardware regression procedure. True battery-disconnected cold boot, phone address-privacy behavior, a second unbonded central, and ESP32 hardware remain separate uncompleted gates; do not infer them from the XIAO results.</p>"},{"location":"hardware_validation_checklist/#current-marathon-ledger-through-2026-09-04","title":"Current marathon ledger (through 2026-09-04)","text":"Hardware Stable identity Current state Next blocking check Seeed XIAO nRF52840 <code>B35E71C1C3726CE7</code> OTAFIX candidate <code>0x02040405</code> passed exact serial install and corrected Legacy DIS model gates; the patched Bluetooth repeater-updater application was restored over BLE and returned as exact <code>2886:8044</code> USB Use the updater for an identity-gated Bluetooth transfer to another repeater, then prove current-build cold persistence Seeed Tracker T1000-E <code>34A9141999729D5D</code> OTAFIX candidate <code>0x02040405</code> and the <code>uf2reset</code>-fixed Full Companion are installed. The real text command returned exact <code>2886:0057</code> boot USB, the same fixed app was restored, and refreshed bonded BLE services pass as <code>MeshCore-09848C15</code> Restore the protected Repeater identity when Companion qualification is complete; cold boot, then force LR1110 reset RAK3401 <code>0B81C9C68D8D01B4</code>; FICR <code>8D8D01B4 0B81C9C6</code> OTAFIX test version <code>0x02040403</code> passes bidirectional application UF2, exact SWD application/bootloader readback, unchanged UICR, and a 74-block direct V4 LoRa apply from exact <code>3caf9dcf</code> to current HEAD <code>9fd580c8</code>. Post-apply USB and LoRa identity/hash checks pass and the temporary 0 dBm bench setting is restored to 22 dBm Add exact RF packet counters, then repeat the supported-bandwidth and controlled/passive/mixed routed-hop matrix Heltec T096 <code>651F8E496197F882</code> OTAFIX candidate <code>0x02040405</code> and the <code>uf2reset</code>-fixed no-footer Full Companion are installed. The real text command returned exact boot USB, and final USB terminal/Binary mode, dual CDC, version, help, and BLE identity pass Perform a privileged or physical host-driven USB bus reset without resetting the MCU; complete the deferred multi-click/long-press physical matrix Heltec MeshTower V2 with SD <code>9352162A72082314</code> OTAFIX candidate <code>0x02040405</code> passed serial combined install, the historical cached DIS handles, BLE application restore, and exact application USB return. Card format/cooldown/forced-format/raw-erase/remount and the live SD apply contract passed earlier Signed interrupted-download resume, corruption/signature rejection, then full/delta apply Heltec V4 USB MAC <code>44:1B:F6:6A:E8:44</code>; BLE <code>44:1B:F6:6A:E8:45</code> USB/BLE/Wi-Fi and all three TCP services pass on hardware. The final fresh-NTP-gated Full Companion image builds with 4.31 MB app space free Flash the exact final NTP build, prove NTP-before-TLS success/failure ordering, then OTA seeding SenseCAP Indicator LoRa CH340 plus USB MAC <code>D8:3B:DA:75:23:AC</code>; BLE <code>D8:3B:DA:75:23:AD</code> The current dark-layout application is SHA-256 <code>81bebdc07b6a8349c1c975cb5a0e30c5f6019d35bcac641e5f3d4df951f7406b</code>; identity-gated flash, USB ASCII/Binary switching, runtime logging, and separate configured-Wi-Fi, BLE, and TCP checks pass. Fresh-NTP HTTPS recovery, strict Range resume, STAGEV2 install, and RP USB readback passed on earlier exact artifacts; the final coordinator source still needs its blocked-UDP/123 hardware gate Physical display-wrap and four-mode render/heap checks, exact-final blocked-NTP recovery gate, LoRa/TempRadio, and non-empty OTA seeding <p>The current source checkpoint passes 1,132/1,132 native cases, 68/68 host broker/endpoint cases, all 318 LoRa-OTA chain/route/bundle cases, and 41/41 MOTA format/signature/delta cases under the documented pipx <code>detools</code> interpreter. Indicator geometry, dark-theme, and font-recovery contracts pass 4/4, 6/6, and 25/25. A serialized real Indicator ESP32-S3 Wi-Fi/USB profile also compiles at 95,944 bytes RAM and 1,589,433 bytes flash. The direct system-Python MOTA invocation predictably lacks <code>detools</code>; that environment boundary is not a firmware failure and must not be worked around by installing the package globally.</p> <p>The RAK failure log is <code>/home/mikec/hwtest/runs/rak3401-syncidle-clean-tSp7PLgA/result.txt</code> on the Mercerwood Pi. The tested UF2 SHA-256 was <code>650c9fda456685cdf99c1f2996c60f1f551cc9216d2b746a22c8cb78464b0ff7</code>. <code>cp</code> returned success in 95 ms, but <code>sync -f</code> failed with <code>EIO</code> after 157,188 ms. Post-failure SWD readback proved that all seven ordinary sectors whose bytes differed between the old and intended builds still contained the old values, and the settings page was still erased. The only available pre-copy SWD dump was taken several hours earlier, however, so it cannot prove that zero unchanged blocks were written during this attempt or establish when the stale S140-v7 tail in the first application page appeared. The next run must capture an immediate pre-copy dump as well as the post-copy dump. Serial DFU recovery then completed in 35,698 ms with the exact <code>Device programmed.</code> marker. All 1,830 UF2 payload blocks matched SWD readback after recovery, and the application passed a subsequent real power-removal boot.</p> <p>The corrected 2.4.4-preview.2 candidate was installed through identity-gated SWD from combined-image SHA-256 <code>9b1654baccd2a920f68651893e31d79170400d1a7982a3f854ae640f1d3513a8</code>. An immediate pre-copy dump closed the earlier evidence gap. A deliberately old UF2 then copied and flushed successfully in 16,568 ms, and the exact formerly failing UF2 above copied and flushed successfully in 16,601 ms. After each direction, all 1,830 payload blocks matched a full SWD readback with zero header or payload mismatches. The return update changed 123 bytes across five expected application pages, UICR remained byte-identical, and a subsequent downstream USB power removal plus Pi reboot returned the RAK as the same stable identity. It reported the intended <code>3caf9dcf</code> application, board, node name, USA radio tuple, and 22 dBm setting after that cold boot. The new bootloader's CLI source string is truncated before the injected preview number, so the independently hashed SWD artifact is the authoritative candidate identity for this run.</p> <p>The later TinyUSB lifecycle/generation candidate identifies itself as test version <code>0x02040403</code>. Its exact 40,960-byte bootloader readback SHA-256 is <code>f609eb18754070c54f127325b1cb48547baf5c6b1c695d36fd0c8e0874713c13</code>. With that candidate installed, a full <code>CURRENT.UF2</code> read completed before each write. The 936,960-byte <code>bf092b24</code> application UF2 (SHA-256 <code>12477a9734cf12eb920361bd21024e39bf303953fcf79d0bf720e00847e2ae92</code>) copied and flushed in 28,203 ms and returned to application mode four seconds later. The exact <code>3caf9dcf</code> application UF2 (SHA-256 <code>650c9fda456685cdf99c1f2996c60f1f551cc9216d2b746a22c8cb78464b0ff7</code>) then copied and flushed in 26,479 ms and also returned in four seconds. Both boots retained <code>RAK3401-OTA-BENCH</code> and <code>910.525/62.5/SF7/CR5</code>.</p> <p>Identity-gated SWD then read the entire 468,480-byte padded UF2 application range. Its SHA-256 exactly matched the converted source on both sides at <code>b2e37a7681027ca91d1b2bd8e39b55395d9e91d4863aed17131e50c1ba1d2227</code>. The bootloader still matched the installed <code>0x02040403</code> image byte-for-byte, and UICR still matched the pre-test image at <code>d029ea630c2f632a1b690cb52b2a96a28b6f870c656c3e1bd74ba3a571c53b9c</code>. The authoritative logs are under <code>/home/mikec/hwtest/runs/rak3401-uf2-02040403-20260830-170829</code> and <code>/home/mikec/hwtest/runs/rak3401-uf2-return-02040403-sfHiGEqA</code> on Mercerwood.</p> <p>The subsequent direct LoRa qualification used the V4 as controller/seeder and the RAK's exact <code>bf092b24</code> body <code>91CF4EC2882F23D6</code> as the base. Its mandatory fixed three-minute rehearsal passed on <code>909.95/250/SF5/CR5</code>, including natural expiry and exact normal-radio recovery. The 2,132-byte, two-block in-place delta reached <code>2/2</code> and ready in six seconds; install was accepted, and the new body appeared at the 60-second reboot probe. The automation took 514 seconds including rehearsal, clock/radio safety checks, and post-install verification. The final body was <code>27A223DDFC3A8F47</code>, version <code>1.17.1.5</code> at <code>3caf9dcf</code>, and the bootloader reported <code>blrc:B8</code>, which is OTAFIX's successful application apply result rather than an error. Exact target TX power was wrapped from 22 dBm to 0 dBm for the co-located transfer and restored to 22 dBm afterward; the source RXPS configuration and both normal radio tuples were also restored.</p> <p>Identity-gated SWD then read the live application at <code>0x26000</code>. All 468,384 bytes matched the intended release image exactly (SHA-256 <code>b496e3f4419c9f771564ed3c74b3407822f45acdf60cbd6c4625a54b181ca084</code>), and the independently recomputed EndF hash was <code>27A223DDFC3A8F47</code>. The target ID was <code>2FA509C1</code>, hardware ID was <code>RAK_3401</code>, and version word decoded to <code>1.17.1.5</code>. The 40,024-byte bootloader readback also matched the exact installed <code>ffb1580</code>/test-version-<code>0x02040402</code> artifact byte-for-byte; UICR was unchanged. After SWD reset-halt/resume, USB again reported the expected application, identity, name, radio, 22 dBm, no TempRadio lease, and <code>blrc:00</code> (the retained success diagnostic is intentionally cleared by the next normal boot).</p> <p>The current <code>0x02040403</code> bootloader candidate then passed a second direct V4 LoRa qualification using a materially larger application change. The unsigned in-place package was 75,614 bytes with 75,108 payload bytes and 74 transfer blocks. Its mandatory fixed three-minute rehearsal passed, including natural TempRadio expiry and exact normal-channel recovery; one lost read-only <code>ota status</code> reply was reconciled by its bounded exact retry. The transfer reached 74/74 and READY in 122 seconds, the explicit unsigned install was accepted, and reboot produced exact HEAD <code>9fd580c8</code> with body <code>744BC4443891ED10</code>. The complete safety-wrapped run took 589.487 seconds, including rehearsal, recovery, and final verification. The first postboot <code>ver</code> reply was lost and its exact read-only retry passed. Independent USB checks then confirmed target <code>2FA509C1</code>, hardware <code>RAK_3401</code>, unchanged identity/name/radio/RXPS/watchdog state, bootloader CRC <code>6683C066</code>, ABI 3, apply result <code>blrc:B8</code>, and no active TempRadio/download/seeder/key state. After the separate host-recovery exercise, the near-field TX setting was restored from 0 dBm to its exact original 22 dBm and read back over an authenticated LoRa session. The sanitized authoritative log is <code>/home/mikec/hwtest/runs/rak3401-02040403-head-vzWOXVxT/qualification-redacted.log</code> with SHA-256 <code>3e53dcaa5922c7c18a7890963b8fc092311d2db01caa5603640f43f1482802f6</code>.</p> <p>A serialized VM build of the six connected-board qualification profiles then completed 6/6 in 136.122 seconds: XIAO nRF52 BLE Companion, T1000-E BLE Companion, RAK3401 LoRa-OTA Repeater, SenseCAP Indicator LoRa USB/Wi-Fi Companion, MeshTower V2 SD LoRa-OTA Repeater, and the consolidated Heltec V4 V4.2/V4.3 Full Companion. The earlier V4 selector typo was rejected before any compile began and is not a firmware build failure.</p> <p>After the fresh-NTP download gate, shared SNTP coordinator, MQTT-to-MeshCore RTC handoff, and daily refresh policy were added, the complete native matrix passed 1,102/1,102 cases in 93.953 seconds. The scheduler is host-tested at 24-hours-minus-one-millisecond, the exact 24-hour boundary, normal and wrapped <code>millis()</code> values, a short retry that overrides the daily cadence, the zero deadline sentinel, and a Wi-Fi event latch. A reconnect after a successful sample preserves the existing deadline, so successful samples are requested after boot and then only once per day. All current Python and shell contract suites passed, and the expanded LoRa-OTA automation suite passed 317/317 cases.</p> <p>Serialized real builds also passed after that change. The final event-safe implementation uses an atomic <code>GOT_IP</code> latch so even a short initial connection before the 10-second MQTT status sample cannot skip the required boot NTP request. The final Heltec V4 MQTT Observer application is 1,853,304 bytes with SHA-256 <code>1938ae88fcdbe601cf8698df44b548656079562d899801886b808af913e5f9ac</code>. The consolidated Full V4 image used 2,250,801/6,553,600 flash bytes and left 4,302,799 bytes of app-image space. Its 2,251,272-byte application image has SHA-256 <code>05131eac29164be46d1bcceeb4f03455f5ea8d61c8d4f529b77d8adfe25fdb6a</code>; the 2,316,808-byte merged image has SHA-256 <code>c4c1fc639b6d0087c795a81aca79c07eba56dc4e071eb374dc70da0bec81815e</code>. The focused daily-NTP policy suites passed all 42 cases after the latch was added, and the Full capability manifest verified all ten expected features. The reduced RAK3401 LoRa-OTA Repeater also compiled with the verified WisBlock I2C aliases. At that source state its link used 471,344/815,104 flash bytes; the reduced external-sensor contract retains INA219/INA226/INA260/INA3221 as the voltage/current entries in the optional environmental-telemetry table. These are not the image's only I2C consumers. The image separately retains its SSD1306 display, auto-discovered I2C RTCs, RAK12500 I2C GPS, and RAK12501/L76K UART GPS paths. The configured INA3221 and RAK12500 both default to I2C address <code>0x42</code>; those two devices cannot coexist at those addresses. The supported combined arrangement leaves RAK12500 at <code>0x42</code>, straps INA3221 A0 to SCL for <code>0x43</code>, and uses a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>. The nRF52840 die-temperature and ADC battery-voltage paths are also retained. The 472,227-byte DFU ZIP SHA-256 is <code>fdd369005a61635756efa9e38b217376a952f334b0864f927a46799b65264fa9</code>, and the matching 943,104-byte UF2 SHA-256 is <code>2155632fde730e0ae2e4a72ce64f89910861f6c5105a4bd7ac96aaa538a33dca</code>. These VM results do not replace the remaining exact-final hardware test with UDP/123 blocked.</p> <p>The later serialized RAK3401 contract build, after the non-blocking nRF52 USB logging change, used 471,576 bytes before its 56-byte EndF trailer. Its EndF body hash is <code>026749684bf6ee8f</code>, target ID is <code>2FA509C1</code>, hardware ID is <code>RAK_3401</code>, and version word is <code>0x01110105</code>. The 472,435-byte DFU ZIP has SHA-256 <code>cf0880b26f2d6bd8157f8af76a6718fe1f998de8ea7df8cd952e734448201fb9</code>; the 943,616-byte UF2 has SHA-256 <code>f893a8cebf309af12a4a6f5483acb28f94158e18632f660e011658c846e8ca7f</code>. The linked ELF contains GPS, SSD1306, RTC, and the four INA families, while an exact symbol audit finds none of AHT10/20, BME280, BMP280, SHTC3, SHT4X, LPS22HB, MLX90614, VL53L0X, BME680/BSEC, BMP085, or RAK12035. The complete native matrix passed 1,112/1,112 cases at that intermediate source state. These are VM gates only; flash the exact artifacts and repeat the physical peripheral and blocked-clock checks before marking any later source state hardware-qualified.</p> <p>Subsequent source hardening changed RAK peripheral discovery: the shared 3V3_S rail remains enabled, UART GPS requires a complete checksum-valid NMEA sentence, an exact INA3221 identity blocks a conflicting u-blox probe, and a successful I2C GPS claim suppresses a sensor only on the same bus and address. The hashes and sizes above describe their recorded intermediate artifacts; they are not current-HEAD evidence and must not be reused for the hardened source.</p> <p>The immutable font endpoint was re-probed only after the VM reported <code>NTPSynchronized=yes</code>. GitHub returned HTTP 206 for bytes <code>0-65535</code>, an exact 65,536-byte match to the checked-in font (range SHA-256 <code>8b0dd308eb01469d1f9e732fba260720a80cc86f6cb5385c28e8a16c76dcfbf3</code>), with total length 1,302,608 and strong ETag <code>\"39ff0cfbe37e36905507697d042869c05374c3202dd96d5a9f98812153f324c1\"</code>. This validates the current strict Range assumptions against the live service; the exact-final Indicator still needs the negative hardware run proving that blocked UDP/123 prevents every TLS request and RP2040 staging write.</p> <p>Mercerwood subsequently recovered without a target write. Both its Tailscale and LAN addresses again accepted SSH, Bluetooth was idle, and the exact T1000-E stable serial <code>34A9141999729D5D</code> was present as application USB <code>239a:8029</code>. The RAK3401 simultaneously uses the same VID/PID, which confirms that every continuation must resolve the stable serial/by-id identity rather than VID/PID. The T1000-E remained in the exact bonded Full Companion application; no stale DFU, scanner, <code>meshcli</code>, or HCI-capture process was running.</p> <p>The post-reboot seven-TTY inventory was also resolved without assuming that one board owned adjacent device names. <code>ttyUSB0</code> is the SenseCAP Indicator's ESP32-S3 CH340 UART and <code>ttyACM5</code> is its RP2040; their sibling physical USB paths and the Indicator's live TCP board reply agree. The separately attached <code>ttyACM4</code> is the MeshTower V2 native <code>HT-n5262</code> endpoint and returned the qualified MeshTower build over its own console. The remaining ACM endpoints independently identify the RAK3401, XIAO nRF52840, Heltec V4, and T1000-E.</p> <p>ModemManager had restarted after the Pi reboot and could probe otherwise idle radio consoles. Six serial-bearing boards now use stable-serial-only <code>ID_MM_DEVICE_IGNORE</code> rules. Because the Indicator CH340 has no stable serial, its separate rule requires the exact current physical port chain and exact <code>1a86:7523</code> identity; there is no broad CH340, product, or VID/PID-only rule. A controlled ModemManager restart reported zero modems, displaced no TTY owner, caused no USB disconnect/re-enumeration, and left all seven endpoints ignored. The same mctomqtt process retained sole ownership of the RAK, while a subsequent Indicator TCP query still returned the expected board and build. Reversible root-only backups were retained on the Pi before each rule update.</p>"},{"location":"hardware_validation_checklist/#run-wide-gates","title":"Run-wide gates","text":"<ul> <li>[ ] Record commit, version string, role/profile, artifact filename, size, and       SHA-256 before flashing.</li> <li>[ ] Archive the exact ELF and symbol/objdump map beside each qualification       firmware. A rebuilt ELF is acceptable for diagnosis only after its       firmware binary matches byte-for-byte; compiler <code>__DATE__</code>/<code>__TIME__</code>       strings can otherwise change both bytes and the EndF body hash.</li> <li>[ ] Bind every operation to a stable USB serial number or physical USB path;       never rely on a changing <code>ttyACM</code>/<code>ttyUSB</code> number.</li> <li>[ ] After erasing/reflashing a BLE board that reuses its Bluetooth address,       remove any stale host bond and pair again with the board's current PIN       before diagnosing service-discovery disconnects. On Linux, verify the       BlueZ agent actually accepted the passkey; a scanner seeing the device is       not proof that Companion GATT is usable.</li> <li>[ ] Do not use BlueZ's advertisement <code>service_uuids</code> as a same-address warm       handoff identity gate. After application/bootloader transitions BlueZ can       merge the bootloader's cached GATT UUIDs into the live application's       advertisement. Gate the application advertisement by exact address and       name, then require the live connected BLEDfu service, control/revision       characteristics, retained bond/encryption, notification subscription,       and observed target disconnect before accepting the handoff.</li> <li>[ ] Do not treat <code>meshcli -P</code> as an infallible pairing probe. Immediately       after one successful post-DFU session, a second invocation with the exact       paired XIAO address hit the meshcore-cli <code>NoneType ... pair/disconnect</code>       path before it created a Bleak client. BlueZ still reported the exact       bond and the same command without <code>-P</code> connected and synchronized the       clock successfully. Capture this as a host-tool failure, then verify the       device independently before blaming firmware.</li> <li>[ ] After a successful <code>BleakClient.connect()</code>, start a fresh disconnect       generation before beginning DFU. BlueZ can fail one internal LE attempt,       retry successfully, and still deliver the failed attempt's callback. A       stale event caused the host to stop notifications and issue a local HCI       disconnect after a valid image CRC but before ACTIVATE; the target and       bootloader had not dropped the link. Preserve an HCI trace through       activation so local-host and remote-target disconnects remain       distinguishable.</li> <li>[ ] Before a BLE pairing/throughput test on a Wi-Fi-managed Pi, record both       management addresses and a same-LAN recovery vantage point. The XIAO       pairing run completed, but Mercerwood then stopped answering on both its       Wi-Fi and Tailscale addresses; BellevueBBS confirmed the old LAN address       was absent at ARP and no replacement LAN host exposed SSH. This is an       infrastructure outage until Pi logs prove a cause, not a firmware or BLE       failure. The T1000-E pairing run reproduced the management outage: its       exact application paired successfully and exposed the complete DFU       service, then Mercerwood stopped accepting SSH and ultimately stopped       answering Tailscale pings. No buttonless DFU write had been sent, and the       T1000 remained in its valid application. Capture Pi Wi-Fi/firmware logs       after recovery and avoid leaving discovery enabled between operations.</li> <li>[ ] Confirm the selected board and role before every erase or flash.</li> <li>[ ] Before every SWD write, read the target FICR device ID and match it to the       intended board's stable USB serial (and physical wiring record). A USB       product name or remembered cable position is not sufficient.</li> <li>[ ] Confirm no other PlatformIO process is active; run only one PlatformIO       build, test, clean, or upload at a time.</li> <li>[ ] Record the installed bootloader, SoftDevice, partition table, or flash       layout independently of the application banner where applicable.</li> <li>[ ] Test both a software reboot and a real power removal/cold boot.</li> <li>[ ] After an update, read back identity, version, radio tuple, node name, and       persistent settings instead of assuming they survived.</li> <li>[ ] Save command output and elapsed milliseconds. Mark a test <code>FAIL</code>, not       <code>PASS</code>, if the transport reports an I/O error even when firmware later       boots.</li> <li>[ ] Before calling a node hung, validate that the probe uses that profile's       command terminator, check a second transport, and capture PC/LR/watchdog       state over identity-gated SWD before reset. Resume once and retest before       using reset as recovery so the diagnostic state is not destroyed first.</li> <li>[ ] Treat a remote login acknowledgement and the following command reply as       separate LoRa packets. A lost login acknowledgement is not proof of       failed authentication when a command-matched private reply from the       selected contact key is present; an explicit negative login result still       fails closed.</li> <li>[ ] Restore the intended USA radio preset and normal-radio mode after tests.</li> <li>[ ] Compare both semantic version and exact EndF/body hash. A transition       between two commits carrying the same version string must stop at the       normal reinstall guard unless the run plan explicitly records and passes       <code>--allow-non-upgrade</code>; a different commit name alone is not authorization.</li> <li>[ ] Do not allow a non-interactive transmission-failure prompt to continue       retry cycles forever. Optional capability probes must fail/fall back after       a bounded interval, while mutations and cleanup retain their stronger       bounded-lease recovery rules.</li> <li>[ ] Before the first remote command after any controller/source reboot, read       its RTC and compare it with a trusted host clock. Advance a clock which is       behind and prove readback; never move a radio clock backward. Fail closed       when it is more than 10 minutes ahead. During the RAK rehearsal the V4       rebooted to <code>2026-03-01</code> while the RAK remained at <code>2026-08-30</code>; the RAK       received the direct packets but correctly rejected their old timestamps       as replays. Setting the V4 to host epoch immediately restored login and       the exact public-key reply at SNR -1.5 dB.</li> <li>[ ] Before every external HTTPS download, require a fresh SNTP response for       that bounded operation, a plausible signed wall clock, connected Wi-Fi,       and a non-expired proof immediately before opening TLS. Re-check the proof       before every resumed/Range TLS connection. A retained plausible RTC or       mesh time is not a substitute for observing NTP, and failure must occur       before any HTTP request body or flash writer begins.</li> <li>[ ] Treat an unacknowledged immediate <code>tempradio</code> mutation as potentially       active, not merely lost. On the tested repeater, scheduled-radio expiry       deliberately waits for <code>hasOutbound()</code> to clear; a CLI reply stranded on       the temporary tuple can therefore hold the node there beyond its nominal       lease. Prefer one fixed absolute <code>tempradioat</code> window per node, so duplicate       delivery cannot extend it, and prove the return on both tuples before a       transfer. If recovering an older immediate handoff, join the exact       temporary tuple to drain the reply before issuing <code>normalradio</code>.</li> <li>[ ] Do not diagnose a co-located high-power LoRa bench failure as weak RF       without an overdrive check. On the RAK3401/V4 bench, the RAK at 22 dBm       produced only 3/6 status replies around -1.5 dB SNR, while a reversible       0 dBm setting produced 6/6 replies in 5--8 seconds at +12 to +12.5 dB       SNR. Read the original power, lower it only for the near-field test, and       require exact restoration afterward.</li> </ul>"},{"location":"hardware_validation_checklist/#compute-placement-gate","title":"Compute-placement gate","text":"<ul> <li>[ ] Run firmware builds, PlatformIO, mOTA/delta generation, compression,       full-image hashing sweeps, symbol generation, and other sustained CPU or       memory work on the VM. Do not offload these jobs to a Pi merely because       the hardware and source artifacts are attached there.</li> <li>[ ] Use the Mercerwood Pi as the identity-gated hardware gateway, SWD/USB/BLE       test host, and LoRa/Wi-Fi seeder. Copy only the completed artifact plus       its manifest/hash to the Pi, then verify the copied SHA-256 before use.</li> <li>[ ] Run CPU work on a Pi only when Pi performance or deployment behavior is       itself the test subject, and label that exception in the run log.</li> <li>[ ] Do not assume a non-interactive SSH session has the same <code>PATH</code> as an       interactive shell. Resolve pipx-installed tools such as esptool and       detools to their explicit venv path, record the version, and fail before       erase if the pinned executable is unavailable.</li> <li>[ ] Treat short serial/BLE/SWD control scripts on the Pi as hardware I/O, not       as permission to generate artifacts there. Use the explicit Python from       the relevant pipx environment when a probe needs one of its dependencies;       the Pi system Python did not contain <code>pyserial</code> during the RAK run.</li> </ul>"},{"location":"hardware_validation_checklist/#lora-controlled-host-recovery-gate","title":"LoRa-controlled host recovery gate","text":"<ul> <li>[x] The privileged recovery boundary is a root-owned, group-restricted       AF_UNIX broker with a fixed command grammar and fixed <code>systemctl</code> argv.       The unprivileged MQTT endpoint cannot gain privileges under       <code>NoNewPrivileges</code>, cannot select an executable or unit, and commits an       action only after its signed challenge/reply has been published and       confirmed. The installed broker passed its cold activation, peer       credential, socket owner/mode, injection, duplicate, timeout, durable       reservation, and ambiguous-outcome checks.</li> <li>[x] A signed <code>host network restart</code> was accepted exactly once in 4.088       seconds. The broker retained one <code>network-restart</code> record at sequence 1,       and the fixed unit journal had exactly one start/finish pair. Independent       management probing measured 7.184 seconds from last successful probe to       first recovered success and 6.314 seconds from first failure to recovery.       Pi-local loopback MQTT delivered 107/107 samples; mosquitto, mctomqtt,       and the endpoint retained their exact PIDs, and mctomqtt remained the sole       owner of the RAK USB port. One read-only LoRa status reply was lost at the       temporary 0 dBm bench setting, then authenticated status returned       <code>scheduled</code>; no mutation was replayed. One monitor parsed two       <code>systemctl --value</code> columns in reverse order, so its boolean labels are       discarded; its PID/MQTT trace and the independent postchecks remain       valid.</li> <li>[x] A signed <code>host reboot</code> was accepted exactly once in 3.312 seconds and       armed the fixed 10-second timer. A changed boot ID and one observed       outage prove one reboot; management recovery took 35.763 seconds from       the last pre-outage success and 31.276 seconds from the first failed       probe. Postboot signed LoRa uptime replied in 3.651 seconds. All seven       exact USB identities returned, only the RAK port was owned, the deployed       configuration hashes were unchanged, and NetworkManager, Tailscale,       mosquitto, mctomqtt, the endpoint, and both privileged sockets were       active. Broker action state is intentionally under <code>/run</code> and persistent       journaling was unavailable, so exactly-once evidence is the accepted       reply, one boot-ID transition, one outage, an inactive timer, and no       second outage; do not claim a durable postboot operation record.</li> <li>[x] Reboot auto-started the still-enabled ModemManager service, but all seven       exact devices retained <code>ID_MM_DEVICE_IGNORE=1</code>, zero modems appeared,       and no TTY was probed or claimed. The service was returned to its       pretest inactive state without disabling or masking it. The RAK then       passed exact identity/body/radio gates; an explicit radio-busy rejection       left TX at 0 dBm, one bounded idempotent retry after idle returned OK,       and authenticated readback proved exact restoration to 22 dBm. V4       identity, power-saving, RXPS, TempRadio, and seeder state also matched       their pretest values.</li> </ul> <p>The sanitized host-recovery evidence bundle is under <code>out/host-actions-live-20260831/</code>. Its <code>SHA256SUMS</code> manifest has SHA-256 <code>5acff71ed98f483bb769e8c99c577bf358d0491355ac72855ee7093cd658bf21</code>, and <code>sha256sum -c</code> verifies every deployed-hash, pre/post-state, radio, OTA, network, and reboot record in that manifest.</p>"},{"location":"hardware_validation_checklist/#mercerwood-pi-usb-power-cycle-gate","title":"Mercerwood Pi USB power-cycle gate","text":"<ul> <li>[ ] Confirm the Pi is reachable through Wi-Fi/Tailscale and that <code>eth0</code> is not       the active management path before cycling its downstream USB tree.</li> <li>[ ] Stop all flashes/transfers, run <code>sync</code>, and release SWD GPIO 8 and GPIO 11       to inputs with no pulls before removing USB power. This prevents an SWD       signal from partially back-powering an otherwise unpowered nRF52.</li> <li>[ ] Never issue a standalone <code>uhubctl ... -a off</code> to Pi root hub location <code>1</code>.       Once its only port is off, the hub disappears from <code>uhubctl</code> discovery and       a separate <code>-a on</code> command fails with <code>No compatible devices detected at       location 1!</code>. This has interrupted two hardware runs.</li> <li>[ ] A downstream hub may be cycled only after resolving the board's stable       USB serial to an exact sysfs path and proving that hub advertises       per-port power switching. Record the hub location and port, cycle only       that port, and gate the re-enumerated VID/PID/serial before continuing.       The T1000-E qualification safely used child hub <code>1-1.2</code>, port 3; this is       not permission to cycle the ganged root hub at location <code>1</code>.</li> <li>[ ] Do not use <code>uhubctl</code> <code>off</code>, <code>on</code>, or atomic <code>cycle</code> on Mercerwood root       hub location <code>1</code>. Physical testing showed that even one atomic <code>cycle</code>       powers the ganged root hub down and then cannot rediscover it to restore       power. Use a planned Wi-Fi-issued <code>sudo reboot</code>, which is the verified       recovery, or arrange a true upstream VBUS removal when that distinction       is part of the test.</li> <li>[ ] Treat root hub <code>1</code> as a ganged operation: every attached test board and USB       Ethernet adapter loses power. After recovery, enumerate every stable       <code>/dev/serial/by-id</code> identity again before resuming any board-specific test.</li> <li>[ ] On this heavily populated root hub, inspect kernel logs for real transfer       faults before and after a flash, and stop ModemManager while it could open       a test TTY. A CH340/ESP32-S3 write which lost the chip at 460800 baud       completed and verified at 115200 after a planned Pi reboot; start at the       board-qualified conservative rate rather than treating a fast partial       transfer as firmware failure.</li> <li>[ ] Under non-interactive SSH, do not let <code>udisksctl</code> fall through to an       interactive polkit password prompt. After resolving the exact UF2 block       device by board serial, either use an already-mounted volume or an       explicit <code>sudo -n mount</code> at a board-specific mount point; re-check       <code>INFO_UF2.TXT</code> model/version before copying.</li> </ul>"},{"location":"hardware_validation_checklist/#seeed-xiao-nrf52840","title":"Seeed XIAO nRF52840","text":"<ul> <li>[ ] Stable USB identity distinguishes application (<code>2886:8044</code>) from UF2       bootloader (<code>2886:0044</code>).</li> <li>[ ] Do not repeat the known-failing full-application UF2 copy under the       installed initial 2.4.4 candidate. The identity-gated 897,024-byte copy       returned exit 0, then <code>sync -f</code> failed with <code>EIO</code> in 850 ms; the kernel       logged an offline device, lost queued writes, and FAT errors before USB       disappeared. Recover through a separately hash-gated BLE/serial path and       qualify a corrected bootloader candidate before retrying UF2.</li> <li>[ ] SWD readback exactly matches the intended bootloader-region SHA-256.</li> <li>[ ] Actual SoftDevice FWID and runtime application base match the artifact       (<code>S140 7.3.0</code>: FWID <code>0x0123</code>, application base <code>0x27000</code>).</li> <li>[ ] Exercise and independently verify the exact-board combined       bootloader+SoftDevice recovery path before relying on it in the field.       A wrong-layout nRF52840 application can overwrite part of S140 while the       UF2 bootloader still accepts files and the application still reads flash;       internal writes or <code>InternalFS.format()</code> may then hang or reboot. An       application-only UF2 and a filesystem erase cannot repair that state.       The known XIAO incident in upstream issue #3284 recovered only after the       matching Sense/non-Sense OTAFIX bootloader+S140 ZIP was installed. Keep       board identity, SoftDevice FWID, application base, and package contents       as four separate pre-write gates.</li> <li>[ ] Invalid settings enter persistent UF2 recovery after a cold boot.</li> <li>[ ] UF2 application copy returns success; <code>sync -f</code> returns success; the host       has no offline-sector, lost-write, or FAT I/O errors.</li> <li>[ ] Application enumerates after update and reports the expected board,       version, role, and radio tuple.</li> <li>[ ] Legacy serial DFU crosses all application pages, emits the exact       <code>Device programmed.</code> success marker, and rejects false-success output.       Two application serial-DFU attempts on this board timed out waiting for       the start ACK while <code>adafruit-nrfutil</code> still returned exit 0, so exit       status alone is explicitly insufficient.</li> <li>[ ] Legacy BLE DFU verifies each cumulative PRN receipt exactly and fails on       a missing, short, regressive, or overreported offset; it may adapt       only among the packet-size-specific safe receipt windows after timely       exact receipts and must step back down on slow exact receipts. Final       application/SoftDevice/bootloader CRC and a peer disconnect are mandatory       before declaring success.</li> <li>[ ] Every upward PRN move is a bounded adjacent-level probe. A failed probe       or a later real demotion blocks further increases for that transfer, while       additional slow exact receipts may still negotiate down one level at a       time. This prevents <code>4 -&gt; 8 -&gt; 4 -&gt; 8</code> churn without disabling a safe       initial probe or a <code>32 -&gt; 16 -&gt; 8</code> fallback.</li> <li>[x] The exact Full Companion ZIP       <code>Xiao_nrf52_companion_radio_full-v1.17.1.5-halo-keymind-cascade-3caf9dcf.zip</code>       (SHA-256 <code>9a916c1a3ea83d8f6dd704465fe9c044a363478f852a4369cf6b13424a7a9430</code>)       installed over BLE in 237,297 ms at about 2,110 B/s using ATT MTU 247,       244-byte writes, PRN 4, and exact cumulative receipts. Validate and the       target-initiated disconnect passed. USB then reported the exact expected       version/hash, USA radio tuple, key, RXPS policy, and reversible       Terminal/Binary mode; the new application advertised NUS as       <code>MeshCore-4610BBD2</code>.</li> <li>[x] The post-update application was paired through BlueZ with the expected       PIN. Companion GATT then returned the same public key, USA radio tuple,       22 dBm limit, non-repeater role, board, and build over BLE. Its RTC was       18,038 seconds behind the trusted host; <code>clock sync</code> advanced it and the       immediate readback was within one second of the host interval. No       backward clock write was performed.</li> <li>[x] A second exact same-image update exercised application buttonless DFU and       retained-peer bootloader entry. The bootloader deliberately reused the       bonded application address <code>E5:C3:A8:B0:60:66</code> rather than the cold-entry       address ending in <code>:67</code>; exact name, Legacy DFU service, and DIS model       gates still passed. The first adaptive threshold remained at PRN 4 and       completed all 448,416 bytes at about 877 B/s in 527,832 ms; validate,       target disconnect, USB identity, application key, role, and USA radio       readback all passed. The application clock was then about 10 minutes       behind because its RTC did not advance during the bootloader transfer;       it was advanced to the host clock and proved by immediate readback.</li> <li>[x] A third same-image A/B run used bounded neutral-window exploration. At       244-byte writes, two exact neutral PRN-4 receipts triggered one adjacent       PRN-8 probe. PRN 8 measured about 845 B/s against an approximately       879 B/s PRN-4 baseline, so the helper rolled back to PRN 4 after two       receipts and never re-probed. All 448,416 bytes completed at about       870 B/s in 531,804 ms; CRC validation, target disconnect, USB return,       exact Companion key/role/radio readback, and post-DFU forward clock sync       passed. This proves up/down sender-window adaptation and no churn, while also showing       that PRN receipt overhead is not the bonded-path bottleneck on this run.</li> <li>[x] A bootloader candidate built from exact ZIP SHA-256       <code>9c70200fc15a315a50ec68d2a905b5bcf2fc07a796a21fbd439535ec19a608be</code>       disabled inherited slave latency locally during DFU DATA. The controller       trace still reported the peer-negotiated 30 ms interval and latency 4,       with no connection-parameter update after START; the change is therefore       a local event-attendance override, not a GAP speed renegotiation. A cold       address-generation control completed 448,416 bytes at 2,231 B/s and       passed validation/activation in 226,103 ms.</li> <li>[x] Two subsequent bonded application-to-bootloader runs completed the exact       same 448,416-byte image at 3,524 and 3,534 B/s. Their complete elapsed       times, including exact application advertisement proof, buttonless       handoff, bootloader scan, erase, DATA, CRC validation, activation, and       reboot, were 169,414 and 169,221 ms. Both targets initiated the final       disconnect; USB returned as stable serial <code>B35E71C1C3726CE7</code>; the public       key, 22 dBm setting, USA <code>910.525/62.5/SF7/CR5</code> tuple, board, and build       read back exactly. Compared with the prior roughly 877 B/s bonded run,       the DATA rate improved by about 4.0x without increasing the PRN window       beyond 8.</li> <li>[x] An exact bonded B-A-B link-profile sequence used the same Full Companion       ZIP SHA-256 <code>9a916c1a3ea83d8f6dd704465fe9c044a363478f852a4369cf6b13424a7a9430</code>,       lab helper SHA-256 <code>4909c617de37b5666cc622b7190568f002280f55bf26a05843ea283f2be8f566</code>,       handoff helper SHA-256       <code>1bad570173079b623bbe2bbb9e5ba7c4f8ac379bf966bfd4382c5266fb9fd214</code>,       stable USB serial, bonded address, and 448,416-byte application throughout.       First B, <code>xiao-ble-event-length-prestart-20260830-072641-W7COxm</code>, used one       exact pre-START 15 ms/latency-0 update with <code>0/0</code> no-preference event-length       hints and completed DATA in 72.030 seconds at 6,225 B/s; DFU through target       disconnect was 102.792 seconds and the full workflow was 117,064 ms.       Control A, <code>xiao-ble-control-prestart-20260830-073149-yKf0lO</code>, requested no       update, retained the bootloader connection's 30 ms/latency-4 link, and       completed DATA in 134.131 seconds at 3,343 B/s; DFU was 165.137 seconds and       the full workflow was 182,624 ms. Final B,       <code>xiao-ble-exact15-prestart-20260830-073554-FuGPfH</code>, repeated exact 15 ms and       completed DATA in 71.970 seconds at 6,231 B/s; DFU was 102.799 seconds and       the full workflow was 117,179 ms. Both B rates were about 1.86x control and       differed by only 0.096%.</li> <li>[x] The B-A-B protocol and link gates passed independently. Both B runs probed       PRN 4 -&gt; 8 after an exact 0.135-second four-packet receipt, rolled back       once to PRN 4 after the exact 0.345-second eight-packet receipt, and never       re-probed. Control A likewise probed after 0.269 seconds and rolled back       after 0.600 seconds. Each B bootloader connection had exactly one matching       HCI Update Complete before START; control A had no bootloader-connection       update. All three captures contained zero connection updates from START       through DATA, CRC validation, activation, and the target-initiated       disconnect. Each run ended <code>RESULT=PASS</code>, <code>RC=0</code>, <code>STAGE=complete</code>; final B       returned the exact Full Companion application as USB <code>2886:8044</code>, stable       serial <code>B35E71C1C3726CE7</code>, with current application name       <code>MeshCore-4610BBD2</code>. A fresh post-B binary Companion query independently       re-gated the unchanged public identity, name, Full Companion role, 22 dBm       power, and USA <code>910.525/62.5/SF7/CR5</code> radio tuple. A separate bonded BLE       application query then returned the same board, build, and Full Companion       role, so the USB return did not mask a broken Companion BLE path or stale       bootloader alias.</li> <li>[x] The current host-controller ceiling is independently characterized. The       Pi Zero 2 W Broadcom UART controller reports HCI/LMP 4.2 but supports only       LE 1M; LE Read Maximum Data Length and Read Suggested Default Data Length       both return Unknown HCI Command. The final B capture contains 1,837 full       244-byte firmware writes,       each split into ten 27-byte HCI ACL fragments; all 18,425 transmitted ACL       fragments received completed-packet accounting. The median full-write gap       was 29.947 ms at 15 ms versus 59.936 ms in control A. A BLE 5 controller       with working Data Length Extension is therefore the next host-side speed       experiment; this built-in controller cannot exercise DLE or LE 2M.</li> <li>[x] The host helper now clears a disconnect callback left by an unsuccessful       internal BlueZ connection attempt only after <code>connect()</code> has returned a       live link, and labels PRN changes as adaptation rather than link       negotiation. All 81 strict host tests pass. The first physical run before       this fix still proved the 3,520 B/s DATA rate and returned a successful       validation response, but is correctly recorded as FAIL because the stale       host event prevented ACTIVATE.</li> <li>[ ] Warm app-to-bootloader handoff is tested with the application watchdog       active; cold recovery is tested separately.</li> <li>[ ] BLE Companion/recovery behavior and radio-reset recovery are exercised.</li> <li>[x] The post-Pi-recovery application still enumerated as exact       <code>2886:8044</code> / <code>B35E71C1C3726CE7</code>, but one identity-gated, bounded USB       Binary Companion attempt received no protocol response. <code>meshcore-cli</code>       1.6.0 printed both of its no-response error lines and nevertheless exited       zero; the supervisor treated the attempt as a failure and independently       proved that no process retained the serial port. The exact terminal-stop       token and an identity/path-gated USB bus reset also failed, which excludes       an ordinary startup Terminal-mode hold and host USB endpoint state. The       external tool defect remains in upstream <code>meshcore-cli</code> 1.6.3: its serial       creation failure returns normally, so callers must validate command output       instead of trusting exit zero. The LoRa-OTA controller has an exact       three-diagnostic regression and continues to fail closed.</li> <li>[x] An exact hash-recorded Full Companion application DFU erased/replaced only       the application and completed in 36 seconds. The transferred ZIP was       440,083 bytes with SHA-256       <code>9946b8417c389784ac92c20e4ce5cf0b6a0123a58136627c0689815637f96992</code>.       The same stable USB serial returned as interface <code>00</code>; USB and the existing       bonded BLE identity both reported <code>Seeed Xiao-nrf52</code>, the 31-Aug-2026       build, and Companion role. Preserved settings included a roughly six-month       stale clock, which Binary Companion <code>clock sync</code> advanced to one second of       the Pi without changing the role.</li> <li>[x] The recovered application passed explicit Terminal start/stop, exact board       query, saved <code>usb.logging off</code>, source-only OTA status, and a real serial       <code>motatool serve</code> attach/detach with an empty folder (<code>COUNT -&gt; 0</code>). Binary       Companion returned after both terminal and mOTA ownership. Enabling USB       logging and rebooting produced exact interfaces <code>00</code> and <code>02</code>; interface       <code>02</code> emitted 123 bytes of entirely printable log data while Binary       Companion stayed usable on <code>00</code>. Disabling and rebooting removed <code>02</code>,       restored the single-interface descriptor, and read back logging off.</li> <li>[ ] A physical power-removal cold test is still needed to prove persistence of       the current application. It cannot retrospectively determine whether a       power cycle alone would have cleared the original stall. Answer that only       after reproducing the stall under a bounded stress loop, capturing state,       and power-cycling before any DFU. The application DFU proves recovery but       intentionally does not claim the underlying stall trigger is fixed.</li> </ul>"},{"location":"hardware_validation_checklist/#seeed-tracker-t1000-e","title":"Seeed Tracker T1000-E","text":"<ul> <li>[x] The cross-role <code>uf2reset</code> repair was hardware-qualified with Full       Companion ZIP SHA-256       <code>16e470c0d66bec14e1e9f2d4ebe04d83ffb30efa606465f885cbe9fc3d004a14</code>.       It was built from <code>f2c15225</code> with GCC 14.2.1, the USA Cascadia/Cascade       profile, and embedded version       <code>v1.17.1-uf2reset-f2c15225-f2c15225</code>. Serial DFU took 32.196 seconds and       stable application USB returned in 35.888 seconds. Terminal entry,       version, help, the exact no-argument command, application disconnect, and       stable <code>2886:0057</code> boot USB all passed in one 8.898-second script. The same       image was restored in 32.204 seconds and stable <code>239a:8029</code> USB returned       in 36.313 seconds; a final terminal check returned Binary mode cleanly.</li> <li>[x] The fixed application advertises live as <code>MeshCore-09848C15</code> at       <code>D1:A0:86:CD:BB:C6</code>. The obsolete Pi bond for the earlier temporary       identity was removed, and the exact address was paired again with the       qualification PIN. Paired, bonded, and trusted state, an encrypted BLEDfu       revision read, and the Nordic UART service all passed. The pre-run old       application enumerated but produced neither a terminal response nor a       live advertisement, so this run does not claim continuity of that       temporary identity or of application-owned settings across a combined       SoftDevice/bootloader recovery install.</li> <li>[x] Stable application identity <code>34A9141999729D5D</code> is recorded and is not       confused with the RAK3401 even though both currently enumerate with USB       product ID <code>239a:8029</code>. Application is <code>239a:8029</code>; the exercised       bootloader is <code>2886:0057</code>, with the same stable serial and exact       <code>T1000-E</code>/<code>T1KE_DFU</code> model/name gates.</li> <li>[x] A post-Pi-recovery, identity-gated, read-only USB Companion query returned       the exact T1000-E model, non-repeater Full Companion role, 22 dBm maximum,       and <code>910.525/62.5/SF7/CR5</code>. Its clock readback was within the query's       few-second host interval. No clock, radio, role, key, or settings write       was issued.</li> <li>[ ] Board, version, repeater role, bootloader status, and USA radio tuple are       correct after erase/install and after reboot. The live baseline and a       2,184 ms software reboot passed: <code>3caf9dcf</code>, <code>Seeed Tracker T1000-E</code>, 22 dBm,       <code>910.525/62.5/SF7/CR5</code>, OTA target <code>7B071FA0</code>, bootloader       <code>0.11.0-OTAFIX2.4.3</code>, and full OTA base hash       <code>3E92B157128B6963</code>. A real power-removal boot is still required.</li> <li>[ ] UF2 and serial DFU installation paths complete without host I/O errors.       On OTAFIX 2.4.3, an identity-gated root copy of the exact old UF2 returned       success in 112 ms, but the device disconnected before host writeback was       durable: <code>sync -f</code> failed with <code>EIO</code> after 17,695 ms and the kernel logged       lost asynchronous writes/FAT read errors. The old application happened to       boot and retained its settings, but this transport is a FAIL. Retest       with the corrected 2.4.4 candidate before qualifying T1000-E UF2.</li> <li>[x] The installed <code>t1000e_repeater_lora_ota_no_external_sensors</code> profile does       not compile the Companion BLE transport and did not advertise during a       post-reboot BlueZ scan; that is expected for this repeater image. BLE       Companion qualification belongs to the separate T1000-E Companion build.</li> <li>[x] The exact latency-disable bootloader candidate ZIP (SHA-256       <code>ebe9739ce40c2c7cc1f52076f9614194959fcf6df93d37666b69b7bd415fab68</code>)       installed through identity-gated serial DFU. The final output contained       exactly one terminal <code>Device programmed.</code> success line, the bootloader       returned as <code>2886:0057</code>, and its embedded manifest identifies       <code>T1KE_DFU</code>, S140 7.3/FWID <code>0x0123</code>, application base <code>0x27000</code>, and test       version <code>0x02040403</code>.</li> <li>[ ] The later connection-policy-reapply combined ZIP (SHA-256       <code>c2de1fb2704154b4abc371b6b4827c32ad09c4d15f3f6d97d0f4182bb51fff58</code>)       was identity-gated, transferred, validated, activated, and returned as       exact <code>2886:0057</code> recovery USB. <code>INFO_UF2.TXT</code> reported       <code>0.11.0-OTAFIX2.4.3-3-gffb1580-dirty-test-version-0x02040403</code>, S140       7.3.0, and the T1000-E board. The earlier and later candidates share the       same visible version string, however, so package sequencing and INFO_UF2       do not independently prove the installed bootloader bytes. Require an       identity-gated live bootloader-region readback or a uniquely versioned       rebuild before checking this item.</li> <li>[x] The combined-image BLE transport itself passed: 193,688 bytes at       3,331 B/s, target CRC validation, and target-initiated activation. The       package contains SoftDevice plus bootloader and <code>APP=0</code>, so remaining in       recovery USB was the correct postcondition. Its first supervisor record       is not accepted as run-level evidence: TERM inherited status zero and       wrote a false <code>PASS</code> at <code>STAGE=post_copy_usb</code>. A separate audit records       the transport result, and all later wrappers map INT/TERM to nonzero and       refuse <code>PASS</code> unless <code>STAGE=complete</code>.</li> <li>[x] A separate exact application recovery after that combined transfer       completed 404,468 bytes at 2,095 B/s, validated, activated, and returned       stable application USB in 225,899 ms. The lower rate is the expected       cold/unbonded class, not the bonded warm baseline.</li> <li>[x] A cold exact Full Companion application ZIP (SHA-256       <code>b3be000ab2391527a325cc868e2706dec291c167b6e6cd3495908addb8af6c65</code>)       completed all 404,468 DATA bytes over BLE at 1,572 B/s. The complete       workflow took 281,236 ms (about 1,438 B/s end to end, including setup,       validation, activation, and reboot). ATT MTU reached 247, but BlueZ's       independently cached maximum write size was still 20, so the       identity-gated helper correctly used 20-byte packets, adapted PRN       8 -&gt; 16 -&gt; 32, validated CRC, activated, observed the target-initiated       disconnect, and gated the exact USB application return.</li> <li>[x] The Full Companion application advertised as <code>MeshCore-F9AD7082</code> at the       expected address generation, paired with the qualification PIN, and       exposed its bonded, MITM-protected Legacy DFU service after connection.       That DFU service is intentionally absent from the advertisement, so an       advertisement-only check is insufficient. A 1200-baud USB touch instead       selects serial-only DFU and correctly produces no BLE advertisement;       use the bonded application control characteristic for a warm BLE handoff.</li> <li>[x] Exact same-address bonded warm buttonless DFU passed. The application       advertisement, Paired/Bonded state, connected BLEDfu service/control/       revision layout, encrypted notification/write gate, observed target       disconnect, <code>T1KE_DFU</code> advertisement, DIS model <code>T1000-E</code>, ATT MTU 247,       and 244-byte write capability were all checked. All 404,468 bytes were       confirmed in 121.081 seconds at 3,340 B/s; DFU through target disconnect       took 144.076 seconds and the full supervisor took 176.958 seconds. CRC,       activation, and exact <code>239a:8029</code>/<code>34A9141999729D5D</code> USB return passed.</li> <li>[x] Two accepted in-DATA 30 ms -&gt; 15 ms -&gt; 30 ms controller experiments       completed without corrupting either image, but were decisive negative       performance results. The first finished DATA in 425.398 seconds at       951 B/s; the later candidate finished DATA in 449.063 seconds at 901 B/s.       HCI capture found the cause: <code>hcitool lecup</code> silently encoded both       connection-event-length hints as <code>0x0001</code> (0.625 ms). The Pi's Broadcom       4.2 controller consequently scheduled about one ACL fragment per event:       roughly 64 fragments/s at 15 ms and 32 fragments/s after the 30 ms       \"rollback\", versus roughly 120--144 fragments/s on the untouched link.       The later pre-START controls prove that 15 ms itself is not slow; the       restrictive event-length hint and in-DATA update/rollback were unsafe.</li> <li>[x] Two exact 15 ms/latency-0, zero-event-length lab controls passed:       <code>t1000-ble-event-length-prestart-20260830-071549-QOeVuw</code> completed all       404,468 DATA bytes in 64.905 seconds at 6,232 B/s (95.635 seconds through       target disconnect; 112,639 ms full workflow), and       <code>t1000-ble-event-length-prestart-20260830-071825-VE9Re3</code> completed DATA in       62.070 seconds at 6,516 B/s (92.794 seconds through target disconnect;       106,807 ms full workflow). Both used exact <code>0/0</code> no-preference minimum and       maximum connection-event lengths. On each bootloader connection the HCI       trace contains exactly one successful update before START and none from       START through DATA, validation, activation, and the target disconnect;       Update Complete preceded START by 7.535 and 7.536 seconds. Completed-packet       clusters followed the 15 ms connection anchors, while the median full-size       DFU write gap was 29.997 ms in both traces. Exact package hash, CRC,       activation, and stable application USB return passed twice.</li> <li>[x] <code>t1000-ble-event-length-prestart-20260830-071358-ogzmRy</code> is the bounded       negative control. HCI accepted exact 15 ms/latency 0 with both event-length       hints set to 10 ms, then reported <code>Connection Timeout (0x08)</code> 6.810 seconds       after Update Complete during the 20-second pre-START pause. The run failed       closed at <code>STAGE=pre_start_update</code> in 44,227 ms; START and application DATA       were never sent. A 10 ms event-length hint is therefore rejected for this       adapter/target pair.</li> <li>[ ] Production BLE DFU keeps the controller-negotiated link and issues no raw       host connection update unless that exact adapter/target profile has been       separately graduated. The opt-in lab path may issue exactly one request on       the bootloader connection before START while sent/confirmed are zero: exact       interval and latency, <code>0/0</code> no-preference event-length hints, bounded pause,       and a matching HCI Update Complete are mandatory. Failure or mismatch       disconnects before START. Never update or roll back the link during DATA;       only the protocol PRN/window may adapt there. Compare complete repeated       control/candidate DFUs offline before graduating a production profile.</li> <li>[ ] Repeat the cold transfer with the host's bounded BlueZ readiness wait.       When ATT MTU is greater than 23 while the cached write capability remains       20, it polls the same connected DFU characteristic for at most three       seconds, aborts on disconnect, disappearance, or characteristic-handle       change, and otherwise falls back safely to 20. The four readiness unit       cases and all 81 strict helper tests pass; a physical 20 -&gt; 244-byte       promotion is still required.</li> <li>[ ] Restore the protected       <code>t1000e_repeater_lora_ota_no_external_sensors</code> application (target       <code>0x7B071FA0</code>, exact ZIP SHA-256       <code>9b9be2bee9ebb6644d22806d404fe02c415d037707713d206fa43a8c689cf632</code>)       through identity-gated application DFU while retaining the candidate       bootloader. Do not use the generic repeater image or the unqualified UF2       path. Verify the protected private/public identity without printing the       private key, plus exact name, latitude/longitude, build/body/OTA target,       USA radio, 22 dBm, GPS off, power saving on, RX gain on, RXPS on,       watchdog on, telemetry access <code>all</code>, no TempRadio/download, and a valid       admin login.</li> <li>[ ] LoRa radio reset/recovery is forced and normal receive/transmit resumes.       Normal post-reboot bidirectional LoRa is already proven: the V4 learned a       zero-hop path, received the exact message-specific ACK in 558 ms, and       received the T1000-E's exact <code>3caf9dcf</code> version reply. A deliberately       forced LR1110 recovery event is still required.</li> <li>[x] Direct V4 LoRa OTA receive, apply, reboot, and post-update verification       passed from exact <code>bf092b24</code> body <code>9443FB5E6F23FC1B</code> to exact <code>3caf9dcf</code>       body <code>3E92B157128B6963</code> on OTAFIX 2.4.3. The mandatory fixed three-minute       rehearsal passed at <code>909.950/250/SF5/CR5</code>, including natural expiry and       return to <code>910.525/62.5/SF7/CR5</code>. The 2,036-byte/two-block delta reached       ready in six seconds, the new body replied at the 50-second probe, and the       complete safety-wrapped runner took 519 seconds. V4 source RXPS and both       normal radio tuples were restored. The co-located T1000 was temporarily       reduced to 0 dBm and restored to 22 dBm using bounded retries across its       RXPS busy windows.</li> <li>[x] Independent post-LoRa-OTA USB verification matched the protected pre-run       private key, public key, name, latitude, and longitude without printing       private material. GPS remained off; device power saving, system watchdog,       RX gain, and RXPS remained on; telemetry access remained <code>all</code>; no       TempRadio lease or download remained. <code>blrc:B8</code> is the expected OTAFIX       application-apply success diagnostic. A subsequent software reboot reset       uptime and preserved the exact build/body, name, radio, 22 dBm, GPS,       power-saving, RXPS, watchdog, and no-TempRadio state. The CDC symlink did       not disappear during this warm reset, so uptime/readback\u2014not USB removal\u2014       is the required reboot proof on this board.</li> <li>[x] GPS was initially off, enabled successfully under device power saving,       reported active/no-fix/zero-satellites with its duty-cycle deadline, and       was restored to off. Device power saving reported on, RXPS reported       <code>on,18205,20423</code>, GPS advert policy <code>prefs</code>, and telemetry access <code>all</code>.</li> </ul>"},{"location":"hardware_validation_checklist/#rak3401","title":"RAK3401","text":"<ul> <li>[x] Stable USB identity and SWD FICR identity are independently matched.</li> <li>[x] Source-level WisBlock peripheral pins are complete and non-conflicting:       I2C SDA/SCL are P0.13/P0.14 through both <code>PIN_WIRE_*</code> and       <code>PIN_BOARD_*</code>; GPS-module RX crosses to MCU UART TX P0.16, GPS-module TX       crosses to MCU UART RX P0.15, and PPS is P0.17. A static contract test       prevents these aliases from silently disappearing or being uncrossed.</li> <li>[x] Ordinary/full-sensor RAK3401 profiles use the source-built Adafruit BME680       provider, not Bosch's precompiled BSEC archive, so upstream issue #3292's       soft-float/hard-float link mismatch is not reachable there. The reduced       LoRa-OTA profile deliberately omits BME680/BSEC and the other declared       optional environmental/ranging drivers. A static contract test requires       the hard-float path fix and BSEC dependency if BSEC is enabled in this       board or an inherited full-sensor recipe later.</li> <li>[ ] With the RAK13302 radio installed, detect a RAK12501/L76K UART GPS from a       complete checksum-valid NMEA sentence in sensor slot A. Confirm random       UART bytes, an incomplete sentence, and a bad checksum do not claim GPS.</li> <li>[ ] Detect RAK12500 I2C GPS alone at <code>0x42</code>; exercise GPS power saving and       confirm the shared 3V3_S rail, OLED, RTC, and other slots remain powered.</li> <li>[ ] Detect INA3221 alone at the firmware-configured <code>0x42</code> and prove the       discovery path does not send u-blox configuration traffic to it.</li> <li>[ ] Exercise RAK12500 at <code>0x42</code> and INA3221 at <code>0x43</code> together after strapping       INA3221 A0 to SCL and building with       <code>-DTELEM_INA3221_ADDRESS=0x43</code>; verify both retain independent telemetry.</li> <li>[ ] With a representative omitted environmental sensor attached, confirm the       reduced image leaves the generic I2C bus healthy but does not advertise a       driver that was intentionally removed.</li> <li>[x] Local USB terminal probes are terminated with carriage return (<code>\\r</code>).       This CLI echoes an LF-only command without executing it; an echoed       <code>ver</code> with no reply is therefore a bad probe, not evidence of a hung       application. Confirm any suspected hang with a CR-terminated command,       LoRa status, and SWD state before resetting the board.</li> <li>[x] Assert CDC DTR when probing the RAK terminal. With DTR deasserted, writes       reached the port but no CLI replies were returned; the same exact       stable-identity port returned the expected version immediately after DTR       was asserted. Keep 1200-baud bootloader touch separate from 115200-baud       application probes, and allow a full reply window so delayed responses       are not attributed to the following command.</li> <li>[x] Installed S140 6.1.1 FWID (<code>0x00B6</code>) and runtime application base       (<code>0x26000</code>) are independently verified.</li> <li>[x] Bootloader version and apply capabilities are independently reported.</li> <li>[x] UF2 application copy returns success; <code>sync -f</code> returns success; no USB       reset/timeout or offline-sector errors occur; SWD readback matches every       UF2 payload byte. Current 2.4.4-preview.2 result is PASS in both       current\u2192old and old\u2192current directions.</li> <li>[x] Board, repeater role, version, name, and USA radio tuple are verified       after serial recovery and again after a real cold boot.</li> <li>[x] Six consecutive authenticated <code>ota self</code> attempts leave the application       healthy. In the qualification run, two login/reply pairs were lost, one       login succeeded while its command reply was lost, and the next three       commands replied in about 2.5 seconds each. A CR-terminated local <code>ver</code>       probe passed after every attempt; packet loss did not become a node hang.</li> <li>[ ] An unchanged admin login does not rewrite the ACL flash file, while an       actually changed/newly learned persistent route schedules exactly one       delayed save and survives reboot. Cover delayed flood-path replies,       already-unknown paths, changed permissions/secrets, new/evicted clients,       and the intentionally non-persistent guest case. Do not rely on an       unrelated login write to capture a later PATH response.</li> <li>[ ] Location and private-key persistence are verified without exposing the       private key in logs.</li> <li>[x] Serial recovery rejects nrfutil's false exit-0 failure, requires the exact       success marker, and produces a byte-exact SWD application readback.</li> <li>[ ] UF2/serial recovery works with both the deployed older bootloader family       and the current backward-compatible application.</li> <li>[ ] Bluetooth advertisement and connection work when enabled. The tested       repeater profile does not advertise BLE during normal operation.</li> <li>[x] Direct LoRa OTA from the V4 passes with elapsed time, bounded retry       behavior, final hash/version verification, exact radio restoration, and       independent SWD readback. The qualified <code>bf092b24</code> base       <code>91CF4EC2882F23D6</code> reached <code>3caf9dcf</code>/<code>27A223DDFC3A8F47</code> using a       two-block, 2,132-byte delta: ready in six seconds, new body at the       60-second reboot probe, and 514 seconds for the complete safety-wrapped       run. Log:       <code>/home/mikec/hwtest/runs/rak3401-0dbm-final-9KWjey61/run.log</code>.</li> <li>[x] The current OTAFIX test version <code>0x02040403</code> independently passes a       74-block direct LoRa update from exact <code>3caf9dcf</code> body       <code>27A223DDFC3A8F47</code> to HEAD <code>9fd580c8</code> body <code>744BC4443891ED10</code>.       READY took 122 seconds and the complete three-minute-rehearsal,       transfer, install, reboot, recovery, and restore wrapper took 589.487       seconds. Lost read-only preflight and postboot replies were reconciled by       bounded exact retries. USB confirmed the target/hardware/body and       bootloader success result, and authenticated LoRa readback confirmed the       final 22 dBm restoration. Sanitized log:       <code>/home/mikec/hwtest/runs/rak3401-02040403-head-vzWOXVxT/qualification-redacted.log</code>.</li> <li>[ ] Add exact RF packet sent/confirmed counters to the device/host telemetry.       The qualified run records two payload blocks, all seeder reads, command       retries, and final success, but those are not equivalent to LoRa packet       counts and must not be presented as such.</li> <li>[ ] Repeat at each supported bandwidth and record 0-hop, 1-hop, and 2-hop       estimates from measured airtime rather than extrapolating only by file size.</li> </ul>"},{"location":"hardware_validation_checklist/#rak4631-reduced-profiles","title":"RAK4631 reduced profiles","text":"<ul> <li>[x] Serialized VM contracts distinguish the three application identities:       the plain and Serial2 reduced profiles retain the combined WisBlock GPS       provider and all four INA voltage/current drivers; the explicit legacy       Serial1 profile retains the INA drivers and omits GPS. This is build       evidence only, not physical peripheral qualification.</li> <li>[ ] On the plain reduced profile, detect and read RAK12500 I2C GPS, a       RAK12501/L76K UART GPS in a separate run, the SSD1306 OLED, a supported       autodiscovered RTC, and representative INA telemetry. Verify GPS sleep and       repeated discovery never lower the shared WB_IO2/3V3_S rail.</li> <li>[ ] With a UART RAK12501 installed and detected, confirm the Serial2 bridge       and GPS remain usable together. Select Serial1 and try to enable the       bridge with the GPS preference both on and off; verify each attempt is       refused before the bridge starts and does not change GPS transport,       acquisition, hold, or cached-fix state. The shared WB_IO2/3V3_S rail must       remain high and GPS must remain usable after each refusal.</li> <li>[ ] With only an I2C RAK12500 installed, and again with neither GPS installed,       select Serial1 on the merged image and confirm bridge enable is refused       without changing saved UART/runtime state. Silence or an I2C-only detection       must not defeat the fail-closed RAK12501 reservation. Confirm Serial2 starts       and I2C GPS telemetry remains usable.</li> <li>[ ] Exercise RAK12500 at <code>0x42</code> and INA3221 at <code>0x43</code> together with the       address-matched build. Separately place INA3221 alone at the configured       <code>0x42</code> and prove the identity guard prevents u-blox configuration writes.</li> <li>[ ] With a logic analyzer, hold SDA low and then SCL low before sensor       discovery. Confirm the validated board pins receive at most nine       open-drain recovery clocks and a STOP only after SCL rises; the firmware       must skip discovery if either line remains low. Repeat on ProMicro's       remapped SDA 8/SCL 7 and verify the user-button pin is never driven.</li> <li>[ ] Record the remaining core limitation: the pinned Adafruit nRF52 Wire       implementation has no transaction timeout. This preflight cannot protect       display/RTC calls made earlier in boot or interrupt a peripheral that       wedges after a transaction begins. Qualify those cases with a hard power       cut/watchdog fixture before claiming bus-hang recovery.</li> <li>[ ] Confirm the explicit legacy Serial1 image exposes neither UART RAK12501       nor I2C RAK12500. Record this as a combined-provider build limitation, not       an assertion that RAK12500 electrically conflicts with the UART.</li> </ul>"},{"location":"hardware_validation_checklist/#heltec-t096","title":"Heltec T096","text":"<ul> <li>[x] The cross-role <code>uf2reset</code> repair was hardware-qualified on the exact       no-footer Full Companion image. ZIP SHA-256 is       <code>0585bee1c0b278a68788f78af384bcbdb5633d57f9ea301fc14f1c80c4275489</code>;       embedded version is <code>v1.17.1-uf2reset-f2c15225-f2c15225</code>. Terminal entry       and help passed, the exact command disconnected application USB in       1.031 seconds, and stable boot USB returned in 2.026 seconds. The final       Full image installed over serial in 38.900 seconds and stable application       USB returned in 41.672 seconds. Final primary terminal/Binary switching,       dedicated logging interface, version, help entry, and live       <code>MeshCore-8E229D0A</code> advertisement at <code>CF:A8:18:36:DE:8B</code> all passed.</li> <li>[x] Stable USB serial <code>651F8E496197F882</code> distinguishes the application       (<code>239A:8029</code>) from the OTAFIX serial-DFU interface. Every flash followed       that identity across the host-assigned <code>COM9 -&gt; COM6 -&gt; COM9</code> transition;       the simultaneously connected MeshPocket on <code>COM20</code> was never selected.</li> <li>[x] Baseline bootloader <code>0.11.0-OTAFIX2.4.3</code> was installed at this checkpoint. The restored Repeater       reports application body hash <code>3B6D1A729C087243</code>, target <code>98411AC6</code>, apply       ABI 3, codec mask <code>0x5</code>, and stage address <code>0xED000</code>. The application ZIP       is 708,216 bytes with SHA-256       <code>abb00560cc5618ae155bf10252e9261127416a7a91b5f6565837384f0dec2390</code>.</li> <li>[x] A 48,229-byte in-place delta with SHA-256       <code>988bd2385e9c995d0ae04effb6bb5cd614227c7c764590d82bd1943da2f18e4d</code>       transferred over LoRa in 47/47 blocks from the MeshPocket seeder and       applied successfully. The first application boot reported bootloader       result <code>B8</code>; the running body hash matched the candidate exactly. No chat       message was sent for this transfer.</li> <li>[x] The generic delayed AGC/watchdog arming fix passes warm-reboot hardware       checks on both the T096 and MeshPocket. The restored T096 retained AGC       interval 8 and, after 215 seconds, was in RX with 100 packets received,       28 sent, zero core errors, and <code>err_flags=0</code>. The Pocket's quiet-channel       liveness recovery set only the expected radio-watchdog bit; temporarily       matching the USA channel then received 14 packets with zero receive       errors before its saved <code>869.618/62.5/SF8/CR5</code> profile was restored. At       498 seconds the T096 had one CAD-busy timeout after 37 busy-channel       samples, then returned to RX with no queue, watchdog, or start-RX fault.</li> <li>[x] Exact Full Companion ZIP SHA-256       <code>ee92856e5bfb7877b0d8bff6d6a5873d8037fc178ddb151202a9e6a6d9d59e73</code>       installed by serial DFU and passed the reversible dual-CDC test. Logging       off exposed only interface <code>00</code>; <code>set usb.logging on reboot</code> added       interface <code>02</code> as <code>COM21</code>. Opening <code>02</code> emitted both portable identity       lines, 980 captured bytes were entirely printable, and host input produced       no echo or command reply while Binary Companion on <code>00</code> returned the exact       model, key, and radio tuple.</li> <li>[x] With interface <code>02</code> deliberately unread, 11/11 text-terminal probes stayed       between 212 and 231 ms for 44.4 seconds. A longer 100-second hold buffered       8,636 entirely printable bytes while 60/60 hard-bounded Binary Companion       reconnects passed with no timeout; the final full identity query completed       in 739 ms. Neither USB interface disconnected. Logging off plus reboot       removed <code>02</code>, read back off on <code>00</code>, and the qualified Repeater was then       restored with its original name, public key, and USA radio tuple.</li> <li>[x] The descriptor/reconnect follow-up built a 482,271-byte Full Companion DFU       ZIP with SHA-256       <code>2a5a6bd0fd26031a2c2e047af6ead8f85f0d617da238d0cd6d816f7d5c41ec6f</code>.       On the physical T096, Windows read interface <code>02</code>'s bus-reported       description as <code>MeshCore Logging</code>. Two immediate open/close cycles each       delivered the complete 80-byte two-line identity marker with no NUL or       other invalid control byte, while Binary Companion on interface <code>00</code>       retained the exact key, model, and <code>910.525/62.5/SF7/CR5</code> tuple.</li> <li>[x] The final short-write/reconnect guard built a 482,271-byte Full Companion       DFU ZIP with SHA-256       <code>bbbc3459b2c032af23c6da05e41984cb0250398b57ba56ea99166456700ace6f</code>       and EndF body hash <code>41365E4DB0FF4AE5</code>. On the physical T096, interface       <code>02</code> again reported <code>MeshCore Logging</code>; 3/3 explicit DTR sessions each       delivered one complete 80-byte marker with no NUL or invalid control byte.       With that logging endpoint held open and unread, interface <code>00</code> completed       60/60 Binary Companion reconnect queries and retained public key       <code>8e229d0a9ace9bd6f768fc1237d9e3ebca340d1ff1c6087349983a07f305903a</code>       plus the exact <code>910.525/62.5/SF7/CR5</code> tuple.</li> <li>[x] The corrected Windows flasher identifies Binary-mode Full Companion and       links the same-radio <code>MI_02</code> inventory row to <code>MI_00</code>. An intentional       selection of <code>COM21/MI_02</code> was canonicalized to <code>COM9/MI_00</code> before any       1200-baud action; the exact USB serial then followed       <code>COM9 -&gt; COM6 -&gt; COM9</code>, never touched the logging endpoint or MeshPocket,       and produced both <code>Device programmed.</code> and <code>Flash completed.</code>. The VM was       suspended only across each touch/transfer and resumed immediately. After       restoring the qualified Repeater and performing a final warm reboot, the       58-second snapshot was in RX with 28 packets received, 9 sent, zero core       errors, an empty queue, and <code>err_flags=0</code>.</li> <li>[x] Final flasher review now revalidates the selected USB identity and exact       interface immediately before both the direct 1200-baud open and its Python       fallback, and balances every successfully written terminal START with a       STOP even when the banner is lost. Windows PowerShell 5.1 and PowerShell 7       regression suites pass. A second physical restore deliberately selected       <code>COM21/MI_02</code>; it was canonicalized to <code>COM9/MI_00</code>, followed the same       <code>COM9 -&gt; COM6 -&gt; COM9</code> transition, and completed without touching the       MeshPocket. At 112 seconds the restored Repeater retained its name, OTA       body hash <code>3B6D1A729C087243</code>, USA radio tuple, and AGC interval 8; it was in       RX with 20 packets received, 6 sent, zero core errors, an empty queue, and       <code>err_flags=0</code>. The VM was running again immediately after the flash.</li> <li>[x] The T096-only message profile defines <code>UI_MESSAGE_CHANNEL_FOOTER=0</code>;       every other profile retains the default footer. The exact incoming       <code>#testing</code> message <code>T096 footer test: wrapped text should reach the screen       bottom.</code> traversed the live channel receive/display path, and the temporary       empty <code>#testing</code> channel slots on both endpoints were restored byte-for-byte.       Static profile coverage passes 2/2. No framebuffer or camera capture was       available, so the evidence is the exact live UI path plus the compiled       board-specific flag rather than a pixel photograph.</li> <li>[x] The then-final Full Companion artifact at this checkpoint,       <code>v1.17.1-t096-head-fcd1f8cc-usbtask8-fcd1f8cc</code>, was installed. Its DFU ZIP       is 487,231 bytes with SHA-256       <code>CD267952F420294DF21CA96E3AA6D924C6EF7467C31C8D69B46F31E6719A1D67</code>;       the application is 486,428 bytes with a 486,372-byte EndF body and hash       <code>2E03B1C1166D4CC0</code>. The ELF exposes strong <code>T</code> definitions for both CDC       callbacks, mount/unmount, SOF, and the CDC0-only framework flush override.</li> <li>[x] Identity-gated BLE application DFU passed through the bonded address       <code>CF:A8:18:36:DE:8B</code>: encrypted application handoff from       <code>MeshCore-8E229D0A</code>, same-address <code>T096_DFU</code> Legacy service, and DIS model       <code>HT-n5262G</code> all matched. The target confirmed 486,428/486,428 bytes in       565.986 seconds at 859 payload B/s, validated, activated, and initiated       the expected disconnect; end-to-end time was 603.967 seconds. USB serial,       version, board, public key, radio tuple, EndF hash, and bootloader apply       ABI 3/codecs <code>0x5</code> returned exactly, and a fresh active scan observed the       application name again at the same address.</li> <li>[x] The real host <code>motatool</code> opened <code>COM9</code>, survived the intentional CDC       session-settle purge, attached an empty folder with <code>COUNT -&gt; 0</code> and       <code>OK folder attached</code>, then detached it and restored Binary mode. This       test sent no mesh messages. Three primary-port close/reopen cycles after       deliberately abandoned terminal output exposed zero stale bytes and each       returned a clean banner. Five logging-port reopen sessions each began       with the exact 80-byte identity marker and contained no NUL or invalid       control byte.</li> <li>[x] With both USB outputs deliberately unread for 65 seconds after a 10,000-byte       terminal input burst, the primary accumulated 16,886 printable bytes and       CDC1 accumulated 3,735 printable bytes beginning with its exact marker.       <code>ver</code> and Binary Companion remained responsive. A subsequent warm reboot       removed USB for 2.209 seconds, returned both interfaces in 2.409 seconds,       and CDC1 again emitted the exact marker. At 65 seconds the fresh boot had       <code>err_flags=0</code>, an empty outbound queue, 9 received floods, and zero CRC       errors. A Windows host-side composite       restart was attempted but denied by the non-elevated PnP API, so the       distinct host-driven BUS_RESET case remains a physical/privileged check;       it is not inferred from the warm-reboot result.</li> <li>[x] After the operator physically removed and restored T096 power (the off       interval was not measured), stable serial <code>651F8E496197F882</code> returned as       primary <code>MI_00</code>/<code>COM9</code> and logging <code>MI_02</code>/<code>COM21</code>. The cold terminal       reported exact version       <code>v1.17.1-t096-head-fcd1f8cc-usbtask8-fcd1f8cc</code>, Heltec T096 identity,       public key, USA radio tuple, BLE name, dedicated-CDC logging state, EndF       body hash <code>2E03B1C1166D4CC0</code>, and bootloader apply ABI 3/codecs <code>0x5</code> with       stage ceiling <code>0xD4000</code>; mOTA remained source-only with no folder attached,       and STOP restored Binary mode. CDC1's first read was the exact 80-byte       identity marker with no NUL. At 150 seconds, Binary stats reported 4,224       mV, <code>err_flags=0</code>, an empty outbound queue, 47 packets received, zero       packets sent, and zero TX airtime. A second core checkpoint advanced       monotonically to 315 seconds with 4,220 mV, <code>err_flags=0</code>, and an empty       queue, providing no evidence of a watchdog reboot. A fresh active BLE       scan observed <code>MeshCore-8E229D0A</code> at the same <code>CF:A8:18:36:DE:8B</code>       address; BlueZ still       reported paired, bonded, and trusted. No mesh message was sent. This proves       cold persistence, but not the distinct host-only USB <code>BUS_RESET</code> path.</li> <li>[x] The display auto-off wake failure was traced to the shared ST7735 power       lifecycle: <code>turnOff()</code> released SCK/MOSI as inputs, but the nRF52       <code>SPIClass::begin()</code> wake path was a no-op while the SPI object still       considered itself initialized. The shared driver now restores the bus-pin       directions and nRF52 high-drive configuration explicitly, waits through       reset release, and primes the retained frame after <code>DISPON</code>. Static wake       ordering and the T096 footer profile pass, and the exact Full Companion artifact       <code>v1.17.1-t096-head-fcd1f8cc-wake1-fcd1f8cc</code> compiled at 486,348 bytes.       Its 487,231-byte serial-DFU ZIP has SHA-256       <code>A091F6DC458177BB26B8384B2AAAC0A9FD550322179F96062CCD3F0F5BB0E585</code>;       the 486,428-byte OTA image reports a 486,372-byte EndF body with hash       <code>E9AB2A36E9F7091F</code>. Identity-gated <code>meshfirmware</code> selected <code>COM21/MI_02</code>,       canonicalized it to <code>COM9/MI_00</code>, followed <code>COM9 -&gt; COM6 -&gt; COM9</code>, and       emitted both <code>Device programmed.</code> and <code>Flash completed.</code> without touching       the MeshPocket. The VM was suspended only across touch/transfer and was       running again as soon as exact serial <code>651F8E496197F882</code> returned. Live       readback then matched the public key, Heltec T096 board, USA       <code>910.525/62.5/SF7/CR5</code> tuple, ABI 3/codecs <code>0x5</code>/stage <code>0xD4000</code>, and exact       80-byte CDC1 marker; core checkpoints advanced through 369 seconds with       <code>err_flags=0</code>, an empty queue, and zero TX. Follow-up physical testing       confirmed auto-off wake and single-click page navigation. Double-click,       triple-click, long-press, and simultaneous-button gestures remain deferred.</li> <li>[x] A signed bootloader mOTA package for OTAFIX HIL candidate <code>0x02040401</code>       transferred over LoRa in 40/40 blocks, passed the privileged-install gate,       installed with the watchdog enabled, and rebooted with unchanged node and       radio settings. The installed bootloader CRC changed to the package's       expected <code>381BAE6E</code>; the temporary HIL signer was removed afterwards.</li> <li>[x] A 486,796-byte Full Companion application completed bonded Legacy BLE DFU       at approximately 5.7-6.2 kbit/s payload throughput, then returned with the       same identity and USA radio tuple. The later CDC0 first-open fix preserved       immediate <code>APP_START</code> input across the eight-millisecond session gate:       first client after reboot passed with CDC1 logging active, followed by       10/10 immediate COM9 close/reopen queries. CDC1 continued to emit its exact       identity marker and printable packet/debug logs.</li> </ul>"},{"location":"hardware_validation_checklist/#heltec-meshtower-v2-with-sd","title":"Heltec MeshTower V2 with SD","text":"<ul> <li>[x] Stable serial <code>9352162A72082314</code> and physical downstream-hub path       <code>1-1.2</code> port 4 identify this board across application and bootloader       descriptors; no other attached nRF52 endpoint was selected. The older       2.4.3 bootloader's UF2/serial failure was rejected rather than treated as       a successful flash.</li> <li>[x] Exact <code>1.17.1.5-halo-keymind-cascade-marathon-hwtest-e26d48e4</code> SD       Repeater boots with hardware ID <code>Heltec_tower_v2</code>, target <code>0A9DBBF0</code>,       body hash <code>E9282D470AAC348B</code>, and USA radio       <code>910.525/62.5/SF7/CR5</code>. <code>ota self</code> reports SD apply ABI 3 with codec mask       <code>0x5</code>; <code>ota bootloader</code> reports board <code>239A0071</code>, target <code>1150F50E</code>, name       <code>TOWER_V2_OTA</code>, and capability byte <code>09</code>.</li> <li>[x] A post-Pi-recovery identity-gated serial audit reconfirmed the exact       Tower V2 model, Repeater role, build, <code>910.525/62.5/SF7/CR5</code>, target       <code>0A9DBBF0</code>, body <code>E9282D47</code>, SD ABI 3/codecs <code>0x5</code>, and installed       bootloader identity/capability <code>239A0071</code>/<code>09</code>. The card reported       959.6 MiB free and no active download. This profile exposes the local       text console but deliberately has no runtime <code>usb.logging</code> setting; the       unknown-setting reply is a capability result, not a transport failure.</li> <li>[x] Card detection and destructive maintenance pass. Normal format took       3,927 ms; an immediate repeat was rejected by the five-minute cooldown;       forced format took 3,933 ms; and raw erase plus format took 3,947 ms.       The card remounted empty with 16.0 KiB used and 959.6 MiB free, and both       completion ages were recorded. Automatic archive capture was then       disabled deterministically, leaving only <code>/mota/cache.off</code>.</li> <li>[ ] SD card detection, staging, hash validation, apply, cleanup, and recovery       from missing/corrupt media pass.</li> <li>[ ] Multi-page application and bootloader update paths pass across a cold boot.</li> <li>[ ] LoRa OTA receive/apply reports the expected target ID and installed version.</li> </ul>"},{"location":"hardware_validation_checklist/#heltec-v4","title":"Heltec V4","text":"<ul> <li>[x] Exact V4 hardware variant is reported (<code>Heltec V4.3 OLED</code>); OLED/TFT       variants are not merged.</li> <li>[x] Full Companion boots with USB logging off and Binary Companion selected.       The text terminal independently reports the complete build string;       protocol <code>ver</code> has a shorter fixed-width version field.</li> <li>[ ] USB logging changes take effect immediately on this single-TTY ESP32       profile, require no reboot, and return to Binary Companion only through       the explicit terminal-stop mode change.</li> <li>[x] Bluetooth pairing and Companion protocol operations pass. Qualification       required removing the Pi's stale pre-flash bond, pairing through a BlueZ       <code>KeyboardOnly</code> agent with the current displayed/reported PIN, then       reconnecting; BLE <code>infos</code> and <code>ver</code> returned the exact V4.3 OLED identity.</li> <li>[x] Saved Wi-Fi connects to <code>SlowFi</code>, returns at <code>192.168.1.51</code> after the test       host reboot, reports Wi-Fi power save <code>min</code>, and remains governed by the       configured-network behavior rather than the unconfigured 30-minute       shutdown policy.</li> <li>[x] TCP Binary Companion (<code>5000</code>), Wi-Fi OTA (<code>5001</code>), and text CLI (<code>5002</code>)       are each tested and cannot be confused with one another. Port 5000       returned the exact Companion identity; 5002 returned the full terminal,       version, Wi-Fi, logging, RXPS, and memory state; and a real <code>motatool       serve --tcp 192.168.1.51:5001 -v</code> session received <code>COUNT -&gt; 0</code> from an       intentionally empty folder. Disconnect then restored <code>folder:not       connected</code> while the 5001 listener stayed active.</li> <li>[ ] For a shared Full-Companion controller/seeder, bind the source identity       to the exact public key already read from Binary Companion port 5000.       Do not require <code>get public.key</code> from text port 5002: the hardware-tested       V4 Full CLI rejects that command. Port 5002 must still prove the local       TempRadio state/tuple, while keyed on-air destination replies prove the       physical LoRa handoff.</li> <li>[ ] V4 seeds direct and routed LoRa OTA; TempRadio preflight, apply, and       automatic normal-radio restoration all pass.</li> </ul>"},{"location":"hardware_validation_checklist/#seeed-sensecap-indicator-lora","title":"Seeed SenseCAP Indicator LoRa","text":"<ul> <li>[x] Flashing selects the ESP32-S3 CH340 endpoint, never the Indicator RP2040       ACM endpoint; esptool MAC probing succeeds before erase. The qualifying       merged write used 115200 baud and completed with flash hash verification.</li> <li>[x] A fresh merged install completes SPIFFS initialization and reports the       intended Full Companion version/role and <code>Seeed SenseCAP Indicator</code>       hardware identity. The exact qualifying artifact was       <code>SenseCapIndicator-LoRa_companion_radio_full-1.17.1.5-halo-keymind-cascade-marathon-e26d48e4-merged.bin</code>,       2,070,152 bytes, SHA-256       <code>df08b770313ca8776436456525681cf286cd9b5b40e05e7cf55f21ef097f338a</code>;       its ELF, map, manifest, and partition signature are archived beside it on       the Mercerwood Pi.</li> <li>[x] The current dark-layout Full Companion application was flashed app-only       with exact CH340/MAC/partition gates, preserving identity, Wi-Fi, and       settings. The 2,147,800-byte application has SHA-256       <code>81bebdc07b6a8349c1c975cb5a0e30c5f6019d35bcac641e5f3d4df951f7406b</code>;       esptool verified its flash hash in 134.2 seconds. USB Binary/terminal,       saved logging-off state, configured Wi-Fi, BLE, TCP ports 5000/5001/5002,       and an empty-folder Wi-Fi mOTA <code>COUNT -&gt; 0</code> exchange all pass afterward.</li> <li>[x] Keep one identity-gated CH340 descriptor open with DTR/RTS deasserted       through startup. On the valid-current-font path, the Indicator streams a       1,302,608-byte font from its RP2040 at 1 Mbps before registering the USB       terminal, so allow at least 30 seconds before the first command. A       missing/corrupt-font recovery instead runs in the background after the       interfaces start. Reopening short probes can reset the ESP32 repeatedly       and create a false UART-hang diagnosis; the controlled run returned       <code>ver</code> and <code>board</code> after the same apparent-silence condition.</li> <li>[x] Automatic font recovery starts from a physically corrupt RP asset. The       setup deliberately installed 64 all-zero bytes, CRC32 <code>758d6336</code>, in       place of <code>/meshcore/ui-font.vlw</code>; the ESP32 rejected that asset and kept       its built-in fallback font while recovery ran.</li> <li>[x] Every new HTTPS recovery attempt waits for a fresh SNTP callback and a       signed epoch at or after the compiled asset publication time before it       opens TLS. The forced-resume run observed fresh syncs in 3,700, 400, and       699 ms across three outer attempts, including two failed TLS handshakes;       the final normal run synced in 1,999 ms and only then logged the first       <code>api.github.com</code> connection. A retained merely plausible clock is not       accepted. CA validation and the compiled asset SHA-256 remain mandatory.</li> <li>[x] The release-source normal path downloaded all 1,302,608 bytes into PSRAM       in 13,205 ms, closed TLS, verified SHA-256       <code>61bce9662db314054e7bcfaa26147a28ad7b500b51baac4cae1caacce90b7421</code>,       staged receiver-paced 512-byte <code>MCFONT STAGEV2</code> chunks in 36,676 ms,       committed, and verified RP CRC32 <code>19f80d64</code> at 76.7 seconds from reset.       An independent <code>MCFONT GET</code> over RP USB then returned exactly 1,302,608       bytes with the same CRC and SHA in 15.273 seconds. The exact installed       application is       <code>SenseCapIndicator-LoRa_companion_radio_full-1.17.1.5-halo-keymind-cascade-marathon-font-recovery-e26d48e4.bin</code>;       its log is       <code>/home/mikec/hwtest/runs/indicator-release-recovery-lUZEmBHL/esp-serial.log</code>       on Mercerwood. The current RP service reports protocol 2 and completed       STAGEV2 accounting; its installed flash was not independently read back,       so no RP artifact hash is inferred from the archived candidates.</li> <li>[x] Strict Range recovery passed a forced hardware interruption. Exact test       application SHA-256       <code>cfd5aec497cb9919f87c0f82f5deaf8614d411582a709cea1c36275529c0bb68</code>       closed the initial response at verified offset 1,048,576. Its first       same-offset resume handshake failed; bounded retry 2/2 then accepted only       the remaining 254,032-byte <code>206</code> response under the original strong       ETag/<code>If-Range</code>, retained the same PSRAM buffer and SHA stream, completed       the download in 49,422 ms, staged in 36,702 ms, committed, and passed an       independent exact USB readback. The full log is       <code>/home/mikec/hwtest/runs/indicator-range-v2-xbKr09wI/esp-serial.log</code>.       An earlier forced 512 KiB run proved one correct resume at 524,288 but       later exhausted its second reconnect on a TLS failure; it is retained as       regression-trigger evidence rather than an end-to-end pass.</li> <li>[x] Rebooting the exact release-source application with the current valid       font performed no NTP query, TLS connection, or GitHub request. The       valid-font boot log is       <code>/home/mikec/hwtest/runs/indicator-release-valid-a84vd7Du/esp-serial.log</code>.</li> <li>[x] The post-qualification shared SNTP-coordinator source compiles in the       real Arduino-ESP32 2.x LoRa USB/WiFi profile (1,587,965 bytes, 60.6% of       its OTA slot), the dynamically generated ESP-NOW Full profile (2,093,465       bytes, 79.9%), and the matching RP2040 transactional service. After the       VM independently reported <code>NTPSynchronized=yes</code>, an       end-to-end request to the immutable GitHub asset returned HTTP 200,       exactly 1,302,608 bytes, and SHA-256       <code>61bce9662db314054e7bcfaa26147a28ad7b500b51baac4cae1caacce90b7421</code>.       A live <code>524288-1302607</code> continuation then returned HTTP 206, the same       strong ETag, an exact 778,320-byte <code>Content-Length</code>, and a byte-for-byte       hash match against the checked-in font tail; the pinned Sectigo E46 root       independently verified the current <code>api.github.com</code> chain.       The same coordinator also compiles in the real       <code>heltec_v4_repeater_observer_mqtt</code> profile: its 1,852,392-byte EndF image       has SHA-256       <code>fe8352654437f67488b412e1c1a690f2874e836abb5a5d209654bd030c713d7e</code>.       MQTT's three process-global <code>configTime()</code> paths are lease-protected,       and a busy asynchronous refresh uses a wrap-safe five-second retry       deadline instead of overwriting another service's SNTP callback or       recording a false successful refresh.       The exact final LoRa Full artifact gate then passed 11/11 linked-image       markers, including both <code>requesting fresh NTP time before download</code> and       the subsequent TLS-open marker. Its 2,146,312-byte application has       SHA-256       <code>f557088a5ef3f49f74ab01ca95fefc76911cca4073f01b77cee4882284fc5110</code>       and 475,128 bytes remain in its app slot; the matching 2,211,848-byte DIO       merged image has SHA-256       <code>52a4559774384b54dd7fb81da82c791e2c9564991fcf016bcad3b6ad756c1fb2</code>.       The exact ELF, map, capability manifest, and partition signature are       archived together under <code>/tmp/indicator-full-daily-ntp.WQ6ozM</code> on       the VM pending transfer to the hardware-run archive.       The ESP-NOW Full sibling passed the same 11/11 gate with a 2,093,928-byte       application (527,512 bytes free), SHA-256       <code>fcd9e0e8a37551a845a234fc10eaa4a9f420d54172039b9241f4696a12d4c65f</code>,       and matching DIO merged-image SHA-256       <code>f3637c23f58204f5b752b68a1bd494601cb68bee9c27b664832d40abd03cc186</code>;       its complete archive is <code>/tmp/indicator-espnow-full-ntp-gate.YN9T8l</code>.       Repeat the negative UDP/123-blocked hardware gate on this exact final       source before treating the coordinator refinement as hardware-qualified.</li> <li>[ ] Full Wi-Fi SSID, setup address, and related status text wrap without       clipping on the physical display. The new dark palette and exclusive       lower pairing block are installed; a fresh bond removal held the random       PIN request on-screen for 30 seconds and then an immediate second attempt       paired, trusted, and returned the exact Indicator identity over BLE. A       human physical-readability confirmation is still required; the automated       geometry tests prove the PIN block is centered at four-fifths height and       cannot overlap IP, inbox, or status text.</li> <li>[ ] Boot the exact current LoRa and ESP-NOW Full artifacts in both saved       secondary-transport modes and capture the <code>Indicator render</code> line. Require       LoRa + WiFi, LoRa + BLE, and ESP-NOW + infrastructure WiFi to retain       480x480, and ESP-NOW + BLE to select 320x320 scaled to the panel. A logged       emergency 320x320 fallback keeps the unit recoverable but does not pass a       native-480 gate.</li> <li>[ ] For all four boots, record free heap and largest internal block before       interfaces and after the selected interface is usable. In WiFi mode prove       BLE never starts; in BLE mode prove infrastructure WiFi, WebConfig, MQTT,       and TCP never start. Keep the primary LoRa or ESP-NOW radio exchanging       traffic throughout. For both BLE modes pair/encrypt, negotiate MTU,       subscribe, exchange repeated Companion requests, disconnect/reconnect,       and repeat after bond removal; exercise network/TCP traffic in both WiFi       modes and record the lowest heap/largest-block values.</li> <li>[x] With no saved SSID, setup Wi-Fi powers down after the absolute 30-minute       window even if queried or used.</li> <li>[x] A software reboot starts a fresh unconfigured setup window.</li> <li>[x] With a saved SSID, Wi-Fi reconnects to <code>SlowFi</code>, reports minimum modem       power save, and remains governed by normal configured-network behavior.</li> <li>[x] Bluetooth Companion pairing and protocol operations pass after saving a       deterministic qualification PIN, removing any stale host bond, pairing,       disconnecting the <code>bluetoothctl</code> client, and reconnecting with meshcli.       Binary <code>infos</code>/<code>ver</code> returned the exact Indicator identity and USA tuple.       A second connection after the USB-open reboot and logging-mode exercise       also returned the exact build; one initial scanner miss was resolved by       an explicit BlueZ discovery pass and was not a firmware advertisement       failure.</li> <li>[x] Wi-Fi/TCP Companion, CLI, and OTA endpoints pass at <code>192.168.1.54</code>:       port 5000 returned Binary Companion identity, port 5002 returned the full       text version/status, and motatool completed a port-5001 <code>COUNT -&gt; 0</code>       protocol exchange against an empty served folder.</li> <li>[x] Fresh Full starts with USB logging off. On this single-TTY ESP32 profile,       logging on/off applies and persists without a descriptor-changing reboot;       the same held-open ASCII terminal reported off -&gt; on -&gt; off correctly,       emitted live Wi-Fi/radio diagnostics while on, then accepted the explicit       terminal-stop token and returned a valid 85-byte Binary Companion device       info frame for <code>Seeed SenseCAP Indicator</code> without rebooting. Companion       remained independently usable over Bluetooth and Wi-Fi.</li> <li>[x] Normal-radio LoRa transmit and receive pass. At the installed 22 dBm,       a co-located discovery request overloaded the nearby receivers and found       zero nodes; temporarily reducing only the Indicator to 0 dBm produced       three repeater replies at RSSI -29 to -59 dBm, proving both directions.       The saved 22 dBm value was restored and independently read back after the       test; this near-field result is a lab-power gate, not a firmware failure.</li> <li>[ ] TempRadio sanity check, OTA seeding, and normal-radio restoration pass.</li> </ul>"},{"location":"hardware_validation_checklist/#cross-radio-lora-ota-acceptance","title":"Cross-radio LoRa OTA acceptance","text":"<ul> <li>[ ] Run a three-minute reachability preflight before staging or changing any       repeater radio settings.</li> <li>[ ] Test direct, fully controlled multi-hop, passive TempRadio hop, and mixed       controlled/passive paths independently.</li> <li>[ ] Record bytes, LoRa packets sent, packets confirmed, retries, useful       throughput, total elapsed time, and per-phase elapsed time.</li> <li>[ ] Confirm every controlled intermediate returns to its saved radio tuple.</li> <li>[ ] Verify target application and bootloader hashes after apply, not merely the       OTA tool's final status line.</li> <li>[ ] Exercise interruption/retry and confirm incomplete data cannot be approved       or booted.</li> </ul>"},{"location":"heltec_v4_wifi_partition_migration/","title":"Heltec V4 legacy-partition migration over Wi-Fi","text":"<p>Heltec V4/V4.3 OLED repeaters with their normal 16 MiB flash use the shared ESP32 Wi-Fi partition migration bridge. It changes Arduino's old <code>default.csv</code> layout, with two 1.25 MiB OTA slots, to <code>default_16MB.csv</code>, with two 6.25 MiB OTA slots.</p> <p>Build the bridge application image:</p> <pre><code>&amp; \"$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe\" run -e heltec_v4_partition_migrator\n</code></pre> <p>Upload <code>.pio/build/heltec_v4_partition_migrator/firmware.bin</code> through the legacy browser Wi-Fi updater. Rejoin <code>MeshCore-Migrate</code> with password <code>meshcore-migrate</code>; when it reports Expanded layout ready, upload the app-only Full V4 repeater image at <code>/update</code>.</p> <p>Do not use an <code>-merged.bin</code> in either browser uploader. Merged images contain bootloader and table offsets for cable flashing. The bridge preserves the private identity; other SPIFFS-backed settings may be recreated after the Full image starts.</p>"},{"location":"home_text_spacing/","title":"Home-screen text spacing","text":"<p>On non-Indicator companions, a visible Bluetooth PIN or connection status owns a separate bottom-aligned block. It replaces the ordinary inbox instruction, clock and WiFi rows while displayed. The PIN stays below the inbox title; the label and value use measured font heights, including the MeshPocket's larger e-paper font. An unusually short viewport may omit the label, never overlap the title or clip the PIN. Indicator's dedicated pairing layout is unchanged.</p> <p>The repeater home page also stacks measured font-height rows instead of fixed ten-pixel offsets. Long names and status lines are ellipsized horizontally.</p> <p>Run <code>python3 -m unittest discover -s test -p test_home_text_spacing.py -v</code> on a host with a C++ compiler. This renders the actual companion and repeater home branches, recording every text rectangle and rejecting overlaps or clipping. It covers 128x64 OLED, 160x80 T096, 250x122 MeshPocket and larger viewports, PIN/connected/disabled/prompt states, WiFi variants, long strings and a sweep of font heights. It also checks the static reader hint. The separate native display and T096 tests exercise the driver drawing/measurement methods.</p> <p>Hardware acceptance: check that the full six-digit PIN is near the bottom, with no text over it; connect/disconnect Bluetooth and verify no stale digits; then check the repeater's five rows and the V4's non-blinking reader footer.</p>"},{"location":"host_cli_service/","title":"LoRa CLI Host Service","text":"<p>The repeater <code>host &lt;text&gt;</code> command lets an authenticated LoRa administrator request a small, explicitly allowed operation from a USB-connected computer. The included Raspberry Pi endpoint supports these exact requests:</p> <pre><code>cmd host help\ncmd host cpu-temp\ncmd host hostname\ncmd host uptime\ncmd host load\ncmd host memory\ncmd host disk-free\ncmd host clock status\ncmd host clock sync\ncmd host clock set &lt;unix_epoch&gt;\ncmd host network restart\ncmd host reboot\ncmd host action status &lt;operation_id&gt;\ncmd host run &lt;alias&gt; [arguments]\n</code></pre> <p>The first seven actions after <code>help</code> are read-only. Clock changes, network restart, and reboot are opt-in actions and are disabled unless explicitly enabled. Text such as <code>reboot now</code>, <code>cpu-temp; reboot</code>, and embedded newlines is not a command: the endpoint accepts only an exact allowlist match.</p> <p>The bridge is included in normal repeater firmware except on Wio-E5. Its specialized RS232 bridge image omits the host service because the combined application exceeds the fixed 240 KiB partition; use the normal Wio-E5 repeater image when the USB/MQTT host service is needed.</p>"},{"location":"host_cli_service/#run-alongside-meshcoretomqtt","title":"Run alongside meshcoretomqtt","text":"<p><code>meshcoretomqtt</code> must remain the only process that opens the repeater USB serial port. The endpoint communicates with it through the same MQTT broker, which can be local to the Raspberry Pi:</p> <pre><code>LoRa -&gt; repeater -&gt; USB -&gt; meshcoretomqtt -&gt; MQTT -&gt; host endpoint\nLoRa &lt;- repeater &lt;- USB &lt;- meshcoretomqtt &lt;- MQTT &lt;- host endpoint\n</code></pre> <p>Clock-recovery deployments must run the loopback broker, <code>meshcoretomqtt</code>, and endpoint on the same Pi. A wrong Pi clock can prevent TLS validation against a remote broker, while split host clocks can reject the signed live claim before the correction arrives. Remote brokers remain suitable for ordinary commands when the connection and both clocks are already healthy.</p> <p>Launch <code>meshcoretomqtt</code> with its existing arguments plus <code>--debug</code>; its current debug-topic parser needs that flag to publish the repeater request record. Do not open the serial TTY from the host endpoint too.</p> <p>This feature does not compare the repeater wall clock with the Pi clock. Minutes of drift, an unset repeater clock, and later clock corrections are safe: request freshness comes from a live one-time challenge. The normal <code>meshcoretomqtt</code> <code>sync_time</code> setting may remain enabled for its other uses, but host-command authorization does not depend on it.</p> <p>Generate a dedicated service key using the Python environment installed by <code>meshcoretomqtt</code>:</p> <pre><code>sudo /opt/mctomqtt/venv/bin/python3 host_cli_service.py \\\n  --generate-key /etc/mctomqtt/host-cli-key.json\nsudo chown mctomqtt:mctomqtt /etc/mctomqtt/host-cli-key.json\nsudo chmod 600 /etc/mctomqtt/host-cli-key.json\n</code></pre> <p>Add the printed public key to the existing <code>meshcoretomqtt</code> configuration:</p> <pre><code>[remote_serial]\nenabled = true\nallowed_companions = [\n  \"SERVICE_PUBLIC_KEY_PRINTED_ABOVE\"\n]\nnonce_ttl = 120\ncommand_timeout = 10\n</code></pre> <p>Restart <code>meshcoretomqtt</code>, then run the endpoint. Replace <code>USA</code> with the exact three-character IATA namespace configured in the broker and supply the repeater's complete 64-character public key:</p> <pre><code>sudo -u mctomqtt /opt/mctomqtt/venv/bin/python3 host_cli_service.py \\\n  --broker 127.0.0.1 \\\n  --iata USA \\\n  --repeater-key REPEATER_PUBLIC_KEY \\\n  --service-key /etc/mctomqtt/host-cli-key.json\n</code></pre> <p>Add <code>--username NAME --password-file FILE</code> for broker authentication. Add <code>--tls</code>, and optionally <code>--ca-cert FILE</code>, for TLS. Custom installations can use <code>--request-topic</code> and <code>--command-topic</code> to match their broker namespace. The endpoint source and its systemd/configuration details are in <code>examples/host_cli_service</code>.</p>"},{"location":"host_cli_service/#allowlisted-programs-and-arguments","title":"Allowlisted programs and arguments","text":"<p>Add <code>--programs-file FILE</code> to expose locally selected programs as <code>host run &lt;alias&gt; [arguments]</code>. The example JSON file fixes each executable, fixed leading arguments, maximum 1-5 second runtime, and the exact remote argument schema. For example:</p> <pre><code>cmd host run fan on 15\n</code></pre> <p>The example maps that request to the fixed process argument vector:</p> <pre><code>/usr/local/bin/mesh-fan-control --source lora on 15\n</code></pre> <p>The supported argument rules are an explicit non-option <code>choice</code>, a bounded nonnegative <code>integer</code>, or a short <code>token</code> using a restricted ASCII character set. Alias lookup and every argument validation happen before process creation. Execution uses an absolute configured path, no stdin, <code>shell=False</code>, a minimal environment, and <code>/</code> as its working directory. Extra arguments, leading-option injection, shell syntax, control characters, and invalid quoting are rejected. The allowlist file and executable must not be group- or world-writable.</p> <p>Copy and edit <code>programs.example.json</code>, then give the service account only the operating-system permissions needed by those trusted programs.</p>"},{"location":"host_cli_service/#opt-in-network-and-reboot-recovery","title":"Opt-in network and reboot recovery","text":"<p>These actions use their own socket-activated root broker, independently of the clock-control broker. Installing or enabling clock control does not grant host recovery actions. Install the following as root-owned files:</p> <pre><code>sudo install -o root -g root -m 0755 meshcore_host_actions.py \\\n  /usr/local/sbin/meshcore-host-actions\nsudo install -o root -g root -m 0644 meshcore-host-actions.socket \\\n  /etc/systemd/system/meshcore-host-actions.socket\nsudo install -o root -g root -m 0644 meshcore-host-actions.service \\\n  /etc/systemd/system/meshcore-host-actions.service\nsudo install -o root -g root -m 0644 meshcore-networkmanager-restart.service \\\n  /etc/systemd/system/meshcore-networkmanager-restart.service\nsudo install -o root -g root -m 0644 meshcore-host-reboot.timer \\\n  /etc/systemd/system/meshcore-host-reboot.timer\nsudo install -o root -g root -m 0644 meshcore-host-reboot.service \\\n  /etc/systemd/system/meshcore-host-reboot.service\n</code></pre> <p>The root-owned broker policy enables nothing by default. Create a systemd drop-in and select <code>network-restart</code>, <code>reboot</code>, or both as an exact comma-separated list:</p> <pre><code>sudo systemctl edit meshcore-host-actions.service\n</code></pre> <pre><code>[Service]\nEnvironment=MESHCORE_HOST_ACTIONS=network-restart,reboot\n</code></pre> <p>Reload systemd and enable only the broker socket:</p> <pre><code>sudo systemctl daemon-reload\nsudo systemctl enable --now meshcore-host-actions.socket\n</code></pre> <p>After changing the policy on an already active installation, restart <code>meshcore-host-actions.service</code> so the broker reads the new value.</p> <p>Finally add <code>--allow-network-restart</code>, <code>--allow-reboot</code>, or both to the unprivileged endpoint. An action must pass both gates: the endpoint flag and the root-owned broker policy. The endpoint never invokes <code>sudo</code>; remove legacy <code>wifi-restart</code> program aliases and host-action sudoers entries because sudo aliases are not a fallback for this hardened service. Use the exact <code>host network restart</code> action instead.</p> <p>Systemd creates <code>/run/meshcore-host-actions.sock</code> as <code>root:mctomqtt</code> mode <code>0660</code>. The root broker authenticates both the endpoint UID and primary GID with <code>SO_PEERCRED</code>, while the endpoint authenticates the root-created listener. The protocol is one bounded ASCII line. Neither the caller nor request text can choose an executable, unit, path, or argument. The broker can start only the fixed static NetworkManager restart service or the fixed reboot timer; the broker and action units have empty capability sets and systemd sandboxing. The configured <code>mctomqtt</code> UID and its effective primary GID are the delegated local trust boundary; supplementary group membership alone is rejected.</p> <p>Side effects follow a fail-closed two-phase sequence. The endpoint reserves a canonical 128-bit operation ID with <code>PREPARE</code>, publishes its reply with MQTT QoS 1, and requires <code>wait_for_publish</code> plus <code>is_published</code> confirmation before sending one <code>COMMIT</code>. It does not block the Paho network callback while waiting. No confirmation means no commit. Reboot uses a fixed approximately 10-second timer that starts only after commit. The MQTT confirmation proves acceptance by the local broker, not delivery over USB and LoRa; there is no correlated serial delivery acknowledgement, so the physical reply is best effort.</p> <p><code>network restart</code> deliberately drops Wi-Fi and Tailscale management while NetworkManager restarts. Use a loopback MQTT broker and keep the broker, <code>meshcoretomqtt</code>, host endpoint, and USB device services independent of NetworkManager: they must not have <code>Requires=</code>, <code>BindsTo=</code>, or ordering dependencies on it. This preserves the local reply/commit path while remote management temporarily disappears.</p> <p>The operation ID is derived from the authenticated repeater key, request ID, and nonce. The reply displays it, and its state can be queried later:</p> <pre><code>cmd host action status 0123456789ABCDEF0123456789ABCDEF\n</code></pre> <p>The root broker retains at most 64 records for the current boot. It persists <code>prepared</code> before replying and <code>in-progress</code> before scheduling, schedules a committed operation at most once, and never automatically retries an ambiguous outcome. A broker restart converts recovered <code>in-progress</code> to <code>ambiguous</code>. Only an old uncommitted <code>prepared</code> record may be evicted; otherwise a full store rejects new work. Reusing an operation ID for a different action is rejected. <code>scheduled</code> means PID 1 accepted the fixed unit job; it does not claim that the subsequent network restart or reboot completed successfully.</p> <p>A distinct reboot is rejected while another reboot is committed or ambiguous, so a second request cannot falsely promise a fresh 10-second timer while the first timer is already running. A new reboot reservation may supersede only an older, uncommitted reboot reservation; the superseded operation can no longer be committed.</p>"},{"location":"host_cli_service/#opt-in-clock-recovery","title":"Opt-in clock recovery","text":"<p><code>clock status</code> reports the Pi epoch and NTP synchronization state without root access. To enable the exact <code>clock sync</code> and <code>clock set &lt;unix_epoch&gt;</code> actions, install <code>meshcore_clock_control.py</code> as <code>/usr/local/sbin/meshcore-clock-control</code>, owned by root and mode <code>0755</code>, then install the accompanying <code>meshcore-clock-control.socket</code> and <code>meshcore-clock-control.service</code> and static <code>meshcore-chrony-step.service</code> files in <code>/etc/systemd/system</code> as root-owned mode-<code>0644</code> files:</p> <pre><code>sudo install -o root -g root -m 0755 meshcore_clock_control.py \\\n  /usr/local/sbin/meshcore-clock-control\nsudo install -o root -g root -m 0644 meshcore-clock-control.socket \\\n  /etc/systemd/system/meshcore-clock-control.socket\nsudo install -o root -g root -m 0644 meshcore-clock-control.service \\\n  /etc/systemd/system/meshcore-clock-control.service\nsudo install -o root -g root -m 0644 meshcore-chrony-step.service \\\n  /etc/systemd/system/meshcore-chrony-step.service\nsudo systemctl daemon-reload\nsudo systemctl enable --now meshcore-clock-control.socket\n</code></pre> <p>The socket is fixed at <code>/run/meshcore-clock-control.sock</code>; systemd creates it as <code>root:mctomqtt</code> with mode <code>0660</code>. Run the endpoint as user and primary group <code>mctomqtt</code>, then add <code>--allow-clock-control</code>. The endpoint validates the socket metadata and authenticates the connected server as root with Linux <code>SO_PEERCRED</code>. The root service independently requires the peer's UID and primary GID to match <code>mctomqtt:mctomqtt</code> before it reads or executes a request. No clock-control sudo rule is used; remove old clock-helper sudoers lines when upgrading.</p> <p>Both layers require one canonical unsigned decimal argument with no sign, leading zero, whitespace, or trailing text. The accepted epoch range is 2020 through 2099. The private protocol accepts only the complete bounded ASCII lines <code>sync</code> and <code>set &lt;epoch&gt;</code>. Every child process uses a fixed absolute argv, <code>shell=False</code>, and a timeout no longer than 1.5 seconds.</p> <p><code>clock set</code> changes <code>CLOCK_REALTIME</code> without disabling NTP, then requests an NTP step. If the NTP request fails, the response honestly reports that the clock changed and which synchronization step remains incomplete. If <code>clock sync</code> enables NTP but the explicit step/restart fails, that partial outcome is also reported. When chrony is available, the root broker starts only the fixed static <code>meshcore-chrony-step.service</code>. That hardened one-shot runs <code>/usr/bin/chronyc -a makestep</code> as <code>_chrony:_chrony</code>, with no capabilities, <code>AF_UNIX</code> only, and a one-second start timeout; it can therefore reach chrony's private runtime socket without broadening the root broker. The <code>_chrony</code> account comes from the Debian/Raspberry Pi chrony package. Without chrony, the broker restarts systemd-timesyncd. Clock drift cannot authorize a captured command: the signed request still needs the repeater's live one-time claim, whose deadline is monotonic rather than wall-clock based.</p>"},{"location":"host_cli_service/#trust-and-injection-controls","title":"Trust and injection controls","text":"<p>The MQTT broker transports records but does not establish their authenticity. The endpoint checks the configured repeater identity and verifies its Ed25519 signature over the complete request ID, random nonce, and Base64URL request. It also validates framing, UTF-8, and byte limits. It does not execute that first record.</p> <p>Instead, the endpoint stores the request in memory, creates a random 64-bit challenge, and sends <code>@claim=&lt;random&gt;</code> through <code>meshcoretomqtt</code>'s signed serial channel. The repeater accepts it only from physical USB while the exact ID and nonce are pending, then signs a <code>CLAIMED</code> proof containing the challenge. Only a matching live proof lets the endpoint perform allowlist matching and execute the action. It consumes the proof before execution, so MQTT redelivery cannot execute an action twice.</p> <p>A captured request only causes a new challenge that an idle repeater refuses. A captured proof does not match a new challenge, and restarting the endpoint forgets pending challenges. Repeater/Pi clock drift therefore cannot turn an old <code>reboot</code> or <code>run</code> record into a valid action. The reply and claim commands still use short-lived JWTs; <code>meshcoretomqtt</code> checks their signer allowlist, target, expiration, signature, and separate replay nonce. Wall-clock expiry and its in-memory nonce cache are not sufficient across a backward clock jump plus restart; the firmware's live one-time claim is what protects these host actions. Keep recovery-mode <code>allowed_companions</code> limited to the dedicated service key, with the endpoint and <code>meshcoretomqtt</code> on the same Pi.</p> <p>Newlines and other reply control characters are converted to spaces and are also independently rejected by the firmware parser.</p> <p>Protect the service private key and use broker ACLs that allow it to subscribe only to the selected repeater debug topic and publish only to that repeater serial-command topic. A private key listed in <code>allowed_companions</code> is trusted to sign serial requests.</p>"},{"location":"host_cli_service/#limits","title":"Limits","text":"<ul> <li>The request is at most 155 UTF-8 bytes after <code>host</code>, or 152 bytes with the   legacy three-byte companion correlation prefix.</li> <li>The complete LoRa reply is at most 162 UTF-8 bytes.</li> <li>Only one host request can be pending per repeater.</li> <li>Only one privileged action or action-status query can be active; overlapping   work is rejected before reservation.</li> <li>The live claim must complete within 4 seconds. Allowlisted programs have a   configured 1-5 second child-process timeout. Privileged actions and status   queries share one 5-second broker/reply-confirmation deadline.</li> <li><code>host.reply</code> is accepted only through physical USB, not LoRa or Ethernet.</li> </ul> <p>Use <code>cmd get host</code> to report the bridge state and limits.</p>"},{"location":"kiss_modem_protocol/","title":"MeshCore KISS Modem Protocol","text":"<p>Standard KISS TNC firmware for MeshCore LoRa radios. Compatible with any KISS client (Direwolf, APRSdroid, YAAC, etc.) for sending and receiving raw packets. MeshCore-specific extensions (cryptography, radio configuration, telemetry) are available through the standard SetHardware (0x06) command.</p> <p>KISS protocol version 2 adds an opt-in logical port 1 for MeshCore's second time-shared LoRa profile. It is still one physical transceiver: the firmware fast-switches between <code>radio</code> and <code>radio2</code>; it does not create a second radio.</p>"},{"location":"kiss_modem_protocol/#serial-configuration","title":"Serial Configuration","text":"<p>115200 baud, 8N1, no flow control.</p>"},{"location":"kiss_modem_protocol/#frame-format","title":"Frame Format","text":"<p>Standard KISS framing per the KA9Q/K3MC specification.</p> Byte Name Description <code>0xC0</code> FEND Frame delimiter <code>0xDB</code> FESC Escape character <code>0xDC</code> TFEND Escaped FEND (FESC + TFEND = 0xC0) <code>0xDD</code> TFESC Escaped FESC (FESC + TFESC = 0xDB) <pre><code>+------+-----------+--------------+------+\n| FEND | Type Byte | Data (escaped)| FEND |\n| 0xC0 |  1 byte   | 0-510 bytes  | 0xC0 |\n+------+-----------+--------------+------+\n</code></pre>"},{"location":"kiss_modem_protocol/#type-byte","title":"Type Byte","text":"<p>The type byte is split into two nibbles:</p> Bits Field Description 7-4 Port <code>0</code> primary <code>radio</code>; <code>1</code> secondary <code>radio2</code> for Data only in protocol v2; controls stay on port 0 3-0 Command Command number <p>Maximum unescaped frame size: 512 bytes.</p>"},{"location":"kiss_modem_protocol/#standard-kiss-commands","title":"Standard KISS Commands","text":""},{"location":"kiss_modem_protocol/#host-to-tnc","title":"Host to TNC","text":"Command Value Data Description Data <code>0x00</code> Raw packet Queue on primary <code>radio</code>; use type <code>0x10</code> to queue on <code>radio2</code> in v2 (one pending packet total) TXDELAY <code>0x01</code> Delay (1 byte) Transmitter keyup delay in 10ms units (default: 50 = 500ms) Persistence <code>0x02</code> P (1 byte) CSMA persistence parameter 0-255 (default: 63) SlotTime <code>0x03</code> Interval (1 byte) CSMA slot interval in 10ms units (default: 10 = 100ms) TXtail <code>0x04</code> Delay (1 byte) Post-TX hold time in 10ms units (default: 0) FullDuplex <code>0x05</code> Mode (1 byte) 0 = half duplex, nonzero = full duplex (default: 0) SetHardware <code>0x06</code> Sub-command + data MeshCore extensions (see below) Return <code>0xFF</code> - Exit KISS mode (no-op)"},{"location":"kiss_modem_protocol/#tnc-to-host","title":"TNC to Host","text":"Type Value Data Description Data <code>0x00</code> Raw packet Received packet from primary <code>radio</code> Data <code>0x10</code> Raw packet Received packet from secondary <code>radio2</code> (v2) <p>Data frames carry raw packet data only, with no metadata prepended. The Data command payload is limited to 255 bytes to match the MeshCore maximum transmission unit (MAX_TRANS_UNIT); frames larger than 255 bytes are silently dropped. The KISS specification recommends at least 1024 bytes for general-purpose TNCs; this modem is intended for MeshCore packets only, whose protocol MTU is 255 bytes. A v2 port-1 Data packet reaches RF only while <code>radio2</code> is configured <code>rxtx</code>; with <code>off</code> or <code>rx</code>, the modem returns <code>TxDone(0)</code> and never falls back to primary.</p> <p>Only one packet may be pending for radio transmission at a time. If the host sends a second Data frame before the first has completed, the modem responds with Error (0xF1) and TxBusy (0x07).</p>"},{"location":"kiss_modem_protocol/#fast-dual-profile-receive-switching","title":"Fast dual-profile receive switching","text":"<p>After OpenHop (or another KISS client) configures <code>radio2</code> or <code>tempradio2</code>, the board's <code>radio_driver.loop()</code> performs the RF hops locally. KISS does not send a command for every hop: that would be slower than the serial link alone. The shared scanner uses a 600 \u00b5s nominal retune allowance per hop, with the profile timing/preamble calculation accounting for it. It is a measured target rather than a hard maximum; packet handling and a slow board loop can extend an individual hop. The KISS parser services at most 32 incoming bytes per outer loop so a busy OpenHop serial peer cannot starve the scanner.</p> <p>Thus \u201caround 0.6 ms\u201d refers to the on-board RF setting transition, not a full host-to-board request/response round trip. The returned Data port (<code>0x00</code> or <code>0x10</code>) identifies which profile actually received each packet.</p> <p><code>SetRadio2</code> and <code>SetTempRadio2</code> acknowledge that their tuple was accepted and scheduled; they do not acknowledge that a receiver has already entered that tuple. The next local scanner service performs the retune. KISS clients should configure the profiles once and let the board perform automatic time-sharing; a 115200-baud serial round trip cannot be a 0.6 ms receive-hop control plane. Clients that need temporary-lease state can poll <code>GetTempRadio2</code>.</p>"},{"location":"kiss_modem_protocol/#host-output-backpressure","title":"Host Output Backpressure","text":"<p>Outbound frames are encoded into a 2-slot queue and flushed when serial output space is available; <code>loop()</code> never blocks on writes. Radio TX state advances independently of host read speed. TxDone is retained until it can be queued. If the outbound queue is full, the modem responds with Error (0xF1) and TxBusy (0x07). Hosts should read serial promptly to avoid delayed responses.</p>"},{"location":"kiss_modem_protocol/#csma-behavior","title":"CSMA Behavior","text":"<p>The TNC implements p-persistent CSMA for half-duplex operation:</p> <ol> <li>When a packet is queued, monitor carrier detect</li> <li>When the channel clears, generate a random value 0-255</li> <li>If the value is less than or equal to P (Persistence), wait TXDELAY then transmit</li> <li>Otherwise, wait SlotTime and repeat from step 1</li> </ol> <p>In full-duplex mode, CSMA is bypassed and packets transmit after TXDELAY.</p>"},{"location":"kiss_modem_protocol/#sethardware-extensions-0x06","title":"SetHardware Extensions (0x06)","text":"<p>MeshCore-specific functionality uses the standard KISS SetHardware command. The first byte of SetHardware data is a sub-command. Standard KISS clients ignore these frames.</p>"},{"location":"kiss_modem_protocol/#frame-format_1","title":"Frame Format","text":"<pre><code>+------+------+-------------+--------------+------+\n| FEND | 0x06 | Sub-command | Data (escaped)| FEND |\n| 0xC0 |      |   1 byte    |   variable   | 0xC0 |\n+------+------+-------------+--------------+------+\n</code></pre>"},{"location":"kiss_modem_protocol/#request-sub-commands-host-to-tnc","title":"Request Sub-commands (Host to TNC)","text":"Sub-command Value Data GetIdentity <code>0x01</code> - GetRandom <code>0x02</code> Length (1 byte, 1-64) VerifySignature <code>0x03</code> PubKey (32) + Signature (64) + Data SignData <code>0x04</code> Data to sign EncryptData <code>0x05</code> Key (32) + Plaintext DecryptData <code>0x06</code> Key (32) + MAC (2) + Ciphertext KeyExchange <code>0x07</code> Remote PubKey (32) Hash <code>0x08</code> Data to hash SetRadio <code>0x09</code> Freq (4) + BW (4) + SF (1) + CR (1) SetTxPower <code>0x0A</code> Power dBm (1) GetRadio <code>0x0B</code> - GetTxPower <code>0x0C</code> - GetCurrentRssi <code>0x0D</code> - IsChannelBusy <code>0x0E</code> - GetAirtime <code>0x0F</code> Packet length (1) GetNoiseFloor <code>0x10</code> - GetVersion <code>0x11</code> - GetStats <code>0x12</code> - GetBattery <code>0x13</code> - GetMCUTemp <code>0x14</code> - GetSensors <code>0x15</code> Permissions (1) GetDeviceName <code>0x16</code> - Ping <code>0x17</code> - Reboot <code>0x18</code> - SetSignalReport <code>0x19</code> Enable (1): 0x00=disable, nonzero=enable GetSignalReport <code>0x1A</code> - SetRadio2 <code>0x1B</code> Radio2 parameters (13; see below) GetRadio2 <code>0x1C</code> - SetTempRadio2 <code>0x1D</code> Radio2 parameters + duration (15) GetTempRadio2 <code>0x1E</code> -"},{"location":"kiss_modem_protocol/#response-sub-commands-tnc-to-host","title":"Response Sub-commands (TNC to Host)","text":"<p>Response codes use the high-bit convention: <code>response = command | 0x80</code>. Generic and unsolicited responses use the <code>0xF0</code>+ range.</p> Sub-command Value Data Identity <code>0x81</code> PubKey (32) Random <code>0x82</code> Random bytes (1-64) Verify <code>0x83</code> Result (1): 0x00=invalid, 0x01=valid Signature <code>0x84</code> Signature (64) Encrypted <code>0x85</code> MAC (2) + Ciphertext Decrypted <code>0x86</code> Plaintext SharedSecret <code>0x87</code> Shared secret (32) Hash <code>0x88</code> SHA-256 hash (32) Radio <code>0x8B</code> Freq (4) + BW (4) + SF (1) + CR (1) TxPower <code>0x8C</code> Power dBm (1) CurrentRssi <code>0x8D</code> RSSI dBm (1, signed) ChannelBusy <code>0x8E</code> Result (1): 0x00=clear, 0x01=busy Airtime <code>0x8F</code> Milliseconds (4) NoiseFloor <code>0x90</code> dBm (2, signed) Version <code>0x91</code> Version (1) + Reserved (1) Stats <code>0x92</code> RX (4) + TX (4) + Errors (4) Battery <code>0x93</code> Millivolts (2) MCUTemp <code>0x94</code> Temperature (2, signed) Sensors <code>0x95</code> CayenneLPP payload DeviceName <code>0x96</code> Name (variable, UTF-8) Pong <code>0x97</code> - SignalReport <code>0x9A</code> Status (1): 0x00=disabled, 0x01=enabled Radio2 <code>0x9C</code> Saved radio2 parameters (13) TempRadio2 <code>0x9E</code> Active temporary radio2 + remaining minutes (15) OK <code>0xF0</code> - Error <code>0xF1</code> Error code (1) TxDone <code>0xF8</code> Result (1): 0x00=failed, 0x01=success RxMeta <code>0xF9</code> SNR (1) + RSSI (1)"},{"location":"kiss_modem_protocol/#error-codes","title":"Error Codes","text":"Code Value Description InvalidLength <code>0x01</code> Request data too short InvalidParam <code>0x02</code> Invalid parameter value NoCallback <code>0x03</code> Feature not available MacFailed <code>0x04</code> MAC verification failed UnknownCmd <code>0x05</code> Unknown sub-command EncryptFailed <code>0x06</code> Encryption failed TxBusy <code>0x07</code> Radio TX busy, or host output queue full"},{"location":"kiss_modem_protocol/#unsolicited-events","title":"Unsolicited Events","text":"<p>The TNC sends these SetHardware frames without a preceding request:</p> <p>TxDone (0xF8): Sent after radio transmission completes. Contains a single byte: 0x01 for success, 0x00 for failure. Delivery to the host may be delayed under serial backpressure but is not dropped.</p> <p>RxMeta (0xF9): Sent after each Data frame (type 0x00 or v2 type 0x10) with SNR (1 byte, signed, value x4) and RSSI (1 byte, signed, dBm). It remains exactly two bytes; the Data port identifies the receiving profile. Queued with the data frame; omitted if the data frame cannot be queued. Enabled by default; toggle with SetSignalReport. Standard KISS clients ignore this frame.</p>"},{"location":"kiss_modem_protocol/#data-formats","title":"Data Formats","text":""},{"location":"kiss_modem_protocol/#radio-parameters-setradio-radio-response","title":"Radio Parameters (SetRadio / Radio response)","text":"<p>All values little-endian.</p> Field Size Description Frequency 4 bytes Hz (e.g., 869618000) Bandwidth 4 bytes Hz (e.g., 62500) SF 1 byte Spreading factor (5-12) CR 1 byte Coding rate (5-8)"},{"location":"kiss_modem_protocol/#secondary-radio-parameters-setradio2-radio2-response","title":"Secondary Radio Parameters (SetRadio2 / Radio2 response)","text":"<p><code>SetRadio2</code> is the binary KISS equivalent of <code>radio2</code>. It changes only RAM state for this KISS session; it does not write the Mesh CLI profile file. All values are little-endian. The mode values are <code>0=off</code>, <code>1=rx</code>, and <code>2=rxtx</code>. An <code>off</code> tuple may contain zero radio parameters, which are ignored.</p> Field Size Description Frequency 4 bytes Hz Bandwidth 4 bytes Hz SF 1 byte Spreading factor (5-12) CR 1 byte Coding rate (5-8) Mode 1 byte <code>off</code>, <code>rx</code>, or <code>rxtx</code> as above Preamble 2 bytes Symbols; <code>0</code> chooses automatic <p><code>GetRadio2</code> returns this exact 13-byte tuple. The modem preserves the exact frequency and bandwidth values sent by the host even though its radio driver uses floating-point MHz/kHz internally.</p>"},{"location":"kiss_modem_protocol/#temporary-secondary-radio-settempradio2-tempradio2-response","title":"Temporary Secondary Radio (SetTempRadio2 / TempRadio2 response)","text":"<p><code>SetTempRadio2</code> is the binary KISS equivalent of <code>tempradio2</code>: the 13-byte secondary tuple followed by <code>duration_minutes:u16</code>, from 1 to 10080. It is RAM-only and automatically restores the saved <code>radio2</code> tuple on expiry or reboot. A mode <code>off</code> with duration zero cancels the temporary lease and immediately restores saved <code>radio2</code>; all other <code>off</code>/zero-duration combinations are invalid. <code>GetTempRadio2</code> returns the active 13-byte tuple plus remaining minutes, rounded up. It returns a zero/off tuple with zero duration when no temporary lease is active.</p> <p>Changing saved <code>radio2</code> during an active temporary lease does not interrupt the active tuple; the replacement becomes active when the lease ends. Pending KISS Data is bound to a profile generation at queue time. If that profile is replaced before RF transmission begins, the modem sends normal <code>TxDone(0)</code> and never falls back to the other profile.</p>"},{"location":"kiss_modem_protocol/#version-version-response","title":"Version (Version response)","text":"Field Size Description Version 1 byte Firmware version Reserved 1 byte Always 0"},{"location":"kiss_modem_protocol/#encrypted-encrypted-response","title":"Encrypted (Encrypted response)","text":"Field Size Description MAC 2 bytes HMAC-SHA256 truncated to 2 bytes Ciphertext variable AES-128 block-encrypted data with zero padding"},{"location":"kiss_modem_protocol/#airtime-airtime-response","title":"Airtime (Airtime response)","text":"<p>All values little-endian.</p> Field Size Description Airtime 4 bytes uint32_t, estimated air time in milliseconds"},{"location":"kiss_modem_protocol/#noise-floor-noisefloor-response","title":"Noise Floor (NoiseFloor response)","text":"<p>All values little-endian.</p> Field Size Description Noise floor 2 bytes int16_t, dBm (signed) <p>The modem recalibrates the noise floor every 2 seconds with an AGC reset every 30 seconds.</p>"},{"location":"kiss_modem_protocol/#stats-stats-response","title":"Stats (Stats response)","text":"<p>All values little-endian.</p> Field Size Description RX 4 bytes Packets received TX 4 bytes Packets transmitted Errors 4 bytes Receive errors"},{"location":"kiss_modem_protocol/#battery-battery-response","title":"Battery (Battery response)","text":"<p>All values little-endian.</p> Field Size Description Millivolts 2 bytes uint16_t, battery voltage in mV"},{"location":"kiss_modem_protocol/#mcu-temperature-mcutemp-response","title":"MCU Temperature (MCUTemp response)","text":"<p>All values little-endian.</p> Field Size Description Temperature 2 bytes int16_t, tenths of degC (e.g., 253 = 25.3degC) <p>Returns <code>NoCallback</code> error if the board does not support temperature readings.</p>"},{"location":"kiss_modem_protocol/#device-name-devicename-response","title":"Device Name (DeviceName response)","text":"Field Size Description Name variable UTF-8 string, no null terminator"},{"location":"kiss_modem_protocol/#reboot","title":"Reboot","text":"<p>Sends an <code>OK</code> response, flushes serial, then reboots the device. The host should expect the connection to drop.</p>"},{"location":"kiss_modem_protocol/#sensor-permissions-getsensors","title":"Sensor Permissions (GetSensors)","text":"Bit Value Description 0 <code>0x01</code> Base (battery) 1 <code>0x02</code> Location (GPS) 2 <code>0x04</code> Environment (temp, humidity, pressure) <p>Use <code>0x07</code> for all permissions.</p>"},{"location":"kiss_modem_protocol/#sensor-data-sensors-response","title":"Sensor Data (Sensors response)","text":"<p>Data returned in CayenneLPP format. See CayenneLPP documentation for parsing.</p>"},{"location":"kiss_modem_protocol/#cryptographic-algorithms","title":"Cryptographic Algorithms","text":"Operation Algorithm Identity / Signing / Verification Ed25519 Key Exchange X25519 (ECDH) Encryption AES-128 block encryption with zero padding + HMAC-SHA256 (MAC truncated to 2 bytes) Hashing SHA-256"},{"location":"kiss_modem_protocol/#notes","title":"Notes","text":"<ul> <li>Data payload limit (255 bytes) matches MeshCore MAX_TRANS_UNIT; no change needed for KISS \"1024+ recommended\" (that applies to general TNCs, not MeshCore)</li> <li>Modem generates identity on first boot (stored in flash)</li> <li>All multi-byte values are little-endian unless stated otherwise</li> <li>SNR values in RxMeta are multiplied by 4 for 0.25 dB precision</li> <li>TxDone is sent as a SetHardware event after each transmission</li> <li>Legacy KISS clients use only type 0x00 data and remain compatible. Version-2-aware clients can use type 0x10 to send on, or identify reception from, <code>radio2</code>.</li> <li>Standard KISS clients can safely ignore all SetHardware (0x06) frames</li> <li>See packet_format.md for packet format</li> </ul>"},{"location":"lora_ota_automation/","title":"Scripted LoRa OTA from start to finish","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>The dedicated RAK3401 chain report records the physical failures of withdrawn migrations and the physically qualified compact nine-step replacement. Its runner blocks the withdrawn chains and pins every accepted bridge image by SHA-256.</p> <p><code>tools/lora_ota/lora_ota.sh</code> and <code>tools/lora_ota/lora_ota.ps1</code> automate a MeshCore LoRa firmware update from a release <code>.zip</code> or ready <code>.mota</code>. They identify the destination, validate the hardware and running firmware, prepare the right container, move the participating nodes to a temporary radio channel, serve and monitor the download, request installation, restore the controller, and check the rebooted node.</p> <p>The script cannot install the destination's first OTA-capable firmware. It can stage signed v3 bootloader containers with <code>--no-install</code>, but never sends the privileged bootloader install command. Invalid v2 containers carrying the bootloader flag remain rejected. Do the first nRF52 bootloader installation over USB. An already-capable, explicitly supported internal-flash, XIAO QSPI, or exact MeshTower V2 microSD repeater may later use the separate manual <code>ota bootloader install</code> workflow.</p>"},{"location":"lora_ota_automation/#required-topology","title":"Required topology","text":"<p>The reliable serial topology uses two local radios:</p> <pre><code>                                      authenticated admin commands\ncomputer -- MeshCore binary API --&gt; controller Companion -------------------+\n   |                                                                         |\n   +-- raw text CLI + mOTA seeder --&gt; OTA source ---- LoRa OTA blocks ----&gt; target\n                                                        |                    ^\n                                                        +-- relay(s) --------+\n</code></pre> <ul> <li>Controller: a Companion connected through serial, TCP, or BLE. The   script uses <code>meshcli</code> to send remote admin commands to the target and changes   the controller's live radio parameters during the transfer. A serial   Companion stays in its normal Binary USB mode at 115200 baud.</li> <li>OTA source: an OTA-enabled repeater/FULL node whose USB port is a raw   text CLI, an ESP32 <code>companion_radio_full</code> using WiFi ports 5001 and 5002, or   an nRF52 <code>companion_radio_full</code> whose USB port switches between Binary,   terminal control, and exclusive mOTA seeding.</li> <li>Target: an OTA-enabled ESP32 or nRF52 node present in the controller's   contact list. Its admin password is required.</li> <li>Relays: optional. They do not need to install OTA themselves, but every   relay on the path must be running current firmware and have an overlapping   TempRadio window.</li> </ul> <p>One serial port cannot serve both controller roles: <code>meshcli</code> must keep reopening the controller while <code>motatool</code> owns the source port. The script rejects an attempt to use the same port for both.</p> <p>The USB ASCII switch (<code>+++MESHCORE-TERM-START</code>) is the local control path, not the mOTA data framing. On an nRF52 dual-CDC Full Companion, the script uses that mode briefly for <code>ota status</code> and TempRadio commands. It then closes the CLI and starts <code>motatool</code>; the exact <code>ota folder on</code> preamble switches the same USB interface <code>00</code> into exclusive mOTA mode from either startup ASCII or Binary Companion mode. If USB logging was enabled and the Full Companion rebooted, its separate interface <code>02</code> continues to provide plaintext logging and is not a controller or source port. With default logging off, interface <code>02</code> is not enumerated. BLE remains available.</p> <p>ESP32 Full Companion normally uses its dedicated TCP seeder on port 5001. ESP32 builds that also retain serial folder support use the same exclusive USB mOTA ownership state as nRF52. The exact <code>ota folder on</code> line transfers the USB port from startup ASCII or idle Binary Companion mode before binary mOTA frames begin; neither console mode shares that port until the folder detaches.</p>"},{"location":"lora_ota_automation/#bootloader-packages-and-station-identifiers","title":"Bootloader packages and station identifiers","text":"<p>Both wrappers use the same package-aware runner. It identifies application versus bootloader updates from container metadata, not filenames. A ZIP mixing application inputs and bootloader mOTAs requires <code>--zip-member</code>; their versions and target IDs are independent and must not be ranked together.</p> <p>Signed format-3 nRF52 bootloader packages can be staged with <code>--no-install</code>. Use the same controller/source/TempRadio arguments as an application transfer, but provide the bootloader <code>.mota</code> (or its ZIP member) and <code>--no-install</code>. Without that flag, even <code>--yes</code> stops before opening a radio. Bootloader staging requires Python <code>cryptography</code> in the interpreter running the wrapper and a current <code>motatool</code> supporting format 3. The runner reuses <code>tools/mota/motalib.py</code> for strict geometry, embedded identity/CRC, capability, hash and signature validation, and still runs <code>motatool verify</code> including any <code>--public-key</code> pin.</p> <p>If Python cannot load <code>cryptography</code>, an interactive run offers:</p> <pre><code>Install cryptography privately and retry signature verification? [y/N]\n</code></pre> <p>After approval, it uses the exact running Python interpreter to install <code>cryptography==50.0.1</code> and its dependencies from PyPI into a separate per-user, per-interpreter cache. Binary wheels only are accepted; the repair does not compile native code, overwrite system/virtual-environment packages, change PATH, use <code>sudo</code>, or bypass externally-managed Python protections. It checks Ed25519 against a known valid signature and a tampered message, then retries the original full package verification. A later run can reuse a working cache without another download. This works for direct <code>.mota</code> files and bootloader members inside ZIPs; ordinary application updates and raw <code>--tcp-cli</code> commands do not need this library.</p> <p>The interpreter must have working pip. If pip is missing, the script gives an exact-interpreter <code>ensurepip</code> command and operating-system pip/venv guidance; it does not silently install system tools. No compatible binary wheel, an old pip, network/download failures, an unwritable cache, or a failed signature check stop the run before radio access. Pip output is shown and installation is bounded at ten minutes. The radio admin-password environment variable is not passed to pip. Partial installation files may remain in the displayed private directory. The cache is under <code>meshcore-lora-ota/python/&lt;interpreter-id&gt;/cryptography==50.0.1</code> in the same per-user cache base described below for <code>motatool</code>.</p> <p>Only <code>y</code> or <code>yes</code> approves this repair; <code>--yes</code> is not installation consent. Noninteractive runs print a copyable private-install command and stop. After running that command manually, rerun the original OTA command; no Python path changes are needed. Declining never skips signature verification.</p> <p>It probes actual <code>motatool inspect</code> support before radio access: older and newer builds may advertise the same version. If the tool is missing or incompatible, an interactive run offers an automatic repair:</p> <pre><code>Install this bootloader-capable motatool and continue after verification? [y/N]\n</code></pre> <p>Only <code>y</code> or <code>yes</code> approves installation. <code>--yes</code> does not approve host software installation. Noninteractive runs stop and print a copyable manual installation command plus the <code>--motatool</code> argument to use afterward.</p> <p>The motatool repair builds the mikecarper/motatool fork at pinned revision <code>8c38369e7d35ad50cf74261869676d52dd24adf7</code>, with Cargo's <code>--locked</code> dependencies, in a separate per-user cache directory. It needs matching stable Cargo and rustc 1.86.0 or newer and a native linker already installed; otherwise it points to Rust installation and stops without installing anything. The pinned dependency set needs more than the older <code>rust-version</code> in motatool's own manifest: <code>zeroize 1.9.0</code> needs edition 2024, and ICU/idna dependencies need Rust 1.86. Cargo 1.75 is a version problem, not a root-permission problem; no nightly toolchain is necessary.</p> <p>Before asking to build or downloading crates, the runner checks both executable versions. It keeps a compatible default pair; otherwise it looks for versioned executables on PATH (such as Ubuntu's <code>cargo-1.91</code> and <code>rustc-1.91</code>) and already installed stable rustup toolchains. It displays the selected paths and pins both for the build process, so a newer Cargo cannot silently invoke an old rustc. Rustup proxies are resolved to their actual toolchain binaries before changing to the build directory. No default toolchain, symlink, system PATH, or package installation is changed, and probes disable rustup's automatic toolchain install. Tool version probes have ten-second timeouts. A working cached motatool does not need Cargo or Rust checks at all.</p> <p>To choose a pair explicitly, append:</p> <pre><code>--cargo cargo-1.91 --rustc rustc-1.91\n</code></pre> <p>These options also accept executable paths, not shell aliases or a command with embedded arguments. Explicit selections and <code>RUSTC</code>/<code>CARGO_BUILD_RUSTC</code> compiler overrides are honored; if incompatible, they fail instead of silently selecting another compiler. <code>--rustc</code> takes precedence over those environment variables. The manual build command includes the chosen compiler as well as Cargo. Native linker, SDK, and system-library availability are still checked by the real build; a passed version check is not a guarantee that every host prerequisite is present. Source/dependency downloads, build time and disk use are disclosed before confirmation. Cargo progress is displayed, with a one-hour build timeout. The radio admin-password environment variable is not passed to the build.</p> <p>The installer does not overwrite the selected/system <code>motatool</code> or alter PATH. It may replace only a previous copy in its displayed private install directory. After installation it repeats the bootloader-package capability check and uses the new binary for this run only if that check passes. A later run using the default <code>motatool</code> selection can reuse the checked cache without downloading again; switching from an explicit <code>--motatool</code> path still asks permission. Refusal, a failed build, or a failed recheck stops before opening any radio. Failed build files may remain in the displayed cache directory for diagnostics.</p> <p>The install root is <code>meshcore-lora-ota/motatool/&lt;revision&gt;</code> under <code>%LOCALAPPDATA%</code> on Windows, <code>~/Library/Caches</code> on macOS, or <code>$XDG_CACHE_HOME</code> (default <code>~/.cache</code>) on Linux. Cargo uses an explicit <code>--root</code>, <code>--rev</code>, and <code>--locked</code> instead of replacing a global installation or following a moving branch.</p> <p>Before transfer it queries the destination's <code>ota bootloader status</code>, checks its bootloader-specific target/hardware identity, installed ABI/codecs and matching internal/QSPI/SD storage profile. It does not compare an application version or application target ID to a bootloader package. After transfer it checks the destination's exact staged MID and image-hash confirmation, then prints the manual command; it never sends a bootloader install command:</p> <pre><code>ota bootloader status\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Review and send those commands on the destination, not the source. The device independently enforces signer authorization, safe live storage, continuity and upgrade-only policy at installation. <code>--base</code>, <code>--allow-non-upgrade</code>, and <code>--prepare-only</code> remain application-only. See the bootloader prerequisites and recovery limits.</p> <p><code>TARGET_NODE</code>, <code>--relay</code>, and <code>--source-contact</code> accept a contact name, full public key, or unique hexadecimal key prefix. The runner reads the controller's existing contact table and binds each selection to a full key before remote commands, so emoji names need not be typed and later name changes cannot redirect the run. Duplicate names, ambiguous prefixes, or the same radio under different participant aliases stop with an actionable error. Missing destination and relay contacts must first be imported or discovered. A missing connected source can be imported with the confirmation prompt below; a key alone does not create a contact.</p> <p>For a separate source with a managed USB/TCP console, automatic source selection reads the physical source's full public key and matches it in the controller's contacts. Repeaters use <code>get public.key</code>. Full Companion does not implement that repeater command: on both USB and TCP, its key is read from a fresh terminal welcome banner, with a supported <code>ver</code> reply on the same connection proving the terminal is live. USB briefly uses the existing STOP/START/STOP terminal wrapper to obtain that banner, even for an ASCII-first Full Companion; TCP reads the greeting from a new connection. Identity rechecks repeat this exchange rather than trusting a key cached from an earlier connection.</p> <p><code>ota status</code> identifies the Full Companion seeder role before this probe. For unrecognized firmware, only an explicit unsupported <code>get public.key</code> response can trigger the Companion fallback. Timeouts, permission errors, malformed keys, missing/ambiguous banners, and failed <code>ver</code> replies still stop the run. Firmware that exposes neither identity mechanism needs a supported terminal firmware; the runner does not guess a key from the node name or skip the identity check.</p> <p>Source selection does not require the source's current name to match an old saved advert, and duplicate/emoji names cannot redirect this lookup. An explicit <code>--source-contact</code> must identify that same physical source. If its key is missing, an interactive run offers:</p> <pre><code>Add the connected OTA source to this controller's contacts? [y/N]\n</code></pre> <p>This works through both the shell and PowerShell launchers. The runner reads the source's existing <code>card</code> command over USB/TCP, checks the full key in its contact card against the connected source, and shows its name/key before asking. On approval it rechecks the source/controller identities and live contact table, then uses MeshCore's existing <code>import_contact</code> API. Signature validation remains with the controller's normal advert importer. For manual-add controllers it can approve only that exact source through <code>add_pending</code>; it does not enable general auto-add. A fresh <code>reload_contacts</code> must confirm the full source key before OTA continues. No LoRa advertisement or firmware update is required for this import.</p> <p>The default answer is No; <code>--yes</code> does not approve adding a contact. A noninteractive run stops with instructions to rerun in a terminal. Unsupported <code>card</code> firmware, malformed/mismatched cards, and unverified imports stop with manual-import/discovery guidance. To protect existing contacts, the controller's overwrite-oldest policy must be verifiably disabled; otherwise the runner stops and shows how to disable that bit without changing other auto-add flags. It does not change this policy itself. A full table or rejected import cannot be worked around by deleting another contact; an uncertain import is not automatically retried. An approved contact remains on the controller for subsequent runs.</p> <p>The normal/TempRadio on-air ACK checks still run; adding a contact does not prove radio reachability or skip those checks. When the controller and source are the same TCP Full Companion, use the verified <code>--source-shares-controller</code> topology; it does not need a contact for itself.</p>"},{"location":"lora_ota_automation/#destination-requirements","title":"Destination requirements","text":"Destination Package installed One-time prerequisite Raw ZIP handling ESP32 Full application image OTA-enabled image with an A/B partition table Builds a full mOTA from the matching non-merged application <code>.bin</code> nRF52, internal flash In-place delta Exact-board OTAFIX bootloader with mOTA apply support Requires <code>--base</code> with the exact image currently running nRF52 repeater, external QSPI Full image or in-place delta QSPI-aware exact-board OTAFIX bootloader and matched repeater build Builds a full mOTA; adding <code>--base</code> requests a delta MeshTower V2 nRF52, microSD Full image or in-place delta SD-aware exact-board OTAFIX bootloader and compatible card Builds a full mOTA; adding <code>--base</code> requests a delta <p>MeshTower V2 microSD application and bootloader containers require an Ed25519 signature from a key in the device allowlist. Supply <code>--sign-key</code> when the runner must build a container, and install the BLM2-capable SD-aware bootloader locally before attempting application or bootloader OTA. Preview.12 requires USB/BLE DFU or SWD; see MeshTower V2 microSD LoRa OTA.</p> <p>The firmware inside a raw ZIP must have a valid MeshCore <code>EndF</code> trailer. An ESP32 merged/factory image is not an application image and is rejected. A generic vendor DFU ZIP may also be unusable if it does not contain the raw EndF-bearing <code>.hex</code> or <code>.bin</code>.</p> <p>For an internal-staging nRF52, the exact base image is irreducible information. The node reports its eight-byte body hash, but that hash cannot reconstruct the firmware bytes needed to create a delta. Keep the <code>.pio/build/ENV/firmware.hex</code> that was actually flashed. A matching filename or version alone is not enough.</p>"},{"location":"lora_ota_automation/#1-install-the-host-tools","title":"1. Install the host tools","text":"<p>Install Python 3.10 or newer, Rust, Git, the official <code>meshcore-cli</code> 1.6.0 or newer, and the official <code>motatool</code>.</p> <p>For signed bootloader staging, see the automatic <code>cryptography</code> and bootloader-capable <code>motatool</code> repairs above. Pip is needed only when installing the missing Python dependency; Rust/Cargo and a native linker are needed only when building motatool, not when using an already compatible binary. The runner checks the selected meshcli version before opening radios. Keep its serial/BLE dependencies in meshcli's own environment (pipx handles these); installing cryptography in meshcli's pipx environment does not make it available to the separate Python interpreter running this wrapper. A ready bootloader <code>.mota</code> does not need the Python <code>detools</code> or <code>intelhex</code> build dependencies.</p> <p>On Bash:</p> <pre><code>python3 -m pip install --user pipx\npython3 -m pipx ensurepath\npipx install meshcore-cli\n\ngit clone https://github.com/vk496/motatool.git\ncargo install --path ./motatool\n\nmeshcli -v\nmotatool --version\n</code></pre> <p>On PowerShell:</p> <pre><code>py -m pip install --user pipx\npy -m pipx ensurepath\npipx install meshcore-cli\n\ngit clone https://github.com/vk496/motatool.git\ncargo install --path .\\motatool\n\nmeshcli -v\nmotatool --version\n</code></pre> <p>Restart the shell if <code>pipx</code> or Cargo reports that it changed <code>PATH</code>.</p>"},{"location":"lora_ota_automation/#2-identify-and-test-both-local-links","title":"2. Identify and test both local links","text":"<p>List serial devices:</p> <pre><code>meshcli -l\n</code></pre> <p>The examples below assume <code>/dev/ttyACM0</code> is the controller and <code>/dev/ttyACM1</code> is the OTA source. On Windows they might be <code>COM7</code> and <code>COM8</code>. Close picocom, a serial monitor, the phone app, and any other program holding either link.</p> <p>Test the controller's binary API:</p> <pre><code>meshcli -s /dev/ttyACM0 -b 115200 ver\n</code></pre> <p>For an ordinary raw-text source, test its OTA support:</p> <pre><code>meshcli -r -s /dev/ttyACM1 -b 115200 \"ota status\"\n</code></pre> <p>The command must print an <code>OTA | ... target:XXXXXXXX</code> status.</p> <p>For an nRF52 full Companion, open the source port with terminal mode selected automatically:</p> <pre><code>picocom -b 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM1\n</code></pre> <p>Run <code>ota status</code>. It must report <code>OTA seeder</code>, <code>install:disabled</code>, and target <code>00000000</code>; send <code>+++MESHCORE-TERM-STOP</code> before closing the terminal. The automation detects and performs this token-wrapped preflight itself, so no extra command-line option is needed.</p> <p>For an ESP32 full Companion, test its separate WiFi control console instead:</p> <pre><code>./tools/lora_ota/lora_ota.sh --tcp-cli 192.168.1.50 \"ota status\"\n</code></pre> <p>It must report <code>OTA seeder</code>, <code>install:disabled</code>, and target <code>00000000</code>.</p> <p>This standalone fallback uses Python's raw TCP socket directly. It works with <code>meshcli</code> versions whose <code>-r</code> mode rejects <code>-t</code>; it does not need <code>meshcli</code>, <code>motatool</code>, <code>nc</code>, or a firmware package. It defaults to text port 5002; port 5000 speaks the binary Companion protocol and port 5001 serves mOTA data. The firmware must expose the text console; this option does not enable one.</p> <p>Specify a port or adjust the total connection/command timeout (10 seconds by default):</p> <pre><code>./tools/lora_ota/lora_ota.sh --tcp-cli 192.168.1.50:5002 --timeout 15 \"ver\"\n</code></pre> <p>PowerShell uses the same option:</p> <pre><code>.\\tools\\lora_ota\\lora_ota.ps1 --tcp-cli 192.168.1.50 \"ota status\"\n</code></pre> <p>Place <code>--tcp-cli</code> first. Each invocation sends one command and waits for the complete reply and terminal prompt. Connection failures, timeouts, missing replies, and rejected commands exit nonzero. If USB owns the terminal, close the active USB terminal and try again. Commands are never automatically resent in this standalone mode: a timeout after sending may mean the command executed but its reply was lost. Inspect the device state before repeating a change.</p> <p>For an actual OTA run, continue using <code>--source-tcp HOST:5001</code> with <code>--source-cli-tcp HOST:5002</code>; that existing control path also bypasses <code>meshcli</code> raw mode. The standalone fallback does not transfer a firmware image itself.</p> <p>Changing a terminal to 57600 baud does not select ASCII mode. USB Companion builds and the normal raw management CLI use 115200 unless a particular build was explicitly configured otherwise.</p>"},{"location":"lora_ota_automation/#3-check-the-destination-once","title":"3. Check the destination once","text":"<p>The destination must be in the controller's contacts and remotely reachable on the normal channel. The script runs these authenticated checks itself:</p> <pre><code>ota status\nget bootloader.ver\nota self\nota stats\n</code></pre> <p>The script uses <code>get bootloader.ver</code> as an optional platform/version hint, not as an install gate. It makes one attempt without an interactive retry loop. <code>unknown</code>, an unsupported/missing command, an unrecognized reply, or a lost reply produces a warning and does not by itself block the run. In particular, older MeshCore firmware can report <code>unknown</code> for the installed signed OTAFIX 2.4.6 MeshTower V2 SD image because it omits the legacy UF2 version string. Both the shell and PowerShell launchers use this same behavior; no application or Companion firmware update is required for this host-side workaround. The runner also accepts the new <code>OTAFIX2.4.6</code> and explicitly labelled <code>0.11.0 (base)</code> formats.</p> <p>The runner still requires <code>ota self</code> to report <code>bootloader: apply OK</code>, <code>bootloader: QSPI apply OK</code>, or <code>bootloader: SD apply OK</code> and checks the reported bootloader ABI and codec mask against the selected package. If the version command is unavailable on older firmware, the script warns and falls back to the legacy <code>ota self</code> platform marker. If an nRF52 bootloader lacks the required capabilities, install the exact-board OTAFIX bootloader first. Positive nRF52 capability markers take precedence over a generic unsupported getter response, so it cannot silently skip nRF52 safety checks. Bootloader packages still require the independently checked <code>ota bootloader status</code> board, target, ABI, codec and storage identity; missing version text never bypasses package signature checks or the explicit bootloader-install workflow. The separate hardware-qualified <code>rak3401_mota_chain.py</code> retains its exact deployed version restriction; it is not a general OTAFIX 2.4.6 update runner. Current firmware also reports <code>maxblk:2048</code> near the front of both OTA replies. The runner treats a missing marker as the deployed 1 KiB receive limit, rejects a ready 2 KiB package for such a target before transfer, and passes the live limit to <code>motatool --block-size</code> when it builds from raw firmware. Thus updating an older target from a release ZIP produces a compatible 1 KiB package while a current target retains the 2 KiB application default. <code>ota stats</code> is only an optional EndF version probe. It uses one bounded retry cycle; unsupported firmware or a lost reply falls back directly to the required <code>ver</code> command instead of entering an operator continuation loop.</p> <p>The default TempRadio tuple is:</p> <pre><code>909.950,250,5,5,120\n</code></pre> <p>The test default is 250 kHz bandwidth, SF5, and CR5. The frequency is only a North American example: choose a legal frequency supported by every participating radio and appropriate to your location. Older radios that do not support SF5 require a complete replacement tuple passed with <code>--temp-radio</code>.</p> <p>Before that long window is allowed, the live runner performs a mandatory independent three-minute rehearsal. Its exact normal-channel <code>ota status</code> and <code>ota self</code> identity proof gets one shared four-minute, read-only budget before any schedule, radio override, seeder, or transfer is armed; this tolerates a marginal link without consuming or extending a live lease. It advances a stale managed controller with exact readback and treats a source terminal's whole-minute display as an uncertainty window, never as an exact epoch. A source minute overlapping the host is preserved; a completely stale minute is pinned to a guarded future value and read back once. Neither clock is moved backward, and the runner stops if a managed clock cannot be proven within the ten-minute limit. Each remote participant must expose an empty <code>tempradioat</code> schedule. The runner projects one fixed start/end interval into each participant's independently sampled RTC, sends each mutation once, proves every exact identity on the temporary tuple, waits for natural expiry, and proves the complete normal path again. A lost schedule reply is resolved by those on-air proofs; it is never blindly replayed with a fresh duration.</p> <p>The published RAK3401 <code>v1.16.7-c1caa5ad</code> LoRa-OTA image includes <code>get/set/del tempradioat</code> and can take this safe first step. A truly older or reduced build without fixed TempRadio scheduling is rejected before mutation; bootstrap it locally or with another explicitly controlled maintenance path. The automation does not substitute an immediate <code>tempradio</code> command whose first delivery could remain queued after cleanup.</p>"},{"location":"lora_ota_automation/#rxps-handling-during-tempradio","title":"RXPS handling during TempRadio","text":"<p>RXPS improves receive performance per unit of radio-on time, so the runner keeps the destination's saved RXPS preference enabled whenever the selected fast tuple has a qualified timing window. Before changing any radio, it reads <code>ver</code> from the destination, controller, source, and every named relay. It treats v1.17.1.5 as the first forward contract in which every SF5-SF8 transmission, including a retry, uses the same tuple-selected physical preamble: normally 32 symbols, 64 only when 32 cannot enable RXPS, and 128 only when neither 32 nor 64 can. A saved RXPS level is also safely retuned after a radio change. An older or unparseable destination version fails closed: the runner temporarily sends <code>set radio.rxps off</code> instead of assuming an ad-hoc build contains the timing fixes. Automation deliberately treats the version as a wire-format contract.</p> <p>For the default SF5/BW250 tuple, the runner keeps destination RXPS on only when the destination and every possible sender are v1.17.1.5 or newer. It does not overwrite an existing level-based preference. Current firmware retunes that preference against the tuple-selected 64-symbol wire preamble; the qualified boundary is effective level 8, preamble 64 (<code>1252 / 6424 us</code>). A manually configured node may save <code>set radio.rxps level 8 preamble 32</code> before entering TempRadio: when 32 symbols cannot cover the TCXO transition, firmware safely selects the real 64-symbol preamble. If the saved setting uses fixed manual timings, or even one participant is older or unknown, RXPS is temporarily off. This avoids the receive gap that a 32-symbol sender or an unretuned manual window would create.</p> <p>The complete qualified SX1262+TCXO policy is:</p> TempRadio SF/BW Saved reference setting Qualified boundary Automation SF7/BW500 <code>level 7 preamble 32</code> 7 / 32 RXPS on for a current destination SF6/BW250 <code>level 7 preamble 32</code> 7 / 32 RXPS on for a current destination SF5/BW125 <code>level 7 preamble 32</code> 7 / 32 RXPS on for a current destination SF5/BW250 <code>level 8 preamble 32</code> 8 / 64 RXPS on only when every participant follows the 64-symbol contract SF6/BW500 <code>level 8 preamble 32</code> 8 / 64 RXPS on only when every participant follows the adaptive-preamble contract SF5/BW500 <code>level 8 preamble 32</code> 8 / 128 RXPS on only when every participant follows the adaptive-preamble contract SF5/BW62.5 <code>level 10 preamble 16</code> 10 / 16 RXPS on for a current destination Unqualified tuple none continuous RX RXPS temporarily off <p>If RXPS was already off, the runner leaves it off. Otherwise it writes the original level, preamble assumption, receive/sleep periods, and temporary decision to protected <code>target-rxps-settings.json</code> in the run's working directory, verifies the temporary state, and restores the exact original setting after the target is back on its normal radio. Current firmware exposes this complete state through <code>get radio.rxps.config</code>; a legacy reply has only on/off and periods, so the runner can restore those periods but cannot reconstruct an unreported saved level. A radio change later recalculates from a preserved saved minimum, so moving back to a slower tuple returns to the operator's saved level.</p> <p>The OTA source has a stricter policy than the destination. For every source with a managed serial or TCP CLI, the runner reads and retains its exact RXPS preference, using the legacy fixed-period query only when the detailed query is unavailable. It builds and verifies the package, completes the read-only target checks, and obtains confirmation while that preference remains unchanged. Immediately before the first radio mutation, it reads the source RXPS state again, disables RXPS, and verifies the readback. Source RXPS stays off through catalog serving, download, installation, and post-install identity verification. Cleanup first proves that the source has returned to its normal radio, then restores and verifies the exact saved level/preamble or fixed-period state once. A source whose RXPS state cannot be read, disabled, or restored safely fails closed. If current firmware explicitly rejects an RXPS disable or restore with <code>radio busy; retry</code>, the runner retries that idempotent mutation at staggered 210\u2013378 ms intervals. All 32 delays are distinct and contribute about 9.4 seconds of waits; source-CLI command round-trip time is additional. This avoids repeatedly sampling one radio phase while retaining a strict attempt cap. Other rejections are not replayed.</p>"},{"location":"lora_ota_automation/#4-run-an-esp32-update","title":"4. Run an ESP32 update","text":"<p>The ZIP can contain a compatible ready <code>.mota</code> or the exact board-and-role non-merged application <code>.bin</code>:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='target-admin-password'\n\n./tools/lora_ota/lora_ota.sh ./release.zip \"Roof ESP32\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <p>The script shows the detected target, hardware, running hash, chosen package, version, manifest ID, and action before asking for confirmation. For an unattended job, add <code>--yes</code>:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Roof ESP32\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1 \\\n  --yes\n</code></pre> <p>PowerShell equivalents:</p> <pre><code>$env:MESHCORE_ADMIN_PASSWORD = 'target-admin-password'\n\n&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.zip' 'Roof ESP32' `\n  --controller-serial COM7 `\n  --source-serial COM8\n\n&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.mota' 'Roof ESP32' `\n  --controller-serial COM7 `\n  --source-serial COM8 `\n  --yes\n</code></pre> <p>Prefer the environment variable or the interactive password prompt. Passing <code>--password</code> works, but the wrapper's own command line may be visible to other local processes. The runner keeps the password out of child <code>meshcli</code> command lines and removes its protected temporary command file after each call.</p>"},{"location":"lora_ota_automation/#5-run-an-nrf52-update","title":"5. Run an nRF52 update","text":"<p>If the input ZIP already contains a compatible in-place delta <code>.mota</code>, no base argument is needed: its embedded base hash is compared with the live node. If the ZIP contains raw new firmware, supply the exact running image:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./nrf52-new-release.zip \"Hill nRF52\" \\\n  --base ./firmware-that-is-running.hex \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <pre><code>&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\nrf52-new-release.zip' 'Hill nRF52' `\n  --base '.\\firmware-that-is-running.hex' `\n  --controller-serial COM7 `\n  --source-serial COM8\n</code></pre> <p>Before building a delta, the runner proves that the base's target ID, hardware identity, firmware version when available, and <code>EndF</code> body hash match the live destination. It then asks <code>motatool</code> for codec 2, the nRF52 in-place format. The normal workspace is <code>0x98000</code>.</p> <p>For a QSPI-backed repeater or the SD-backed MeshTower V2 target, a raw ZIP becomes a full image without <code>--base</code>. Supplying an exact base requests a smaller in-place delta and automatically selects the conservative external workspace <code>0xC6000</code>, which is safe for S140 v6 and v7 application layouts. An explicit <code>--inplace-memory</code> overrides the automatic value.</p> <p>The live runner detects QSPI from <code>ota self</code> (<code>QSPI apply OK</code>) or <code>ota status</code> (<code>bl:QSPI</code>) and refuses an explicit <code>QSPI store:ERR 0K</code> report even when the bootloader itself advertises QSPI apply support. Offline <code>--prepare-only</code> runs must supply <code>--nrf-qspi</code>; do not use that switch for a board that only exposes QSPI pins or uses the chip as a Companion filesystem. The application and bootloader must both be from the matched repeater list in the nRF52 QSPI guide.</p>"},{"location":"lora_ota_automation/#6-add-intermediate-relays","title":"6. Add intermediate relays","text":"<p>List relays from farthest to nearest so each command is sent before its route moves to TempRadio. A bare relay name uses the destination password; use <code>NAME=PASSWORD</code> when it differs:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1 \\\n  --relay \"Far Relay=far-password\" \\\n  --relay \"Near Relay=near-password\"\n</code></pre> <p>PowerShell uses the same arguments:</p> <pre><code>&amp; .\\tools\\lora_ota\\lora_ota.ps1 '.\\release.mota' 'Remote Target' `\n  --controller-serial COM7 `\n  --source-serial COM8 `\n  --relay 'Far Relay=far-password' `\n  --relay 'Near Relay=near-password'\n</code></pre>"},{"location":"lora_ota_automation/#other-connection-choices","title":"Other connection choices","text":"<p>The controller can use any one of:</p> <pre><code>--controller-serial PORT\n--controller-tcp HOST[:PORT]       # default port 5000\n--controller-ble ADDRESS_OR_NAME\n</code></pre> <p>An ESP32 FULL/repeater source can serve over its dedicated WiFi seeder port while its raw USB CLI is used to start TempRadio:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.50:5001 \\\n  --source-cli-serial /dev/ttyACM1\n</code></pre> <p>An ESP32 <code>companion_radio_full</code> uses WiFi for both dedicated source links:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.50:5001 \\\n  --source-cli-tcp 192.168.1.50:5002\n</code></pre> <p>Port 5002 defaults automatically when it is omitted from <code>--source-cli-tcp</code>. Current Full Companion firmware exposes its complete role-specific text terminal there; the runner uses only <code>ota</code>, <code>tempradio</code>, and <code>normalradio</code>, and remains compatible with older bounded port-5002 consoles. The source-only Companion never stages or installs the image itself; it streams the host folder to other nodes over LoRa. See the full Companion guide for manual operation and interface details.</p> <p>An nRF52 <code>companion_radio_full</code> uses one USB source port sequentially. The runner automatically wraps local control commands in the terminal tokens, and unmodified <code>motatool</code> switches that port into mOTA mode when seeding starts:</p> <p>The wrapper sends STOP, then START, before each command. This makes fallback independent of whether a prior raw probe left an unobservable USB-UART connection in ASCII or Binary mode. Seeder startup is reported only after the verbose device log contains its <code>COUNT</code> acknowledgement; an immediate device <code>ERR</code> or a missing acknowledgement fails during startup instead of surfacing later as a catalog timeout.</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.mota \"Remote Target\" \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-serial /dev/ttyACM1\n</code></pre> <p>If the source is already on the exact TempRadio tuple through a scheduled or manual operation, <code>--source-already-temp</code> lets a TCP source run without a raw CLI link. The script cannot verify, extend, or shorten that source window, so leave a comfortable time margin. It also cannot inspect or change that unmanaged source's RXPS state; disable source RXPS yourself before starting the run and restore it only after returning the source to its normal radio.</p> <p>Use <code>--controller-baud</code> or <code>--source-baud</code> only for a build whose corresponding interface is genuinely configured to another speed.</p>"},{"location":"lora_ota_automation/#package-selection-and-safety-gates","title":"Package selection and safety gates","text":"<p>For a ZIP, the runner first examines every <code>.mota</code> without extracting paths. It keeps only packages matching the live target, hardware, base, platform, codec, and bootloader capabilities. It chooses the newest compatible version and prefers a delta over a full image at the same version. If equally suitable files differ, select one explicitly:</p> <pre><code>--zip-member path/inside/archive/update.mota\n</code></pre> <p>If no ready mOTA is usable, it searches <code>.bin</code> and <code>.hex</code> members for a valid, matching <code>EndF</code>, then builds the platform-appropriate container. Every result is structurally checked by the runner and independently passed through <code>motatool verify</code> before any radio changes. Direct firmware and mOTA inputs, as well as individual ZIP members, are rejected above 64 MiB before being loaded.</p> <p>Useful controls:</p> <ul> <li><code>--public-key signer.key.pub</code> requires a particular Ed25519 signer during   verification.</li> <li><code>--sign-key signer.key</code> signs a newly built container.</li> <li><code>--no-install</code> downloads and verifies the image but leaves it staged. By   default the runner then schedules the target, relays, and a script-configured   source back to their normal radios. Combining it with   <code>--leave-controller-radio</code> deliberately preserves the destination, relays,   and separate controller on the TempRadio topology; a managed source is still   returned to normal so its exact RXPS setting can be restored.   If the version gate required RXPS off, it stays off while that topology is   preserved; use <code>target-rxps-settings.json</code> to restore it only after sending   <code>normalradio</code>.</li> <li><code>--allow-non-upgrade</code> deliberately permits the same or an older application version.</li> <li><code>--replace-active-download</code> deliberately discards a different update already   downloading or staged on the target. Without it, that update is preserved.</li> <li><code>--source-shares-controller</code> is for a Full Companion whose USB Binary API is   the controller while its TCP port <code>5001</code> is the source. It verifies that the   source's port-<code>5000</code> public key equals the controller key, then binds the   fresh port-<code>5002</code> Full Terminal banner's complete public key to that Binary   identity and challenges it with the supported <code>ver</code> command. It does not   assume the Full Terminal implements repeater-only <code>get public.key</code>. Port   <code>5002</code> uses a bounded local <code>tempradio</code> override to move the shared physical   radio without overwriting its saved normal tuple; the Binary API remains the   authenticated transport. Cleanup sends local <code>normalradio</code>, proves that   override inactive, and then reasserts the saved Binary tuple. It cannot be   combined with   <code>--leave-controller-radio</code>,   because exact source RXPS restoration requires that shared physical radio to   be back on its verified normal tuple.</li> <li><code>--require-system-watchdog-off</code> checks <code>get system.watchdog</code> immediately   before every <code>ota install</code> transmission and refuses installation unless the   destination reports <code>&gt; off</code>. Use it for nRF52 chains whose bootloader cannot   service an application watchdog inherited across reset.</li> <li>Managed <code>--relay</code> nodes have their original <code>rxdelay</code> and <code>txdelay</code> captured   in the work directory. During transfer the runner verifies <code>rxdelay 0</code> and   an airtime-scaled <code>txdelay 0.3</code> (override with <code>--relay-txdelay</code>), then   restores both values before the relay leaves TempRadio.</li> <li><code>--work-dir PATH</code> chooses a new, non-existent work directory.</li> <li><code>--meshcli PATH</code> and <code>--motatool PATH</code> select binaries not on <code>PATH</code>.</li> <li><code>--package-build-timeout SECONDS</code> bounds local mOTA generation. It defaults   to 3600 seconds. Run detools, delta/compression, and raw-firmware package   generation on a workstation or build VM, then transfer the completed,   hash-verified <code>.mota</code> to a Pi-class radio host. The Pi should perform only   lightweight identity-gated hardware I/O and serve that finished artifact;   preparation still occurs before any radio state changes.</li> <li><code>--debug</code> prints redacted child commands, timeouts, process status, stdout,   and stderr. Admin passwords are never printed, but node names, addresses,   paths, and command replies can still be sensitive; share the log carefully.</li> </ul> <p>For offline package preparation only:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.zip offline \\\n  --prepare-only \\\n  --platform nrf52 \\\n  --target-id 1234ABCD \\\n  --target-base-hash 0011223344556677 \\\n  --target-hw Heltec_T114 \\\n  --base ./firmware-that-is-running.hex\n</code></pre> <p>Live operation is safer because the script obtains these values directly from the destination.</p>"},{"location":"lora_ota_automation/#what-happens-during-a-run","title":"What happens during a run","text":"<ol> <li>Validate the input paths and host tools, then prove the source is either an    OTA-enabled raw CLI or a source-only full Companion control interface. Read    and durably save a managed source's exact RXPS preference without changing    it.</li> <li>Before sending any remote packet, prove the managed source has no active,    pending, or fixed TempRadio work, then gate the source and controller    clocks. Advance a stale exact clock to host time; for a minute-resolution    source, preserve an overlapping minute or use one guarded forward value    with readback. Preserve a small future lead and fail closed above the    ten-minute drift limit. Then    authenticate to the target, query its target ID, hardware, running body    hash, firmware version, bootloader version, and nRF52 bootloader    capabilities, and save the controller's normal radio tuple.</li> <li>Select or build one compatible v2 application mOTA and verify all block    hashes, Merkle root, full-image hash where applicable, identity fields,    signature, codec, base, and the live firmware's reported maximum block size    (1 KiB for legacy replies without <code>maxblk</code>, currently 2 KiB otherwise).    Version-3 bootloader packages are refused before any target state changes.</li> <li>Read every participant's version, save the destination's RXPS state,    select the qualified destination policy, and show the confirmation prompt.</li> <li>Run the fixed-window three-minute rehearsal described above. This phase    does not disable RXPS, start a seeder, request a pull, or install anything;    the long transfer remains completely unarmed until temporary and normal    reachability both pass.</li> <li>Fresh-read, disable, and verify source RXPS; apply and verify the    destination RXPS policy; then start TempRadio on the    target, far-to-near relays, and source. A separate controller is moved and    read back through Binary; a shared Full Companion instead schedules its    bounded local override while Binary remains the transport. The runner    rejects a TempRadio window that cannot cover setup, seeder startup,    discovery, the transfer timeout, final polling, and install checks.</li> <li>Start <code>motatool serve</code>, discover the exact eight-hex manifest ID, request    <code>ota pull &lt;id&gt; flash</code>, and poll until that same ID reports ready. A seeder    process exit stops the run immediately. For <code>--no-install</code>, schedule all    script-controlled nodes back to their normal radios before restoring the    controller, unless <code>--leave-controller-radio</code> was requested.</li> <li>Recheck that exact ID, give the target a short final TempRadio safety window,    and request <code>ota install</code>. Then shorten each relay's TempRadio window so the    normal multi-hop route returns, stop the seeder, shorten the source window,    restore the controller, and probe <code>ota self</code> every 10 seconds through the    configured readiness window (five minutes by default). The exact new body    hash is the readiness signal;    only then does the runner require the exact package version. A relayed run    continues the 10-second probes through the mandatory relay-return window. A    source supplied with <code>--source-already-temp</code> is never modified.    <code>--leave-controller-radio</code> moves the controller back to TempRadio only after    this normal-channel verification. Restore the destination's exact original    RXPS setting after normal-channel identity is proven. A managed source stays    RXPS-off through that verification and its exact setting is restored only    after its own TempRadio state is proven inactive.</li> </ol> <p>Remote replies are matched only after queued messages have been drained and only when they come from the intended contact and fit the command. A ready status for another manifest ID is an error, never permission to install it.</p>"},{"location":"lora_ota_automation/#transmission-loss-and-retries","title":"Transmission loss and retries","text":"<p>Read-only and replay-safe transmissions retry up to three times. Three retries or 90 seconds, whichever comes first, opens a 10-second stop-or-continue prompt when stdin is an interactive terminal. Continue remains the default on timeout or Enter, so an operator can persist through a temporary outage; enter <code>s</code> or <code>stop</code> to end the run, and Ctrl-C remains immediate. With non-interactive stdin, the runner stops after that finite automatic retry cycle instead of silently starting another cycle forever. Optional participant-version probes always use a bounded cycle and degrade to <code>unknown</code>; optional destination <code>ota stats</code> falls back directly to <code>ver</code>. The mandatory normal-channel destination baseline is the narrow exception: it may make nine total read-only attempts but is stopped by one hard four-minute deadline before any TempRadio lease or OTA mutation exists. Proofs inside the live rehearsal retain the smaller four-attempt limit.</p> <p>Commands that change OTA state are reconciled before replay:</p> <ul> <li>After a lost <code>ota pull</code> reply, <code>ota status</code> must show the requested manifest   ID before the runner treats the pull as started. Otherwise the safe retry   policy applies.</li> <li>A lost <code>ota install</code> reply is not blindly resent. After a short wait, it is   sent again only if the target replies that the same manifest is still ready.   If the target has stopped replying because it may be rebooting, the runner   restores the normal path and lets post-reboot identity resolve the outcome.   The target's final three-minute safety window also returns a non-rebooting   target to the normal channel promptly.</li> </ul> <p>Retries and operator-selected continuation can outlast the original TempRadio budget. If a bounded window expires, rerun the same package after the nodes return to their normal channel; the manifest-ID check resumes its partial download without replacing it.</p> <p>The working directory is created before a managed source can be changed, then retained and printed at exit. It contains the exact served mOTA, <code>motatool-serve.log</code>, extracted build inputs when needed, and <code>controller-radio.txt</code>. A managed source also gets a protected <code>source-rxps-settings.json</code> containing its exact original preference and idempotent restore command. Its contents and directory entry are flushed before RXPS is disabled. When the destination started with RXPS enabled, protected <code>target-rxps-settings.json</code> records its manual recovery state. The RAK3401 chain points every nested step at one chain-root source record, so a rerun after host power loss does not adopt the temporary RXPS-off state as the original. A retained record is accepted only for the same managed CLI endpoint. These files contain no saved admin password. After exact source restoration, a standalone run atomically retires its record; the chain retains its shared record between steps and retires it only after the verified endpoint restoration completes.</p>"},{"location":"lora_ota_automation/#interruption-and-recovery","title":"Interruption and recovery","text":"<p>Ctrl-C stops the seeder, detaches its serial folder, makes a bounded attempt to shorten a source TempRadio window started by the script, and attempts to restore the controller. For a managed source it leaves RXPS off until the source is proven back on its normal radio, then restores and verifies the saved source preference. A transient success-path restore failure remains armed for one more idempotent cleanup attempt. The target and relays remain on TempRadio only until their bounded windows end; rebooting also restores their saved radio settings. A normal cleanup restores the destination's exact RXPS periods. If that remote restore cannot be confirmed, use <code>target-rxps-settings.json</code> after the target returns to its normal channel. A partial download remains safe. Once the target is reachable again (after its TempRadio window ends, or after putting the controller back on that tuple), rerunning the same package recognizes its manifest ID and resumes the existing session instead of clearing it.</p> <p>When a chained run has already proved the newly running body hash, its retained previous package can briefly report <code>verifying staged blocks</code> after TempRadio reactivates the OTA manager. The runner waits only through the configured discovery timeout, keeps checking source liveness, and accepts only the same manifest becoming <code>ready to install</code> or the manager becoming idle. A changed ID, failed or incomplete state, or timeout stops the chain. It then proves the exact installed body again. If that same session is still attached and ready, the runner detaches it with <code>ota cancel</code>; if the manager has become idle, it sends no cancel. An ordinary-channel <code>no download</code> status proves only that the manager is idle, not that persistent staging was erased. The runner therefore does not issue or describe an IDLE cancel as durable cleanup. The next chain transition explicitly re-adopts and proves the expected previous MID before detaching it; after the final install OTAFIX has consumed the approval word, so any retained container is inert and is replaced by the next valid pull.</p> <p>A hard process kill or host power loss cannot run cleanup. Recover a serial controller using the tuple saved in the printed work directory:</p> <pre><code>radio=$(tr -d '\\r\\n' &lt; ./meshcore-lora-ota-20260807-123456-1234/controller-radio.txt)\nmeshcli -s /dev/ttyACM0 set radio \"$radio\"\n</code></pre> <pre><code>$radio = (Get-Content '.\\meshcore-lora-ota-...\\controller-radio.txt' -Raw).Trim()\nmeshcli -s COM7 set radio $radio\n</code></pre> <p>For a managed source, first return it to its ordinary radio, then inspect <code>source-rxps-settings.json</code> and issue its exact <code>restore_command</code> through the same serial or TCP-console endpoint recorded in that file. The command is idempotent; confirm the full setting with <code>get radio.rxps.config</code> before resuming an update.</p> <p>If you stop during final confirmation, reconnect on the node's normal channel and run <code>ota self</code> and <code>ver</code>. A completed run returns success only when <code>ota self</code> reports a valid new body hash and <code>ver</code> exactly matches the package; an unverified install returns status 2. Do not immediately replace a staged image: the default active-download guard preserves it until you explicitly use <code>--replace-active-download</code> or run <code>ota cancel</code>.</p> <p>Exit status is <code>0</code> for success, <code>2</code> for a validation or operational error, and <code>130</code> for Ctrl-C.</p>"},{"location":"management_decoder/","title":"Management report decoder","text":"<p>Paste MGR1 management-report payloads or complete GroupData packets from a packet analyzer to read a radio's public management information. Everything, including password authentication and ACL decryption, happens locally in this browser. The report, password, and candidate public key are never uploaded.</p> <p>The public portion of a report is deliberately plaintext, but it is not authenticated until a management password is supplied. A password-authenticated page proves that its public fields and encrypted ACL bytes have not been altered by someone who does not know that password.</p>"},{"location":"management_decoder/#decode-a-management-report","title":"Decode a management reportEncrypted ACL entries","text":"MGR1 payload or complete GroupData packet hex <p>     Spaces, line breaks, colons, dashes, <code>0x</code>, and MQTT JSON fields named     <code>raw</code> or <code>data</code> are accepted. Paste all pages from one report     together to view a complete multi-page ACL. Press Ctrl/Command+Enter to decode.   </p> Management password (optional for public fields; required for ACLs) <p>     The password remains in this page only. The decoder derives the MGR1 AES-SIV key in     your browser and does not send it anywhere.   </p> Candidate administrator public key (optional) <p>     ACL encryption reveals per-radio 12-byte fingerprints, not recoverable public keys.     Supplying a complete candidate key checks whether its fingerprint appears in this report.   </p> Decode management report Clear local data Load authenticated example Decode notes"},{"location":"management_decoder/#what-the-decoder-accepts","title":"What the decoder accepts","text":"<ul> <li>Complete <code>PAYLOAD_TYPE_GRP_DATA</code> (<code>0x06</code>) analyzer/MQTT packet hex. It checks   the MeshCore route header, encoded path length, MGR1 page bounds, and required   zero padding.</li> <li>A canonical MGR1 payload beginning with <code>4D475231</code> (<code>MGR1</code>).</li> <li>One raw packet or canonical payload per line; duplicate observations of an   identical page are deduplicated.</li> </ul> <p>Use the same password configured by <code>set mgmt.password</code>. A decoded ACL lists the report-specific fingerprints and the administrator and/or OTA-signer flags. It cannot turn a fingerprint back into a full key. Use the optional candidate field to test a specific full public key.</p> <p>For the report schedule, public-field layout, cryptographic design, and the offline Python capture tool, see Management reports.</p>"},{"location":"management_reports/","title":"Management reports (MGR1)","text":"<p>Available on repeater (including observer), room-server and sensor firmware. Companions/terminal-chat nodes and KISS modems do not originate these reports. Off by default. A management password and explicit enable are both required. No radio settings, existing preferences layout, or OTA authorization policy is changed by enabling reporting. This protocol does not authorize updates.</p>"},{"location":"management_reports/#cli","title":"CLI","text":"<p>Run through the existing local CLI or an authenticated administrator session:</p> <pre><code>get data.tx\nset data.tx path 1:12ab77\nset data.tx region auto\nset mgmt.password &lt;12-to-96-byte password&gt;\nset mgmt.direct 5\nset mgmt.flood 21\nset mgmt.enabled on\nget mgmt\nset mgmt.enabled off\n</code></pre> <p>Use a long randomly generated password. There is no password getter. Firmware stores the derived 32-byte key, not the plaintext password. That stored key is equivalent authority to decrypt reports and must also be protected. Passwords entered into terminal programs may still be recorded by those programs.</p> <p><code>data.tx</code> is the single shared route for management reports, telemetry history, and future scheduled data producers. Its fresh-install defaults are <code>path=direct</code> (zero hops) and <code>region=auto</code>; configuring it never enables a producer. Paths use <code>1:</code>, <code>2:</code> or <code>3:</code> followed by complete hop hashes without separators, or the comma-separated form accepted by <code>set outpath</code>. <code>none</code> removes the path. <code>get/set mgmt.path</code> remain compatibility aliases for <code>get/set data.tx path</code>.</p> <p><code>region=auto</code> uses the radio's configured default region when it is usable; otherwise it resolves the unique deepest flood-enabled entry in the region hierarchy. If equally deep candidates make that choice ambiguous, it resolves to nothing and no fallback is transmitted. <code>default</code> requires and follows <code>region default</code>; a region name pins that named scope. <code>none</code> disables scoped fallback. The resolved transport key is looked up when a report starts, so edits to the region definition take effect without rewriting <code>/data_tx</code>.</p> <p>The direct path leads to the receiver/uplink's vicinity; this broadcast-radio datagram has no private destination identity. The radio ID in the payload identifies the reporter.</p> <p>Direct and flood schedules are independently configurable and may each be turned off. Fresh settings are <code>direct=5d</code> and <code>flood=21d</code>; global reporting is still off until <code>mgmt.enabled on</code>. Direct accepts 5\u201390 days and requires the shared path. Flood accepts 21\u201390 days and requires a resolvable shared region. At least one route must remain active while reporting is enabled. The legacy <code>set mgmt.interval N</code> shorthand enables both, setting direct to <code>N</code> and flood to <code>max(21,N)</code>. No transmission is sent merely by configuring a password. Initial reporting waits for the configured schedules. Reports have deterministic per-radio/per-sequence jitter of up to an hour; pages are spaced at least a minute apart.</p> <p>The radio cannot know that an observer uploaded a packet to MQTT, so the flood schedule is deliberately independent of direct transmission. A region-scoped <code>TRANSPORT_FLOOD</code> is sent at its independently configured interval. An unresolved or ambiguous data region blocks that transmission rather than sending an unscoped flood. If direct and flood become due together, the flood is sent and replaces the redundant direct copy. Ordinary reports are never retried in a tight loop; a partial report gives up after an hour. Existing relay filters, hop limits and duty constraints still apply.</p> <p>Schedule state is atomically reserved before transmission, and checkpointed hourly. Timers use elapsed powered-on time rather than the RTC: clock corrections cannot create floods, and reboot does not clear the budget. Downtime is not credited; each reboot can delay a report by up to an additional hour. This is a deliberately conservative tradeoff for nodes with unreliable clocks. Off/on and password changes do not reset the flood limit. Corrupt/unreadable state or failed writes stop reporting; <code>get mgmt</code> shows <code>FAULT(no TX)</code> until storage is repaired and the radio restarted. <code>/management</code> and the shared <code>/data_tx</code> are versioned, CRC-protected, and replaced transactionally.</p> <p>Weekly history is collected once a minute while enabled. Hour-bucket extrema cover 7 days to 7 days + 1 hour (conservative boundary bucket). The first report after enable/reboot is marked partial where appropriate. Since-report extrema reset after all pages have been queued, retaining readings taken since the snapshot for the next report. These statistics are not durable; reboot loses the history, not the flood countdown. Temperature is MCU temperature, not ambient. Reporting does not wake GPS, start Wi-Fi, or initialize external OTA media. Unknown capabilities/readiness are explicitly distinguishable from false. History/snapshot working memory is allocated only when reporting is enabled and is bounded to 1.5 KiB, plus a small configuration object and temporary stack use.</p>"},{"location":"management_reports/#routing-and-mqtt","title":"Routing and MQTT","text":"<p>Both direct/path and flood reports use <code>PAYLOAD_TYPE_GRP_DATA</code> (<code>0x06</code>). The route bits independently select direct or flood. <code>MGR1</code> is an application extension with literally plaintext public fields, not a call to the ordinary encrypted <code>createGroupDatagram()</code> builder. A fixed public marker is not an owner or password-derived channel ID. There is no outer channel encryption.</p> <p>The body is padded with zeroes to a group-compatible length <code>3 + 16*n</code> (maximum 179 bytes). Existing repeaters in the checked upstream implementation route group data without requiring a successful channel decryption. This fork recognizes the management envelope before ordinary channel processing. Reception of a management packet never exempts it from forwarding policy. Some third-party firmware may apply additional channel/layout policies; interoperability with every fork is not guaranteed. Packet logging/uplinks can capture it without the password.</p> <p><code>RAW_CUSTOM</code> (<code>0x0F</code>) is not used for reports because stock upstream does not flood-route it.</p> <p>The observer's existing MQTT <code>PACKET</code> JSON supplies the complete frame in <code>raw</code>. No broker configuration or password changes are necessary to capture a report. The decoder understands all four route forms, 1\u20133-byte hashes, scope transport codes, and duplicate copies heard by several uplinks:</p> <pre><code>python -m pip install -r tools/management/requirements.txt\npython tools/management/report.py --mqtt capture.jsonl\n</code></pre> <p>The password is prompted, not supplied as a process argument. Input may be JSONL or a JSON array of MQTT messages. Alternatively omit <code>--mqtt</code> for a JSON array of canonical payload hex strings. <code>--match-admin FULL_PUBLIC_KEY</code> in canonical payload mode matches a known administrator against the encrypted fingerprints. This is an offline capture decoder, not a broker subscriber or downlink service.</p> <p>For a browser-local decoder that also decrypts and authenticates ACL entries, use the Management report decoder. It does not upload the captured packet or password.</p>"},{"location":"management_reports/#canonical-payload-little-endian","title":"Canonical payload (little endian)","text":"Offset Bytes Field 0 4 <code>MGR1</code> 4 16 First 16 bytes of reporter public key 20 4 Persisted report sequence (never wraps; exhaustion stops TX) 24 4 RTC Unix timestamp; advisory, may be wrong 28 4 Firmware major/minor/patch/pre packed as mOTA version 32 4 Bootloader packed version, or unknown 36 4 EndF target ID 40 8 Complete mOTA delta-base body hash 48 4 EndF image length 52 4 Staging capacity; planning still checks actual package geometry 56 4 OTA capability bits 60 2 Uptime hours, saturated at 65535 62 4 Weekly minimum mV, minimum \u00b0C, maximum \u00b0C 66 4 Since-report extrema in the same format 70 1 History coverage hours, capped at 168 71 1 Interval days for this report's direct or flood schedule 72 1 Role: 1 repeater, 2 room server, 3 sensor 73 1 Compiled/detected capability bits 74 1 Active status bits 75 1 Mask of status bits whose state is known 76 2 Validity/partial-history flags 78 1 Zero-based page index 79 1 Total pages (1\u20136) 80 1 Unique ACL count (0\u201336) 81 1 First ACL index in this page 82 1 ACL entries on this page (0\u20136) 83 13 \u00d7 count AES-SIV encrypted ACL entries after ACL 16 Full AES-SIV authentication tag after tag 0\u201315 Zero padding to group-compatible length; not part of canonical payload <p>Each private entry is a per-radio 12-byte keyed fingerprint followed by flags: bit 0 administrator, bit 1 trusted OTA signer. Duplicate entries combine flags. An oversized ACL fails closed rather than silently truncating. The reported allowlist includes all current full administrators and all four possible trusted OTA signing keys; region/filter managers and ordinary clients are excluded.</p> <p>Feature bits: 0 Wi-Fi, 1 GPS, 2 NTP, 3 USB data, 4 LoRa OTA. Wi-Fi active means connected, GPS means receiver enabled (not necessarily a fix), NTP means an actual accepted NTP response this boot, USB means observable native USB data connection (not power or an unobservable external UART bridge). OTA capability means compiled support; active means an established usable apply/store path.</p> <p>Validity bits: 0 firmware version, 1 bootloader version, 2 EndF/base identity, 3 staging capacity, 4 partial week, 5 partial since-report period, 6 MCU temperature. Voltage is unsigned millivolts, zero missing. Temperatures: zero missing, 1\u2013251 represent \u221250\u2026200 \u00b0C, 252 below range, 253 above range, 254\u2013255 reserved. OTA bits: 0 protocol compiled, 1 transfer DEFLATE, 2 2-KiB app transfer blocks; bits 8\u201323 are apply codec bits (full/sequential/in-place). Transfer DEFLATE is not compressed bootloader apply. There is no manifest ID. Exact old binaries are still needed on the computer to generate a differential update; a hash alone cannot reconstruct them. Unknown metadata must not be treated as OTA readiness.</p>"},{"location":"management_reports/#cryptography","title":"Cryptography","text":"<p>Password root: <code>SHA256(\"#\" || literal UTF-8 password)</code> (hashtag-style derivation). Subkeys: <code>HMAC-SHA256(root, ASCII_domain || radio_id16)</code>. Domains: <code>MeshCore-MGR1-SIV</code>, <code>MeshCore-MGR1-ACL</code>. Fingerprint: <code>HMAC-SHA256(ACL_subkey, radio_id16 || full_admin_key32)[0:12]</code>. The same owner has different fingerprints on different radios. A collector needs a candidate administrator's full key to identify a fingerprint.</p> <p>Encryption is RFC 5297 AES-SIV-CMAC-256, using the existing rweather AES primitive. The single associated-data string is the complete 83-byte clear header. Ciphertext is exactly the ACL byte length. Full 16-byte tag, no truncation. This deterministic misuse-resistant mode avoids reliance on the firmware's noncryptographic general-purpose RNG or RTC nonces. An identical restored snapshot may repeat ciphertext, but does not expose XORs of different ACL plaintexts as nonce-reused stream encryption would.</p> <p>All public fields are readable without a password but are authenticated only to password holders. A shared password authenticates knowledge of that password, not a unique individual radio identity; another holder can forge reports. There is no per-device signature. Collectors must enforce their own persisted sequence/replay policy and explicitly handle factory resets/restored backups. The decoder verifies snapshot consistency but does not maintain a database. This fast password derivation permits offline guessing, so twelve characters is only a minimum length, not a guarantee of password strength. Packet timing, public metadata and entry/page counts remain visible.</p>"},{"location":"mbedtls-tls-footprint/","title":"Shrinking the per-connection TLS footprint on non-PSRAM observers","text":""},{"location":"mbedtls-tls-footprint/#why","title":"Why","text":"<p>On a non-PSRAM Heltec V3 running two WSS/JWT broker slots, the largest allocatable block in internal DRAM walks down in ~16 KiB steps at every TLS reconnect while total free heap stays flat. Measured on hardware over 50 reconnect cycles: 62,452 -&gt; 16,372 bytes, permanently.</p> <p>The step size is not a coincidence. <code>framework-arduinoespressif32 3.20017</code> (Arduino 2.0.17, IDF 4.4) builds mbedTLS with the symmetric buffer configuration:</p> <pre><code>CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN 16384      # sizes BOTH the in and out record buffers\nCONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE 1\n# CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN       -- not defined\n# CONFIG_MBEDTLS_DYNAMIC_BUFFER               -- not defined\n# CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH   -- not defined\n</code></pre> <p>Read from <code>packages/framework-arduinoespressif32/tools/sdk/esp32s3/qio_qspi/include/sdkconfig.h</code>. Note the separate <code>framework-arduinoespressif32-libs</code> package in <code>~/.platformio</code> belongs to the esp32c6 env (pioarduino, IDF 5.3) and is not what this env links against -- though it happens to carry identical mbedTLS values.</p> <p>So each broker slot costs 2 x 16 KiB = 32 KiB of contiguous internal DRAM in record buffers alone, and two slots cost 64 KiB on a board with roughly 80 KiB free. Every reconnect frees and re-allocates those buffers, and anything that lands in the vacated hole in between prevents them from going back, which is the ratchet.</p> <p>Confirmed by two independent observations: losing a whole TLS session returned exactly 16,384 bytes of contiguity on one device and exactly 32,768 on another, and per-connection teardown frees ~41.6-44.7 KB total.</p>"},{"location":"mbedtls-tls-footprint/#what-the-firmware-could-already-do-and-its-limit","title":"What the firmware could already do, and its limit","text":"<p><code>softDisconnect()</code> (branch <code>perf/mqtt-renewal-no-stop</code>, commit <code>6c51e468</code>) stops the JWT renewal bounce from destroying and recreating the esp-mqtt task, keeping its 6 KiB stack out of the hole. Measured: the staircase arrests after 2 steps at 36,852 through cycle 16, where the baseline took 4 steps and settled at 16,372 by cycle 11 -- about 20 KB better.</p> <p>That is as far as the application layer reaches. MQTT 3.1.1 has no re-authentication packet, so presenting a fresh JWT requires a transport reconnect; mbedTLS's internal allocation order during the handshake is not controllable from the application. The remaining cost is the record buffers themselves.</p>"},{"location":"mbedtls-tls-footprint/#the-changes","title":"The changes","text":"<p>All three are compile-time in mbedTLS, and the Arduino framework ships precompiled <code>.a</code> archives (<code>tools/sdk/esp32s3/lib/libmbedtls.a</code>), so a project-level <code>-D</code> cannot change them. A custom framework build is required.</p> Setting From To Saving per connection <code>CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN</code> unset <code>y</code> enables the two below <code>CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN</code> 16384 (implied) 16384 none -- keep it <code>CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN</code> 16384 (implied) 4096 ~12 KiB <code>CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE</code> <code>1</code> <code>n</code> ~4 KiB <p>Roughly 16 KiB per connection, 32 KiB across two slots.</p>"},{"location":"mbedtls-tls-footprint/#why-inbound-stays-at-16-kib","title":"Why inbound stays at 16 KiB","text":"<p>A peer may legitimately send a 16 KiB TLS record. Lowering the inbound limit only works if both brokers negotiate the max-fragment-length extension or provably never send larger, and getting it wrong produces invalid-record and handshake failures rather than a clean error. Outbound is ours to choose: this firmware's MQTT and WebSocket frames are far below 4 KiB (<code>MAX_TRANS_UNIT</code>-bounded packets plus small JSON), so 4 KiB is comfortable.</p>"},{"location":"mbedtls-tls-footprint/#risk-on-the-peer-certificate","title":"Risk on the peer certificate","text":"<p>Dropping <code>KEEP_PEER_CERTIFICATE</code> means <code>mbedtls_ssl_get_peer_cert()</code> returns NULL after the handshake. Chain validation still happens -- only retention of the parsed leaf changes. This firmware verifies against a CA (<code>GTS_ROOT_R4</code> / the bundle) and never inspects the peer certificate or a fingerprint, so it should be safe. It does change <code>mbedtls_ssl_session</code> layout, which is exactly why the whole framework must be rebuilt together rather than swapping a single archive in.</p>"},{"location":"mbedtls-tls-footprint/#build-procedure","title":"Build procedure","text":""},{"location":"mbedtls-tls-footprint/#do-not-use-esp32-arduino-lib-builder-for-this","title":"Do not use esp32-arduino-lib-builder for this","text":"<p><code>release/v4.4</code> is the branch matching Arduino 2.0.x, but its <code>update-components.sh</code> clones every dependency at master, so it no longer resolves. Five successive failures, each a different repo: the arduino branch name it passes to <code>-A</code> does not exist; <code>jq</code> is absent from the IDF image and its absence makes <code>build.sh</code>'s target loop a silent no-op that still exits 0; <code>esp_littlefs</code> and <code>esp32-camera</code> master require IDF &gt;=5.0/&gt;=5.1; <code>esp32-camera</code> later needs an <code>esp_jpeg</code> version the 4.4 registry cannot satisfy; and tinyusb's source layout no longer matches <code>arduino_tinyusb/CMakeLists.txt</code>. Pinning each one in turn just surfaces the next.</p>"},{"location":"mbedtls-tls-footprint/#rebuild-only-the-mbedtls-archives","title":"Rebuild only the mbedTLS archives","text":"<p>More rigorous anyway, because it reuses the shipped <code>sdkconfig</code> verbatim -- so the archives differ from stock only by the intended change, with no arduino-version or <code>DYNAMIC_BUFFER</code> drift.</p> <p>This is ABI-safe for the content-length change specifically: <code>ssl.h</code> declares <code>in_buf</code> and <code>out_buf</code> as <code>unsigned char *</code>, allocated in <code>ssl_setup()</code>, and no public struct embeds a CONTENT_LEN-sized array. The other precompiled archives (esp-tls, esp_http_client, esp-mqtt) therefore remain compatible. It is not safe for <code>CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE</code>, which changes <code>mbedtls_ssl_session</code> layout -- that one needs everything rebuilt together, so it is excluded here.</p> <ol> <li>Minimal IDF project whose only component requirement is <code>mbedtls</code>.</li> <li><code>sdkconfig.defaults</code> = the shipped    <code>packages/framework-arduinoespressif32/tools/sdk/esp32s3/sdkconfig</code>, with    <code>CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN=16384</code> replaced by the three asymmetric lines.    Verify the diff is exactly 5 lines before building.</li> <li><code>docker run --rm -v $PWD:/project -w /project espressif/idf:v4.4.7 idf.py -DIDF_TARGET=esp32s3 build</code></li> <li>Confirm <code>build/config/sdkconfig.h</code> carries <code>OUT_CONTENT_LEN 4096</code>.</li> <li>Stage the four archives under the framework's names -- note the rename:</li> </ol> built framework name stock size rebuilt <code>esp-idf/mbedtls/libmbedtls.a</code> <code>libmbedtls.a</code> 113,914 113,338 <code>esp-idf/mbedtls/mbedtls/library/libmbedtls.a</code> <code>libmbedtls_2.a</code> 1,252,150 1,245,718 <code>.../libmbedcrypto.a</code> <code>libmbedcrypto.a</code> 4,302,698 4,259,458 <code>.../libmbedx509.a</code> <code>libmbedx509.a</code> 676,590 673,318 <p>All within ~1% of stock, which is a good check that only the config differs.</p>"},{"location":"mbedtls-tls-footprint/#wire-it-in-with-l-never-platform_packages","title":"Wire it in with -L, never platform_packages","text":"<pre><code>PLATFORMIO_BUILD_FLAGS=\"-L/path/to/staged/archives\" pio run -e Heltec_v3_repeater_observer_mqtt\n</code></pre> <p>Verify with <code>grep -oE \"[^ ]*libmbed[a-z0-9_]*\\.a\" .pio/build/&lt;env&gt;/firmware.map | sort -u</code> -- every path must be the staged directory.</p> <p>Do not point <code>platform_packages</code> at a <code>file://</code> copy of the framework. PlatformIO installs it over the shared <code>~/.platformio/packages/framework-arduinoespressif32</code>, silently changing mbedTLS for every other ESP32 env and project on the machine. It does this even when the copy's <code>package.json</code> version differs -- verified twice here, and both times the fix was <code>rm -rf</code> the package and <code>pio pkg install</code> to re-download stock. A prepended library search path keeps the change scoped to one env, because the linker takes each archive member from the first archive that satisfies an undefined symbol.</p>"},{"location":"mbedtls-tls-footprint/#how-to-verify-it-worked","title":"How to verify it worked","text":"<ol> <li><code>strings</code>/<code>grep</code> the new <code>sdkconfig.h</code> for the four settings.</li> <li>Build and check the RAM figure; static usage should be unchanged (these are heap buffers).</li> <li>On hardware, <code>get mqtt.stats</code> at boot with two slots connected: the largest free block    should start roughly 24-32 KiB higher than the current 62-67 KiB.</li> <li>Soak across reconnect cycles and compare the floor against the two recorded runs:    baseline settled 16,372 (cycle 11); <code>softDisconnect</code> holds 36,852 (cycle 16).</li> </ol>"},{"location":"mbedtls-tls-footprint/#prior-art-in-this-investigation","title":"Prior art in this investigation","text":"<p><code>.scratch/mqtt-non-psram-heap-staircase-analysis-2026-08-05.md</code> (untracked -- <code>.scratch/</code> is globally gitignored) holds the full allocation inventory. <code>~/mqtt-soak/STATE.md</code> holds the soak evidence, including two retracted hypotheses worth not repeating: the perf commits were not the cause, and waev does not cap connections per IP.</p>"},{"location":"mixed_scan_validation/","title":"Mixed-bandwidth two-channel reception test","text":"<p>V4 transmitter on MercerWoodMesh; XIAO ESP32-S3/Wio SX1262 receiver. Channel 0: 909.5 MHz, SF7/62.5 kHz, preamble 32. Channel 1: 910.5 MHz, 500 kHz, SF and preamble below. Both use CR4/5, explicit header, CRC and 64-byte test payloads. Fast RX-preamble scanning uses four symbols of the active profile per visit, not four simultaneous channels or hardware CAD.</p> <p>Each setting starts with a five-packet-per-channel continuous-RX baseline. Scanning sends 50 packets per channel in shuffled order with random host delays. Only CRC-valid, payload-validated, sequence-matched packets count. Any scan loss escalates the 500 kHz preamble by 16, capped at 128. SF9 and SF8 start at 32; SF7 starts at 48. An additional SF8/40 test was requested after SF8/48; its firmware adds acceptance of preamble 40 without changing radio timing or scanning behavior.</p> 500 kHz SF Preamble Mode SF7/62.5 received 500 kHz received Mean scan cycle SF9 32 Fixed baseline 5/5 5/5 \u2014 SF9 32 Scan 50/50 50/50 14.676 ms SF8 32 Fixed baseline 5/5 5/5 \u2014 SF8 32 Scan 50/50 49/50 12.628 ms SF8 48 Fixed baseline 5/5 5/5 \u2014 SF8 48 Scan 50/50 50/50 12.629 ms SF8 40 Fixed baseline 5/5 5/5 \u2014 SF8 40 Scan 50/50 49/50 12.630 ms SF7 48 Fixed baseline 5/5 5/5 \u2014 SF7 48 Scan 50/50 50/50 11.603 ms <p>These are strong-signal, sequential-transmission lab results. Successful reception of 50 packets is not proof of zero loss over months. The receiver remains on one channel through an entire detected packet, so overlapping traffic on the other channel can be lost. Scan-cycle measurements exclude time occupied by packet reception; USB command handling can add timing outliers.</p> <p>Machine-readable counts, timings and firmware/source hashes: mixed_scan_results.json.</p> <p>After testing, both boards were restored to their original B soak firmware using app-only flashes. Version and normal radio settings were verified on both boards; Wi-Fi was connected and MQTT reported <code>custom (ok)</code>. Both persistent soak loggers were restarted in phase <code>B-post-CAD-soak</code>, marking the intentional uptime reset.</p>"},{"location":"mixed_sf_bw_validation/","title":"Equal-symbol-time mixed SF/BW, four-channel test","text":"<p>2026-09-14. Promising, but no strict 400/400 pass. With no added settling, the mixed scanner received 61 consecutive packets on the correct channels, then timed out on packet 62. The near-ceiling +22.4 ms setting received four packets and timed out on the fifth. There were no wrong-channel payloads in either run. Both stopped on the first miss without retries.</p>"},{"location":"mixed_sf_bw_validation/#configuration","title":"Configuration","text":"Channel Center (MHz) SF BW (kHz) Symbol time (ms) 0 909.5 9 62.5 8.192 1 910.5 10 125 8.192 2 911.5 11 250 8.192 3 912.5 12 500 8.192 <p>These preserve the preceding SF10/125 symbol duration exactly, rather than approximately: <code>symbol_us = 2^SF * 1000 / BW_kHz</code>. The supported SF/BW values and symbol-rate equation are specified in Semtech's SX1261/2 datasheet, sections 6.1.1.1\u20132. Equal symbol durations do not imply equal payload airtime or sensitivity.</p> <ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, MAC 28:84:85:B4:09:80.</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, serial B35E71C1C3726CE7.</li> <li>Normal RX gain 0x94, -9 dBm TX chip request, CR4/5, 32-symbol preamble,   16-byte CHS1 packets, 1 MHz channel spacing. No extra IRQ tracing/polling.</li> <li>5.1-symbol visits = 41,780 us; programmed preamble = 262,144 us.</li> <li>Double frequency write retained, warm XOSC, bulk SPI and fast RX restart.   SF/BW changes on every hop, so one 0x8B command is required on every hop.</li> <li>Goal per setting: 100 packets/channel, 400 total, strict channel identity.   No relaxed off-channel acceptance and no automatic channel-count expansion.</li> </ul> <p>The lab scanner stages four channels through the existing two production profile slots; this does not change the public two-profile protocol.</p>"},{"location":"mixed_sf_bw_validation/#positive-controls","title":"Positive controls","text":"<p>Before scanning, each profile received ten fixed-frequency probes after full normal initialization. All four passed 10/10, forty total. Zero frequency commands occurred after each setup; no stationary receiver hardware failure. These are fresh ten-packet controls, not claims of 100/100 on each new profile.</p> <p>Both devices acknowledge the same exact modulation table through <code>mixinfo</code>. Transmitter results verify SF, fractional BW, center, sequence and packet size. RX records verify center-command word and SF/BW at packet read. Full expected payload identity and CRC remain required. Mode/cache errors are treated as fixture failures rather than ordinary RF misses.</p>"},{"location":"mixed_sf_bw_validation/#timing-controls-and-settling-budget","title":"Timing controls and settling budget","text":"<p>Six-second RX-only window at zero added delay: 141 hops, mean 637.922 us, maximum 828 us. The largest 100 us delay step with a 500 us per-hop reserve is <code>floor((262144/4 - 41780 - 828 - 500)/100)*100 = 22400 us</code>.</p> <p>The +22,400 us RX-only verification window measured 87 hops, mean 638.241 us, maximum 833 us. Nineteen complete idle cycles measured mean 259,292.789 us, maximum 259,310 us, below the 262,144 us preamble. Every hop had two observed frequency commands and one modulation command, with no mode/cache/RX errors.</p> <p>This is an empirical near-ceiling budget, not a guarantee of acquisition for every arrival phase. Longer packet holds and software jitter can defeat the idle-cycle calculation. RX is active throughout added settling.</p>"},{"location":"mixed_sf_bw_validation/#four-channel-results","title":"Four-channel results","text":"Added settling Strict received / attempted before first miss Failed TX profile Mean switch (us) Max switch (us) Max idle cycle (us) 22,400 us 4 / 5 Channel 2, SF11/250 660.951 892 259391 0 us 61 / 62 Channel 0, SF9/62.5 674.819 899 169798 <p>Both failures were timeouts, with TX rc=0, RX mode=1, device errors=0. Both runs had zero mode/cache/receive errors and zero off-channel payloads. The +22.4 ms run exercised 163 hops, 326 frequency commands and 163 modulation commands. Zero-delay exercised 718 hops, 1,436 frequency commands and 718 modulation commands. Optimized RX resume counts equaled hop counts.</p> <p>No-delay per-channel counts at stop:</p> Channel Received Attempted Good-packet mean RSSI (dBm) Good-packet mean SNR (dB) 0 15 16 -34.00 11.15 1 16 16 -33.69 8.24 2 15 15 -34.33 5.78 3 15 15 -33.27 3.47 <p>The receiver stayed longer on some visits: maximum held visit 582,993 us with settling, 580,577 us without. Held-visit statistics include successful packet reception, so these maxima alone do not prove false off-channel preamble holds in this experiment. No IRQ trace was collected for the two failures; their precise mechanism is not established.</p> <p>The longer success sequence and absence of wrong-channel payloads are encouraging relative to the earlier uniform-SF/BW tests, but do not establish a statistically measured improvement or zero-loss reliability. Each setting was censored at first failure; do not present 61/62 as an unbiased measured packet-delivery rate or either run as a completed 400-packet test. The random arrival method is seeded, not RF-phase synchronized across configurations.</p>"},{"location":"mixed_sf_bw_validation/#implementation-verification-and-final-state","title":"Implementation, verification and final state","text":"<p>HIL-only <code>ProfileMixedChannels.h</code>, <code>basemixed</code>, <code>mixtx</code>, <code>scanmixed</code> and <code>profile_switch_mixed.py</code> add the bounded experiment. Uniform modes preserve their defaults. Post-hop checks use the actual per-channel modulation; the uniform collector and settling evidence checks reject mixed-mode results. Receive ownership, packet guards, BUSY and command-error handling remain intact.</p> <p>17 native profile tests and 48 HIL host tests passed. Tests cover fractional 62.5 kHz, equal symbol duration, table identity, normal uniform mapping, required modulation writes, TX replay, and wrong-policy rejection. Both firmware builds and normal uploads succeeded. The nRF52 ZIP is application- only, SoftDevice ID 0x0123; no bootloader or SoftDevice replacement. RAK COM29 was not opened. Production settings/source were not changed this turn.</p> <p>Both boards rebooted idle after the second failed setting, with test firmware retained. No autonomous TX, background collectors or restoration. Temporary PlatformIO overlay removed. No commit or push was requested. Existing unrelated working-tree changes remain intact. <code>git diff --check</code> passed apart from unrelated pre-existing CRLF warnings.</p>"},{"location":"mixed_sf_bw_validation/#provenance","title":"Provenance","text":"<p>Raw capture: <code>tools/hil/profile_switch_mixed_equal_symbols_results.json</code>. It includes the four baselines, two timing controls and two strict scans, with <code>complete:true</code>, <code>stopped:both_delay_controls_failed</code>, and no fixture or cleanup errors. Earlier captures were not rewritten.</p> <ul> <li>Raw SHA-256: <code>49de5c6415b1becdca02bc6e3c72d5e55127e92e758bbe3ac6c342c89e3723dd</code></li> <li>RX BIN SHA-256: <code>20d3008ef3d92610510748f64ac90c327f37c91d96cd3ac55272a918867fd5d0</code></li> <li>TX ZIP SHA-256: <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> <li>TX HEX SHA-256: <code>1225bcc70854a224f2862443d816b0e9216a253da87c42e96569a933204af941</code></li> </ul> <p>RX build reported 94,844 bytes RAM / 367,537 bytes flash. TX reported 18,220 / 95,908 bytes. Source is keymindCascade commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> plus existing uncommitted work and these HIL changes; this is not a clean-release comparison.</p>"},{"location":"nimble_companion_trial/","title":"ESP32-S3 NimBLE Full Companion trial","text":"<p>These optional builds use NimBLE-Arduino 2.5.1 with the existing ESP32 Arduino 2.0.17 toolchain. They are hardware qualification builds, outside the normal release matrix and firmware picker.</p> <p>See the 2026-09-08 hardware results for measured RAM, MAC-policy checks, WiFi updates, and remaining qualification.</p> <p>The contact-cache guide adds six optional 350-contact trials for ESP32 boards without PSRAM, including Heltec V3. Their qualification results include linked RAM margins, V4/RAK hardware tests and the mOTA queue policy.</p> Hardware Trial environment Contacts Channels Offline queue Heltec V4.2/V4.3 OLED, FEM on <code>heltec_v4_2_v4_3_companion_radio_full_femon_nimble</code> 350 40 512 XIAO ESP32-S3 with WIO SX1262 <code>Xiao_S3_WIO_companion_radio_full_nimble</code> 350 40 256 <p>The XIAO profile uses WIO radio pins CS 41, DIO1 39, BUSY 40 and RESET 42. It is not the generic XIAO profile for separately wired radio modules. Both boards retain their parent Full Companion features, USB mOTA sender, WiFi update slots, and PSRAM-backed offline queue. The V4 also retains direct MQTT.</p> <p>The small-screen message layout uses 6-pixel capitals on 128x64 panels and 5-pixel capitals on very tiny panels. It includes a compact channel/sender line and full message previews. Font selection is automatic.</p>"},{"location":"nimble_companion_trial/#build","title":"Build","text":"<p>Enable the optional configuration in the ignored <code>platformio.local.ini</code>:</p> <pre><code>[platformio]\nextra_configs =\n  variants/*/platformio.ini\n  platformio.nimble.ini\n</code></pre> <p>If that file already contains local settings, merge this list with them. Run one PlatformIO/build.sh command at a time. Both commands below use USA Cascade:</p> <pre><code>OUTPUT_DIR=.releases/nimble-v4 bash build.sh build-firmware \\\n  heltec_v4_2_v4_3_companion_radio_full_femon_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-nimble-test \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n\nOUTPUT_DIR=.releases/nimble-xiao bash build.sh build-firmware \\\n  Xiao_S3_WIO_companion_radio_full_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-nimble-test \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n</code></pre> <p>Use the merged image at address 0 for a USB installation. The V4 uses 16 MB flash; the XIAO uses 8 MB. Both use DIO flash mode. Use the application-only <code>.bin</code> for an existing, matching WiFi OTA layout. Remove the optional config entry when finished to return to the ordinary release matrix.</p>"},{"location":"nimble_companion_trial/#bluetooth-identity-and-pairing","title":"Bluetooth identity and pairing","text":"<p>All existing MAC settings remain available from the ASCII USB terminal and the app's authenticated local CLI. A setting takes effect after reboot.</p> Command Behavior <code>get bluetooth.mac</code> Show the saved MAC policy. <code>set bluetooth.mac C2:17:15:04:00:01</code> Use this custom random-static address. <code>set bluetooth.mac random</code> Generate one address and retain it across boots. <code>set bluetooth.mac random-every-boot</code> Generate a new address on each boot. <code>set bluetooth.mac random-after-connect</code> Rotate on the next boot after an authenticated connection; otherwise retain the address. <code>set bluetooth.mac default</code> Restore the factory Bluetooth address. <code>set bluetooth.stealth on</code> Pair once, then accept the saved bonded peer. <code>set bluetooth.stealth off</code> Restore ordinary discovery without changing the MAC policy. <code>get bluetooth.stealth</code> Show pairing or bonded-peer-only state. <p>The <code>ble.mac</code> and <code>ble.stealth</code> aliases also work. A literal custom address must be a valid BLE random-static address (first byte C0-FF). Forget the old entry in the phone's Bluetooth settings and pair again after an address change or switching Bluetooth libraries. Existing Bluedroid bonds are not migrated.</p> <p>Stealth does not disable the selected rotation policy. If rotation changes the address on reboot, first pairing opens again for the new identity.</p> <p>Pairing requires encryption, PIN authentication and a stored bond. NimBLE's controller byte order is converted explicitly, so a custom address appears over the air in the order entered. Failed identity setup stops advertising and retries initialization instead of advertising the wrong address.</p>"},{"location":"nimble_companion_trial/#v4-wifi-setup-qr","title":"V4 WiFi setup QR","text":"<p>The active WiFi setup page displays a compact QR code with a one-pixel white border. The normal open setup network fits a 44 x 44 pixel code, with 2 x 2 pixel modules. The SSID, portal address and <code>HOLD STOP</code> hint remain beside it. Short-click to leave the page; hold the button on this page to start or stop the setup AP. From USB, <code>start webconfig ap</code> starts the same setup session.</p> <p>When the setup AP is inactive and the node has joined WiFi, this page shows <code>WIFI CONNECTED</code>, <code>IP &lt;address&gt;</code>, <code>SETUP AP INACTIVE</code>, then <code>HOLD START AP</code> from top to bottom. The address appears once assigned and clears when the station disconnects. While the setup AP is active, the QR page shows the setup portal's address instead.</p>"},{"location":"nimble_companion_trial/#regression-checks","title":"Regression checks","text":"<pre><code>python3 -B test/test_nimble_companion.py\npython3 -B test/test_bluetooth_mac_contract.py\npython3 -B test/test_bluetooth_pairing_ui.py\npython3 -B test/test_heltec_v4_wifi_setup_page.py\npython3 -B test/test_firmware_ram.py\npython3 -B test/test_esp32_dram.py\npython3 -B test/test_shared_mota_queue.py\npython3 -B test/test_companion_mqtt_stack.py\npio test -e native -f test_companion_node_prefs \\\n  -f test_ble_tx_stall_watchdog -f test_companion_frame_queue \\\n  -f test_display_driver\n</code></pre> <p>The adapter test compiles the actual transport under address/undefined-behavior sanitizers with API doubles. It injects allocation, identity and bond failures; checks PIN authentication and stealth; and exercises 176-byte frames, MTU and notification subscription gating, retry and duplicate prevention. Embedded builds compile against the pinned real library. RAM reports retain the existing wireless budget; linked headroom is not a measurement of live free heap. The MQTT save callback also has a compiler-enforced stack-frame regression check: nested preference copies previously overflowed the V4 loop task when saving MQTT settings through WebConfig, despite sufficient free heap.</p> <p>Hardware qualification must additionally verify pairing and reconnection, advertised addresses for every MAC policy, contact synchronization, WiFi/BLE coexistence, and uptime under load. BlueZ results do not establish iOS or Android camera/pairing compatibility.</p>"},{"location":"nimble_companion_trial_results/","title":"ESP32-S3 NimBLE trial results, 2026-09-08","text":"<p>These are local hardware trial results for USA Cascade Full Companions on a Heltec V4.3 OLED and a Seeed XIAO ESP32-S3 with WIO SX1262. The V4.2 shares the profile but was not physically tested. Build and command instructions are in the trial guide.</p> <p>The final source revision is <code>9dbab431</code>, using NimBLE-Arduino 2.5.1 and the existing Arduino-ESP32 2.0.17 toolchain. These optional profiles are outside the ordinary release matrix. This trial does not change GitHub release assets or the firmware picker.</p>"},{"location":"nimble_companion_trial_results/#capacity","title":"Capacity","text":"Measurement Heltec V4 XIAO S3 WIO Contacts / channels 350 / 40 350 / 40 PSRAM-backed offline queue 512 256 Application image, bytes 1,774,600 1,510,536 OTA application slot, bytes 6,553,600 3,342,336 Linked internal capacity before runtime allocation, bytes 263,944 265,576 Required runtime RAM budget, bytes 173,056 148,480 Headroom beyond that budget, bytes 90,888 117,096 Live free heap with Bluetooth and 350 test contacts, bytes 142,644 147,444 Minimum free heap during that contact test, bytes 138,024 142,788 <p>The live contact-test readings are from revision <code>7f1bd8b1</code>. Revision <code>9dbab431</code> retains the same Bluetooth adapter, contact allocation and queue sizes, and fixes the MQTT save stack use described below. Linked capacity is not live free heap; the firmware memory reports label that distinction.</p> <p>A matching V4 build using Bluedroid had 248,840 bytes of linked internal capacity. NimBLE recovers 15,104 bytes at link time. The matching Bluedroid application was 2,169,848 bytes. There was no matching physical Bluedroid heap measurement, so these figures do not establish a live heap saving.</p>"},{"location":"nimble_companion_trial_results/#bluetooth-hardware-checks","title":"Bluetooth hardware checks","text":"<p>Both boards passed the following cases with BlueZ on the Mercerwood Pi:</p> <ul> <li>PIN authentication, encryption, stored bonding, and bonded reconnection.</li> <li>MTU 179; accepted 176-byte writes and complete 148-byte contact notifications.</li> <li>Insert and synchronize all 350 synthetic contacts without missing or   duplicate entries.</li> <li>Custom MAC address appears over the air in the entered byte order and   persists across reboots.</li> <li>Saved random MAC persists; random-every-boot changes on each boot.</li> <li>Random-after-connect retains its address through an unauthenticated boot   and rotates on the boot following an authenticated connection.</li> <li>Stealth first pairing, bonded-peer reconnection, and reconnection after   reboot with a stable identity.</li> <li>Restore factory MAC and ordinary discovery.</li> <li>Three reconnect samples with no observed downward free-heap trend.</li> </ul> <p>The complete MAC suite ran on <code>7f1bd8b1</code>. Final-image connection and update checks also verify the unchanged adapter after the MQTT stack fix. Synthetic contacts were removed after testing; factory MAC mode and stealth off were restored.</p>"},{"location":"nimble_companion_trial_results/#mqtt-save-stack-overflow","title":"MQTT save stack overflow","text":"<p>The V4 test reproduced an actual reset while saving MQTT settings through WebConfig. Serial output identified <code>Stack canary watchpoint triggered (loopTask)</code>. <code>onConfigBatchEnd()</code> kept a second 2.8 KB preference copy while the loader and NVS code also used stack space. Free heap was not the limiting resource.</p> <p>The loader already updates its destination only after validation, so the callback now passes the live preference object directly. The actual Xtensa callback frame shrank from 2,928 bytes to 32 bytes. The regression test compiles the real callback with a 512-byte frame ceiling and demonstrates that the previous nested-copy implementation fails the check.</p> <p>On the corrected <code>9dbab431</code> image, the 11-setting WebConfig batch completed with all entries accepted and no reboot. The V4 connected to a local Mosquitto broker, published MQTT traffic, and kept its authenticated Bluetooth session alive through a 30-second load interval with continuous uptime and zero reported error flags. Free heap measured 120,684 then 122,140 bytes; the minimum was 118,332 bytes and the largest free block was 110,580 bytes. Disabling the test MQTT slot also completed successfully without reboot.</p>"},{"location":"nimble_companion_trial_results/#wifi-updates-and-qr","title":"WiFi updates and QR","text":"<p>Both boards completed real application-image uploads over WiFi with Bluetooth connected, followed by reboot and reconnection using the saved bond. Repeated HTTP page requests and Bluetooth status requests ran together before upload. The image hash was checked before transmission, and the running firmware version was checked after reboot.</p> <p>The V4 WiFi setup page again contains a QR code. The default open setup SSID fits a 44 x 44 pixel code: 2 x 2 pixel modules and an exact one-pixel white border. The native test rendered the actual display/QRCode code and decoded the result with ZXing. SSID, portal address and the hold-to-stop hint fit beside it. Physical phone-camera scanning has not been verified.</p>"},{"location":"nimble_companion_trial_results/#observed-limits","title":"Observed limits","text":"<p>One XIAO warm reboot left its USB endpoint unresponsive while Bluetooth still answered. The user's physical unplug/replug restored USB; the later full MAC suite completed its commanded reboots successfully. The cause of that one USB failure is unconfirmed.</p> <p>The XIAO initially failed to associate with the saved WiFi network. Reapplying the SSID scheduled a fresh connection, after which it joined at -53 dBm and completed WiFi OTA. No antenna change was needed for that recovery.</p> <p>This was functional hardware testing, not a long-duration soak. iOS/Android app pairing, phone camera scanning, multiple TLS MQTT brokers, and an end-to-end LoRa mOTA transfer were not qualified in this trial. The XIAO parent profile does not include direct MQTT; the V4 does.</p>"},{"location":"nimble_companion_trial_results/#final-application-hashes","title":"Final application hashes","text":"Hardware SHA-256 V4 <code>e6a1522ced4ed38ddd00e7cdf8393857224adbb622888a86370c0f7a3ee28d88</code> XIAO S3 WIO <code>ecf7afe6222e3897556a04e022515f9dcfcb825172dae9eaaa72eb92396dd004</code>"},{"location":"nrf52-usb-ready-fix/","title":"nRF52 USB READY hang","text":"<p>The RAK3401 on Mercer was found stuck in the framework's TinyUSB power handler: USBD was enabled and attached, but its write-one-to-clear READY event was already consumed. The duplicate-event guard also required HFCLK to be running. If that guard missed the completed initialization, the following unbounded READY wait could stop application startup. A bootloader update alone cannot replace this USB driver in an already installed MeshCore application.</p> <p>The wait and guard were inherited through the pinned Adafruit nRF52 Arduino framework, not introduced by the recent OTAFIX upstream merge. TinyUSB's wait dates back at least to 2019; the guard was added in upstream commit 7d9efd0697. OTAFIX's August 24 HFCLK backport addressed a later clock wait, leaving this earlier READY wait uncovered. The exact live interrupt ordering is not known; the stalled program counter and consumed event were read directly over SWD.</p> <p>All nRF52 environments inherit <code>pre:scripts/nrf52_usb_power_fix.py</code>. It compiles a build-local replacement for the matching framework driver, without changing PlatformIO's shared SDK or affecting ESP32 builds. A changed/unrecognized framework implementation stops the build for review. The backport:</p> <ul> <li>requests HFCLK before checking the consumed READY event;</li> <li>rechecks attachment while waiting, including completion by another callback;</li> <li>bounds both waits with one 100,000-poll budget, independent of OS ticks;</li> <li>ignores stale READY on a disabled peripheral and exits if it is removed.</li> </ul> <p>The poll budget is an iteration limit, not a promised elapsed-time timeout. If the clock/peripheral never becomes ready, the caller returns instead of freezing the application. A later power event can retry; permanent electrical failure can still require reconnecting USB. This does not establish or fix the separate Pi hub/controller fault.</p> <p>Run <code>python3 -B test/test_nrf52_usb_power.py -v</code>. The tests compile the actual patched handler from the pinned-framework fixture, model W1C event semantics, and cover duplicate/nested callbacks, delayed/missing clocks and READY, removal, retry, and detached USB. Restoring the inherited READY prefix must reproduce the infinite wait under a subprocess deadline. Additional tests check SDK isolation, idempotence, fail-closed patching, and all nRF52 environment hooks. The harness is shared with OTAFIX's TinyUSB fork at <code>test/otafix/nrf5x_power_test.py</code>; keep the two copies in sync when extending it.</p>"},{"location":"nrf52_companion_storage_recovery/","title":"nRF52 Companion automatic ExtraFS recovery","text":"<p>Companion builds using internal ExtraFS reserve 100 KiB at <code>0xD4000..0xED000</code>. Identity and preferences remain in the separate 28 KiB primary store at <code>0xED000..0xF4000</code>. This applies to internal-ExtraFS Companion builds, including Full, not repeaters or external QSPI storage.</p> <p>At startup the firmware:</p> <ol> <li>Mounts primary storage without erasing nonblank media. Only proven-blank    primary storage may be initialized automatically.</li> <li>Checks the exact ExtraFS address, size, block geometry, and application    linker reservation, then attempts a non-formatting secondary mount.</li> <li>Validates primary filesystem metadata before any destructive secondary    recovery. An unavailable primary store blocks recovery and identity replacement.</li> <li>Keeps an already mounted, metadata-valid ExtraFS unchanged. If its initial    mount or validation failed, unmounts and retries once without formatting.</li> <li>If the retry remains unusable, automatically formats only the reserved    100 KiB region, then remounts and validates it. There is one format attempt    per boot; failure keeps the contact/channel write quarantine active.</li> <li>Runs the existing verified migration from primary into ExtraFS. Primary    contact/channel sources are retired only after every destination is copied,    read back, and the migration transaction is committed. Identity and    preferences stay on primary.</li> </ol> <p>No terminal repair command, phone intervention, or bootloader update is needed for this recovery path when a compatible application/layout is already used. After successful recovery, the Companion storage API reports 100 KiB total rather than the 28 KiB primary fallback.</p>"},{"location":"nrf52_companion_storage_recovery/#data-loss-boundary","title":"Data-loss boundary","text":"<p>Automatic rebuilding prioritizes a usable contact/channel store over retaining an unreadable secondary filesystem. Data stored only in that damaged region can be lost. Surviving primary files are migrated, but may not contain the latest secondary-only changes. An API backup remains advisable before flashing. Primary storage is never formatted by this recovery path.</p> <p>This is mount/metadata recovery, not forensic file recovery. An invalid migration journal, unreadable individual contact page, primary-source error, full filesystem, or failed migration cleanup does not on its own trigger a format of a mountable, metadata-valid secondary store. Those cases retain the existing validation, retry, and incomplete-load protections.</p>"},{"location":"nrf52_companion_storage_recovery/#regression-coverage","title":"Regression coverage","text":"<p><code>test/test_internal_secondary_fs_repair</code> exercises healthy/no-format startup, successful remount, failed remount/traversal followed by one repair, and format/remount/validation failure. <code>test/test_nrf52_extrafs_contract.py</code> checks primary-first ordering, internal-only geometry guards, quarantine handling, and the separation between migration failures and destructive recovery.</p>"},{"location":"nrf52_companion_storage_recovery/#t1000-e-hardware-qualification-2026-09-03","title":"T1000-E hardware qualification (2026-09-03)","text":"<p>A device reporting 25/28 KiB primary fallback and contact enumeration error 5 was flashed with the recovery build. With no explicit repair command, startup activated 100 KiB ExtraFS and loaded all 125 contacts and 40 channel slots. Identity, preferences, radio settings, and channels matched the pre-update API snapshot. Add, edit, and delete of an owned temporary contact each survived a separate normal reboot; the device ended with the original 125 contacts and 27/100 KiB usage. The 161 offline/native regression tests and target build passed.</p> <p>This was not lossless recovery of every historical RAM value: 21 contacts had older advertisement/local-modification timestamps, including one older advertised location. No contact was missing, and no computer-backup restoration was used. A subsequent read-only scan found no readable cached advert for any of the 125 contacts. Without a surviving newer copy, firmware cannot infer those earlier values; receiving new verified advertisements can refresh them normally.</p>"},{"location":"nrf52_power_management/","title":"nRF52 Power Management","text":""},{"location":"nrf52_power_management/#overview","title":"Overview","text":"<p>The nRF52 Power Management module provides battery protection features to prevent over-discharge, minimise likelihood of brownout and flash corruption conditions existing, and enable safe voltage-based recovery.</p>"},{"location":"nrf52_power_management/#features","title":"Features","text":""},{"location":"nrf52_power_management/#boot-voltage-protection","title":"Boot Voltage Protection","text":"<ul> <li>Checks battery voltage immediately after boot and before mesh operations commence</li> <li>If voltage is below a configurable threshold (e.g., 3300mV), the device configures voltage wake (LPCOMP + VBUS) and enters protective shutdown (SYSTEMOFF)</li> <li>Prevents boot loops when battery is critically low</li> <li>Skipped when external power (USB VBUS) is detected</li> </ul>"},{"location":"nrf52_power_management/#voltage-wake-lpcomp-vbus","title":"Voltage Wake (LPCOMP + VBUS)","text":"<ul> <li>Configures the nRF52's Low Power Comparator (LPCOMP) before entering SYSTEMOFF</li> <li>Enables USB VBUS detection so external power can wake the device</li> <li>Device automatically wakes when battery voltage rises above recovery threshold or when VBUS is detected</li> <li>Uses no LPCOMP hysteresis; on divided battery inputs the additional 50 mV   comparator hysteresis can move the effective battery wake point by several   hundred millivolts and strand an otherwise charged node</li> </ul>"},{"location":"nrf52_power_management/#early-boot-register-capture","title":"Early Boot Register Capture","text":"<ul> <li>Captures RESETREAS (reset reason) and GPREGRET2 (shutdown reason) before SystemInit() clears them</li> <li>Allows firmware to determine why it booted (cold boot, watchdog, LPCOMP wake, etc.)</li> <li>Allows firmware to determine why it last shut down (user request, low voltage, boot protection)</li> </ul>"},{"location":"nrf52_power_management/#shutdown-reason-tracking","title":"Shutdown Reason Tracking","text":"<p>Shutdown reason codes (stored in GPREGRET2):</p> Code Name Description 0x00 NONE Normal boot / no previous shutdown 0x4C LOW_VOLTAGE Runtime low voltage threshold reached 0x55 USER User requested powerOff() 0x42 BOOT_PROTECT Boot voltage protection triggered"},{"location":"nrf52_power_management/#supported-boards","title":"Supported Boards","text":"Board family Implemented LPCOMP wake VBUS wake Seeed Studio XIAO nRF52840 (<code>xiao_nrf52</code>) Yes Yes Yes SenseCAP Solar Yes Yes Yes RAK4631 / RAK3401 Yes Yes Yes GAT562 30S / EVB Pro / Tracker Pro / Watch13 Yes Yes Yes Heltec T096 / T114 / T1 / Tower V2 Yes Yes Yes Muzi Works R1 Neo Partial Inactive Inactive Promicro nRF52840 No No No RAK WisMesh Tag No No No Heltec Mesh Solar No No No LilyGo T-Echo / T-Echo Lite / T-Impulse Plus No No No WIO Tracker L1 / L1 E-Ink / WM1110 No No No Mesh Pocket / Meshtiny / Nano G2 Ultra No No No ThinkNode M1 / M3 / M6 No No No T1000-E No No No Ikoka Nano / Stick / Handheld (nRF) No No No Keepteen LT1 / Minewsemi ME25LS01 No No No <p>Notes: - \"Implemented\" reflects Phase 1 (boot lockout + shutdown reason capture). - R1 Neo has the integration compiled, but its board configuration deliberately   sets <code>PWRMGT_VOLTAGE_BOOTLOCK</code> to <code>0</code>; automatic protective shutdown and its   voltage/VBUS recovery wake are therefore inactive. - User power-off does not enable LPCOMP wake; voltage recovery is armed only   for boot protection and automated low-voltage shutdown. - VBUS detection is used to skip boot lockout on external power, and VBUS wake is configured alongside LPCOMP when supported hardware exposes VBUS to the nRF52.</p>"},{"location":"nrf52_power_management/#technical-details","title":"Technical Details","text":""},{"location":"nrf52_power_management/#architecture","title":"Architecture","text":"<p>The power management functionality is integrated into the <code>NRF52Board</code> base class in <code>src/helpers/NRF52Board.cpp</code>. Board variants provide hardware-specific configuration via a <code>PowerMgtConfig</code> struct and override <code>initiateShutdown(uint8_t reason)</code> to perform board-specific power-down work and conditionally enable voltage wake (LPCOMP + VBUS).</p>"},{"location":"nrf52_power_management/#early-boot-capture","title":"Early Boot Capture","text":"<p>A static constructor with priority 101 in <code>NRF52Board.cpp</code> captures the RESETREAS and GPREGRET2 registers before: - SystemInit() (priority 102) - which clears RESETREAS - Static C++ constructors (default priority 65535)</p> <p>This ensures we capture the true reset reason before any initialisation code runs.</p>"},{"location":"nrf52_power_management/#board-implementation","title":"Board Implementation","text":"<p>To enable power management on a board variant:</p> <ol> <li> <p>Enable in platformio.ini:    <code>ini    -D NRF52_POWER_MANAGEMENT</code></p> </li> <li> <p>Define configuration in variant.h:    <code>c    #define PWRMGT_VOLTAGE_BOOTLOCK    3300   // Won't boot below this voltage (mV)    #define PWRMGT_LPCOMP_AIN          7      // AIN channel for voltage sensing    #define PWRMGT_LPCOMP_REFSEL       2      // REFSEL (0-6=1/8..7/8, 7=ARef, 8-15=1/16..15/16)</code></p> </li> <li> <p>Implement in board .cpp file:    ```cpp    #ifdef NRF52_POWER_MANAGEMENT    const PowerMgtConfig power_config = {      .lpcomp_ain_channel = PWRMGT_LPCOMP_AIN,      .lpcomp_refsel = PWRMGT_LPCOMP_REFSEL,      .voltage_bootlock = PWRMGT_VOLTAGE_BOOTLOCK    };</p> </li> </ol> <p>void MyBoard::initiateShutdown(uint8_t reason) {      // Board-specific shutdown preparation (e.g., disable peripherals)      bool enable_lpcomp = (reason == SHUTDOWN_REASON_LOW_VOLTAGE ||                            reason == SHUTDOWN_REASON_BOOT_PROTECT);</p> <pre><code> if (enable_lpcomp) {\n   configureVoltageWake(power_config.lpcomp_ain_channel, power_config.lpcomp_refsel);\n }\n\n enterSystemOff(reason);\n</code></pre> <p>}    #endif</p> <p>void MyBoard::begin() {      NRF52Board::begin();  // or NRF52BoardDCDC::begin()      // ... board setup ...</p> <p>#ifdef NRF52_POWER_MANAGEMENT      checkBootVoltage(&amp;power_config);    #endif    }    ```</p> <p>For user-initiated shutdowns, <code>powerOff()</code> remains board-specific. Power management only arms LPCOMP for automated shutdown reasons (boot protection/low voltage).</p> <ol> <li>Declare override in board .h file:    <code>cpp    #ifdef NRF52_POWER_MANAGEMENT      void initiateShutdown(uint8_t reason) override;    #endif</code></li> </ol>"},{"location":"nrf52_power_management/#voltage-wake-configuration","title":"Voltage Wake Configuration","text":"<p>The LPCOMP (Low Power Comparator) is configured to: - Monitor the specified AIN channel (0-7 corresponding to P0.02-P0.05, P0.28-P0.31) - Compare against VDD fraction reference (REFSEL: 0-6=1/8..7/8, 7=ARef, 8-15=1/16..15/16) - Detect UP events (voltage rising above threshold) - Use no hysteresis so the configured recovery threshold is not widened by the battery divider - Wake the device from SYSTEMOFF when triggered</p> <p>VBUS wake is enabled via the POWER peripheral USBDETECTED event whenever <code>configureVoltageWake()</code> is used. This requires USB VBUS to be routed to the nRF52 (typical on nRF52840 boards with native USB).</p> <p>LPCOMP Reference Selection (PWRMGT_LPCOMP_REFSEL):</p> REFSEL Fraction VBAT @ 1M/1M divider (VDD=3.0-3.3) VBAT @ 1.5M/1M divider (VDD=3.0-3.3) 0 1/8 0.75-0.82 V 0.94-1.03 V 1 2/8 1.50-1.65 V 1.88-2.06 V 2 3/8 2.25-2.47 V 2.81-3.09 V 3 4/8 3.00-3.30 V 3.75-4.12 V 4 5/8 3.75-4.12 V 4.69-5.16 V 5 6/8 4.50-4.95 V 5.62-6.19 V 6 7/8 5.25-5.77 V 6.56-7.22 V 7 ARef - - 8 1/16 0.38-0.41 V 0.47-0.52 V 9 3/16 1.12-1.24 V 1.41-1.55 V 10 5/16 1.88-2.06 V 2.34-2.58 V 11 7/16 2.62-2.89 V 3.28-3.61 V 12 9/16 3.38-3.71 V 4.22-4.64 V 13 11/16 4.12-4.54 V 5.16-5.67 V 14 13/16 4.88-5.36 V 6.09-6.70 V 15 15/16 5.62-6.19 V 7.03-7.73 V <p>Important: For boards with a voltage divider on the battery sense pin, LPCOMP measures the divided voltage. Use: <code>VBAT_threshold ~ (VDD * fraction) * divider_scale</code>, where <code>divider_scale = (Rtop + Rbottom) / Rbottom</code> (e.g., 2.0 for 1M/1M, 2.5 for 1.5M/1M, 3.0 for XIAO).</p>"},{"location":"nrf52_power_management/#softdevice-compatibility","title":"SoftDevice Compatibility","text":"<p>The power management code checks whether SoftDevice is enabled and uses the appropriate API: - When SD enabled: <code>sd_power_*</code> functions - When SD disabled: Direct register access (NRF_POWER-&gt;*)</p> <p>This ensures compatibility regardless of BLE stack state.</p>"},{"location":"nrf52_power_management/#cli-commands","title":"CLI Commands","text":"<p>Power management status can be queried via the CLI:</p> Command Description <code>get pwrmgt.support</code> Returns \"supported\" or \"unsupported\" <code>get pwrmgt.source</code> Returns current power source - \"battery\" or \"external\" (5V/USB power) <code>get pwrmgt.bootreason</code> Returns reset and shutdown reason strings <code>get pwrmgt.bootmv</code> Returns boot voltage in millivolts <p>On boards without power management enabled, <code>get pwrmgt.source</code> and <code>get pwrmgt.bootmv</code> return:</p> <pre><code>ERROR: Power management not supported\n</code></pre> <p><code>get pwrmgt.support</code> returns <code>unsupported</code>. <code>get pwrmgt.bootreason</code> is not compiled out at all and answers on every board: <code>getResetReason()</code> and <code>getShutdownReason()</code> are virtuals on the base board class, so a board that does not override them reports <code>Not available</code> rather than an error. ESP32 boards override the reset half with <code>esp_reset_reason()</code>, so they return a real reset reason and <code>Not available</code> for the shutdown reason.</p>"},{"location":"nrf52_power_management/#debug-output","title":"Debug Output","text":"<p>When <code>MESH_DEBUG=1</code> is enabled, the power management module outputs:</p> <pre><code>DEBUG: PWRMGT: Reset = Wake from LPCOMP (0x20000); Shutdown = Low Voltage (0x4C)\nDEBUG: PWRMGT: Boot voltage = 3450 mV (threshold = 3300 mV)\nDEBUG: PWRMGT: LPCOMP wake configured (AIN7, ref=3/8 VDD)\n</code></pre>"},{"location":"nrf52_power_management/#phase-2-planned","title":"Phase 2 (Planned)","text":"<ul> <li>Runtime voltage monitoring</li> <li>Voltage state machine (Normal -&gt; Warning -&gt; Critical -&gt; Shutdown)</li> <li>Configurable thresholds</li> <li>Load shedding callbacks for power reduction</li> <li>Deep sleep integration</li> <li>Scheduled wake-up</li> <li>Extended sleep with periodic monitoring</li> </ul>"},{"location":"nrf52_power_management/#references","title":"References","text":"<ul> <li>nRF52840 Product Specification - POWER</li> <li>nRF52840 Product Specification - LPCOMP</li> <li>SoftDevice S140 API - Power Management</li> </ul>"},{"location":"number_allocations/","title":"Number Allocations","text":"<p>This document lists unique numbers/identifiers used in various MeshCore protocol payloads.</p>"},{"location":"number_allocations/#group-data-types","title":"Group Data Types","text":"<p>The <code>PAYLOAD_TYPE_GRP_DATA</code> payloads have a 16-bit data-type field, which identifies which application the packet is for.</p> <p>To make sure multiple applications can function without interfering with each other, the table below is for reserving various ranges of data-type values. Just modify this table, adding a row, then submit a PR to have it authorised/merged.</p> <p>NOTE: the range FF00 - FFFF is for use while you're developing, doing POC, and for these you don't need to request to use/allocate.</p> <p>Once you have a working app/project, you need to be able to demonstrate it exists/works, and THEN request type IDs. So, just use the testing/dev range while developing, then request IDs before you transition to publishing your project.</p> Data-Type range App name Contact 0000 - 00FF -reserved for internal use- 0100 MeshCore Open zsylvester@monitormx.com - https://github.com/zjs81/meshcore-open 0110 - 011F Ripple ripple_biz@protonmail.com - https://buymeacoffee.com/ripplebiz 0120 MCO Advanced most.original.address@gmail.com - https://github.com/HDDen/meshcore-open/tree/rename-mco-advanced FF00 - FFFF -reserved for testing/dev- <p>(add rows, inside the range 0100 - FEFF for custom apps)</p>"},{"location":"ota_easy/","title":"Easy firmware updates over LoRa","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>This guide shows the shortest manual path for sending firmware from a computer to a MeshCore node over LoRa. Choose the package type for the destination node:</p> <p>For an end-to-end controller that accepts a release ZIP or ready mOTA, see Scripted LoRa OTA from start to finish.</p> Destination Update type Files needed to build the <code>.mota</code> Installer ESP32 Full firmware New non-merged application <code>.bin</code> ESP32 A/B firmware slots nRF52, internal staging In-place delta Exact running <code>firmware.hex</code> and new <code>firmware.hex</code> Exact-board OTAFIX bootloader Supported nRF52 QSPI repeater Full firmware or in-place delta New <code>firmware.hex</code>; a delta also needs the exact running <code>firmware.hex</code> Matching QSPI-aware OTAFIX bootloader MeshTower V2 SD target Full firmware or in-place delta New <code>firmware.hex</code>; a delta also needs the exact running <code>firmware.hex</code> Matching SD-aware OTAFIX bootloader <p>An internal-staging nRF52 target accepts only an in-place delta built against its exact running firmware. Matched QSPI repeater targets and the MeshTower V2 microSD target can also install a full image because the complete container stays off-chip. See nRF52 repeater OTA with external QSPI and MeshTower V2 microSD LoRa OTA.</p> <p>MeshTower V2 microSD application and bootloader containers must be Ed25519-signed by a key in the device allowlist; pass <code>--sign</code> to <code>motatool build</code> (or <code>--sign-key</code> to the end-to-end runner) when building one. Its BLM2-capable SD-aware bootloader is also required before ordinary application or bootloader OTA can use the reset-retained authorization record. Upgrade preview.12 locally over USB/BLE DFU or SWD first; there is no raw-card compatibility handoff.</p>"},{"location":"ota_easy/#temporary-ota-channel-used-in-this-guide","title":"Temporary OTA channel used in this guide","text":"Setting Value Center frequency 910.525 MHz Bandwidth 250 kHz Spreading factor SF5 Coding rate used in this guide CR5 Example window 120 minutes <p>The copy/paste command is:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>The fourth value is the transmit coding rate. This guide uses CR5, but the participating nodes' coding rates do not need to match.</p> <p><code>tempradio</code> is not saved and the node returns to its normal radio settings when the window ends or the node reboots. Current full-parser firmware also accepts <code>normalradio</code>, which cancels the temporary window and restores the saved tuple after replying on the current channel. This frequency is intended for North American configurations. Confirm that it is permitted in your location and change it when necessary.</p> <p>At SF5/BW250, an SX1262+TCXO destination can keep RXPS enabled only when it and every sender that can reach it (controller, source, and relays) follow the v1.17.1.5-or-newer adaptive-preamble contract. The qualified destination boundary is effective level 8, preamble 64 and <code>1252 / 6424 us</code>. For manual setup, save <code>set radio.rxps level 8 preamble 32</code> before entering TempRadio; the <code>32</code> is a conservative saved timing assumption and current firmware selects the real 64-symbol wire preamble when it retunes the temporary radio. For an older, unknown, or mixed-version path, use <code>set radio.rxps off</code> for the maintenance window. First record <code>get radio.rxps.config</code>; after <code>normalradio</code>, restore a reported level with <code>set radio.rxps level N preamble P</code> (omit <code>preamble P</code> when <code>P</code> is <code>0</code>). A legacy node returns only on/off and periods, which can be restored with <code>set radio.rxps RX_US SLEEP_US</code>. The scripted runner performs the version checks, temporary change, verification, and restoration automatically while preserving automatic retuning. SF5/BW500 is too fast for RXPS even with a 64-symbol preamble, so current firmware selects 128 and uses the qualified level-8 <code>626 / 6398 us</code> timing when every participant supports the adaptive contract.</p>"},{"location":"ota_easy/#before-you-start","title":"Before you start","text":"<p>Both paths require:</p> <ul> <li>A destination artifact explicitly identified by its release table as install-capable. Some lean internal   nRF52 builds carry <code>lora_ota_no_external_sensors</code> in the filename, while matched QSPI boards enable install   support in the normal full-sensor repeater or room-server artifact, so filename text alone is not authoritative. Confirm   support with <code>ota self</code> and <code>ota status</code>. Intermediate repeaters do not need an install-capable build:   current repeater firmware relays OTA packets opaquely without storing or installing them.</li> <li>An OTA-enabled MeshCore source connected to the computer by USB serial, or   an ESP32 WiFi companion/FULL source connected over WiFi as described below.</li> <li>Overlapping <code>tempradio</code> windows on the source, destination, and every repeater needed between them.</li> </ul> <p>LoRa OTA packets are generated, consumed, and relayed only while <code>tempradio</code> is active. Intermediate repeaters apply their normal forwarding filters, duplicate checks, and flood limits; they do not interpret the OTA payload. If any required window closes, the transfer stops making progress and can resume during a later overlapping window.</p> <p><code>build.sh</code> provides a <code>*_repeater_lora_ota_no_external_sensors</code> or <code>*_room_server_lora_ota_no_external_sensors</code> build for standalone ESP32 and nRF52 infrastructure targets that need a smaller internal update workspace. Those siblings omit selected optional environmental and ranging drivers while retaining board-native features such as displays, buttons, battery monitoring, and GPS where the target uses the GPS-preserving lean profile. RAK3401 and RAK4631 reduced builds also retain INA219, INA226, INA260, and INA3221 I2C voltage/current monitors; together these drivers cost less than 5 KiB in the measured profile. Those four monitor drivers are not the only retained I2C support: the board's SSD1306 OLED, supported autodiscovered RTCs, and the RAK12500 GPS remain separate I2C peripherals in GPS-compatible RAK recipes. RAK12501/L76K GPS instead uses UART Serial1. The RAK3401 OTA repeater supports either GPS module in sensor slot A; slot D conflicts with the RAK13302 radio's BUSY/DIO1 lines. The RAK4631 OTA repeater defaults its runtime RS-232 bridge to Serial2 so the UART RAK12501 can retain Serial1. The runtime guard always reserves Serial1 because a bounded silent probe cannot prove a cold RAK12501 is absent; the shared WB_IO2/3V3_S rail keeps a fitted module powered and driving the UART. Use Serial2. Serial1 requires an explicit no-GPS/dedicated image. The merged image remains fail-closed even when it detects an I2C RAK12500. The explicit legacy Serial1 bridge omits the combined GPS provider, including the otherwise non-UART RAK12500 path.</p> <p>The firmware-configured INA3221 address and the RAK12500 address are both <code>0x42</code>; they cannot coexist on one bus at those addresses. Keep RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a build with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both are installed.</p> <p>Selected nRF52 boards with matched external QSPI application and bootloader support can instead make the normal full-sensor repeater or room-server install-capable; those targets do not need to reserve internal flash for the downloaded container. SolarXiao 30S and 33S use this matched external-QSPI path and therefore do not emit redundant no-external-sensors siblings. A RAK19007 can use the same separately wired W25Q16 with either RAK4631 or RAK3401 + RAK13302: the flash consumes no WisBlock slot and GPS remains supported in slot A. This is not the RAK15001 arrangement; RAK15001 and RAK13302 share a chip-select and cannot be used together. Other normal repeaters can still serve as intermediate relays but cannot necessarily install an update themselves. ESP32 <code>-ota-</code> siblings also retain the lightweight browser WiFi uploader (<code>start ota</code>), the complete CLI, and up to 254 neighbors; constrained targets use 50 as recorded in their capability manifests. RP2040 and STM32 repeaters do not currently have a safe self-apply path, but current repeater firmware can still relay OTA packets opaquely during TempRadio.</p> <p>For one explicitly selected internal-flash nRF52 repeater or room server, the default <code>--build-profile auto</code> run emits two install-capable choices. The <code>*-full-ota-*</code> artifact retains external sensors, while the <code>*_lora_ota_no_external_sensors-reduced-ota-*</code> artifact trades only those optional drivers not explicitly retained by the board profile for more delta-staging space. They retain the same OTA target identity so update tooling does not confuse the optimization choice with a different board. QSPI- and SD-backed repeater and room-server roles emit only the complete choice unless a measured size failure requires a fallback.</p> <p>nRF52 <code>-ota-</code> siblings are compiled with size optimization instead of the Adafruit platform's default speed optimization. This prevents the retained software Ed25519 fallback from expanding beyond the fixed in-place workspace; CC310 hardware crypto, hardware RNG mixing, telemetry history, and board-native features remain enabled.</p> <p>ESP32 <code>*-full-usb-wifi-ota-*</code> artifacts retain all compiled features and enable LoRa OTA for every FULL role, including room servers, sensors, observers, and bridges. A FULL image requires its expanded partition table: install the matching merged image over USB once before installing later non-merged FULL updates over LoRa. ESP32 MQTT observers and ESP-NOW bridges are always emitted as FULL artifacts; compact-CLI variants are no longer built. The <code>*-full-usb-wifi-ota-*</code> profile compiles USB packet logging and direct WiFi MQTT into one image. Use <code>set logging.output off|usb|wifi|both</code> to persist the desired path. A <code>*-full-logging-ota-*</code> artifact is now only a fallback for a hardware/role combination without a WiFi MQTT target and can produce substantial serial output.</p>"},{"location":"ota_easy/#choose-the-source-radio","title":"Choose the source radio","text":"<p>Use an OTA-enabled MeshCore node as the source. It receives the update folder from the computer, then advertises it over LoRa. ESP32 USB/WiFi companions and FULL ESP32 roles include the required transport. A <code>*_companion_radio_full</code> target keeps only the source half of LoRa OTA: it serves host images but cannot stage or install one for itself. ESP32 full combines USB, BLE, and WiFi; nRF52 full combines USB and BLE because nRF52840 has no WiFi. A small set of high-capacity, non-PSRAM classic ESP32 companions keep their normal image and provide a separate <code>-full-logging-ota-</code> fallback with 100 contacts, 8 group channels, a 16-frame offline queue, and persistent USB output selection. Install that variant's merged image over USB once before using it. Connect the source by USB serial or, when supported, by WiFi. For an ordinary raw-text USB source, confirm that its USB CLI accepts:</p> <pre><code>ota folder on\n</code></pre> <p>If an older build reports that <code>OTA_FOLDER_SERIAL</code> is not compiled in, install a current <code>-ota-</code>, <code>-full-usb-wifi-ota-</code>, or applicable <code>-full-logging-ota-</code> build first. Do not use a KISS modem: KISS firmware is a TNC/KISS frame interface and does not provide the MeshCore CLI or the OTA-folder transport that <code>motatool serve</code> requires.</p> <p>An nRF52 <code>companion_radio_full</code> starts in its USB ASCII terminal and automatically changes to Binary Companion when it receives a complete <code>&lt;</code> frame. It also recognizes <code>motatool</code>'s exact initial <code>ota folder on</code> line and enters exclusive mOTA mode directly, so <code>motatool serve --serial</code> can be the first client after boot. No terminal token or preliminary disconnect is required. Stopping the tool or disconnecting resets USB to Binary. BLE remains available throughout. See the Full Companion USB switcher guide for the complete ownership transitions. Protocol v14 can instead take the catalog from a paired phone or Linux host over a separate encrypted BLE mOTA service while Binary Companion remains active. USB and BLE catalog sources are mutually exclusive. See the Full Companion Bluetooth source guide.</p> <p>For an ESP32 WiFi companion or FULL ESP32 source with active WiFi, use its dedicated OTA seeder:</p> <pre><code>motatool serve --dir ./motas --tcp &lt;source-host&gt;:5001 -v\n</code></pre> <p>Port <code>5001</code> is separate from the companion application port (<code>5000</code>) and the HTTP configuration/browser-OTA port (<code>80</code>, depending on the role). An ESP32 <code>companion_radio_full</code> also has its complete role-specific text terminal on port <code>5002</code>; OTA automation uses its <code>ota</code> and TempRadio subset. See the full Companion guide. On a FULL repeater or room server, <code>start webconfig</code> can bring up the saved WiFi connection. Other FULL roles with browser OTA support can raise <code>MeshCore-OTA</code> with <code>start ota</code> and use <code>192.168.4.1:5001</code>. The TCP seeder auto-attaches; do not also run <code>ota folder on</code> for USB serial.</p>"},{"location":"ota_easy/#install-motatool","title":"Install <code>motatool</code>","text":"<p>Install Rust if necessary, then install the standalone packaging and serving tool:</p> <pre><code>git clone https://github.com/vk496/motatool\ncargo install --path ./motatool\n</code></pre>"},{"location":"ota_easy/#esp32-package-a-full-firmware-image","title":"ESP32: package a full firmware image","text":"<p>The destination must be an OTA-capable ESP32 with an A/B partition table. Download or build the new non-merged <code>.bin</code> application for the destination's exact board and role. Do not use an ESP32 <code>-merged.bin</code> factory image.</p> <p>Put the application firmware in a working directory, then build a full <code>.mota</code> container. For example:</p> <pre><code>mkdir -p ./motas\nmotatool build --fw ./Heltec_v3_repeater-ota-v1.16.05.bin --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>Replace the example filename with the firmware for the destination's exact target. With no <code>--base</code> argument, <code>motatool build</code> creates a full-image update. The firmware must contain its MeshCore <code>EndF</code> identity trailer so <code>motatool</code> and the destination can verify the target, hardware, and version.</p> <p>Do not continue if <code>motatool verify</code> reports a failure.</p>"},{"location":"ota_easy/#nrf52-package-a-full-image-or-in-place-delta","title":"nRF52: package a full image or in-place delta","text":""},{"location":"ota_easy/#1-install-and-check-the-otafix-bootloader","title":"1. Install and check the OTAFIX bootloader","text":"<p>This is a one-time prerequisite. Install the OTAFIX bootloader built for the destination's exact board from the OTAFIX nRF52 bootloader releases. Internal-staging delta updates require OTAFIX 2.4 or newer. External QSPI and SD staging require OTAFIX 2.4.1 or newer and release notes that explicitly list the exact board and storage mode. Follow the release's board-specific installation and erase instructions. If it does not contain the destination's exact board, this LoRa install path is not yet available for that board; never substitute a similar board's bootloader.</p> <p>Before preparing or downloading a LoRa update, run this on the destination:</p> <pre><code>get bootloader.ver\nota self\n</code></pre> <p>The first command identifies the installed nRF52 bootloader. Continue only if the <code>ota self</code> reply includes the apply mode required by this target:</p> <pre><code>bootloader: apply OK\nbootloader: QSPI apply OK\nbootloader: SD apply OK\n</code></pre> <p>The reply also contains the running firmware's <code>base_hash</code>. Save it for the package check below. A stock, legacy, or older OTAFIX bootloader without <code>.mota</code> in-place-apply support will report that apply support is missing, and <code>ota install</code> will refuse to reboot into it.</p>"},{"location":"ota_easy/#2-choose-full-or-delta-packaging","title":"2. Choose full or delta packaging","text":"<p>For a QSPI- or SD-backed target, a full update needs only the new raw <code>firmware.hex</code>:</p> <pre><code>mkdir -p ./motas\nmotatool build --fw ./LilyGo_T-Echo_repeater-new.hex --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>Use a full package when an exact base image is unavailable. Use the delta path below when reducing airtime is worth retaining the exact running image.</p>"},{"location":"ota_easy/#3-keep-the-exact-current-and-new-application-images-for-a-delta","title":"3. Keep the exact current and new application images for a delta","text":"<p>You need the raw <code>.pio/build/&lt;environment&gt;/firmware.hex</code> from the build that is actually running, plus the corresponding <code>firmware.hex</code> from the new build. Save the current file before building the new version, because PlatformIO reuses that path. For example:</p> <pre><code># Save this immediately after building/flashing the version now running on the node.\ncp .pio/build/Heltec_t114_repeater_lora_ota_no_external_sensors/firmware.hex \\\n  ./Heltec_t114_repeater_lora_ota_no_external_sensors-running.hex\n\n# After checking out and building the new version, save its image separately.\ncp .pio/build/Heltec_t114_repeater_lora_ota_no_external_sensors/firmware.hex \\\n  ./Heltec_t114_repeater_lora_ota_no_external_sensors-new.hex\n</code></pre> <p>Replace <code>Heltec_t114_repeater_lora_ota_no_external_sensors</code> with the destination's exact PlatformIO environment. The two images must be for the same board and role, and both must contain their <code>EndF</code> trailers. Do not pass a release <code>.uf2</code> or BLE-DFU <code>.zip</code> to <code>motatool</code>; those are installation containers rather than raw application images.</p> <p>Keeping a file with the same version label is not enough: the base must be byte-for-byte identical to the running application. The hash check in the next step proves that it is the right file.</p> <p>On RAK4631 repeaters, use the <code>RAK_4631_repeater_lora_ota_no_external_sensors</code> environment. It retains built-in battery monitoring but omits selected optional environmental/ranging drivers so the delta fits the safe in-place workspace. INA219, INA226, INA260, and INA3221 I2C voltage/current monitors remain supported despite the legacy target name. That trim does not remove the SSD1306 OLED, autodiscovered I2C RTCs, or GPS-compatible RAK12500 I2C path. The <code>0x42</code> RAK12500/INA3221 addressing rule above still applies. If the device has a RAK15001 installed in sensor slot C and the matching RAK15001 OTAFIX bootloader, use <code>RAK_4631_repeater_rak15001_slot_c_lora_ota</code> instead. That target retains the full sensor/GPS set and can install either a full image or a delta from the external 2 MiB store.</p> <p>With the separately wired Winbond breakout, use <code>RAK_4631_repeater_w25q16_lora_ota</code> for RAK4631 or <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code> for RAK3401 + RAK13302. Both require an <code>EF4015</code> 2 MiB device. As a one-time prerequisite, install <code>wiscore_rak4631_w25q16</code> for RAK4631 or <code>wiscore_rak3401_rak13302_w25q16</code> for RAK3401 + RAK13302. Wire CLK/MISO/MOSI to the RAK19007 IO connector pins 26/27/28, CS to J11 AIN1, and VCC/GND to J12 VDD/GND. Fit an approximately 10 kOhm CS-to-VDD pull-up; never use VBAT. The SPI pins require underside taps or an interposer, but no sensor slot is occupied. See the nRF52 QSPI guide before installing either image.</p>"},{"location":"ota_easy/#4-build-and-check-the-in-place-delta","title":"4. Build and check the in-place delta","text":"<pre><code>mkdir -p ./motas\nmotatool build \\\n  --base ./Heltec_t114_repeater_lora_ota_no_external_sensors-running.hex \\\n  --fw ./Heltec_t114_repeater_lora_ota_no_external_sensors-new.hex \\\n  --patch-type in-place \\\n  --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p><code>motatool</code> prints the generated filename. Inspect that file:</p> <pre><code>motatool inspect ./motas/GENERATED_FILENAME.mota\n</code></pre> <p>Check all three of these before serving it:</p> <ul> <li><code>codec_id</code> is <code>2 (detools-in-place)</code>.</li> <li><code>base_hash</code> is the same 8-byte value reported by the destination's <code>ota self</code> command.</li> <li>The numeric <code>target_id</code> exactly matches <code>target:</code> in the destination's <code>ota status</code>, and the hardware and   firmware version identify the intended board and role. If <code>inspect</code> shows <code>N/A</code> for the human-readable   target name, the tool's name table is older than that environment; the numeric IDs still must match.</li> </ul> <p>Current layout-aware <code>motatool</code> derives the safe workspace from the new firmware's authenticated EndF layout record, so the normal recipe deliberately omits <code>--inplace-memory</code>. If older tooling requires an explicit override, use <code>0xC6000</code> only for matched external SD/QSPI staging and <code>0x98000</code> for an internal-staging nRF52 such as the RAK4631 lean OTA build. Do not substitute the external value on an internal target, and do not override either value unless you have verified the exact app base, bootloader, and package geometry. Do not continue if verification or any identity check fails.</p>"},{"location":"ota_easy/#transfer-and-install-either-package","title":"Transfer and install either package","text":""},{"location":"ota_easy/#1-start-the-temporary-ota-channel","title":"1. Start the temporary OTA channel","text":"<p>First save the current <code>ota config</code> output. For a direct source-to-destination link, set both OTA-enabled endpoints to direct-only mode before starting the transfer:</p> <pre><code>ota config hops 0\n</code></pre> <p>Do not use <code>hops 1</code> as extra margin on a direct link. It tells a receiving repeater to retransmit each direct DATA/PROOF packet; that unnecessary half-duplex transmission can make it miss the source's next fragment, especially with older single-block receivers. Use <code>hops 1</code> only when one real intermediate relay is required, <code>hops 2</code> for two, and so on. This setting is saved, so restore the original value after the maintenance window.</p> <p>On the source node, destination node, and every intermediate repeater, then run:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>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 <code>tempradio</code>.</p> <p>If you administer the destination over LoRa, the controller used to send later <code>ota</code> commands must also be able to communicate on this temporary channel. For unattended nodes, use synchronized <code>tempradioat</code> entries instead of manually starting the windows. Ensure the nodes' clocks are set before using <code>tempradioat</code>.</p>"},{"location":"ota_easy/#2-serve-the-update-from-the-computer","title":"2. Serve the update from the computer","text":"<p>Close any serial terminal using the source node's USB port, find its device name, and start the server:</p> <pre><code>motatool serve --dir ./motas --serial /dev/ttyACM0 -v\n</code></pre> <p>Replace <code>/dev/ttyACM0</code> with the USB serial device of the source companion selected above. <code>motatool</code> attaches the folder to the source, which advertises the update over LoRa while its temporary-radio window is active. KISS modem serial ports cannot be used here.</p> <p>For an nRF52 Full Companion and a Bluetooth-capable host, the equivalent cable-free source is:</p> <pre><code>python3 tools/ble_mota/ble_mota_seeder.py \\\n  --device MeshCore-MyCompanion \\\n  --dir ./motas \\\n  --local 'tempradio 910.525,250,5,5,120'\n</code></pre> <p>Leave this command running until the destination finishes downloading.</p>"},{"location":"ota_easy/#3-find-and-download-the-update","title":"3. Find and download the update","text":"<p>On the destination node, check its state and ask for nearby updates:</p> <pre><code>ota status\nota ls\n</code></pre> <p>Discovery is asynchronous. <code>ota ls</code> says <code>refreshing</code>; wait a few seconds and run it again even if it first shows an older row. Select <code>[same target]</code>: it can say <code>full</code> for ESP32 and external SD/QSPI nRF52 targets, or <code>delta</code> for any supported nRF52 target. Do not select <code>[unsupported]</code> (for example, a source's self-served full image on an internal-staging nRF52). Rows labelled <code>bootloader</code> are also outside this ordinary application flow: they are never automatic and <code>ota install</code> refuses them. Only an already-capable, allowlisted internal-flash, XIAO-QSPI, or exact MeshTower V2 microSD nRF52 target can use the separate explicit bootloader workflow. Use the row's stable eight-hex manifest ID rather than its changing list position:</p> <pre><code>ota pull 838B8169 flash\n</code></pre> <p>If a legacy internal-flash nRF52 reports <code>no EndF</code>, only a row marked <code>[rescue]</code> is eligible. Current rescue-capable firmware requires <code>ota pull &lt;mid8&gt; flash rescue</code>, followed after completion by <code>ota rescue install &lt;base_hash16&gt;</code>. Older running firmware without those commands must be recovered over USB. Shared-internal bootloader-update builds are stricter: without a valid live <code>EndF</code>, every internal pull is refused before erase because the normal application may extend through <code>0xED000</code>. Recover those builds over USB/BLE DFU or SWD instead of relying on the older 608 KiB rescue estimate.</p> <p>Monitor the transfer:</p> <pre><code>ota status\n</code></pre> <p>To adjust LoRa OTA pacing, use <code>get ota.speed</code> and <code>set ota.speed &lt;0.05..3&gt;</code> on the source, destination, and OTA relays. <code>1</code> preserves the existing timing; lower values slow OTA down, and higher values shorten adjustable delays. This saved setting covers both profiles and OTA adverts as well as the transfer. It does not change radio modulation or the configured airtime budget. See LoRa OTA speed for details.</p> <p>For a powered bench update where restart-resume is not needed, <code>ota config checkpoint 0</code> on the destination removes periodic progress writes. It is a smaller optimization than selecting the correct hop count and it trades away persisted mid-download resume; restore the previous checkpoint cadence afterward.</p> <p>Current repeater firmware automatically uses the full transmit budget during a bounded TempRadio window. Older receivers do not: if <code>get af</code> reports a nonzero value on such a node, record it, use <code>set af 0</code> for the maintenance window, and restore it afterward. This affects how promptly the legacy receiver can send its next block/proof request; it does not increase LoRa transmit power. Use a full duty budget only where the selected frequency and local rules permit it.</p> <p>The update is ready when the status says <code>ready to install</code>. Discovery is background traffic, while an active OTA download is primary mesh traffic. At the temporary-radio settings in this guide, allow roughly one hour for a typical ESP32 full image over a quiet, direct link. That is a planning estimate, not an upper bound: repeaters, retries, weak links, and normal mesh traffic can extend it well past an hour. The 120-minute example window is intentional. If necessary, start another overlapping <code>tempradio</code> window; the download resumes rather than starting over.</p>"},{"location":"ota_easy/#4-verify-and-install","title":"4. Verify and install","text":"<p>Once the destination reports <code>ready to install</code>, run:</p> <pre><code>ota install\n</code></pre> <p>The destination verifies the complete package again before approving it. ESP32 installs the full image into its inactive A/B slot. nRF52 checks the bootloader and storage capabilities and, for a delta, the base hash, then reboots into OTAFIX. The bootloader independently rechecks the package, installs the external full image or applies the delta in place, and verifies the resulting image. Pre-install failures leave the running firmware unchanged and report the reason. If power is lost after an nRF52 in-place apply has begun, OTAFIX will not boot a partial image; it enters recovery DFU so a known-good application can be restored.</p> <p>After the node returns, reconnect on its normal radio channel and confirm:</p> <pre><code>ota status\n</code></pre>"},{"location":"ota_easy/#quick-troubleshooting","title":"Quick troubleshooting","text":"<ul> <li>Nothing appears in <code>ota ls</code>: confirm that <code>motatool serve</code> is still running and every required node   has an active <code>tempradio 910.525,250,5,5,120</code> window.</li> <li>The CLI says LoRa OTA is not included: that firmware does not contain the LoRa OTA feature.   If it is the source or destination, install a supported <code>-ota-</code> build over WiFi or USB first. An intermediate   repeater does not need the OTA CLI and can relay opaquely while its matching <code>tempradio</code> window is active.</li> <li>The update shows another environment or a raw <code>[hw XXXXXXXX]</code>: it is for a different board or firmware   role. Do not install it.</li> <li>An internal-flash nRF52 marks a full update <code>[unsupported]</code>: it can install only an in-place delta.   A matched QSPI repeater or MeshTower V2 microSD target accepts full images with its corresponding bootloader.</li> <li>A QSPI nRF52 reports <code>QSPI store:ERR 0K</code> or <code>bl:NO-QSPI</code>: do not download an install package. Install   the exact QSPI-aware bootloader and check that the selected application matches the board's flash wiring.   A RAK W25Q16 target must identify exactly <code>EF4015</code> and 2048K; also check its physical CS pull-up.</li> <li>nRF52 reports no bootloader apply support: install the exact-board in-place-delta OTAFIX bootloader   before trying LoRa OTA.</li> <li>nRF52 reports a base mismatch: the file passed to <code>--base</code> is not the exact application running on   the destination. Rebuild the delta from the correct saved <code>firmware.hex</code>.</li> <li>The download stalls: check the source, destination, and intermediate repeaters. Restart matching,   overlapping temporary-radio windows if one expired. On a direct link, also require <code>ota config hops 0</code>;   a larger reach makes a repeater destination unnecessarily echo source packets.</li> <li>The serial port is busy: close the serial terminal before starting <code>motatool serve</code>.</li> <li>The destination rejects the package: verify the source files, their <code>EndF</code> trailers, the package's   target/hardware identity, and the result of <code>motatool verify</code>.</li> </ul> <p>For additional commands and safety details, see the full OTA user guide. For protocol and container internals, see the OTA protocol specification.</p>"},{"location":"ota_meshtower_v2_sdcard/","title":"MeshTower V2 microSD LoRa OTA","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>The <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code> target uses the MeshTower V2 onboard microSD socket as persistent storage for its own LoRa OTA downloads. It accepts full application images, in-place application deltas, and explicitly selected signed v3 bootloader packages. After verification, the matching SD-aware OTAFIX bootloader reads the staged file from the card and programs the selected nRF52840 application or bootloader region.</p> <p>The pin assignment follows the Heltec MeshTower V2 partial reference circuit:</p> Signal nRF52840 pin Arduino pin number SD CS P1.00 32 SD MOSI P1.01 33 SD SCK P0.06 6 SD MISO P0.26 26 <p>The SD socket uses its own SPI peripheral, so card traffic does not change the LoRa radio pinout.</p>"},{"location":"ota_meshtower_v2_sdcard/#card-requirements","title":"Card requirements","text":"<p>Use a FAT16, FAT32, or exFAT card accepted by the bundled SdFat version. The normal update path imposes no additional MBR/sector-1 layout requirement; filesystem layouts SdFat cannot mount are still rejected. MeshCore creates <code>/meshcore-ota.mota</code> as a contiguous file and passes its exact sector range to OTAFIX in reset-retained MCU RAM.</p> <p>MeshCore never reads or writes raw sector 1 and does not infer ownership from blank card sectors. Both application and bootloader OTA require a locally provisioned BLM2-capable bootloader that understands the retained-RAM record. Preview.12 must first be upgraded over USB/BLE DFU or SWD.</p>"},{"location":"ota_meshtower_v2_sdcard/#capacity-and-update-types","title":"Capacity and update types","text":"<p>The card removes the internal-flash staging limit. The <code>.mota</code> container may be much larger than the old internal staging gap, and either a full image or an in-place delta may be downloaded. The installed firmware itself must still fit the nRF52840 application region below InternalFS (ending at <code>0xED000</code>); SD storage does not increase the MCU's executable flash.</p> <p>For this S140 v6 target, the maximum application image including its <code>EndF</code> trailer is <code>0xC7000</code> bytes (815,104 bytes). To package a full self-update:</p> <pre><code>motatool build --fw ./Heltec_tower_v2_sdcard-new.hex \\\n  --sign ./trusted-signer.key --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>A delta uses the exact installed image as its base. The normal <code>0x98000</code> workspace remains compatible. If either image is larger than that legacy limit, build the patch with the SD target's larger workspace:</p> <pre><code>motatool build \\\n  --base ./Heltec_tower_v2_sdcard-running.hex \\\n  --fw ./Heltec_tower_v2_sdcard-new.hex \\\n  --patch-type in-place \\\n  --inplace-memory 0xC7000 \\\n  --sign ./trusted-signer.key \\\n  --out-dir ./motas\nmotatool verify ./motas/*.mota\n</code></pre> <p>The download is resumable because the partial <code>.mota</code> stays on the card. Once it reaches <code>ready</code>, <code>ota install</code> performs the final verification, publishes a one-reset authorization record, and reboots. SD application installation requires a valid signature from a key in the node's allowlist. Keep the card inserted through the reboot and installation.</p> <p>The BLM2 retained-auth SD-aware bootloader is mandatory for application OTA. <code>ota install</code> refuses to reboot if its continuity metadata does not match the running S140 family/FWID/application layout or if its capability marker does not advertise SD staging and the selected codec. Existing <code>Heltec_tower_v2_repeater</code> firmware continues to use the internal-flash delta path and is unchanged.</p>"},{"location":"ota_meshtower_v2_sdcard/#signed-bootloader-update","title":"Signed bootloader update","text":"<p>Only this exact SD build exposes the privileged LoRa bootloader-update command. It requires an already installed exact-board ABI-3 OTAFIX bootloader whose one unambiguous capability marker is exactly <code>0x09</code> (<code>SD|BOOT_UPDATE</code>) and whose codec mask is <code>0x0005</code> (<code>FULL|INPLACE</code>). Requiring both application codecs prevents a bootloader self-update from disabling either normal SD application path. A stock bootloader still requires USB/BLE DFU or SWD. The sole remote bootstrap is intentionally absent: preview.12 and any other legacy-v1 image must be upgraded locally before either SD application or bootloader OTA.</p> <p>The signed v3 container is exactly 41,330 bytes and carries a 40 KiB candidate for the installed <code>239A0071 / TOWER_V2_OTA</code> identity (boot target <code>1150F50E</code>). It uses the same contiguous <code>/meshcore-ota.mota</code> file as an application update. GPREGRET <code>0x6B</code> plus the distinct SD source marker <code>0x53</code> selects the bootloader path; LoRa transport remains payload type <code>0x0C</code>.</p> <p>The application linker still ends at <code>0xED000</code>, but OTAFIX needs <code>0xE0000..0xEA000</code> as temporary scratch while replacing itself. Before a boot package can be downloaded or approved, MeshCore requires a hash-valid live <code>EndF</code> proving the complete running image ends by <code>0xE0000</code>; OTAFIX repeats that no-overlap check before its first erase. An application extending above that boundary can still receive normal FULL or delta application updates from SD, but its bootloader must be updated locally.</p> <p>MeshCore also checks the live boot settings before touching that scratch page. Erased settings and a valid-app record with CRC disabled are allowed. When a nonzero bank CRC is active, its recorded <code>bank_0_size</code> must cover the complete EndF-inclusive running image and must end by <code>0xE0000</code>; an undersized or oversized record refuses the operation and requires local DFU/SWD.</p> <p>Because the card is removable, approval is bound to the exact bytes that were authenticated. For both fmt2 application and fmt3 bootloader packages, MeshCore authenticates one exact signed manifest, requires every streamed manifest byte to match it, and verifies the leaves, payload, and image. During that same pass it hashes the entire container with only the mutable four-byte <code>APRV</code> field normalized to zero. After writing and syncing <code>APRV</code>, MeshCore publishes a 72-byte <code>MOTASDA2</code> record at reset-retained RAM address <code>0x20006008</code>. The record binds package purpose/format, exact LBA range, card size, container length, and that normalized SHA-256. OTAFIX consumes and clears the record before reading the card; changing the card or file can only fail. A power loss erases the authorization and also fails closed.</p> <p>For fmt3, MeshCore additionally writes and readback-verifies the temporary 64-byte <code>MOTASDBL</code> token at <code>0xE0000</code>, binding the exact total and signed manifest <code>image_hash</code>. OTAFIX requires the parsed manifest, streamed payload, and final scratch image to match it. The token page becomes scratch during a successful boot update and is not permanently reserved.</p> <p>Every new candidate also carries a backward-compatible <code>BLM2</code>/<code>SOFT</code> continuity extension next to its legacy embedded manifest. The complete 76-byte envelope is fixed at final raw-image offset <code>0x9FB4</code>; a relocated copy is not a valid candidate. Its embedded bootloader version must equal the outer package version, match the runtime SoftDevice family/FWID, application base, and layout ABI, and be strictly newer than an installed BLM2 version. Preview values use low bytes <code>1..254</code> and a stable release uses <code>0xFF</code>; zero-preview and all-ones versions are invalid. Remote bootloader rollback is not supported; use local DFU/SWD when rollback or migration is intentional.</p> <p>Bootloader packages are never autofetched or autoinstalled. Select and confirm one exact package manually:</p> <pre><code>ota ls\nota pull &lt;MID8&gt; flash\n# wait for ota status to report the bootloader download ready\nota bootloader\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Copy the MID and first 16 image-hash hex digits from <code>ota bootloader</code>. Ordinary <code>ota install</code> rejects this package, and the bootloader command rejects an application package. Keep the SD card inserted through the reboot. A later <code>ota status</code> value of <code>blup:C8</code> reports a successful bootloader replacement.</p> <p>After reboot, <code>ota bootloader</code> displays the installed board identity, CRC and capabilities. Its <code>mid</code> and <code>hash</code> fields describe a currently staged download, not the installed bootloader, so <code>staged:none mid=- hash=-</code> is not an install failure. <code>blrc:00</code> means no retained apply result is available; it does not by itself prove either success or failure.</p> <p>Older MeshCore application firmware can report <code>get bootloader.ver</code> as <code>unknown</code> for OTAFIX 2.4.6 because this bootloader image omits the legacy <code>UF2 Bootloader</code> text. The updated getter also reads the CRC-validated BLM2 version. For the official signed MeshTower V2 SD 2.4.6 <code>.mota</code>, the installed identity is <code>TOWER_V2_OTA</code>, CRC <code>5DACDB3D</code>, ABI <code>3</code>, and capabilities <code>09</code>. Compare the exact board/storage package when interpreting these values; the non-SD image differs.</p>"},{"location":"ota_meshtower_v2_sdcard/#sd-card-cli","title":"SD card CLI","text":"<p>The SD-backed target provides these CLI commands:</p> <pre><code>set sdcard format [--force]\nset sdcard erase [--force]\nget sdcard\nget sdcard *\nget sdcard format\nget sdcard erase\nget sdcard free\nget sdcard ls\nget sdcard ls 2\nget sdcard dir 3\n</code></pre> <p><code>format</code> creates a new FAT16, FAT32, or exFAT filesystem according to card size. <code>erase</code> first uses the card's raw media erase command and then formats it, so a successful erase finishes with a usable filesystem. Both operations destroy all data on the card and cancel any staged OTA download.</p> <p>The firmware records successful format and erase completion times in RAM. Repeating the same operation within five minutes is rejected unless <code>--force</code> is present. Format and erase have independent cooldowns. Because erase also formats the card, a successful erase updates both timestamps. The timestamps reset when the device reboots. The <code>get sdcard</code> age queries report how long ago each operation completed. <code>get sdcard free</code> reports used and free filesystem space in human-readable binary units.</p> <p><code>get sdcard ls</code> and <code>get sdcard dir</code> recursively list files on the card, two files per page. A bare command shows page 1; append a positive page number to move through the remaining results. Each row includes the path and a compact file size. The header reports the selected page, total pages, and total files.</p>"},{"location":"ota_meshtower_v2_sdcard/#persistent-ota-archive-and-seeder","title":"Persistent OTA archive and seeder","text":"<p>On the SD-backed target, automatic OTA archiving is on by default. While the temporary OTA radio is active, the node requests full catalogs from seeders and saves every complete mOTA it discovers, including firmware for other hardware targets and codecs that this node cannot install. Archive downloads use the same per-block Merkle proof checks as an install download, but archived images are never selected for local installation.</p> <p>Completed containers are stored as <code>/mota/&lt;manifest-id&gt;.mota</code>. An interrupted download remains <code>/mota/&lt;manifest-id&gt;.part</code> and resumes when that mOTA is seen again. Completed files survive reboot, are enumerated on the first archive access or TempRadio window, and are advertised and served directly from SD. The SD target supports the protocol maximum served set: its own running firmware plus up to 254 archived mOTAs.</p> <p>Automatic capture preserves an 8 MiB free-space reserve for manual <code>/meshcore-ota.mota</code> installation staging. It stops starting new archive files when the next file would cross that reserve. Archive allocation first tries the fast contiguous path and then falls back to an ordinary fragmented FAT file; only the bootloader staging file requires contiguous sectors.</p>"},{"location":"ota_meshtower_v2_sdcard/#preload-many-motas-from-a-computer","title":"Preload many mOTAs from a computer","text":"<p>You can populate the archive much faster on a computer than over LoRa. Use only complete, verified <code>.mota</code> containers. Do not copy firmware <code>.bin</code>, <code>.hex</code>, <code>.zip</code>, or <code>.part</code> files into the archive.</p> <p>Install the standalone <code>motatool</code> first if it is not already available:</p> <pre><code>git clone https://github.com/vk496/motatool.git\ncargo install --path ./motatool\n</code></pre> <p>The on-card filename is part of the archive index and has a strict format:</p> <pre><code>/mota/&lt;merkle_root&gt;.mota\n</code></pre> <p><code>&lt;merkle_root&gt;</code> is the eight-hex-digit value printed by <code>motatool inspect</code>. It is also the mOTA's four-byte manifest ID. The extension must be lowercase, the file must be directly inside <code>/mota</code>, and descriptive release filenames are not indexed. For example, if inspection reports:</p> <pre><code>merkle_root    : ABCD1234\n</code></pre> <p>copy that container to:</p> <pre><code>/mota/abcd1234.mota\n</code></pre> <p>If two containers have the same Merkle root, they have the same protocol ID and cannot both be present. Keep only the intended one. The current SD seeder can index up to 254 archived files. A served file must use a logical block size of at most 1024 bytes and contain at most 2048 blocks; check <code>block_size</code> and <code>block_count</code> in <code>motatool inspect</code> when importing unusually large images. Files outside that serve geometry are not counted or advertised. If a malformed <code>/mota/&lt;id&gt;.mota</code> conflicts with a newly discovered valid image, the repeater preserves the malformed file as <code>&lt;id&gt;.bad</code> through <code>&lt;id&gt;.bad9</code> and downloads a clean replacement instead of treating path existence as a valid cache hit.</p> <p>To prepare and load the card:</p> <ol> <li>Format it as described under Card requirements. The    easiest route is to insert it in the repeater, run <code>set sdcard format</code>, power    the repeater off, and then move the card to the computer. Formatting destroys    the existing card contents.</li> <li>Mount the card on the computer and create a directory named <code>mota</code> at the    filesystem root. Do not use a nested directory such as <code>/firmware/mota</code>.</li> <li>Run <code>motatool verify FILE.mota</code> for every source file. Do not copy a file    that reports <code>FAIL</code>.</li> <li>Run <code>motatool inspect FILE.mota</code>, read its <code>merkle_root</code>, and copy the file    to <code>/mota/&lt;lowercase-merkle-root&gt;.mota</code> on the card.</li> <li>Flush pending writes, safely eject the card, power the repeater off, insert    the card, and boot    <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code>.</li> </ol> <p>On Linux or macOS, this Bash example verifies and imports every <code>.mota</code> from <code>./motas</code>. Replace the example mount path before running it:</p> <pre><code>card_mount=/media/YOU/MESHCORE\nmkdir -p \"$card_mount/mota\"\n\nshopt -s nullglob\nfor image in ./motas/*.mota; do\n  motatool verify \"$image\" || exit 1\n  mid=$(motatool inspect \"$image\" |\n    awk '$1 == \"merkle_root\" { print tolower($3) }')\n  if [[ ! $mid =~ ^[0-9a-f]{8}$ ]]; then\n    echo \"Could not read the Merkle root from: $image\" &gt;&amp;2\n    exit 1\n  fi\n\n  destination=\"$card_mount/mota/$mid.mota\"\n  if [[ -e $destination ]]; then\n    cmp -s \"$image\" \"$destination\" || {\n      echo \"Different containers have the same ID: $mid\" &gt;&amp;2\n      exit 1\n    }\n  else\n    cp \"$image\" \"$destination\"\n  fi\ndone\nsync\n</code></pre> <p>On Windows, create <code>E:\\mota</code>, inspect each source with <code>motatool inspect</code>, and rename it to the reported lowercase root in the same way. Safely eject the drive after all copies finish.</p> <p>After boot, scan the archive and confirm the card contents from the repeater console:</p> <pre><code>get sdcard ls\nget sdcard ls 2\nota cache\nota folder\n</code></pre> <p><code>ota cache</code> should report the imported count. <code>ota folder</code> reports the current served count; once OTA serving starts in TempRadio, that set also includes the repeater's running firmware. If the files appear in <code>get sdcard ls</code> but not in the served count, check their exact names, run <code>motatool verify</code> again, and inspect their block geometry. It is fine to run <code>ota cache off</code> for a curated, read-mostly archive: that disables capture of new mOTAs but continues serving every valid file already on the card.</p>"},{"location":"ota_meshtower_v2_sdcard/#serve-the-preloaded-archive-over-tempradio","title":"Serve the preloaded archive over TempRadio","text":"<p>LoRa OTA traffic exists only during an active temporary-radio window. The SD repeater, each receiving node, and every intermediate repeater in the path need overlapping windows on the same temporary channel. Use a frequency permitted for the node's configured region. This North American example uses the recommended fast OTA settings and a 120-minute window:</p> <pre><code>tempradio 909.950,250,5,5,120\n</code></pre> <p>Start the farthest receiving node first, then intermediate repeaters, and the SD source last so their windows overlap for as long as possible. Before or during the source window, <code>ota cache</code> makes the source scan and attach the SD archive. Entry into TempRadio automatically triggers an OTA advertisement burst; <code>ota announce</code> can send another advertisement immediately.</p> <p>On a receiving OTA-capable node, allow a few seconds for catalog exchange, then run:</p> <pre><code>ota ls\nota ls 2\nota get &lt;mid8&gt; flash\nota status\n</code></pre> <p>Use <code>ota ls 2</code>, <code>ota ls 3</code>, and so on when the source advertises more than the two rows that fit in one remote CLI reply. Each row includes a stable eight-hex-digit manifest ID. Use that ID instead of a list number, because asynchronous catalog refreshes can reorder rows between the list and pull commands. A receiver retains the complete protocol catalog and verifies every transferred block. It still applies its normal target, hardware, codec, signature, and installation checks. The SD repeater may advertise images for many hardware families; it never installs those archive files merely because it serves them.</p> <p>When a temporary window expires or a node reboots, it returns to its saved radio settings and OTA transfer stops. The archive remains on the card. Start another set of overlapping <code>tempradio</code> windows to resume an interrupted download, or use synchronized <code>tempradioat</code> entries for a scheduled window.</p> <p>Archive capture is lower priority than operator work. An explicit <code>ota pull</code> to install storage or a host folder immediately takes the single receive slot; the archive partial is checkpointed and resumes later. Existing cached files can still answer peer requests while another archive file is downloading.</p> <p>Use these commands to inspect or control automatic capture:</p> <pre><code>ota cache\nota cache on\nota cache off\nota config cache on\nota config cache off\n</code></pre> <p>The on/off choice is saved on the SD card. Turning capture off stops new downloads but keeps serving files already cached. Formatting or erasing the card removes both the archive and its off marker, so a newly formatted card returns to the default-on setting. <code>ota config sdseed on|off</code> is also accepted as an alias.</p>"},{"location":"ota_nrf52_bootloader_update/","title":"nRF52 bootloader updates over LoRa","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>Selected nRF52840 repeater LoRa-OTA builds can replace their matching OTAFIX bootloader without replacing the running application. This is a privileged maintenance path, not a normal firmware update. A stock bootloader must first be replaced with the exact ABI-3 self-update-capable OTAFIX build over USB/BLE DFU or SWD. MeshTower SD also requires the BLM2 retained-auth version to be provisioned locally before either application or bootloader OTA.</p>"},{"location":"ota_nrf52_bootloader_update/#storage-layouts","title":"Storage layouts","text":"Layout Application limit Staged boot package Work area Handoff / capability XIAO-module raw QSPI below <code>0xE0000</code> external QSPI offset 0 dedicated internal <code>0xE0000..0xEA000</code> scratch source <code>0x51</code>, flags <code>0x0E</code> Qualified internal-flash target normal <code>0xED000</code> flash limit; top 64 KiB SRAM reserved for application-delta staging shared internal slot, exact start <code>0xE2000</code> the same eleven-page slot; no second flash reservation source <code>0xED</code>, flags <code>0x0A</code> MeshTower V2 microSD normal <code>0xED000</code> limit contiguous <code>/meshcore-ota.mota</code> dynamic internal <code>0xE0000..0xEA000</code> scratch; live image must end by <code>0xE0000</code> source <code>0x53</code>, flags <code>0x09</code> <p>The exact SD target is <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code>. Its normal application FULL and delta updates continue to use the SD file without the bootloader-update scratch restriction. For a bootloader package only, both MeshCore and OTAFIX require a hash-valid live <code>EndF</code> proving the complete running image ends at or below <code>0xE0000</code>. If boot settings carry a nonzero app bank CRC, the recorded bank size must also cover that full EndF-inclusive image and stop by <code>0xE0000</code>; erased or explicitly CRC-disabled settings remain valid. OTAFIX then copies the verified 40 KiB payload from SD into <code>0xE0000..0xEA000</code> and uses the MBR copy operation to replace <code>0xF4000..0xFE000</code>. The application linker remains at <code>0xED000</code>; a future application extending above <code>0xE0000</code> can still use application mOTA but must update its bootloader through local DFU/SWD.</p> <p>The removable SD authorization is fail-closed for both application and bootloader packages. MeshCore directly authenticates one exact signed manifest, requires the streamed copy to remain byte-identical, verifies all leaves/payload/image bytes, and computes a normalized full-container SHA-256 in that same pass (<code>APRV</code> bytes are treated as zero). After syncing <code>APRV</code>, it publishes a 72-byte <code>MOTASDA2</code> record in reset-retained RAM at <code>0x20006008</code>. That record binds purpose/format, first LBA, sector count, total length, card sector count, and the normalized digest. OTAFIX copies, validates, and clears the record before SD access. A card swap/mutation or a power cycle therefore fails closed; there is no general sector-1 ownership inference.</p> <p>For fmt3, MeshCore also writes and readback-verifies a 64-byte <code>MOTASDBL</code> token at <code>0xE0000</code>. That token contains the exact container length and the exact authenticated signed manifest <code>image_hash</code>. OTAFIX requires the same hash in the parsed manifest, streamed payload, and final scratch image. The page is consumed as scratch during success and is not permanently reserved.</p> <p>The first BLM2-capable MeshTower bootloader cannot be delivered to preview.12 through the retained-RAM protocol that preview.12 predates. MeshCore does not write a raw-sector compatibility record because a blank sector is not proof of ownership. Upgrade preview.12 through USB/BLE DFU or SWD. Both fmt2 application and fmt3 bootloader OTA then require the installed BLM2 metadata to match the live SoftDevice/application layout; neither MeshCore nor OTAFIX uses sector 1.</p> <p>The internal path does not change the application's <code>0xED000</code> flash limit or permanently set aside separate app-OTA, boot-package, and flash-scratch regions. Qualified applications do use a dedicated linker that reserves the top 64 KiB of SRAM for hybrid application-delta staging and a retained authorization record. That SRAM is never part of a bootloader-update package. The ordinary bottom-aligned internal flash store holds one container prefix at a time: either an application delta or the complete bootloader package.</p> <p>The exact bootloader container is 41,330 bytes: 365 bytes of signed mOTA metadata, a 40 KiB payload, and the five-byte trailer. Below the normal <code>0xED000</code> store ceiling it bottom-aligns at <code>0xE2000</code>. Admission requires a hash-valid live <code>EndF</code> proving the current application, including its trailer, ends at or before <code>0xE2000</code>. OTAFIX then reads each source window before erasing and compacts the payload forward in place to the page-aligned raw range <code>0xE2000..0xEC000</code>; it verifies every page and the whole image before asking the MBR to copy that image over <code>0xF4000..0xFE000</code>.</p> <p>An ordinary application delta can be smaller or larger than this eleven-page shape. On the qualified profile, a delta larger than one page uses the minimum page-aligned flash prefix ending at <code>0xED000</code> and keeps up to 64 KiB of its logical tail in reset-retained SRAM; its detools workspace must stop at the actual flash-prefix start. A one-page-or-smaller delta stays wholly in flash. In either case the reconstructed application must stop below <code>0xED000</code>. The two package kinds are mutually exclusive because they use the same flash store, and a bootloader package never uses the volatile SRAM suffix.</p> <p>For internal-self-update builds, an absent or corrupt live <code>EndF</code> disables all internal staging before the first erase. The older 608 KiB rescue estimate is unsafe when a normally linked application may extend to <code>0xED000</code>. Builds without this feature retain the legacy rescue behavior.</p>"},{"location":"ota_nrf52_bootloader_update/#internal-flash-target-inventory","title":"Internal-flash target inventory","text":"<p>The release builder consumes the allowlist in <code>tools/mota/nrf52_internal_bootloader_targets.txt</code>. Ten names are also literal PlatformIO environments and are enabled automatically when built directly. The other eleven are release aliases assembled from a base environment plus the lean OTA overlay; build them through <code>build.sh</code>, which passes the same allowlist decision to the common pre-build guard. These lean repeater/bridge targets have no OTA-owned SD/QSPI store and have an exact curated OTAFIX manifest identity:</p> Build target(s) Installed OTAFIX identity Boot target ID <code>Heltec_tower_v2_repeater_lora_ota_no_external_sensors</code> <code>239A0071 / TOWER_V2_OTA</code> <code>1150F50E</code> T096 lean repeater and RS232 bridge <code>239A0071 / T096_DFU</code> <code>42354C85</code> <code>Heltec_t1_repeater_lora_ota_no_external_sensors</code> <code>239A0071 / T1_DFU</code> <code>FC556FFC</code> T114 display and without-display lean repeaters <code>239A0071 / T114_DFU</code> <code>0C3F2902</code> <code>Mesh_pocket_repeater_lora_ota_no_external_sensors</code> <code>239A0071 / MESH_POCKET_OTA</code> <code>059277F4</code> <code>KeepteenLT1_repeater_lora_ota_no_external_sensors</code> <code>239A00B3 / KeepteenLT1_OTA</code> <code>DB2E7B51</code> <code>Minewsemi_me25ls01_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / MX25_DFU</code> <code>026AA982</code> <code>ProMicro_repeater_lora_ota_no_external_sensors</code> <code>239A00B3 / PROM_DFU</code> <code>AF79E8CC</code> <code>t1000e_repeater_lora_ota_no_external_sensors</code> <code>28860057 / T1KE_DFU</code> <code>E6F5F03F</code> <code>ThinkNode_M3_repeater_lora_ota_no_external_sensors</code> <code>239A00DA / TNM3_DFU</code> <code>0CA41DB2</code> <code>RAK_3401_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / 3401_DFU</code> <code>23818A80</code> RAK4631 lean repeater and both lean RS232 bridges <code>239A0029 / 4631_DFU</code> <code>2D0DF000</code> GAT562 30S/Tracker Pro/EVB Pro lean targets <code>239A0029 / GAT562_DFU</code> <code>D50D2D44</code> <code>R1Neo_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / 4631_DFU</code> <code>2D0DF000</code> <code>RAK_WisMesh_Tag_repeater_lora_ota_no_external_sensors</code> <code>239A0029 / RTAG_DFU</code> <code>C72E9C9C</code> <p>Board IDs are not globally unique. For generic targets, the signed hardware ID is the exact NUL-padded 32-byte value <code>NRF_BL_&lt;BOARD_ID&gt;_&lt;DEVICE_NAME&gt;</code>. The wire target is the little-endian first four SHA-256 bytes of all 32 padded bytes. The installed and candidate embedded manifest pairs must match exactly. XIAO retains its deployed <code>XIAO_BL_28860044</code> / <code>XIAO_BL_28860045</code> identity and raw board-ID target.</p> <p>The Python reference builder and release tooling audit these boot targets for duplicates and collisions with application target IDs. Generic image parsing can inspect a future canonical identity, but signing/building a package fails until that exact identity is in the qualified inventory.</p> <p>Earlier GAT562 installations may report the RAK-compatible <code>4631_DFU</code> identity. The installed and candidate identity pair must match exactly, so a remote bootloader update cannot migrate one of those devices to <code>GAT562_DFU</code>. Provision the GAT562-specific OTAFIX bootloader once through USB/BLE DFU or SWD; subsequent signed bootloader mOTA updates use target <code>D50D2D44</code>.</p>"},{"location":"ota_nrf52_bootloader_update/#embedded-continuity-and-version-policy","title":"Embedded continuity and version policy","text":"<p>Every remotely supplied successor retains the legacy 44-byte CRC-valid <code>BLMF</code> v1 record for identity continuity and diagnostics. Immediately after that record is a 32-byte <code>BLM2</code>/<code>SOFT</code> extension. The complete 76-byte envelope is fixed at the final raw-image offset <code>0x9FB4</code>; relocated candidates are refused, while installed legacy-v1 discovery remains a generic diagnostic scan. The extension carries the actual packed bootloader version, SoftDevice family and FWID, application base, layout ABI, and zero compatibility/reserved fields; the legacy whole-image CRC covers the extension too. Scanners first count CRC-valid 44-byte base manifests, then interpret continuity only after one base identity remains. A malformed claimed extension therefore cannot make a duplicate identity disappear, and a sole half-present extension is rejected rather than treated as legacy.</p> <p>MeshCore requires the candidate extension, exact equality between its embedded version and the signed outer mOTA version, and exact agreement with the running SoftDevice family/FWID/application layout. Qualified internal/QSPI paths may bootstrap a CRC-valid installed legacy-v1 image once; the SD path never does and requires local BLM2 provisioning. Once the installed bootloader has BLM2 metadata, the candidate version must be strictly greater. Preview low bytes are <code>1..254</code>, a stable release uses <code>0xFF</code>, and low-byte zero or all-ones values are rejected. There is no remote rollback/migration override; intentional rollback uses USB/BLE DFU or SWD.</p> <p>The legacy <code>no_external_sensors</code> profiles trim selected optional environmental and ranging drivers to preserve flash headroom; they do not generally disable the I2C bus. Reduced RAK3401 and RAK4631 recipes retain INA219, INA226, INA260, and INA3221 voltage/current monitors. Those are entries in the optional sensor table, not the complete set of I2C consumers: the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals where the exact board recipe enables them. RAK3401 retains its compatible RAK12500 I2C and RAK12501/L76K UART GPS paths in sensor slot A. The plain RAK4631 repeater and Serial2 bridge retain GPS. Its RAK12501 path uses Serial1; the explicitly compiled Serial1 RS232 bridge therefore omits the combined GPS provider, including RAK12500, even though RAK12500 itself is I2C rather than UART.</p> <p>The firmware-configured INA3221 and RAK12500 addresses are both <code>0x42</code>. They cannot coexist on the same bus at those addresses. Leave RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use firmware built with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both modules are installed.</p> <p>Boards with onboard external flash are not silently redirected to internal staging. Mesh Solar, Nano G2 Ultra, T-Impulse Plus, ThinkNode M8, T-Echo Lite/Card, MeshTracker X1, and Wio WM1110 have board-specific QSPI hardware and need a separately matched QSPI path where available. Full Companions, other SD/QSPI/ExtraFS roles, Ethernet roles, source-only roles, and unqualified full-sensor roles are excluded from the internal-flash inventory. The exact MeshTower V2 SD role above is separately qualified for its SD path.</p> <p>This internal layout is limited to nRF52840 devices with 1 MiB internal flash, the exact S140 v6/v7 map, and the 40 KiB boot region at <code>0xF4000..0xFE000</code>. nRF52833 and smaller nRF52 parts cannot provide that map plus a non-overlapping 41,330-byte live staging slot, so configuration fails closed instead of selecting smaller or overlapping geometry.</p>"},{"location":"ota_nrf52_bootloader_update/#explicit-install-workflow","title":"Explicit install workflow","text":"<p>The <code>tools/lora_ota/lora_ota.sh</code> and <code>.ps1</code> runners can perform the discovery, transfer, verification and radio cleanup for a bootloader mOTA with <code>--no-install</code>. They detect format 3 automatically and check the destination's bootloader-specific identity/capabilities. They do not install it: the final MID/hash confirmation below remains an explicit operator action. A mixed application/bootloader ZIP requires <code>--zip-member</code>.</p> <p>Check the installed identity and capability marker:</p> <pre><code>ota bootloader\n</code></pre> <p>The response must show a CRC-valid exact identity, ABI 3 or newer, both FULL and INPLACE application codecs (<code>codecs=0x5</code>), and exact flags <code>0x09</code> for MeshTower V2 SD, <code>0x0A</code> for internal shared storage, or <code>0x0E</code> for XIAO QSPI. A bootloader row is visible in <code>ota ls</code>, but it is never autofetched or autoinstalled. Fetch its exact MID, then explicitly arm it:</p> <pre><code>ota pull &lt;MID8&gt; flash\n# wait for ota status to report the download ready\nota bootloader\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Copy both confirmation values from the second <code>ota bootloader</code> response. Ordinary <code>ota install</code> rejects a bootloader package; the bootloader command rejects an application package. The FULL-codec exception exists only for that manual bootloader MID. Ordinary application FULL remains disabled on an internal single-slot node, bootloader autofetch remains off, and a partial bootloader package is not automatically resumed after an application reboot.</p> <p>Before writing <code>APRV</code>, the application authenticates and authorizes the package: exact v3 geometry, trusted Ed25519 signer, signed/embedded identity, one unambiguous capability marker, embedded CRC, sane vectors, complete Merkle/payload/image hashes, storage-specific safe live placement, and the typed MID/hash confirmation. The manifest root and target inside the received manifest must also equal the MID/target that opened the fetch before any store is allocated. On SD, <code>APRV</code>, the retained geometry/container authorization, and the internal signed-image-hash token are published in that order before the reset trigger. OTAFIX consumes that application-written authorization and then independently rechecks the safety/integrity subset: strict v3 structure, canonical identity/capabilities, vectors, full payload SHA, embedded manifest CRC, the applicable live <code>EndF</code>/bank-settings no-overlap geometry, the SD token binding where applicable, scratch readback, and final copy hash. It does not re-run Ed25519, the signer allowlist, Merkle leaves/root, or the typed operator confirmation. Success is reported as <code>blup:C8</code>.</p>"},{"location":"ota_nrf52_bootloader_update/#failure-behavior","title":"Failure behavior","text":"<p>The feature fails closed when the MCU/map is wrong, required valid <code>EndF</code> headroom is insufficient, an unsupported external/ExtraFS role owns the target, the exact installed capability marker is absent or ambiguous, identity cannot be derived unambiguously, or any package check fails. Before the storage-specific scratch/copy step, the application and bootloader are unchanged. OTAFIX consumes the trigger and authorization before its first destructive action, so an interrupted operation cannot automatically retry a partly consumed package. On SD, the retained-RAM authorization is zero-consumed before media access; <code>APRV</code> and the fmt3 flash token may persist but are inert without a new explicit authenticated re-arm and reset trigger. No SD raw-sector handoff is created or consumed. Use USB/BLE DFU or SWD for initial provisioning and local recovery.</p> <p>For XIAO and ordinary external-QSPI details, see nRF52 repeater LoRa OTA with external QSPI.</p>"},{"location":"ota_nrf52_qspi/","title":"nRF52 repeater LoRa OTA with external QSPI","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>Selected nRF52840 repeater builds use their dedicated external QSPI NOR flash as a raw LoRa OTA staging device. This removes the internal-flash staging conflict: the complete <code>.mota</code> stays off-chip, and the bootloader can use the entire internal application region while it installs either a full image or an in-place delta.</p> <p>This is a matched application-and-bootloader feature. A board merely having an nRF52840, free RAM, or pins named QSPI is not enough. Both halves must use the exact flash wiring, and <code>ota self</code> must confirm the store and bootloader before an update is downloaded.</p>"},{"location":"ota_nrf52_qspi/#supported-repeater-families","title":"Supported repeater families","text":"<p>QSPI staging is enabled only for explicitly matched repeater-role environments (and RS232 bridge variants that directly inherit one of those repeater targets) on these currently matched families:</p> <ul> <li>Seeed XIAO nRF52840 and XIAO nRF52840 Sense modules, including the   <code>Xiao_nrf52</code>, SolarXiao 30S/33S, and XIAO-module Ikoka handheld, Nano, and   Stick repeaters</li> <li>original LilyGo T-Echo</li> <li>Elecrow ThinkNode M1 and M6</li> <li>Seeed Wio Tracker L1</li> <li>Seeed SenseCAP Solar Node P1</li> <li>RAK4631 with a RAK15001 in WisBlock sensor slot C, using the dedicated   <code>RAK_4631_repeater_rak15001_slot_c_lora_ota</code> application and matching   <code>wiscore_rak4631_board_rak15001_slot_c</code> OTAFIX bootloader</li> <li>RAK4631 with an externally wired Winbond W25Q16JV breakout on RAK19007,   using <code>RAK_4631_repeater_w25q16_lora_ota</code></li> <li>RAK3401 with its RAK13302 1 W radio and the same externally wired W25Q16JV   breakout on RAK19007, using   <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code></li> </ul> <p>Heltec T114 is intentionally not in this list. Its public V1, V2.0, and V2.1 schematics show U9 (MX25R1635F) as an optional QSPI footprint, so standard T114 application and bootloader targets do not assume that external NOR is populated.</p> <p>The XIAO-module derivatives use the matching XIAO or XIAO Sense OTAFIX bootloader shown by the module's <code>INFO_UF2.TXT</code>. Do not substitute a similar bootloader for a board with different QSPI pins. For example, the T-Echo Card and T-Echo Lite have different flash wiring and are not enabled by the original T-Echo target.</p> <p>Companion builds are intentionally excluded. Some companion targets use the same external QSPI as a LittleFS message/data store, where raw OTA staging would corrupt the filesystem; other companions simply do not assign that chip to OTA. Room-server, sensor, and KISS roles are unchanged. Raw QSPI OTA is scoped to the explicitly matched repeater-derived environments.</p>"},{"location":"ota_nrf52_qspi/#rak15001-placement-and-module-conflicts","title":"RAK15001 placement and module conflicts","text":"<p>RAK15001 is a 2 MiB GD25Q16C standard SPI module, not a quad-I/O flash. The dedicated RAK4631 target uses the nRF52840 QSPI peripheral in its single-data-line FAST_READ/page-program modes at 8 MHz and accepts only the module's exact <code>C8 40 15</code> JEDEC ID. <code>ota self</code> reports <code>QSPI store:2048K</code> only when the expected module responds. An empty slot or a different SPI device reports <code>QSPI store:ERR 0K</code>, and install is refused.</p> <p>The module is electrically usable in sensor slot A-D because those slots share the SPI signals and RAK15001 has onboard 10 kOhm pull-ups on WP# and HOLD#. The supported MeshCore/OTAFIX combination nevertheless requires slot C. It is the placement that remains safe when a RAK12501 GNSS is fitted in either of its supported slots, A or D: slot C avoids the GNSS PPS/reset nets on IO1/IO2 and IO5/IO6. In particular, GPS in A plus flash in B would share IO1/IO2 through the modules' auxiliary pins.</p> <p>Only one device that uses the shared WisBlock SPI chip-select may be fitted. Do not combine this target with RAK13800 Ethernet, RAK15002 SD, or another SPI module. RAK13800 and RAK15001 cannot coexist because they use the same SPI chip-select. Update a RAK13800 Ethernet build locally over USB using the release's Manual UF2 or Serial DFU (.zip) download; it cannot use this RAK15001 LoRa-OTA staging target.</p> <p>RAK3401 with RAK13302 remains incompatible with RAK15001. The 1 W radio uses the same WisBlock SPI clock/data pins and the same chip-select as RAK15001. Firmware cannot independently select or detect those two chips, so a stock RAK3401 + RAK15001 assembly cannot provide reliable OTA staging without a hardware chip-select rework. This restriction does not apply to the separate-CS W25Q16 wiring below.</p> <p></p>"},{"location":"ota_nrf52_qspi/#one-w25q16-wiring-for-rak4631-or-rak3401-rak13302","title":"One W25Q16 wiring for RAK4631 or RAK3401 + RAK13302","text":"<p>An external Winbond W25Q16JV breakout can remain attached to a RAK19007 while the core is changed between RAK4631 and RAK3401 + RAK13302. It shares only the WisBlock SPI clock/data nets and has its own chip-select on AIN1:</p> W25Q16 breakout RAK19007 connection nRF52840 / Arduino pin <code>CLK</code> IO connector pin 26, <code>SPI_CLK</code> P0.03 / <code>3</code> <code>DO</code> / MISO IO connector pin 27, <code>SPI_MISO</code> P0.29 / <code>29</code> <code>DI</code> / MOSI IO connector pin 28, <code>SPI_MOSI</code> P0.30 / <code>30</code> <code>CS</code> J11 <code>AIN1</code> P0.31 / <code>31</code> <code>VCC</code> J12 <code>VDD</code> regulated 3.3 V <code>GND</code> J12 <code>GND</code> ground <p>Fit a physical approximately 10 kOhm pull-up from <code>CS</code> to J12 <code>VDD</code>. That keeps the flash deselected during reset, bootloader entry, and a core-module swap. Power the breakout only from J12 <code>VDD</code>; never use J11 <code>VBAT</code>, which can exceed the flash's supply rating. The six-pin breakout does not expose WP#/IO2 or HOLD#/IO3; do not add nRF IO2/IO3 wiring. A breakout with an onboard power LED works, but that LED draws continuously and is undesirable for low-power or solar operation.</p> <p>This arrangement consumes no WisBlock sensor slot. However, <code>SPI_CLK</code>, <code>SPI_MISO</code>, and <code>SPI_MOSI</code> are not available on the easy 2.54 mm J10/J11/J12 headers. Those three signals require a short underside-pad tap or a suitable IO-connector interposer at pins 26-28. J11 and J12 alone are not sufficient.</p> <p>GPS remains supported in sensor slot A. RAK12500 uses I2C, while RAK12501/L76K uses UART plus its auxiliary control signals; neither uses the shared SPI clock/data bus. On RAK4631 the built-in SX1262 has a separate private SPI bus. On RAK3401 the RAK13302 and flash share clock/data, but have independent chip-selects: RAK13302 NSS is P0.26 and flash CS is P0.31. The matched firmware holds the radio NSS high while it temporarily hands the bus to the flash, then restores the radio SPI interface.</p> <p>The breakout target accepts only a 2 MiB W25Q16 with JEDEC ID <code>EF 40 15</code> and runs it at 8 MHz in standard single-data-line SPI mode. A substituted W25Q32, W25Q64, or W25Q128 fails closed instead of being treated as the OTA store. Use the complete application/bootloader identity row that matches the fitted core:</p> Core and radio PlatformIO environment MOTA hardware identity OTAFIX board / DFU device name RAK4631 built-in SX1262 <code>RAK_4631_repeater_w25q16_lora_ota</code> <code>RAK4631_W25Q16</code> <code>wiscore_rak4631_w25q16</code> / <code>4631_W25Q16_DFU</code> RAK3401 + RAK13302 1 W <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code> <code>RAK3401_RAK13302_W25Q16</code> <code>wiscore_rak3401_rak13302_w25q16</code> / <code>3401_W25Q16_DFU</code> <p>The physical flash wiring is identical, but the two application and bootloader pairs are not interchangeable.</p>"},{"location":"ota_nrf52_qspi/#one-time-prerequisite","title":"One-time prerequisite","text":"<p>Install a QSPI-capable OTAFIX 2.4.1 preview.9 or newer bootloader for the exact board from the OTAFIX releases before using LoRa OTA. The release notes must explicitly list that board's QSPI mode. Also install the SoftDevice version expected by that target. The application refuses the install handoff when the bootloader does not advertise QSPI support.</p> <p>For the external W25Q16 option, install the corresponding bootloader once before installing its MeshCore application: <code>wiscore_rak4631_w25q16</code> (<code>DEVICE_NAME=4631_W25Q16_DFU</code>) for RAK4631, or <code>wiscore_rak3401_rak13302_w25q16</code> (<code>DEVICE_NAME=3401_W25Q16_DFU</code>) for RAK3401 plus RAK13302. Use only a release that explicitly names that exact pairing. Do not substitute the RAK15001 bootloader or swap the two W25Q16 bootloaders merely because the base-board wiring is the same.</p> <p>For the first migration from the ordinary <code>wiscore_rak4631_board</code> bootloader to <code>wiscore_rak4631_board_rak15001_slot_c</code>, use Nordic serial DFU or a compatible BLE DFU client with the exact slot-C OTAFIX combined bootloader + SoftDevice DFU package (or use SWD), then reinstall the slot-C MeshCore application. The release filename has this form:</p> <pre><code>wiscore_rak4631_board_rak15001_slot_c_bootloader-&lt;OTAFIX-version&gt;_s140_6.1.1.zip\n</code></pre> <p>Do not copy the slot-C bootloader-update UF2 onto the stock UF2 drive. The stock loader is bound to <code>DEVICE_NAME=4631_DFU</code>, while the slot-C image is bound to <code>4631_15001C_DFU</code>, so that UF2 is intentionally rejected. After the one-time DFU/SWD migration, later canonical slot-C bootloader UF2 files work normally. The combined OTAFIX package above is not the MeshCore application's Serial DFU <code>.zip</code>; an application package does not migrate the bootloader.</p> <p>After installing the repeater application, check:</p> <pre><code>get bootloader.ver\nota self\nota status\nota qspi\n</code></pre> <p>A ready RAK15001 target reports all of the following:</p> <pre><code>QSPI store:2048K\nbootloader: QSPI apply OK\nbl:QSPI\nQSPI jedec=C84015 size=2048K sr1=00 stage=jedec\n</code></pre> <p>A ready external W25Q16 target instead identifies the Winbond part:</p> <pre><code>QSPI store:2048K\nbootloader: QSPI apply OK\nbl:QSPI\nQSPI jedec=EF4015 size=2048K sr1=00 stage=jedec\n</code></pre> <p>Other supported boards can report a capacity different from 2048K; the RAK15001 and W25Q16 targets must report exactly 2048K and their respective exact JEDEC IDs. <code>QSPI store:ERR 0K</code>, <code>NO QSPI</code>, or <code>bl:NO-QSPI</code> means the flash wiring, flash power, chip-select pull-up, application, or bootloader does not match. Do not start an install in that state.</p> <p><code>ota qspi</code> is a read-only diagnostic probe available on QSPI OTA builds. It reports the exact JEDEC ID, status-register byte, last store stage, and the first latched storage error. Run it after an immediate <code>storage error</code> before starting another pull; later capacity probes preserve that failure detail.</p>"},{"location":"ota_nrf52_qspi/#capacity-and-package-types","title":"Capacity and package types","text":"<p>The store reads the JEDEC capacity at runtime and accepts supported 1 MiB through 16 MiB devices using 24-bit addressing. QSPI capacity is not the final firmware limit. The reconstructed application, including its 56-byte <code>EndF</code> trailer, must fit its build's linked application region:</p> SoftDevice layout Application region Maximum image S140 v7, boot-update-capable XIAO module <code>0x27000..0xE0000</code> <code>0xB9000</code> (757,760 bytes) S140 v7, app base <code>0x27000</code> <code>0x27000..0xED000</code> <code>0xC6000</code> (811,008 bytes) S140 v6, app base <code>0x26000</code> <code>0x26000..0xED000</code> <code>0xC7000</code> (815,104 bytes) <p>The XIAO limit is deliberately 52 KiB smaller. Its linker and post-link record cap every ordinary application at <code>0xE0000</code>; OTAFIX reserves <code>0xE0000..0xEA000</code> as a 40 KiB self-update scratch bank, with the remaining gap left unused before InternalFS. Full and delta application packages for these targets derive their effective application end from that <code>0xE0000</code> record and are rejected if their reconstructed image or detools geometry crosses it.</p> <p>A full package needs only the new raw <code>firmware.hex</code> or non-merged application image. An in-place delta still needs the exact image currently running. The automation uses a conservative <code>0xC6000</code> detools workspace for external nRF52 staging so one package setting is safe for both layouts.</p> <p>For online automation, QSPI is detected from <code>ota self</code> or <code>ota status</code>. For offline preparation, identify it explicitly:</p> <pre><code>./tools/lora_ota/lora_ota.sh ./release.zip target-name \\\n  --prepare-only \\\n  --platform nrf52 \\\n  --nrf-qspi \\\n  --target-id 12345678 \\\n  --target-hw Xiao_nrf52\n</code></pre> <p>Use the real target ID and hardware identity from the destination. A ready full <code>.mota</code> normally uses that target ID for discovery and routing. An operator can deliberately override the routing target for a role change, so <code>target_id</code> is not an apply-time safety assertion; the destination still enforces the package's hardware identity before approval.</p>"},{"location":"ota_nrf52_qspi/#explicit-xiao-bootloader-updates-over-lora","title":"Explicit XIAO bootloader updates over LoRa","text":"<p>This section documents the deployed XIAO raw-QSPI layout. Curated nRF52840 targets without external staging use a separate internal-flash layout with the same explicit operator safety model; see nRF52 bootloader updates over LoRa.</p> <p>Bootloader delivery is available only when all of these are already true:</p> <ul> <li>the application is an <code>OTA_QSPI_BOOTLOADER_UPDATE</code> XIAO-module repeater build   linked below <code>0xE0000</code>;</li> <li><code>ota bootloader</code> shows a CRC-valid installed <code>XIAO_DFU</code> embedded identity for   board ID <code>28860044</code> (base) or <code>28860045</code> (Sense);</li> <li>the installed OTAFIX marker reports ABI 3 or newer and both QSPI (<code>0x04</code>) and   boot-update (<code>0x08</code>) capability bits;</li> <li>the package is the exact signed v3/40-KiB/1-KiB-block profile for that board,   and its signer is already in <code>ota key</code>'s trusted allowlist.</li> </ul> <p>This is not part of normal automation. Bootloader catalog rows are labelled <code>bootloader</code>; even a capable node never autofetches or autoinstalls them, and ordinary <code>ota install</code> rejects them in every application backend. The <code>tools/lora_ota</code> deployment runner also refuses v3 packages. Fetch and arm one only with the explicit flow:</p> <pre><code>ota ls\nota pull &lt;MID8&gt; flash\n# wait for ota status to report the same bootloader download as ready\nota bootloader\n# copy the exact mid= and hash= values printed above\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>The pull command is only transport intent; it does not authorize an install. The final command must reproduce both the complete staged manifest ID and the first eight bytes of its signed image hash. Before approval the application again checks package/root/payload/image hashes, Ed25519 signature and trusted allowlist, exact signed <code>XIAO_BL_...</code> ID, installed and incoming embedded   manifest/CRC/name/board identity, vector table, ABI-3 QSPI+boot-update marker,   and the adjacent CRC-covered <code>BLM2</code>/<code>SOFT</code> continuity extension at the exact   final-image offset <code>0x9FB4</code>. The embedded   boot version must equal the signed outer package version, the SoftDevice   family/FWID/application base/layout ABI must match the running platform, and   a successor to installed BLM2 must be strictly newer. Low-byte-zero and   all-ones versions are invalid. Remote rollback is refused; use local DFU/SWD.</p> <p>After the reply drains, GPREGRET <code>0x6B</code> and GPREGRET2 <code>0x51</code> enter the special OTAFIX path. <code>APRV</code> carries the app's signature/allowlist and explicit operator authorization decision. OTAFIX independently rechecks the strict structure, identity/capabilities, vectors, payload SHA, embedded CRC, and copy hashes before using the reserved scratch bank to replace its own <code>0xF4000..0xFE000</code> region. The running application remains preserved; a rejected candidate returns to it unchanged. Post-reboot <code>ota status</code> reports bootloader-update diagnostics as <code>blup:C0</code> to <code>blup:CF</code> (<code>blup:C8</code> is success), separately from ordinary application <code>blrc</code>.</p> <p>This feature cannot update a stock or old bootloader that lacks the capability marker: perform the first exact-board combined bootloader+SoftDevice migration over USB/BLE DFU or SWD. Do not attempt to bootstrap it with a v3 package.</p>"},{"location":"ota_nrf52_qspi/#storage-ownership-and-recovery","title":"Storage ownership and recovery","text":"<p>The QSPI store is raw, not a file inside LittleFS. It owns the flash from offset zero, erases 4 KiB sectors as blocks arrive, writes data before progress metadata, and verifies every programmed page. A previously interrupted download is reopened only when its header and trailer are valid; every claimed block is re-hashed before it is trusted. Between a probe, transfer operation, or checkpoint, firmware puts the NOR into deep power-down, deactivates the nRF QSPI peripheral, and turns off a board-provided flash power-enable pin. The next operation powers the chip, shifts the NOR's <code>0xAB</code> wake command over GPIO, then activates the nRF QSPI peripheral and identifies the flash. Waking it before peripheral activation is required because a flash in deep power-down ignores the activation traffic itself. Merely running <code>ota self</code> therefore does not leave QSPI drawing active-mode current or prevent the following operation from reactivating it.</p> <p>Installing a QSPI repeater build over a former companion build therefore repurposes the external flash and destroys companion filesystem data as OTA sectors are written. Back up anything important first. Returning to a companion build may require formatting its external data store.</p> <p>Before changing internal application flash, the application verifies package integrity, hardware identity, signature policy, and bootloader capabilities. The target ID selects discovery/fetch routing and can be deliberately overridden; it is not a second hardware gate. The bootloader then verifies a full payload before its first application erase. For a delta, the application rejects invalid detools geometry before approval and the bootloader independently repeats the base and geometry checks before applying it. It clears the one-shot approval marker before invalidating the running image. If power is lost after application writes begin, the bank remains invalid and OTAFIX enters USB/BLE recovery rather than booting a partial image.</p> <p>See Easy firmware updates over LoRa for the transfer commands and the OTA protocol for the container and handoff details.</p>"},{"location":"ota_protocol/","title":"MeshCore OTA - <code>.mota</code> container &amp; LoRa protocol","text":"<p>This is the single source of truth for MeshCore's over-the-air firmware update system (\"mOTA\"). It is written for developers who want to implement an interoperable peer (server, fetcher, relay, or host tool) in another codebase or project. Everything below is implemented in this repository and covered by host, simulation, build, or hardware tests as noted in the relevant section. Hardware qualification is target- and chain-specific; do not infer it from implementation alone. Where a section names a source file, that file is the authoritative reference for byte-level details.</p> <p>Just want to update your node? See the plain-language OTA user guide - this document is the technical/wire specification.</p> <p>Design goals</p> <ul> <li>Distribute firmware over LoRa as a self-verifying, resumable, single-source block transfer that   survives reboots and never auto-applies without explicit consent.</li> <li>Trustless mesh relay: repeaters may forward packets while the source alone serves firmware data;   integrity is content-addressed   against a signed merkle root, so a relay need not be trusted and never needs the signing keys.</li> <li>Primary while transferring: periodic discovery stays at background priority, but manifest, block,   data, and proof packets for an active fetch use primary queue priority at every relay hop.</li> <li>Portable: the engine (<code>src/helpers/ota/OtaManager</code>) is Arduino/radio/crypto-free and host-testable,   so the same logic drives a device, a simulation, or a third-party implementation.</li> </ul> <p>Source map (all under <code>src/helpers/ota/</code> unless noted)</p> Concern File Constants, enums, flags <code>OtaFormat.h</code> Container/manifest parse <code>MotaContainer.{h,cpp}</code> Merkle tree + proofs <code>MerkleTree.{h,cpp}</code> EndF self-identity <code>FirmwareInfo.{h,cpp}</code> Wire message codec <code>OtaProtocol.{h,cpp}</code> Session engine (serve+fetch+discovery) <code>OtaManager.{h,cpp}</code> Multi-mota / folder relay <code>OtaSource.h</code>, <code>MotaSourceSerial.{h,cpp}</code>, <code>MotaSeederProto.h</code> Staging stores <code>OtaStore.h</code>, <code>OtaStoreFlashNrf52.*</code>, <code>OtaStoreFlashEsp32.*</code> Apply <code>OtaApply.*</code>, bootloader <code>Adafruit_nRF52_Bootloader_OTAFIX</code> Device glue (CLI/context) <code>OtaCli.cpp</code>, <code>OtaContext.h</code> Host tooling <code>motatool</code> (standalone Rust CLI: build/verify/inspect/serve); <code>tools/mota/</code> (Python reference lib <code>motalib.py</code> + build/test glue)"},{"location":"ota_protocol/#1-conventions","title":"1. Conventions","text":"<ul> <li>Endianness: all multi-byte integers are little-endian unless stated.</li> <li>Hashes (multihash): the hash family is declared once per manifest via <code>hash_algo</code> =   <code>0x12</code> = SHA-256 (the multihash code for sha2-256).   Truncations used:</li> <li><code>sha2-256:4</code> - first 4 bytes of the SHA-256 digest. Merkle leaves, internal nodes, root, proofs,     <code>manifest_id</code>, and the discovery <code>set_digest</code>.</li> <li><code>sha2-256:8</code> - first 8 bytes. Base-firmware identity (<code>base_hash</code>, <code>EndF.body_hash</code>).</li> <li><code>sha2-256:32</code> - full digest. The image security anchor (<code>image_hash</code>).   Digests are stored bare (just the truncated bytes); the family is implied by <code>hash_algo</code>.</li> <li>Signatures: Ed25519 (RFC 8032), 64-byte detached signature, 32-byte public key.</li> </ul> <p>Reference constants (<code>OtaFormat.h</code>):</p> Name Value ASCII / note Container <code>MAGIC</code> <code>6D 4F 54 41</code> <code>mOTA</code> Container <code>TRAILER</code> <code>76 6B 34 39 36</code> <code>vk496</code> <code>EndF</code> marker <code>45 6E 64 46</code> <code>EndF</code> <code>hash_algo</code> (sha2-256) <code>0x12</code> multihash code application <code>format_ver</code> <code>0x02</code> ordinary full/delta application package bootloader <code>format_ver</code> <code>0x03</code> privileged exact-identity nRF52 bootloader package only <code>approval</code> = not approved <code>FF FF FF FF</code> erased NOR word <code>approval</code> = approved <code>41 50 52 56</code> <code>APRV</code> <code>MFLAG_FULL</code> <code>0x01</code> flags bit0 <code>MFLAG_SIGNED</code> <code>0x02</code> flags bit1 <code>MFLAG_BOOTLOADER</code> <code>0x04</code> flags bit2; valid only in the exact v3 bootloader profile <code>CODEC_FULL</code> / <code>_SEQUENTIAL</code> / <code>_INPLACE</code> <code>0</code> / <code>1</code> / <code>2</code> Section 5 <code>PAYLOAD_TYPE_OTA</code> <code>0x0C</code> MeshCore packet type (<code>src/Packet.h</code>) <code>MAX_PACKET_PAYLOAD</code> <code>184</code> usable bytes per packet (<code>src/MeshCore.h</code>) Default application block size <code>2048</code> <code>block_size_log2 = 0x0B</code>; deployed 1 KiB application packages remain accepted Bootloader-package block size <code>1024</code> fixed <code>block_size_log2 = 0x0A</code> for format 3 OTA discovery TX priority <code>250</code> background (<code>OTA_TX_PRIORITY</code>, <code>src/Mesh.h</code>) OTA active-transfer TX priority <code>0</code> primary (<code>OTA_TRANSFER_TX_PRIORITY</code>, <code>src/Mesh.h</code>) <p>Current application firmware publishes its receive/reassembly ceiling as the compact <code>maxblk:2048</code> field near the front of both <code>ota status</code> and <code>ota self</code>. Keeping the field ahead of variable diagnostics ensures it survives the 160-byte remote-admin reply limit. Host updaters must treat an absent field as the deployed legacy capability (<code>1024</code>), reject a ready package whose manifest block size exceeds that capability, and use the reported size when turning a raw firmware image into a new application package. This capability does not change the format-3 bootloader package's fixed 1 KiB geometry.</p>"},{"location":"ota_protocol/#2-firmware-image-the-endf-trailer","title":"2. Firmware image &amp; the <code>EndF</code> trailer","text":"<p>Every OTA-capable build appends a fixed 56-byte <code>EndF</code> trailer to its flashed image so a running node can discover its own size and self-describing identity on any MCU (no linker symbols needed). Every field is always present at a constant offset. Implemented by <code>FirmwareInfo.cpp</code>; appended at build time by <code>tools/mota/pio_endf.py</code> (post-build hook).</p> <pre><code>flashed image = BODY (image bytes) || EndF trailer\nEndF trailer (fixed 56 bytes):\n  off 0   4   \"EndF\"        45 6E 64 46\n  off 4   4   body_len      uint32 LE - length of BODY (excludes the whole trailer)\n  off 8   8   body_hash     sha2-256:8 of BODY\n  off 16  4   fw_version    uint32 LE, packed MAJOR&lt;&lt;24|MINOR&lt;&lt;16|PATCH&lt;&lt;8|pre  (0 = unknown)\n  off 20  4   target_id     uint32 LE - sha2-256:4(pio_env): hardware + role + partition (fetch routing)\n  off 24  32  hw_id         NUL-padded ASCII hardware tag (brick-safety), e.g. \"RAK4631\" (\"\" = unknown)\n</code></pre> <ul> <li>Self-describing identity. <code>pio_endf.py</code> uses <code>build.sh</code>'s <code>MOTA_TARGET_ID</code> when present (required for   virtual LoRa-OTA build names), otherwise it computes <code>target_id</code> from the PlatformIO env name. It reads   <code>hw_id</code> from <code>MOTA_HW_ID</code> and <code>fw_version</code>   from <code>FIRMWARE_VERSION</code>. The device reads them back (<code>ota_self_firmware()</code>), so a node's advertised   identity is correct regardless of how it was built - and the packaging tool reads them straight from a raw   <code>.bin</code> (no <code>--target-env</code>/<code>--fw-version</code> flags, no reliance on filenames; Section 9, Section 13). A dev build with no   dotted version simply carries <code>fw_version = 0</code> / empty <code>hw_id</code> (= unknown) - still a full 56-byte trailer.</li> <li>Size discovery: scan flash from the partition top downward for the <code>EndF</code> marker; the byte before it   is the last BODY byte (the trailer is always 56 bytes). See <code>ota_self_firmware()</code>.</li> <li>Delta base matching: a node's <code>body_hash</code> is read directly from its own <code>EndF</code>; a delta's <code>base_hash</code>   (Section 5) must equal it. <code>body_hash</code> is over BODY only.</li> <li>No circularity: <code>EndF</code> hashes only the BODY, never itself.</li> </ul> <p>The \"reconstructed image\" referenced by the manifest is the full <code>BODY || EndF</code> (what gets flashed).</p>"},{"location":"ota_protocol/#esp32-application-slot-profiles","title":"ESP32 application-slot profiles","text":"<p>ESP32 Companion firmware is exempt from the portable-slot limit. When an exact Full recipe exists, one expanded-partition image supplies USB, BLE, WiFi, source-only LoRa OTA, and persistent USB logging instead of separate transport artifacts. A small set of high-capacity, non-PSRAM classic ESP32 companions use 100 contacts, 8 group channels, and a 16-frame offline queue in that combined image to preserve internal-DRAM headroom. MQTT observers and ESP-NOW bridges always use FULL builds because fitting them into the legacy slot would require removing CLI and role features. Except for those FULL roles and the ESP32-C6 case below, non-companion ESP32 artifacts, including room, sensor, and repeater roles, must fit the legacy slot from <code>0x10000</code> up to <code>0x150000</code> (<code>0x140000</code>, 1,310,720 bytes), including the 56-byte <code>EndF</code> trailer. The build checks both that limit and the target's actual app partition. The ESP32-C6 <code>no_external_sensors</code> OTA siblings are the narrow exception: the Arduino 3.x WiFi runtime cannot fit that cross-family ceiling, so those images retain their established target-specific 1920 KiB or larger A/B app layout and are checked against the actual app partition. For standalone ESP32 and nRF52 repeater and room-server roles that need a lean staging profile, <code>build.sh</code> also exposes an explicit <code>*_lora_ota_no_external_sensors</code> artifact: the ordinary role remains sensor-enabled, while that sibling trims selected optional environmental/ranging drivers for LoRa distribution. SolarXiao 30S and 33S use matched external QSPI staging, so their ordinary full-sensor repeater and room-server images are already install-capable and no redundant lean sibling is generated. Integrated GPS and other board-native telemetry remain enabled where the target selects the GPS-preserving lean profile. The legacy suffix describes a driver trim, not removal of the generic I2C bus. Reduced RAK3401 and RAK4631 profiles retain INA219, INA226, INA260, and INA3221 voltage/current monitors. These are retained optional-sensor-table drivers, not the only I2C consumers: SSD1306 display, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals where selected by the board recipe. The RAK3401 OTA repeater also retains RAK12500 I2C and RAK12501/L76K UART GPS support; install either GPS module in sensor slot A because slot D conflicts with the RAK13302 radio's BUSY/DIO1 lines. The plain RAK4631 OTA repeater and its Serial2 bridge retain GPS. RAK12501 uses Serial1. Its explicitly compiled Serial1 bridge therefore omits the combined GPS provider, including RAK12500, even though RAK12500 itself does not use the UART.</p> <p>The firmware-configured INA3221 address and RAK12500 address are both <code>0x42</code>, so those devices cannot share one bus at those addresses. Keep RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use firmware built with <code>-DTELEM_INA3221_ADDRESS=0x43</code> when both are installed.</p> <p>ESP32 siblings retain the compact browser WiFi updater and use up to 254 neighbors. Internal-DRAM-constrained targets use 50 as recorded in the artifact capability manifest; see ESP32 memory budget. RP2040 and STM32 targets are not offered because those platforms do not yet have a safe bootloader/apply path.</p> <p>nRF52 LoRa-OTA siblings use size optimization rather than the Adafruit platform's default <code>-Ofast</code>. This keeps the runtime software Ed25519 fallback from being expanded into tens of kilobytes of repeated curve arithmetic while retaining CC310 hardware crypto, hardware RNG mixing, telemetry history, and board-native features.</p> <p>WiFi-heavy non-companion roles are not reduced to fit the legacy application slot. <code>build.sh</code> automatically promotes every ESP32 MQTT observer and ESP-NOW bridge to the expanded FULL partition profile. These artifacts retain the complete role CLI, WebConfig where supported, display and optional sensor support, full timezone and TLS behavior, and the board's normal power-management implementation. The compact CLI is not compiled into any build. Ordinary repeater and room-server builds remain sensor-enabled; only explicitly named <code>*_lora_ota_no_external_sensors</code> siblings trim selected optional environmental/ranging drivers for LoRa distribution, and those siblings retain the complete CLI and target-declared I2C peripherals.</p> <p>MQTT observer radio and bridge preferences use verified temporary files plus a recoverable backup. A reset during a settings save restores the last committed common preference image or publishes the completed new image; it does not leave a partially written <code>/com_prefs</code> file to fail on the next boot. A truncated legacy image is rejected before any partial radio or string fields are applied, then rewritten from safe defaults.</p> <p>Option 3 in <code>build.sh</code> emits one <code>*-full-usb-wifi-ota-*</code> ESP32 artifact for each FULL-capable non-companion hardware/role that has a matching MQTT environment. It compiles USB packet logging and direct WiFi MQTT together. A <code>*-full-logging-ota-*</code> fallback is emitted only when there is no MQTT sibling; ordinary non-OTA roles compile runtime USB logging into their canonical image, so separate standard-logging artifacts are not emitted. Non-MQTT FULL twins are also skipped for covered ESP32 roles. MQTT observers and ESP-NOW bridges are emitted only with expanded FULL partitions. Menu option 8, or <code>build-full-esp32-firmwares</code>, builds the unified profiles plus necessary fallbacks. Menu option 9, or <code>build-full-esp32-logging-firmwares</code>, builds only those fallbacks. FULL builds restore WebConfig, display support, optional external sensors, and the full role CLI and feature set, full ElegantOTA where that target declares the required library, and LoRa OTA for every included role, including room servers, sensors, observers, and bridges. They use expanded A/B partition tables: 1984 KiB application slots on 4 MiB boards and the framework's larger dual-OTA tables on 8 MiB and 16 MiB boards. Explicit <code>*_lora_ota_no_external_sensors</code> targets are not duplicated; their ordinary repeater or room-server build is the FULL, sensor-enabled counterpart. The <code>*-full-usb-wifi-ota-*</code> profile enables USB packet logging and MQTT, with a persistent <code>logging.output</code> selector; its verbose internal debug remains off. The fallback <code>*-full-logging-ota-*</code> profile enables USB debug and packet logging and has no MQTT target. Install a matching <code>*-full-usb-wifi-ota-*-merged.bin</code> or <code>*-full-logging-ota-*-merged.bin</code> over USB once to write the expanded partition table. After that, its matching non-merged FULL application image can be installed through USB, WiFi OTA, or LoRa OTA. Do not install a non-merged FULL image onto a node that still has its old partition table.</p> <p>Implementer note: the bootloader (and any non-Arduino consumer) MUST locate the body extent by scanning for <code>EndF</code>, never by trusting a stored size - see the bootloader contract in Section 12.</p>"},{"location":"ota_protocol/#3-the-mota-container","title":"3. The <code>.mota</code> container","text":"<p>The distributed form (host-built, wire-transferred). Parsed by <code>mota_parse()</code> in <code>MotaContainer.cpp</code>.</p> <pre><code>off            size   field\n0              4      MAGIC = 6D 4F 54 41\n4              4      MOTA_TOTAL_SIZE  uint32 LE - total container bytes (incl. manifest, leaves[],\n                                       payload, trailer). Lets a node pre-reserve staging and compute\n                                       write_start = staging_region_end - MOTA_TOTAL_SIZE.\n8              M      MANIFEST         (Section 4; M = 197 fixed + leaves[], 4*BC; no length field - BC from payload_size)\n8 + M          P      PAYLOAD          (payload_size bytes; delta or full image)\n8 + M + P      5      TRAILER = 76 6B 34 39 36\n</code></pre> <p><code>MOTA_TOTAL_SIZE = 4 + 4 + M + P + 5</code>. The manifest <code>M</code> includes <code>leaves[]</code>; the manifest-minus-leaves prefix (<code>mfl</code>, sent over the wire as <code>OTA_MANIFEST</code>) is <code>[8, leaves_off)</code>.</p> <p>Staged (in-flash) form. Written bottom-aligned so <code>TRAILER</code> ends at <code>staging_region_end</code>. Identical bytes, except the device mutates two regions in place (both NOR-safe, no re-erase): the <code>leaves[]</code> slots (filled as blocks arrive - Section 7) and the 4-byte <code>approval</code> field (on owner consent - Section 4.2). Everything else is immutable.</p>"},{"location":"ota_protocol/#4-the-manifest","title":"4. The manifest","text":"<p>Fixed layout. Every field sits at a constant offset and is always present - <code>base_hash</code>, <code>signer_pubkey</code> and <code>signature</code> are zero-filled when not applicable (a full image / an unsigned container). Only <code>leaves[]</code> is variable (one 4-byte hash per block). So the manifest-minus-leaves (<code>mfl</code>) is always 197 bytes and the parser is plain offset reads - no conditionals. Parsed by <code>mota_parse_manifest()</code>.</p> <pre><code>off  size   field            notes\n0    1      format_ver       = 0x02 application, or 0x03 privileged bootloader package\n1    1      flags            bit0 FULL; bit1 SIGNED; bit2 BOOTLOADER; bits3-7 reserved 0\n2    1      hash_algo        0x12 = sha2-256\n3    4      target_id        device/arch/role discriminator (Section 9)\n7    4      fw_version       MAJOR&lt;&lt;24 | MINOR&lt;&lt;16 | PATCH&lt;&lt;8 | pre   (comparable uint32)\n11   4      image_size       size of the reconstructed image (BODY||EndF)\n15   4      payload_size     PAYLOAD bytes in this container\n19   1      block_size_log2  e.g. 0x0B = 2048 (new application default); 0x0A = deployed 1024\n20   4      merkle_root      sha2-256:4 over PAYLOAD blocks (Section 6) - also the manifest_id\n24   32     image_hash       sha2-256:32 of the reconstructed image - SECURITY anchor\n56   1      codec_id         0=full/raw, 1=detools-sequential, 2=detools-in-place\n57   32     hw_id            NUL-padded ASCII hardware tag (e.g. \"RAK4631\"); same tag =&gt; bootable-compatible.\n                             SIGNED. Applier refuses a mismatch (brick-safety); empty on either side = skip.\n89   8      base_hash        sha2-256:8 of the BASE image's BODY (== that build's EndF.body_hash). 0 if FULL.\n97   32     signer_pubkey    Ed25519 public key. 0 if not SIGNED.\n129  64     signature        Ed25519 over manifest[0, 129). 0 if not SIGNED.\n193  4      approval         FF FF FF FF = not approved; 41 50 52 56 (\"APRV\") = approved\n--- end of manifest-minus-leaves: mfl = 197 (constant); leaves_off = 8 + 197 = 205 in the container ---\n197  4*BC   leaves[]         BC = ceil(payload_size / 2^block_size_log2). sha2-256:4 each (the only variable field)\n</code></pre> <p>The signature always covers <code>manifest[0, 129)</code> (the head + <code>base_hash</code> + <code>signer_pubkey</code>). <code>approval</code> is outside the signed region so it can be flipped in place on consent without breaking the signature.</p> <p>Manifest-minus-leaves size (<code>mfl</code>) is a constant 197 bytes for every container (full or delta, signed or unsigned). At 197 bytes the manifest exceeds one packet, so <code>OTA_MANIFEST</code> is always sent multi-fragment (Section 8.4, 2 fragments) and reassembled by the fetcher.</p> <p>The two versions are deliberately disjoint. Version 2 accepts application packages only and rejects the BOOTLOADER bit. Version 3 accepts only flags exactly <code>FULL|SIGNED|BOOTLOADER</code>; a non-bootloader v3 package is invalid. Consequently, deployed v2-only application parsers reject a bootloader package before they can mistake its raw 40 KiB payload for an application image.</p>"},{"location":"ota_protocol/#41-signed-region","title":"4.1 Signed region","text":"<p><code>signature</code> covers manifest bytes <code>[0, 129)</code> - the head + <code>base_hash</code> + <code>signer_pubkey</code>. It does not cover <code>approval</code> or <code>leaves[]</code>:</p> <ul> <li><code>leaves[]</code> are verified against the signed <code>merkle_root</code> (Section 6), so they need no separate signature.</li> <li><code>approval</code> is device-local consent (Section 4.2), deliberately outside the signature.</li> </ul>"},{"location":"ota_protocol/#42-the-approval-field","title":"4.2 The <code>approval</code> field","text":"<ul> <li>Distributed and forced on ingest to <code>FF FF FF FF</code> (a peer can never pre-approve).</li> <li>The local owner's <code>ota applydelta</code> writes <code>41 50 52 56</code> (<code>\"APRV\"</code>) - a single NOR-safe write (only clears   bits from the erased word). Any partial/other value reads as not-approved (fail-safe).</li> <li>Bound to this image (lives in this <code>.mota</code>'s manifest, re-erased when a new <code>.mota</code> is staged).</li> <li>A consent marker, not a security primitive. Authenticity = <code>signature</code> + <code>image_hash</code> + <code>hw_id</code>.</li> </ul>"},{"location":"ota_protocol/#43-privileged-nrf52-bootloader-package-profile","title":"4.3 Privileged nRF52 bootloader package profile","text":"<p>A v3 bootloader package has a deliberately narrow, non-extensible profile:</p> <ul> <li>flags exactly <code>FULL|SIGNED|BOOTLOADER</code>, <code>CODEC_FULL</code>, nonzero <code>fw_version</code>, zero <code>base_hash</code>;</li> <li>a raw payload and <code>image_size</code> of exactly <code>0xA000</code> (40 KiB), split into exactly forty 1024-byte blocks;</li> <li>a target derived from the installed CRC-valid embedded manifest identity. Deployed XIAO identities keep   raw board IDs <code>0x28860044</code>/<code>0x28860045</code>; generic identities use LE32(SHA-256(canonical padded hw32));</li> <li>signed <code>hw_id</code> exactly <code>XIAO_BL_28860044</code>/<code>XIAO_BL_28860045</code> for deployed XIAO, or the zero-padded   32-byte <code>NRF_BL_&lt;BOARD_ID&gt;_&lt;DEVICE_NAME&gt;</code> for a generic target;</li> <li>a sane nRF52840 vector table, exactly one CRC-valid embedded manifest v1 with the exact board/name pair,   followed by the required CRC-covered <code>BLM2</code>/<code>SOFT</code> continuity extension (embedded boot version,   SoftDevice family/FWID, application base, and layout ABI), with that complete 76-byte envelope at the   canonical final-image offset <code>0x9FB4</code>,   and exactly one <code>MOTABLDR</code> marker advertising ABI &gt;= 3, both application codecs (<code>FULL|INPLACE</code>, mask   <code>0x0005</code>), boot-update continuity, and the exact storage flags for the application layout (<code>0x09</code>   MeshTower V2 SD, <code>0x0E</code> XIAO QSPI, or <code>0x0A</code> shared internal staging).</li> </ul> <p>The incoming embedded identity must exactly match the installed CRC-valid bootloader identity. Both scans consider every aligned structurally valid candidate so magic bytes in a literal pool cannot shadow the real manifest. Duplicate accounting counts each CRC-valid 44-byte base record before interpreting adjacent continuity metadata, so a corrupt or half-present <code>BLM2</code> extension cannot hide a second identity; after exactly one base record is selected, malformed claimed continuity fails closed. A package must be signed by a key already in the device's trusted allowlist; unlike ordinary application packages, there is no unsigned manual-install exception. The signed outer <code>fw_version</code> must equal the embedded boot version. Qualified internal/QSPI targets may bootstrap a CRC-valid legacy-v1 installed bootloader once; MeshTower SD instead requires local BLM2 provisioning because it has no safe legacy media handoff. After bootstrap every remote successor must be strictly newer and match the live SoftDevice/application layout. Low-byte zero and all-ones boot versions are invalid. Remote rollback has no override and must use local DFU/SWD.</p>"},{"location":"ota_protocol/#5-payload-codecs-delta-base","title":"5. Payload, codecs &amp; delta base","text":"<p><code>PAYLOAD</code> is either the full reconstructed image (<code>FULL</code>) or a delta (<code>!FULL</code>).</p> <code>codec_id</code> Meaning Used by 0 full / raw PAYLOAD = reconstructed image (<code>BODY||EndF</code>). ESP32 A/B or an external SD/QSPI nRF52 target. 1 detools sequential random read of base + sequential write of result -&gt; ESP32 A-&gt;B inactive slot. 2 detools in-place bounded scratch; rewrites the app region in place -&gt; nRF52 single-slot. <p>For deltas, <code>base_hash</code> = the base build's <code>EndF.body_hash</code> (sha2-256:8 of its BODY). A node applies a delta only if <code>base_hash</code> matches its own <code>EndF.body_hash</code>. After applying, the result MUST hash (sha2-256:32) to <code>image_hash</code> before it is booted - the hard security gate.</p> <p>A fetcher only requests firmware it can apply. Each node declares the codec(s) it can apply (<code>set_apply_codec</code>/<code>set_apply_codec2</code>): ESP32 accepts <code>full</code> + <code>sequential</code> (+ <code>in-place</code>). Internal-staging nRF52 targets accept only <code>in-place</code> because internal flash cannot hold a second full application image. Matched SD and raw-QSPI nRF52 targets accept <code>full</code> + <code>in-place</code> because external media holds the container. A <code>.mota</code> with an unsupported codec is rejected at discovery time, before any blocks are requested. A manual pull to an external folder may accept other codecs because that path captures bytes and never installs them.</p> <p>Compression is internal to the detools patch and must be supported by the applier. Patches are produced by detools 0.53.0 (<code>tools/mota</code> -&gt; <code>detools.create_patch</code>) and decoded on-device by detools' embeddable C decoder, vendored verbatim at <code>src/helpers/ota/detools/</code> (see its <code>README.meshcore.txt</code>). That build enables only the self-contained <code>NONE</code> + <code>CRLE</code> compressions (no malloc/liblzma/heatshrink), so MeshCore deltas use <code>--compression crle</code>. Do not reimplement the codec - use the vendored decoder.</p>"},{"location":"ota_protocol/#6-merkle-tree-sha2-2564","title":"6. Merkle tree (sha2-256:4)","text":"<p>Verifies each PAYLOAD block against the signed <code>merkle_root</code> before the whole payload exists, so corruption/forgery is localized to a block. Implemented in <code>MerkleTree.cpp</code>.</p> <ul> <li>Blocks: PAYLOAD splits into <code>BC = ceil(payload_size / B)</code> blocks, <code>B = 2^block_size_log2</code> (new   application default 2048; deployed 1024-byte application packages remain valid). The last block is its   real length (no zero padding). Format-3 bootloader packages remain fixed at 1024 bytes.</li> <li>Leaf: <code>leaves[i] = sha2-256:4( block_i_bytes )</code>.</li> <li>Internal node: <code>node = sha2-256:4( left || right )</code> (4+4 input bytes).</li> <li>Odd level: an odd count promotes the last node unchanged to the next level (no duplication).</li> <li>Root: reduce until one node remains. <code>BC == 1</code> -&gt; root = <code>leaves[0]</code>. <code>BC == 0</code> is invalid.</li> </ul>"},{"location":"ota_protocol/#61-proofs","title":"6.1 Proofs","text":"<p>A proof for block <code>i</code> is the ordered list of sibling digests from leaf to root. Promoted levels contribute no element. Verification (needs <code>BC</code> to know the tree shape):</p> <pre><code>h = leaf_i ; idx = i ; n = BC ; p = 0\nwhile n &gt; 1:\n    if (n is odd) and (idx == n-1):        # this node was promoted\n        pass\n    else:\n        sib, side = proof[p] ; p += 1\n        h = sha2-256:4( sib || h ) if side==left else sha2-256:4( h || sib )\n    idx //= 2 ; n = (n + 1) // 2\naccept iff h == merkle_root and p == len(proof)\n</code></pre> <p>Over LoRa, <code>leaves[]</code> are omitted from the manifest transfer. A serving node computes a block's proof on demand from its stored <code>leaves[]</code> and normally sends <code>OTA_PROOF</code> immediately after that block's paced <code>OTA_DATA</code>. <code>OTA_REQ_PROOF</code> remains the fallback for an older source or a lost proactive proof. The fetcher fills its own <code>leaves[i]</code> as each verified block lands.</p>"},{"location":"ota_protocol/#7-block-availability-staging-resume","title":"7. Block availability, staging &amp; resume","text":"<p>There is no separate availability structure. Block <code>i</code> is present &lt;=&gt; <code>leaves[i]</code> is non-erased (<code>!= FF FF FF FF</code>). Because <code>leaves[]</code> live in the staged flash region, availability survives reboot.</p> <p>Commit order per block (crash-safe): (1) verify proof, (2) write block payload to its offset, (3) write <code>leaves[i]</code> last. A power loss before step 3 leaves the slot erased -&gt; the block is simply re-fetched (idempotent). On boot a node rebuilds an in-RAM present-bitmap by scanning <code>leaves[]</code> for a persistent, reopenable store. A hybrid nRF52 transfer is the deliberate exception: its SRAM-backed payload suffix is volatile, so the application refuses to adopt that staged header instead of rebuilding partial progress.</p> <p>Resume (<code>OtaManager::resumeStaged</code> + <code>OtaStore::checkpoint</code>/<code>reopenFor</code>): an interrupted fetch resumes from the staged container after a reboot - re-parse the stored manifest, recompute geometry, count present blocks, continue fetching the holes (or jump straight to COMPLETE). The checkpoint cadence (persist progress every N committed blocks) is runtime-tunable (<code>ota config checkpoint &lt;N&gt;</code>, 0 = only finalized containers resume). Boot-time adoption is an automatic fetch decision: current <code>autofetch</code> must be enabled, the stored target must equal the node target, policy <code>signed</code> requires the signed bit, and an enabled running-version floor requires a strictly newer manifest. An explicit MID pull may deliberately resume an older or unsigned package and keeps target <code>0</code> as a MID-only wildcard. Stores keep <code>leaves[]</code> in RAM until flush and never auto-GC, preserving resumable progress. The debug/operator equivalent is <code>ota dev resume &lt;MID8&gt;</code>; after a reboot the MID is mandatory, while a no-argument form may only reuse a still-active session MID. It never uses the <code>nullptr</code> automatic-adoption path, so a malformed MID or no active MID fails closed. Raw ESP32/nRF52 staging scans every valid header before adoption: address order is not creation order. Explicit resume selects a unique matching MID/target; automatic resume refuses multiple valid headers without erasing them. A leaf-marker read error is never treated as a missing block: reconnectable storage pauses and re-verifies after reconnection, while other storage reports failure and permits an explicit retry. Hybrid nRF52 staging cannot enter this resume path after an application restart, even if its flash prefix still contains metadata; the complete logical container must be fetched again.</p> <p>Flash-store note (RX-safe writes): a flash page-erase halts the CPU (~85 ms on nRF52) and starves LoRa RX, so the flash stores (<code>OtaStoreFlashNrf52</code>/<code>OtaStoreFlashEsp32</code>) coalesce writes to the erase unit (4 KB page / sector) and commit each once off the per-packet path. Ordinary stores keep RAM at O(one page), not O(image); a qualified hybrid nRF52 profile additionally reserves one fixed 64 KiB staging arena. A small delta that fits page 0 does zero flash I/O until COMPLETE.</p>"},{"location":"ota_protocol/#8-lora-ota-protocol","title":"8. LoRa OTA protocol","text":"<p>Carried in MeshCore packets with <code>PAYLOAD_TYPE_OTA = 0x0C</code>. Every OTA packet payload is:</p> <pre><code>[0]    ota_msg_type      (OtaMsgType, OtaFormat.h)\n[1..]  body              (fixed per type; encode/decode in OtaProtocol.cpp)\n</code></pre> <p>Message types:</p> <code>ota_msg_type</code> val routing purpose <code>OTA_ADV</code> 0x01 discovery tiny per-node beacon (discovery tier 1) <code>OTA_QUERY</code> 0x02 discovery ask a source for its catalog (discovery tier 2) <code>OTA_HAVE</code> 0x03 discovery the catalog reply (fragmented, digest-tagged) <code>OTA_GET_MANIFEST</code> 0x04 transfer request a manifest's fragments (<code>want_mask</code>) by <code>manifest_id</code> <code>OTA_MANIFEST</code> 0x05 transfer the manifest-minus-leaves, fragmented <code>OTA_REQ</code> 0x06 transfer request fragments from an adaptive flight of 1-4 blocks (<code>want_mask</code> per block) <code>OTA_DATA</code> 0x07 transfer one self-describing fragment of a block's data <code>OTA_REQ_PROOF</code> 0x08 transfer request/re-request a missing proof <code>OTA_PROOF</code> 0x09 transfer the merkle proof for one block <code>OTA_GET_LEAVES</code> 0x0A transfer request the target's <code>leaves[]</code> fragments (<code>want_mask</code>) - warm-start only <code>OTA_LEAVES</code> 0x0B transfer a fragment of the <code>leaves[]</code> array (for host-side seed leaf-diff) <ul> <li><code>manifest_id</code> = the manifest's <code>merkle_root</code> (4 bytes) - a compact content id present in every   transfer message, so a multi-mota server dispatches each request to the right image.</li> <li>Priority: <code>OTA_ADV</code>, <code>OTA_QUERY</code>, and <code>OTA_HAVE</code> enqueue at background priority 250. Once a fetch is   active, manifest, block request, data, and proof messages enqueue at primary priority 0. Relay-only   nodes classify the wire message identically, so a transfer stays primary across the complete path.</li> <li>Reliability is eventual: the fetcher re-requests only missing fragments after an adaptive deadline   derived from packet airtime, outstanding response packets, duty pacing, and path length. The manager may   still run a one-second maintenance tick, but that tick is not itself a retry timer. No hard ACKs or global   ordering are required.</li> <li>Relay envelope: OTA still uses a bounded flood-shaped mesh header so the same packets can cross the   configured number of hops without first discovering an addressed return path. During TempRadio each node   forwards one copy; active OTA packets do not use the generic flood-retry subsystem. The fetcher verifies   every block against the signed root, and a repeater without <code>ENABLE_OTA</code> can transport   <code>PAYLOAD_TYPE_OTA</code> opaquely without the manager, staging store, installer, or destination bootloader.</li> <li>Hop limit + duty cycle: OTA floods accumulate one path-hash per relay (the mesh's flood routing). A   node with the OTA manager accepts a packet only if it arrived within <code>ota config hops</code> hops (default 3;   <code>0</code> = direct only) and relays it only while still under that limit, appending its own hash. Relay-only   repeaters instead use their ordinary flood limits and forwarding filters. Discovery relays remain   lowest-priority and may be skipped when the packet pool runs low. Active-transfer relays bypass that   background pool gate and use priority 0; operators should therefore treat TempRadio as a dedicated OTA   maintenance window because the transfer can delay unrelated mesh traffic.</li> </ul>"},{"location":"ota_protocol/#81-two-tier-discovery","title":"8.1 Two-tier discovery","text":"<p>Because a node may serve many mOTAs (its own firmware plus an external folder - Section 10), discovery is split so the periodic beacon stays tiny regardless of catalog size:</p> <p>Tier 1 - <code>OTA_ADV</code> beacon (10 bytes, constant). Flooded as a short burst at boot, then every <code>advert_mins</code> minutes (default 24h; runtime-tunable via <code>ota config advert</code>, <code>0</code> disables the periodic re-advertise). It is also emitted immediately whenever the served set changes (e.g. a <code>motatool</code> folder is attached/detached), so peers learn about newly-available firmware without waiting for the next interval:</p> <pre><code>seeder_id[4]    advertiser node id = pubkey[0:4]; the QUERY address + distinct-source id\nn_motas         uint8 - count of complete servable mOTAs (saturates at 255)\nset_digest[4]   sha2-256:4 over the SORTED set of served manifest_ids (see below)\n</code></pre> <p><code>set_digest</code> is a content hash of the offering, not a counter: canonical across nodes, and it changes iff the set of served mids changes. A peer that has already catalogued this <code>{seeder, set_digest}</code> ignores the beacon (steady state is query-free). For a single served mota, <code>set_digest = sha2-256:4(mid)</code>.</p> <p>Tier 2 - <code>OTA_QUERY</code> -&gt; <code>OTA_HAVE</code> (on interest only):</p> <pre><code>OTA_QUERY  (flood):  seeder_id[4]  set_digest[4]  filter_target(uint32) want_fragments(uint32)\n                     # filter_target 0 = everything; want_fragments 0 = every fragment\nOTA_HAVE   (flood):  seeder_id[4]  set_digest[4]  frag_idx(1) frag_total(1) n_rows(1)  rows[]\n  HaveRow (16 bytes, OTA_HAVE_ROW_BYTES): mid[4] target_id(4) fw_version(4) codec_id(1) flags(1) have_count(2)\n</code></pre> <p><code>have_count</code> is the number of blocks the source holds (<code>== block_count</code> for a complete offered image). Receivers do not advertise partial or completed downloads as new sources.</p> <p>A node interested in a source's offering schedules a QUERY; the source replies with its full catalog as <code>OTA_HAVE</code> rows (fragmented if they exceed one packet - 10 rows per fragment). A receiver marks the catalog complete only after all <code>frag_total</code> fragments arrive. If any are missing after the recovery timeout, it sends another QUERY whose <code>want_fragments</code> bitmap names only the holes. <code>want_fragments</code> is an append-only extension: an original 13-byte QUERY is still accepted and means \"send every fragment.\" The heavy manifest is fetched per-mid only on commit (Section 8.3).</p> <p>Fragment numbers are canonical pages of the complete catalog sorted by <code>manifest_id</code>. <code>filter_target</code> may remove rows from a requested page (and can therefore produce an empty fragment), but it never renumbers pages or changes <code>frag_total</code>. Receivers derive the unfiltered page count and each page's row count from the source's advertised <code>n_motas</code>. A page counts as received only if both counts match that complete geometry; filtered rows are still cached, but omitted rows leave the page eligible for an unfiltered recovery query. This also prevents legacy filtered replies which renumber pages from completing an unfiltered catalog.</p>"},{"location":"ota_protocol/#82-anti-storm-mandatory-at-mesh-scale","title":"8.2 Anti-storm (mandatory at mesh scale)","text":"<p>If 50 neighbours all queried a new beacon at once, the mesh would collapse. Mitigations (gossip/mDNS pattern), all in <code>OtaManager</code>:</p> <ul> <li><code>OTA_HAVE</code> is flooded and digest-tagged. EVERY node that overhears it caches the rows passively   (keyed by <code>{seeder, set_digest}</code>) - no query of its own needed.</li> <li>Jittered query: a peer needing a catalog schedules its <code>OTA_QUERY</code> after a random delay   <code>OTA_QUERY_MIN_MS (300) + rand(OTA_QUERY_SPREAD_MS (4000))</code>, derived from <code>id +/ digest +/ self</code>.</li> <li>Overhear suppression: during the jitter window, overhearing another QUERY that covers the same scope,   or completing the HAVE fragment set for the same <code>{seeder, set_digest}</code>, cancels the pending query.</li> <li>Per-source recovery: each seeder has independent query/retry state. One source cannot overwrite another   source's timer, and a partial reply requests only missing fragments after 15 seconds (five bounded retries,   then another source ADV or explicit <code>ota ls</code> can start a fresh series).</li> </ul> <p>Net effect: a digest change costs ~1 query + ~1 HAVE flood mesh-wide; a stable mesh is query-free.</p>"},{"location":"ota_protocol/#83-fetch-handshake","title":"8.3 Fetch handshake","text":"<pre><code>fetcher                                   server (any node that has the mid)\n  OTA_GET_MANIFEST(mid, want_mask)  &gt;     (want_mask=0xFFFF first; only missing fragments on retry)\n                               &lt;-------   OTA_MANIFEST(mid, frag_idx, frag_total, bytes)   x requested frags\n  (reassemble manifest, verify, compute geometry: BC, block_size, payload_size)\n  for each adaptive flight of missing blocks (starts at 1, grows on clean flights):\n    OTA_REQ(mid, {block_idx, want_mask}[]) &gt;  (one packet; all fragments first, only holes on recovery)\n                               &lt;-------   OTA_DATA(mid, block_idx, frag_off, data) x requested frags/block\n                               &lt;-------   OTA_PROOF(mid, block_idx, n_proof, proof) x requested blocks\n    (independently reassemble + verify each block, but remain RX-silent until the flight drains)\n    [after adaptive deadline: recover one block's holes, or OTA_REQ_PROOF for a missing proof]\n    (clean flight grows by one block; recovered flight halves the next width)\n  when all blocks present: verify full merkle_root + image_hash -&gt; COMPLETE\n</code></pre> <p>Before allocating or writing the selected store, the receiver parses the reassembled manifest and requires its <code>merkle_root</code> to equal the requested/wire <code>manifest_id</code> and its <code>target_id</code> to equal the catalog or explicit-pull target that opened the receive slot. The wire envelope and HAVE row are advisory; they cannot label and stage a different manifest.</p>"},{"location":"ota_protocol/#84-message-bodies-transfer","title":"8.4 Message bodies (transfer)","text":"<p>All offsets after the 1-byte type. Encoders/decoders in <code>OtaProtocol.cpp</code>; constants in <code>OtaManager.h</code>.</p> <pre><code>OTA_GET_MANIFEST:  manifest_id[4]  want_mask(uint16)   # bit k = send manifest fragment k; 0xFFFF = all\nOTA_MANIFEST:      manifest_id[4]  frag_idx(1)  frag_total(1)  bytes[]     # up to OTA_MF_FRAG=176 B/frag\nOTA_REQ:           manifest_id[4]  { block_idx(uint16)  want_mask(uint16) }[1..4]\n                   # legacy: bit k requests its 160-byte fragment\n                   # v2: bit15=marker, bit14=allow transport DEFLATE,\n                   #     bit13=2 KiB descriptor, bits0..12=fragment bitmap;\n                   #     bit12 must be zero when bit13 is set (0xFFFF stays legacy)\nOTA_DATA legacy:   manifest_id[4]  block_idx(uint16)  frag_off(uint16)  data[&lt;=160]\nOTA_DATA v2:       manifest_id[4]  block_idx(uint16)  descriptor(uint16)\n                   stream_id[4]  data[&lt;=171]\n                   # deployed 1 KiB descriptor: bit15=marker, bit14=DEFLATE,\n                   #   bits13..10=fragment, bits9..0=complete encoded length minus one\n                   # negotiated 2 KiB descriptor: bit15=marker, bits14..11=fragment,\n                   #   bits10..0=complete encoded length minus one; DEFLATE iff that\n                   #   length is strictly less than the manifest-derived raw block length\nOTA_REQ_PROOF:     manifest_id[4]  block_idx(uint16)\nOTA_PROOF:         manifest_id[4]  block_idx(uint16)  n_proof(1)  proof[]   # n_proof x 4 bytes\nOTA_GET_LEAVES:    manifest_id[4]  want_mask(uint16)   # bit k = send leaves fragment k; 0xFFFF = all\nOTA_LEAVES:        manifest_id[4]  frag_idx(1)  frag_total(1)  bytes[]      # up to OTA_LEAVES_FRAG=176 leaf bytes\n</code></pre> <ul> <li> <p>Warm-start / leaf-diff (<code>OTA_GET_LEAVES</code>/<code>OTA_LEAVES</code>) - motatool folder-capture only. Capturing a   device's firmware into a <code>motatool serve</code> folder is slow (a full image is hundreds of blocks). Because   builds here are non-deterministic, you cannot reproduce the exact target on the host - but a similar   build (e.g. a fresh recompile) is ~99% identical. So <code>motatool serve --seed &lt;similar.mota&gt;</code> stages that   build's payload into the destination <code>.part</code>, and <code>ota pull &lt;mid8&gt; folder validate</code> makes the fetcher (1) bulk-   fetch the target's <code>leaves[]</code> via <code>OTA_GET_LEAVES</code>/<code>OTA_LEAVES</code> (bitmap-fragmented with a <code>want_mask</code>, same   anti-burst rule as <code>OTA_MANIFEST</code>), (2) recompute the merkle root from them and check it equals the   manifest root (authenticate), then (3) keep every seeded block whose leaf matches and pull full <code>OTA_DATA</code>   only for the blocks that differ. The <code>want_mask</code> is a fixed uint16, so <code>leaves[]</code> is capped at   <code>OTA_LEAVES_MAXFRAG=16</code> fragments (<code>OTA_DIFF_MAX_BLOCKS=704</code> blocks); larger images just fall back to a full   fetch. Normal P2P nodes never use this - they target only the blocks they want; the only always-on part   is answering <code>OTA_GET_LEAVES</code> with leaves the node already holds, so any node's firmware can be captured.</p> </li> <li> <p>Negotiated 171-byte fragments: the deployed profile remains unchanged: <code>frag_off</code> is a byte offset and   <code>data[]</code> carries at most 160 bytes. A new fetcher marks an <code>OTA_REQ</code> row as v2. For a deployed 1 KiB block,   its first request also includes every fragment bit needed by the legacy representation, so an old source can   answer it completely. The extended 2 KiB profile reserves bit 12 as zero; this both fits its twelve v2   fragments and ensures the deployed <code>0xFFFF</code> legacy all-fragments request is never misclassified. Receipt of   untagged <code>OTA_DATA</code> switches the fetch session to the old geometry. If no v2 data appears by the first   adaptive deadline, the fetcher retries with an ordinary legacy mask. New sources answer v2 with a packed descriptor, a repeated 4-byte representation   ID, and exactly 171 data bytes except the final fragment. A raw 1 KiB block falls from seven data packets to   six; a raw 2 KiB block falls from thirteen to twelve. Message type IDs do not change, so multi-hop relays   continue to forward request/data/proof packets opaquely with the same priority.</p> </li> <li>Transport-only DEFLATE: a fetcher sets the v2 DEFLATE-permission bit only when its application includes   and configures the decoder. A source may encode each logical block as an independent raw RFC 1951 stream   with full stored, fixed-Huffman, and dynamic-Huffman support (<code>BTYPE=0/1/2</code>). Compression is used only when   strictly smaller, otherwise the source returns raw v2 data. The   receiver inflates to the manifest-derived block length, then performs the unchanged Merkle proof and writes   the original bytes to staging. Thus staging and bootloader apply remain uncompressed. Deployed 1 KiB   <code>.mota</code> containers remain compatible; new 2 KiB containers require a receiver advertising the extended   descriptor. Format-3 bootloader packages retain their strict 1 KiB geometry. The 4-byte <code>stream_id</code> is   SHA-256:4 of the complete raw or compressed   representation and appears in every fragment. A receiver locks <code>{encoding, encoded length, stream_id}</code> for   a block, preventing fragments from independently encoded seeders from being mixed. After one sparse retry,   a second stalled interval clears the full in-flight window and switches the session to legacy geometry, so   a vanished v2 seeder cannot prevent an older source from taking over; proof verification remains unchanged.   Every <code>ENABLE_OTA</code> MeshCore application registers the vendored tinf 1.2.1 full raw decoder; its wrapper   bounds output to the exact logical block length and rejects truncation, malformed streams, and trailing   whole bytes. Builds without OTA do not link the decoder. This application capability is independent of the   bootloader because transport data is inflated before the unchanged staged container is written.</li> <li>Adaptive flight size is not signed block size. Each slot holds one manifest-defined block: 1 KiB for   deployed application containers or 2 KiB for new ones. A clean link changes how many complete blocks one   <code>OTA_REQ</code> names: 1, then 2, then 3, then the compiled cap. It never changes block geometry. Two KiB halves   the leaf, block-request, and proof count for a payload while giving each independent DEFLATE stream a larger   history window.</li> <li>Append-only request-window compatibility: the first four-byte request row is exactly the original   <code>block_idx + want_mask</code> body. Old sources decode that row and ignore appended bytes. New sources queue all   rows. If a new fetcher meets an old source, the unserved tail rows eventually time out and are recovered as   ordinary single-row requests; the dirty flight then contracts. Old fetchers continue sending nine-byte   single-row requests, which new sources accept normally.</li> <li>Fragment-level requests (anti-deadlock + anti-congestion): <code>OTA_REQ</code>, <code>OTA_GET_MANIFEST</code>, and <code>OTA_QUERY</code>   carry fragment masks. For catalog discovery, <code>want_fragments</code> is a 32-bit bitmap and covers the protocol   maximum 255-row catalog (26 fragments at the current packet size). For block and manifest transfer, the   <code>want_mask</code> is 16 bits. A fetcher requests the full set on the first ask   (<code>(1&lt;&lt;nf)-1</code>, or <code>0xFFFF</code> before <code>frag_total</code> is known) and only the still-missing bits on any retry,   so recovering one lost fragment re-sends one fragment, not the whole block/manifest. This is essential on   half-duplex radios: re-requesting a whole multi-fragment burst let the periodic retry (a transmit) collide   with the tail of the in-flight burst and drop the same fragment forever - a hang. Requesting only the hole   removes the burst, so there is nothing to collide with. The block/manifest mask matches the 16-bit   reassembly bitmap (&lt;=16 fragments/block; 1 KiB is 7 legacy or 6 raw-v2 fragments; 2 KiB is 13 legacy or 12   raw-v2 fragments). <code>OTA_PROOF</code> is a single packet and needs no mask.</li> <li>Data and proof remain separate packets, without a normal extra round trip. A server retains requested   blocks in a bounded descriptor queue, admits at most one response per main-loop pass, and sends one   <code>OTA_PROOF</code> after each block's requested fragments. Before admitting that proactive proof, the source leaves   an airtime/duty-aware 100-3000 ms RX turnaround gap. It accounts for one active transmission plus the two   paced-response queue credits. A legacy receiver uses the gap to send its immediate   <code>OTA_REQ_PROOF</code>; receiving that explicit request bypasses the remaining gap, avoiding a proof/request   collision and an otherwise multi-second legacy retry. A newer receiver uses an airtime/path-aware proof   grace (never less than 500 ms) and defers <code>OTA_REQ_PROOF</code> while any flight slot still expects DATA. Thus a   missing early proof cannot make the receiver transmit into the rest of a legitimate half-duplex response   train. After the complete-flight deadline, only one slot's missing fragments/proof is requested at a time.</li> </ul>"},{"location":"ota_protocol/#85-sizing-against-max_packet_payload-184","title":"8.5 Sizing against <code>MAX_PACKET_PAYLOAD = 184</code>","text":"message fixed overhead payload/packet <code>OTA_DATA</code> legacy 9 B (type+mid4+idx2+off2) <code>OTA_FRAG_DATA = 160</code> -&gt; 7 raw frags/1 KiB or 13/2 KiB <code>OTA_DATA</code> v2 13 B (legacy header + stream ID) <code>OTA_FRAG_DATA_V2 = 171</code> -&gt; 6 raw frags/1 KiB or 12/2 KiB; fewer when compressed <code>OTA_MANIFEST</code> 7 B <code>OTA_MF_FRAG = 176</code> -&gt; signed manifest ~ 2 frags <code>OTA_HAVE</code> 12 B 10 rows x 16 B per fragment <code>OTA_PROOF</code> 8 B up to ~44 sibling digests (&gt;&gt; any real tree) <p>A served mota supports up to 1024 leaves in the default 4 KiB proof scratch (about 2 MiB of payload at the new 2 KiB default, or 1 MiB for a deployed 1 KiB container); larger self-images pass a bigger scratch buffer.</p>"},{"location":"ota_protocol/#86-temporary-radio-and-transfer-boundary","title":"8.6 Temporary-radio and transfer boundary","text":"<p>OTA packets may cross normal mesh relay hops, but each participating node processes or relays them only while its <code>tempradio</code> window is actually running. A receiver selects missing blocks in serial order into a bounded request flight. Every session starts with one block. A clean completed flight increases the next request by one block; a flight requiring fragment/proof recovery halves the next width (<code>4 -&gt; 2</code>, <code>3 -&gt; 2</code>, <code>2 -&gt; 1</code>). The default compiled cap is two blocks; the RAK3401 LoRa-OTA target caps at four, so it probes <code>1 -&gt; 2 -&gt; 3 -&gt; 4</code>. All rows are sent in one backward-compatible <code>OTA_REQ</code>, and no freed slot is refilled until the current flight is finished. It never serves partial blocks. A normal install receiver never re-advertises its completed download. An SD archive node is the deliberate exception: after a fully proof-verified container is published to its persistent archive, it registers that complete file as a MotaSource and advertises it as a new seeder. This keeps each active transfer as one transmitter and one receiver while still allowing active temporary-radio repeaters between them and persistent archive nodes to improve future availability.</p> <p>TempRadio is treated as a private maintenance network. Active transfer packets use priority 0, bypass the public-flood receive holdoff, use the full transmit budget without overwriting the saved normal-radio airtime factor, retain the relay role's airtime-scaled transmit collision window, and do not schedule generic flood retries. Deployed firmware predating that TempRadio budget override can be accelerated manually with a saved <code>get af</code> / temporary <code>set af 0</code> / restore sequence. The bounded serving queue admits at most two DATA/PROOF packets ahead of the radio while preserving at least four free packet-pool entries. CAD remains enabled to arbitrate the half-duplex channel, but its busy retry is scaled to one-quarter of a packet airtime and clamped to 5-50 ms instead of the ordinary 120-360 ms cadence. Discovery traffic keeps collision jitter and background priority. The fetch deadline uses the active radio's measured maximum-packet airtime, remaining DATA/PROOF packet count, dispatcher airtime factor, and longest observed path (falling back to the configured hop horizon before one is observed), with bounded guard time. Faster SF/BW settings therefore recover loss sooner; slower or multi-hop settings do not spuriously re-request a response still on air. These changes remove software waits and duplicate bursts; they do not remove the one required forwarding transmission per hop.</p>"},{"location":"ota_protocol/#9-identity-trust-versioning","title":"9. Identity, trust &amp; versioning","text":"<ul> <li><code>target_id</code> (4 B): <code>sha2-256:4(pio_env_name)</code> (little-endian uint32). The env name uniquely captures   hardware and role/partition, so a node auto-fetches only matching firmware (a companion image is not   fetched onto a repeater even though it shares <code>hw_id</code>). It is self-described in the firmware's EndF   (Section 2, written by <code>pio_endf.py</code>) and read via <code>ota_self_firmware()</code>, so it is correct on any build;   <code>-D MOTA_TARGET_ID</code> / <code>MainBoard::getOtaTargetId()</code> is the fallback when no EndF identity is present.   <code>tools/mota</code> reads it from the firmware's EndF (or <code>--target-env</code>). A manual <code>ota pull</code>/<code>want</code> can override   target (deliberate role switch); the <code>hw_id</code> brick-safety gate (Section 4) still applies at apply time.</li> <li><code>target_id</code> vs <code>hw_id</code> - complementary, not redundant: <code>target_id</code> is the fetch-routing key   (hw + role + partition); <code>hw_id</code> is the human-readable brick-safety key (hardware only). Same board, two   roles =&gt; same <code>hw_id</code>, different <code>target_id</code>.</li> <li>One-way target migration: a release may compile <code>MOTA_MIGRATION_TARGET_ID</code> into a legacy image. While   that image is running, automatic fetch accepts only the declared successor target; manual pulls remain   unchanged. The staged manifest must still match the requested successor target, the signed <code>hw_id</code>, image   hash, codec, and partition/layout checks. After reboot the successor's EndF becomes the node's normal   identity, so later updates use the canonical target. The migration alias is not used for bootloader packages.</li> <li>Naming a <code>target_id</code> locally: only the 4-byte <code>target_id</code> ever travels on the wire. To show which   board/role a target is, a node (and <code>motatool</code>) reverse-looks-it-up in <code>src/helpers/ota/OtaTargets.h</code> -   a generated <code>target_id -&gt; env-name</code> table covering every <code>ENABLE_OTA</code> env (<code>tools/mota/gen_targets.py</code>,   resolved from <code>pio project config</code>). So <code>ota ls</code> can render <code>[Heltec_v3_repeater]</code> for a neighbour's   beacon without the string being transmitted. Unknown IDs show as raw <code>hw XXXXXXXX</code> / <code>N/A</code> values.</li> <li><code>fw_version</code>: packed comparable uint32 (<code>MAJOR&lt;&lt;24 | MINOR&lt;&lt;16 | PATCH&lt;&lt;8 | pre</code>); also self-described   in EndF. <code>ota ls</code> prints the stable eight-hex manifest ID and uses <code>[same target]</code>, <code>[unsupported]</code>, or   <code>[rescue]</code> after combining target equality with the local codec, bootloader, and EndF preflight. A known   different target is rendered by environment name; an unknown/unset target remains raw or <code>?</code>. Target   equality is routing information, not by itself an assertion that an image is safe to install.</li> <li><code>hw_id</code>: 32-byte NUL-padded ASCII hardware tag inside the signed head. The applier refuses a <code>.mota</code>   whose <code>hw_id</code> differs from the device's own tag (empty on either side = permissive). Brick-safety   independent of signature.</li> <li>Signing &amp; allowlist: a node keeps a runtime allowlist of trusted Ed25519 signer pubkeys (none embedded   in firmware; <code>ota key add/list/rm</code>). A <code>.mota</code> is eligible for auto-install only if signed by an   allowlisted key, the signature verifies, <code>image_hash</code> matches, and its nonzero signed <code>fw_version</code> is   strictly greater than the running hash-valid EndF version. Both catalog admission and final automatic   apply enforce the version floor, so a lying HAVE row cannot bypass it. Manual <code>ota install</code> is the explicit   equal-version/rollback override and generally permits unsigned packages,   but a package that claims to be signed must have a valid signature from an allowlisted key or it is rejected.   The removable-SD target is stricter: every application install needs a valid allowlisted signature because   the app mints an authenticated one-reset media authorization for OTAFIX.   Transfer needs no trust - blocks are content-addressed against the manifest's merkle root.</li> <li>Policies (persisted): <code>autofetch</code> in {off, any, signed} (default off) gates automatic block fetching of   own-target (or an explicitly compiled one-way successor) adverts; <code>autoinstall</code> in {off, trusted} (default off) gates auto-apply of a COMPLETE signed +   allowlisted fetch. Conservative defaults: a fresh node discovers + announces but never fetches/installs   without operator intent.</li> <li>Supersession: a newer version announced mid-download does not abort the in-progress transfer   (finish-current).</li> </ul>"},{"location":"ota_protocol/#10-multi-mota-serve-the-external-folder-relay","title":"10. Multi-mota serve &amp; the external \"folder\" relay","text":"<p>A node serves a set of mOTAs: its own firmware plus, optionally, an external folder of <code>.mota</code> files it relays without holding them in flash. To peers it simply \"has N mOTAs\"; the relay is trustless (fetchers verify everything). The serve side (<code>OtaManager</code>) keeps a lightweight registry of what it advertises and two resident \"views\": <code>view0</code> (its own firmware) and one on-demand view loaded from a source when a request targets an external mota. Every fetch message carries <code>manifest_id</code>, so dispatch is a registry lookup.</p> <p>The USB/TCP host-folder link can also be a pull destination (the reverse direction): <code>ota pull &lt;mid8&gt; folder</code> fetches a <code>.mota</code> off the mesh and streams it onto the host as <code>&lt;mid&gt;.mota</code> via the seeder STORAGE ops (<code>OP_STAT/BEGIN/WRITE/SREAD/FIN</code>, see <code>MotaSeederProto.h</code>), using a <code>FolderMotaStore</code> as the fetch's <code>OtaStore</code> instead of RAM/flash. This captures an exact copy of a device's firmware - e.g. to build a delta against firmware you don't have. Resume is bookkeeping-free: <code>BEGIN</code> 0xFF-fills the file and, on reconnect after a link drop (the fetch PAUSES, holding progress on the host - no RAM/flash fallback), <code>STAT</code>+<code>SREAD</code> let the fetcher recompute and refill only the missing blocks. TCP disconnect preserves the selected MID, target, and destination across dynamic-context idle cleanup. Metadata initialization or seed leaf-diff restarts from the manifest on reconnect; an initialized transfer reopens and rehashes the same MID before requesting missing blocks. Host I/O failure during final verification or publication pauses too; a genuine Merkle mismatch remains a failed transfer. Explicit cancel/detach still releases the session, and a different host transport cannot take over a paused capture without cancellation. The phone-oriented BLE link is deliberately source-only and does not register a folder destination.</p>"},{"location":"ota_protocol/#101-the-motasource-abstraction-otasourceh","title":"10.1 The <code>MotaSource</code> abstraction (<code>OtaSource.h</code>)","text":"<p>Transport-agnostic provider of one or more complete <code>.mota</code> as random-access bytes. The same serve code drives USB-serial, BLE, a WiFi URL list, an NFS/samba mount, etc. - only <code>read()</code> differs.</p> <pre><code>struct MotaDesc {                      // catalog metadata + region offsets (no whole image in RAM)\n  uint8_t mid[4]; uint32_t target_id, fw_version; uint8_t codec_id, flags;\n  uint8_t block_size_log2, source_caps;\n  uint32_t total_size, leaves_off, block_count, payload_off, payload_size;\n};\nclass MotaSource {\n  virtual uint8_t count();                                  // # mOTAs offered\n  virtual bool    describe(uint8_t idx, MotaDesc&amp; out);     // metadata + offsets\n  virtual bool    read(uint8_t idx, uint32_t off, uint8_t* buf, uint32_t len);   // random-access bytes\n  virtual bool    read_deflated_block(uint8_t idx, uint16_t block,\n                                      uint8_t* buf, uint16_t cap, uint16_t* len); // optional raw RFC 1951\n};\n</code></pre> <p>To serve an external mota the node reads its manifest-minus-leaves + <code>leaves[]</code> into RAM (&lt;=4 KiB for &lt;=1024 blocks) and streams payload blocks from the source on demand; proofs are generated from the read leaves.</p>"},{"location":"ota_protocol/#102-the-mota-seeder-transport-motaseederprotoh","title":"10.2 The <code>mota-seeder</code> transport (<code>MotaSeederProto.h</code>)","text":"<p>A <code>MotaSource</code> is fed by a host that serves a folder over the device's USB serial (the same console the CLI uses - no extra hardware), on an ESP32 WiFi companion or FULL ESP32 role over WiFi (TCP), or on an nRF52 Full Companion over an encrypted BLE GATT service. The host is the standalone Rust tool <code>motatool</code> (<code>motatool serve --serial &lt;port&gt;</code> / <code>--tcp &lt;host[:port]&gt;</code>, which also builds + verifies + inspects <code>.mota</code>). The device only emits request frames while actively serving a fetch, and reads the reply synchronously, so over the shared USB console binary frames coexist with the text CLI/logs (resync on magic + checksum). Little-endian, XOR-checksummed:</p> <pre><code>request  (device -&gt; host):  'M' 'S'  op(1)  args...                 xsum(1 = XOR of op+args)\nresponse (host -&gt; device):  'm' 's'  op(1)  status(1)  payload...    xsum(1 = XOR of all prior)\n\nOP_COUNT     0x01   args: -            -&gt; payload: count(1)\nOP_DESCRIBE  0x02   args: idx(1)       -&gt; payload: MotaDesc wire (38 B)\nOP_READ      0x03   args: idx(1) off(4) len(2)  -&gt; payload: len bytes\nOP_DEFLATE_BLOCK 0x09 args: idx(1) block(2) off(2) len(2)\n                         -&gt; payload: total_encoded_len(2) + requested bytes\nMotaDesc wire (38 B): mid[4] target_id(4) fw_version(4) codec(1) flags(1)\n                      total_size(4) leaves_off(4) block_count(4) payload_off(4) payload_size(4)\n                      block_size_log2(1) source_caps(1) reserved(2)\nstatus: 0 = OK, non-zero = error (out of range / past EOF).\n</code></pre> <p><code>SerialMotaSource</code> splits logical reads into replies of at most 192 payload bytes. A manifest's leaf table can exceed 256 bytes and new payload blocks are normally 2 KiB; requesting either in one transaction can overrun common USB CDC/UART receive rings even though the host successfully wrote the complete reply. Chunking is internal to the transport and does not change <code>OP_READ</code> or the <code>MotaSource</code> random-access contract.</p> <p><code>OP_DEFLATE_BLOCK</code> lets a host-folder source perform the optional transport compression without linking an encoder into the embedded seeder. <code>len=0, off=0</code> queries the exact encoded length; subsequent chunks are at most 190 bytes, keeping the total response payload at 192 bytes. The host independently encodes each manifest payload block as ordinary raw RFC 1951 at level 9. It returns an error for an invalid range, an unsupported operation, or a result that is not smaller than the raw block; <code>SerialMotaSource</code> then serves the ordinary raw v2 representation. A supporting host sets <code>source_caps bit 0</code> in every descriptor. Older hosts leave that formerly-reserved byte zero, so upgraded firmware skips the optional request instead of waiting for an old daemon that silently ignores unknown operations.</p> <p>Manifest fragments are retained as bounded response jobs and admitted one at a time. Their source-side gap follows the active maximum packet airtime and dispatcher duty spacing, clamped to 100-1000 ms. The 100 ms floor protects fast radios' TX-to-RX turnaround; the cap keeps the receiver's one-second manifest progress/retry observation responsive. The source uses the same radio-aware 100-3000 ms drain/turnaround gap before an unsolicited block proof, but immediately serves a legacy receiver's explicit <code>OTA_REQ_PROOF</code>. Relay collision delay is a separate setting: active OTA floods honor the relay role's configured <code>txdelay</code>, and the deployment runner temporarily uses <code>0.3</code> on managed relays.</p> <p>What to plug into <code>--serial</code>. Use the USB serial console of an OTA-enabled MeshCore node built with <code>OTA_FOLDER_SERIAL</code>. The node must have a working LoRa radio plus an <code>ota folder on</code> command; that command confirms it can host and advertise the folder. A KISS modem will not work: KISS firmware exposes a TNC/KISS frame interface, not the MeshCore CLI and <code>mota-seeder</code> request/response transport. An ESP32 WiFi companion or FULL ESP32 role with active WiFi is the alternative source connection: use its dedicated seeder port with <code>motatool serve --tcp &lt;host&gt;:5001</code>. An nRF52 Full Companion can instead pair with a phone or Linux host, subscribe to its mOTA request characteristic, and use protocol-v14 <code>CMD_BLE_MOTA_SOURCE</code>. That BLE path is source-only; it does not expose the reverse <code>FolderMotaStore</code> capture operations.</p> <p>Device CLI: <code>ota folder on</code> (attach + announce), <code>ota folder</code> (list), <code>ota folder off</code>. Build flag <code>OTA_FOLDER_SERIAL</code> (default stream = console <code>Serial</code>; override <code>OTA_FOLDER_SERIAL_STREAM</code> + define <code>OTA_FOLDER_SERIAL_BEGIN</code> for a dedicated UART). ESP32 WiFi companions and FULL ESP32 roles run a <code>WiFiServer</code> on the dedicated seeder port (<code>OTA_SEEDER_TCP_PORT</code>, default <code>5001</code>) while WiFi is usable. On a companion it is separate from the app port (<code>TCP_PORT</code>, default <code>5000</code>); on infrastructure roles it is separate from WebConfig and browser OTA on port 80. The node auto-attaches the source when a seeder client connects and detaches when it closes (no <code>ota folder on</code> needed over TCP). An already-active serial folder causes a TCP client to be rejected instead of silently replacing it. Verified on hardware: a RAK4631 relays a host folder to a Heltec V3 over one USB cable, and a host feeds a Heltec V3 over WiFi (<code>:5001</code>) while the companion serves a phone on <code>:5000</code> - every block merkle-checked.</p> <p>The attach reply and bare <code>ota folder</code> report <code>host=advertised/offered</code>. The registry is RAM-bounded (<code>OTA_MAX_SERVE</code>, with the node's own firmware consuming one slot), so a host may correctly index more valid files than this particular firmware can advertise. Omitted entries are now reported instead of silently disappearing. Operators should split a large chain or use a higher-capacity/SD seeder when the two counts differ.</p> <p>Transport-agnostic by design. The request/response semantics (<code>COUNT</code> / <code>DESCRIBE(idx)</code> / <code>READ(idx, off, len)</code> over a folder catalog) are independent of the link. The 2-byte magic + XOR checksum + resync framing above exists for the shared USB-UART (an unframed byte stream); it is harmless over a reliable stream and the WiFi (TCP) transport reuses it as-is - both ends just treat the socket as a byte stream (on-device, <code>SerialMotaSource</code> runs verbatim over an Arduino <code>Stream</code>-compatible <code>WiFiClient</code>; <code>motatool</code>'s <code>TcpTransport</code> mirrors its <code>SerialTransport</code>). The nRF52 Full Companion's BLE GATT path also reuses the exact frame and checksum. Device requests are notifications on a dedicated characteristic and host responses are ordered write-with-response fragments on a second characteristic. Keeping the same framing makes retries and corruption handling identical across USB, TCP, and GATT. The Linux reference implementation is <code>tools/ble_mota/ble_mota_seeder.py</code>; a phone app can implement the same transport-free catalog operations.</p>"},{"location":"ota_protocol/#11-cli-surface-otaclicpp","title":"11. CLI surface (<code>OtaCli.cpp</code>)","text":"<p>User-facing OTA data should travel via <code>CMD_OTA_*</code> companion binary frames; the text CLI below is debug/operator oriented and replies are <code>snprintf</code>-bounded into a 160-byte buffer.</p> <p>Commands take intuitive aliases (matched by the first word; see <code>is_cmd</code> in <code>OtaCli.cpp</code>) so they're easy to type and read - <code>status</code>/<code>neighbors</code>/<code>pull</code>/<code>drop</code>/<code>applydelta</code> are the canonical names, the aliases are the recommended user-facing forms. Output is plain-language (a user-facing guide lives at ota_user_guide.md).</p> <pre><code>ota help | ? | h                   list the commands\nota status | st  (or bare `ota`)   plain-language: running fw, the one fetch session (state/%/id), serving, keys\nota ls | neighbors | nbrs | updates | n [page]   paged updates (queries sources; rows arrive async via OTA_HAVE)\nota get | pull | download &lt;mid8|#index&gt; flash [rescue] | folder [validate]\n                                      fetch by stable mid8 (preferred) or current page index\nota install | apply | applydelta   verify + approve + (ESP32) apply / (nRF52) reboot-to-bootloader\nota rescue install &lt;base_hash16&gt;  internal-flash nRF52 only: recover from failed app-side EndF validation\nota bootloader [status]           capable allowlisted nRF52 repeater: installed BL identity/caps + staged confirmation\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n                                      explicitly verify/arm one complete trusted v3 package; never automatic\nota cancel | drop | stop           drop the fetch; durably invalidate device staging, or retain a folder partial for resume\nota announce | adv                 serve self + send a beacon now\nota self | id                      print this firmware's EndF (body/image size, base_hash)\nota qspi | storage                 QSPI nRF52 only: JEDEC/SR1/stage/latched storage error (read-only)\nota folder | fold [on|off]         attach/detach an external .mota folder (host daemon) ; bare = list\nota config | cfg | set [autofetch|autoinstall|checkpoint] ...   show/set persisted policy\nota key | keys [add|rm &lt;hex&gt;]      trusted signer allowlist ; bare = list\nota dev ...                        bring-up helpers (stage/recv/serve/resume &lt;MID8&gt;/verify)\n</code></pre> <p>For a device-backed pull, current firmware returns success only after the persistent store can no longer be reopened; flash/SD/QSPI I/O or readback failure is reported as an error even though the in-memory manager session was dropped. For a <code>folder</code> pull, cancellation detaches the live transfer but deliberately leaves the host <code>.part</code> file available for a later resume. If the shared receive engine is currently performing the MeshTower SD auto-archive capture, cancellation likewise detaches that archive transfer and retains its <code>.part</code> file; it does not erase the unrelated manual-install store.</p> <p></p>"},{"location":"ota_protocol/#12-apply-bootloader-contract","title":"12. Apply &amp; bootloader contract","text":"<ul> <li>ESP32 (A/B): applied in-firmware via the detools decoder into the inactive OTA slot   (<code>OtaApply.cpp::ota_apply_detools_mota</code> + <code>OtaStoreFlashEsp32</code>), then set-boot + reboot (power-safe,   rollback-capable). No bootloader changes. Erase ranges must be sector-aligned (4096).</li> <li>nRF52 (single-slot): the running firmware never flashes the app. <code>ota install</code> verifies the   container fully (<code>image_hash</code>, codec, signature/allowlist, <code>hw_id</code>, and <code>base_hash</code> for a delta), writes   <code>approval = \"APRV\"</code>, then reboots into the modified bootloader   (<code>Adafruit_nRF52_Bootloader_OTAFIX</code>). The bootloader:</li> <li>locates the staged <code>.mota</code> in the approved internal, raw-SD, or raw-QSPI store without trusting an      unchecked stored size,</li> <li>re-checks <code>TRAILER</code>, <code>image_hash</code>, and <code>approval == \"APRV\"</code>; for a delta it also checks that      <code>base_hash</code> equals the running firmware's <code>EndF.body_hash</code> (recomputed by scanning for <code>EndF</code> - never      trust <code>bank_0_size</code>),</li> <li>writes a full external-media payload or applies the in-place codec over the app region, then boots only      if the result hashes to <code>image_hash</code>.</li> <li>nRF52 internal staging ceiling: an internal-store application derives the ceiling from facts available   in every build, not a board-name list. A companion that actually links the internal ExtraFS datastore stays   below <code>0xD4000</code>; a default linker region or a role that does not mount ExtraFS can reclaim the unused   100 KiB through <code>0xED000</code>. A qualified internal bootloader-self-update target keeps that normal flash   ceiling and does not reserve a second boot-package or flash-scratch region, but it uses a dedicated   application linker that reserves the top 64 KiB of SRAM (<code>0x20030000..0x20040000</code>) plus a 72-byte   retained authorization record after the existing persistent clock bytes. Application deltas larger than   one flash page use a deterministic page-aligned flash prefix ending at <code>0xED000</code> and place up to 64 KiB   of the logical container tail in that SRAM. Packages of one page or less, and bootloader-update packages,   remain wholly in flash. Hybrid staging is enabled only when the installed bootloader contains exactly one   valid <code>MOTARAMA</code> capability marker; otherwise a larger hybrid-profile fetch fails before erase. Immediately   before a software reset the application publishes a valid-last <code>MOTAHYB1</code> record binding the split geometry   and normalized container hash. The bootloader consumes it once and rejects power-loss, stale-reset, corrupt,   or mismatched-RAM cases before its first application write. A hybrid transfer cannot resume after an   application restart because its suffix is deliberately volatile. The bootloader treats every unknown/legacy   GPREGRET2 handoff value as <code>0xD4000</code>, and accepts a flash-only container only at the bottom-aligned position   for the selected ceiling.</li> <li>nRF52 dynamic apply window: the post-build hook records the resolved app base, linked app end,   internal-ExtraFS/SD/QSPI/hybrid-RAM storage flags, and desired staging ceiling immediately before <code>EndF</code>.   <code>motatool</code> reads that authenticated firmware record and chooses <code>memory_size</code> from the actual patch size   and bottom-aligned stage address. For a hybrid base it charges only the deterministic flash prefix against   that workspace; the retained-RAM suffix is still part of the same hashed logical container.   Firmware without the record retains the conservative <code>0x98000</code> default. Before writing <code>APRV</code>, an   internal-store app validates the staged-address bound; an external SD/QSPI app validates the full detools   geometry against the application workspace. The bootloader independently parses and validates the same   geometry before its first application write. Expanded auto-sized packages require a bootloader   with the ceiling-handoff capability; use <code>--inplace-memory 0x98000</code> when intentionally targeting an older   bootloader and the images still fit that window.</li> <li>nRF52 EndF rescue: <code>ota rescue install &lt;base_hash16&gt;</code> is a pre-provisioned recovery path for an   internal-flash nRF52 application that still runs but cannot validate its own EndF identity. It refuses   when normal EndF validation succeeds, requires the operator hash to exactly equal the staged delta's   <code>base_hash</code>, requires the package <code>target_id</code> to match and its <code>hw_id</code> to pass the normal hardware gate,   and retains the normal payload and signature/allowlist gates. Approval only delegates the base decision:   OTAFIX independently   locates the physical EndF, hashes the running app, and compares that value with the package before its   first app write. A physically absent/corrupt EndF or wrong base therefore returns to the unchanged app;   it still requires USB recovery if that app does not already contain this command.   A chain intended to cross historical firmware must introduce this command in its first bridge and retain   it in every later bridge. Manual pulls still use the build-provided target ID when app-side EndF parsing   fails, so a rescue-capable bridge can fetch its exact successor before invoking the guarded command. Such   a node must acknowledge the condition up front with <code>ota pull &lt;mid8&gt; flash rescue</code>; an ordinary flash pull   refuses before altering staged data. Firmware that predates both rescue commands still requires USB recovery.   Internal-bootloader-self-update builds are a stricter exception: because their ordinary linker may extend   through <code>0xED000</code>, an absent/corrupt live <code>EndF</code> disables every internal staging pull before erase instead   of trusting the legacy 608 KiB estimate.</li> <li>MeshTower V2 SD nRF52: the application stores a contiguous <code>/meshcore-ota.mota</code> on microSD. After   authenticating one exact signed manifest and verifying the leaves/payload/image, it hashes the exact full   container with only <code>APRV</code> normalized to zero and publishes a 72-byte reset-retained <code>MOTASDA2</code> record.   That record binds app-vs-boot purpose, format, raw sector range, total/card geometry, and normalized digest;   OTAFIX consumes and clears it before reading the card. There is no normal sector-1 handoff or additional   OTA-specific partition-layout requirement beyond what the bundled SdFat can mount. The matching   bootloader reads the authorized sectors without mounting FAT, supports either a full image or an in-place delta,   verifies the staged/full result hash, and never writes through <code>0xED000</code> where InternalFS begins. The   exact SD repeater also accepts a manually selected, signed v3 bootloader package when installed and   candidate markers are exactly <code>0x09</code> (<code>SD|BOOT_UPDATE</code>). MeshCore streams the same strict identity,   CRC, vector, signature, MID/hash-confirmation, and complete-image checks from the SD file. GPREGRET   <code>0x6B</code> plus GPREGRET2 <code>0x53</code> selects this privileged path. Both MeshCore and OTAFIX require a hash-valid   live <code>EndF</code> ending by <code>0xE0000</code>; when a nonzero boot-settings bank CRC is active, its recorded size must   also cover that complete live image and stop by <code>0xE0000</code>. For fmt3 MeshCore additionally writes a readback-checked   <code>MOTASDBL</code> token at <code>0xE0000</code> containing the exact total and signed <code>image_hash</code>. OTAFIX binds the parsed manifest,   streamed payload, and final scratch image to that   token, so a removable-media change can only fail closed. OTAFIX then uses <code>0xE0000..0xEA000</code> as temporary scratch; the normal   application linker remains at <code>0xED000</code> and ordinary application updates do not inherit this scratch   headroom restriction. Both fmt2 application apply and fmt3 bootloader apply require installed BLM2   continuity matching the live S140 FWID/application layout. Preview.12 must be upgraded locally over   USB/BLE DFU or SWD. MeshCore never writes a raw sector-1 handoff.</li> <li>Matched external-QSPI nRF52 repeaters: the application reserves the board's dedicated QSPI NOR as a   raw store beginning at offset zero. It obtains a 1-16 MiB capacity from JEDEC, checkpoints payload before   leaf metadata, and verifies each erased/programmed page. GPREGRET2 <code>0x51</code> selects QSPI only when the   matching bootloader advertises the QSPI storage bit; legacy markers retain the internal scan path. The   bootloader pre-hashes a full payload before invalidating the app, or applies an in-place delta with the   complete internal application region as workspace. Companion builds never enable this raw store: some use   QSPI as a filesystem, while others simply leave that chip outside OTA ownership. See   the nRF52 QSPI guide.</li> <li>XIAO bootloader self-update (explicit only): selected XIAO-module QSPI repeater builds link the   ordinary application below <code>0xE0000</code>, reserving <code>0xE0000..0xEA000</code> as a 40 KiB internal scratch bank.   They accept a v3 bootloader package only through an exact manual MID pull. Ordinary <code>ota install</code>,   autofetch, autoinstall, and every application apply backend reject it. The operator then copies the   staged package's exact values from <code>ota bootloader</code> into   <code>ota bootloader install &lt;MID8&gt; &lt;HASH16&gt;</code>. The app repeats the strict v3 geometry, installed/candidate   identity, vectors, embedded CRC/capabilities, complete payload/image hashes, signature, and trusted-key   gates before writing <code>APRV</code>. GPREGRET <code>0x6B</code> plus GPREGRET2 <code>0x51</code> hands the QSPI package to OTAFIX.   <code>APRV</code> carries the app's authenticated and explicitly confirmed authorization decision; OTAFIX does not   repeat Ed25519/allowlist, Merkle, or typed operator confirmation. It independently rechecks the strict v3   structure, canonical identity/capabilities, vectors, payload SHA, embedded CRC, and scratch/copy hashes,   uses the scratch bank to preserve the running application while replacing <code>0xF4000..0xFE000</code>, and reports   boot-update results in GPREGRET2 <code>0xC0..0xCF</code>   (<code>0xC8</code> success). This mechanism cannot bootstrap a stock/older bootloader; install an ABI-3,   boot-update-capable exact-board OTAFIX over USB/BLE DFU or SWD once first.</li> <li>Internal-flash bootloader self-update (explicit only): curated nRF52840 lean repeater/bridge targets   without an OTA-owned SD/QSPI store share the normal bottom-aligned internal store below <code>0xED000</code>.   It holds either an ordinary app delta or the exact 41,330-byte v3 container, never both. The boot package   bottom-aligns at <code>0xE2000</code>; a hash-valid live <code>EndF</code> must prove the complete running image ends at or below   that address before the first erase. OTAFIX reads each source window before erasing and compacts the   payload forward in the same eleven pages to raw <code>0xE2000..0xEC000</code>; no separate flash scratch bank exists.   The qualified application linker reserves a 64 KiB SRAM arena only for hybrid application deltas; the   bootloader package remains wholly in flash. GPREGRET <code>0x6B</code> plus GPREGRET2 <code>0xED</code> selects boot update,   while ordinary app apply uses GPREGRET <code>0x6A</code> plus the same storage source. Exact installed/candidate   capability flags are <code>0x0A</code> (<code>STAGE_CEILING|BOOT_UPDATE</code>). Ordinary deltas remain dynamically sized, may start below   <code>0xE2000</code>, and reconstruct only below the normal <code>0xED000</code> app ceiling. The same signature, explicit   confirmation, exact identity, vector, CRC, and single-marker rules as the XIAO path apply. Bootloader FULL   admission is isolated from ordinary application FULL policy, and privileged partials are never resumed   automatically after an application reboot. See   the nRF52 bootloader-update guide for the exact target inventory.</li> </ul> <p>A signature, when present, proves author authenticity and must pass the device allowlist. Unsigned v2 application packages remain installable when local policy permits them. A v3 bootloader package is always signed and trusted. The one-shot <code>approval</code> marker records local consent before the bootloader may apply it.</p> <p>Bootloader testing note: always test apply with a real different image (base != target). A same-image (X-&gt;X) \"delta\" trivially reproduces the target and gives a false positive.</p>"},{"location":"ota_protocol/#13-versioning-of-this-spec","title":"13. Versioning of this spec","text":"<p>The fixed byte layout has two intentionally disjoint profiles: <code>format_ver = 2</code> for ordinary application packages and <code>format_ver = 3</code> only for the exact privileged bootloader profile in Section 4.3. A parser must reject v2+BOOTLOADER, v3 without exact <code>FULL|SIGNED|BOOTLOADER</code>, and every other version. The multihash <code>hash_algo</code> separately allows swapping the digest family without a format bump. Unknown <code>codec_id</code> / <code>ota_msg_type</code> values are ignored (a node simply will not fetch what it cannot apply).</p>"},{"location":"ota_user_guide/","title":"Updating your node over the air (OTA) - user guide","text":"<p>For 1.17.1.5, use the exact board/storage profile from OTAFIX 2.4.6 for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB.</p> <p>This guide is for node operators: how to update your MeshCore device's firmware over the radio, in 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.)</p> <p>LoRa OTA download and installation are present only in supported Keymind destination artifacts; the receiver must already be running one of those install-capable builds. Some internal-staging nRF52 targets use a lean <code>lora_ota_no_external_sensors</code> target, while matched external-QSPI boards can retain their normal full-sensor repeater features. Release filenames include an OTA marker, but capability must still be confirmed on the running device. A source can be an OTA-enabled infrastructure node or a source-only Full Companion backed by <code>motatool</code>. Intermediate repeaters do not need OTA-enabled firmware: current repeater builds transport OTA floods opaquely, subject to their normal forwarding filters, duplicate checks, and flood limits. OTA radio traffic is accepted, generated, and relayed only while <code>tempradio</code> is actually running on that node. Every source, receiver, and intermediate repeater must therefore have an overlapping temporary-radio window.</p> <p>The recommended temporary OTA settings use 250 kHz bandwidth, SF5, CR5, and a 120-minute window. For a North American node currently configured for 910.525 MHz, run this on every participating node:</p> <pre><code>tempradio 910.525,250,5,5,120\n</code></pre> <p>Use the node's current permitted regional frequency in place of <code>910.525</code> when necessary.</p> <p>The scripted updater checks the firmware version of the receiver and every sender before deciding whether RX power saving can remain active. At SF5/BW250, an all-v1.17.1.5-or-newer path can use effective RXPS level 8 with the tuple-selected 64-symbol physical preamble. SF5/BW500 can use level 8 with 128 symbols. Other fast tuples remain at the shortest viable preamble, normally 32. A mixed, older, or unknown long-preamble path is put in continuous receive for the update, then the receiver's exact saved RXPS setting is restored. This preserves the RX benefit without risking missed packets from a legacy 32-symbol sender.</p> <p>Can my node install the update? Choose a release-table artifact explicitly labelled LoRa-OTA capable, then confirm <code>ota self</code> and <code>ota status</code> expose install support; do not infer support from the filename alone. 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. An intermediate repeater only relays packets and needs neither an install-capable image nor OTAFIX. Check the bootloader release for an exact board match before attempting an update.</p> <p>The following nRF52 repeater families gained firmware-side LoRa OTA targets in this release. Their ordinary repeater keeps its complete declared sensor recipe; the install-capable <code>lora_ota_no_external_sensors</code> sibling is smaller:</p> <ul> <li>Heltec Mesh Solar, T1, and Tower V2</li> <li>Keepteen LT1, LilyGo T-Impulse Plus, Mesh Pocket, and Nano G2 Ultra</li> <li>Minewsemi ME25LS01, RAK3401, SenseCAP Solar, and Wio WM1110</li> </ul> <p>The RAK3401 <code>RAK_3401_repeater_lora_ota_no_external_sensors</code> image trims selected optional environmental/ranging drivers but does not disable I2C. It retains the INA219, INA226, INA260, and INA3221 voltage/current monitors, board display and RTC support, and both RAK12500 I2C and RAK12501/L76K UART GPS paths. The four INA drivers are only the retained voltage/current entries in the optional environmental-sensor table; they are not the only I2C users. The SSD1306 OLED, autodiscovered DS3231/RV3028/PCF8563/RX8130CE RTCs, and RAK12500 GPS use I2C as separate board peripherals. Install one GPS module in sensor slot A. Slot D's reset/PPS lines conflict with the RAK13302 radio's BUSY/DIO1 lines.</p> <p>The firmware-configured INA3221 address and the RAK12500 address are both <code>0x42</code>, so those devices cannot share one bus at those addresses. To install both, leave the RAK12500 at <code>0x42</code>, strap INA3221 A0 to SCL for <code>0x43</code>, and use a firmware build with <code>-DTELEM_INA3221_ADDRESS=0x43</code>.</p> <p>The reduced RAK4631 profiles likewise retain the four INA monitors. The plain repeater and Serial2 bridge retain GPS: a RAK12501 can use sensor slot A or D, and a RAK12500 can use slot A or C. The runtime RS-232 bridge defaults to Serial2 so the UART RAK12501 can retain Serial1. The merged runtime image always reserves Serial1: a bounded silent probe cannot prove that a cold RAK12501 is absent, and turning the GPS setting off cannot stop a fitted module from driving the shared UART while WB_IO2/3V3_S remains powered. Use Serial2. Serial1 requires an explicit no-GPS/dedicated image. The reservation remains fail-closed even when an I2C RAK12500 is detected. The explicitly compiled <code>RAK_4631_repeater_bridge_rs232_serial1_lora_ota_no_external_sensors</code> target omits the combined GPS provider because its bridge owns the UART used by RAK12501; consequently that legacy image does not expose the I2C RAK12500 path either, even though RAK12500 itself does not use the UART.</p> <p>Selected nRF52 repeaters with dedicated external QSPI can now stage the complete package off-chip, so their normal full-sensor repeater build can install a full image or an in-place delta. The current matched families are XIAO nRF52840 and its XIAO-module derivatives, original LilyGo T-Echo, ThinkNode M1/M6, Wio Tracker L1, SenseCAP Solar, and the dedicated RAK4631 + RAK15001 slot-C target. The list also includes a separately wired W25Q16JV on RAK19007 with either RAK4631 or RAK3401 + RAK13302. These require the corresponding exact QSPI-aware OTAFIX bootloader; see the nRF52 QSPI guide.</p> <p>The W25Q16 option uses one permanent RAK19007 wiring for either core: CLK/MISO/ MOSI tap IO-connector pins 26/27/28, flash CS uses J11 AIN1, and power uses J12 VDD (3.3 V) and GND. Add an approximately 10 kOhm CS-to-VDD pull-up and never power the flash from VBAT. The three SPI signals require underside pads or an IO-connector interposer; the easy J10/J11/J12 headers do not expose them. The flash consumes no WisBlock slot, so a supported GPS can remain in slot A.</p> <p>The ordinary full-sensor <code>RAK_4631_repeater</code> image remains too large for the safe internal in-place update limit. Without external flash, use <code>RAK_4631_repeater_lora_ota_no_external_sensors</code>; it trims selected optional environmental/ranging drivers while retaining generic I2C, battery monitoring, the four INA monitors, and target-compatible GPS. A RAK4631 fitted with RAK15001 in sensor slot C can instead use <code>RAK_4631_repeater_rak15001_slot_c_lora_ota</code> to retain the full sensor/GPS set and stage full images or deltas off-chip.</p> <p>For the external Winbond breakout, use <code>RAK_4631_repeater_w25q16_lora_ota</code> on RAK4631 or <code>RAK_3401_repeater_rak13302_w25q16_lora_ota</code> on RAK3401 + RAK13302. They retain the full sensor/GPS recipe and require exactly a 2 MiB <code>EF4015</code> W25Q16 plus the bootloader for that same core/radio/flash combination. Install <code>wiscore_rak4631_w25q16</code> for RAK4631 or <code>wiscore_rak3401_rak13302_w25q16</code> for RAK3401 + RAK13302 as a one-time prerequisite. The physical wiring is shared, but the two firmware identities are deliberately different and cannot be substituted for one another.</p>"},{"location":"ota_user_guide/#the-important-part-first-its-safe","title":"The important part first: it's safe","text":"<ul> <li>Nothing installs by itself. Your node can discover and download an update, but   it only installs when you say so (unless you deliberately turn on auto-install - see below).</li> <li>Bad downloads can't sneak in. Every piece of the firmware is checked against a cryptographic   fingerprint as it arrives, and the whole image is verified again before install. A corrupt or tampered   download is rejected, not installed.</li> <li>You choose who to trust. Updates can be signed by their author. You can tell your node to only   auto-install firmware signed by keys you've added.</li> <li>Discovery stays quiet; a transfer is deliberate. Periodic update discovery uses background priority.   Once a download starts, its transfer packets are primary traffic across every relay hop, so use   TempRadio as an OTA maintenance window when delaying unrelated mesh traffic would matter.</li> <li>It can recover. If an install ever fails, the node falls back to a safe recovery mode (you can   re-flash a known-good firmware over USB) - it won't be left bricked.</li> </ul>"},{"location":"ota_user_guide/#how-to-talk-to-your-node","title":"How to talk to your node","text":"<p>Connect to your node's console - usually a USB serial terminal at 115200 baud (or whatever tool you already use to manage the node). You type <code>ota ...</code> commands and the node replies in plain words.</p> <p>The commands have short, friendly names (and most accept aliases, so you don't have to remember exact spelling): type <code>ota help</code> any time to see the list, or just <code>ota</code> for a status summary.</p>"},{"location":"ota_user_guide/#common-tasks","title":"Common tasks","text":""},{"location":"ota_user_guide/#1-see-what-im-running-and-whether-anything-is-going-on","title":"1. See what I'm running and whether anything is going on","text":"<pre><code>ota status\n</code></pre> <p>Shows your current firmware version, your node's update \"target\" (its hardware/role id), and whether a download is in progress.</p> <p>For a denser admin view - your firmware's content id (<code>mid</code>) and its body hash, the fingerprint of the set you're serving, live download progress, and the current policy - use:</p> <pre><code>ota stats\n</code></pre> <p>On a remote node this is admin-only (the remote command console requires the admin password) - send it from the app's repeater command screen, or the WiFi/serial OTA console.</p>"},{"location":"ota_user_guide/#2-find-updates-available-near-me","title":"2. Find updates available near me","text":"<pre><code>ota ls\nota ls 2                 # page 2 when more than two updates are available\n</code></pre> <p>Your node asks around and lists the firmware updates other nodes nearby are offering, in plain words - each with a temporary number, a stable eight-hex manifest ID, its version, whether it's a full image or a small delta, how many nodes have it, and how recently it was seen. For example:</p> <pre><code>Updates 1/1 (2 src; refreshing):\n 1) 838B8169 v1.2.3 delta [same target] 3n 5s\n 2) BF0AB0C4 v1.2.0 full [unsupported] 1n 12s\n</code></pre> <p>Each row shows the version, full-vs-delta, whether it fits your node, how many nodes have it, and how long ago it was seen. The fit marker:</p> <ul> <li>[same target] - the advertised target ID matches this hardware-and-role build. Download and apply   still enforce codec, bootloader, signed hardware tag, base hash, and integrity checks.</li> <li>[unsupported] - the target may match, but this build or its bootloader cannot apply that codec. A common   example is the source node's self-served full image on an internal-staging nRF52, which needs an   in-place delta. A matched external-QSPI nRF52 can accept that full codec.</li> <li>[rescue] - an installable in-place nRF52 delta for the same target, but this running firmware has no   valid app-side EndF. It requires the explicit rescue download and install flow below.</li> <li>[name] - a different known board or role (for example <code>[ProMicro_companion_radio_usb]</code>). Don't install it.</li> <li>[?] - can't tell (a build with no target id set, e.g. a bare IDE build rather than a release build).</li> </ul> <p>Run it again after a few seconds - discovery happens in the background, so the list fills in. Nothing is downloaded yet; this is just looking around. <code>refreshing</code> means the command has just sent asynchronous catalog queries, so run it again even when an older row is already visible. Two updates fit in each remote CLI reply; use <code>ota ls 2</code>, <code>ota ls 3</code>, and so on for later pages. Catalog rows can change while replies arrive, so use the displayed manifest ID for scripts and important operations rather than a numeric position. (<code>ota neighbors</code> / <code>ota updates</code> also work.)</p>"},{"location":"ota_user_guide/#3-download-an-update","title":"3. Download an update","text":"<p>Pick one from the list by its stable manifest ID (a number also works for interactive use), and say where to put it:</p> <pre><code>ota pull 838B8169 flash            # stage it in this node's flash, to install here\nota pull 838B8169 folder           # capture it onto a connected motatool folder as &lt;id&gt;.mota\nota pull 838B8169 folder validate  # warm-start capture from a motatool --seed build (much faster; below)\n</code></pre> <p>The destination is required - <code>ota pull 838B8169</code> on its own just shows the choices. <code>flash</code> is always available (stage here, then <code>ota install</code>). <code>folder</code> appears only while a <code>motatool serve</code> link is attached (it shows the link, e.g. <code>folder: tcp 192.168.4.5</code>); it streams the firmware straight onto the host folder - nothing is staged on this node. That's how you grab an exact copy of another device's firmware off the mesh (to a <code>.mota</code> file) so you can later build a delta against firmware you don't otherwise have. (<code>ota get</code> is an alias.)</p> <p><code>validate</code> (warm-start, advanced). Capturing a full image over the radio is slow. If you have a similar build on the computer (e.g. a fresh recompile of the same firmware), run motatool with <code>--seed &lt;that.mota&gt;</code> and add <code>validate</code>: the node fetches just the target's block fingerprints, keeps every block your seed already matches, and pulls over the radio only the handful that actually differ - turning a ~30-minute capture into seconds. The result is still a byte-exact, verified copy of the target.</p> <p>Where the seed comes from: it is the <code>--seed &lt;file&gt;</code> you pass to <code>motatool serve</code> - not a file you drop into the capture (<code>--dir</code>) folder, which is only the destination and starts empty. There is exactly one configured seed. When you run <code>... folder validate</code>, the node asks motatool to begin the capture and motatool stamps that seed's payload into the fresh <code>.part</code> in the same step - so it is always the file you named, with no guessing. <code>validate</code> is the switch: a plain <code>folder</code> pull ignores any seed and fetches from scratch; re-running a <code>validate</code> pull re-begins fresh (it never resumes a stale partial). Nothing about the seed is trusted - every kept block is checked against the target's own fingerprints, so a mismatched or missing seed just means those blocks are fetched over the radio (correct result, only slower).</p> <p>The node fetches from one source as primary traffic, with bounded adaptive request flights. Every session probes with one manifest block, then clean flights grow <code>1 -&gt; 2 -&gt; 3 -&gt; 4</code> blocks on RAK3401 OTA builds. New application packages use 2 KiB blocks; deployed 1 KiB packages remain supported. All blocks in a flight share one request packet, and the receiver stays silent until the source/relays finish returning them. A recovery halves the next flight. Retry timing follows the active SF/BW airtime, duty budget, and path length, so faster settings recover sooner without a fixed one-second request colliding with a valid multi-hop response. Mesh repeaters carry the packets only while their temporary-radio windows are active. Check progress with <code>ota status</code>.</p> <p>If a <code>folder</code> pull loses its link mid-transfer, <code>ota status</code> shows paused - the host keeps the partial and the pull resumes (filling only what's missing) the moment you reconnect motatool; it never falls back to flash. A TCP disconnect preserves the selected image even if it happens before its manifest arrives or during the final save. Reconnect through the same transport; an interrupted manifest or seed comparison restarts initialization, while a partial transfer rechecks its stored blocks. The paused capture keeps its OTA workspace until reconnection or cancellation. To stop a download you no longer want:</p> <pre><code>ota cancel\n</code></pre> <p>For a download staged on the node, success means current firmware also invalidated the persistent flash/SD/QSPI copy; it reports an error if that media operation cannot be verified. For a <code>folder</code> capture, cancel only detaches the live session and retains the host partial so it can be resumed or removed on the host deliberately. On a MeshTower SD auto-archive capture, cancel also detaches the live archive session and retains its card partial for the archive service to resume later; use <code>ota cache off</code> to stop new archive captures.</p>"},{"location":"ota_user_guide/#4-install-a-downloaded-update","title":"4. Install a downloaded update","text":"<p>Once <code>ota status</code> shows the download is ready to install:</p> <pre><code>ota install\n</code></pre> <p>The node verifies the firmware one last time, and if everything checks out it installs it and reboots into the new version. If the check fails, it tells you why and does not install. Unsigned images normally install only through this explicit command. The MeshTower V2 SD target is stricter and requires an allowlisted signature even for a manual application install, because it authorizes removable-media bytes for the bootloader. A signed image whose signer is not in the device allowlist is rejected; trusted signed images can auto-install only when that policy is enabled and the signed version is strictly newer than the running hash-valid EndF version. Manual <code>ota install</code> remains the deliberate equal-version/rollback override.</p> <p>After it reboots, run <code>ota status</code> to confirm the new version.</p>"},{"location":"ota_user_guide/#updating-an-nrf52-bootloader-advanced-explicit-only","title":"Updating an nRF52 bootloader (advanced, explicit only)","text":"<p>This is available on specially marked no-external-flash nRF52840 lean repeater/bridge builds, on the legacy XIAO nRF52840/Sense raw-QSPI builds, and on the exact <code>Heltec_tower_v2_sdcard_repeater_lora_ota_no_external_sensors</code> microSD build, after a one-time exact-board ABI-3 OTAFIX installation over USB/BLE DFU or SWD. It is not the normal firmware update path. Check support first:</p> <pre><code>ota bootloader\n</code></pre> <p>The reply must show a CRC-valid installed identity plus ABI 3 and the exact storage/boot-update capability bits for that build (<code>0x09</code> for MeshTower V2 microSD, <code>0x0A</code> for the shared internal store, or <code>0x0E</code> for XIAO raw QSPI). A bootloader package appears as <code>bootloader</code> in <code>ota ls</code>. It is never downloaded or installed automatically, even if both OTA automation settings are enabled. Use its stable ID explicitly:</p> <pre><code>ota pull &lt;MID8&gt; flash\n# wait until ota status says this bootloader download is ready\nota bootloader\nota bootloader install &lt;MID8&gt; &lt;HASH16&gt;\n</code></pre> <p>Copy both confirmation values exactly from the second <code>ota bootloader</code> reply. Ordinary <code>ota install</code> deliberately refuses this package. The privileged command requires an exact 40 KiB candidate payload in the fixed 41,330-byte container, a valid exact embedded identity/CRC and vector table, continued boot-update support, required <code>BLM2</code>/<code>SOFT</code> continuity metadata at canonical raw-image offset <code>0x9FB4</code>, a boot version that exactly matches the package and is newer than installed BLM2, and a valid signature from a key already in <code>ota key</code>'s trusted allowlist. It preserves the running application while OTAFIX replaces itself; <code>blup:C8</code> in post-reboot <code>ota status</code> means success. Remote rollback is refused. Any node lacking this command or those capabilities must update its bootloader locally instead.</p> <p>On an internal-flash target, the package shares the ordinary store below <code>0xED000</code> and bottom-aligns at <code>0xE2000</code>; there is no separate reserved scratch bank. A valid live <code>EndF</code> must prove the current image ends at or below that address before any page is erased. If <code>EndF</code> is missing/corrupt or the app is too large, the pull is refused and local DFU/SWD is required. On the MeshTower V2 SD target, the application linker remains at <code>0xED000</code>, but bootloader replacement needs temporary scratch beginning at <code>0xE0000</code>. A hash-valid live <code>EndF</code> must therefore prove the complete current image ends by <code>0xE0000</code>. A CRC-bound boot-settings bank must cover that complete image while also ending by <code>0xE0000</code>. MeshCore binds both application and bootloader SD approval to purpose, exact raw geometry, and a normalized SHA-256 in a reset-retained <code>MOTASDA2</code> record. Boot updates also bind the exact authenticated signed image hash in the E0000 token. OTAFIX consumes the retained record before media access, so a later card change or power cycle fails instead of authorizing different bytes. MeshCore never claims or writes raw sector 1. Both application and bootloader OTA wait until a matching BLM2 bootloader has been provisioned locally; preview.12 requires USB/BLE DFU or SWD first. Larger applications can continue to use normal application mOTA; only bootloader self-update is refused. See the nRF52 bootloader-update guide for the complete target inventory, storage layouts, and safety contract.</p>"},{"location":"ota_user_guide/#5-if-something-goes-wrong","title":"5. If something goes wrong","text":"<ul> <li>A download that stalls or gets interrupted just resumes later. Use   <code>ota cancel</code> to durably discard device staging; a folder capture keeps its   host partial for a later resume.</li> <li>A legacy app-only internal-flash nRF52 that still runs but reports <code>no EndF</code> can use the pre-provisioned rescue path   if its physical EndF is intact and only app-side validation is failing. Fetch the exact <code>[rescue]</code>   in-place delta with an explicit acknowledgement, obtain its 16-hex-digit <code>base_hash</code> from the package   metadata, then run:</li> </ul> <p><code>text   ota pull &lt;mid8&gt; flash rescue   # wait for ota status to say ready to install   ota rescue install &lt;base_hash16&gt;</code></p> <p>This is not a force option. It refuses a normally valid EndF, a different package hash, hardware or   target mismatch, corrupt payload, and invalid/untrusted signatures. The bootloader independently hashes   the running app and rejects a wrong base before writing the app. If the physical EndF is absent or the   rescue commands were not already in the running firmware, recover over USB.   Release chains should put this command in their first bridge and keep it in every bridge after that.   The shared-internal bootloader-update builds are intentionally excluded:   without valid live <code>EndF</code>, they refuse every internal pull before erase   because their normal application can extend through <code>0xED000</code>. Recover one   of those builds over USB/BLE DFU or SWD. - If an install fails, the node won't boot a broken image - it lands in recovery mode:   - nRF52: it appears as a USB drive; drag a known-good firmware <code>.uf2</code> for that exact board onto it     to recover.   - ESP32: it keeps the previous firmware in the other slot and rolls back. - When in doubt, you can always re-flash over USB the normal way.</p>"},{"location":"ota_user_guide/#adjust-lora-ota-speed","title":"Adjust LoRa OTA speed","text":"<p>Use one saved speed factor for this node's LoRa OTA traffic:</p> <pre><code>get ota.speed\nset ota.speed 0.5\nset ota.speed .05\nset ota.speed 3\nset ota.speed 1\n</code></pre> <p>The range is 0.05 through 3, including decimals. 1 is the existing timing. At <code>0.5</code>, adjustable OTA delays are twice as long; at <code>0.05</code>, they are twenty times as long. At <code>3</code>, adjustable delays are divided by three. Actual transfer speed also depends on packet airtime, the configured airtime budget, relays, and packet loss; <code>3</code> does not guarantee three times the throughput.</p> <p>The factor covers OTA requests and responses (catalog, manifest, leaves, DATA, and proofs), OTA relay delays, discovery jitter, and automatic OTA adverts. Below <code>1</code>, the transmit queue also spaces out every OTA packet, including both profile copies, while letting ordinary messages run. Recovery waits grow for slower transfers; faster settings retain the existing retry allowance so they do not retry before a physical response train can finish. The radio's frequency, bandwidth, SF, coding rate, preamble, and airtime budget stay as set. The proof turnaround allowance also keeps its existing physical minimum. Dual-profile timing accounts for the participating profiles and reply copies; it does not vary with the scanner's current visit. Deliberate slow pacing is excluded from observer builds' stale-packet age, while congestion still ages queued packets normally.</p> <p>Set the same factor on the source, destination, and OTA relays. It is a local setting, not a value negotiated with peers. A slow source paired with a receiver at <code>1</code> can cause unnecessary retries. The setting takes effect during an active session, survives reboot and temporary-radio expiry, and applies to OTA on either radio profile. <code>set ota.speed 1</code> restores the previous pace. Ordinary chat, node adverts, and USB/WiFi source transfers keep their timing. Local verification of a staged image and leaf comparisons keep their normal maintenance rate even when LoRa pacing is slow. If the local transmit queue cannot accept a catalog, manifest, or leaf request, OTA keeps it pending without consuming a network retry. Successfully queued requests that receive no answer still have bounded retries. Blocked block requests also preserve the v2 transfer format and fragments already received; queue congestion alone does not trigger legacy fallback. Retry timing includes the primary channel when an RX-only temporary radio2 uses crossover to send requests there.</p> <p><code>ota config speed 0.5</code> is an equivalent setter. <code>ota config speed</code> and <code>ota speed</code> read the current factor; the <code>ota config</code> summary also includes it. The setting is available on OTA-enabled repeaters, rooms, sensors, Companions, and seeder-only builds. Its separate <code>/ota_speed</code> settings file preserves the existing preference layouts and does not need an active OTA workspace.</p>"},{"location":"ota_user_guide/#optional-let-it-update-automatically","title":"Optional: let it update automatically","text":"<p>By default your node only discovers updates - it won't download or install on its own. If you want more automation (e.g. for a remote node you can't easily reach), you can opt in. These settings are saved.</p> <pre><code>ota config autofetch any        # auto-DOWNLOAD any compatible update for this node (still won't install)\nota config autofetch signed     # auto-download only signed updates\nota config autofetch off        # back to manual (default)\n\nota config autoinstall trusted  # auto-INSTALL only a trusted signed version newer than the running EndF\nota config autoinstall off      # never auto-install (default)\n\nota config advert 1440          # re-advertise every N minutes while temp radio is running\nota config advert 0             # only advertise when a temp-radio window starts\n\nota config hops 3               # how far OTA travels: accept from / relay up to N repeater hops (default 3)\nota config hops 0               # only exchange OTA with directly-connected nodes (never relay)\n\nota config                      # show the current settings\n</code></pre> <p>These policies also govern automatic adoption of an interrupted staged download after reboot. <code>off</code> leaves it untouched, <code>signed</code> requires the stored manifest's signed flag, and automatic resume requires the stored target to match this node and its version to be newer than the running valid EndF. Reissuing an explicit <code>ota pull &lt;MID8&gt;</code> remains the deliberate override for an older or unsigned partial. For bring-up/debugging, <code>ota dev resume &lt;MID8&gt;</code> performs the same explicit MID-bound re-adoption without starting a new network fetch. After reboot it requires the MID; bare <code>ota dev resume</code> is accepted only while an active/requested session MID still exists, and malformed or missing identifiers are rejected. If raw flash contains multiple valid staged headers, automatic resume leaves them untouched rather than guessing which is newest. Specify the intended MID to select its unique checkpoint; ambiguous matches are rejected. Temporary storage read failures no longer consume a download slot indefinitely: host storage pauses for reconnection, while non-reconnectable storage reports a storage error and can be retried.</p> <p>Recommended for most people: leave both off and update by hand. Use <code>autoinstall trusted</code> only once you've added the signer's key (next section) and you trust them to push updates unattended. Automatic admission and final apply both reject zero, equal, or older signed versions; a dishonest catalog version cannot bypass the manifest check. Use manual <code>ota pull</code> plus <code>ota install</code> for an intentional rollback.</p> <p>The MeshTower V2 SD OTA target has a separate, default-on archive policy. It saves all mOTAs it sees to the SD card so the repeater can seed them later; this does not install them and does not change the install-oriented <code>autofetch</code> default above. Use <code>ota cache</code> for status and <code>ota cache off</code> or <code>ota config cache off</code> to stop new archive captures. Already cached files remain available to peers. Manual <code>ota pull</code> commands take priority and an interrupted archive capture resumes later. See Preload many mOTAs from a computer for the required <code>/mota/&lt;manifest-id&gt;.mota</code> filenames and the complete TempRadio seeding workflow.</p>"},{"location":"ota_user_guide/#optional-only-trust-updates-from-specific-people","title":"Optional: only trust updates from specific people","text":"<p>If you'll use auto-install, tell your node which signing keys to trust. The firmware author shares their public key (a hex string); you add it:</p> <pre><code>ota key add &lt;public-key-hex&gt;    # trust this signer\nota key list                    # show trusted signers\nota key rm &lt;public-key-hex&gt;     # stop trusting one\n</code></pre> <p>Only strictly newer updates signed by a trusted key are eligible for auto-install. Manual <code>ota install</code> permits an unsigned package after all integrity, hardware, base, and bootloader checks pass, except on the MeshTower V2 removable-SD path where all application installs must be signed and allowlisted. A signed package whose signer is not in the device allowlist is rejected rather than silently treated as unsigned.</p>"},{"location":"ota_user_guide/#sharing-updates-with-others-advanced","title":"Sharing updates with others (advanced)","text":""},{"location":"ota_user_guide/#relay-a-folder-of-firmware-from-a-computer","title":"Relay a folder of firmware from a computer","text":"<p>If your node is connected to a computer (e.g. a gateway on a Raspberry Pi), it can hand out a whole folder of firmware files to the mesh - without storing them itself. Useful for seeding a new release to a remote area.</p> <ol> <li>Put the firmware files (<code>.mota</code> files - see below) in a folder on the computer.</li> <li>Install the helper tool once - the standalone <code>motatool</code> CLI (https://github.com/vk496/motatool) -    then point it at your node and the folder - over the node's USB serial, over WiFi if it is    an ESP32 WiFi companion or FULL ESP32 node, or over encrypted Bluetooth if it is an nRF52 Full Companion:    <code>git clone https://github.com/vk496/motatool &amp;&amp; cargo install --path ./motatool    # over USB serial:    motatool serve --dir ./my_firmware/ --serial /dev/ttyACM0 -v    # ...or over WiFi: the seeder is on dedicated TCP port 5001:    motatool serve --dir ./my_firmware/ --tcp 192.168.1.50:5001 -v    # ...or over paired BLE to an nRF52 Full Companion (protocol v14):    python3 tools/ble_mota/ble_mota_seeder.py \\      --device MeshCore-MyCompanion --dir ./my_firmware/</code>    It answers the node's requests; your node then advertises those updates to neighbours, who can    <code>ota get</code> them like any other. (A WiFi node prints its IP + seeder port to the serial log on connect.    Details: https://github.com/vk496/motatool.)</li> </ol> <p>Check the device's attach reply or run <code>ota folder</code>: <code>host=X/Y</code> means the firmware is advertising <code>X</code> of the <code>Y</code> valid entries reported by the host. Serve registries are deliberately RAM-bounded on smaller builds, and the node's own firmware also consumes a slot. If <code>X &lt; Y</code>, split the chain across seeders/folders or use a higher-capacity seeder; <code>motatool</code> saying that every file is valid does not mean every file fit on-device.</p> <p>To stop, just stop the daemon - over WiFi the node auto-detaches when the connection closes; over USB you can also run <code>ota folder off</code> on the node. <code>ota folder</code> on its own lists what your node is offering. On a FULL repeater or room server, run <code>start webconfig</code> first if WiFi is not already active. Other FULL roles with browser OTA support can use the <code>MeshCore-OTA</code> access point from <code>start ota</code> and connect to <code>192.168.4.1:5001</code>. Every LoRa participant still needs an overlapping <code>tempradio</code> window.</p>"},{"location":"ota_user_guide/#everyone-helps-share","title":"Everyone helps share","text":"<p>You don't have to be a gateway to help. Once any node finishes downloading an update, it automatically offers it to its neighbours too. So a new firmware spreads outward node-to-node, instead of everyone hammering the one node that had it first. Discovery remains background traffic; an actual transfer is primary traffic for the duration of its TempRadio maintenance window.</p>"},{"location":"ota_user_guide/#where-firmware-files-come-from","title":"Where firmware files come from","text":"<p>OTA distributes <code>.mota</code> files - a packaged, verifiable firmware image (full image or a small \"delta\" that only contains what changed). You get them by:</p> <ul> <li>Downloading a build. This fork publishes a rolling <code>dev-latest</code> release on GitHub with the   current firmware for many boards, each accompanied by a <code>.full.mota</code> and a tiny <code>.delta.mota</code>. Grab the   one for your board to test.</li> <li>Building your own with the <code>mota</code> packaging tool - see tools/mota/README.md   (this is for people distributing updates, not everyday operators).</li> </ul>"},{"location":"ota_user_guide/#quick-reference","title":"Quick reference","text":"I want to... Command List all commands <code>ota help</code> See my firmware + any download <code>ota status</code> (or just <code>ota</code>) Admin: ids/hashes + serving + policy <code>ota stats</code> (admin-only remotely) Find updates nearby <code>ota ls</code> Download a listed update for installation <code>ota get &lt;mid8&gt; flash</code> Cancel a download <code>ota cancel</code> Install a finished download <code>ota install</code> Recover app-side <code>no EndF</code> on a legacy app-only internal nRF52 <code>ota rescue install &lt;base_hash16&gt;</code> Turn on auto-download <code>ota config autofetch any</code> Turn on auto-install (trusted only) <code>ota config autoinstall trusted</code> Trust a signer <code>ota key add &lt;hex&gt;</code> Relay a folder (gateway) <code>ota folder on</code> + the seeder daemon List what I'm offering <code>ota folder</code> <p>(Older names still work too: <code>neighbors</code>/<code>updates</code> = <code>ls</code>, <code>pull</code> = <code>get</code>, <code>applydelta</code>/<code>apply</code> = <code>install</code>, <code>drop</code>/<code>stop</code> = <code>cancel</code>.)</p>"},{"location":"ota_user_guide/#a-few-terms","title":"A few terms","text":"<ul> <li>Firmware - the software running your node. Updating it can add features or fix bugs.</li> <li><code>.mota</code> - a packaged firmware update file, with built-in integrity checks.</li> <li>Target - your node's hardware + role identity. Your node only auto-fetches updates built for the   same target, so it won't grab firmware meant for a different board.</li> <li>Delta - a small update containing only the changes from your current firmware (faster to send than a   full image). Your node rebuilds the complete firmware from it and verifies the result before installing.</li> <li>Signed - the update carries the author's cryptographic signature, so you can verify who made it.</li> </ul> <p>For the full technical details (the file format and the radio protocol), see the OTA protocol spec.</p>"},{"location":"packet_format/","title":"Packet Format","text":"<p>This document describes the MeshCore packet format.</p> <ul> <li><code>0xYY</code> indicates <code>YY</code> in hex notation.</li> <li><code>0bYY</code> indicates <code>YY</code> in binary notation.</li> <li>Bit 0 indicates the bit furthest to the right: <code>0000000X</code></li> <li>Bit 7 indicates the bit furthest to the left: <code>X0000000</code></li> </ul>"},{"location":"packet_format/#version-1-packet-format","title":"Version 1 Packet Format","text":"<p>This is the current version-1 MeshCore wire packet structure. Older firmware may support only a subset of the path encodings and payload types described here.</p> <pre><code>[header][transport_codes(optional)][path_length][path][payload]\n</code></pre> <ul> <li>header - 1 byte<ul> <li>8-bit Format: <code>0bVVPPPPRR</code> - <code>V=Version</code> - <code>P=PayloadType</code> - <code>R=RouteType</code></li> <li>Bits 0-1 - 2-bits - Route Type<ul> <li><code>0x00</code>/<code>0b00</code> - <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> - Flood Routing + Transport Codes</li> <li><code>0x01</code>/<code>0b01</code> - <code>ROUTE_TYPE_FLOOD</code> - Flood Routing</li> <li><code>0x02</code>/<code>0b10</code> - <code>ROUTE_TYPE_DIRECT</code> - Direct Routing</li> <li><code>0x03</code>/<code>0b11</code> - <code>ROUTE_TYPE_TRANSPORT_DIRECT</code> - Direct Routing + Transport Codes</li> </ul> </li> <li>Bits 2-5 - 4-bits - Payload Type<ul> <li><code>0x00</code>/<code>0b0000</code> - <code>PAYLOAD_TYPE_REQ</code> - Request (destination/source hashes + MAC)</li> <li><code>0x01</code>/<code>0b0001</code> - <code>PAYLOAD_TYPE_RESPONSE</code> - Response to <code>REQ</code> or <code>ANON_REQ</code></li> <li><code>0x02</code>/<code>0b0010</code> - <code>PAYLOAD_TYPE_TXT_MSG</code> - Plain text message</li> <li><code>0x03</code>/<code>0b0011</code> - <code>PAYLOAD_TYPE_ACK</code> - Acknowledgment</li> <li><code>0x04</code>/<code>0b0100</code> - <code>PAYLOAD_TYPE_ADVERT</code> - Node advertisement</li> <li><code>0x05</code>/<code>0b0101</code> - <code>PAYLOAD_TYPE_GRP_TXT</code> - Group text message (unverified)</li> <li><code>0x06</code>/<code>0b0110</code> - <code>PAYLOAD_TYPE_GRP_DATA</code> - Group datagram (unverified)</li> <li><code>0x07</code>/<code>0b0111</code> - <code>PAYLOAD_TYPE_ANON_REQ</code> - Anonymous request</li> <li><code>0x08</code>/<code>0b1000</code> - <code>PAYLOAD_TYPE_PATH</code> - Returned path</li> <li><code>0x09</code>/<code>0b1001</code> - <code>PAYLOAD_TYPE_TRACE</code> - Trace a path, collecting SNR for each hop</li> <li><code>0x0A</code>/<code>0b1010</code> - <code>PAYLOAD_TYPE_MULTIPART</code> - Packet is part of a sequence of packets</li> <li><code>0x0B</code>/<code>0b1011</code> - <code>PAYLOAD_TYPE_CONTROL</code> - Control packet data (unencrypted)</li> <li><code>0x0C</code>/<code>0b1100</code> - <code>PAYLOAD_TYPE_OTA</code> - OTA-over-LoRa firmware distribution</li> <li><code>0x0D</code>/<code>0b1101</code> - reserved</li> <li><code>0x0E</code>/<code>0b1110</code> - reserved</li> <li><code>0x0F</code>/<code>0b1111</code> - <code>PAYLOAD_TYPE_RAW_CUSTOM</code> - Custom packet (raw bytes, custom encryption)</li> </ul> </li> <li>Bits 6-7 - 2-bits - Payload Version<ul> <li><code>0x00</code>/<code>0b00</code> - v1 - 1-byte src/dest hashes, 2-byte MAC</li> <li><code>0x01</code>/<code>0b01</code> - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)</li> <li><code>0x02</code>/<code>0b10</code> - v3 - Future version</li> <li><code>0x03</code>/<code>0b11</code> - v4 - Future version</li> </ul> </li> </ul> </li> <li><code>transport_codes</code> - 4 bytes (optional)<ul> <li>Only present for <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> and <code>ROUTE_TYPE_TRANSPORT_DIRECT</code></li> <li><code>transport_code_1</code> - 2 bytes - <code>uint16_t</code> - calculated from region scope</li> <li><code>transport_code_2</code> - 2 bytes - <code>uint16_t</code> - reserved</li> </ul> </li> <li><code>path_length</code> - 1 byte - Encoded path metadata<ul> <li>Bits 0-5 store path hash count / hop count (<code>0-63</code>)</li> <li>Bits 6-7 store path hash size minus 1<ul> <li><code>0b00</code>: 1-byte path hashes</li> <li><code>0b01</code>: 2-byte path hashes</li> <li><code>0b10</code>: 3-byte path hashes</li> <li><code>0b11</code>: reserved / unsupported</li> </ul> </li> </ul> </li> <li><code>path</code> - <code>hop_count * hash_size</code> bytes - Path to use for Direct Routing or flood path tracking<ul> <li>Up to a maximum of 64 bytes, defined by <code>MAX_PATH_SIZE</code></li> <li>Effective byte length is calculated from the encoded hop count and hash size, not taken directly from <code>path_length</code></li> <li>v1.12.0 firmware and older only handled legacy 1-byte path hashes and dropped packets whose path bytes exceeded 64 bytes</li> </ul> </li> <li><code>payload</code> - variable length - Payload Data<ul> <li>Up to a maximum 184 bytes, defined by <code>MAX_PACKET_PAYLOAD</code></li> <li>Generally this is the remainder of the raw packet data</li> <li>The firmware parses this data based on the provided Payload Type</li> <li>v1.12.0 firmware and older drops packets with <code>payload</code> sizes larger than 184</li> </ul> </li> </ul>"},{"location":"packet_format/#packet-format_1","title":"Packet Format","text":"Field Size (bytes) Description header 1 Contains routing type, payload type, and payload version transport_codes 4 (optional) 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) path_length 1 Encodes path hash size in bits 6-7 and hop count in bits 0-5 path up to 64 (<code>MAX_PATH_SIZE</code>) Stores <code>hop_count * hash_size</code> bytes of path data if applicable payload up to 184 (<code>MAX_PACKET_PAYLOAD</code>) Data for the provided Payload Type <p>NOTE: see the Payloads documentation for more information about the content of specific payload types.</p>"},{"location":"packet_format/#header-format","title":"Header Format","text":"<p>Bit 0 means the lowest bit (1s place)</p> Bits Mask Field Description 0-1 <code>0x03</code> Route Type Flood, Direct, etc 2-5 <code>0x3C</code> Payload Type Request, Response, ACK, etc 6-7 <code>0xC0</code> Payload Version Versioning of the payload format"},{"location":"packet_format/#route-types","title":"Route Types","text":"Value Name Description <code>0x00</code> <code>ROUTE_TYPE_TRANSPORT_FLOOD</code> Flood Routing + Transport Codes <code>0x01</code> <code>ROUTE_TYPE_FLOOD</code> Flood Routing <code>0x02</code> <code>ROUTE_TYPE_DIRECT</code> Direct Routing <code>0x03</code> <code>ROUTE_TYPE_TRANSPORT_DIRECT</code> Direct Routing + Transport Codes"},{"location":"packet_format/#path-length-encoding","title":"Path Length Encoding","text":"<p><code>path_length</code> is not a raw byte count. It packs both hash size and hop count:</p> Bits Field Meaning 0-5 Hop Count Number of path hashes (<code>0-63</code>) 6-7 Hash Size Code Stored as <code>hash_size - 1</code> <p>Hash size codes:</p> Bits 6-7 Hash Size Notes <code>0b00</code> 1 byte Legacy / default mode <code>0b01</code> 2 bytes Supported in current firmware <code>0b10</code> 3 bytes Supported in current firmware <code>0b11</code> 4 bytes Reserved / invalid <p>Examples:</p> <ul> <li><code>0x00</code>: zero-hop packet, no path bytes</li> <li><code>0x05</code>: 5 hops using 1-byte hashes, so path is 5 bytes</li> <li><code>0x45</code>: 5 hops using 2-byte hashes, so path is 10 bytes</li> <li><code>0x8A</code>: 10 hops using 3-byte hashes, so path is 30 bytes</li> </ul>"},{"location":"packet_format/#payload-types","title":"Payload Types","text":"Value Name Description <code>0x00</code> <code>PAYLOAD_TYPE_REQ</code> Request (destination/source hashes + MAC) <code>0x01</code> <code>PAYLOAD_TYPE_RESPONSE</code> Response to <code>REQ</code> or <code>ANON_REQ</code> <code>0x02</code> <code>PAYLOAD_TYPE_TXT_MSG</code> Plain text message <code>0x03</code> <code>PAYLOAD_TYPE_ACK</code> Acknowledgment <code>0x04</code> <code>PAYLOAD_TYPE_ADVERT</code> Node advertisement <code>0x05</code> <code>PAYLOAD_TYPE_GRP_TXT</code> Group text message (unverified) <code>0x06</code> <code>PAYLOAD_TYPE_GRP_DATA</code> Group datagram (unverified) <code>0x07</code> <code>PAYLOAD_TYPE_ANON_REQ</code> Anonymous request <code>0x08</code> <code>PAYLOAD_TYPE_PATH</code> Returned path <code>0x09</code> <code>PAYLOAD_TYPE_TRACE</code> Trace a path, collecting SNR for each hop <code>0x0A</code> <code>PAYLOAD_TYPE_MULTIPART</code> Packet is part of a sequence of packets <code>0x0B</code> <code>PAYLOAD_TYPE_CONTROL</code> Control packet data (unencrypted) <code>0x0C</code> <code>PAYLOAD_TYPE_OTA</code> OTA-over-LoRa firmware distribution <code>0x0D</code> reserved reserved <code>0x0E</code> reserved reserved <code>0x0F</code> <code>PAYLOAD_TYPE_RAW_CUSTOM</code> Custom packet (raw bytes, custom encryption)"},{"location":"packet_format/#payload-versions","title":"Payload Versions","text":"Value Version Description <code>0x00</code> 1 1-byte src/dest hashes, 2-byte MAC <code>0x01</code> 2 Future version (e.g., 2-byte hashes, 4-byte MAC) <code>0x02</code> 3 Future version <code>0x03</code> 4 Future version"},{"location":"pair_4p6_300us_validation/","title":"SF7/62.5 + SF8/500: 4.6 slow chirps, 0.3 ms reserve","text":"<p>User-requested follow-up to the original pair test. Completed 2026-09-15 00:21:27\u201300:23:52 UTC (September 14 local time).</p>"},{"location":"pair_4p6_300us_validation/#result","title":"Result","text":"Profile Requested dwell Stationary control Scanning received Slow: SF7 / 62.5 kHz 9.421 ms, approximately 4.6 chirps 100/100 97/100 Fast: SF8 / 500 kHz 21.847 ms, approximately 42.67 chirps 100/100 100/100 <p>Full scan: 197/200 (98.5%), not lossless. All three misses were slow-profile timeouts with no device error and the chip still in RX. The collector completed every scheduled probe, with no RF retry, retune/reset on a miss, or early stop. The two controls plus the scan contain 400 unique probes; each fixed transmitter acknowledged exactly 200 packets. There were no USB result replays.</p> <p>This is one finite sample. It does not establish that 4.6 is inherently worse than 4.1 or better than 5.1, nor identify the cause of the three losses.</p>"},{"location":"pair_4p6_300us_validation/#timing-and-unchanged-conditions","title":"Timing and unchanged conditions","text":"<ul> <li>Reserve: 300 us; nominal switching allowance: 600 us per hop. Neither is an   added settling delay. Nominal cycle: 9.421 + 21.847 + 1.200 = 32.468 ms.</li> <li>Actual switching across 3,957 hops: 0.582 ms mean, 0.827 ms maximum.   Direction means: 0.586 ms toward slow, 0.578 ms toward fast.</li> <li>Five-second RX-only switching window: 0.559 ms mean, 0.779 ms maximum.</li> <li>Non-packet-held cycle: 32.428 ms mean, 34.242 ms maximum. These samples can   still include USB/loop scheduling overruns; the reserve is not a hard bound.</li> <li>Observed non-held dwell means: slow 9.426 ms, fast 21.855 ms; maxima 10.480   and 23.474 ms respectively. No per-loss timing trace was collected.</li> <li>Successful-packet mean SNR: slow +12.27 dB, fast +13.47 dB; mean RSSI:   -20.87 and -18.99 dBm. These remain strong-signal lab conditions.</li> </ul> <p>Same V4 RX, RAK4631 slow TX and T1000-E/LR1110 fast TX; 909.5/910.5 MHz, CR4/5, explicit header, CRC, 32-symbol preambles, 16-byte synthetic payloads, -9 dBm chip TX power, normal RX gain 0x94, randomized interleaving and 10\u2013180 ms arrival delays. Only one transmitter sends at a time. Each TX configures once; every packet has zero frequency/modulation writes.</p> <p>The single-pass production guarded switching path uses warm XOSC and buffered 8 MHz SPI. Each hop issued exactly one frequency and one modulation command, with one optimized RX restart. No double writes, detours, rollback, added settling, off-channel acceptance, cache errors, RX errors or retune failures. As before, this is a small HIL application, not full production UI/network load.</p>"},{"location":"pair_4p6_300us_validation/#verification-and-artifacts","title":"Verification and artifacts","text":"<p>Only the V4 application was updated. Exact USB identity/MAC, idle ownership and existing partition metadata were checked before writing. The nRF52 transmitter images, bootloaders, SoftDevices, gateway and unrelated radios were not flashed. All three test radios were rebooted and verified idle afterward; HIL firmware was left installed. ModemManager was restored active, gateway and host CLI services are active, and the previously paused memory soak remains inactive.</p> <ul> <li>Raw capture, SHA-256   <code>1c2e0eae3f304fcaeb6addfeef4f2f09a3c2bec8d78c60d3f151c952d0f6d5f5</code>.</li> <li>Independent offline validation   checks complete samples, unique sequences, sender lifetime counts, actual   RX frequency/SF/BW/payload, command counts, policies and idle cleanup.</li> <li>Manifest records the   receiver image/source hashes and prior transmitter-manifest hash. Bundle   SHA-256 <code>fb7a08536ed06e36cf7d5c29babbe2affb30183de05918c4db271b98b796e579</code>.</li> <li>Remote records remain under   <code>/home/mikec/hwtest/runs/pair-sf8-32-4p6-300us-20260914</code>.</li> <li>Receiver build passed. HIL host regression suite: 64/64 passed; new plan   guards and the exact dwell/budget arithmetic are covered. Python compile and   scoped whitespace checks passed. Collector/wrapper exit zero.</li> </ul> <p>No production timing defaults changed, and no commit or push was made.</p>"},{"location":"pair_preamble32_validation/","title":"SF7/62.5 + SF8/500, fast switching and preamble 32","text":"<p>User-requested hardware validation, 2026-09-14. This is a finite HIL experiment, not a production reliability guarantee. No production timing defaults or automatic-preamble overrides are changed by this test.</p>"},{"location":"pair_preamble32_validation/#fixture-and-method","title":"Fixture and method","text":"<ul> <li>Heltec V4 receiver, USB serial <code>44:1B:F6:69:CF:98</code>, normal chip RX gain (0x94).</li> <li>RAK4631 <code>9AB3B64C641BA927</code>: stationary transmitter at 909.5 MHz, SF7/62.5 kHz.</li> <li>T1000-E/LR1110 <code>34A9141999729D5D</code>: stationary transmitter at 910.5 MHz, SF8/500 kHz.</li> <li>CR4/5, explicit header, CRC, 32-symbol preamble, synthetic 16-byte sequence-tagged   payloads. -9 dBm chip output. Only one transmitter sends at a time on host request.</li> <li>Each transmitter initializes its assigned settings once. RF-frequency and   modulation-command counters must remain unchanged for every TX call.</li> <li>100 fixed-channel controls per profile before scanning. Require 100/100 on   both before making a scan-timing inference.</li> <li>Three scanner settings, 100 packets per profile per setting, randomized   interleaving and 10\u2013180 ms arrival delays. A miss does not cause a retry,   retune, reset, or early end of the finite sample. The scan expectation expires   after 1000 ms, far longer than the test frame and randomized host delay.</li> </ul> Case Loop reserve (not a delay) Slow visit Fast visit 4.1-chirp floor 0 ms 8.397 ms 23.171 ms Spare time used for 5.1 slow chirps 0 ms 10.445 ms 21.123 ms Previous reserve comparison 4 ms 8.397 ms 19.171 ms <p>The 5.1 case reallocates 2.048 ms from the fast visit to the slow visit; it does not increase the nominal cycle. The 4 ms reserve is omitted from the first two cases. The theoretical switch allowance is 0.6 ms per hop; actual switching is measured, never forced to equal that allowance. Changed SF/BW requires one modulation command per hop; frequency-only cache-hit timings do not apply.</p> <p>The scheduler uses the same asymmetric two-profile visit budget and the actual production guarded <code>tuneProfile()</code> / fast RX implementation, but runs in a small RAM-only HIL application, without the full production networking/UI load. All retunes are single-pass, warm-XOSC, buffered 8 MHz SPI, zero added settling; double frequency writes, detours and rollback experiments are off. Packet/busy ownership guards are retained. Explicit 32 on both sides bypasses the historical automatic SF8/500 88-symbol rule without removing it from production.</p> <p>The selected radios already had disposable HIL firmware. Updates are application-only: matching nRF52 SoftDevice IDs/address ranges and exact USB serial/topology are checked. V4 partition metadata is read back and compared before its application-only write. No bootloader, SoftDevice, settings backup, gateway firmware or unrelated radio is changed. Prior images/captures remain.</p>"},{"location":"pair_preamble32_validation/#results","title":"Results","text":"<p>Finished all 800 unique probes, 2026-09-15 00:04:54\u201300:11:19 UTC (September 14 local time). Both stationary controls passed 100/100. All three scans completed their full 100-packet sample per profile. No scan achieved 200/200.</p> Case SF7/62.5 received SF8/500 received Total Switch mean / max Idle cycle mean / max 4.1 chirps, no loop reserve 99/100 100/100 199/200 0.581 / 0.829 ms 32.717 / 34.733 ms 5.1 chirps, no loop reserve 100/100 97/100 197/200 0.572 / 0.834 ms 32.706 / 34.978 ms 4.1 chirps, 4 ms loop reserve 97/100 99/100 196/200 0.567 / 0.836 ms 28.701 / 31.195 ms <p>Switch timing includes every successful hop during each stage, including post-reception hops. The RX-only five-second windows averaged 0.554 ms per hop. The largest observed switch was 0.836 ms: 0.6 ms is a nominal allowance, not a measured worst-case bound. Direction-specific timing is in the validated capture. Idle-cycle samples exclude packet-held visits but still include USB command/loop scheduling; their occasional roughly 2 ms overshoots are real.</p> <p>Every scan hop issued exactly one RF-frequency and one modulation command, with one optimized RX restart. There were zero added settling delays, double passes, frequency repeats, RF retries, USB result replays, device errors, retune failures, RX mode errors, cache errors or off-channel acceptances. All eight missed packets were sequence-matched RX timeouts with the receiver still in RX mode and no device error. Both transmitters acknowledged exactly 400 transmissions and zero frequency/modulation writes during every packet.</p> <p>Successful scan packets had mean SNR approximately +12.0 to +12.1 dB on the slow profile and +12.8 dB on the fast profile. Mean RSSI was approximately -20.4 to -20.7 dBm and -18.5 to -18.9 dBm, respectively. These are strong-signal bench results; the controls passed, but weak-signal performance and possible strong-signal/front-end effects are not established by this test.</p>"},{"location":"pair_preamble32_validation/#what-the-extra-chirp-changes","title":"What the extra chirp changes","text":"<p>An extra SF7/62.5 symbol is 2.048 ms, equivalent to four SF8/500 symbols. Increasing the slow dwell from 4.1 to 5.1 preserves the full-sweep budget by shortening the fast dwell, but increases the fast profile's uninterrupted blind interval. With the nominal 0.6 ms hops, the 32-symbol fast preamble's remaining time after the slow visit plus two hops falls from 6.787 to 4.739 ms (13.26 to 9.26 fast symbols), before acquisition and scheduling overruns. This is a timing-budget calculation, not an experimentally proven acquisition threshold or a per-miss trace.</p> <p>The observed 5.1 sample improved the slow result from 99 to 100, while the fast result fell from 100 to 97. This is consistent with a dwell/acquisition tradeoff; one finite sample per setting does not isolate the cause or establish a statistically reliable ranking. Simply fitting a sweep inside a preamble does not establish lossless acquisition. The 4 ms reserve is an allowance, not a sleep; retaining it also did not produce a lossless result here.</p> <p>Using genuine spare time above the 4.1 floor remains a reasonable policy to investigate, but allocation must protect both profiles' acquisition/return budgets and measured switching/scheduling overruns. Do not automatically spend all of the reserve on longer slow visits, or treat the historic 88-symbol rule as disproven by this nearly-lossless sample. No production defaults or warning formula were changed by this hardware-test turn.</p>"},{"location":"pair_preamble32_validation/#capture-integrity-deployment-and-cleanup","title":"Capture integrity, deployment and cleanup","text":"<ul> <li>Raw capture: profile_pair_sf8_32_results.json,   SHA-256 <code>3472883ade89494b64657486efd1645a04b0a3bebfd0a2e31bbf914341ad792f</code>.</li> <li>Independent offline checks: profile_pair_sf8_32_validated.json.   Checks all 800 unique sequences, 100/profile/phase, sender lifetime counts,   actual RX frequency/SF/BW/payload identity, command counts, policies and cleanup.</li> <li>Manifest records source and image hashes.   Bundle SHA-256 <code>d6cb9ff36be109af8906eddbbe8a4657ca793d1351ec4bf50ebbd4909eed2bba</code>.   Local bundle is <code>out/pair-sf8-32-20260914</code>; remote capture remains under   <code>/home/mikec/hwtest/runs/pair-sf8-32-20260914</code>.</li> <li>Initial RAK USB reset returned EPROTO before any firmware write. The preserved   pre-write record   has an empty writes list. Inspection confirmed the exact RAK serial/topology   in its documented CDC-only bootloader PID 0x002A. Deployment was revised to   accept that identity (and reset-time disconnect only after exact bootloader   re-enumeration); no permission check or board-identity check was bypassed.   The revision hash and all three successful application-only writes are saved   in the deployment records. No bootloader or SoftDevice was replaced.</li> <li>All three radios were rebooted and live-verified idle, with test firmware left   installed. ModemManager was restored active; gateway and host CLI services   remained active. The preexisting memory soak remains inactive. No unrelated   radio was flashed. Wrapper exit was zero.</li> <li>All three HIL firmware builds passed, run sequentially. The HIL host regression   suite passed 63/63 tests, including the new plan and packet-policy tests.   Python compile checks and scoped <code>git diff --check</code> passed. No commit or push.</li> </ul>"},{"location":"pair_preamble32_validation/#follow-up","title":"Follow-up","text":"<p>The requested 4.6-chirp / 0.3 ms reserve follow-up completed 197/200 scanning packets: slow 97/100, fast 100/100, after fresh 100/100 controls on both profiles. Its captures are separate from this run.</p>"},{"location":"payloads/","title":"Payload Format","text":"<p>Inside each MeshCore Packet is a payload, identified by the payload type in the packet header. The types of payloads are:</p> <ul> <li>Request, response, and plain text (<code>0x00</code>-<code>0x02</code>).</li> <li>Acknowledgment and node advertisement (<code>0x03</code>-<code>0x04</code>).</li> <li>Group text and group datagram (<code>0x05</code>-<code>0x06</code>).</li> <li>Anonymous request and returned path (<code>0x07</code>-<code>0x08</code>).</li> <li>Trace, multipart, control, and OTA (<code>0x09</code>-<code>0x0C</code>).</li> <li>Custom raw data (<code>0x0F</code>).</li> </ul> <p>This document describes the shared payload envelopes implemented by the core. Application-specific request, response, control, and custom bodies can add their own formats.</p> <p>NOTE: all 16 and 32-bit integer fields are Little Endian.</p>"},{"location":"payloads/#important-concepts","title":"Important concepts:","text":"<ul> <li>Node hash: the first byte of the node's public key</li> </ul>"},{"location":"payloads/#node-advertisement","title":"Node advertisement","text":"<p>This kind of payload notifies receivers that a node exists, and gives information about the node</p> Field Size (bytes) Description public key 32 Ed25519 public key of the node timestamp 4 unix timestamp of advertisement signature 64 Ed25519 signature of public key, timestamp, and app data appdata rest of payload optional, see below <p>Appdata</p> Field Size (bytes) Description flags 1 specifies which of the fields are present, see below latitude 4 (optional) decimal latitude multiplied by 1000000, integer longitude 4 (optional) decimal longitude multiplied by 1000000, integer feature 1 2  (optional) reserved for future use feature 2 2  (optional) reserved for future use name rest of appdata name of the node <p>Appdata Flags</p> Value Name Description <code>0x01</code> is chat node advert is for a chat node <code>0x02</code> is repeater advert is for a repeater <code>0x03</code> is room server advert is for a room server <code>0x04</code> is sensor advert is for a sensor server <code>0x10</code> has location appdata contains lat/long information <code>0x20</code> has feature 1 Reserved for future use. <code>0x40</code> has feature 2 Reserved for future use. <code>0x80</code> has name appdata contains a node name"},{"location":"payloads/#acknowledgement","title":"Acknowledgement","text":"<p>An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the \"extra\" payload (see Returned Path) instead of as a separate acknowledgement packet. Current <code>CLI_DATA</code> commands do not cause acknowledgement responses, neither discrete nor extra; their text reply is the application-level result. Repeaters still ACK the legacy plain-text form before processing it.</p> <p>Repeater remote CLI keeps one volatile copy of the most recently completed reply, keyed by the authenticated sender, request timestamp, and command text. Repeating that same logical request re-sends the text reply without executing the command again. A retry must therefore preserve the original timestamp and command text. The cache is cleared by reboot and replaced by the next completed remote command; commands that intentionally produce no text reply remain silent.</p> Field Size (bytes) Description checksum 4 CRC checksum of message timestamp, text, and sender pubkey"},{"location":"payloads/#returned-path-request-response-and-plain-text-message","title":"Returned path, request, response, and plain text message","text":"<p>Returned path, request, response, and plain text messages are all formatted in the same way. See the subsection for more details about the ciphertext's associated plaintext representation.</p> Field Size (bytes) Description destination hash 1 first byte of destination node public key source hash 1 first byte of source node public key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted message, see subsections below for details"},{"location":"payloads/#returned-path","title":"Returned path","text":"<p>Returned path messages provide a description of the route a packet took from the original author. Receivers will send returned path messages to the author of the original message.</p> Field Size (bytes) Description path descriptor 1 low 6 bits are the hash count; high 2 bits encode hash size minus one path count \u00d7 size encoded node-hash prefixes, each 1-3 bytes; the four-byte code is reserved extra type 1 low nibble is the bundled payload type, such as acknowledgment or response; high nibble is reserved extra rest of data extra, bundled payload content, follows same format as main content defined by this document"},{"location":"payloads/#request","title":"Request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) request data rest of payload application-defined request payload body <p>For the common chat/server helpers in <code>BaseChatMesh</code>, the current request type values are:</p> Value Name Description <code>0x01</code> get stats get stats of repeater or room server <code>0x02</code> keepalive keep-alive request used for maintained connections"},{"location":"payloads/#get-stats","title":"Get stats","text":"<p>Gets information about the node, possibly including the following:</p> <ul> <li>Battery level (millivolts)</li> <li>Current transmit queue length</li> <li>Current free queue length</li> <li>Last RSSI value</li> <li>Number of received packets</li> <li>Number of sent packets</li> <li>Total airtime (seconds)</li> <li>Total uptime (seconds)</li> <li>Number of packets sent as flood</li> <li>Number of packets sent directly</li> <li>Number of packets received as flood</li> <li>Number of packets received directly</li> <li>Error flags</li> <li>Last SNR value</li> <li>Number of direct route duplicates</li> <li>Number of flood route duplicates</li> <li>Number posted (?)</li> <li>Number of post pushes (?)</li> </ul>"},{"location":"payloads/#get-telemetry-data","title":"Get telemetry data","text":"<p>Not defined in <code>BaseChatMesh</code>. Sensor- and application-specific request payloads may be implemented by higher-level firmware.</p>"},{"location":"payloads/#get-telemetry","title":"Get Telemetry","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-minmaxave-sensor-nodes","title":"Get Min/Max/Ave  (Sensor nodes)","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-access-list","title":"Get Access List","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-neighbors","title":"Get Neighbors","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#get-owner-info","title":"Get Owner Info","text":"<p>Not defined in <code>BaseChatMesh</code>.</p>"},{"location":"payloads/#response","title":"Response","text":"Field Size (bytes) Description content rest of payload application-defined response body <p>Response contents are opaque application data. There is no single generic response envelope beyond the encrypted payload wrapper shown above.</p>"},{"location":"payloads/#plain-text-message","title":"Plain text message","text":"Field Size (bytes) Description timestamp 4 send time (unix timestamp) txt_type + attempt 1 upper six bits are txt_type (see below), lower two bits are attempt number (0..3) message rest of payload the message content, see next table <p>txt_type</p> Value Description Message content <code>0x00</code> plain text message the plain text of the message <code>0x01</code> CLI data CLI command OR reply text <code>0x02</code> signed plain text message first four bytes is sender pubkey prefix, followed by plain text message <code>0x03</code> CLI command (since v1.18+) CLI command text (explicit) <p>For a room post, companion firmware uses its own monotonic clock for the on-air timestamp and preserves that timestamp across application retries. Room servers track post timestamps separately from login, request, and CLI traffic. They also remember recent accepted posts by sender, timestamp, and text: an exact retry is ACKed again without storing a duplicate, while stale or same-timestamp mismatches are rejected.</p>"},{"location":"payloads/#anonymous-request","title":"Anonymous request","text":"Field Size (bytes) Description destination hash 1 first byte of destination node public key public key 32 sender's Ed25519 public key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted message, see below for details"},{"location":"payloads/#room-server-login","title":"Room server login","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) sync timestamp 4 sender's \"sync messages SINCE x\" timestamp password rest of message password for room"},{"location":"payloads/#repeatersensor-login","title":"Repeater/Sensor login","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) password rest of message password for repeater/sensor"},{"location":"payloads/#repeater-regions-request","title":"Repeater - Regions request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) req type 1 0x01 (request sub type) reply path len 1 path len for reply reply path (variable) reply path"},{"location":"payloads/#repeater-owner-info-request","title":"Repeater - Owner info request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) req type 1 0x02 (request sub type) reply path len 1 path len for reply reply path (variable) reply path"},{"location":"payloads/#repeater-clock-and-status-request","title":"Repeater - Clock and status request","text":"Field Size (bytes) Description timestamp 4 sender time (unix timestamp) req type 1 0x03 (request sub type) reply path len 1 path len for reply reply path (variable) reply path"},{"location":"payloads/#group-text-message","title":"Group text message","text":"Field Size (bytes) Description channel hash 1 first byte of SHA256 of channel's shared key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted message, see below for details <p>The plaintext contained in the ciphertext matches the format described in plain text message. Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be <code>0x00</code> because it is a \"plain text message\". The message will be of the form <code>&lt;sender name&gt;: &lt;message body&gt;</code> (eg., <code>user123: I'm on my way</code>).</p> <p>The sender name is unverified message text. Group messages contain no sender signature, so any channel-key holder can choose any sender name.</p>"},{"location":"payloads/#group-datagram","title":"Group datagram","text":"Field Size (bytes) Description channel hash 1 first byte of SHA256 of channel's shared key cipher MAC 2 MAC for encrypted data in next field ciphertext rest of payload encrypted data, see below for details <p>The data contained in the ciphertext uses the format below:</p> Field Size (bytes) Description data type 2 Identifier for type of data. (See number_allocations.md) data len 1 byte length of data data rest of payload (depends on data type)"},{"location":"payloads/#control-data","title":"Control data","text":"Field Size (bytes) Description flags 1 upper 4 bits is sub_type data rest of payload typically unencrypted data"},{"location":"payloads/#discover_req-sub_type","title":"DISCOVER_REQ (sub_type)","text":"Field Size (bytes) Description flags 1 0x8 (upper 4 bits), prefix_only (lowest bit) type_filter 1 bit for each ADV_TYPE_* tag 4 randomly generate by sender since 4 (optional) epoch timestamp (0 by default)"},{"location":"payloads/#discover_resp-sub_type","title":"DISCOVER_RESP (sub_type)","text":"Field Size (bytes) Description flags 1 0x9 (upper 4 bits), node_type (lower 4) snr 1 signed, SNR*4 tag 4 reflected back from DISCOVER_REQ pubkey 8 or 32 node's ID (or prefix)"},{"location":"payloads/#trace","title":"Trace","text":"<p>Trace packets use direct routing. Their normal direct-path header is empty; instead, the intended route follows a fixed nine-byte trace header in the payload. Each forwarding node appends its received SNR multiplied by four to the packet's route-accumulator field.</p> Field Size (bytes) Description tag 4 Sender-selected trace identifier. auth code 4 Application-defined authentication/correlation value. flags 1 Low two bits encode the route hash size. Current senders use the legacy <code>1 &lt;&lt; value</code> interpretation (1, 2, 4, or 8 bytes); receivers also accept the packed 1-4-byte interpretation where it is unambiguous. route rest Concatenated node-hash prefixes for the requested direct route. <p>At the destination, the application receives the tag, auth code, flags, accumulated SNR bytes, and original route bytes. Trace therefore differs from a normal direct packet whose path is carried entirely in the packet route field.</p>"},{"location":"payloads/#multipart","title":"Multipart","text":"<p>The first payload byte identifies the inner payload and how many packets remain:</p> Field Size (bytes) Description remaining + type 1 Upper nibble is the remaining-packet count; lower nibble is the inner payload type. inner data rest Data for the inner payload type. <p>The core currently creates and consumes multipart acknowledgments. For that form, the low nibble is <code>0x03</code> and the next four bytes are the acknowledgment CRC. Other multipart inner types are reserved for application or future use.</p>"},{"location":"payloads/#ota","title":"OTA","text":"<p>An OTA payload contains one OTA protocol message and is normally sent by flood. Its message types, integrity fields, and transfer state are defined in the OTA-over-LoRa protocol. Builds without OTA support can still relay an opaque OTA packet when their routing policy permits it.</p>"},{"location":"payloads/#custom-packet","title":"Custom packet","text":"<p>Custom packets have no defined format.</p>"},{"location":"pr7_review_validation/","title":"PR #7 review and validation","text":"<p>Validated on 2026-09-10 against integration commit <code>fa010196b130dee9a8a6fc6325d794e2f4fb9ede</code>, which combines base <code>01cc7b8a</code> with PR head <code>c002966c</code> and the review fixes. This includes the stacked ESP32 memory changes already present in PR #7.</p>"},{"location":"pr7_review_validation/#review-fixes","title":"Review fixes","text":"<ul> <li>Use the published ExpressLRS Linkflow calibration,   expose 17\u201330 dBm, and retain the fixed +2 dBm radio drive and correct RF output   after radio recovery. Propagate startup and radio-setting failures.</li> <li>Keep Linkflow LoRa OTA enabled, as intended by the added repeater target.</li> <li>Preserve stored ACLs and flood filters when allocation fails. Release owned   buffers and prevent accidental shallow copies of their owners.</li> <li>Release heap OTA workspaces after self-serving windows; retain them for active   transfers, manual staging, folder operations, and pending application. Service   cleanup on Companions and reset staged-resume flags when a context disappears.</li> <li>Count dynamically allocated clients, filters, and OTA workspaces in the RAM   budget. Respect explicit OTA storage ownership in PlatformIO flags.</li> </ul>"},{"location":"pr7_review_validation/#automated-validation","title":"Automated validation","text":"<ul> <li><code>pio test -e native -e native_kiss_modem</code>: 1,393/1,393 cases passed.</li> <li>Real C++ radio-power, heap-context, ACL persistence/CLI, and shared OTA queue   tests passed. The applicable radio-power, heap-context, and shared-queue tests   also passed on Linux with AddressSanitizer and UndefinedBehaviorSanitizer.</li> <li>Display/inbox, radio receive, static DRAM, and runtime RAM regression tests   passed. ACL allocation-failure coverage verifies that stored clients survive.</li> <li>Sequential firmware builds and their memory gates passed for:   <code>GEPRC_Linkflow_900_repeater</code>, <code>Heltec_v2_companion_radio_ble</code>,   <code>Tbeam_SX1262_repeater_observer_mqtt</code>,   <code>heltec_v4_r8_repeater_observer_mqtt</code>, <code>RAK_4631_repeater</code>, and   <code>SenseCapIndicator-LoRa_companion_radio_full</code>.</li> </ul>"},{"location":"pr7_review_validation/#indicator-hardware-validation","title":"Indicator hardware validation","text":"<p>The original SenseCAP Indicator LoRa with 8 MiB flash and 8 MiB octal PSRAM was reached through the MercerWoodMesh Pi over Wi-Fi. Its MAC, public identity, board reply, and existing partition layout were checked before updating. USB interfaces were absent, so this run does not qualify USB behavior.</p> <p>The Full profile was applied to <code>SenseCapIndicator-LoRa_comp_radio_usb_wifi</code>. The exact application is 2,149,208 bytes:</p> <ul> <li>Application SHA-256:   <code>7a2b11e731f946af79d1104818c7993d3897e6d8ec1f0121d27284c0f0c8c665</code></li> <li>ELF SHA-256, also verified in the application descriptor:   <code>24e60c7785a7aefe3fb0536b0b595bf19e1264e4d5f100d201290dc95eb1761a</code></li> </ul> <p>This direct profile build uses the repository's default <code>v1.17.1</code> version text and <code>14 Aug 2026</code> build-date text; the hashes above identify the tested image.</p> <p>The Wi-Fi updater returned HTTP 200 and booted the application in <code>app1</code> at <code>0x400000</code>. The previous application remains in <code>app0</code> at <code>0x10000</code>; the partition table, NVS, and SPIFFS were not rewritten. Public identity, radio parameters, and USB logging preference matched their pre-update values.</p> <p>The existing Companion stress harness, using a TCP socket adapter, completed 100 persistent cycles and 100 reconnects in 109.9 seconds: 501 requests and 501 validated responses, with no discarded bytes, malformed frames, or device error flags. Device info, time, storage, and core statistics were exercised. The text terminal exposed all four display-power controls and <code>display.inbox</code>. The OTA folder service issued a valid <code>COUNT</code> request, received an empty-folder reply, and returned to its disconnected state after the client closed.</p> <p>After these checks, four memory snapshots showed 69,548\u201369,996 bytes of free internal heap and a 61,428-byte largest block. PSRAM availability stayed at 6,408,731 bytes. Final uptime was 262 seconds, with zero error flags and an empty outbound queue. This is a short regression check, not a long-term soak. Raw baseline, upload, stress, and final-state records are retained on the Pi under <code>/home/mikec/hwtest/runs/pr7-review/</code>.</p> <p>No Linkflow module or RF power meter was available in this run. Linkflow power calibration is supported by the pinned upstream table and executable driver tests, not a physical RF output measurement. The Indicator's ESP32-S3 does not exercise the classic ESP32 heap-OTA default; host tests and classic ESP32 builds cover that path. Physical display readability was not inspected.</p>"},{"location":"preamble_detection_investigation/","title":"Off-channel preamble investigation","text":"<p>Measured 2026-09-14. The SF8 off-channel preamble indication reproduces with a stationary, fully initialized receiver, without profile hopping or fast RX reuse. Both boards reproduce it when their transmitter/receiver roles are reversed. This is evidence of transmitter-associated off-channel detection in this close-range bench setup, not evidence that the channel jump needs more settling time.</p> <p>The earlier SF8 scan's long software guard explains its missed listening opportunity. The earlier SF6 scan miss remains unresolved: its trace had no preamble indication or guard hold. No production guard or acquisition policy was changed during this investigation.</p>"},{"location":"preamble_detection_investigation/#controlled-experiment","title":"Controlled experiment","text":"<ul> <li>XIAO ESP32-S3 + WIO SX1262 (COM31) and SenseCAP Indicator ESP32-S3 LoRa   (COM28). The Indicator RP2040 and RAK4631 were not modified.</li> <li>Receiver fixed at 910.000 MHz. Transmitter silent, on frequency, or offset   by +/-250, +/-500 or +/-1,000 kHz. These are offsets, not bandwidths.</li> <li>125 kHz bandwidth, SF8 or SF6, CR4/5, 32 programmed preamble symbols,   -9 dBm, one 16-byte sequence-tagged synthetic payload per transmitting case.</li> <li>Each case fully initializes both radios. RX uses ordinary <code>startReceive()</code>;   profile-switch optimization and experimental omission masks are disabled.   Buffered 8 MHz SPI remains enabled. No hops, warm-retune reuse, CAD, or   <code>isReceiving()</code> software guard runs during these controls.</li> <li>TX is prepared before RX is armed. Each receive window lasts 450 ms;   all eight cases are shuffled within each balanced round, seed 814910.   The full RX window completes even when an off-frequency packet is not   received, as expected. An on-frequency positive-control failure stops the   experiment. No RF retransmissions are used to repair a result.</li> <li>The HAL records actual outgoing <code>SetRfFrequency</code> bytes on both boards,   and the frequency word present at <code>SetTx</code>. The host verifies these words   against the requested frequencies. This checks commands sent to the chip,   not an independent measurement of the emitted RF spectrum.</li> <li>Existing IRQ replies are observed and IRQs additionally polled at a nominal   64 us interval. Events are buffered in RAM; timestamps are software   observations, not synchronized RF arrival times. Unknown payload contents   are not exported.</li> </ul> <p>The three completed matrices contain 128 windows: 112 transmitted probes and 16 silent controls. A separate initial 450 ms receiver-only smoke check was also performed. These are bounded diagnostic controls, not another 100-packets-per-channel capacity sweep.</p>"},{"location":"preamble_detection_investigation/#results","title":"Results","text":"<p>Entries below are windows with a preamble indication / tested windows. Each positive window reported one indication; latched IRQs do not count continuous detector activity or prove a valid packet.</p> Transmitter offset SF8, XIAO RX SF8, Indicator RX SF6, XIAO RX Silent 0/8 0/4 0/4 On frequency 8/8 4/4 4/4 -250 kHz 8/8 4/4 1/4 +250 kHz 8/8 4/4 0/4 -500 kHz 5/8 3/4 0/4 +500 kHz 1/8 3/4 0/4 -1,000 kHz 5/8 4/4 0/4 +1,000 kHz 5/8 3/4 0/4 <p>All 16 on-frequency probes delivered valid payloads. None of the 96 off-frequency probes delivered a valid payload. No silent control detected a preamble. Completed windows ended in RX mode with zero device errors; there were no foreign valid payloads or trace overflows.</p> <p>Most off-frequency detections stopped at <code>PreambleDetected</code> (0x0004). Four progressed further but failed CRC (<code>seen_irq=0x0056</code>: preamble, header, RxDone, CRC error): two at +250 kHz with XIAO RX, and one each at +250 and +1,000 kHz with Indicator RX. Therefore HeaderValid alone would not prove that these off-frequency indications are legitimate traffic.</p> <p>In forward SF8 on-frequency controls, instantaneous RSSI at the first preamble was -42 to -41 dBm; at +/-250 kHz it was -91 to -88 dBm. These are instantaneous receiver readings, not calibrated measurements of transmitted leakage or a sensitivity test. Board positions and attenuation were not systematically varied. Reversing roles reproduces the behavior but does not isolate its physical path.</p>"},{"location":"preamble_detection_investigation/#what-this-explains","title":"What this explains","text":"<p>The earlier SF8 four-channel scan missed probe 13 on 910.250 MHz after detecting a bare preamble while tuned to 910.000 MHz. The existing <code>CustomSX1262::isReceiving()</code> guard allowed 91 ms for preamble progression, consistent with the observed 92.257 ms from first preamble observation to the stale-bit clear. That produced approximately 102 ms total occupancy on the wrong channel and a 135.145 ms target-channel revisit gap. The programmed 32-symbol preamble lasted only 65.536 ms.</p> <p>The delayed retune itself took 550 us. These controls reproduce the suspect off-frequency indication with no retunes at all. Together the evidence supports off-channel acquisition plus a long guard hold as the SF8 failure mechanism, rather than slow SPI or a demonstrated need for a longer post-jump delay. It does not independently prove the RF source of that one historical scan event.</p> <p>The controlled-transmitter association and quiet silent controls make random ambient RF alone an inadequate explanation of the repeated bench result. Exact RF cause remains unmeasured: receiver selectivity/false acquisition, transmitter spectral leakage, and coupling between the nearby boards are not separated by these tests. No spectrum-analyzer capture or calibrated attenuation sweep was performed. Increasing channel spacing is not established as a fix: SF8 indications also occurred at +/-1 MHz.</p> <p>The earlier SF6 miss had no observed nonzero IRQ or guard hold. The four successful stationary SF6 positive controls show the fixed-channel link works, but do not establish the acquisition time needed after a retune. These small, differently sized samples are not packet-error rate estimates or proof of a zero-loss channel count.</p>"},{"location":"preamble_detection_investigation/#follow-up-candidates-not-implemented-fixes","title":"Follow-up candidates, not implemented fixes","text":"<p>Semtech documents that false LoRa detections can occur and describes <code>SetLoRaSymbNumTimeout</code> as validating reception over multiple symbols before continuing when the modem locks. This is a candidate to investigate, not a drop-in verified fix. Its behavior in continuous RX and through each retune must be measured. See section 13.4.9, page 99 of the Semtech SX1261/2 datasheet, revision 2.2.</p> <p>Useful next experiments would qualify/revalidate preambles before granting a long scan hold, and repeat the controls with lower signal levels or increased physical isolation. Any candidate must preserve legitimate weak signals and long preambles. Blindly shortening the current guard, or requiring only a header indication, is not justified by these results. No production radio change was made in this diagnostic turn.</p>"},{"location":"preamble_detection_investigation/#reproduction-provenance-and-checks","title":"Reproduction, provenance, and checks","text":"<p>See the stationary diagnostic instructions. The same diagnostic firmware binaries were used for all three matrices. Base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus local changes; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL targets built and uploaded successfully. All 29 selected host/native tests passed after testing.</p> <p>Raw results and SHA-256:</p> <ul> <li>Forward SF8, eight rounds:   <code>e876a8b1727c5584aa67cb4fcdcae5ca30701e90f7ed998b5df36c37d245f7b0</code></li> <li>Reverse SF8, four rounds:   <code>83b576544f807c6b81ee83a7db487137ef2584cb4981e475c7e7ac50e4fa2363</code></li> <li>Forward SF6, four rounds:   <code>bdb65b4e23d8b05c8523cec092533509021f878518a38523b02135b810da991b</code></li> <li>Aborted initial SF6 launch   is retained: no trials and no RF probes. A host reboot-command quoting   failure left the diagnostic image unready after the preceding run. After   correcting the command and rebooting both boards, the complete SF6 matrix   was recorded to the separate <code>run2</code> path. A subsequent host cleanup change   ensures an already-opened receiver port is closed if opening TX fails.</li> </ul> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>f89da2a2e542df481ff6c26d2492dcc46db8794b5549d3b4f73217767130a21d</code></li> <li>Indicator: <code>e58207c7e63de625bee2d4e4400eb934b2737f51e8babc7c1fddd85c48efdda6</code></li> </ul>"},{"location":"preamble_detection_investigation/#device-handoff","title":"Device handoff","text":"<p>Fresh full 8 MiB backups were taken and separately verified before flashing, in the private current-user MeshCore backup directory. No backup contents or identity/channel secrets are in the diagnostic results.</p> <ul> <li>XIAO backup: <code>5e5825b625a0e6ded65aafa72658eb3b15b466316a9efe8239b2f09de9418e63</code></li> <li>Indicator backup: <code>6f834296d4e29e4fe17297aad0a9e2bf2adcf0a1391cf645de1bc51aebfd70de</code></li> </ul> <p>Both original images were restored after the controls, separately verified against the complete 8 MiB flash with matching digests, and hardware-reset. The RAK4631 and Indicator RP2040 were untouched; the XIAO soak logger was not restarted. The temporary HIL build overlay was removed. Investigation source, tests, and results were initially handed off locally before publication.</p>"},{"location":"preset_test/","title":"Temporary radio test builder","text":"<p>Choose a window and radio tuple to create a shareable temporary-radio test URL.</p> <p>MeshCore \u00b7 default 48-hour temporary preset test</p> Scheduled Starts in \u2014 \u2014 Start End Display time zone Need to leave the test early? <p>Send this command to return to your saved radio settings in one minute:</p> Copy leave command KeyMind firmware and advanced commands <p>         Use these only if your firmware supports the listed commands or you need         dual-radio operation, scheduling, or clock correction.       </p> <p>Firmware schedule epochs: </p> <p>         Primary scheduling requires a Simple Repeater build. Companion         <code>tempradio2</code> and <code>tempradioat2</code> require dual-profile         firmware. If a command is unknown, use only the method your installed         firmware supports.       </p> <p>         Enter the test times in the selected time zone and choose the radio         tuple. The generated URL converts the times to exact UTC instants, keeps         the date punctuation readable, and keeps <code>tz</code> so the page         displays them in the organizer's local time zone.           </p> Start date and time End date and time Selected time zone Detecting browser time zone\u2026                    Use browser time zone                  <p>                 Loading time zone map\u2026               </p>                  Click a region to select its IANA time zone. The initial selection                 comes from <code>tz=</code> when present; otherwise it uses your                 browser's time zone. Map design inspired by                 zones.arilyn.cc;                 boundaries from                 Timezone Boundary Builder                 and \u00a9 OpenStreetMap contributors.                Test radio profile Frequency (MHz) Bandwidth (kHz) 7.810.415.6 20.831.2541.7 62.5125250500 Spreading factor 5678 9101112 Coding-rate denominator 5678 TX output for estimate (dBm) This estimate-only value does not change the TempRadio commands. Generate test URL <p></p> <pre><code></code></pre> Copy generated URL Open generated page <p>         Advanced use: <code>start</code> and <code>end</code> also accept ISO-8601         timestamps with explicit UTC offsets or Unix epoch seconds. If         <code>tz</code> is omitted, the page uses the browser's time zone. The         other URL parameters are <code>freq</code>, <code>bw</code>,         <code>sf</code>, <code>cr</code>, and estimate-only <code>tx</code>.           </p>"},{"location":"preset_test/#preset-test-title","title":"910.100 MHz /             500 kHz /             SF8 /             CR7","text":""},{"location":"preset_test/#stock-test-title","title":"Stock firmware: copy this <code>tempradio</code> command","text":"Copy tempradio command <p>           Before sending it, run <code>get radio</code> and save the result.           No clock setup is needed. Your saved settings return automatically.         </p>"},{"location":"preset_test/#continuity-plan-title","title":"Bridges and early-revert plan","text":"<p>         The test will include bridges. If the Puget Sound area experiences a         widespread power outage or loss of cellular service, we will end the         test early. A stock node's one-minute temporary test profile then ends         on that node's own saved radio settings.       </p>"},{"location":"preset_test/#save-settings-title","title":"Before changing a radio","text":"<p>         Run <code>get radio</code> and record the saved primary tuple. Both         primary TempRadio methods return to that saved tuple; they do not store         a return tuple inside the temporary command. On a Companion, also run         <code>get radio2</code> and <code>get radio2.cross</code> so you can restore         any non-default secondary-profile setup.       </p>"},{"location":"preset_test/#clock-check-title","title":"Check the node clock before scheduling","text":"<p>         The primary <code>tempradioat</code> and Companion         <code>tempradioat2</code> schedulers use UTC Unix time. Run         <code>clock</code> on every node that will be scheduled and compare it         with the browser UTC time below. It should agree to within about a minute.         A wrong clock can start late, start immediately, or cause the schedule to         be rejected.       </p> Browser UTC now \u2014 Browser Unix time \u2014 Node clock reported by <code>clock</code> (UTC, optional)              Paste the node's <code>clock</code> reply immediately after it arrives.             The firmware form <code>02:42 - 22/9/2026 UTC</code> is also accepted.             Leave this blank to keep the normal UTC schedule epochs unchanged.            Apply clock conversion <p>         No node-clock correction is applied. Scheduled commands use the normal UTC epochs.       </p> <p>         This changes only the absolute <code>tempradioat</code> and         <code>tempradioat2</code> epochs shown on this page; it does not issue a         clock-setting command. The correction is for this node and this open page         only: it is never added to generated URLs, and is cleared on reload. If         the node clock later syncs or jumps, delete and queue the schedule again.       </p> Remote admin session <p>             In a MeshCore client that supplies the sender timestamp, sync and             then verify:           </p> <pre><code>clock sync\nclock</code></pre> Local USB or browser console <p>Copy this fresh, run it immediately, and then verify with <code>clock</code>:</p> <pre><code>time 0\nclock</code></pre> Copy current clock command If the clock is ahead and cannot move backward <p>             If setting the correct time returns <code>ERR: clock cannot go backwards</code>,             run the command below. It resets the clock to an older fallback date and             reboots the node immediately, so it sends no reply. After the node reconnects,             copy and run the fresh local clock command above, verify with <code>clock</code>,             and then add the Companion <code>tempradioat2</code> schedule again. The             reboot clears any pending scheduled entries.           </p> <p>             If resetting or correcting this remote node's clock is not safe, leave             it unchanged and use the optional node-clock conversion above instead.           </p> <pre><code>clkreboot</code></pre> Copy clock reset command <p>         The Companion schedule must be queued while both its start and end are         in the future and within the firmware's roughly 24-day scheduling         horizon. Scheduled entries are held in RAM and disappear if the node         reboots.       </p>"},{"location":"preset_test/#join-now-title","title":"Companion: use both frequencies","text":"<p>         These commands become available one hour before the official start.         Their timeout shrinks so the Companion returns at the same end time.       </p> Companion using both frequencies Dual profile Copy commands <p> <code>rxtx</code> permits transmission on the second profile;             <code>radio2.cross on</code> copies ordinary Companion traffic across             the primary and temporary profiles.           </p>"},{"location":"preset_test/#schedule-title","title":"Schedule a supported node in advance","text":"<p>         A Simple Repeater build can schedule its primary radio with         <code>tempradioat</code>. A Companion can instead schedule its second         profile with <code>tempradioat2</code>. Both commands use the exact UTC         epochs below, switch at the common start, and restore saved settings at         the common end. A node-clock conversion above replaces only those command         epochs with its per-node translated values. Room-server and sensor roles         use the stock join command above instead.       </p> Room server or sensor No advance schedule <p>             Use the stock <code>tempradio</code> command above after             its setup window opens.           </p> Simple Repeater primary radio Primary schedule <pre><code></code></pre> Copy schedule commands <p>             This is available only on a Simple Repeater build with primary             scheduled-radio support. It changes the primary tuple at the start             and restores the saved tuple at the end. If <code>get tempradioat</code>             returns <code>Error: unsupported</code>, use the stock join command             above instead.           </p> Companion using both frequencies Dual-profile schedule <pre><code></code></pre> Copy schedule commands <p>             Crossing is saved independently and remains <code>on</code> after the             temporary second profile ends. Restore its previous value after the             test; <code>auto</code> is the normal default.           </p>"},{"location":"preset_test/#cancel-title","title":"Cancel a schedule or adjust the timeout","text":"<p>         For a primary or Companion schedule, the <code>all</code> form removes every temporary         schedule in that family. To preserve another schedule, first run the         corresponding <code>get</code> command and replace <code>all</code> with         its displayed entry number.       </p> Stock: leave in 30 minutes <pre><code></code></pre> Copy 30-minute command <p>             This replaces the current temporary timeout with 30 minutes, then             restores the saved primary tuple automatically.           </p> Simple Repeater \u00b7 scheduled primary radio <pre><code></code></pre> Copy cancel commands <p>             Before the start, this removes the queued temporary schedule. While             it is running, it also restores the saved primary tuple after the             command reply drains.           </p> Companion \u00b7 before it starts <pre><code></code></pre> Copy cancel commands Companion \u00b7 while it is running Leave now <pre><code></code></pre> Copy restore commands <p>             If <code>get radio2.cross</code> was not <code>auto</code> before the             test, restore that recorded value instead.           </p> Leave in 30 minutes <pre><code></code></pre> Copy 30-minute commands <p>             These commands clear any absolute second-profile schedule and give             the test profile a fresh 30-minute lease. The saved second profile             returns at expiry, but crossing remains <code>on</code>; afterward,             restore the value you recorded before the test (<code>auto</code> is             the normal default).           </p>"},{"location":"preset_test/#share-title","title":"Build a temporary radio test URL","text":""},{"location":"preset_test/#radio-estimates-title","title":"Radio estimates","text":"Nominal LoRa bitrate\u2014 Estimated sensitivity\u2014 TX output used\u2014 Estimated link budget\u2014 <p>             The bitrate is the nominal LoRa physical-layer rate; usable payload             throughput is lower. Sensitivity assumes a 6 dB receiver noise figure             and the standard LoRa SNR threshold for the selected spreading factor.             Link budget is TX output minus that sensitivity, before antenna gain,             cable loss, path loss, interference, and implementation differences.           </p>"},{"location":"qr_codes/","title":"QR Codes","text":"<p>This document provides an overview of QR Code formats that can be used for sharing MeshCore channels and contacts. The formats described below are supported by the MeshCore mobile app.</p>"},{"location":"qr_codes/#add-channel","title":"Add Channel","text":"<p>Example URL:</p> <pre><code>meshcore://channel/add?name=Public&amp;secret=8b3387e9c5cdea6ac9e5edbaa115cd72\n</code></pre> <p>Parameters:</p> <ul> <li><code>name</code>: Channel name (URL-encoded)</li> <li><code>secret</code>: 16-byte secret represented as 32 hex characters</li> <li><code>region_scope</code>: Region Scope (optional, URL-encoded if provided)<ul> <li>Supported by MeshCore App v1.47.0+</li> </ul> </li> </ul>"},{"location":"qr_codes/#add-contact","title":"Add Contact","text":"<p>Example URL:</p> <pre><code>meshcore://contact/add?name=Example+Contact&amp;public_key=9cd8fcf22a47333b591d96a2b848b73f457b1bb1a3ea2453a885f9e5787765b1&amp;type=1\n</code></pre> <p>Parameters:</p> <ul> <li><code>name</code>: Contact name (URL-encoded if needed)</li> <li><code>public_key</code>: 32-byte public key represented as 64 hex characters</li> <li><code>type</code>: numeric contact type<ul> <li><code>1</code>: Companion</li> <li><code>2</code>: Repeater</li> <li><code>3</code>: Room Server</li> <li><code>4</code>: Sensor</li> </ul> </li> </ul>"},{"location":"radio_chirp_math_validation/","title":"Shared radio/radio2 chirp timing and preamble warnings","text":"<p>Historical validation record: the nominal 600 us policy described below has been replaced by the activation self-test and 10% guarded measured budget. The later automatic policy also removed the pair-specific 88-symbol SF8/500 floor and the fixed 300 us loop allowance; the older calculations below remain as test history. See radio profiles for current behavior.</p> <p>Implemented in the <code>keymindCascade</code> working tree, 2026-09-14. The initial 4.1/4000-us implementation record below is retained as history; the 4.6/300-us policy update was a prior stage. No radios were flashed or RF experiments started for either function-only change.</p>"},{"location":"radio_chirp_math_validation/#initial-implementation-scope","title":"Initial implementation scope","text":"<ul> <li>One portable timing function in <code>src/RadioProfiles.h</code> calculates both profiles   from their own SF/BW symbol times, optional dwell times and explicit budgets.</li> <li>The production dwell minimum is now 4.1 chirps on both profiles, rounded up to   a whole microsecond. The slow visit changed from 4.8 to 4.1; the old four-chirp   fast minimum changed to 4.1. The existing asymmetric scheduler may allocate   a longer fast-channel visit from the slow preamble's return deadline.</li> <li>Automatic preambles and diagnostics share the same requirement calculation.   The hot retune path computes only the requested profile, not a full diagnostic   structure or extra hardware reads.</li> <li>Round recommendations upward to multiples of eight, minimum 32. Preserve   the prior measured 88-symbol SF8/500-versus-SF7/62.5 floor.</li> <li>Warn by profile name with the recommended preamble when the requirement is   above 32 or above an explicitly selected short value. Successful radio-setting   replies include <code>WARN recommended preamble: radio=...</code> and/or <code>radio2=...</code>.   Existing explicit values are not overwritten.   Existing unsafe-airtime and infeasible-return-deadline rejection stays intact.</li> <li><code>get radio2.timing</code> / <code>get radio.timing</code> is read-only. It reports both dwell   values and requirements in <code>radio,radio2</code> order. Settings/getters and scheduling   acknowledgments include warnings; successful primary-setting responses use a   preview of the requested SF/BW, not stale live settings.</li> </ul>"},{"location":"radio_chirp_math_validation/#evidence-and-limits","title":"Evidence and limits","text":"<p>The five-radio single-pass bench received 392/400 at 5.1 chirps. The longer-dwell repeats scored 342/348 before the user stopped 6.1, and 395/400 at 7.7. They do not establish any lossless four-channel dwell. They also do not justify treating one full sweep fitting inside the preamble as proof of acquisition.</p> <p>The function retains the earlier production two-profile policy: two return opportunities on the slower channel, blind time plus sixteen acquisition symbols on the faster channel. Its 4.1 floor is the requested policy boundary, not an experimentally established detection minimum. This change requires RF qualification before describing it as a reliability improvement.</p> <p>Single-pass V4 switching peaked at 804 us including post-reception cache refresh. Indicator reached 8428 us in the prior receive-only study. The pure function can model either allowance. Per the follow-up request, runtime scheduling now uses a nominal 600 us switch / 4000 us loop budget; advisory calculations raise the switch allowance if the observed maximum exceeds 600 us. The 0.6 ms nominal value does not cover all measured switches. They do not dynamically retune the production scheduler or silently lengthen already configured preambles.</p> <p>See the formula and CLI examples.</p>"},{"location":"radio_chirp_math_validation/#verification","title":"Verification","text":"<ul> <li>Portable C++ property sweep: 1,600 SF/BW pairs (SF5 through SF12, five bandwidths   on each side), minimum dwell, rounding, automatic/diagnostic consistency and   the two-return deadline for accepted tuples.</li> <li>Exact SF10/125 symbol duration and 4.1 floor; SF6/125 comparison using 1000 us   versus 9000 us switching; reversed profile order; invalid/non-finite inputs;   explicit long/short preambles; advisory-only overrun handling.</li> <li>Production CLI tests cover warnings before delayed publication, named profiles,   both timing aliases, single-profile off, explicit short overrides, saved versus   temporary primary settings, read-only enforcement and bounded reply buffers.</li> <li>Production scan/transition harness retains packet ownership, busy deferral,   failed-retune rollback, receive restoration and oscillator-policy checks.</li> <li> <p>Native <code>test_trace_retry</code>: 63/63 tests passed, including the updated automatic   preamble expectations and profile routing/retry/scheduling tests.</p> </li> <li> <p>Host regression suites: 22/22 tests passed across chirp math, profile CLI,   scan transitions, setting contracts, temporary-reply delivery, STM32 float   formatting, local/LoRa CLI access and repeater timing integration. The CLI   fixtures include the new warning method. Windows MinGW runs the local-access   assertions without unavailable ASan/UBSan runtimes; Linux retains those flags.</p> </li> <li>Full <code>heltec_v4_repeater</code> build after the 0.6 ms follow-up: passed;   RAM 125,344 bytes, flash 1,597,789 bytes, runtime-RAM checks passed.</li> <li>Full <code>heltec_v4_companion_radio_usb</code> build after the follow-up: passed;   RAM 62,460 bytes, flash 828,589 bytes, runtime-RAM checks passed.</li> <li>The rerun passed all 22 host tests and 63 native cases, including actual   primary-setting reply dispatch (local and LoRa), requested-tuple previews,   a recommended 32-symbol preamble for an explicit 16-symbol override, and   the nominal 600 us allowance. The 4.1-symbol floor and 4000 us loop margin   remain unchanged.</li> <li><code>git diff --check</code>: passed. No firmware was uploaded and no commit or push   was made for this change.</li> </ul>"},{"location":"radio_chirp_math_validation/#automatic-46-chirp-300-us-policy-update","title":"Automatic 4.6-chirp / 300-us policy update","text":"<p>After the separate 4.6/0.3 ms hardware test, the user requested this policy in the shared production function. That sample was 197/200 (slow 97/100, fast 100/100), not evidence of lossless operation.</p> <ul> <li>Slow-profile dwell is now <code>ceil(4.6 * symbol_us)</code>; the fast floor remains   <code>ceil(4.1 * symbol_us)</code>. Slow/fast is selected by symbol duration, not profile   index (primary wins equal-symbol ties). Single-profile mode is unchanged.</li> <li>Keep 600 us per switch and use 300 us of loop reserve. Allocate the fast   visit from half the configured slow preamble duration minus the slow visit,   two switches and the reserve. The reserve is not an added delay.</li> <li>The pure calculator, automatic preamble calculation, real scheduler and   acceptance checks all use the same role-specific rounded minima. Advisory   warnings still account for measured switch overruns without rewriting   explicit preambles or persisted configuration.</li> <li>SF7/62.5 + SF8/500 with a slow preamble of 32 yields 9,421 us slow and   21,847 us fast, matching the tested plan, in either profile order.</li> <li>Preserve unsafe-airtime/short-slow-preamble rejection, eight-symbol rounding,   the 32-symbol recommendation minimum, and the historical SF8/500 88-symbol   floor. For SF7/500 paired with SF7/62.5, the automatic fast preamble changes   from 72 to 64 because the reserve is smaller. Explicit 32 remains explicit,   with the existing short-override warning.</li> </ul> <p>Verification covers 1,600 SF/BW pairs with exact role-dependent rounding and fast-dwell arithmetic, profile reversal, equal-symbol ties, larger explicit slow preambles, infeasible short slow preambles, single-profile off, long explicit visits, and advisory-only switch overruns. Production CLI checks assert the actual <code>4.60,42.67</code> chirp readout, <code>loop=300us</code>, warning values and unchanged explicit 32 on the tested SF8/500 pair. The frozen HIL plan now checks equality against the production 4.6/300-us allocation.</p> <ul> <li>Host production regression suites: 15/15 passed.</li> <li>Native production radio/routing/retry suite: 63/63 passed.</li> <li>HIL host regression suites: 64/64 passed.</li> <li>Full V4 repeater build: passed; RAM 125,344 bytes, flash 1,597,881 bytes.</li> <li>Full V4 USB companion build: passed; RAM 62,460 bytes, flash 828,657 bytes.   Both passed runtime-RAM checks; builds ran sequentially in one process.</li> <li>Scoped <code>git diff --check</code>: passed.</li> <li>No hardware upload, commit or push for this policy update.</li> </ul>"},{"location":"radio_dwell_policy_validation/","title":"Automatic dwell policy: 4.6 chirps on both profiles","text":"<p>Historical validation record: the nominal 600 us switch allowance below has been replaced by the activation self-test and a 10% guarded measured budget. The current automatic policy also removed the fixed 300 us loop allowance and the pair-specific SF8/500 88-symbol floor. Values below are retained as bench history, not current automatic defaults. See radio profiles for current behavior.</p> <p>The shared <code>RadioProfiles</code> function uses a 4.6-symbol minimum for both logical profiles of one physical transceiver, rounded upward to a whole microsecond. The slower profile is selected by symbol duration, with primary winning ties. The fast visit receives the remaining half-slow-preamble budget, subject to the same 4.6-symbol minimum. The nominal allowances are 600 us per switch and 300 us per cycle, not added delays.</p> <p>The scheduler, automatic preambles, configuration acceptance and diagnostic calculator use the same minima. Preserve explicit preambles, safe-airtime validation, too-short slow-preamble rejection, recommendation rounding to multiples of eight (minimum 32), and the existing SF8/500 versus SF7/62.5 88-symbol recommendation floor. Measured switching overruns raise advisory warnings without rewriting configured values. Single-profile RX still does not perform a scan.</p> <p>For SF7/62.5 plus SF8/500 with slow preamble 32, the allocation remains 9,421 us slow and 21,847 us fast, in either profile order. The fast visit already exceeds 4.6 fast symbols. Raising the fast minimum matters when less budget is available: equal SF7/500 profiles with slow preamble 30 no longer fit, because only 1,162 us would remain versus the new 1,178 us floor. Slow preamble 32 fits with a 1,418 us fast visit.</p>"},{"location":"radio_dwell_policy_validation/#hardware-context","title":"Hardware context","text":"<p>The preceding V4 RX / fixed RAK4631 and T1000-E TX bench used explicit 32-symbol preambles on both profiles, 100 stationary controls per profile and a complete 100/profile scan. Controls passed 100/100 each; scanning received slow 97/100 and fast 100/100 (197/200 total). Switching averaged 582 us and peaked at 827 us. Successful-packet mean SNR was +12.27/+13.47 dB. No RF retry or USB result replay was used. Radios were left idle.</p> <p>That test used the same 9,421/21,847 us windows, so the higher fast floor does not change this particular allocation. It does not establish lossless performance or qualify other SF/BW combinations. Raw capture SHA-256: <code>1c2e0eae3f304fcaeb6addfeef4f2f09a3c2bec8d78c60d3f151c952d0f6d5f5</code>. No additional RF run is required to apply the user-requested policy change.</p>"},{"location":"radio_dwell_policy_validation/#software-verification","title":"Software verification","text":"<p>The portable C++ test sweeps 1,600 SF/BW pairs and checks both 4.6-symbol minima, exact fast-window allocation, preamble/diagnostic consistency and accepted return deadlines. It also covers reversed/equal symbol times, explicit preambles, newly infeasible short settings, long requested visits, invalid parameters and advisory-only switching overruns. CLI tests exercise warnings, both timing aliases, saved/temporary configuration, persistence and bounded replies. Native integration covers routing, retries and packet ownership alongside the timing model.</p> <p>Verification completed on 2026-09-14 (local date):</p> <ul> <li>Exact commit snapshot: 24/24 host production tests passed, including primary   CLI settings, shared timing, command dispatch, persistence and reply checks.</li> <li>Native radio/routing/retry integration: 63/63 passed.</li> <li>Existing HIL host regressions: 64/64 passed in the working checkout.</li> <li>Both firmware builds passed from the isolated commit snapshot, without the   unrelated local lab/Wi-Fi/extra modulation-cache edits: V4 repeater RAM   125,336 bytes / flash 1,597,497 bytes; USB companion RAM 62,452 bytes /   flash 828,257 bytes. Both passed runtime-RAM checks.</li> <li>Staged whitespace and documentation-link checks passed. No radios were   flashed for this function update.</li> </ul>"},{"location":"radio_profile_switch_validation/","title":"SX1262 profile-switch validation","text":"<p>Measured locally on 2026-09-13 using an XIAO ESP32-S3 with WIO SX1262. Later tests also use the SenseCAP Indicator ESP32-S3 LoRa processor. The V8 integration is the current implementation; V1-V7 sections/captures document the development history.</p>"},{"location":"radio_profile_switch_validation/#initial-result-v1","title":"Initial result (V1)","text":"<p>The production retune path averaged 1.434 ms with XOSC held, versus 3.166 ms with RC standby. Holding the oscillator saved 1.732 ms per retune (54.7%). Warm-mode maximum was 1.467 ms across 6,000 measured retunes. The 6 ms switch allowance and 4 ms loop allowance are unchanged.</p> <p>Each row combines both directions and two reversed-order trials, with 2,000 measured retunes per standby policy. Times run from production <code>tuneProfile</code> entry until BUSY is observed low. GetStatus confirmed RX after every timed hop.</p> Secondary profile RC mean / maximum XOSC mean / maximum SF7 / 500 kHz 3.161 / 3.199 ms 1.434 / 1.467 ms SF8 / 500 kHz 3.166 / 3.209 ms 1.435 / 1.464 ms SF9 / 500 kHz 3.171 / 3.193 ms 1.433 / 1.437 ms <ul> <li>Primary: 909.5 MHz, SF7 / 62.5 kHz, CR 4/5.</li> <li>Secondary: 910.5 MHz, CR 4/5, automatic production preamble calculation.</li> <li>TCXO configuration remained 1.8 V and 1,600 us startup delay.</li> <li>12,000 measured retunes; zero retune failures, BUSY timeouts, or RX-mode errors.</li> <li>109 packet/busy deferrals were excluded from hop timings (57 RC, 52 XOSC).   Deferral preserves the existing packet and radio ownership checks.</li> <li>The first eight successful hops of every trial were excluded from   steady-state statistics, including the initial oscillator transition.</li> <li>All 12 trials returned to RC standby after disabling the second profile.</li> </ul>"},{"location":"radio_profile_switch_validation/#scope-and-reproducibility","title":"Scope and reproducibility","text":"<p>The timing harness compiles the actual production wrapper, not the earlier fast/minimal RX benchmark. RC and XOSC use the same executable: the baseline changes only the standby policy after entering dual-profile mode. No TCXO supply or initial startup delay is disabled. The normal guard checks and frequency/SF/BW/CR/preamble setters remain active.</p> <p>This isolates radio switching from UI, Wi-Fi, BLE, mesh dispatch, and scan-loop scheduling. BUSY polling/timer overhead is included; the RX status query is outside the timing. This is not a packet-delivery test, first-startup timing, power measurement, wide-frequency image-recalibration test, or proof of analog RF settling beyond BUSY/RX status. Indicator I/O-expander latency and nRF52 timing still need their own measurements before reducing common budgets.</p> <p>Raw results: profile_switch_results.json. The collector requires all requested samples, zero failure/timeout/mode-error counts, and successful RC restoration before accepting a trial.</p> <p>Build provenance:</p> <ul> <li>Base commit: <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code>, with the local warm-standby patch.</li> <li>Environment: <code>profile_switch_xiao</code>; Espressif32 6.11.0 / Arduino 2.0.17.</li> <li>RadioLib: pinned <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code> (7.7.1).</li> <li>Test <code>firmware.bin</code> SHA-256:   <code>629d39bba80ad97c434fbaab61bc7c3c302b5ac8180cb2cb12806508b2d111e0</code>.</li> <li>Existing unrelated Companion/repeater/Wi-Fi soak changes were not included   in this minimal timing executable.</li> </ul> <p>Host regression checks also passed: profile scan/CLI (3 tests), receive contract (2 tests), and SX126x RX-status decoding (1 test). A normal <code>heltec_v4_companion_radio_usb</code> build and the XIAO timing build succeeded.</p> <p>The XIAO's original 8 MiB flash snapshot was verified against the device while held in the bootloader before the timing firmware was uploaded. Raw flash backups stay in the current user's private backup directory, outside Git. After testing, the entire original snapshot was restored and verified again against the device before reboot. The live USB CLI then confirmed <code>Xiao S3 WIO</code> running <code>v1.17.1-soak-xiao-B</code> (11-Sep-2026). Its soak logger was left stopped; existing logs were preserved. The Indicator and RAK Tag were not flashed.</p>"},{"location":"radio_profile_switch_validation/#follow-up-batched-modulation","title":"Follow-up: batched modulation","text":"<p>On the same date, a second 12,000-retune experiment held XOSC warm in both cases and compared the old three-setter sequence with one combined LoRa modulation update. Both paths ran in the same V2 executable, with the second round reversing their order. Each mode completed 6,000 timed hops.</p> Secondary profile Separate setters: mean / maximum Batched: mean / maximum SF7 / 500 kHz 1.442 / 1.473 ms 1.159 / 1.198 ms SF8 / 500 kHz 1.444 / 1.480 ms 1.158 / 1.192 ms SF9 / 500 kHz 1.446 / 1.478 ms 1.156 / 1.163 ms <p>Overall: 1.444 ms to 1.158 ms, saving 0.286 ms (19.8%) per retune. Use this matched V2 baseline for the batching comparison; the earlier V1 warm-standby numbers came from a different executable layout.</p> <p>There were zero retune failures, BUSY timeouts, RX-mode errors, or SF/BW/CR cache mismatches. All 12 trials restored RC standby after disabling profile 2. 84 packet/busy deferrals were excluded (54 separate-setter, 30 batched). First eight successful hops per trial were excluded as before.</p> <p>The batching removes two repeated modem checks and two modulation writes. The helper validates a complete MeshCore bandwidth/SF/CR tuple, updates RadioLib's cached SF/BW/CR before its automatic LDRO calculation, and restores the old cache if the command fails. The wrapper's existing physical rollback and safe-transition paths are retained. Frequency changes, preamble updates, standby, IRQ/buffer setup, packet parameters, and RX restart remain unchanged. This does not qualify eliminating those other repeated operations.</p> <p>Raw results: profile_switch_batch_results.json. V2 test firmware SHA-256: <code>b4403f6f5eb0a2b0a31c2d79859122225f247296699a578ad2596ef17eaed0fd</code>. Toolchain and RadioLib pin match the first experiment. The normal <code>heltec_v4_companion_radio_usb</code> build also succeeded with batching enabled.</p> <p>The two new host tests execute the production method over 1,200 valid bandwidth/SF/CR/LDRO combinations, invalid inputs and wrong modem, command failures with cache rollback/retry, and the wrapper's failure short-circuit. All eight relevant host tests passed. RF packet delivery and application/UI scheduling remain outside this timing experiment; shared budgets are unchanged.</p>"},{"location":"radio_profile_switch_validation/#expanded-screening-redundant-rx-setup-and-spi-v5","title":"Expanded screening: redundant RX setup and SPI (V5)","text":"<p>Corrected V5 measurements on 2026-09-13 cover 28,800 timed retunes in 300 trials across XIAO S3/WIO SX1262 and the Indicator ESP32/SX1262. Each sweep uses SF7/8/9 at 500 kHz paired with SF7/62.5 kHz, both directions, reversed case order in round two, and eight excluded initial hops per trial. All 300 trials completed their sample count and restored RC standby on exit. There were zero timed switch failures, BUSY timeouts, RX-mode errors or SF/BW/CR cache mismatches. The normal packet guards deferred 175 attempted hops; these were not counted as timed retunes.</p> <p>Twenty-one distinct cases were screened: seven individual redundant-operation changes, a full manual RX control, combinations, 2/4/8 MHz SPI and whole-buffer ESP32 SPI transfers. Shared controls appear in both groups. All new shortcuts are HIL-only, not included in normal targets.</p>"},{"location":"radio_profile_switch_validation/#individual-and-combined-rx-changes","title":"Individual and combined RX changes","text":"<p>Means in milliseconds, with warm oscillator and batched modulation throughout. Each XIAO row has 768 timed hops; each Indicator row has 384.</p> RX/SPI case XIAO mean Indicator mean Production batching, 2 MHz SPI 1.182 15.190 Manual RX sequence, no omissions 1.181 15.135 Skip second standby 1.124 14.195 Skip repeated IRQ setup 1.096 14.399 Skip repeated buffer-base setup 1.146 14.437 Skip repeated packet-parameter setup 0.991 12.364 Skip RX modem query 1.145 14.427 Defer preamble to the one RX packet-parameter write 0.956 11.659 Skip wake NOP when already awake 1.146 14.576 Combined omissions, early preamble write 0.771 9.096 Combined omissions, deferred preamble 0.732 8.384 4 MHz SPI only 0.985 14.996 8 MHz SPI only 0.889 14.889 Combined/deferred, 4 MHz SPI 0.627 8.280 Combined/deferred, 8 MHz SPI 0.579 8.224 <p>The largest individual saving is programming preamble/packet parameters once. Compare individual omissions with the manual full control when attributing their isolated costs: replacing RadioLib's staging dispatch also has overhead. Individual savings are not additive; some remove overlapping work.</p>"},{"location":"radio_profile_switch_validation/#whole-buffer-spi-follow-up-same-v5-binaries","title":"Whole-buffer SPI follow-up (same V5 binaries)","text":"Case XIAO mean / maximum Indicator mean / maximum Production batching, byte loop, 2 MHz 1.184 / 1.221 ms 15.185 / 15.785 ms Bulk transfer only, 2 MHz 1.070 / 1.073 ms 15.092 / 15.134 ms Bulk transfer only, 4 MHz 0.890 / 0.903 ms 14.924 / 14.983 ms Bulk transfer only, 8 MHz 0.797 / 0.806 ms 14.836 / 14.908 ms Combined/deferred, byte loop, 8 MHz 0.579 / 0.588 ms 8.222 / 8.843 ms Combined/deferred + bulk, 2 MHz 0.671 / 0.700 ms 8.369 / 9.027 ms Combined/deferred + bulk, 4 MHz 0.582 / 0.595 ms 8.252 / 8.315 ms Combined/deferred + bulk, 8 MHz 0.535 / 0.545 ms 8.203 / 8.233 ms <p>The fastest XIAO candidate saves 0.649 ms (54.8%) versus that sweep's already-warm, already-batched production control. At 8 MHz, bulk transfers alone add about 0.043 ms of benefit to the combined RX shortcut. The Indicator remains dominated by I2C-mediated chip-select/BUSY/DIO access; the final bulk step improves its combined mean by only 0.019 ms. Small HAL effects varied between executable layouts in preliminary screens; do not generalize them.</p> <p>The Indicator exceeds the generic 6 ms switch allowance even in its fastest experimental path. These are board measurements, not a justification for reducing the shared 6 ms switch / 4 ms loop constants. Indicator scheduling and effective preambles need board-specific treatment before a production rollout. Application/display/network scheduling is still excluded here.</p> <p>Raw accepted sweeps:</p> <ul> <li>XIAO RX cases</li> <li>Indicator RX cases</li> <li>XIAO bulk SPI</li> <li>Indicator bulk SPI</li> </ul>"},{"location":"radio_profile_switch_validation/#test-corrections-and-provenance","title":"Test corrections and provenance","text":"<p>V3/V4 broad screening accidentally called <code>SX1262::startReceive()</code> instead of <code>CustomSX1262::startReceive()</code> in the fallback, omitting MeshCore's extra preamble-detection IRQ flag. Their raw files are marked superseded and are not included in the counts or conclusions above. The V4 packet sweep was stopped on discovery. V5 preserves that flag in both normal and manual RX paths; a host regression test checks the Custom fallback and mapped flags. The earlier V1/V2 warm/batching experiments did not use that experimental subclass and are unaffected.</p> <p>An initial V5 XIAO capture stopped on a partial serial JSON line during guarded mode exit. It is retained as incomplete, not counted above. The host now accumulates reads until newline, with regression coverage. Initial setup rejections are retried only for the explicit pre-measurement packet-guard reply, bounded to three seconds and counted; packet losses and timed failures are never retried away.</p> <p>Final V5 firmware SHA-256:</p> <ul> <li>XIAO: <code>5506a40ffa8240201aca519e8e24db3647f897e7a1290bba22be6e4986d8f02f</code></li> <li>Indicator: <code>dd595b2e7fa8c1ccb14fac9223f1a57277cd6a602864ee9bf090672f494fa2f6</code></li> </ul> <p>Base commit/toolchain/RadioLib pin match the earlier experiments. Thirteen unique host tests passed (eight production regressions, two HIL boundary/buffer tests, three serial-reader/setup-guard tests). The HIL tests cover all 255 nonzero omission masks, normal-path fallbacks, preserved IRQ clear/SetRx, error short-circuit and full-duplex buffer lengths 1..260. They are not full driver lifecycle tests. An additional normal <code>t1000e_companion_radio_usb</code> nRF52 build passed with the production warm/batching changes: 591,484-byte app, runtime RAM guard passed. It was not flashed to the RAK or any nRF52 board.</p>"},{"location":"radio_profile_switch_validation/#qualification-boundary","title":"Qualification boundary","text":"<p>No BUSY wait, command status validation, stale-IRQ clear, RX command or wrapper packet-ownership guard is removed. The fastest path relies on a known RX-to-RX window and established RX setup. Correct invalidation after TX, CAD, sleep, reset, failed commands, and recovery must be designed and tested before promoting these shortcuts. The per-byte/bulk HAL experiment is ESP32-specific. Sensitivity/PER, oscillator power draw, large-frequency image recalibration, and application-driven continuous scanning remain unqualified.</p>"},{"location":"radio_profile_switch_validation/#actual-packet-checks-and-limitations","title":"Actual packet checks and limitations","text":"<p>Final forward matrix: Indicator transmitter to XIAO receiver, -9 dBm, 21 cases x SF7/8/9 x both profiles x 16/64/255-byte payloads = 378 probes. 359 sequence/length/payload/profile checks succeeded, 13 receiver-declared wait timeouts occurred, and six receiver USB replies did not arrive before the host deadline. Transmitter replies returned success. Successfully read packets had RSSI -42 to -39 dBm and SNR 10.2 to 14.2 dB. Timeout diagnostics reported RX mode and no device errors; some retained a preamble IRQ. These observations do not establish why packets were missed.</p> <p>The production-batched baseline delivered 17/18 in that matrix; the fastest combined/bulk/8 MHz candidate delivered 18/18. An earlier reversed-order smoke test of the fastest candidate had one receiver timeout, so the clean 18-packet batch is not a reliability qualification. Earlier 0 dBm checks also had baseline and candidate misses. Reducing power did not eliminate them.</p> <p>Reverse direction: XIAO transmitter to Indicator receiver, -9 dBm, baseline, combined/8 MHz and combined/bulk/8 MHz, with the same SF/profile/length matrix. All 54 payloads arrived intact, 18/18 per case. However, one XIAO USB TX acknowledgement was delayed past the host deadline, after which 32 later records picked up the previous command's acknowledgement. Thus the raw file has only 21 fully matched transactions despite 54 correctly received payloads. This is sequence-correlated evidence of a host acknowledgement problem, not 33 RF losses. Subsequent collector code rejects/stores stale sequence replies instead of associating them with a new command, and now asserts DTR on Windows to match the existing <code>s3_memory_soak.py</code> HWCDC session policy. The captures above used DTR deasserted; a causal DTR A/B test was not performed. Sequence handling has host regression coverage, but these last host changes were not rerun on HIL firmware after the boards were restored.</p> <p>USB acknowledgements and actual receiver payload validity are recorded separately. Missing acknowledgements never trigger an automatic retransmit. The host drains the receiver concurrently with the transmitter's command and records timeouts without hiding them. These tests establish some real packet functionality, not a controlled packet-error-rate comparison. Fix/qualify the test transport, repeat with a stable RF reference, then test TX/CAD/reset/RXPS and continuous application scanning before promoting the shortcuts.</p> <ul> <li>Forward matrix, all 21 cases</li> <li>Reverse matrix, three cases</li> <li>0 dBm smoke</li> <li>-9 dBm reversed-order smoke</li> </ul> <p>Earlier incomplete packet captures and superseded screens are retained for audit, not counted in the 378/54 final matrices. No identity or channel secrets were transmitted: probes used synthetic sequence-tagged bytes.</p>"},{"location":"radio_profile_switch_validation/#production-integration-and-usb-recovery-v8","title":"Production integration and USB recovery (V8)","text":"<p>Normal XIAO S3 WIO and Indicator LoRa variants now opt in to buffered 8 MHz SPI and a guarded fast RX-to-RX path. Other SX1262 variants retain default SPI/full RX setup; modulation batching and warm standby remain shared.</p> <p>The fast path keeps the TCXO warm, applies one SF/BW/CR tuple and one packet tuple, clears stale IRQs and starts RX with the original BUSY handling. It reuses an established LoRa IRQ map and buffer bases only within an owned continuous-RX retune. Ordinary standby, staging/TX, CAD, sleep, reset/init, RX duty cycling and command failures invalidate that reuse. RX startup failure now fails the whole profile transaction and restores the old profile/caches with full setup; failed recovery keeps the profile marked for refresh.</p>"},{"location":"radio_profile_switch_validation/#sleep-recovery-discovered-during-integration","title":"Sleep recovery discovered during integration","text":"<p>Initial lifecycle captures found <code>XOSC_START_ERR</code> (0x20) after retained sleep, despite successful RX status. RC-policy controls reproduced the same flag: this was not established as a regression caused by the fast path. Simply waking in RC and entering standby before sleep did not clear it. Reapplying the already configured TCXO voltage and 1,600 us delay resolved it.</p> <p>The production sleep override now enters standby first, wakes in RC, and restores TCXO configuration on wake. It refuses to clear unrelated device faults. The warm policy resumes after full RX setup. This follows the standby entry requirement in section 13.1.1 of the Semtech SX1261/2 datasheet. Section 13.3.6 describes TCXO control and the XOSC error flag; it does not by itself prove the cause of this retained-sleep observation.</p> <p>Diagnostic files <code>profile_switch_v6_recovery_xiao.json</code>, <code>profile_switch_v7_recovery_xiao.json</code>, <code>profile_switch_v7_recovery_xiao_complete.json</code> (despite its filename, its <code>complete</code> field is false), and <code>profile_switch_v7_sleep_diagnostic_xiao.json</code> retain these failures. They are not counted as passing lifecycle tests.</p>"},{"location":"radio_profile_switch_validation/#usb-fix-and-scope","title":"USB fix and scope","text":"<p>The HIL host distinguishes Espressif native CDC (DTR asserted) from CH340 bridges (DTR/RTS deasserted). Replies are newline-assembled and sequence-matched. Firmware caches completed packet and timing reports before emitting and flushing them. A timeout or malformed report triggers a sequence-scoped result query, never a repeated TX or timing run. Randomized session sequence starts avoid a cached result from an earlier host session.</p> <p>V7 had successfully fixed/retested packet result replay but a long native-USB timing sweep still lost one response. V8 adds whole-report timing buffering and replay. The incomplete V7 XIAO timing capture is retained, not silently completed. The public MeshCore Companion USB protocol is unchanged; these USB fixes are for the radio-lab transport. The previous broad Windows-DTR policy described in the V5 history above has been replaced by native-device identification.</p> <p>Both boards passed 20 reopen cycles, deliberate lost timing replies, deliberate lost TX replies, stale TX reply isolation, and 18 lifecycle cases each. The cases cover TX, CAD, sleep, reset/init, RC-policy sleep and explicit TCXO-restoration controls, repeated three times. Fast counters prove one full RX fallback after invalidation and reuse only on the following retune. All command results, RX-mode checks and device-error checks passed.</p> <ul> <li>XIAO recovery</li> <li>Indicator recovery</li> </ul> <p>V8 test firmware SHA-256 (same pinned RadioLib/toolchain as above):</p> <ul> <li>XIAO: <code>e1806bbf4af5a88b31423131806a682713221082235507ff95e5beb9ef3ac067</code></li> <li>Indicator: <code>bab4009078a4fff68dfb7aa73a5afc83e84f5c47589354d8aeb8e5b8d8798442</code></li> </ul> <p>Normal USB Companion builds passed for <code>Xiao_S3_WIO_companion_radio_usb</code> (813,901 app bytes / 63,012 static RAM), <code>SenseCapIndicator-LoRa_comp_radio_usb</code> (879,809 / 62,960), and <code>t1000e_companion_radio_usb</code> (591,980 / 179,868). Runtime RAM budgets passed on all three. These normal application images were compiled, not substituted for the user's configured soak firmware during the HIL tests.</p> <p>Host/native regression coverage includes production modulation caches/LDRO, standby failure short-circuit, RX-start rollback failure, ownership guards, fast-state invalidation, TCXO wake fault preservation, buffered SPI semantics, USB result overflow/replay, partial reads and stale-sequence handling.</p>"},{"location":"radio_profile_switch_validation/#final-steady-state-timing","title":"Final steady-state timing","text":"<p>V8 ran 256 timed retunes per trial, four production configurations, SF7/8/9 at 500 kHz paired with SF7/62.5 kHz, and two reversed-order rounds on each board: 12,288 measured retunes / 48 trials. The first eight hops per trial are excluded. There were zero retune failures, BUSY timeouts, RX-mode errors or modulation-cache errors. All 48 trials restored RC policy on exit. The normal packet guards deferred 21 XIAO and 59 Indicator hops; no setup retries or naturally missing/replayed USB reports occurred in these final sweeps.</p> Production configuration XIAO mean / maximum Indicator mean / maximum Warm + batching, per-byte SPI 2 MHz 1.193 / 1.227 ms 15.174 / 15.836 ms Fast RX, per-byte SPI 2 MHz 0.744 / 0.770 ms 8.426 / 8.471 ms Full RX, buffered SPI 8 MHz 0.828 / 0.840 ms 14.816 / 15.386 ms Fast RX + buffered SPI 8 MHz 0.549 / 0.556 ms 8.263 / 8.879 ms <p>The combined production path saves 54.0% on XIAO and 45.5% on Indicator relative to each same-image warm/batched control. Small differences from V5-V7 reflect different binaries/code layout; only within-image A/Bs are compared. Both fast configurations must increment the production success counter; full RX controls must not. Mode/cache verification happens after the timed region.</p> <ul> <li>XIAO V8 timing</li> <li>Indicator V8 timing</li> </ul> <p>The common 6 ms switch and 4 ms loop allowances are unchanged, not delays inserted by the driver. Indicator still exceeds 6 ms. These measurements do not qualify continuous application scheduling, scan-overlap reception, sensitivity/PER, power use, temperature extremes, or image recalibration on frequency changes larger than this 1 MHz pair. Do not shorten common transmit preambles or advertise the XIAO number for other boards.</p>"},{"location":"radio_profile_switch_validation/#final-over-air-packet-matrix","title":"Final over-air packet matrix","text":"<p>288/288 payloads and command transactions passed: 144 Indicator-to-XIAO and 144 XIAO-to-Indicator. Each direction covers all four production cases, SF7/8/9 secondary profiles, both target profiles, 16/64/255-byte synthetic payloads and two reversed-order rounds. TX used buffered 8 MHz SPI at -9 dBm. Fast receiver readiness reports had to show actual production fast resumes.</p> <p>There were zero RX errors, receiver timeouts, missing replies, stale replies, or natural transport-recovery queries in these matrices. Deliberately lost and stale replies were separately exercised by the recovery tests above. RSSI ranged -43 to -39 dBm and SNR 10.2 to 14.5 dB. This clean short-range matrix addresses the failures seen in the earlier V5 harness; it does not identify which single change caused each historical miss or establish a field packet-error rate.</p> <ul> <li>Indicator TX / XIAO RX</li> <li>XIAO TX / Indicator RX</li> </ul> <p>All 18 host/native regression tests passed. The HIL builds do not include the unrelated pre-existing Companion/repeater/Wi-Fi soak edits; the normal application compile checks include the current working tree and preserve them.</p> <p>A subsequent requested SF6/125 kHz multi-channel test used 32-symbol preambles and 4.8-symbol visits. It stopped on the third packet at the initial four channels (two received, one timeout); no higher count was tried. That continuous scan experiment is separate from the 288/288 stationary-after-retune matrix above.</p>"},{"location":"radio_profile_switch_validation/#unchanged-modulation-tuple-follow-up","title":"Unchanged modulation tuple follow-up","text":"<p>The initial software-only checks below were followed by same-image hardware timing and separated-radio tests. Frequency-only means improved from 548.880 to 451.897 us on XIAO and from 8,263.438 to 7,601.193 us on Indicator. Four-channel SF6 reception was not loss-free. The following paragraph records the initial implementation stage, not the current hardware-test status.</p> <p>Implemented 2026-09-14 after commit <code>0e5955f8</code>, without restarting hardware tests. On opted-in fast RX-to-RX hops, <code>setLoRaModulationParams()</code> now compares the requested SF, encoded bandwidth, encoded CR and effective LDRO against the last successfully acknowledged modulation write. An exact match within a valid owned standby window omits only <code>SetModulationParams</code> (0x8B). Frequency programming, the modem query, preamble/packet parameters, IRQ clears, RF-switch control and BUSY waits remain unchanged.</p> <p>The acknowledgement is separate from RadioLib's mutable software fields. Auto/manual LDRO compares the resulting command byte, with the pinned RadioLib &gt;=16 ms symbol rule. A failed write revokes the whole fast context before rollback. Ordinary SF/BW/CR/forced-LDRO setters invalidate the saved tuple even on failure. Existing full-RX staging, ordinary standby, TX/CAD staging, reset/init, sleep, duty cycling and failed RX/standby operations also invalidate it. The first hop after lost context therefore writes again; frequency-only hops that retain the context can skip subsequent writes.</p> <p>All 30 selected host/native tests passed, including repeat-write counts for all supported bandwidth/SF/CR combinations and auto/forced LDRO modes, each independently changed field, LDRO policy transitions, failed-write retry, modem-query failure, ownership gates, ordinary setters and lifecycle invalidation. Both <code>profile_switch_xiao</code> and <code>profile_switch_indicator</code> compiled successfully against the pinned RadioLib. No firmware was uploaded, no radio command was issued, and no new RF result was collected. The temporary build overlay was removed. The earlier ~0.549 ms XIAO and ~8.263 ms Indicator timings do not measure this added optimization; its time saving and RF behavior await testing.</p>"},{"location":"radio_profile_switch_validation/#mercermesh-heltec-t096-sx1262-experiment-2026-09-21","title":"MercerMesh Heltec T096 SX1262 experiment (2026-09-21)","text":"<p>The Pi has one Heltec T096 (USB serial <code>651F8E496197F882</code>); the other Heltec-named nRF52 is a MeshTower V2, not another T096. An application-only T096 HIL image tested two further RX-to-RX shortcuts with a buffered 8 MHz SPI bus: use SX1262 <code>SetFs</code> instead of warm XOSC standby, and skip <code>SetPacketParams</code> only when the LoRa RX packet tuple is unchanged. Both switches defaulted off in this HIL image. The image explicitly enabled the existing production fast-RX path. Normal T096 firmware does not currently enable that path or use the buffered SPI HAL, so these numbers are not stock T096 switch timings.</p> <p>The same image ran 256 measured hops per configuration, after eight warm-up hops, on 909.5/909.75 MHz. <code>freq</code> held SF7/BW125/CR5; <code>both</code> alternated SF7/SF8 at BW125/CR5. Preamble was 32 symbols. The DWT cycle counter measured through RX re-entry and BUSY release. Every 8 MHz configuration had zero switch failures, mode/cache/RSSI errors, or BUSY timeouts.</p> 8 MHz HIL configuration Frequency-only mean Frequency + SF mean Fast RX baseline 467.3 us 553.6 us <code>SetFs</code> only 422.5 us 517.4 us Unchanged packet tuple skip only 357.7 us 444.0 us Both 313.0 us 407.8 us <p>Combined savings were 154.3 us (33.0%) for frequency-only and 145.8 us (26.3%) for frequency-plus-SF relative to the same-image fast-RX baseline. Command counts confirmed one frequency command, IRQ clear and RX command per hop; the optimized cases eliminated the corresponding standby and packet commands. These are controlled short-range, same-band results, not a field packet-error rate or a qualification of large frequency jumps, sleep/wake, TX/CAD interruption, BLE scheduling, or all SX1262 boards.</p> <p>A separate RAK4631 fixed transmitter sent 16-byte synthetic packets at 909.5 MHz/SF10/BW125/CR5/preamble32, -9 dBm chip power. The T096 hopped to 909.75 MHz and back before each transmission. Baseline and combined shortcuts each delivered 60/60 packets after 120 fast hops, with payload sequence and content checked. The RAK bootloader on this exact fixture enumerated as <code>239A:002A</code> (the fixture's earlier <code>0029</code> expectation was corrected).</p> <p>Doubling buffered SPI to 16 MHz gave only 12\u201321 us (about 3\u20134%) savings in comparable successful cases, while five of eight setup attempts failed. The combined shortcut had no clean 16 MHz result. Keep this T096 at 8 MHz pending a separately diagnosed and repeatable 16 MHz bring-up; no 16 MHz over-air qualification was attempted.</p> <p>Both radios were restored via app-only DFU after the experiment: the T096 to <code>Heltec_t096_repeater</code> and the RAK to <code>RAK_4631_companion_radio_full</code>, each built at <code>v1.17.1.7-hil-restore-e7160dfd</code>. The T096 answered normal <code>version</code> and <code>board</code> commands; the RAK answered the Full Companion terminal's version command. The V4 observer's memory-soak service remained active. Reproducible bench code is in <code>tools/hil/profile_switch_t096_sx1262.cpp</code> and <code>tools/hil/t096_sx1262_packet_probe.py</code>.</p> <p>Follow-up: owned fast RX, <code>SetFs</code>, and acknowledged packet-tuple reuse are now defaults for <code>CustomSX1262</code> targets, including the original XIAO S3 WIO, Station G3 KISS, and Heltec V4 KISS paths. The Seeed Indicator retains its original owned-RX path but explicitly opts out of the two new shortcuts because its radio control and BUSY/IRQ pins run through an I2C expander. The owned-RX state now remembers only an acknowledged packet tuple and revokes it on ordinary packet setters, TX/CAD staging, standby outside the hop, sleep, reset, RX duty cycling, or command failure. The T096 numbers remain lab measurements, not on-board qualification of every <code>CustomSX1262</code> target.</p>"},{"location":"radio_profiles/","title":"Two LoRa profiles on one radio","text":"<p><code>radio2</code> lets one LoRa transceiver alternate between two frequencies or modulation settings. It is useful for listening to two networks, or keeping your usual channel available during a LoRa firmware update.</p> <p>There are at most two active profiles. <code>tempradio</code> temporarily replaces <code>radio</code>; <code>tempradio2</code> temporarily replaces <code>radio2</code>. These are time-shared receive windows, not simultaneous receivers. Receiving or transmitting a packet on one profile makes the other unavailable until that packet finishes.</p> <p>The second-profile commands are shared by repeater, Companion, room server, sensor and standalone terminal-chat firmware with a LoRa radio. ESP-NOW-only devices reject LoRa profile commands. KISS is a raw host-controlled modem: it exposes equivalent RAM-only binary <code>SetRadio2</code>/<code>SetTempRadio2</code> commands and logical KISS Data ports, documented in the KISS modem protocol. It does not use the Mesh CLI's persistent profile file or Mesh retry queues.</p>"},{"location":"radio_profiles/#quick-setup","title":"Quick setup","text":"<p>Keep the primary channel configured with <code>radio</code>, then add the second:</p> <pre><code>set radio2 910.5,500,8,5,rx\nget radio2\nget radio2.status\n</code></pre> <p>The tuple is frequency in MHz, bandwidth in kHz, spreading factor, coding-rate denominator, mode, optional preamble in symbols. <code>5</code> means coding rate 4/5.</p> Mode Receive on profile 2 Transmit on profile 2 <code>rx</code> Yes Only infrastructure replies explicitly configured with <code>tx.reply ... force</code> <code>rxtx</code> (also <code>rx&amp;tx</code>) Yes Yes <code>off</code> No No <p>For transmission on both permanent profiles:</p> <pre><code>set radio2 910.5,500,8,5,rxtx\n</code></pre> <p>The same encoded message is queued separately for each allowed transmit profile. Each has its own direct/flood retry slots and channel-busy backoff. A forwarding echo on one profile cannot cancel the other profile's retry. Packet storage and the physical transceiver's airtime budget are shared; exhausted queues can still drop packets.</p>"},{"location":"radio_profiles/#keep-the-main-channel-during-an-update","title":"Keep the main channel during an update","text":"<pre><code>set tempradio2 910.5,500,8,5,rxtx,120\nget tempradio2\n</code></pre> <p>This enables the second profile for 120 minutes (2 hours). Locally generated LoRa OTA requests use the temporary second profile. Infrastructure OTA responses follow <code>tx.reply</code> below (both TX-capable profiles by default). Ordinary local traffic stays on the primary profile by default. Use an OTA-capable build and the usual OTA setup on every participating node; a temporary profile does not add OTA support to firmware built without it.</p> <p>Local settings take effect after a short reply allowance. On repeaters, immediate remote <code>radio2</code>/<code>tempradio2</code> changes (including <code>off</code>) wait until their exact reply copies finish, with at least one successfully transmitted. A reply that cannot be queued or whose copies all fail cancels the change. Queued replies have a five-minute deadline; an already-transmitting copy may finish under the normal radio watchdog. This confirms transmission, not reception by the remote client.</p> <p>Permanent remote changes are prepared in an uncommitted file before replying; the saved configuration is replaced only after reply transmission. If that replacement fails, the old channel remains active and the commit retries. Local <code>get radio2.status</code> reports this pending state. Roles without the tracked remote reply path require local USB for these immediate secondary-profile changes.</p> <p>Temporary periods and schedules live in RAM and disappear on reboot. Waiting for a reply does not extend a temporary lease. Timer expiry also uses monotonic time, so setting the clock backwards cannot extend a temporary session.</p>"},{"location":"radio_profiles/#repeater-room-server-and-sensor-replies","title":"Repeater, room-server, and sensor replies","text":"<p>These roles default to <code>tx.reply both</code>: locally generated replies are queued on <code>radio</code> and on an active <code>radio2</code> that permits TX. This includes replies to remote CLI/login/telemetry requests, ACKs, returned paths, delayed GPIO command completion, room subscription posts, and locally served LoRa OTA catalog, manifest, data, proof, and leaves responses. Each copy has its own retry state. Forwarded packets, periodic adverts, sensor pushes, and OTA requests continue to use the normal crossing rules.</p> <pre><code>get tx.reply\nset tx.reply both\nset tx.reply both force\nset tx.reply radio\nset tx.reply auto\n</code></pre> Choice Replies transmit on <code>both</code> Primary plus an active <code>rxtx</code> second profile. Default. <code>radio</code> Primary only. <code>radio2</code> Second only; no primary fallback. <code>auto</code> Normal <code>radio2.cross</code> behavior, including permanent/temporary isolation. <code>off</code> Neither profile. This also suppresses remote CLI replies and ACKs. <p>Append <code>force</code> to <code>both</code> or <code>radio2</code> to allow these replies on an active second profile configured as <code>rx</code>. Without <code>force</code>, <code>rx</code> remains receive-only. Sending the command again without <code>force</code> removes the override. It never turns on <code>radio2 off</code>, changes the saved <code>rx</code> mode, or enables ordinary forwarding/TX there. Existing crossover packet filters still apply to the extra copy.</p> <p>The explicit choices override <code>radio2.cross</code>, including <code>off</code> and mixed permanent/temporary profiles. <code>radio</code> means the active primary profile, including <code>tempradio</code>; <code>radio2</code> also includes an active <code>tempradio2</code>. For example, an OTA source can retain its normal channel while allowing OTA and management responses on a temporary receive profile:</p> <pre><code>set tempradio2 910.5,500,8,5,rx,120\nset tx.reply both force\n</code></pre> <p>The source must have OTA support and an active temporary-radio session as usual. A node fetching an update still needs <code>rxtx</code> for its OTA requests. Forcing replies does not change OTA's receive gates, scan timing, or preambles.</p> <p>This setting survives reboot; older saved profiles adopt <code>both</code> without force. The getter reports when the chosen second profile cannot transmit. Already queued replies retain their choice; disabling/changing a profile invalidates stale queued packets. A parameterized repeater <code>tempradio</code> command waits for both admitted reply copies to drain before changing the primary settings; at least one must transmit successfully. Those tracked replies omit alternate paths and transport retries so no late success copy can outlive the handoff. Queue capacity and the shared transceiver's airtime budget still limit delivery. OTA data/proof admission counts both copies against its queue credit and reserves receive capacity before allowing the response.</p> <p>Companions use the per-contact/channel choices below; <code>tx.reply</code> is an infrastructure setting.</p>"},{"location":"radio_profiles/#companion-messages-on-both-profiles","title":"Companion messages on both profiles","text":"<p>To send ordinary Companion messages on both <code>radio</code> and an active <code>tempradio2</code>, configure the temporary profile in <code>rxtx</code> mode and enable crossing:</p> <pre><code>set radio2.cross on\nget tempradio2\nget radio2.cross\nget radio2.status\n</code></pre> <p><code>rxtx</code> permits transmission on the second profile; <code>radio2.cross on</code> copies new messages between the two profiles. <code>TX=a,b</code> reports primary and secondary transmit counts. Crossing also applies to OTA traffic.</p> <p>The crossing setting is saved and remains enabled after the temporary session ends or the node reboots. Run <code>set radio2.cross auto</code> to restore the default isolation between permanent and temporary profiles. The firmware picker's Companion tempradio2 instructions include both choices and the status commands.</p>"},{"location":"radio_profiles/#companion-tx-routing-by-contact-or-channel","title":"Companion TX routing by contact or channel","text":"<p>Companions can save a transmit choice for each contact and each configured channel. The commands apply to messages sent from the phone app, USB/BLE/TCP Companion clients, and the text terminal:</p> <pre><code>set tx.user \"Alice Jones\" radio2\nget tx.user \"Alice Jones\"\nset tx.channel 0 both\nget tx.channel 0\nset tx.channel #wardriving radio\nget tx.channel #wardriving\n</code></pre> <p>Channel indices match the app and the terminal's <code>channels</code> list; Public is normally slot <code>0</code>. Names must match exactly, including capitalization and any leading <code>#</code>. Quotes always select a literal name, so <code>\"1\"</code> is a channel named <code>1</code>, while unquoted <code>1</code> selects slot 1. Quote contact names beginning with <code>key:</code> to distinguish them from public-key selectors. Duplicate names are rejected: use the channel index or a contact's public key instead.</p> Choice Locally addressed traffic transmits on <code>auto</code> Existing behavior, including <code>radio2.cross</code> and temporary-profile isolation. This is the default. <code>radio</code> The primary profile only. <code>radio2</code> The second profile only; sending fails if it is off or RX-only. <code>both</code> The primary profile and the second profile whenever the second is enabled for TX. <code>off</code> Neither profile for this contact/channel. Reception stays enabled. <p>Explicit choices override <code>radio2.cross</code>, including <code>off</code> and the isolation between a permanent and temporary profile. They do not turn on radio2 or change its <code>rx</code>/<code>rxtx</code> mode. For example, leave <code>radio2.cross auto</code> and use <code>set tx.channel 0 both</code> to send Public messages on both <code>radio</code> and an active <code>tempradio2</code>, while other channels keep their default routing.</p> <p><code>radio</code> means the currently active primary profile, whether permanent or <code>tempradio</code>; <code>radio2</code> similarly includes <code>tempradio2</code>. There are still at most two active profiles. Getters show the saved choice and <code>active=</code> for newly initiated messages with the current profile configuration. A temporarily unavailable second profile is reported explicitly.</p> <p>Contact selection uses the full stored public key after resolving a unique name or key prefix. It never routes by the short on-air destination hash. For key selection, prefix 12\u201364 hexadecimal digits (whole bytes) with <code>key:</code>:</p> <pre><code>set tx.user key:0123456789AB radio2\nget tx.user key:0123456789AB\n</code></pre> <p>Replace the example prefix with your contact's key; use more digits if it is ambiguous. <code>get tx.user</code> and <code>get tx.channel</code> report override counts and query syntax. To return a target to the global behavior:</p> <pre><code>set tx.user \"Alice Jones\" auto\nset tx.channel 0 auto\n</code></pre> <p>A user's setting covers addressed texts, login/CLI/telemetry requests, replies, ACKs, and returned paths to that contact. Thus <code>off</code> also prevents ACKs to that contact. Channel settings cover group text and group data, including an explicitly routed group datagram. Contact choices do not filter other people's messages inside a group channel. Adverts, raw traces, raw packets, and OTA packets without a contact/channel destination retain global routing. Packets and their retries already queued retain the choice used when created; changing or disabling the radio profile still invalidates stale queued work. Message timeout estimates use the selected profiles' airtime, independently of the scanner's current receive profile.</p> <p>Choices survive reboot and normal phone-app updates to the same contact or channel key. Replacing a channel's key or deleting/replacing a contact clears its choice. They use reserved bytes in existing saved records, so record sizes and the phone protocol are unchanged. Older firmware ignores these bytes and may reset the choices when it saves the records.</p>"},{"location":"radio_profiles/#choose-whether-traffic-crosses-between-profiles","title":"Choose whether traffic crosses between profiles","text":"<pre><code>get radio2.cross\nset radio2.cross auto\nset radio2.cross on\nset radio2.cross off\n</code></pre> Active primary Active secondary <code>auto</code> (default) <code>on</code> <code>off</code> <code>radio</code> <code>radio2</code> Cross Cross Isolated <code>tempradio</code> <code>tempradio2</code> Cross Cross Isolated <code>radio</code> <code>tempradio2</code> Isolated Cross Isolated <code>tempradio</code> <code>radio2</code> Isolated Cross Isolated <p>These are the global rules used by Companion targets set to <code>auto</code>; an explicit contact/channel choice above overrides crossing for its own outbound packets. Ordinary crossing respects <code>rx</code>. The infrastructure-only <code>tx.reply ... force</code> override above permits locally generated replies on that profile. With crossing allowed, a packet received there may still be forwarded on the primary profile. Existing routing, forwarding and packet-filter settings apply. An RX-only <code>tempradio2</code> also blocks locally generated OTA requests under <code>auto</code> or <code>off</code>; they do not fall back to the normal primary channel. Use <code>rxtx</code> for a fetching node that needs to exchange requests and data. Infrastructure OTA responses follow <code>tx.reply</code> independently of this crossing table.</p>"},{"location":"radio_profiles/#preamble","title":"Preamble","text":"<p>Append the preamble to the end of a command:</p> <pre><code>set radio2 910.5,500,8,5,rxtx,88\nset tempradio2 910.5,500,7,5,rxtx,120,128\nset radio 909.5,62.5,7,5,32\nset tempradio 909.5,62.5,7,5,120,32\n</code></pre> <p>Existing primary <code>radio</code>, <code>tempradio</code>, <code>radioat</code> and <code>tempradioat</code> commands accept the optional trailing preamble where those primary commands are supported by the role. Getters include the preamble. Omit it, or use <code>auto</code>/<code>0</code>, to calculate it automatically. Explicit values are used as entered, subject to the radio's limits and safe airtime arithmetic.</p> <p>Automatic dual-profile preambles round up to a multiple of eight, with a 32-symbol minimum and a 128-symbol maximum. When a second profile activates, the radio first self-tests four successful RX-to-RX switches in each direction using the actual tuples. It defers the test while receiving, transmitting or busy, and never counts a failed switch. The 128-symbol automatic preamble is provisional until the test completes. The largest successful hop, rounded up with a 10% guard, then supplies the per-switch allowance for both the automatic preambles and the scan dwell. There is no fixed switch-time floor. The measurement is reset when either profile changes, including when a <code>tempradio2</code> session starts or ends; it is not saved to flash. The rapid startup hops briefly interrupt reception on each channel; a new packet beginning during this test may be missed. An already detected packet defers the test instead of being interrupted.</p> <p>Each idle scan starts with 4.6 symbols on the slower profile, then spends the remaining budgeted time on the faster profile, also with a 4.6-symbol floor. Slower means a longer LoRa symbol (<code>2^SF / bandwidth</code>), regardless of profile number. The slower preamble sets the return deadline. The calculation allows two slow visits within that preamble, reserving the self-tested, 10%-guarded switch time per hop. There is no extra fixed main-loop allowance. Fast-channel transmit preambles include sixteen acquisition symbols. For a primary SF7 / 62.5 kHz profile with a 763 us measured maximum switch (840 us after the 10% guard, from the BLE-on T1000-E trial):</p> Secondary profile Automatic secondary preamble Previously tested explicit preamble Primary preamble SF9 / 500 kHz 32 32 32 SF8 / 500 kHz 40 64 32 SF7 / 500 kHz 64 80 32 <p>With preamble 32 on that slower profile, its visit is 9.421 ms and the faster visit is 21.667 ms, plus the actual switching time. Increasing the slow preamble also increases the time available on the fast channel. If the symbols are equal in length, the primary profile goes first. Detected packets hold the current channel until reception finishes.</p> <p>The SF8 / 500 kHz value is calculated from the same formula as every other profile; the older pair-specific 88-symbol floor has been removed. The explicit values come from historical production validation: the final fast-channel attempts each received 50/50 packets at 4.8 slow symbols. Automatic values use the measured switch allowance below. Those explicit-preamble tests used the older 4.8-symbol policy; they do not validate the newer 4.6-symbol slow dwell. The 4.6/0.3 ms two-profile bench received 197/200 at SF7/62.5 + SF8/500 with explicit 32-symbol preambles. The newer four-channel 5.1/6.1/7.7 tests also had misses, so this is a timing policy, not a claim of zero packet loss. The automatic fast preamble covers the blind interval during the slow visit, both switches and the acquisition margin. These settings do not guarantee reception during overlapping packets or long pauses in the firmware loop. Transmitters on each channel also need a long enough preamble. Changing the receiver's setting does not lengthen packets sent by other nodes.</p>"},{"location":"radio_profiles/#chirp-calculator-and-warnings","title":"Chirp calculator and warnings","text":"<p><code>get radio2.timing</code> (alias <code>get radio.timing</code>) reports the active pair in <code>radio,radio2</code> order: dwell in chirps, recommended preambles in symbols, and the switching/loop allowances. Before calibration it reports <code>timing self-test pending</code> and the provisional preambles. On the T1000-E, the Full Companion now uses RTC2 for both retune timing and scan visits (about 31 us resolution). Previously, the nRF52 <code>micros()</code> fallback counted 1,024 Hz RTOS ticks: a real sub-millisecond retune could be reported as exactly 977 us, and two ticks as 1,953 us. Those old numbers are timer artifacts, not measured RF costs. For SF7/62.5 on <code>radio</code> and SF8/500 on <code>radio2</code>, one live BLE-on read returned:</p> <pre><code>&gt; chirps=4.60,42.84; need=32,40; switch=706us; loop=0us; test=4/4,4/4 ready; WARN recommended preamble: radio2=40\n</code></pre> <p>Later good hops in another BLE-on trial raised the measured maximum to 763 us (840 us with the 10% guard); the recommendation stayed at 40 symbols.</p> <p>The measured switch duration is wall time, so an interrupt during the hop is included. Bluetooth's SoftDevice may still preempt application code; this clock correction does not stop it. Ordinary Companion/USB work in the main loop does not run inside the synchronous retune, but it can delay when the next scan visit begins. The zero fixed loop allowance is not a guarantee of lossless reception under arbitrary application load.</p> <p><code>WARN recommended preamble</code> identifies each profile whose recommendation exceeds the standard 32 symbols or its explicitly selected value. For example, with SF7/62.5 on the primary profile, <code>set radio2 910.5,500,7,5,rx,32</code> initially replies with <code>timing self-test pending</code>. Once active and measured, <code>get radio2</code> warns:</p> <pre><code>&gt; 910.500,500.000,7,5,rx,32; WARN recommended preamble: radio2=64; short override: radio2\n</code></pre> <p>Successful <code>set radio ...</code> replies also include the recommended preamble for each affected profile, calculated with the requested settings. A <code>short override</code> note identifies an explicit value below the estimate; it is not silently rewritten. Warnings are also included in profile settings/getters, scan info, temporary settings and schedule acknowledgments. These preamble-bearing replies also include <code>switch=547us</code> (or the current measured value) after the self-test for that exact profile pair. The first ACK for a new pair says <code>timing self-test pending</code> instead: it is sent before activation, so it cannot contain the future measurement. Query <code>get radio2</code> after activation to see the measured value beside the resulting preamble. <code>off</code> disables the dual-profile warning. <code>get radio2.status</code> shows self-test progress and the resulting guarded switch budget; its separate <code>max</code> field remains a lifetime diagnostic that can include failed/rolled-back retunes and is not used for calibration. If the recommendation exceeds 128, it additionally reports <code>WARN need &gt;128</code>; an automatic preamble stays at 128, which may not be enough for reliable reception on that pair. Explicit preambles are not rewritten and still use the radio's ordinary validation limits. A timing readout does not change settings or transmit a packet.</p> <p>The shared <code>RadioProfiles::calculateChirpTiming()</code> function accepts both tuples, optional visit times in microseconds, a per-switch allowance and loop margin. Using microseconds throughout:</p> <pre><code>T[i] = 2^SF[i] * 1000 / BW_kHz[i]\nslow = profile with the longer T (radio wins ties)\nL[slow] = max(requested_visit_us[slow], ceil(4.6 * T[slow]))\nL[fast] = max(requested_visit_us[fast], ceil(4.6 * T[fast]))\nO    = 2 * switch_us\nC    = L[radio] + L[radio2] + O\n\nP[slow] = round_up_to_8(max(32, 2 * C / T[slow]))\nP[fast] = round_up_to_8(max(32, (L[slow] + O) / T[fast] + 16))\n</code></pre> <p>Automatic selection uses the minimum visits to choose a preamble, then allocates the fast visit from half the slow preamble's duration. Diagnostics feed the actual allocated visits back into the same function, including longer visits caused by an explicit slow preamble. Too-short slow preambles that cannot fit both minimum visits remain rejected by the existing configuration validation.</p> <p>The automatic scheduler uses these same role-specific minima and computes:</p> <pre><code>slow_dwell = ceil(4.6 * T[slow])\nfast_dwell = max(ceil(4.6 * T[fast]),\n                 floor(P_configured[slow] * T[slow] / 2 - slow_dwell - O))\n</code></pre> <p>For the tested SF7/62.5 + SF8/500 pair with slow preamble 32, this yields 9,421 us slow and 21,197 us fast (41.40 fast chirps) with the 1,075 us guarded switch allowance above. Swapping <code>radio</code> and <code>radio2</code> swaps the allocations automatically.</p> <p>Production scheduling and automatic preambles use the self-tested maximum successful switch plus 10%, without an additional fixed loop allowance. Subsequent successful hops can only raise that allowance until the next profile change. The measured recommendation is rounded up to eight symbols and capped at 128 for automatic settings. The calculator and warnings retain the uncapped recommendation so a slow board is not shown as safe merely because it hit the limit. Older V4 tests peaked at 836 us (827 us in the 4.6/0.3 ms run), and Indicator reached 8428 us; these are historical measurements, not default budgets for other boards. The model preserves two slow-profile return opportunities and the existing 16-symbol fast-profile acquisition allowance. These are conservative policies, not a fitted success curve, and neither packet overlap nor arbitrary application stalls can be made safe by a finite preamble recommendation.</p> <p>See the implementation and validation notes.</p>"},{"location":"radio_profiles/#schedule-the-second-profile","title":"Schedule the second profile","text":"<p>Use UTC Unix timestamps (seconds), or <code>+N</code> for N whole minutes from now:</p> <pre><code>set radioat2 910.5,500,8,5,rxtx,START[,PREAMBLE]\nset tempradioat2 910.5,500,8,5,rxtx,START,END[,PREAMBLE]\nget radioat2\nget radioat2 1\nget tempradioat2\nget tempradioat2 1\ndel radioat2 1\ndel tempradioat2 all\n</code></pre> <p>Replace <code>START</code> and <code>END</code> with timestamps or <code>+N</code>, and the optional <code>PREAMBLE</code> with a number; omit the square brackets. Each schedule family has four slots. Times must be in the future and within 24 days. Overlapping temporary second-profile sessions are rejected. <code>radioat2</code> changes the saved second profile when it starts; <code>tempradioat2</code> restores the saved profile at its end. Pending schedules do not survive reboot.</p> <p>For example, <code>set tempradioat2 910.5,500,8,5,rxtx,+5,+15</code> starts in 5 minutes and restores in 15 minutes (10 minutes active). Both offsets are measured from the same node-clock snapshot when accepting the command, not from each other. <code>set radioat2 910.5,500,8,5,rxtx,+5</code> schedules a saved change in 5 minutes. Offsets must be positive whole minutes. Absolute and relative endpoints can be mixed; bare numbers still mean UTC seconds. Existing clock requirements apply.</p>"},{"location":"radio_profiles/#return-to-one-profile","title":"Return to one profile","text":"<pre><code>set radio2 off\n</code></pre> <p>This saves the disabled state and cancels all second-profile temporary activity and schedules.</p> <pre><code>set tempradio2 off\n</code></pre> <p>This ends temporary second-profile activity, cancels its temporary schedules and restores saved <code>radio2</code>. If the saved second profile is off, this returns to one profile. Packets/retries bound to an expired or changed session are discarded.</p>"},{"location":"radio_profiles/#power-saving-and-diagnostics","title":"Power saving and diagnostics","text":"<p>Dual mode suspends RX power saving and MCU idle sleep so receive visits can run promptly. The saved RX power-saving setting returns when profile 2 is off. The scan uses normal receive, following the CAD/RX measurements, with the updated 4.6-symbol dwell on the slower channel, followed by the remaining fast-channel visit. It does not use CAD for scanning. The separate CAD check before an initial transmission still follows <code>cad</code>.</p> <p>SX1262 dual-profile mode keeps the oscillator running in XOSC standby between visits, so each retune does not need to restart the TCXO. It restores the prior standby policy when returning to one profile, together with the saved RXPS setting. Radio reinitialization temporarily uses RC standby until the TCXO has been configured again. Other radio families retain their existing behavior. This does not disable the TCXO supply or its initial startup delay, and it is not conditional on 500 kHz bandwidth. Keeping the oscillator on uses additional power during the short standby intervals.</p> <p>The switch-time self-test is not a forced settling delay or a proof of RF acquisition. The earlier standalone keep-warm scan experiment averaged about 1.19 ms of overhead per hop (scan-cycle time minus both receive windows, divided by two). That experiment used a leaner receive path; it is not a measurement or guarantee of the production implementation. Measure the target board before shortening its timing margins or transmit preambles.</p> <p>The production-path XIAO timing test measured 1.434 ms average / 1.467 ms maximum with warm standby, compared with 3.166 ms average using RC standby: about 1.732 ms saved per hop. It covered 12,000 retunes across SF7/8/9 at 500 kHz paired with SF7/62.5 kHz. These measurements include observing BUSY low, but exclude application/UI scheduling and are not a packet-delivery qualification or a guarantee for other boards, especially those using I/O expanders.</p> <p>A same-image follow-up batching SF/BW/CR into one modulation command reduced warm switching from 1.444 ms to 1.158 ms average (batched maximum 1.198 ms), saving another 0.286 ms / 19.8%. RadioLib's modulation caches and LDRO calculation remain synchronized; frequency, preamble, packet guards, and RX restart are unchanged. A later HIL-only screening tested redundant standby/IRQ/buffer/packet setup and SPI transfer changes. Its fastest candidate measured 0.535 ms mean on XIAO but 8.203 ms on the Indicator, whose radio GPIOs go through an I2C expander. The validated production implementation now opts XIAO S3 WIO and Indicator LoRa into buffered 8 MHz SPI and a guarded fast-RX state machine. The <code>heltec_v4_kiss_modem</code> and <code>Station_G3_ESP32_kiss_modem</code> targets use the same guarded path only for KISS dual-profile scanning; their normal board roles keep their established HAL/timing policy. V4 uses its existing 160 MHz role override and Station G3 uses its base 240 MHz setting, but both still need an exact-image hardware timing check before a nominal 600 \u00b5s target is claimed. It skips redundant standby, IRQ mapping, buffer-base writes and modem queries only during an owned continuous RX-to-RX retune. Preamble/packet parameters (including the IQ workaround), stale-IRQ clearing, RX commands and BUSY waits remain. TX, CAD, sleep, reset, RXPS and failed commands revoke reuse; failed RX startup rolls back the profile. Sleep entry uses standby and wake restores the existing TCXO voltage/delay. Other variants do not opt in to faster SPI or the fast-RX state machine. Within a valid owned fast-RX retune, identical acknowledged SF/BW/CR/LDRO settings now reuse the previous modulation command: frequency-only hops omit <code>SetModulationParams</code> (0x8B). A changed effective LDRO value also forces a write, including when automatic LDRO policy changes. Ordinary setters and lost RX context invalidate that acknowledgement; initial setup, reset, sleep, failed commands and full RX setup conservatively reapply the tuple. Frequency, preamble/packet setup, IRQ clearing and BUSY checks are unchanged. This follow-up has same-image hardware measurements: frequency-only hops averaged 0.452 ms on XIAO and 7.601 ms on Indicator. The mixed-bandwidth timing figures above predate it. Four-channel SF6 scans still missed packets; faster switching is not proof of loss-free acquisition. See production and USB validation for current measurements, lifecycle tests and limitations. The Indicator result shows why each board now measures its own switch time. That measurement adjusts automatic preambles and dwell, but it cannot verify RF acquisition or lengthen packets transmitted by other nodes.</p> <p>Single-channel noise-floor calibration and RSSI interference comparison are suspended while scanning. Retries use the radio's preamble/header activity indicators. LR2021 extra-SF side detectors are suspended and restored as well.</p> <p><code>get radio2.status</code> reports the active second-profile mode, MeshCore RX/TX counts for each profile, switch count, switch failures, longest measured switch and both effective preambles. A long switch time or rising error count indicates that the chosen settings need investigation on that board.</p> <p><code>get radio2.scan</code> shows which profile goes first, the two idle receive-window lengths in microseconds, and both effective preambles. It reports <code>off</code> in single-profile mode.</p>"},{"location":"radio_profiles_validation/","title":"Dual-profile receive validation","text":"<p>These measurements exercise the production two-profile implementation on one SX1262 transceiver, using a Heltec V4 repeater as receiver and a XIAO ESP32-S3 with a Wio LoRa module as transmitter. They follow the dedicated mixed-bandwidth scan experiment.</p> <p>Counts, diagnostic replies and firmware/source hashes are in radio_profiles_results.json.</p> <p>The primary profile is 909.5 MHz, SF7, 62.5 kHz, CR 4/5, preamble 32. The secondary is 910.5 MHz, 500 kHz, CR 4/5, with SF9, SF8 or SF7. Scanning uses normal RX, starts with the slower profile, and reserves two slow visits per slow preamble. Transmitters must use the corresponding preamble too.</p>"},{"location":"radio_profiles_validation/#method-and-limits","title":"Method and limits","text":"<p>The transmitter sends MeshCore adverts at varied intervals. The receiver's per-profile MeshCore RX counters are compared with the transmitter's completed TX counters before and after each run. Initial OTA announcements can add packets beyond the manually requested adverts; the table includes those transmissions. These are aggregate counters, not sequence-matched payload captures.</p> <p>Runs use one transmitting profile at a time and a strong signal. They do not measure simultaneous traffic, weak-signal reception, interference or months of uptime. A single transceiver remains unavailable to the other profile while receiving or transmitting a packet. A clean finite run is evidence for a timing choice, not a guarantee that it cannot drop packets.</p>"},{"location":"radio_profiles_validation/#five-symbol-baseline","title":"Five-symbol baseline","text":"<p>Slow visits were 10.240 ms and fast visits 6.528 ms, plus actual switching time. The longest observed profile switch was 4.416 ms; no switch failures were reported.</p> Fast profile Fast preamble Fast RX / TX Slow RX / TX SF9 / 500 48 54 / 54 30 / 30 SF8 / 500 72 49 / 50 \u2014 SF8 / 500 80 49 / 50 \u2014 SF8 / 500 88 50 / 50 30 / 30 SF7 / 500 120 50 / 50 30 / 30 <p>The SF8 automatic preamble retains a measured floor of 88 symbols. Automatically selected preambles always round up in steps of eight.</p>"},{"location":"radio_profiles_validation/#fractional-symbol-tuning","title":"Fractional-symbol tuning","text":"<p>The initial sweep started at 4.2 slow symbols, with an increase of 0.1 planned for any slow-channel loss. That first sweep passed all three fast settings. Each completed run used 50 requested adverts per profile. The SF8 fast run was interrupted to check SF9 preamble 32, then restarted; only its completed run is included below.</p> Slow symbols Fast profile Fast preamble Fast RX / TX Slow RX / TX 4.2 SF9 / 500 48 50 / 50 50 / 50 4.2 SF9 / 500 32 50 / 50 50 / 50 4.2 SF8 / 500 88 50 / 50 50 / 50 4.2 SF7 / 500 120 50 / 50 50 / 50 <p>The four completed pairings received 200/200 packets on the slower channel and 200/200 on the faster channel. No switch failures were reported; the longest measured switch during the 4.2-symbol sweep was 4.407 ms.</p> <p>The explicit SF9 preamble-32 check uses the same 8.602 ms slow and 8.166 ms fast windows as the preamble-48 check. Only the fast transmitter's preamble changes. The automatic SF9 calculation still reserves a 48-symbol preamble for the configured switching and loop-jitter budgets.</p>"},{"location":"radio_profiles_validation/#shorter-fast-preambles","title":"Shorter fast preambles","text":"<p>The follow-up starts with preamble 48 on both fast settings. Each miss advances the next candidate by eight symbols. The receive-window budgets stay at 4.2 slow symbols and the same remaining fast-channel time.</p> Fast profile Preamble Fast RX / TX SF8 / 500 48 49 / 50 SF8 / 500 56 50 / 50 SF7 / 500 48 42 / 50 SF7 / 500 56 41 / 50 SF7 / 500 64 45 / 50 SF7 / 500 72 50 / 50 <p>The slower channel passed 50/50 paired with SF8/56, but then received 49/50 paired with SF7/72. Across the completed 4.2-symbol slow-channel runs, that is 299/300. This later miss invalidated the provisional 4.2-symbol choice and triggered the next headroom test at 4.3 symbols. Fast-preamble baselines carry forward as 32 for SF9, 56 for SF8 and 72 for SF7, advancing by eight on a miss.</p> <p>At 4.3 symbols, the SF9/32 pairing received 100/100 slow packets and 50/50 fast packets. The next SF8/56 pairing received only 42/50 slow packets, so that candidate also failed. A control run with scanning disabled received 50/50 on the slow channel. At 4.4, SF8/56 passed 100/100 slow and 50/50 fast, but the SF7/72 pairing then received 49/50 slow packets.</p> <p>At 4.5, the SF7 pairing passed 100/100 slow packets. Fast preamble 72 received 47/50, so the next baseline increased to 80 and passed 50/50. The following SF8/56 slow run received 49/50, triggering 4.6 symbols. Baselines now carry forward as SF9/32, SF8/56 and SF7/80.</p> <p>At 4.6, both SF8/56 and SF7/80 passed 100/100 slow packets and 50/50 fast packets. The following SF9/32 slow run received 49/50, triggering 4.7 symbols. There were no switch failures; the longest observed switch was 4.414 ms.</p> <p>At 4.7, the SF9/32 slow run passed its first 50 packets but received 99/100 over the full run. This triggered 4.8 symbols, with the same fast preamble baselines. No fast-channel run was started for the 4.7 candidate.</p>"},{"location":"radio_profiles_validation/#selected-bench-baseline-48-slow-symbols","title":"Selected bench baseline: 4.8 slow symbols","text":"<p>The 4.8-symbol sweep passed all three slow-channel checks, totaling 300/300. Slow visits are 9.831 ms and fast visits 6.937 ms, plus actual switching time. The longest measured switch was 4.491 ms, with no switch failures.</p> Fast profile Fast preamble Fast RX / TX Slow RX / TX SF9 / 500 32 50 / 50 100 / 100 SF8 / 500 56 49 / 50 100 / 100 SF8 / 500 64 50 / 50 \u2014 SF7 / 500 80 50 / 50 100 / 100 <p>The SF8 miss advanced its baseline from 56 to 64, exactly eight symbols. Its slow-channel check preceded that increase; changing the fast preamble leaves the idle receive-window calculation unchanged. The final fast-channel attempts received 150/150, using explicit preambles 32 / 64 / 80 for SF9 / SF8 / SF7. These become the starting values for further tests, increasing by eight on a fast-channel miss. A slow-channel miss instead advances the listen window by 0.1 symbol.</p> <p>The production automatic preambles remain 48 / 88 / 120, retaining the switching, loop-jitter and acquisition budgets. The shorter explicit values are bench results under the conditions above, not a guarantee for other boards or traffic patterns.</p>"},{"location":"radio_profiles_validation/#transmit-policy","title":"Transmit policy","text":"<p>Hardware checks send three zero-hop adverts from the V4 with the XIAO listening on profile 2. OTA startup traffic is allowed to settle before taking the counter snapshots. The completed cases are:</p> V4 profiles and policy TX on primary / secondary Received by XIAO Permanent / permanent, <code>auto</code> 3 / 3 3 Permanent / permanent, <code>off</code> 3 / 0 0 Permanent / temporary, <code>auto</code> 3 / 0 0 Permanent / temporary, <code>on</code> 3 / 3 3 Secondary RX only, <code>on</code> 3 / 0 0 Temporary / temporary, <code>auto</code> 3 / 3 3 <p>A separate isolation check issued three explicit OTA announce commands with normal <code>radio</code>, RX-only <code>tempradio2</code> and <code>radio2.cross auto</code>. The completed TX counters stayed unchanged on both profiles (0 / 0), confirming that locally generated OTA traffic does not fall back to the normal channel in that mode.</p> <p>Turning <code>radio2</code> off stopped scanning. A one-minute <code>tempradio2</code> session also returned to one profile on expiry. Rebooting with a saved SF8 RX profile and an active temporary SF9 RX/TX profile cleared the temporary session and restored the saved SF8 profile, including its automatic 88-symbol preamble.</p>"},{"location":"radio_profiles_validation/#ota-discovery-while-retaining-the-main-channel","title":"OTA discovery while retaining the main channel","text":"<p>Both boards ran normal SF7 / 62.5 kHz on the primary and temporary SF8 / 500 kHz RX/TX on the secondary, using <code>radio2.cross auto</code> and automatic preambles 32/88. The XIAO discovered the V4's firmware catalogue over profile 2, and both boards recorded received and transmitted OTA packets there. Ten V4 zero-hop adverts then arrived on the XIAO's primary profile (10/10), with both temporary second profiles still active. The XIAO reported no switch failures and a longest switch of 4.547 ms during this check.</p> <p>This hardware check covers discovery, bidirectional OTA traffic and concurrent availability of the main channel between packets. It does not perform a complete firmware transfer or install. Byte-exact transfer validation is provided by the shared OTA software tests described below.</p>"},{"location":"radio_profiles_validation/#software-coverage","title":"Software coverage","text":"<p>Native tests cover identical-packet fanout, separate retry ownership and coding rates, channel-busy backoff, generation changes, temporary-session isolation, deferred replies and stale-packet removal. Tests using the production CLI cover parsing, persistence failures, schedules, expiry and clock rollover. A physical radio mock exercises the production scan transitions, pending RX interrupts, RX power-saving restoration and failed profile switches.</p> <p>The full native suite passed 1,422 cases after the RX-only OTA isolation fix; all eight KISS modem tests also passed. Subsequent timing changes through 4.8 symbols passed the 63-case retry/profile suite and production CLI and scan harnesses. Shared OTA transfer tests passed byte-exact checks with AddressSanitizer and UndefinedBehaviorSanitizer for ESP32 and nRF52 variants.</p> <p>Build coverage includes the Heltec V4 repeater, room server, sensor and terminal chat, the Full XIAO Companion, and the nRF52 T1000-E repeater. The nRF52 result is a build check; these receive measurements use the ESP32/SX1262 boards above.</p>"},{"location":"radio_profiles_validation/#hardware-restored-after-validation","title":"Hardware restored after validation","text":"<p>Both boards were returned to their original B soak images after the checks: <code>v1.17.1-soak-v4-B</code> and <code>v1.17.1-soak-xiao-B</code>. The V4 retained 909.5 MHz, SF7 / 62.5 kHz, CR 4/5 and TX 0; the XIAO retained 910.525 MHz with the same modulation and TX 22. Both reconnected to Wi-Fi and their custom MQTT service. The soak logs resumed under <code>B-post-radio2-soak</code>. These restored images are the earlier memory-soak firmware; the new dual-profile code is validated by the finite tests above, not by a months-long uptime run. The Pi's soak service and Indicator telemetry were also healthy after restoration.</p>"},{"location":"radio_receive_calibration/","title":"Radio receive calibration and recovery","text":"<p>Noise calibration collects 64 idle RSSI samples at least 50 ms apart. A quiet block takes about 3.2 seconds. Both continuous RX and temporary RXPS calibration windows allow up to 30 seconds; a partial block times out without publishing. Periodic requests coalesce while a block is active. RXPS resumes after a complete block, including a held block, or at timeout. Receive and transmit activity are never interrupted just to finish calibration.</p> <p>The block estimate is the 12.5th percentile: the average of the eighth and ninth sorted samples, retaining fractional dBm. A published update uses 25% of the previous floor and 75% of the new estimate, with a -120 dBm lower bound. Initial calibration and explicit gain/tuning changes seed a new baseline. The old published value remains available while collecting. An AGC reset drops partial samples while retaining a valid baseline for channel checks.</p> <p>An estimate more than 15 dB above the established floor is held twice. The third consecutive complete high block is accepted, allowing recovery after a permanent ambient rise. A normal or quieter complete block clears the hold. Partial blocks do not advance it. There is no admission threshold based on the old floor, so an old low baseline cannot reject every sample from a higher floor.</p> <p>Hardware captures with sustained different-SF/BW traffic showed the median and lower quartile following the interferer. The 12.5th percentile retained the quiet background in those captures. It needs at least nine background samples out of 64 to avoid higher-valued traffic entirely. Nearly continuous interference or enough low outliers can still mislead it. The rise hold delays large changes but cannot identify their source.</p> <p>RSSI sampling waits 20 ms after every receive re-arm, including CAD and TX completion, to avoid unsettled frontend readings. The ten-second trial window often failed to complete during heavy traffic with that settling guard; the 30-second cap allows more idle opportunities. Partial blocks still time out without publishing. Longer collection spends more time in continuous RX when RXPS is enabled. A quiet minimum is about 3.2 seconds; real completion time also depends on packet activity and main-loop scheduling.</p> <p>On radios with a mode probe, each eligible RSSI sample first checks that the chip has not silently left RX. Confirmed standby/non-RX discards the partial block without changing the published floor. Rejected attempts are also spaced 50 ms apart. BUSY and packet ownership block sampling; families without a mode probe retain their existing RSSI path.</p> <p>CAD has a bounded wait, stops RX duty cycling before scanning, and re-arms the configured receive mode on success, busy detection, or error. A completed or currently receiving packet owns the radio and blocks CAD. A packet interrupt arriving during re-arm is retained. Failed re-arm and a newly arrived packet both defer transmission.</p> <p>SX126x wrappers additionally run a recovery watchdog at most once per 10 seconds while continuous RX is expected. RXPS sleep, busy SPI, pending packets, and invalid status reads do not count as non-RX evidence. Two confirmed non-RX observations request soft recovery; a third uses the existing hard recovery path where supported. An observed healthy RX state clears the sequence. Recovery preserves tuning, TX power, receive gain, and the operator's power-saving intent. The existing radio liveness and RXPS watchdogs remain active for other failures.</p> <p>The radio liveness watchdog measures time without a successfully received packet. Only a positive <code>recvRaw()</code> result restarts its observation window; TX completion, CAD interrupts, and failed packet reads do not. Reception counts even if application parsing rejects the packet or the packet pool is full. The check runs after pending RX is drained and TX completes, before the next queued transmission, so sustained outbound traffic cannot postpone recovery.</p> <p>The default silence thresholds are 30 minutes for a soft RX/AGC re-arm and 12 hours for a radio-only hard recovery where supported. MQTT observer <code>radio.watchdog</code> settings can override the soft interval. A successful hard recovery starts a fresh observation window to limit repeated resets on a quiet mesh; a failed hard recovery remains escalated and retries after 30 seconds. Targets with <code>RADIO_LIVENESS_SOFT_ONLY</code> repeat soft recovery at the soft interval because their radio cannot be reset independently. These recoveries do not reboot the MCU. The repeater's <code>rx.watchdog</code> is a separate whole-board reboot watchdog, enabled by default with a 24-hour sliding deadline since the last received packet passed MeshCore parsing. Its timer is updated before receive delays and routing filters; raw LoRa reads rejected by the parser do not count. MeshCore parsing checks the packet structure, not sender authentication or decryption of traffic addressed to other nodes. Temporary radio windows of at least 12 hours use a 12-hour deadline; shorter windows disable that reboot watchdog until the window ends. The temporary timing overrides are held in RAM and do not replace saved normal-mode preferences.</p> <p>The status read uses the two-byte GetStatus transaction. The pinned RadioLib getStatus() helper requests zero copied data bytes, so its return value is not usable for this mode check. The dedicated read restores the normal SPI command layout afterward and does not wake a duty-cycling radio to inspect its mode.</p> <p>Validation lives in <code>test_noise_floor_estimator</code>, <code>test_rx_power_saving</code>, <code>test_radio_liveness</code>, <code>test_radio_receive_contract.py</code>, and <code>test_sx126x_receive_mode.py</code>.</p>"},{"location":"rak3401_mota_chain/","title":"RAK3401 1W repeater compact LoRa update chain","text":"<p>Status: published prerelease for controlled, recoverable lab use. On 29-Aug-2026 steps 1-9 completed on the target RAK3401 and are byte-for-byte identical to the corresponding transitions in the physically passed <code>fd98bc90</code> chain. The replacement step 10 installs the current <code>3f6eddd5</code> endpoint. That replacement package and the hardened current runner have passed offline reconstruction plus the exact deployed bootloader simulator, but have not had a new physical end-to-end run. Use the lab gate and keep local DFU/SWD recovery available. Multi-hop and alternate-bandwidth estimates remain planning data, not physical qualification.</p> <p>The prerelease is <code>rak3401-mota-v1.16.07-c1caa5ad-to-v1.17.1.6-3f6eddd5</code>. Use this asset:</p> <pre><code>RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip\n</code></pre> <ul> <li>prerelease ZIP SHA-256: <code>135783dd8777490db2422a7543f7d80e3cf03f621d5ac362da930abbc1850dc4</code></li> <li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>93835ed497c579be0a2322292e7f15ab095e7c8ab7892833fe7df3130dbdaba4</code></li> <li>endpoint image SHA-256: <code>cd1e9b819f9e918f9f2ceaf37b8a74bf242e2be78f319af2cf02a42d7729d0f4</code></li> <li>endpoint EndF body hash: <code>9BD7CF682EE065AE</code></li> </ul> <p><code>--verify-only</code> remains the safe default. Live preflight and installation of this prerelease require <code>--accept-test-candidate</code>. That switch bypasses only the prerelease-status gate; it does not bypass the archive, identity, bootloader, route, watchdog, reachability, or post-boot checks.</p>"},{"location":"rak3401_mota_chain/#exact-destination","title":"Exact destination","text":"<p>This chain is intentionally specific to one firmware lineage and hardware target:</p> <ul> <li>target ID: <code>2FA509C1</code></li> <li>hardware: <code>RAK_3401</code></li> <li>role: <code>RAK_3401_repeater_lora_ota_no_external_sensors</code></li> <li>start: <code>v1.16.7.0-c1caa5ad</code>, EndF <code>71F4026CBE4B8B74</code></li> <li>endpoint source: MeshCore <code>3f6eddd5c20f1fa3df6ba1cc208efbe3e2fffb43</code></li> <li>endpoint label: <code>v1.17.1.6-halo-keymind-cascade-dev-3f6eddd5</code></li> <li>endpoint packed version: <code>0x01110106</code></li> <li>deployment target key: <code>63d8df6387eaffd2e25db7d2a8ad967a65202182a48d681d7e7a9260f917280d</code></li> </ul> <p>The exact starting application is the <code>lora-ota-v1.16.07-halo-keymind-cascade-dev-3a6af3bf</code> RAK3401 asset. Its outer ZIP SHA-256 is <code>58ead2ea18efafda186bc9d983fe08cdf65f69b0e5a3a1c72c18fe35948a254c</code>; its 566,912-byte <code>firmware.bin</code> SHA-256 is <code>4301fc63ebd661c70f9bc40e7eca44d3cb8a358cb3c0075e700d9676a57478cb</code>. The endpoint build ZIP SHA-256 is <code>a9fca9be145a96feb650b57c43b5ed173d74d2f3194da12e31b1c54352635b56</code>.</p>"},{"location":"rak3401_mota_chain/#retained-and-omitted-hardware-support","title":"Retained and omitted hardware support","text":"<p>Despite the legacy <code>no_external_sensors</code> target name, the endpoint retains the RAK12501 GPS provider and the common INA3221, INA219, INA226, and INA260 I2C voltage/current monitors. Install RAK12501 in sensor slot A. Do not use slot D with the RAK13302 1 W radio because the GPS reset/PPS signals overlap the radio's BUSY/DIO1 wiring.</p> <p>The reduced profile omits optional external environmental and ranging devices: AHTX0, BME280, BMP280, SHTC3, SHT4x, LPS22HB, MLX90614, VL53L0X, BME680, BMP085, RAK12035, and BME680 BSEC. Board radio, display, buttons, battery telemetry, GPS, and the INA monitor family remain. No additional \u201cremove I2C temperature\u201d image is needed: the optional I2C temperature/environment drivers are already in the omitted set, while removing the remaining I2C/INA support would discard desired voltage/current monitoring and create another firmware identity without helping this route.</p> <p>Do not use the chain on another target ID, hardware family, starting image, or firmware body hash. The runner checks all four.</p>"},{"location":"rak3401_mota_chain/#why-the-deployed-otafix24-and-old-staging-ceiling-work","title":"Why the deployed OTAFIX2.4 and old staging ceiling work","text":"<p>The deployed bootloader is not changed and no package uses the newer expanded <code>0xED000</code> ceiling. Each package remains bottom-aligned below the old bootloader's <code>0xD4000</code> scan ceiling. Its detools workspace is page-aligned and must satisfy:</p> <pre><code>0x26000 + inplace_memory &lt;= staged_package_start &lt; 0xD4000\n</code></pre> <p>The old bootloader already reads and validates that encoded detools geometry before its first destructive write. The previous application receiver was the limiting part: it reserved a fixed <code>0x98000</code> workspace before accepting a download. Step 1 therefore remains byte-for-byte identical to the physically passed 89,844-byte package. Step 2 is a 46,364-byte fixed-workspace package that installs the compatibility receiver. Later receivers stage above the real EndF image extent and let the bootloader enforce each package's selected workspace.</p> <p>Every package in this candidate is an ordinary application container using format ABI 2 and in-place codec 2. The historical bridge applications scan the bootloader capability marker byte-by-byte, so they recognize the released <code>0.9.2-OTAFIX2.4</code> marker at absolute address <code>0xFCD16</code>. That immutable marker advertises ABI 2, codec mask <code>0x0004</code>, and internal storage profile 0. The <code>3f6eddd5</code> endpoint retains the matching legacy application-update fallback. Its separately compiled internal bootloader-update feature remains unavailable because privileged self-update requires a current ABI 3 marker with the exact storage profile. Installing this chain therefore does not replace the bootloader, and the final application can still accept a future valid ABI-2/codec-2 application update.</p> <p>The exact installed bootloader is the <code>0.9.2-OTAFIX2.4</code> RAK4631 asset. Its outer ZIP SHA-256 is <code>5e29e7a8982cc2ed5f8868435556eb09387250fe5b9a7e8443bac325247dfed1</code>; its 191,040-byte <code>sd_bl.bin</code> SHA-256 is <code>a97f834388db0f1da6c29f6d8f458ff6d3e6a26034709044566384838919bb23</code>. The exact simulator was compiled from release commit <code>d73de8372e89b8ef352747c8bc7a1aaeab80fbfe</code>; its executable SHA-256 is <code>9dacf24b1023fe2f4c620419417649ccc9538dd4a611b47bc19b7fedb97ceba6</code>.</p> <p>The schema-2 exhaustive search checked 1,799 candidate geometries and found 12 feasible forward edges in the declared exact 12-node inventory. It found one shortest ten-package route and selected the smallest total container bytes as the secondary objective. This minimum applies only to that declared inventory and geometry table, not every conceivable new bridge image. The selected route is:</p> Step From To Workspace Package Margin 1 1.16.7.0 1.16.7.9 <code>0x98000</code> 89,844 0 2 1.16.7.9 1.16.7.10 <code>0x98000</code> 46,364 40,960 3 1.16.7.10 1.16.8.7 <code>0x91000</code> 106,029 12,288 4 1.16.8.7 1.16.9.105 <code>0x89000</code> 149,927 0 5 1.16.9.105 1.16.9.110 <code>0x8E000</code> 111,312 16,384 6 1.16.9.110 1.16.9.113 <code>0x8F000</code> 120,624 4,096 7 1.16.9.113 1.16.9.117 <code>0x8B000</code> 139,637 0 8 1.16.9.117 1.16.10.0 <code>0x7E000</code> 174,202 20,480 9 1.16.10.0 1.17.1.3 <code>0x6B000</code> 271,569 0 10 1.17.1.3 1.17.1.6 <code>0x76000</code> 197,825 28,672 <p>Total mOTA transfer data is 1,407,333 bytes. <code>ROUTE.json</code>, <code>CHAIN.csv</code>, and <code>validation-results.json</code> in the bundle pin the exact geometry and image hash for every transition.</p> <p>Steps 1-9 are byte-for-byte identical to the transitions that passed on the physical RAK3401. The replacement step 10, from the physically reached <code>FE65A6135A1E7B3F</code> v1.17.1.3 body to <code>9BD7CF682EE065AE</code>, has offline qualification only. All ten packages passed independent container checks, zero-filled and erased-workspace reconstruction, and the exact deployed <code>0.9.2-OTAFIX2.4</code> simulator. Those results prove the package bytes and apply geometry; they are not a physical claim for the replacement step 10 or the hardened runner.</p> <p>The 171-byte transport DEFLATE support lands only in the final <code>3f6eddd5</code> application. The starting receiver and every receiver that accepts steps 1-10 lack that inflate path, so all ten legacy-chain transfers remain raw and the 1,407,333-byte total above is not automatically reduced over LoRa. A later update can negotiate transport compression after this endpoint is running; the application inflates before staging, and the immutable bootloader still applies an ordinary ABI-2/codec-2 container.</p>"},{"location":"rak3401_mota_chain/#host-requirements","title":"Host requirements","text":"<p>Install Python 3.9 or newer, <code>meshcli</code> 1.6.0 or newer, the current <code>motatool</code>, and an OTA-enabled Full Companion or repeater that can seed mOTA files.</p>"},{"location":"rak3401_mota_chain/#verify-offline","title":"Verify offline","text":"<p>No password or device is needed:</p> <pre><code>python3 tools/lora_ota/rak3401_mota_chain.py \\\n  --bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip \\\n  --work-dir ./rak3401-mota-chain-work \\\n  --motatool /path/to/motatool \\\n  --verify-only\n</code></pre> <p>When given the ZIP, the runner checks its pinned outer hash and binds the extraction cache to that exact archive. An explicitly supplied extracted root starts at the pinned inner checksum list. In either case it checks complete inner coverage, all ten manifests, continuity, image anchors, both recovery images, and every container with <code>motatool</code>. Passing this command means offline and simulator qualification only; it does not unlock live use.</p>"},{"location":"rak3401_mota_chain/#guarded-prerelease-lab-command","title":"Guarded prerelease lab command","text":"<p>These direct-link arguments match the physical transition setup, but the current package replaces step 10 and the current host runner contains later cleanup and recovery fixes. Neither has been cleanly rerun through the whole chain. Keep local USB/SWD recovery available. The candidate switch bypasses only the prerelease-status block; all identity, checksum, bootloader, route, watchdog, reachability, and post-boot gates still run.</p> <p>Restore the test start locally with <code>recovery/test-start/RAK3401-test-start-v1.16.7-c1caa5ad.uf2</code>, then run:</p> <pre><code>export MESHCORE_ADMIN_PASSWORD='password'\n\npython3 tools/lora_ota/rak3401_mota_chain.py \\\n  --bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip \\\n  --work-dir ./rak3401-mota-chain-work \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp 192.168.1.51:5001 \\\n  --source-cli-tcp 192.168.1.51:5002 \\\n  --source-shares-controller \\\n  --target-key 63d8df63 \\\n  --temp-radio 909.950,500,5,5,120 \\\n  --ota-hops 0 \\\n  --legacy-full-airtime \\\n  --motatool /path/to/motatool \\\n  --accept-test-candidate \\\n  --yes\n</code></pre> <p>Keep the work directory. Rerunning the same command resumes only when the live EndF body hash matches an exact chain node. Never manually skip a package. <code>--legacy-full-airtime</code> temporarily sets the destination airtime factor to zero and restores it at the endpoint. Use that option only where the selected frequency and local duty-cycle rules permit a full transmit budget; omit it otherwise.</p>"},{"location":"rak3401_mota_chain/#superseded-b40d2e6c-prerelease","title":"Superseded <code>b40d2e6c</code> prerelease","text":"<p>The immediately preceding prerelease remains pinned for offline provenance:</p> <ul> <li>release: <code>rak3401-mota-v1.16.07-c1caa5ad-to-v1.17.1.5-b40d2e6c</code></li> <li>asset: <code>RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.5-b40d2e6c.zip</code></li> <li>outer ZIP SHA-256: <code>8e7f0c2565f37d4372fa51dc3ba72b591e7f38b74be09303e48641623f99bce4</code></li> <li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>29a02a6c4c83eafa80168a80562b0ded5d8432e6cc02cfaca289cb2ed426681a</code></li> <li>endpoint image SHA-256: <code>a7761da8af1f2447d7f01d72e2b1456b99c0e874a165d6483f48ab1f58e8d905</code></li> <li>endpoint EndF body hash: <code>1FA6AAA3C28D8BD8</code></li> </ul> <p>Its first nine packages are byte-for-byte identical to the current release and the physical <code>fd98bc90</code> evidence. Its different step 10 had offline qualification only. The runner recognizes this exact archive separately and keeps live use gated; it is not interchangeable with the current <code>3f6eddd5</code> asset.</p>"},{"location":"rak3401_mota_chain/#legacy-fd98bc90-physical-and-swd-qualification","title":"Legacy <code>fd98bc90</code> physical and SWD qualification","text":"<p>The earlier local candidate remains the exact physical evidence source for this route:</p> <pre><code>RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.5-fd98bc90.zip\n</code></pre> <ul> <li>candidate ZIP SHA-256: <code>c0b33f4568985e8b2b8dc99411295907212cf2bad21764b6333d5e0ba298fd61</code></li> <li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>3f8c4af8096b96a4aa6506825c387cc8a06f74d5213a29c9387bd11689546881</code></li> <li>endpoint image SHA-256: <code>31c182c888ceb1135e5afb2376610d93cee2e807b556c838e07fd4486c79d095</code></li> <li>endpoint EndF body hash: <code>9179B98432895924</code></li> </ul> <p>All ten exact <code>fd98bc90</code> transitions completed on the RAK3401 with its deployed <code>0.9.2-OTAFIX2.4</code> bootloader and a Heltec V4 source at 909.950 MHz / 500 kHz / SF5 / CR5. Every intermediate EndF hash matched. Independent SWD readback then matched the endpoint application, original bootloader, SoftDevice/MBR, and UICR byte-for-byte. Steps 1-9 are also the exact first nine packages in the <code>b40d2e6c</code> and <code>3f6eddd5</code> prereleases. All three candidates have different step 10 packages or endpoints, so the physical result and step-10 timing must not be attributed to either later prerelease.</p>"},{"location":"rak3401_mota_chain/#measured-direct-link-timing-for-fd98bc90","title":"Measured direct-link timing for <code>fd98bc90</code>","text":"<p>The first <code>ready to install</code> transfer ages were:</p> Step Blocks Transfer 1 88 598 s 2 45 42 s 3 103 81 s 4 146 105 s 5 109 76 s 6 118 94 s 7 136 102 s 8 170 127 s 9 264 187 s 10 169 193 s <p>The physically observed bulk-transfer total for those exact legacy packages is 1,605 seconds (26m45s). The log came from the pre-cleanup-fix runner revision. Step 1 was measured before the host began forcing source RXPS off and is therefore a conservative outlier. A new complete run with that fix is projected at roughly 18\u201319 minutes of bulk transfer, but that projection is not a substitute for the measured total. Allow about 70\u201375 minutes direct at BW500 for validation, ten transfers, installs/reboots, retained-store checks, and final restoration.</p> <p>The legacy step 10's longer per-block time was not a V4 TempRadio delay: the source RXPS readback was off. Its v1.17.1.3 requester uses non-overlapping adaptive flights and a five-second recovery floor and logged more block reloads than step 8. The V4 itself intentionally schedules its local radio handoff after 1.5 seconds so the normal-channel command reply can drain; the host waits three seconds and then checks the live TempRadio state.</p>"},{"location":"rak3401_mota_chain/#live-progress-and-speed-sanity-checks","title":"Live progress and speed sanity checks","text":"<p>The runner watches <code>motatool serve -v</code> locally, so its quarter-progress reports do not consume LoRa airtime. At BW500 direct, physically measured steps 2\u20139 averaged about 1.1\u20131.4 newly requested payload blocks per second; the legacy step 10 averaged about 0.88 blocks/s, and step 1's 0.15 blocks/s was the known pre-RXPS-fix outlier. Use those only as bench sanity ranges, not guarantees. Relays, narrower bandwidths, interference, and recovery reads lower the rate.</p> <p>Healthy output keeps advancing from <code>[download] passive source progress x/y</code> to <code>source read all y payload blocks</code>, followed by destination status <code>ready to install y/y (100%)</code> for the same manifest ID. Aggregate reads above the unique block count indicate recovery/retry traffic. A radio-scaled no-progress window causes one destination status check; the transfer timeout leaves the partial download staged for an exact-package resume. Stop and diagnose instead of installing if the manifest changes, progress remains flat through those checks, the final receiver count is not <code>y/y</code>, or the measured rate is far below the matching bandwidth/hop estimate without an understood RF cause.</p> <p>For planning only, scale the conservative measured <code>fd98bc90</code> 26m45s bulk baseline by the qualified adaptive-preamble airtime and by each additional relay transmission:</p> Bandwidth, SF5/CR5 Direct / 0 relays 1 relay 2 relays 500 kHz 26m45s 53m30s 1h20m15s 250 kHz 46m51s 1h33m42s 2h20m33s 125 kHz 1h27m03s 2h54m07s 4h21m11s 62.5 kHz 2h54m07s 5h48m15s 8h42m23s <p>These are transfer-only estimates, not measured alternate-bandwidth or relay results. Packet loss, relay contention, discovery, administrative commands, staged verification, and ten reboot cycles add time. The bandwidth factors are not simple powers of two because the adaptive wire preamble is 128 symbols at 500 kHz, 64 at 250 kHz, and 32 at 125/62.5 kHz.</p>"},{"location":"rak3401_mota_chain/#manual-operation","title":"Manual operation","text":"<p>The automated runner is preferred because it binds every transition to the expected MID and body hash. The manual details below document the checks used during qualification and recovery; they are not permission to skip the runner's candidate gate. Keep a written copy of each original setting and never skip a step even when a later package appears in <code>ota ls</code>.</p>"},{"location":"rak3401_mota_chain/#1-verify-and-extract-the-asset","title":"1. Verify and extract the asset","text":"<pre><code>sha256sum RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip\nunzip RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5.zip\ncd RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.6-3f6eddd5\nsha256sum -c SHA256SUMS.txt\nfor package in motas/*.mota; do motatool verify \"$package\" || exit 1; done\n</code></pre> <p>The outer hash must be <code>135783dd8777490db2422a7543f7d80e3cf03f621d5ac362da930abbc1850dc4</code>, and the SHA-256 of the extracted <code>SHA256SUMS.txt</code> must be <code>93835ed497c579be0a2322292e7f15ab095e7c8ab7892833fe7df3130dbdaba4</code>. Do not continue after any checksum or verification error.</p>"},{"location":"rak3401_mota_chain/#2-record-and-prepare-the-destination","title":"2. Record and prepare the destination","text":"<p>Before changing anything, save the complete replies from:</p> <pre><code>ver\nota self\nget bootloader.ver\nget system.watchdog\nget radio.rxps\nget powersaving\nget rxdelay\nget af\nota config\n</code></pre> <p>The starting <code>ota self</code> hash must be <code>71F4026CBE4B8B74</code>, the target must be <code>2FA509C1</code>, and the hardware must be <code>RAK_3401</code>. Disable the nRF52 system watchdog before the chain:</p> <pre><code>set system.watchdog off\n</code></pre> <p>The hardware watchdog cannot stop immediately. The RAK will reset once within about 60 seconds. Reconnect, wait at least 90 seconds from the command, and require <code>get system.watchdog</code> to report <code>&gt; off</code> before continuing.</p> <p>For a direct bench link, apply these temporary transfer guardrails to the RAK after every bridge reboot:</p> <pre><code>set powersaving off\nset radio.rxps off\nset rxdelay 0\nota config hops 0\ntempradio 909.950,500,5,5,120\n</code></pre> <p>Where local duty-cycle rules permit it, <code>set af 0</code> can also remove the legacy firmware's saved airtime wait during this bounded maintenance window. Record <code>get af</code> first and restore that exact value after the final step. Current firmware grants the bounded TempRadio transfer budget without overwriting the saved airtime factor.</p> <p><code>set powersaving off</code> is an isolation guardrail, not the fix for the observed failure. The actual source failure was an oversized USB CDC reply; current firmware splits those reads. Some historical bridge builds may report RXPS as unsupported while already operating continuously. Verify the reported state and do not substitute a normal reboot for the one-time watchdog reset. Direct tests use <code>hops 0</code>: <code>hops 1</code> makes the target echo each source response despite there being no intermediate relay, increasing half-duplex loss and legacy three-second retries.</p> <p>The exact candidate cannot use fast RXPS throughout because its historical bridge applications predate the v1.17.1.5 adaptive-preamble contract. Keep RXPS off for all ten steps whether using SF5/BW250 or the faster direct-bench SF5/BW500 tuple. After the final endpoint is proven, a later update whose target, controller, source, and relays are all v1.17.1.5 or newer can use the generic LoRa OTA runner and its qualified adaptive-preamble boundaries.</p> <p>Put the source on the identical TempRadio tuple. A current ASCII-first Full Companion recognizes <code>motatool</code>'s initial <code>ota folder on</code> line directly:</p> <pre><code>motatool serve \\\n  --dir ./motas \\\n  --serial /dev/ttyACM1 \\\n  --baud 115200 \\\n  -v\n</code></pre> <p>The same command also works with older Full Companion firmware in binary mode, where the idle parser recognizes the identical preamble. Restart <code>motatool</code> for every step so the source emits a fresh catalog advert. Leave it running during the download and stop it with Ctrl-C only after the destination reports <code>ready to install</code>.</p>"},{"location":"rak3401_mota_chain/#3-install-all-ten-packages-in-order","title":"3. Install all ten packages in order","text":"Step Manifest ID Before hash Expected version After hash 1 <code>C147BCEF</code> <code>71F4026CBE4B8B74</code> <code>1.16.7.9</code> <code>42BC53A64288E845</code> 2 <code>BEB578FC</code> <code>42BC53A64288E845</code> <code>1.16.7.10</code> <code>1AD2AA8B6C478DA6</code> 3 <code>6D8EF814</code> <code>1AD2AA8B6C478DA6</code> <code>1.16.8.7</code> <code>D709A25308BC1831</code> 4 <code>40AC4CEB</code> <code>D709A25308BC1831</code> <code>1.16.9.105</code> <code>457BEDA5E6406C81</code> 5 <code>F6C8890B</code> <code>457BEDA5E6406C81</code> <code>1.16.9.110</code> <code>E76BFA205634CAB8</code> 6 <code>82405E89</code> <code>E76BFA205634CAB8</code> <code>1.16.9.113</code> <code>65328FC8A1FBED2D</code> 7 <code>80F40DB6</code> <code>65328FC8A1FBED2D</code> <code>1.16.9.117</code> <code>AF7532E13337FADD</code> 8 <code>DBF6310D</code> <code>AF7532E13337FADD</code> <code>1.16.10.0</code> <code>22002359BBDFA76E</code> 9 <code>C2979E08</code> <code>22002359BBDFA76E</code> <code>1.17.1.3</code> <code>FE65A6135A1E7B3F</code> 10 <code>B5011420</code> <code>FE65A6135A1E7B3F</code> <code>1.17.1.5</code> <code>1FA6AAA3C28D8BD8</code> <p>For each row, first prove that <code>ota self</code> exactly matches its Before hash, then inspect the manager before changing it:</p> <pre><code>ota status\n</code></pre> <p>Proceed to discovery only after that status is reconciled. When the manager is idle, run:</p> <pre><code>ota ls\nota pull MANIFEST_ID flash\nota status\n</code></pre> <p>If the first status reports this row's MID as partial, use <code>ota pull</code> with that same MID to resume it. If this row's MID is already ready, do not pull or cancel it; continue with the install checks below. If status reports the immediately previous row's MID as <code>verifying staged blocks</code>, wait through the bounded discovery window; require either that exact MID to become <code>ready to install</code> or the manager to become <code>no download</code>, and re-prove the current Before hash. Cancel only the same previous MID while it is visibly attached and ready. If it has become idle, send no cancel. Stop on any other MID, failed or incomplete state, ambiguous reply, or timeout. Never issue a blind <code>ota cancel</code>: it can discard a resumable or unrelated session.</p> <p>Repeat <code>ota status</code> at a restrained interval until it says <code>ready to install</code>. If the manifest is initially absent, wait for a fresh source advert, run <code>ota ls</code> again, or restart <code>motatool</code>; do not pull a different ID. Stop the seeder and install:</p> <pre><code>get system.watchdog\nota install\n</code></pre> <p>The watchdog reply must still be <code>&gt; off</code>. Allow the current default five-minute readiness window for the USB/LoRa identity to return; automation probes every 10 seconds and returns early as soon as the exact body is visible. Then run <code>ver</code>, <code>ota self</code>, and <code>ota help</code>. Require the row's exact After hash, require <code>bootloader: apply OK</code>, and require <code>rescue install &lt;hash16&gt;</code> in the help before exposing that bridge to the next package. This rescue-help gate applies to steps 1-9; step 10 is the endpoint and is not exposed to another package in this chain. A normal-radio <code>ota status</code> response of <code>no download</code> proves only that the manager is idle; legacy internal-flash firmware does not durably erase a retained container by accepting an IDLE <code>ota cancel</code>. Do not claim otherwise. When the same expected manifest reports <code>verifying staged blocks</code> after the next TempRadio starts, wait only for the bounded discovery window and require that it become <code>ready to install</code> or <code>no download</code>; stop on a changed ID, failed/incomplete state, or timeout. Prove the exact running body before cancelling an attached completed session. OTAFIX consumes the approval word during a successful install, so a retained endpoint container is inert and a later valid pull replaces it. Reapply the transfer guardrails and TempRadio tuple, restart <code>motatool</code>, and continue with the next row.</p> <p>If the board boots but <code>ota self</code> says the EndF is invalid, stop. Only when <code>ota status</code> still identifies that row's complete staged package may the guarded <code>ota rescue install BEFORE_HASH</code> command be used. It is not a force option and must use that row's exact Before hash. If the board does not boot, recover the documented start/recovery UF2 locally over USB. Step 10 is the endpoint and has no successor package in this chain. If its EndF is invalid, use local DFU/SWD rather than attempting an unqualified LoRa package.</p>"},{"location":"rak3401_mota_chain/#4-intermediate-relays-and-restoration","title":"4. Intermediate relays and restoration","text":"<p>On every managed intermediate relay, save <code>get rxdelay</code> and <code>get txdelay</code>, then use the airtime-scaled collision window during the maintenance session:</p> <pre><code>set rxdelay 0\nset txdelay 0.3\n</code></pre> <p>Current OTA transfer packets honor that configured relay <code>txdelay</code>; setting <code>0.3</code> gives competing relays a small randomized, airtime-scaled forwarding window. The source's manifest-fragment gap independently follows active packet airtime and duty spacing, clamped to 100-1000 ms. These two delays solve different problems.</p> <p>After step 10 is proven, restore each saved destination and relay value exactly, including <code>rxdelay</code>, RXPS, CPU power saving, <code>af</code>, <code>ota config hops</code>, and relay timing. Current full-parser repeater firmware accepts <code>normalradio</code> and restores the saved tuple after replying on the temporary channel:</p> <pre><code>normalradio\n</code></pre> <p>The <code>b40d2e6c</code> endpoint supports that command. If a recovery build unexpectedly replies <code>Unknown command</code>, shorten its lease to one minute with the same tuple:</p> <pre><code>tempradio 909.950,500,5,5,1\n</code></pre> <p>Wait for the lease to expire, return the controller and ordinary source to their saved normal channels, and then re-enable the RAK system watchdog:</p> <pre><code>set system.watchdog on\nget system.watchdog\n</code></pre> <p>A Full Companion source is the exception: its local TCP console supports <code>normalradio</code> and the automated runner uses it before restoring the shared Binary API radio tuple.</p> <p>Final lab success requires version <code>v1.17.1.5-halo-keymind-cascade-dev-b40d2e6c</code>, body hash <code>1FA6AAA3C28D8BD8</code>, target <code>2FA509C1</code>, hardware <code>RAK_3401</code>, and <code>get system.watchdog</code> reporting <code>&gt; on</code>. If a relay cannot be restored before its TempRadio lease ends, wait for it to return to the normal channel and restore its saved <code>rxdelay</code> and <code>txdelay</code> there.</p>"},{"location":"rak3401_mota_chain/#two-relay-deployment","title":"Two-relay deployment","text":"<p>The first nine direct package transitions above were physically observed as the byte-identical first nine transitions of the legacy chain. Replacement step 10, this hardened host-runner revision, and multi-hop operation are not cleanly end-to-end physically qualified. A controlled, recoverable multi-hop lab can exercise two intermediate relays by listing them farthest-to-nearest and using three OTA hops. Run a non-mutating preflight first; even preflight requires the prerelease candidate override because the command connects to live devices:</p> <pre><code>python3 tools/lora_ota/rak3401_mota_chain.py \\\n  --bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.1.5-b40d2e6c.zip \\\n  --work-dir ./rak3401-mota-chain-work \\\n  --controller-serial /dev/ttyACM0 \\\n  --source-tcp SOURCE_IP:5001 \\\n  --source-cli-tcp SOURCE_IP:5002 \\\n  --source-shares-controller \\\n  --target-key 63d8df63 \\\n  --relay 'Far Repeater' \\\n  --relay 'Near Repeater' \\\n  --temp-radio 909.950,250,5,5,120 \\\n  --ota-hops 3 \\\n  --motatool /path/to/motatool \\\n  --accept-test-candidate \\\n  --preflight-only\n</code></pre> <p>After preflight succeeds, rerun with <code>--yes</code> in place of <code>--preflight-only</code>. Confirm that the selected frequency and bandwidth are legal at the deployment location.</p>"},{"location":"rak3401_mota_chain/#rescue-and-completion","title":"Rescue and completion","text":"<p>The guarded <code>ota rescue install &lt;base_body_hash&gt;</code> command is present after step 1 and remains available through the step-9 bridge. It is not a force command: it refuses a valid normal EndF, a base mismatch, wrong target/hardware, or invalid payload. A failure before step 1 completes still requires local USB recovery because the deployed start image predates the rescue command. The final <code>b40d2e6c</code> endpoint uses the stricter shared-slot profile; its invalid-EndF recovery is local DFU/SWD, not the rescue command.</p> <p>Before the first mutation, the runner saves the destination's RXPS periods, CPU power-saving state, RX flood delay, airtime factor, and OTA hop reach in the persistent work directory, flushing both the file and its directory entry before changing a guardrail. It also saves the managed source's exact RXPS preference in the chain-root <code>source-rxps-settings.json</code> before disabling it. Every step reuses that protected record, so a rerun after a killed host process restores the chain-start preference instead of treating the temporary off state as original. The record is accepted only for the same CLI endpoint. The runner retires that chain-root record only after it has proved the source is back on its normal radio and restored the exact preference at the verified endpoint. The runner reads the destination, controller, source, and relay versions before applying the same RXPS policy as the generic runner. The mixed historical chain therefore verifies <code>radio.rxps off</code> after every bridge reboot; a future all-v1.17.1.5-or-newer SF5/BW250 chain would instead keep RXPS on under the qualified level-8/preamble-64 boundary. It also verifies <code>set powersaving off</code> and <code>rxdelay 0</code>, plus <code>af 0</code> when <code>--legacy-full-airtime</code> was explicitly selected. It restores every original value only after the exact endpoint is proven. An interrupted run deliberately leaves those transfer guardrails active; rerun the same command with the same work directory to resume and restore them. CPU power saving was not the cause of the observed folder-source failure: that was a USB CDC receive-ring overrun fixed by bounded serial reads. The runtime settings remain conservative isolation and fast-link reliability guardrails.</p> <p>For every named <code>--relay</code>, the per-step runner also captures <code>rxdelay</code> and <code>txdelay</code>, writes them to <code>relay-timing-settings.json</code>, applies <code>rxdelay 0</code> and <code>txdelay 0.3</code> during transfer, verifies the readback, and restores both before the relay leaves TempRadio.</p> <p>The runner also keeps the watchdog off across the chain, rechecks identity and OTA reach before every package, requires the exact post-boot EndF hash, and only re-enables the watchdog after step 10. Lab success requires endpoint body hash <code>1FA6AAA3C28D8BD8</code>, target <code>2FA509C1</code>, hardware <code>RAK_3401</code>, normal radio <code>910.525 MHz / 62.5 kHz / SF7 / CR5</code>, and the watchdog verified on.</p>"},{"location":"rak3401_mota_chain/#external-radio-startup-and-manual-usb-recovery","title":"External-radio startup and manual USB recovery","text":"<p>RAK3401 is a distinct target from RAK4631. Its RAK13300/RAK13302 radio is on the WisBlock SPI bus (<code>SPI1</code> in the Adafruit nRF52 core), with BUSY and DIO1 on P0.09/P0.10. Current builds explicitly enable those NFC-capable pads as GPIO and do not advertise the radio bus as an on-board QSPI flash device.</p> <p>The RAK13302's FEM and boost supply use switched <code>3V3_S</code>, but the SX1262 core uses unswitched 3V3. An MCU reset, a 1200-baud DFU touch, or disconnecting only USB may therefore leave a battery-powered SX1262 in its previous state. At startup, current firmware quiesces the FEM, reinitializes the dedicated SPI instance, asserts NRESET, and, if BUSY remains high, sends the Semtech NSS/GET_STATUS wake sequence without waiting on RadioLib first. The one-time board startup cold-starts <code>3V3_S</code>; later radio retries leave that shared rail enabled so they do not reset GPS or sensor modules.</p> <p>If BUSY still cannot be released, firmware must not enter a reset loop:</p> <ul> <li>Companion starts its USB/BLE management services after three bounded probes,   uses nRF52 hardware entropy if it needs a first-boot identity, and retries the   radio every 60 seconds. Radio statistics remain zero until recovery.</li> <li>Repeater keeps the same USB CDC session open and prints   <code>Radio unavailable; retrying in 60 seconds</code>. It repeats the board-level probe   in place. The normal repeater CLI and mesh transport cannot start until the   radio responds.</li> </ul> <p>A permanently high BUSY after NRESET and the direct wake transaction indicates an electrically unavailable radio, loose module, or power-domain fault; an MCU reboot cannot manufacture a response. If local access is possible, disconnect the battery as well as USB and reseat the WisBlock module. Remote firmware will continue retrying without requiring that physical intervention or churning the USB device.</p> <p>For an existing deployed tower using Preview 5, do not change the bootloader as part of this application chain. Its exact local recovery package is the Preview 5 RAK4631 ZIP. For a new RAK3401 installation or local recovery, use the OTAFIX 2.4.3 RAK3401 ZIP from the OTAFIX 2.4.3 release. These are local DFU/SWD recovery assets, not mOTA chain steps.</p> <p>For a local Serial DFU recovery with the repository helper:</p> <pre><code>cd /path/to/meshfirmware\nMCFIRMWARE_NO_SUDO=1 ./mcfirmware.sh\n</code></pre> <p>Select the serial entry whose USB identity is <code>WisCore RAK3401 Board</code>, then choose Custom, nrf52, and the exact RAK3401 <code>.zip</code>. Use flash-update to preserve InternalFS preferences and identity. Use flash-wipe + flash only when erasing application data is intentional. The helper follows the same USB device into bootloader mode, so do not substitute another <code>/dev/ttyACM*</code> merely because its number appears first.</p>"},{"location":"role_feature_switches/","title":"Feature switches by role \u2014 1.17.1.5 USA Cascade","text":"<p>Use these settings with the exact board's canonical release image. Former logging, power-saving, FEM-gain, and rotated-display variants are now runtime choices where the hardware supports them. A setting cannot add missing radio hardware, MQTT code, storage, or an OTA partition. Check the download's <code>.capabilities.json</code> and the firmware picker. For exact old device/variant names, search the 1.17.1.5 variant map: it maps all 1,361 previous release entries to 1,325 covered choices or 36 excluded entries. Many old choices share one current image; the command tables below explain how to select their former behavior. Excluded entries have no download.</p> <p>Search terms are alternative wording for finding these instructions, not CLI aliases. Use the commands in the role-specific tables and examples.</p>"},{"location":"role_feature_switches/#open-the-usb-web-console","title":"Open the USB web console","text":"<p>Search terms: USB terminal, serial console, ASCII terminal, browser terminal, web serial.</p> <p>Open the MeshCore USB web console in Chrome or Edge, connect a data-capable USB cable, close other applications using that port, and select the device. Use 115200 baud when prompted. Full Companion, Repeater, Room Server, and Sensor start with an ASCII USB terminal. Run <code>board</code>, then <code>ver</code> on any role.</p> <p>If a Companion app has already switched USB to its binary protocol, send:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>To hand the port back to a Companion app or USB MOTA host, send <code>+++MESHCORE-TERM-STOP</code>, close the console, and connect the app/tool. Dedicated USB/BLE/WiFi Companion images can start in binary mode; use the start token there too. KISS firmware uses its modem protocol and is outside this release.</p> <p>The linked console runs in your computer's browser over USB. It does not need node WiFi or <code>set webui on</code>. WebConfig is a separate settings website served by supported ESP32 images. Both infrastructure and WiFi Companion WebConfig include a browser command terminal (<code>set wifi.cli on</code>), enabled by default on the LAN. The Companion browser CLI uses the same terminal commands as USB, including contact import, chat, recipient selection, and streaming replies. Full ESP32 Companion also exposes this terminal at TCP port 5002. See the terminal command guide.</p>"},{"location":"role_feature_switches/#which-old-variant-setting-should-i-use","title":"Which old variant setting should I use?","text":"<p>Search terms: old firmware variants, restore features, turn features on or off, enable MQTT, disable MQTT.</p> <p>These controls apply to every board with the corresponding compiled feature; check the hardware requirements below.</p> Former choice Current image / runtime control USB logging or Station G2/G3 logging variant Same role's canonical image; <code>set usb.logging on</code> / <code>off</code> USB logging, WiFi MQTT, or both MQTT-capable image with USB logging; <code>set logging.output usb</code>, <code>wifi</code>, <code>both</code>, or <code>off</code> Companion WiFi-MQTT variant <code>set mqtt.enabled on</code> / <code>off</code>; configure broker slots through the CLI or WebConfig <code>_ps</code> power-saving variant <code>set powersaving on</code> / <code>off</code>; check <code>get powersaving</code> on every role <code>_femoff</code> / FEM-gain variant <code>set radio.fem.rxgain on</code> / <code>off</code>; separate TX switch where controllable RX boost variant <code>set radio.rxgain on</code> / <code>off</code> on a supported radio iKOKA rotated-display variant Full Companion: <code>set display.rotation 180</code>; <code>0</code> restores the board default Separate USB, BLE, WiFi, Ethernet, or Terminal Chat Companion Exact board's Full Companion where listed; supported transports are included, with SenseCAP selection below RS232 repeater variant consolidated into the ordinary repeater <code>set bridge.enabled on</code> / <code>off</code> on a build containing the RS232 bridge ESP-NOW bridge or primary ESP-NOW radio Select the matching hardware/role image first; bridge and primary-radio channel commands differ LoRa OTA / external-storage variant Still choose the exact receiver/storage image and matching bootloader; this is not a software on/off switch <p>Companion, Repeater, Room Server, and Sensor use the same command names for shared settings. Use <code>get &lt;setting&gt;</code> to check and <code>set &lt;setting&gt; &lt;value&gt;</code> to change them. A command requires its feature to be compiled into the build. <code>set usb.logging on|off</code> changes only USB logging. On MQTT-capable builds, <code>set mqtt.enabled on|off</code> changes only MQTT and keeps broker settings; <code>set logging.output off|usb|wifi|both</code> selects both outputs together.</p>"},{"location":"role_feature_switches/#full-companion-commands","title":"Full Companion commands","text":"Setting Enable / select Disable / restore Read back Device power saving <code>set powersaving on</code> <code>set powersaving off</code> <code>get powersaving</code> LoRa RX power saving <code>set radio.rxps on</code> <code>set radio.rxps off</code> <code>get radio.rxps</code> Radio RX boost <code>set radio.rxgain on</code> <code>set radio.rxgain off</code> <code>get radio.rxgain</code> External FEM RX gain <code>set radio.fem.rxgain on</code> <code>set radio.fem.rxgain off</code> <code>get radio.fem.rxgain</code> External FEM TX gain <code>set radio.fem.txgain on</code> <code>set radio.fem.txgain off</code> <code>get radio.fem.txgain</code> ESP32 USB logging <code>set powersaving off</code>, then <code>set usb.logging on</code> <code>set usb.logging off</code> <code>get powersaving</code>, <code>get usb.logging</code> nRF52 second USB logging port <code>set usb.logging on reboot</code> <code>set usb.logging off reboot</code> <code>get usb.logging</code> MQTT master <code>set mqtt.enabled on</code> <code>set mqtt.enabled off</code> <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, <code>get mqtt.status</code> ESP32 persistent WebConfig <code>set webui on</code> <code>set webui off</code> <code>get webui</code> ESP32 WebConfig browser console <code>set wifi.cli on</code> <code>set wifi.cli off</code> <code>get wifi.cli</code> ESP32 temporary setup AP <code>start webconfig ap</code> <code>stop webconfig</code> <code>get webui</code> Display rotation <code>set display.rotation 90</code>, <code>180</code>, or <code>270</code> <code>set display.rotation 0</code> <code>get display.rotation</code> Temporary MOTA radio window <code>tempradio 910.525,250,5,5,120</code> <code>normalradio</code> <code>tempradio</code> <p>Saved settings apply immediately unless noted. Rotation and gain controls report unsupported hardware instead of creating that feature. Fresh Full Companion preferences enable device power saving and leave USB logging off; existing saved preferences win after an update.</p> <p>ESP32: logging and binary Companion traffic share one USB port. Turn logging off before handing USB to an app/MOTA host. nRF52: the optional second CDC port is for logs; use the primary port for Companion/MOTA. Adding/removing the second port requires a reboot; the optional suffix shown above requests it.</p>"},{"location":"role_feature_switches/#mqtt-controls-shared-by-companion-and-infrastructure","title":"MQTT controls shared by Companion and infrastructure","text":"<p>Search terms: Companion MQTT settings, MQTT on, MQTT off, broker configuration.</p> <p>Configure a broker through the MQTT tab or with the same commands on either role. For example:</p> <pre><code>set mqtt.iata SEA\nset mqtt1.preset custom\nset mqtt1.server broker.example.com\nset mqtt1.port 1883\nset mqtt.enabled on\nget mqtt.enabled\nget mqtt.running\nget mqtt.status\n</code></pre> <p><code>set mqtt.enabled off</code> disconnects brokers while preserving their settings. <code>set mqtt.enabled on</code> allows configured brokers to reconnect. An enabled switch is separate from a running connection: check <code>get mqtt.running</code> and <code>get mqtt.status</code>. The MQTT tab's Enable MQTT checkbox controls this same saved switch. Slot credentials and presets are available through <code>get/set mqtt1.*</code>, <code>mqtt2.*</code>, and the remaining supported slots; secrets stay masked in the browser. WiFi Companion accepts these commands through its USB terminal and browser CLI; Full Companion also accepts TCP port 5002.</p> <p><code>set mqtt1.preset none</code> disables just that slot. Publication controls such as <code>set mqtt.status off</code> do not disconnect brokers. USB logging is independent. Images without MQTT code do not show MQTT cards or accept MQTT controls.</p>"},{"location":"role_feature_switches/#companion-wifi-bluetooth-gps-and-board-exceptions","title":"Companion WiFi, Bluetooth, GPS, and board exceptions","text":"<p>Configure ESP32 WiFi with:</p> <pre><code>set wifi.ssid MyNetwork\nset wifi.pwd my-password\nget wifi.status\n</code></pre> <p><code>set wifi.powersave min</code> enables WiFi modem sleep; <code>none</code> disables it. <code>max</code> is accepted only where the BLE/WiFi coexistence policy allows it. Read back with <code>get wifi.powersave</code>. This is separate from device power saving and RXPS. The assigned WiFi button/display switch controls WiFi services on supported boards. <code>stop webconfig</code> closes only the portal; it is not a WiFi master switch. There is no universal Bluetooth-off or Ethernet-off text command.</p> <p>SenseCAP Indicator Full only: <code>set companion.transport wifi</code> followed by <code>reboot</code> selects WiFi; <code>set companion.transport ble</code> followed by <code>reboot</code> selects Bluetooth. Check <code>get companion.transport</code>. USB remains available. Primary ESP-NOW Indicator images keep their mesh radio in either selection.</p> <p>GPS-equipped builds: use <code>get gps</code>, <code>set gps on</code>, and <code>set gps off</code> on Companion and infrastructure. The Companion app's <code>gps=1</code> / <code>gps=0</code> custom setting controls the same GPS. See GPS tracking for location-sharing settings.</p>"},{"location":"role_feature_switches/#repeater-room-server-and-sensor-commands","title":"Repeater, Room Server, and Sensor commands","text":"<p>These roles use CommonCLI. Feature-dependent commands require the relevant hardware/build; MQTT is present in observer builds, and WebConfig is absent from some portable builds. The USB browser console still works without it.</p> Setting Enable Disable Read back Live USB logging ESP32 1.17.1.5: <code>set powersaving off</code>, then <code>set usb.logging on</code>; other platforms: <code>set usb.logging on</code> <code>set usb.logging off</code> <code>get powersaving</code>, <code>get usb.logging</code> Capture RX log to node storage <code>log start</code> <code>log stop</code> <code>log</code> prints the capture locally RS232 / ESP-NOW bridge master <code>set bridge.enabled on</code> <code>set bridge.enabled off</code> <code>get bridge.enabled</code>, <code>get bridge.running</code>, <code>get bridge.type</code> MQTT periodic status publication <code>set mqtt.status on</code> <code>set mqtt.status off</code> <code>get mqtt.status</code> shows connection status MQTT packet publication <code>set mqtt.packets on</code> <code>set mqtt.packets off</code> <code>get mqtt.packets</code> SNMP on supported MQTT infrastructure <code>set snmp on</code>, then <code>reboot</code> <code>set snmp off</code>, then <code>reboot</code> <code>get snmp</code> MQTT raw packet publication <code>set mqtt.raw on</code> <code>set mqtt.raw off</code> <code>get mqtt.raw</code> MQTT receive capture <code>set mqtt.rx on</code> <code>set mqtt.rx off</code> <code>get mqtt.rx</code> MQTT transmit capture <code>set mqtt.tx on</code> (or <code>advert</code>) <code>set mqtt.tx off</code> <code>get mqtt.tx</code> MQTT master <code>set mqtt.enabled on</code> <code>set mqtt.enabled off</code> <code>get mqtt.enabled</code>, <code>get mqtt.running</code>, <code>get mqtt.status</code> ESP32 persistent WebConfig <code>set webui on</code> <code>set webui off</code> <code>get webui</code> WebConfig browser command terminal <code>set wifi.cli on</code> <code>set wifi.cli off</code> <code>get wifi.cli</code> LoRa RX power saving <code>set radio.rxps on</code> <code>set radio.rxps off</code> <code>get radio.rxps</code> Radio RX boost <code>set radio.rxgain on</code> <code>set radio.rxgain off</code> <code>get radio.rxgain</code> Controllable FEM RX / TX gain <code>set radio.fem.rxgain on</code> / <code>set radio.fem.txgain on</code> <code>set radio.fem.rxgain off</code> / <code>set radio.fem.txgain off</code> Corresponding <code>get radio.fem.rxgain</code> / <code>get radio.fem.txgain</code> GPS, when compiled <code>set gps on</code> <code>set gps off</code> <code>get gps</code> <p>Use <code>set usb.logging on|off</code> on every role. Adding the optional <code>reboot</code> suffix requests a reboot only when changing the USB interfaces requires it, as on nRF52 Full Companion. <code>log start/stop</code> records to storage independently of live USB logging. Use <code>log erase</code> to delete that capture.</p> <p>For ESP32 1.17.1.5 USB logging, run these as separate commands in the role's text terminal (or remote admin CLI on infrastructure):</p> <pre><code>set powersaving off\nset usb.logging on\nget powersaving\nget usb.logging\n</code></pre> <p>Check for power saving <code>off</code> and USB logging <code>on</code>. This avoids the released ESP32 USB sleep bug, including the G3 report. Both settings are saved; turning logging off later does not automatically restore power saving. LoRa RXPS is independent. nRF52 logging does not need this ESP32 workaround.</p> <p>With the G3 sleep correction, enabled live USB logging keeps ESP32 USB serviced and blocks light sleep, including when a host closes the port or disconnects. CPU idle/yield remains available. <code>set usb.logging off</code> removes that blocker; an attached native USB host still prevents sleep. On Full infrastructure, <code>set logging.output usb</code> and <code>both</code> enable the same USB blocker; <code>wifi</code> and <code>off</code> remove it. File capture with <code>log start</code> is independent. The original 1.17.1.5 binaries require the <code>set powersaving off</code> workaround described in the release note.</p>"},{"location":"role_feature_switches/#shared-mqtt-and-logging-output","title":"Shared MQTT and logging output","text":"<p>Search terms: MQTT settings, MQTT on, MQTT off, logging output, USB and WiFi logging.</p> <p>On any Companion or infrastructure build with both MQTT and USB logging compiled:</p> Command USB logs MQTT bridge <code>set logging.output off</code> Off Off <code>set powersaving off</code>, then <code>set logging.output usb</code> On Off <code>set logging.output wifi</code> Off On <code>set powersaving off</code>, then <code>set logging.output both</code> On On <p><code>get logging.output</code> reports the selection. Fresh unified Full infrastructure preferences select <code>both</code>; Full Companion starts with USB logging off. Saved settings override these defaults. To toggle only MQTT while keeping USB logging unchanged, use <code>set mqtt.enabled off</code> / <code>on</code>. Neither setting turns LoRa repeating off. Repeater forwarding uses <code>set repeat off</code> / <code>on</code> and <code>get repeat</code> separately.</p> <p>The <code>set powersaving off</code> step above is the 1.17.1.5 ESP32 USB workaround. WiFi/MQTT-only logging does not need it while the Repeater/Room Server MQTT bridge is running: that sleep guard already exists in the released firmware. Use <code>get mqtt.running</code> to check that MQTT is running; an enabled preference alone is not the running state. <code>set logging.output wifi</code> keeps USB logging off and uses that MQTT guard.</p> <p>For a custom broker on an MQTT-capable Companion, Repeater, or Room Server:</p> <pre><code>set wifi.ssid MyNetwork\nset wifi.pwd my-password\nset mqtt.iata SEA\nset mqtt1.preset custom\nset mqtt1.server broker.example.com\nset mqtt1.port 1883\nset mqtt.enabled on\nget mqtt.status\n</code></pre> <p>Set <code>mqtt1.username</code> / <code>mqtt1.password</code> if required by that broker. Configure only as many slots as the board supports. <code>set mqtt1.preset none</code> disables slot 1; other configured slots remain enabled, within the build's supported slot count. Disabled and partially configured slots remain saved across reboot. For a custom server URL, <code>set mqtt1.port 0</code> clears the port override so the URI supplies it. <code>set mqtt.status off</code> disables status messages, not MQTT itself. See the MQTT reference for presets, TLS, credentials, and slot limits.</p>"},{"location":"role_feature_switches/#infrastructure-power-saving-and-bridges","title":"Infrastructure power saving and bridges","text":"<p>Use <code>get powersaving</code>, <code>set powersaving on</code>, and <code>set powersaving off</code> on every role. The preference is saved. Hardware and active USB/network services decide when sleeping is possible; the command names do not change between roles. Device power saving is separate from WiFi modem sleep and LoRa RXPS.</p> <p>On RS232-capable repeater images, stop the bridge before changing its serial port or baud rate, then restart it:</p> <pre><code>set bridge.enabled off\nset bridge.baud 115200\nset bridge.enabled on\n</code></pre> <p>RAK4631: <code>set bridge.uart 2</code> selects UART2 while the bridge is stopped. Canonical GPS-enabled builds reserve UART1 for GPS; UART1 requires a dedicated GPS-free image. ESP-NOW bridge: use <code>set bridge.channel &lt;1..13&gt;</code> and <code>set bridge.format wrapped</code> / <code>raw</code> where supported. Primary ESP-NOW mesh: use <code>set espnow.channel &lt;1..13&gt;</code> and reboot; this is a different radio setting.</p> <p>For infrastructure WebConfig on the LAN, use <code>start webconfig</code> / <code>stop webconfig</code>. To force a setup AP on an observer, first run <code>set mqtt.enabled off</code>, then <code>start webconfig ap</code>. When finished, run <code>stop webconfig</code> and restore <code>set mqtt.enabled on</code> if you did not reboot.</p>"},{"location":"role_feature_switches/#updating-and-sending-mota","title":"Updating and sending MOTA","text":"<p>Search terms: mOTA, LoRa OTA, update over LoRa, wireless firmware transfer.</p> <p>All released Full Companions can serve MOTA to other nodes. Close the console and run <code>motatool serve --serial /dev/ttyACM0 --dir ./motas -v</code> on the USB host. See Full Companion instructions for WiFi/BLE source commands and the bounded temporary radio setup.</p> Role / hardware Start self-update Stop / requirement ESP32 Repeater, Room Server, Sensor with WiFi updater <code>start ota</code> or <code>start ota ap</code>; open the returned URL (normally port 80, <code>/update</code>) <code>stop ota</code>; close WebConfig first if it shares port 80 ESP32 Full Companion with two application slots <code>start ota</code> or <code>start ota ap</code>; returned URL uses port 8080, <code>/update</code> <code>stop ota</code>; single-slot Full builds use USB nRF52 infrastructure with Bluetooth DFU <code>start ota</code> enters the Bluetooth update flow Matching application DFU ZIP and board bootloader required Qualified LoRa OTA receiver Follow LoRa OTA directions Exact destination package, storage profile, and overlapping temporary radio windows <p>For nRF52 OTAFIX installations use the exact board/storage build from OTAFIX 2.4.6. Its retained-RAM handoff is required by the new internal-flash hybrid receiver images. Full Companions are sources and remain normally USB-updated.</p> <p>The complete infrastructure CLI, role/build matrix, and Full Companion feature guide provide details.</p>"},{"location":"s3_memory_soak_validation/","title":"ESP32-S3 OTA memory experiment","text":"<p>This experiment compares the current static S3 OTA workspace (A) with <code>OTA_HEAP_CONTEXT=1</code> (B), with WiFi and a real TLS MQTT connection enabled. It is isolated on <code>experiment/s3-ota-memory-soak</code>; published recipes retain their existing defaults. A short stress test cannot establish months of uptime.</p>"},{"location":"s3_memory_soak_validation/#hardware-and-scope","title":"Hardware and scope","text":"Board Role Flash PSRAM Lab identity Heltec V4.3 OLED, standard V4 Observer/MQTT repeater 16 MiB 2 MiB QSPI USB MAC <code>44:1B:F6:69:CF:98</code> Original SenseCAP Indicator LoRa Full companion plus experimental MQTT 8 MiB 8 MiB octal WiFi MAC <code>D8:3B:DA:75:23:AC</code> Seeed XIAO ESP32-S3 with WIO LoRa Observer/MQTT repeater 8 MiB 8 MiB octal MAC <code>28:84:85:B4:09:80</code>, Windows COM31 <p>This is not an R8 test. Both Indicator variants use the same 320x320 canvas; the native 480x480 Full-plus-MQTT configuration is not qualified by this run. One custom TLS MQTT slot per board publishes only to the isolated Pi broker. These results do not qualify five concurrent slots, JWT renewal, heavy RF traffic, every OTA receive/apply path, or months of operation.</p>"},{"location":"s3_memory_soak_validation/#reproducible-builds","title":"Reproducible builds","text":"<p>Base commit: <code>bc0fb2c335938c97220de51098cea6162f2f0fe0</code>, following PR #7's merge. Copy <code>tools/hil/s3_memory_soak.ini</code> to ignored <code>platformio.local.ini</code> and build the six named environments sequentially, with <code>MESHCORE_ESP32_FULL_BUILD=1</code>. Never run multiple PlatformIO processes in this checkout. Archive each image, ELF, map, partitions, bootloader, and memory report before the next build.</p> <p>The private broker's public CA must be in <code>ssl_certs</code> while generating these experimental images. Remove it and <code>platformio.local.ini</code> afterward. Private keys stay on the Pi. WiFi credentials and the Windows logger token are in private local files; do not commit them or the generated certificate bundle. Broker certificate verification remains enabled.</p> <p>The V4 and XIAO lab recipes also enable <code>MESH_SOAK_WIFI_KEY_OVERRIDE</code> and require the ignored local header <code>tools/hil/S3SoakWiFiKey.h</code>. To reproduce diagnostics using ordinary WiFi credentials, remove that define from the lab recipe; the private header is then unnecessary. Published recipes do not enable either lab flag.</p> Image Application bytes Link-time available internal bytes SHA-256 V4 A 1,910,392 237,360 <code>68c2749e0ea40db91d953f6355010bc602f85424526ca6acbe1cad7fd11c8630</code> V4 B 1,911,256 252,760 <code>6847ad4ad6bac2e558b8aed67de37417a497972391f13a71e0a42b5c9704dcff</code> Indicator A 2,313,256 244,248 <code>3d0ac27f95ddc54a32b59a3892d157713dcded285dbeb98d1bdfdb1ce0b951ab</code> Indicator B 2,314,136 255,496 <code>83045d7ec48befc43f3460c08c68b71da037a5476e14dd59def5706fc5a1b07e</code> XIAO A 1,845,000 238,448 <code>6fcc657c5ccbc5dd3d53a0cf1ceebde54479d59d329f8625e7cb7141a27d9ed8</code> XIAO B 1,845,912 253,864 <code>2b233e42e0c515b152ce83ca8fe38b1f35780970bb6350dbadf2591b6a2699a1</code> <p>All six firmware builds passed their RAM/flash gates. The linked internal capacity gain is 15,400 bytes on V4, 11,248 bytes on Indicator, and 15,416 bytes on XIAO. This is capacity returned while idle, not a reduction in peak OTA allocation needs. Both A/B variants keep the existing MQTT client reuse policy and internal MQTT task stack; this experiment does not move that stack into PSRAM.</p>"},{"location":"s3_memory_soak_validation/#instrumentation","title":"Instrumentation","text":"<p><code>MESH_SOAK_DIAGNOSTICS</code> exposes local-only <code>get soak</code>, <code>soak ota-cycle</code>, and <code>soak wifi-drop</code> commands. They report free/largest/minimum internal heap, free PSRAM, OTA context size/presence, WiFi state, and uptime. No published recipe enables these controls.</p> <p>The lab network has a valid 64-digit raw WiFi key. Production MQTT preferences currently accept only 63 characters. The V4 experiment uses a separate, test-only NVS key through <code>MESH_SOAK_WIFI_KEY_OVERRIDE</code>, without changing the production binary preference layout. This does not fix released raw-key input. The network's original nine-character passphrase was subsequently recovered from the connected Windows profile; XIAO uses it through ordinary settings. The override is compiled into both XIAO images but no override key is stored.</p> <p>The Pi logger owns one persistent V4 USB handle: opening this particular USB device resets it, even with DTR/RTS disabled. Firmware installations and logger restarts therefore begin new uptime runs. Indicator telemetry uses TCP 5002. The logger distinguishes the 49.7-day <code>millis()</code> rollover from a reboot.</p> <p>Passive samples omit <code>get mqtt.stats</code>: its outbox query can block behind the MQTT client lock during a TLS handshake and stall the CLI. The logger reads <code>get mqtt.status</code> and separately counts messages received through a verified TLS subscription. It stores topic counts, not MQTT payloads or credentials.</p> <p>Two exploratory rapid-flap runs used an overly short 90-second recovery cutoff. The first also used the blocking outbox probe. Preserve those pilot results; do not count them as successful tests. Production MQTT backoff deliberately grows to five minutes and clears after two stable connected minutes, so rapid flapping is not equivalent to repeated independent connection tests.</p>"},{"location":"s3_memory_soak_validation/#results-and-continuing-soak","title":"Results and continuing soak","text":"<p>V4 and Indicator both passed the matched A/B workload: 200 explicit OTA context acquire/release attempts, four MQTT bridge restarts, one WiFi reconnection and one five-second private-broker outage per image. An initial bridge restart preconditions each run. No unexpected uptime resets occurred in these runs. A was paused after its four bridge restarts to investigate the display report, then resumed for the network faults; its elapsed duration includes that pause.</p> <p>After the workload, with WiFi and one TLS MQTT slot connected:</p> Board A free internal bytes B free internal bytes Gain A largest block B largest block Standard V4 95,396 111,040 15,644 (15.28 KiB) 81,908 98,292 Indicator 107,168 118,520 11,352 (11.09 KiB) 94,196 106,484 XIAO (same saved settings, cold boot) 151,028 166,444 15,416 (15.05 KiB) 139,252 147,444 <p>Free heap varies with network activity; link-time capacity is the cleaner measurement of storage moved out of static RAM. PSRAM remained about 2.01 MB on V4 and 6.33 MB on Indicator. In each B run the OTA context returned to absent after the allocation workload. Neither board's largest block shrank through those 200 allocation cycles or the reconnect workload. WiFi/MQTT recovery took about 4.3 seconds on A and 3.8 seconds on B; broker recovery took about 19.5 and 21.8 seconds respectively. These are single observed recovery times.</p> <p>Workspace recreation has an observed latency cost. The 200 command cycles took approximately 189 seconds on V4 B and 379 seconds on Indicator B, versus 32 and 15 seconds on A. This includes command transport, OTA initialization, and ordinary firmware service, so it is not an allocator microbenchmark. The static comparator already owns an initialized workspace; the dynamic variant recreates it. This experiment does not claim faster OTA startup, and this cost should be checked against real session use before a default change. Code inspection shows that <code>OtaContext::begin()</code> calls <code>ota_self_firmware()</code>, which scans the running ESP32 application for its EndF identity on each call. All six experimental images contain valid EndF trailers. Caching immutable boot identity is a candidate for a separate change, not part of these results.</p> <p>The real WiFi mOTA folder endpoint was tested separately on Indicator: 20 empty-folder sessions on A and 40 on B. All completed and B released its context. During B's first batch, free internal RAM went from 118,552 to 116,316 bytes, and its largest block from 106,484 to 102,388. A second batch ended at 116,308 bytes with the same 102,388-byte largest block. This retained allocation/layout change is not explained by the now-absent OTA context; record it separately and watch it during the soak. It did not keep growing in the second batch.</p> <p>The original A folder script also tried V4, whose observer recipe has no TCP 5001 folder source. Its overall result therefore says <code>passed: false</code>, despite Indicator completing all 20 sessions. That endpoint mismatch is preserved in the evidence; it is not an OTA failure on V4. The corrected script targets only the Indicator. These empty-folder checks do not qualify a full firmware transfer.</p> <p>XIAO passed 200 context cycles, four bridge restarts and one WiFi reconnect per image, with no unexpected reset. Its largest block stayed unchanged within each workload. WiFi/TLS recovered in about six seconds for both. This local test did not inject a separate broker outage or exercise a TCP folder endpoint. Verified subscriptions on the Pi confirmed actual TLS publications for both.</p> <p>The first XIAO A run followed initial device configuration and finished with 126,140 internal bytes free, which would have overstated the OTA saving. It is preserved as <code>xiao-live/A-configuration-stress.json</code>. Reflashing A without an erase, retaining exactly the saved settings used by B, and rerunning the whole workload produced the 151,028-byte baseline above. Its resulting gain exactly matches the 15,416-byte linked-capacity change. The earlier larger gap is not credited to OTA storage; the precise retained allocation was not isolated.</p> <p>The Pi stores evidence under <code>/home/mikec/hwtest/runs/s3-memory-soak</code>:</p> <ul> <li><code>telemetry.jsonl</code>: append-only memory, WiFi/MQTT state, uptime, transport errors.</li> <li><code>latest.json</code>: latest samples plus broker-side received-message counts.</li> <li><code>A-stress.json</code> / <code>B-stress.json</code>: matched stress results and phase boundaries.</li> <li><code>A-folder.json</code> / <code>B-folder.json</code>: real WiFi mOTA empty-folder session checks.</li> <li><code>B-repeat-folder.json</code>: the extra batch checking the initial allocation change.</li> </ul> <p><code>meshcore-memory-soak.service</code> holds the USB connection and samples each minute. <code>meshcore-soak-broker.service</code> supplies the private TLS broker. Both are enabled on the Pi. The logger never reboots a board to hide a firmware failure, but reopening the V4 USB transport can itself reset it; inspect transport counts, service restarts, and uptime together when diagnosing any interruption. The final passive phase started at <code>2026-09-11T07:18:07Z</code>. Installing the final logger revision (which serializes concurrent samples) deliberately restarted the service and therefore reset V4 once. That begins its long-soak uptime run; Indicator retained its uptime. Both then reported WiFi/TLS connected, absent OTA contexts, and actual broker-side publications.</p> <p>The local XIAO logger owns COM31 and writes under <code>C:\\git\\MeshCore\\out\\s3-memory-soak\\xiao-live</code>. Its control endpoint is loopback-only with a private token. It runs while this Windows session remains alive; it is not a Pi service and will not survive a computer shutdown. A separate verified TLS subscription on the Pi confirmed XIAO publications for both images. The Pi logger's per-device counts cover V4 and Indicator only. The final XIAO B passive phase was verified at <code>2026-09-11T07:21:21Z</code>, with 166,508 free internal bytes, a 155,636-byte largest block, WiFi/TLS connected, and no active OTA context. The largest block differs from the post-stress sample because this is a fresh boot, which illustrates why comparisons must use the same workload history. A Pi subscription received its publication two seconds later.</p> <p>Read-only checks on the Pi:</p> <pre><code>systemctl is-active meshcore-memory-soak meshcore-soak-broker\ncat /home/mikec/hwtest/runs/s3-memory-soak/latest.json\n</code></pre> <p>On Windows, read <code>out/s3-memory-soak/xiao-live/latest.json</code>. Keep the computer awake for continuous local samples. Neither logger automatically reboots a radio in response to a failed sample.</p> <p>The public lab CA was removed from <code>ssl_certs</code>, and the temporary local PIO configuration and generated test trust bundle were removed after building. Archived experimental firmware and public evidence remain in ignored <code>out/s3-memory-soak</code>; no test CA enters the published build configuration.</p> <p>No published default has changed. Leave the experimental B images running to collect longer evidence before deciding whether to expand S3 heap allocation. More idle internal RAM gives WiFi/TLS useful headroom; it does not itself prove stability or eliminate the need to allocate the OTA workspace during use.</p>"},{"location":"s3_memory_soak_validation/#physical-display-checks","title":"Physical display checks","text":"<p>The user reported unresponsive screens during MQTT restart testing. The V4 lit after temporarily choosing <code>on</code>; after restoring battery and USB profiles to <code>button</code>, 15 seconds, the user confirmed that pressing the button wakes it. The synchronous reconnect/diagnostic work may have delayed UI service, but the exact cause of the original visual report was not established.</p> <p>The T096 is a separate nRF52840 board, USB identity <code>651F8E496197F882</code>. It was reflashed with current Full firmware and briefly instrumented. The trace showed the radio, sensor and UI loop advancing; the display had initialized but was marked off. Its functional CDC0 was in Binary mode after a host-session close. Sending a newline-delimited <code>+++MESHCORE-TERM-START</code> restored ASCII control. With display mode set to <code>on</code>, the user confirmed the normal screen appeared. Temporary tracing was removed by reinstalling the non-instrumented image, and battery/USB profiles were restored to <code>button-pairing</code>, 15 seconds. The user then confirmed that its button wakes the normal screen after timeout.</p> <p>T096 recovery firmware: <code>v1.17.1-t096-check</code>, Full/shared OTA queue, <code>-Os</code> size profile, available linked internal RAM 99,892 bytes (73,728 required). ZIP SHA-256 <code>f5cfcb001efda559ae9b4e7b105ac9766a604808f5fd708b7c533f8a11c64578</code>. No device-wide filesystem erase was needed for this recovery. T096 does not count as an S3 A/B test.</p> <p>Host validation: <code>python -m unittest discover -s tools/hil -p test_s3_memory_soak.py</code>. The five checks cover diagnostic filtering, missing data, resets, and counter rollover. They are not substitutes for the hardware evidence.</p>"},{"location":"separated_radio_modulation_cache_validation/","title":"Separated radios, normal XIAO RX gain, and unchanged-modulation timing","text":"<p>Measured 2026-09-14 on <code>keymindCascade</code>, base commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> plus local changes.</p> <p>The unchanged-modulation optimization reduces XIAO frequency-only retunes from 548.880 to 451.897 us (17.7%) in a same-image control. The separated four-channel SF6 test still misses packets. Separation and disabling XIAO boosted gain were changed together; their RF effects are not isolated.</p>"},{"location":"separated_radio_modulation_cache_validation/#settings-and-controls","title":"Settings and controls","text":"<ul> <li>XIAO ESP32-S3/WIO SX1262 COM31 receiver; SenseCAP Indicator ESP32-S3 COM28   reference transmitter. The user moved the radios apart; distance and   attenuation were not measured. RAK4631 and Indicator RP2040 untouched.</li> <li>XIAO HIL build has <code>SX126X_RX_BOOSTED_GAIN=0</code>; actual RX gain register   readback was 0x94 in initial info, every stationary arm, and every scan   status. Indicator remains 0x96. Normal XIAO production default is unchanged.</li> <li>32-symbol preamble, CR4/5, 16-byte synthetic packets, -9 dBm, buffered 8 MHz   SPI. Four scan centers 909.500/909.750/910.000/910.250 MHz.</li> <li>No guard shortening, forced retunes through packets, RF retransmissions,   new public N-channel protocol, or additional oscillator-delay bypass.</li> </ul>"},{"location":"separated_radio_modulation_cache_validation/#same-image-receive-only-timing-ab","title":"Same-image, receive-only timing A/B","text":"<p>Each board ran four three-second windows in off/on/on/off order, rebooting between windows. SF6/125 kHz, four channels, 2,612 us nominal dwell, no extra IRQ tracing, no TX. A HIL-only hook invalidates just the acknowledged modulation tuple before each baseline hop. Optimized windows use production cache behavior. The binary and all other settings remain identical per board.</p> <p>Time is entry to the production retune through BUSY-low observation. It does not include the listening dwell or full application scheduling, and is not an independent RF settling measurement. Unlike the older mixed-bandwidth tests, this frequency-only workload can skip 0x8B.</p> Board / policy Hops Mean Min\u2013max Actual 0x86 / 0x8B writes XIAO, always write 1,898 548.880 us 535\u2013663 us 1,898 / 1,898 XIAO, reuse unchanged tuple 1,957 451.897 us 441\u2013580 us 1,957 / 0 Indicator, always write 564 8,263.438 us 8,228\u20138,428 us 564 / 564 Indicator, reuse unchanged tuple 602 7,601.193 us 7,583\u20137,762 us 602 / 0 <p>Pooled means are sample-weighted from reported per-window means. Savings are 96.983 us (17.7%) for XIAO and 662.246 us (8.0%) for Indicator. All 5,021 hops passed RX-mode/software-cache checks with zero retune errors or deferrals. Counters observe outgoing SPI opcodes, not merely which software branch ran. Initial setup before counter snapshots is excluded. The Indicator remains above the common 6 ms switching allowance; no common timing budget changed.</p>"},{"location":"separated_radio_modulation_cache_validation/#stationary-rf-controls","title":"Stationary RF controls","text":"<p>Full initialization before every case, fixed RX at 910 MHz, ordinary RX with fast reuse disabled, shuffled offsets, 450 ms capture windows. Method matches the earlier investigation.</p> TX offset SF6 preamble windows SF8 preamble windows Silent 0/4 0/8 On frequency 4/4 8/8 -250 kHz 0/4 1/8 +250 kHz 0/4 1/8 -500 kHz 0/4 2/8 +500 kHz 0/4 0/8 -1,000 kHz 0/4 0/8 +1,000 kHz 0/4 0/8 <p>All 12 on-frequency probes delivered valid payloads. No off-frequency header or valid payload, silent preamble, device/read error, foreign valid payload, or trace overflow occurred. SF6 off-channel detections changed from 1/24 to 0/24; SF8 from 32/48 to 4/48. These are small bounded samples, not sensitivity or packet-error-rate estimates. On-frequency instantaneous RSSI was -41 to -40 dBm at SF6 and -42 dBm at SF8: the signal remains strong and readings are not calibrated attenuation measurements. Improvement cannot be attributed solely to separation or solely to normal gain.</p>"},{"location":"separated_radio_modulation_cache_validation/#four-channel-sf6125-51-symbol-visits","title":"Four-channel SF6/125, 5.1-symbol visits","text":"<p>Same image, baseline then optimized, reboot both boards between runs. Each requested 100 packets/channel with varied unsynchronized arrival timing and stopped at its first miss. Extra nominal 64 us IRQ polling was enabled here, unlike the receive-only timing windows. No higher channel count was tested.</p> Policy Received before first miss Failed channel Timed hops Mean retune Always write 0x8B 24, then probe 25 missed 1 / 909.750 MHz 4,746 551.253 us Reuse unchanged tuple 51, then probe 52 missed 1 / 909.750 MHz 7,748 455.157 us <p>Optimized RF run: 7,697 hops omitted 0x8B, averaging 453.081 us; 51 hops reapplied it after received packets, averaging 768.529 us. These are different RX lifecycle paths, not a pure 315 us command-cost comparison. Both runs had one frequency write per hop and no RX-mode/cache/retune errors. Successful packets read -42 to -40 dBm with SNR 10.0\u201311.5 dB. Neither met 100/100 on every channel. More packets before the first miss does not establish a reliable improvement in packet-error rate.</p> <p>The baseline miss captured a target-channel preamble at 176,194 us after arming, 1,830 us after a hop onto that channel. A guard held it there; no header or packet followed. An IRQ clear was observed at 195,025 us and the next hop completed at 195,240 us. This is not the earlier SF8 wrong-channel hold: the preamble was observed on the intended channel. Its RF source and reason for failing to progress remain unproven.</p> <p>The optimized miss captured 3,256 hops over ten seconds with no observed nonzero IRQ and no guard hold, reproducing the pre-acquisition symptom of the earlier SF6 miss. Target-channel revisit intervals were 12.249\u201312.324 ms (mean 12.286 ms), shorter than the 16.384 ms programmed preamble, yet no packet was acquired during those short individual visits. This does not establish that additional post-retune settling is needed. Trace buffers did not overflow. TX returned success for both failed probes; the MCU clocks are not synchronized and there was no independent RF capture.</p>"},{"location":"separated_radio_modulation_cache_validation/#provenance","title":"Provenance","text":"<p>RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both targets built and uploads were verified. These captures precede the subsequent SF5/250 bandwidth-selector addition.</p> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>8aa79da891409c9e600ce14c1d83a8d73c3198225a2aaf799fc884247e882fab</code></li> <li>Indicator: <code>868946d0beca882d8f215c1556c0c19bf41908baac6620dc5632c3fca85b5feb</code></li> </ul> <p>Raw files in <code>tools/hil</code>, preserved byte-for-byte:</p> File SHA-256 XIAO timing <code>45e7a640323a3c9028b6c92a5128e51307db1bd94a4846e8744d3c3ec098adfd</code> Indicator timing <code>f0a85826f500b3a9173bf22c6207fbfba3b6cb17f3d70b849a9fe7621ae3dfc5</code> Stationary SF6 <code>1d981e5af41eabbc43f92641813bf8f7c5e7015439f5ba53ce0467fe6477d3f3</code> Stationary SF8 <code>36e63da7435d0a16f61db7db7730893de392d028feca7a96960fd17ae1fa624b</code> SF6 baseline scan <code>cbfd200170891b334ef3958479694c6e318146993b94073eb9aee981f97fde97</code> SF6 optimized scan <code>d88a621ef9aa358ce52bb3efb6aa9c4bcb77c681af20b2c66e4aebf3721e17ca</code> <p>Fresh complete 8 MiB backups were saved and separately verified in the private current-user backup directory before testing. Restores had already started when the user requested leaving HIL firmware installed; those in-flight writes and verification finished safely. Both boards were subsequently loaded with the newer SF5/250 HIL build for the user's next sweep. Do not restore them again unless requested. No private backup contents were added to Git.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/","title":"SF10/125 full samples: 10 Hz versus 100 Hz first-pass detour","text":"<p>2026-09-14. Both 400-packet samples completed: 100 attempts on each of four channels, with no RF retries or early stop on misses. Payload loss was 64/400 (16.0%) at 10 Hz and 81/400 (20.25%) at 100 Hz. Strict same-channel reception was almost identical: 230/400 versus 231/400. The larger offset showed no improvement in this comparison.</p> <p>These are two sequential finite bench samples, not proof that the offset caused the difference in payload loss. The earlier stop-first tests could not provide this error-rate estimate and are not combined with these counts.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#settings-and-method","title":"Settings and method","text":"<ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, 28:84:85:B4:09:80.</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, B35E71C1C3726CE7.</li> <li>Uniform SF10, BW125 kHz, nominal CR4/5; 909.5, 910.5, 911.5, 912.5 MHz.</li> <li>32-symbol preamble; 5.1-symbol visits (41,780 us); zero added settling.</li> <li>Normal RX gain 0x94, -9 dBm chip TX request, 16-byte CHS1 payloads.</li> <li>Warm XOSC, bulk SPI, fast RX; TCXO setting 1600 us. No added IRQ tracing.</li> <li>Two full retunes per hop. First: selected positive RF offset, CR4/6.   Second: exact original RF command, CR4/5. Duplicate frequency writes   remain inside each pass: four RF commands, two modulation writes and   two optimized RX starts per completed hop.</li> <li>Requested 10 Hz = +10 integer RF-word steps, nominal 9.5367431640625 Hz.   Requested 100 Hz = +105 steps, nominal 100.13580322265625 Hz. Neither   depends on a float-MHz addition. This is programmed, not independently   spectrum-measured, frequency.</li> <li>Same receiver image for both runs; only the requested offset changed.   Order: 10 Hz, reboot, 100 Hz. TX firmware was unchanged.</li> <li>Seed 606125: shuffled channel order each round and varied arrival pauses.   Each run has 400 unique probe sequences and exactly 100 TXs per channel.</li> <li>Existing 10-second expectation timeout retained. A miss does not reset   the receiver, tune it toward TX, reset the visit clock or clear counters.   Hardware/guard/command failures still abort rather than become RF losses.</li> </ul> <p>The complete comparison ran from 21:09:11 to 21:42:39 UTC (14:09\u201314:42 PDT), about 33 minutes. The 10 Hz sample took about 15.4 minutes; 100 Hz about 18.0. The extra elapsed time is largely the additional ten-second timeouts.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#overall-results","title":"Overall results","text":"<p>\"Payload loss\" means no intact expected payload was delivered within the expectation window, regardless of reported RX channel. \"Strict error\" also counts intact payloads received while the scanner reports another channel.</p> Requested offset Attempts Correct-channel delivery Intact wrong-channel delivery Timeouts / payload loss Strict errors 10 Hz 400 230 (57.5%) 106 (26.5%) 64 (16.0%) 170 (42.5%) 100 Hz 400 231 (57.75%) 88 (22.0%) 81 (20.25%) 169 (42.25%) <p>All scored delivery failures were timeouts. The receiver also counted six packet-read errors at 10 Hz and eleven at 100 Hz. The error codes were not captured, so these cannot be identified specifically as CRC failures or mapped one-to-one to timeout probes. \"Zero invalid payloads\" in the summary does not mean there were no packet-read/CRC errors before timeout.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#per-channel-results","title":"Per-channel results","text":"<p>Each cell uses exactly 100 attempts. Loss counts therefore also equal percent.</p> Center (MHz) 10 Hz payload loss 100 Hz payload loss 10 Hz strict errors 100 Hz strict errors 909.5 10% 11% 26% 25% 910.5 23% 23% 51% 45% 911.5 19% 26% 48% 55% 912.5 12% 21% 45% 44% <p>The extra 17 payload losses at 100 Hz occurred on channels 0 (+1), 2 (+7) and 3 (+9). Correct-channel deliveries differed by only one packet overall. Neither offset eliminated wrong-channel acquisition/delivery or timeouts. This comparison does not isolate the underlying RF failure mechanism.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#switching-and-signal-measurements","title":"Switching and signal measurements","text":"Metric 10 Hz 100 Hz Completed hops 16,992 20,676 Mean complete two-pass switch 1263.765 us 1262.551 us Maximum complete switch 1533 us 1532 us Mean first pass 660.712 us 659.458 us Mean second pass 592.344 us 592.406 us RF commands 67,968 82,704 Modulation commands / RX starts 33,984 / 33,984 41,352 / 41,352 Maximum unheld four-channel cycle 174,139 us 173,722 us Maximum held channel visit 590,757 us 640,492 us Packet-read errors 6 11 <p>Unheld cycles fit within the 262,144 us programmed preamble; packet-related held visits can exceed it. Aggregate timing without IRQ traces does not prove which hold caused any particular timeout. The approximately 1.2 us difference in mean switching time is negligible here and does not explain the losses.</p> <p>All completed hops passed the internal first-offset/final-correction and CR command checks: 16,992/16,992 and 20,676/20,676, <code>detour.bad=0</code>. Second-pass blocks, retune failures, mode errors and cache errors were zero. Counts match four RF writes, two modulation writes and two RX starts per completed hop.</p> <p>Telemetry limitation: the diagnostic <code>detour.first_rf/first_mod</code> fields are updated on a guard-deferred first attempt as well as an applied attempt, while <code>final_rf/final_mod</code> retain the last completed second pass. Thus the final snapshot's displayed pair can be from different attempts and appears equal in these captures. Those fields must not be interpreted as the last verified pair. Verification itself runs only after two applied passes and increments <code>detour.n</code> only then; its per-hop comparisons, zero failures and matching counts establish the commanded sequence. Original capture bytes are retained.</p> Packet group 10 Hz mean RSSI / SNR 100 Hz mean RSSI / SNR Correct-channel delivery -34.05 dBm / +8.56 dB -34.15 dBm / +8.62 dB Intact wrong-channel delivery -105.18 dBm / -13.75 dB -105.22 dBm / -13.62 dB <p>The markedly weaker wrong-channel readings are observations, not proof of a specific filter/image/overload mechanism.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#implementation-and-verification","title":"Implementation and verification","text":"<p>The HIL scanner gained <code>scancontinue 1</code>, default off, so its ordinary completion and timeout accounting can leave scanning active. The host gained bounded <code>--continue-on-miss --max-channels 4</code> with separate delivery/strict summaries. <code>scandetouroffset 10|100</code> and <code>--first-pass-offset-hz 10|100</code> select the integer offset while stopped. Production radio defaults and receive guards were not changed. The controller is <code>tools/hil/profile_switch_offset_compare.py</code>.</p> <p>23 native profile tests and 51 host tests passed. Coverage includes continuing through all 400 attempts without restart/retry, balanced channels, separated error definitions, default first-miss behavior, aborting fixture failures, both integer offsets and exact restoration. Build/upload succeeded with hash verification: RAM 94,948 bytes, reported flash 370,213 bytes.</p> <p>There was one cached USB RX-result replay in each sample, with no RF retransmit. All TX commands returned success. Host/device strict receive and miss counters matched; both captures are complete under <code>fixed_sample_complete</code>. The master manifest is complete under <code>both_400_packet_samples_complete</code>, with no fixture or cleanup error.</p> <p>Both boards rebooted idle afterward. RX confirmed scanner inactive, zero channels, one-pass default, detour/continue disabled and normal gain 0x94. TX confirmed no autonomous TX. HIL remains installed; RAK COM29 was not opened. The temporary PlatformIO overlay was removed. No background collector remains. This work made no commits or pushes. Existing unrelated changes were preserved.</p>"},{"location":"sf10_10_vs_100hz_full_sample_validation/#provenance","title":"Provenance","text":"<ul> <li>Manifest: <code>tools/hil/profile_switch_sf10_10_vs_100hz_full_results.json</code>   SHA-256 <code>40ef9d70991b585abe6b99b3dc4878829412d55e0e8b5a984576b00db0326981</code></li> <li>10 Hz capture: <code>tools/hil/profile_switch_sf10_10_vs_100hz_full_results_10hz.json</code>   SHA-256 <code>889a7afeb980ec8459fccb8da5a7c496feebd433da8715f84181f02c1da613aa</code></li> <li>100 Hz capture: <code>tools/hil/profile_switch_sf10_10_vs_100hz_full_results_100hz.json</code>   SHA-256 <code>0b54a057c07f9da0b03f585aeffee960ffcfa2ecb5383914554697ca250aa071</code></li> <li>RX BIN SHA-256:   <code>bddf779208cbfd24478d39d3075f3f7537b7c9275453492748a349f3ec15b630</code></li> <li>Unchanged TX ZIP SHA-256 from the preceding validated upload:   <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> </ul> <p>Source: live keymindCascade working tree at HEAD <code>2b5a6f209835f0f67ed73fee78d36447a4566ce6</code>, plus existing dirty changes and these HIL additions. The RX image hash identifies the exact tested build. Earlier captures were not overwritten.</p>"},{"location":"sf10_10hz_cr_detour_validation/","title":"SF10/125: tiny first-pass frequency offset and coding-rate detour","text":"<p>2026-09-14. The requested offset no longer rounds to zero. Actual outgoing commands verified a +10-step RF-word change (nominal +9.536743 Hz), then exact restoration of the original word, with CR4/6 then CR4/5. Two passes averaged 1.259 ms in RX-only timing. The first packet still timed out. This is a bounded one-probe failure, not a 400-packet loss-rate estimate.</p>"},{"location":"sf10_10hz_cr_detour_validation/#scope-and-precision","title":"Scope and precision","text":"<p>The request was to apply a slightly different center frequency and coding rate on the first full retune, then the correct settings on the second, with about 0.01 kHz difference. At these centers a float in MHz advances in roughly 61 Hz increments: adding 0.00001 MHz can produce the same float.</p> <p>The HIL implementation does not make that float addition. A scoped integer offset changes the four-byte argument of the actual 0x86 frequency command by ten steps. The nominal SX1262 step is 32 MHz / 2^25; ten steps are 9.5367431640625 Hz, the nearest achievable nominal command offset to 10 Hz. See the frequency-step specifications in the Semtech SX1261/2 datasheet. Pinned RadioLib 7.7.1 also specifies this step and sets the standard sensitivity configuration bit for bandwidths other than 500 kHz. This establishes the programmed offset, not a spectrum-analyzer measurement of physical frequency.</p> <p>First pass: destination RF word + 10 and CR4/6. Second pass: original RF word and CR4/5. The offset is applied to both existing duplicate frequency writes inside the first pass. Caller buffers remain unchanged; a scoped restore prevents the offset leaking into the corrected pass or an unrelated command. Rollback applies the offset only when restoring the temporary CR4/6 tuple.</p> <p>Both passes retain ordinary packet/ownership/BUSY guards, command-result checks and RX startup. A blocked second pass fails the diagnostic rather than overriding a packet guard. Each completed hop verifies both outgoing frequency words and modulation words (0x0a040200 then 0x0a040100). The host requires a verification count equal to completed hops and zero mismatches.</p> <p>This feature is HIL-only, off on reboot. Production defaults were not changed. The earlier +31.25 kHz draft was superseded before flashing or RF testing.</p>"},{"location":"sf10_10hz_cr_detour_validation/#fixture-and-method","title":"Fixture and method","text":"<ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, 28:84:85:B4:09:80.</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, B35E71C1C3726CE7; unchanged firmware.</li> <li>Centers 909.5, 910.5, 911.5, 912.5 MHz; uniform SF10/BW125.</li> <li>32-symbol preamble, 5.1-symbol visits (41,780 us), no added settling.</li> <li>Normal RX gain 0x94; warm XOSC, bulk SPI and fast RX; TCXO setting 1600 us.</li> <li>16-byte CHS1 probes, -9 dBm chip TX request, varied arrival phase.</li> <li>Goal 100 packets/channel; stop at the first strict miss or 400/400.</li> <li>Four frequency commands, two forced modulation writes, two optimized RX   starts per completed hop. No extra IRQ tracing/polling.</li> </ul> <p>Same-image RX-only ABBA controls compare two identical full passes (A) with the first-pass detour followed by correction (B), six seconds each, rebooting between windows. This is not a comparison against the original single-pass approximately 0.53 ms cached-modulation path.</p>"},{"location":"sf10_10hz_cr_detour_validation/#timing","title":"Timing","text":"Window First-pass detour Hops Mean total (us) Maximum (us) First pass mean (us) Second pass mean (us) A1 Off 139 1230.094 1464 631.727 594.281 B1 On 139 1259.770 1490 647.165 603.245 B2 On 139 1258.806 1481 646.547 602.957 A2 Off 139 1230.597 1467 633.209 593.252 <p>Mean two-pass control 1230.346 us; detour/correction 1259.288 us, about 28.943 us additional total including configuration/verification bookkeeping. The detour passes themselves averaged 646.856 + 603.101 us. Both detour windows verified 139/139 completed hops with zero mismatches; all four windows had exactly 556 RF commands, 278 modulation commands and 278 RX starts, with zero guard blocks or RX/mode/cache errors.</p>"},{"location":"sf10_10hz_cr_detour_validation/#packet-result","title":"Packet result","text":"<p>Probe 1021099889, TX channel 3 at 912.5 MHz, timed out: 0 received / 1 attempted, then stopped. TX rc=0, setup 86,914 us, transmit call 529,297 us. RX was in receive mode, hardware device-errors=0. No payload-only diagnostic ran because this was a timeout, not an intact payload attributed to another channel. There were no RF retries.</p> <p>During that packet window:</p> <ul> <li>220 completed hops; 220 verified detour/correction pairs, zero mismatches.</li> <li>880 RF commands, 440 modulation commands, 440 optimized RX starts.</li> <li>Mean switch 1262.095 us, maximum 1507 us; first pass 652.082 us, second   601.295 us. Second-pass-blocked=0, retune failures=0, mode/cache errors=0.</li> <li>Maximum unheld four-channel cycle 172,222 us, below the 262,144 us preamble.</li> <li>Maximum held visit 542,732 us; the aggregate receive-error count was 1.   That counter means a packet read returned an error; this capture does not   retain its error code or IRQ trace, so it cannot establish CRC as the cause   or assign the hold to a particular channel. Device-errors=0 is a separate   hardware status and does not mean there were no receive errors.</li> </ul> <p>Across both detour timing windows and the packet window, 498/498 completed hops verified the nonzero first-pass RF offset, original final RF word and CR4/6-to-CR4/5 sequence. This proves the change was exercised; it did not resolve reception in this bounded test. The underlying RF failure remains unidentified.</p>"},{"location":"sf10_10hz_cr_detour_validation/#usb-setup-issue-and-verification","title":"USB setup issue and verification","text":"<p>The first controller attempt stopped before transmitting because the new 126-byte capability JSON plus CRLF formed an exact 128-byte native-USB reply. It remained buffered until another command was sent. This was preserved as a fixture failure, not counted as packet loss. A single LF-terminated write (127 bytes) fixed this specific reply; three independent reads then passed without a follow-up command, and the complete controller ran successfully.</p> <p>22 native profile tests and 49 host tests passed. Added tests cover integer carry, unchanged caller bytes, both SPI paths, observation of shifted wire bytes, exact restoration, scope exit/nesting, non-frequency commands, overflow, detour verification failures and the USB reply length. Build/upload passed with flash hash verification: RAM 94,948 bytes, reported flash 369,593 bytes. <code>git diff --check</code> passed (unrelated existing CRLF warning only).</p> <p>Both boards rebooted idle after completion. RX confirmed scanner inactive, zero channels, one-pass default, detour disabled, normal gain 0x94. TX reports no autonomous transmission. HIL firmware remains installed as requested. RAK COM29 was not opened. Temporary PlatformIO overlay removed; no collector left running. This experiment made no commits, pushes or production-default changes.</p>"},{"location":"sf10_10hz_cr_detour_validation/#provenance","title":"Provenance","text":"<ul> <li>Successful manifest: <code>tools/hil/profile_switch_sf10_10hz_cr_detour_verified_results.json</code>   SHA-256 <code>84a14c3ca3169b8afdaffbef4405a5ea25140560c799091e5f22257814713bcb</code></li> <li>Strict capture: <code>tools/hil/profile_switch_sf10_10hz_cr_detour_verified_results_strict.json</code>   SHA-256 <code>e7995b327b5a84d8fc1830ece1f4cfccd70cae9f367eefd91b7e97ade4a9fb68</code></li> <li>Setup-only failed attempt: <code>tools/hil/profile_switch_sf10_10hz_cr_detour_results.json</code>   SHA-256 <code>486dd52a4ce5f4b20fadec4e6af2e1ede9669acd3e6a09b3490ae5c8b52b82dd</code></li> <li>Installed RX BIN SHA-256:   <code>aae7fd3ffcb5226759884e4d1b41d9da67bb97e95ef89d29dd54f204412d6b48</code></li> <li>Unchanged TX ZIP SHA-256 from the preceding validated upload:   <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> </ul> <p>Successful manifest complete, stopped <code>bounded_tests_complete</code>; strict capture complete under first-miss stopping. No fixture or cleanup error in that run. The build used the live keymindCascade working tree with existing dirty changes and these HIL additions, not a clean-release image. HEAD observed at completion was <code>2b5a6f209835f0f67ed73fee78d36447a4566ce6</code>; the unrelated Companion USB commit advanced HEAD from the earlier experiment's base during this ongoing work. Its files were not reverted. The RX image hash above is the exact tested-image identifier. Prior captures were preserved.</p>"},{"location":"sf10_full_retune_twice_validation/","title":"SF10/125: apply the full radio settings twice per hop","text":"<p>2026-09-14. Two full retune passes were verified, averaging 1.276 ms per channel switch. This did not resolve reception in the bounded packet test: the first packet timed out. This is one failed probe, not a 400-packet loss measurement. No production defaults or receive guards were changed.</p>"},{"location":"sf10_full_retune_twice_validation/#requested-interpretation-and-fixture","title":"Requested interpretation and fixture","text":"<p>\"The 125 run\" was interpreted as uniform SF10/125 on four channels, not the preceding mixed-SF/BW experiment. Apply the complete retune twice to each destination: frequency, modulation, preamble/packet configuration and RX restart, retaining normal guards and command-result checks for both passes.</p> <ul> <li>Receiver: XIAO ESP32-S3 / Wio SX1262, COM31, 28:84:85:B4:09:80.</li> <li>Transmitter: XIAO nRF52840 / Wio SX1262, COM15, B35E71C1C3726CE7.</li> <li>Centers: 909.5, 910.5, 911.5, 912.5 MHz. SF10/125, CR4/5, 32-symbol   preamble, 5.1-symbol visits, 16-byte CHS1 probes, -9 dBm chip request.</li> <li>Normal RX gain 0x94; warm XOSC and fast/bulk RX path; TCXO timing 1600 us.</li> <li>No added settling and no extra IRQ tracing/polling. Goal: 100 packets per   channel, stop on the first strict miss or a complete 400/400 pass.</li> <li>The previous immediate double frequency write remains inside each   pass: four frequency commands per hop. Modulation is forced in both passes,   giving two 0x8B commands and two optimized RX starts per completed hop.</li> </ul> <p>The earlier approximately 0.53 ms path could skip unchanged modulation. This test deliberately writes those settings again, so it measures more than 0.53 + 0.53 ms. No artificial time padding was added to meet an expected value.</p>"},{"location":"sf10_full_retune_twice_validation/#same-image-rx-only-timing","title":"Same-image RX-only timing","text":"<p>Six-second windows in 1/2/2/1-pass order, with a reboot before each. Both one- and two-pass controls force modulation writes, so the comparison isolates complete repetition rather than also changing cache policy.</p> Window Passes per hop Hops Mean total (us) Max total (us) Mean first pass (us) Mean second pass (us) A1 1 141 647.284 847 644.220 \u2014 B1 2 139 1275.410 1491 648.899 622.835 B2 2 139 1276.086 1488 649.000 623.288 A2 1 141 647.858 836 644.872 \u2014 <p>Equal-weight/hop-count means: one full pass 647.571 us; two full passes 1275.748 us. The first and second passes average 648.950 + 623.062 us; the total includes approximately 3.7 us additional wrapper/BUSY bookkeeping. Both two-pass windows had 556 frequency writes, 278 modulation writes and 278 optimized RX starts. No second-pass guard block or hardware/cache error.</p>"},{"location":"sf10_full_retune_twice_validation/#packet-test","title":"Packet test","text":"<p>First probe: TX channel 3, 912.5 MHz, sequence 600920621. TX returned rc=0, setup 86,914 us, transmit call 529,297 us. RX timed out with mode=1 and device errors=0. The controller stopped without retrying or testing further packets. No separate payload-only diagnostic ran because this was a real timeout, not an intact wrong-channel delivery.</p> <p>During the packet window:</p> <ul> <li>223 channel hops; 892 frequency writes; 446 modulation writes; 446 optimized   RX starts. Both pass counters = 223, second-pass-blocked = 0.</li> <li>Mean full switch 1275.058 us, maximum 1510 us.</li> <li>First pass mean 648.812 us, second pass mean 622.601 us.</li> <li>Maximum unheld full four-channel cycle 172,262 us, below the 262,144 us   programmed preamble. Mean listening visit 41,785.719 us.</li> <li>Maximum held visit 405,102 us. No IRQ trace was taken, so the exact cause   and channel of this hold cannot be assigned from these aggregate numbers.</li> <li>Received 0, missed 1. Mode errors, cache errors, RX errors and device errors   were all zero. Normal gain remained 0x94.</li> </ul> <p>This shows that completing two real settings applications does not by itself guarantee successful reception in this fixture. It does not prove every packet would fail or independently identify the cause of this particular timeout.</p>"},{"location":"sf10_full_retune_twice_validation/#implementation-and-verification","title":"Implementation and verification","text":"<p>HIL <code>BenchWrapper::hop</code> performs the first ordinary guarded <code>tuneProfile</code>, then waits boundedly for BUSY-low and requests a refresh of the same profile before the second ordinary guarded transaction. This bypasses only the same-generation no-op, not receive ownership or packet-in-progress checks. The modulation cache is invalidated for each requested full pass.</p> <p>If the second pass is blocked by newly acquired reception, the diagnostic fails closed. Returning ordinary BUSY would wrongly imply that no channel change occurred even though pass one had completed; it is therefore treated as a fixture failure, not silently skipped or counted as an RF loss.</p> <p><code>scanretunepasses 1</code> is the reboot default. <code>scanretunepasses 2</code> and <code>--retune-passes 2 --modulation-cache off</code> select this bounded test. The standalone controller is <code>tools/hil/profile_switch_retune_repeat.py</code>. 19 native profile tests and 49 host tests passed, including real refresh, first/second failure handling, BUSY timeout, no guard override, and rejection of missing physical write/resume counts. <code>git diff --check</code> passed with only unrelated existing CRLF warnings.</p> <p>Receiver build/upload succeeded with hash verification: 94,908 bytes RAM, 368,389 bytes reported flash. Transmitter firmware was not changed or reflashed. Unrelated RAK COM29 was not opened. Both boards rebooted idle after completion, retaining HIL firmware; no autonomous TX or background collector. Temporary PlatformIO overlay removed. No commit/push requested or performed.</p>"},{"location":"sf10_full_retune_twice_validation/#provenance","title":"Provenance","text":"<ul> <li>Manifest: <code>tools/hil/profile_switch_sf10_full_retune_twice_results.json</code>   SHA-256 <code>2928955ce4b02828f3de292cdf8a18606cb56d8a5d6b65c7b50c3de1dd15f764</code></li> <li>Strict capture: <code>tools/hil/profile_switch_sf10_full_retune_twice_results_strict.json</code>   SHA-256 <code>322d1859716fbed0e42224f7bfbf71815dcc986df3ccccea37c1680a63723340</code></li> <li>Installed RX BIN SHA-256:   <code>aa7e3e96729bdb855593385a7a5ab9a22a5e186fda551db863a52a81b7cca2bb</code></li> <li>Unchanged TX ZIP SHA-256:   <code>915d507d0feec1712fad2bd4be62c2fa8d769d11400711de0da1cf98a50a4b36</code></li> </ul> <p>Manifest complete, stopped <code>bounded_tests_complete</code>; strict capture complete under first-miss stopping. No fixture or cleanup error. Previous captures were not rewritten. Source remains keymindCascade commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> plus existing dirty changes and these HIL-only additions, not a clean-release comparison.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/","title":"SF10 / 125 kHz, XIAO nRF52 TX, double write, 1 ms delay grid","text":"<p>2026-09-14. Fixed-channel positive control passed 100/100. The subsequent four-channel, double-write sweep failed at every 1 ms step from +0 to +23 ms.</p> <p>New sender serial B35E71C1C3726CE7 first enumerated as Zephyr CDC COM33 (2FE3:0004). A 1200-baud touch exposed Seeed XIAO bootloader COM25 (2886:0044, XIAO-BOOT). The application-only DFU ZIP was accepted with its normal compatibility checks, reported programmed successfully and reappeared as COM15 (2886:8044), with the same serial and ready XIAO nRF52840/Wio SX1262 HIL identity. No bootloader/SoftDevice replacement or full erase was performed. The unrelated RAK COM29 (4D6F77FD74011872) was not opened.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/#requested-test","title":"Requested test","text":"<ul> <li>Receiver: existing XIAO ESP32-S3/Wio SX1262 on COM31, normal RX gain 0x94.   MAC 28:84:85:b4:09:80. The host reasserts double-write mode after every reboot.</li> <li>Sender: XIAO nRF52840/Wio SX1262 COM15, serial B35E71C1C3726CE7.</li> <li>SF10/125 kHz, CR4/5, four channels, 5.1-symbol listening visits, 32-symbol   preamble, 100 packets/channel, fixed 16-byte probes at -9 dBm chip request.</li> <li>Added post-BUSY settling 0, 1, 2, ... 23 ms. Each failed setting stops at   its first miss; the entire sweep stops at its first 400/400 pass. No added   delay beyond the nominal full-sweep timing ceiling and no lower SF runs.</li> <li>Double frequency writes retained; modulation cache on; no extra IRQ trace.   No prior-transmitter or single-write measurements will be reused.</li> </ul> <p>Budget uses 539 us nominal double-write retune (ceil of the measured 538.192 us RX-only mean), 41,780 us post-settle visit and 262,144 us preamble: <code>262144 / 4 - 41780 - 539 = 23217 us</code>. Last 1 ms grid point is 23,000 us. This is a nominal ceiling, not a worst-case jitter or zero-loss guarantee.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/#preparation","title":"Preparation","text":"<p>The settling controller now accepts <code>--step-us 1000 --frequency-repeat on</code>; its existing defaults are unchanged. Capture policy checks reject mixed single/double evidence. The 42 host collector tests and 14 selected profile native tests passed, including grid/first-pass stop, nRF USB DTR behavior, transmitter replay, setup/TX failure, stationary payload integrity, zero-retune and host/device-count checks. <code>git diff --check</code> passed (unrelated CRLF warnings).</p> <p>Minimal <code>profile_switch_xiao_nrf52_tx</code> firmware compiled successfully: 95,340 bytes reported flash usage, 18,212 bytes static RAM. It uses the production XIAO pin map and CustomSX1262 initialization, exposes only reference TX and cached USB results, and has no Mesh identity or application settings writes. Includes the existing build-local bounded nRF USB READY/HFCLK fix.</p> <p>Platform: Nordic nRF52 10.8.0; Adafruit nRF52 framework 1.10701.0+sha.d5413016; ARM GCC 14.2.1; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>.</p> <p>Generated DFU ZIP contains application only, requiring SoftDevice ID 0x0123. Upload used normal DFU validation without compatibility overrides. The V4's earlier no-backup erase authorization is not treated as authority to erase this new board's bootloader or unrelated storage.</p> <p>Flashed nRF52 transmitter SHA-256:</p> <ul> <li>HEX: <code>aaee693900dedc3816a6baeca576c7449502d30c05ac48e2663b02acec9aec9a</code></li> <li>DFU ZIP: <code>7466625ef5e7bcc8f7dd16db2b843db29b4312a33b0d32bc0b1e1193d6aee03a</code></li> </ul>"},{"location":"sf10_nrf52_double_write_settling_validation/#baseline-requested-before-continuing-the-sweep","title":"Baseline requested before continuing the sweep","text":"<p>The initial four-channel run was interrupted at the user's request after 13 completed settings, added delay 0..12,000 us. Each missed its first packet: nine matched the test sequence but were reported on channel 2 when channel 3 was expected; four timed out. These are not 13 full 400-packet measurements and must not be presented as an unbiased loss rate. The incomplete original top manifest and all raw captures under <code>tools/hil/profile_switch_sf10_nrf52_double_1ms_results*</code> remain unchanged.</p> <p>Added an independent HIL-only stationary receiver: one full normal radio initialization, fixed 910.25 MHz (channel 3), normal RX rearm, no profile scheduler/fast-switch/cache shortcut. All 100 packets use the same transmitter, SF10/125, CR4/5, 32 preamble symbols, 16-byte CHS1 body and -9 dBm request. No RF retries and no early stop on an RF miss; hardware/fixture faults abort.</p> <p>Result: 100/100, CRC/read errors 0, foreign packets 0, hardware errors 0, observed frequency writes after setup 0. Normal gain register 0x94 and RX mode 1 verified. RSSI mean -33.610 dBm, range -34..-33; SNR mean +8.736 dB, range +7.8..+10.0. Baseline cleanly stopped and both devices rebooted idle. This confirms the fixed-channel link in this finite sample, not all-channel or interference immunity.</p> <p>Capture: <code>tools/hil/profile_stationary_nrf52_sf10_100_results.json</code>. SHA-256: <code>547c30efc89c29e3f60cb975f7fc34de3e9f14bed3ed4cc9f1ba01f63402bf15</code>. Receiver image with stationary capability compiled/flashed and hash-verified: SHA-256 <code>0daab2e3293359280714042492639ab8c176609143cf01996ad4ba7026704768</code>. Reported flash 364,657 bytes; static RAM 94,796 bytes. Existing double-write and four-channel switching implementation is unchanged; baseline is a separate inactive command mode during the scan.</p>"},{"location":"sf10_nrf52_double_write_settling_validation/#post-baseline-four-channel-run","title":"Post-baseline four-channel run","text":"<p>Fresh prefix: <code>tools/hil/profile_switch_sf10_nrf52_postbaseline_double_1ms_results</code>. Command: <code>profile_switch_settling.py --receiver COM31 --sender COM15 --sf 10 --frequency-repeat on --step-us 1000 --output &lt;fresh-prefix&gt;.json</code>. No old captures are reused. Stop at the first 400/400 or after +23 ms.</p> <p>Completed all 24 settings. No 400/400 pass. At zero added delay, the first packet passed and the second timed out. Each +1..+23 ms setting failed its first packet. Total 25 probes: one valid, 17 timeouts and seven test-sequence packets reported on channel 2 while expecting channel 3. Each setting stops on its first miss; this is deliberately censored evidence, not a measured unbiased 4% packet-delivery rate. The lone valid packet was -33 dBm / +8.2 dB SNR. The wrong-channel records do not alone distinguish real off-channel acquisition from channel bookkeeping; no root cause is claimed.</p> <p>Measured 3,086 retunes, weighted mean 526.783 us (0.527 ms), maximum 876 us (0.876 ms), excluding the separately applied settling delay. Exactly 6,172 SetRfFrequency commands confirm two per hop. One modulation command was issued across the measured scan windows (after the sole received packet); no retune failures, RX-mode errors, cache errors or CRC/read errors. All gain checks remained 0x94. This measurement is from the receiver image with the new independent baseline mode, not a controlled performance A/B against the previous image's 538.192 us RX-only mean.</p> <p>At +23 ms the measured settling interval was 23,000..23,001 us and mean switch-plus-settle 23,567.2 us. That short failed window did not contain a complete unheld scan cycle, so it provides no measured final-step full-sweep latency. The ceiling remains the nominal 23,217 us calculation above.</p> <p>Post-baseline top manifest SHA-256: <code>badda7f64a7bdd445942da19dc76dea0d1aace2ae451772edf4744d4670ac28c</code>. Interrupted pre-baseline top manifest SHA-256: <code>90f7b213bc44ae73714c5d9d32216ff3f1760fafd657feb5ea9299ed1e10ddf3</code>.</p> <p>Conclusion: the fixed-channel link passes its 100-packet control, but extra post-switch settling through the nominal budget does not cure this scanner failure. Investigate acquisition/hold behavior and channel attribution next; do not claim more waiting, a second frequency write, or a transmitter swap has fixed the issue. No guard/default production timing was changed here.</p> <p>Collector exited successfully at the nominal timing limit, with no cleanup error; both radios rebooted idle. The previous follow-up automation remains paused. No commit or push requested; HIL firmware remains installed. Temporary build overlay removed. No background test collector remains running.</p>"},{"location":"sf10_rollback_failure_validation/","title":"SF10/125 rollback and wider-spacing failure isolation","text":"<p>2026-09-14. No strict four-channel 400/400 pass. Reverting the switching optimizations did not remove failures. Off-channel reception also occurs with a fixed, fully initialized receiver, without any channel switching. A traced timeout shows an off-channel preamble holding the scanner away from the intended channel until after its transmit preamble. Wider spacing did not eliminate either wrong-channel delivery or actual missing packets.</p> <p>This isolates a concrete scanner failure mechanism, not the underlying physical RF cause. Commanded frequency words are observed, but actual emitted spectrum, antenna-port power, image responses and overload have not been independently measured. Do not claim front-end saturation or a specific spur as proven. Do not treat these first-failure-censored samples as unbiased PER.</p>"},{"location":"sf10_rollback_failure_validation/#fixture-and-requested-controls","title":"Fixture and requested controls","text":"<ul> <li>RX: XIAO ESP32-S3 / Wio SX1262, COM31, MAC 28:84:85:B4:09:80; normal RX gain   register 0x94 throughout (boosted gain off).</li> <li>TX: XIAO nRF52840 / Wio SX1262, COM15, serial B35E71C1C3726CE7.</li> <li>SF10, 125 kHz BW, CR4/5, 32-symbol preamble, 16-byte sequenced CHS1 probes,   -9 dBm chip request, four channels, 5.1-symbol post-settle listening visits.</li> <li>Original centers: 909.5, 909.75, 910.0, 910.25 MHz. User-requested wider   centers: 909.5, 910.5, 911.5, 912.5 MHz (1 MHz spacing).</li> <li>Existing fixed-channel positive control was 100/100; see   <code>sf10_nrf52_double_write_settling_validation.md</code>. No failed packets retried.</li> <li>Unrelated RAK COM29 was not opened. New nRF52 upload was application-only,   using normal SoftDevice ID 0x0123 validation; no bootloader/SoftDevice erase.</li> </ul> <p>Rollback modes are runtime HIL controls on the same current source, not historical firmware checkouts. No production default or receive safety guard was changed during this investigation. Tests preserve ownership, packet-in- progress, BUSY and command-result checks. Existing unrelated working-tree changes were left intact. No commit or push was requested this turn.</p>"},{"location":"sf10_rollback_failure_validation/#maximum-practical-settling-control","title":"Maximum practical settling control","text":"<p>At SF10/125, a symbol is 8,192 us, the programmed preamble is 262,144 us, and each 5.1-symbol post-settle visit is 41,780 us. For each rollback mode:</p> <ol> <li>Measure six seconds of RX-only switching without added delay.</li> <li>Choose the largest 100 us delay step satisfying    <code>4 * (41780 + observed_max_switch_us + added_delay_us + 500) &lt;= 262144</code>.</li> <li>Measure another six seconds; require at least eight full idle cycles and    maximum observed idle cycle below the preamble before allowing TX.</li> </ol> <p>The 500 us per-hop reserve covers some observed scheduling variation, not all possible jitter. RX is active during added settling. Near-ceiling cycle timing is not itself a guarantee of acquisition for every arrival phase, especially when an IRQ causes an extended packet hold. Idle-cycle statistics exclude guard/packet-held visits; those are measured separately.</p>"},{"location":"sf10_rollback_failure_validation/#250-khz-spacing-eleven-rollback-cases","title":"250 kHz spacing: eleven rollback cases","text":"<p>Each case stopped on its first probe, TX channel 3, with a real timeout. No strict 400/400 pass, TX fault, RX mode/cache failure, or hardware error. The first nine cases used the checkout's existing 1,600 us TCXO setting; the final two explicitly restored 6,000 us. Production timing was not edited.</p> Case Added delay (us) Zero-delay mean switch (us) Max settled idle cycle (us) Fast, cached modulation, double frequency write 22500 535.88 259297 Always write modulation 22500 625.50 259682 Individual SF/BW/CR writes 22200 840.97 259346 Full normal RX restart 22200 896.89 259577 Full RX + individual modulation 22000 1113.95 259623 Above + byte-wise SPI, warm XOSC 21800 1215.79 259220 Above + RC standby, 1.6 ms TCXO 20100 2942.50 259339 Fast, cached modulation, single frequency write 22600 450.25 259341 RC/full RX/individual/byte-wise, single write, 1.6 ms TCXO 20200 2837.50 259329 RC/full RX/individual/byte-wise, double write, 6 ms TCXO 15800 7293.25 259550 RC/full RX/individual/byte-wise, single write, 6 ms TCXO 15800 7190.31 259139 <p>Actual frequency/modulation command counts and fast-RX counts verified each policy. Slower modes received less added delay to preserve the total sweep budget. These are eleven probes with eleven timeouts, not eleven complete 400-packet runs. Packet arrival pauses use the same seeded scheduling method but not hardware-synchronized identical RF phases across modes.</p>"},{"location":"sf10_rollback_failure_validation/#fixed-frequency-controls-off-channel-responses-without-switching","title":"Fixed-frequency controls: off-channel responses without switching","text":"<p>Each pair received three independent probes after full normal initialization. Positive controls were interleaved. The receiver remained at one frequency: zero observed frequency commands after setup, no hopping or cache shortcut. Payload success requires the exact expected sequence/channel/body, length 16 and clean CRC. It does not require RX center to equal TX center in this explicit offset diagnostic. Offset below means programmed RX minus TX.</p> Spacing RX-TX offset (kHz) Probes Intact expected payloads Preamble IRQ seen 250 kHz 0 6 6 6 250 kHz -250 3 2 3 250 kHz -500 3 0 3 250 kHz -750 3 0 3 250 kHz +250 3 0 2 1 MHz 0 6 6 6 1 MHz -1000 3 2 3 1 MHz -2000 3 0 0 1 MHz -3000 3 3 3 1 MHz +1000 3 3 3 <p>At 250 kHz spacing, the two valid -250 kHz-offset packets reported RSSI -91/-90 dBm and SNR -12.8/-10.8 dB. At 1 MHz spacing, valid off-channel packets reported RSSI -102..-109 dBm and SNR -11.5..-15.8 dB. Wider on-channel controls were all -33 dBm, SNR +8.0..+8.8 dB. These are radio-reported values, not calibrated measurements of transmitted spurs or receiver rejection.</p> <p>The non-monotonic offset pattern means that increasing spacing alone cannot be assumed to remove this response. These fixed-frequency tests rule out a channel-hop shortcut as a necessary condition for the observed off-channel packets; they do not establish which physical component produces them.</p>"},{"location":"sf10_rollback_failure_validation/#a-traced-real-timeout-at-250-khz-spacing","title":"A traced real timeout at 250 kHz spacing","text":"<p>Fast/double-write RX, +22,500 us settling. One channel-3 probe timed out with TX rc=0, RX mode=1 and device errors=0. The trace contains 454 events, overflow 0. Trace adds 64 us IRQ polling; use it for ordering, not an unperturbed timing A/B comparison. Times below are relative to receiver expectation arming.</p> RX time (ms) Evidence 169.190 Frequency command for channel 3, 910.25 MHz 234.032 Leaves channel 3 for channel 0 298.869 Frequency command for channel 1, 909.75 MHz 330.030 PREAMBLE_DETECTED (0x0004) while on channel 1 363.632 Requested next hop is held by receive-in-progress guard 726.734 Guard clears the lingering preamble IRQ 726.826 Frequency command for channel 2 791.654 Finally commands intended channel 3 again 814.586 Channel-3 hop/settling completes <p>TX setup was 86,914 us and its transmit call 529,297 us. Host/firmware timing places TX RF start approximately 287..289 ms after RX arming and the end of its programmed preamble around 550 ms. This estimate is not a synchronized RF measurement, but the receiver's several-hundred-millisecond absence from the intended channel is much larger than USB timestamp uncertainty.</p> <p>The held channel-1 visit measured 427,395 us, versus normal idle four- channel cycle maximum 259,358 us. The guard timeout is consistent with <code>RadioLibWrapper::calcMaxPacketMillis</code>: <code>(32 + 8 + 4.25) * 8192 = 362496 us</code>, rounded to 363 ms. <code>CustomSX1262::isReceiving()</code> starts that timer when the guard first observes the preamble, here later than the diagnostic IRQ poll.</p> <p>Thus an off-channel preamble can monopolize the scanner long enough to miss the real channel. Do not simply remove or shorten this safety guard as a production fix: it also protects legitimate weak or long-preamble reception.</p>"},{"location":"sf10_rollback_failure_validation/#1-mhz-spacing-strict-results-versus-payload-delivery","title":"1 MHz spacing: strict results versus payload delivery","text":"<p>Three strict rollback cases (fast double, fast single, fully rolled back single/6 ms) each stopped at their first probe. All three actually decoded the intact channel-3 payload while programmed for channel 2: RX 911.5 MHz, TX 912.5 MHz, RF word at read 955777024. They are channel mismatches, not lost payloads. RSSI was -102/-101/-101 dBm; SNR -11.5/-11.5/-11.2 dB.</p> <p>An explicitly separate payload-delivery diagnostic then continued through such packets while retaining strict validity in raw evidence:</p> Mode Added delay Delivered before stop Strict same-channel Stop Mean switch Max idle cycle Fast, cached, double write 22.5 ms 3 of 4 probes 0 TX channel 0 timed out 557.721 us 259381 us RC/full RX/individual/byte-wise, single write, 6 ms TCXO 15.8 ms 2 of 3 probes 0 TX channel 1 timed out 7310.510 us 259643 us <p>Every delivered packet in these two runs arrived one programmed channel below its transmitter. Both runs had zero mode/cache/RX/device errors and actual switch-policy counts matched. Neither is a 400/400 pass, even under the relaxed delivery-only criterion. The true timeout in the fully rolled-back path also shows the problem is not limited to the accelerated RX restart or 0x8B cache. No traces were enabled for these two runs, so do not assign their individual timeouts the exact IRQ timeline from the earlier traced probe.</p>"},{"location":"sf10_rollback_failure_validation/#changes-and-verification","title":"Changes and verification","text":"<ul> <li>HIL-only rollback, explicit TCXO timing, selectable 250/1000 kHz spacing,   frequency-command trace events and fixed-frequency offset controls.</li> <li>Separate opt-in payload-delivery test; strict wire validity remains intact.   Host/device counters distinguish strict from off-channel deliveries;   settling sweeps reject delivery-only captures, including reused evidence.</li> <li>16 native profile tests and 46 HIL host tests passed. Receiver and nRF52   builds/uploads succeeded with normal verification. Receiver reported   94,844 bytes RAM / 366,777 bytes flash; nRF52 18,220 / 95,572 bytes.</li> <li><code>git diff --check</code> passed; unrelated pre-existing CRLF warnings only.</li> <li>Temporary PlatformIO overlay removed. Controllers stopped, both boards   rebooted idle with HIL firmware retained. No autonomous TX or restoration.</li> </ul> <p>Next useful isolation is the physical off-channel response (controlled RF attenuation or reversed radio roles), followed by safe acquisition/hold-policy experiments. More settling delay alone does not address the demonstrated false-hold mechanism. No claim of an identified silicon defect or verified production fix is made here.</p>"},{"location":"sf10_rollback_failure_validation/#evidence-provenance-sha-256","title":"Evidence provenance (SHA-256)","text":"<p>Raw JSON files below are under <code>tools/hil/</code>; prior captures were not rewritten. Matrix manifests include per-case paths and timing controls. All listed new experiments completed under their stated stopping policies without fixture or cleanup errors. Completed first-failure runs still have incomplete 400-packet levels by design.</p> Capture SHA-256 profile_switch_sf10_rollback_results.json <code>e87c504b3c89fbafe90c18fcd0ab37df34a6aeb51d95b5c69f58d60f70de185a</code> profile_stationary_sf10_offset_results.json <code>d3d87315513a70fc3f00cc7f17369043328f53ee3028d499087b21e767370ab7</code> profile_switch_sf10_rollback_fast_trace_results.json <code>8ac9db50f0f06eb7511d7d233957119618df62afdc7112dd83eb68d292fcd725</code> profile_switch_sf10_rollback_6ms_results.json <code>74e7bfeb23bc569a5786e2322b5e3b1753cba9f628e2969bf4f5c4296ca5817a</code> profile_switch_sf10_wide_rollback_results.json <code>d79096fbe3e15e0375457b487fd40be3418789e798a978efb79d8298c880eea2</code> profile_switch_sf10_wide_payload_results.json <code>1316a2c2f32a8c0773fc56587c4220ee8f6f6cdf4ab9b87e00fd361fc9395257</code> profile_switch_sf10_wide_legacy_payload_results.json <code>fcf2123270634e2f27800787e20b9b8b7ae63bcfb03e17d26a4a4f6f4e23d32f</code> profile_stationary_sf10_wide_offset_results.json <code>4c494a59fa793d274b0366185cfe3230b6c9fce7a57dfaa61f9f29c36465bbd3</code> <p>RX firmware images used, in chronological order:</p> Stage firmware.bin SHA-256 Initial nine-mode rollback <code>5f8dbf9c4584e0de94a7aebda5a20e961b644a880ecb6a34ab5871621958696f</code> Fixed 250 kHz offsets and traced timeout <code>cd839caa33c869dd448cc55e9c8b959e39d105f80a2ac4a8029393698b993fd3</code> Explicit 6 ms TCXO rollback <code>0ba044035c4986749c9ad4f50c702dc8c57e8e0fecf9d46fc11515cad5678166</code> Wider strict rollback <code>5fc919c80438635b4a96021b39fae2ada9e767508d7bb73854e4e108f0d4920f</code> Wider delivery diagnostics and fixed offsets; final installed <code>7b313a0f8f1eb04f6fc12197af5e9481ad43154b981ab7627e50167d2a97d8c2</code> <p>The 250 kHz tests used the prior nRF52 TX ZIP hash <code>7466625ef5e7bcc8f7dd16db2b843db29b4312a33b0d32bc0b1e1193d6aee03a</code>. All wider tests used the new selectable-spacing application:</p> <ul> <li>TX ZIP: <code>c474b7598a2c0b6c529ead897f3fc7aab8caf4b7581c73d7acac6ffae081377d</code></li> <li>TX HEX: <code>b400fc53c496f4a956f88ccee5cda83b5f6679b8e2b59bfcb4b8155ea9e1e5e9</code></li> </ul> <p>Build artifacts are generated and may be replaced by a subsequent build; hashes identify the images used, not a promise that every historical binary remains in <code>.pio/build</code>. Source starts from keymindCascade commit <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> with the existing dirty changes and these uncommitted HIL additions; this is not a clean-release comparison.</p>"},{"location":"sf125_settling_limits_validation/","title":"Descending SF10..SF5 / 125 kHz settling limits","text":"<p>Experiment started 2026-09-14. Stopped at the user's request to replace the Indicator transmitter with a V4. No 400/400 pass was found. The saved top-level manifest remains incomplete; the SF10 manifest contains all completed settings. Original evidence is not rewritten to make an interrupted experiment look complete.</p>"},{"location":"sf125_settling_limits_validation/#results-at-user-requested-stop","title":"Results at user-requested stop","text":"<p>94 SF10/125 settings completed: every added delay from 0 through 9,300 us in 100 us increments. Each stopped on its first RF miss; none reached 400/400. The best individual setting was +1,000 us: 25 valid packets, then packet 26 failed. No lower SF was reached in this descending sweep. No result is claimed for SF10 delays above 9,300 us or for SF9..SF5 in this run.</p> <p>Across these completed settings: 641 probes, 547 valid and 94 failed. Because each setting ends at its first miss, these totals are not an unbiased packet error-rate measurement and do not establish a reliable lower/upper delay limit.</p> <p>For the 547 valid receptions, reported SNR averaged +8.311 dB, minimum +7.5 dB and maximum +9.5 dB. RSSI averaged -40.547 dBm, range -42 to -39 dBm. These are conditional on successful reception; no SNR is inferred for missing packets.</p> <p>24,055 retunes averaged 456.620 us, weighted by hop count and excluding the intentional settling delay. Reported retune failures, RX-mode errors and cache errors were all zero. Four RX errors were reported, one each at +1,100, +5,900, +6,700 and +6,900 us. These counters do not identify the transmitter as the cause. At +9,300 us, the unheld four-channel cycle averaged 206.134 ms (maximum 206.157 ms), versus a 262.144 ms programmed preamble; this nominal time margin still did not produce an all-pass setting.</p> <p>Controllers and collector were stopped, and both boards were rebooted to idle HIL. Follow-up polling is paused. Subsequent <code>info</code> checks returned ready on both boards, with XIAO gain register 0x94 and Indicator 0x96. Test firmware was retained; no original firmware was restored. Replacement-board testing has not started.</p> <p>Saved manifest SHA-256 at stop:</p> <ul> <li>Top level: <code>9cbf315704816be4d3cf7977e954e64a2033155e654cd7108919e6a17a5f8f8a</code></li> <li>SF10: <code>509f632de1a463d4f5f84c055a1570468c5752685d596f4b445aa7d7c339189d</code></li> </ul>"},{"location":"sf125_settling_limits_validation/#requested-method","title":"Requested method","text":"<p>XIAO ESP32-S3/WIO SX1262 COM31 RX, SenseCAP Indicator ESP32-S3 COM28 TX, user-separated positions, XIAO boosted gain off (actual register 0x94), Indicator gain unchanged at 0x96. Four centers 909.500/909.750/910.000/910.250 MHz; bandwidth 125 kHz, CR4/5, 5.1-symbol visits, 32 programmed preamble symbols, 16-byte synthetic packets at -9 dBm. Warm fast RX, buffered 8 MHz SPI and unchanged-modulation cache enabled. No extra IRQ polling/tracing.</p> <p>Start SF10 and descend one SF at a time through SF5. For each SF, test added post-BUSY delay in 100 us increments starting at zero. Every failed setting stops on its first invalid reception/timeout; a pass requires 100/100 on each of four channels. Latest user instruction: stop the entire sweep at the first 400/400 pass, without continuing to find an upper limit or a lower SF. Without any pass, continue to the ceiling, then lower SF. Fixture errors abort the entire experiment. No failed RF probe is retransmitted.</p> <p>This searches for a sampled all-pass setting, not proof of monotonic delay behavior, an upper delay limit, or zero PER. The RX modem remains active during the extra delay; the independent 5.1-symbol visit starts afterward. Thus extra settling is also extra RX occupancy, not a pre-SetRx blanking interval.</p> SF Visit Last 100 us delay step Programmed preamble 10 41,780 us 23,300 us 262,144 us 9 20,890 us 11,400 us 131,072 us 8 10,445 us 5,400 us 65,536 us 7 5,223 us 2,500 us 32,768 us 6 2,612 us 1,000 us 16,384 us 5 1,306 us 200 us 8,192 us <p>Budget: <code>preamble_us / 4 - dwell_us - 453</code>, using the nominal retune cost. Actual cycle means/maxima are recorded and may exceed that nominal budget. The randomized arrival pause now includes added settling when estimating two scan cycles; earlier saved captures retain their original distributions.</p> <p>The stop policy changed after SF10 delays 0..5,600 us had all failed. The old supervisors were stopped while the active 5,600 us collector finished normally. Original captures are preserved. A fresh first-pass manifest reuses completed, configuration-validated raw captures with their SHA-256 hashes, then resumes at 5,700 us; no completed setting is repeated. The earlier top-level manifest is incomplete because its upper-limit policy was superseded, not due to an RF or fixture fault.</p>"},{"location":"sf125_settling_limits_validation/#build-and-initial-checks","title":"Build and initial checks","text":"<p>Both HIL targets compiled and verified uploads succeeded. The selected 53 host/native tests passed: 36 host collectors, seven profile native, four SX1262, five radio and one receive-mode test. After the stop-rule change, all 39 host collector tests passed, including new whole-sweep first-pass stopping and matching, hash-preserving capture reuse.</p> <p>Actually loaded firmware SHA-256:</p> <ul> <li>XIAO: <code>89faa3bbc5eade5e632e0c720c75be0ba9105e595b1384de74a00e09c0b60a24</code></li> <li>Indicator: <code>fb06c52e138e5cd65fff1393e3f1208230b06977e5f824852086d4c80c89845c</code></li> </ul> <p>A one-second RX-only SF10/+23,300 us smoke check recorded 15 hops with minimum delay 23,300 us, minimum post-delay dwell 41,782 us, and zero retune/RX-mode/cache errors. Its two clean cycles averaged 262,125 us, maximum 262,127 us: only a tiny margin against the 262,144 us preamble, not a robust worst-case bound. No RF probe was transmitted during that check.</p> <p>Base <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> on <code>keymindCascade</code>, plus local changes. RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17.</p> <pre><code>python tools/hil/profile_switch_sf_limits.py --receiver COM31 --sender COM28 --output tools/hil/profile_switch_sf125_limits_results.json\n</code></pre> <p>Updated run:</p> <pre><code>python tools/hil/profile_switch_sf_limits.py --receiver COM31 --sender COM28 --output tools/hil/profile_switch_sf125_first_pass_results.json --stop-on-first-pass --reuse-prefix tools/hil/profile_switch_sf125_limits_results.json\n</code></pre> <p>The controller reboots to idle HIL after each per-SF child completes or fails; test firmware is to remain installed, per user request. Original private flash backups are retained. RAK4631, Indicator RP2040 and unrelated S3 soak work are not part of this experiment. No commit/push requested. Temporary build overlay has been removed.</p>"},{"location":"sf5_250_dwell_validation/","title":"SF5 / 250 kHz: four-channel dwell sweep","text":"<p>Measured 2026-09-14. No tested dwell from 4.1 through 8.1 chirps passed. Each setting stopped at its first invalid reception or timeout; the sweep stopped at the requested 8.1 limit. None reached 100 packets per channel.</p>"},{"location":"sf5_250_dwell_validation/#setup","title":"Setup","text":"<ul> <li>XIAO ESP32-S3/WIO SX1262, COM31, receiver; SenseCAP Indicator ESP32-S3,   COM28, reference TX. Radios remain in the user's separated positions.</li> <li>XIAO boosted RX off, verified actual gain register 0x94 before tests   and in every final scan status. Indicator 0x96, unchanged as transmitter.</li> <li>Four centers: 909.500, 909.750, 910.000, 910.250 MHz. SF5, bandwidth 250 kHz,   CR4/5, 32 programmed preamble symbols, 16 synthetic bytes, -9 dBm.</li> <li>Production warm fast RX and unchanged-modulation cache enabled, buffered   8 MHz SPI. Existing packet guards and initialization unchanged.</li> <li>Requested grid 4.1 to 8.1 in 0.5-symbol steps. Each setting starts fresh,   shuffles channel order with seed 606125 and varies arrival timing without   synchronization to RX visits. Both boards reboot between settings.</li> <li>100 packets/channel maximum; stop that setting on first failure, then move   to next dwell. No retransmission of a failed probe. Stop the entire sweep   on first complete 400/400 result or after 8.1; abort on fixture errors.</li> <li>Extra IRQ polling and packet traces disabled to avoid adding diagnostic   overhead to sub-millisecond visits. RX mode, modem software cache, gain,   SPI command counts, timing and packet identity checks remain enabled.</li> </ul> <pre><code>python tools/hil/profile_switch_dwell.py --receiver COM31 --sender COM28 --output tools/hil/sf5_250_dwell_normal_results.json\n</code></pre>"},{"location":"sf5_250_dwell_validation/#results","title":"Results","text":"<p>\"Received\" means correct sequence, payload and reported receive channel. Each row is a first-failure sample, not a 100-packet/channel PER measurement.</p> Chirps Requested dwell Received / attempted First failure Mean retune 4.1 525 us 1 / 2 channel mismatch 458.122 us 4.6 589 us 0 / 1 timeout 450.787 us 5.1 653 us 0 / 1 timeout 450.667 us 5.6 717 us 0 / 1 timeout 452.270 us 6.1 781 us 2 / 3 timeout 452.991 us 6.6 845 us 0 / 1 timeout 451.082 us 7.1 909 us 0 / 1 timeout 453.796 us 7.6 973 us 0 / 1 timeout 453.568 us 8.1 1,037 us 4 / 5 timeout 457.886 us <p>All 16 requested transmissions returned success. Seven met the full receive checks. Of nine failures, one returned a matching synthetic sequence on a different reported receive channel and eight timed out. Every timeout run also recorded one <code>rx_errors</code> increment. These are receive/read/decode errors, not retune hardware faults; without an IRQ trace their exact cause and association with the expected probe cannot be reconstructed.</p> <p>All 64,507 timed hops passed RX-mode/software-cache checks with zero retune failures. Weighted mean switch time was 452.739 us, excluding listening dwell and full application scheduling. Each hop programmed a frequency. Modulation rewrites occurred only when the prior context needed re-establishing, rather than on every frequency-only hop.</p> <p>The 4.1 second probe was transmitted for channel 2 (910.000 MHz), but its sequence was returned while the receiver reported channel 3 (910.250 MHz), 16 bytes, RSSI -66 dBm, SNR 0.5 dB. It therefore failed the channel check; the saved <code>valid=false</code> also does not independently certify all payload bytes. No synchronized RF/frequency-register capture was taken, so this is evidence of wrong-channel reporting/reception, not proof of its physical mechanism. Successful correct-channel probes read -42 to -41 dBm, SNR 7.8\u20138.8 dB.</p>"},{"location":"sf5_250_dwell_validation/#interpretation","title":"Interpretation","text":"<p>SF5/250 did not establish a solution to the close-range problem, and increasing dwell alone did not produce a clean four-channel result. The wrong-channel sequence and receive errors prevent interpreting this as a pure minimum-dwell/acquisition test. It is not evidence that 8.1 is a reliable setting merely because four probes passed before its miss.</p> <p>There is also a timing tradeoff: a symbol lasts 128 us, so 32 programmed preamble symbols occupy only 4.096 ms. A ~453 us retune costs about 3.54 symbols. At 4.1, four nominal dwells plus four such retunes consume about 3.91 ms before other loop costs; at 8.1 they consume about 5.96 ms. Longer visits give acquisition more uninterrupted time but increase the time spent away from each channel. This arithmetic motivates testing a longer preamble or fewer channels separately; it does not prove the cause of any particular failure. No such follow-up was transmitted after the 8.1 limit.</p> <p>Unlike the earlier separated SF6 run, this changes SF, bandwidth, absolute preamble duration and diagnostic polling. The RF settings also leave channel spacing unchanged at 250 kHz. It is not a matched comparison isolating receiver sensitivity or the modulation cache.</p>"},{"location":"sf5_250_dwell_validation/#provenance-and-handoff","title":"Provenance and handoff","text":"<p>Base <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> on <code>keymindCascade</code>, plus uncommitted production cache and HIL changes. RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>; Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL builds and verified uploads succeeded. All 39 selected host/native tests passed, including bandwidth/dwell calculation and bounded sweep stopping. No commit or push was requested for this work.</p> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>6ba7b4c6785ac11eb8a4ecd2f1148f4f55ce866c1cb172776757fe0a95047da9</code></li> <li>Indicator: <code>3672ca330d4b2d3e8efa39edf2dbc3b27b8804dbb9a98f29267c85c41972a028</code></li> </ul> <p>Raw manifest references all nine per-dwell captures. SHA-256 values (all files under <code>tools/hil</code>):</p> File suffix after <code>sf5_250_dwell_normal_results</code> SHA-256 <code>.json</code> <code>aaf00ef8531cb2c5c7e4dfb78d3b8b03ce61d9afe8323fb33e70be09656adf54</code> <code>_4p1.json</code> <code>a9c6baf0bece79c9b9c96bfa97e3cd9932e0c04fc76b43f61ed350512306341a</code> <code>_4p6.json</code> <code>63863b55108374011afbe555bfeb97034b010e194cdad83a212d5d286d1992fe</code> <code>_5p1.json</code> <code>ff1d2927365e3634984bc0b843a09f2934c5dcac49b60b862ff4db030e0f7e74</code> <code>_5p6.json</code> <code>33c91687d0b61dd83e2a08d8358b43f21fa27f9e80f9503feedeb657453a7efd</code> <code>_6p1.json</code> <code>5baa8d1bfcf0ccc947c92d563dc555802ac599ce1e8d260a623964936a99da4e</code> <code>_6p6.json</code> <code>90f6b4d7785add771e30da7dfa78672fd75ad13d8a5965c21ec1a37e15d8dabb</code> <code>_7p1.json</code> <code>eb99afd932a5579c765f8a6c0a18db4bacc317829b0654d11fbf2f569c3a8618</code> <code>_7p6.json</code> <code>bdb88da82437fa6e01ad90ab927d364b4d67aaadbac7597c3aacb9799b053211</code> <code>_8p1.json</code> <code>404ee179e4c10333bd6fddae9f0faa9da81f6193dcb5fff6d9bd37a466c319a3</code> <p>Both boards were rebooted after the sweep and answered ready with correct HIL capabilities; XIAO gain remained 0x94. Per user request, HIL firmware is left installed, idle with no autonomous test transmissions. Private original flash backups remain available. The RAK4631, Indicator RP2040 and unrelated S3 soak work were not modified. The temporary build overlay was removed.</p>"},{"location":"sf6_125_settling_validation/","title":"SF6/125 four-channel post-switch settling sweep","text":"<p>Measured 2026-09-14. No setting from +0.0 through +1.0 ms passed 400/400. The requested delay was applied after BUSY went low without consuming the subsequent 5.1-symbol listening visit. Each run stopped on its first miss; the sweep would have stopped at the first 400/400 pass, but reached its nominal timing limit instead. No RF probes were sent beyond that limit.</p>"},{"location":"sf6_125_settling_validation/#method-and-timing-budget","title":"Method and timing budget","text":"<ul> <li>XIAO ESP32-S3/WIO SX1262 COM31 receiver, SenseCAP Indicator ESP32-S3 COM28   transmitter, unchanged user-separated positions. XIAO boosted gain off,   actual register 0x94 verified; Indicator 0x96. Original backups retained.</li> <li>SF6 / 125 kHz / CR4/5, four centers 909.500/909.750/910.000/910.250 MHz,   32-symbol preamble, 16-byte synthetic packets, -9 dBm.</li> <li>Warm fast RX, buffered 8 MHz SPI, unchanged-modulation reuse enabled.   Same XIAO image for every delay; unchanged Indicator reference image.</li> <li>100 packets/channel requested, balanced shuffled channel order (seed 606125),   varied unsynchronized arrival timing. Both HIL boards reboot between delays.</li> <li>No extra IRQ polling or packet traces; ordinary ownership/preamble guards   remain enabled. No RF retries, shorter channel count or altered preamble.</li> </ul> <p>At SF6/125, a symbol is 512 us. The requested listening visit rounds up to ceil(5.1 * 512) = 2,612 us; 32 programmed preamble symbols last 16,384 us. Using the user's nominal 453 us retune, the extra per-hop budget is:</p> <p><code>16,384 / 4 - 2,612 - 453 = 1,031 us</code></p> <p>Thus the 100 us grid runs from 0 through 1,000 us; 1,100 us would exceed the nominal full-sweep calculation. Sync/header time is not spent as extra scan budget. This is not a worst-case scheduling or acquisition guarantee.</p> <p>The delay is HIL-only: after a successful guarded production retune and BUSY-low observation, the CPU waits without SPI/IRQ operations, then starts a separate 2,612 us listening clock. The SX1262 is already receiving throughout that delay and may acquire a packet. This tests extra RX occupancy/settling, not a pre-SetRx delay or a period with RX disabled. Ordinary RX restarts after processing packets reset the visit clock without another channel delay. Zero delay preserves the previous production RX-start clock.</p> <p>An initial receive-only, 300 ms smoke check at +1,000 us measured 74 hops, minimum applied delay 1,000 us and minimum subsequent dwell 2,612 us. Its 17 clean full cycles averaged 16,235.941 us, maximum 16,260 us. No RF probe was transmitted in this check. The longer packet experiments below capture more scheduling variability, including host command handling.</p>"},{"location":"sf6_125_settling_validation/#results","title":"Results","text":"<p>All times in the last two columns are measured means, not target values. \"Received\" is successes before the next probe timed out; every row ended in one timeout. These first-failure samples do not estimate comparable PERs.</p> Added delay Received before miss Switch + delay Clean full cycle 0.0 ms 44 0.452381 ms 12.256886 ms 0.1 ms 4 0.548387 ms 12.669976 ms 0.2 ms 34 0.650424 ms 13.074105 ms 0.3 ms 53 0.753410 ms 13.485859 ms 0.4 ms 47 0.850830 ms 13.868454 ms 0.5 ms 66 0.952289 ms 14.273736 ms 0.6 ms 14 1.050333 ms 14.671156 ms 0.7 ms 21 1.151351 ms 15.076094 ms 0.8 ms 63 1.255113 ms 15.482272 ms 0.9 ms 19 1.352843 ms 15.880361 ms 1.0 ms 25 1.452750 ms 16.283488 ms <p>All 401 transmissions returned success: 390 valid receptions and 11 timeouts, spread across the eleven independently stopped settings. None completed 100/100 on each channel. All 52,609 timed hops passed RX-mode and software-cache checks, with one observed frequency write per hop and zero retune failures. Each positive-delay hop waited at least the requested time; every run's minimum subsequent idle dwell was 2,612 us. No receive-error counter increment or device error was reported. Successful RSSI was -42 to -40 dBm and SNR 9.5\u201311.8 dB.</p> <p><code>switch</code> measures production retune entry through BUSY-low observation; <code>settling</code> measures the following wait, including timer overhead; <code>switch_and_settle</code> combines them. Even zero requested delay records roughly 1\u20132 us of timer/bookkeeping overhead in the combined boundary. Listening dwell and full application scheduling are not included in retune time.</p> <p><code>idle_cycle</code> measures consecutive channel-0 return times, excluding initial cycles and cycles containing packet/guard-held visits. It still includes loop and USB work encountered during otherwise unheld visits. At +1.0 ms its mean is 100.512 us inside the preamble budget, but its maximum was 17.475 ms, exceeding 16.384 ms. At +0.9 ms the observed maximum was 16.153 ms. Therefore the last grid point fits only the nominal/mean calculation, not every observed full cycle. Legitimate packet holds can extend scan timing further.</p>"},{"location":"sf6_125_settling_validation/#conclusion-and-limits","title":"Conclusion and limits","text":"<p>Extra post-switch settling through the available timing budget did not establish loss-free four-channel reception. The 66 successes at +0.5 ms are not evidence that it is an optimum; the results are small, first-failure samples with different uncontrolled RF arrival phases. The added delay also extends total RX occupancy, so any improvement would not isolate analog settling from longer acquisition time.</p> <p>Every failure here was a timeout without a reported receive/decode error. Without an IRQ trace or synchronized independent RF capture, that does not prove absence of a preamble/header indication or identify the precise cause. It does not justify changing production packet guards or adding a permanent settling penalty. No production default was changed by this experiment.</p>"},{"location":"sf6_125_settling_validation/#reproduction-provenance-and-handoff","title":"Reproduction, provenance and handoff","text":"<pre><code>python tools/hil/profile_switch_settling.py --receiver COM31 --sender COM28 --output tools/hil/sf6_125_settling_normal_results.json\n</code></pre> <p>See harness instructions. Base <code>0e5955f889788a4317863e731b38ffe09e3d5441</code> on <code>keymindCascade</code> plus local changes. RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL targets compiled; only XIAO needed an upload for the new receiver-side delay. All 45 selected host/native tests passed, including delay/visit separation, packet restart, timer wraparound, clean-cycle accounting, bounded grid and first-pass stop.</p> <p>Actually loaded firmware SHA-256:</p> <ul> <li>XIAO: <code>a0dbc113dcb297be34e22c0bc058db71c4108659e1e289679ecdbfc5c0009f8e</code></li> <li>Indicator, unchanged from SF5/250 sweep:   <code>3672ca330d4b2d3e8efa39edf2dbc3b27b8804dbb9a98f29267c85c41972a028</code></li> </ul> <p>Raw manifest and per-delay captures are preserved byte-for-byte. SHA-256, file suffixes after <code>tools/hil/sf6_125_settling_normal_results</code>:</p> Suffix SHA-256 <code>.json</code> <code>41a20c3d5b809cd225772980fbe0d305c14391659f10d685bf78f8bdf326e61c</code> <code>_0us.json</code> <code>47a73a35ed72ebc61b88bfe315e86bf7e15ba1d2d93e68ce92ce681e1ef73cef</code> <code>_100us.json</code> <code>b585ea01f605bc876da86ba2a35fbe6e7cc6543eb5e827ba190c51dca10dcb85</code> <code>_200us.json</code> <code>6ce378cd079eefae8450c7f5672281095b9b99e28e0c7920f024a4396606bb40</code> <code>_300us.json</code> <code>d93e7a258dddb6731c030e395e09c3f06b4d5988638cc85dc5cd0745256c6202</code> <code>_400us.json</code> <code>56bfe4cb7cbab2a660a232a2bf85b9bb87221ffade7c9bbce6d1116e6c30fcbf</code> <code>_500us.json</code> <code>fffb6c33a506f537913084fc4f5cc9f8009a4f0f61e4f290dd81a7409f53d1bd</code> <code>_600us.json</code> <code>7bc6dd41f0079f37bdbf77fc48c4113e26589bcce704850b106c33d057e34659</code> <code>_700us.json</code> <code>54170f5b63bbe8ffa231852bf892ea55d8579c33631775f29fb7c127197afb2a</code> <code>_800us.json</code> <code>f7c53375b29764b4369b84e8ac3244aa37e385c8738a9dfd7f3257d85a64a705</code> <code>_900us.json</code> <code>56bc3691f2046cafcf2115b2f6b7bd164e9c9039733ea51028db292deea10230</code> <code>_1000us.json</code> <code>f708af37caee8f689f2436567382458d63aba1269e8306ac6e4d0079677b9115</code> <p>Both boards rebooted to idle HIL after testing and answered ready. XIAO gain remained 0x94 and settling policy was returned to zero. Test firmware stays installed, per user request; no restore, commit or push was performed this turn. RAK4631, Indicator RP2040 and unrelated S3 soak work were untouched. The temporary build overlay was removed; no autonomous test TX remains.</p>"},{"location":"sf6_5p1_trace_validation/","title":"SF6 / 125 kHz: four channels at 5.1 chirps","text":"<p>Measured 2026-09-14. Seven packets received, then packet 8 missed. The run stopped at that first miss. No RF retry, other dwell, or higher/lower channel count was tested. The target of 100 packets per channel was not reached.</p> <p>Follow-up: SF8/125 at the same 5.1-chirp dwell missed on packet 13 and captured an off-channel preamble hold. That differs from the absence of observed preamble in this SF6 failure.</p>"},{"location":"sf6_5p1_trace_validation/#setup","title":"Setup","text":"<ul> <li>XIAO ESP32-S3 + WIO SX1262 scanner, COM31.</li> <li>SenseCAP Indicator ESP32-S3 reference transmitter, COM28.</li> <li>Four centers: 909.500, 909.750, 910.000, 910.250 MHz.</li> <li>SF6 / 125 kHz / CR4/5, 32-symbol programmed TX preamble.</li> <li>User-corrected dwell: 5.1 symbols, ceil(5.1 * 512) = 2,612 us.</li> <li>Same warm production fast retune, buffered 8 MHz SPI, packet guards.</li> <li>16-byte synthetic payloads at -9 dBm; balanced randomized channel order,   seed 606125; varied arrival timing, not synchronized to scan phase.</li> <li>IRQ changes, IRQ clears, hops and first guard deferrals buffered in RAM.   Additional read-only IRQ polling at nominal 64 us intervals while armed.   No per-event serial printing during capture. Trace read after each result.</li> </ul> <pre><code>python tools/hil/profile_switch_channels.py --receiver COM31 --sender COM28 --output tools/hil/sf6_125_5p1_trace_results.json --samples 100 --preamble 32 --max-channels 4 --dwell-symbols 5.1 --trace\n</code></pre>"},{"location":"sf6_5p1_trace_validation/#results-and-what-the-trace-establishes","title":"Results and what the trace establishes","text":"<p>Probes 1\u20137 succeeded on channels 3, 2, 1, 0, 2, 3, 1. Probe 8, sequence <code>944962150</code>, missed on channel 0 (909.500 MHz). Thus channel 0 had already received a valid probe; this was not a channel that never worked at all. Successful packets had RSSI -42 to -40 dBm and SNR 9.5 to 10.8 dB.</p> <p>The failed probe has a complete, non-overflowed 3,160-event trace:</p> <ul> <li>Expectation armed on channel 3 without selecting the expected channel.</li> <li>3,158 completed hops during the bounded 10-second confirmation interval.</li> <li>No observed nonzero IRQ bits: no preamble, header, RxDone or CRC event.</li> <li>No guard-held visit on any channel during that expectation.</li> <li>Receiver timeout at 10,000,369 us, with RX mode and zero device errors.</li> <li>Reference TX returned success. All USB sequence acknowledgements matched;   no stale replies, missing acknowledgements or cached transport recovery.</li> </ul> <p>The scanner was not stuck on the wrong channel by a false preamble. It also did not acquire a header and then fail a CRC check. The evidence locates the failure before observed preamble acquisition, not at payload decoding. It does not prove why acquisition failed: a short-visit/arrival-phase issue remains a candidate, as does an unobserved RF/reference issue. There was no independent RF capture, and the two MCU clocks were not synchronized.</p>"},{"location":"sf6_5p1_trace_validation/#actual-timing-during-the-failed-expectation","title":"Actual timing during the failed expectation","text":"Measurement Minimum Mean Maximum Receive dwell, 3,158 hops 2,613 us 2,628.706 us 2,646 us Retune, trace hop rows 526 us 538.700 us 630 us Channel 0 revisit interval, 789 cycles 12,643 us 12,666.829 us 12,705 us <p>The repeatable scan timing rules out a large software scheduling stall in the failed capture. The 32 programmed symbols occupy 16.384 ms, longer than that idle scan cycle; nevertheless, revisiting within the preamble did not ensure successful acquisition during these short individual visits.</p>"},{"location":"sf6_5p1_trace_validation/#successful-acquisition-traces","title":"Successful acquisition traces","text":"<p>Times below are relative to the logged hop completion onto the eventual receive channel, not a precisely captured RF edge or hardware RX-start edge. The trace observed the following progression for every successful probe: PreambleDetected (0x0004), HeaderValid (0x0014), RxDone (0x0016), consumption.</p> Probe Channel First observed preamble after hop RxDone after hop 1 3 1,838 us 32,982 us 2 2 1,836 us 35,470 us 3 1 1,844 us 35,151 us 4 0 2,332 us 37,329 us 5 2 1,847 us 35,532 us 6 3 1,831 us 30,731 us 7 1 1,329 us 32,567 us <p>After detecting preamble, the production guard kept those visits on-channel until reception completed. The failed probe never reached that observed state. This is not evidence that 5.1 symbols always suffice, nor does 7/8 estimate a stable packet-error rate or establish a channel-capacity limit.</p>"},{"location":"sf6_5p1_trace_validation/#instrumentation-and-reporting-caveats","title":"Instrumentation and reporting caveats","text":"<p>The failed capture made 115,783 diagnostic IRQ polls, costing a total 2,821,617 us (about 24.4 us each; maximum 61 us). These reads are not free: they alter loop load, although actual dwell and revisit timing were measured. This is not a matched A/B against the earlier untraced 4.8-symbol run, so seven successes versus two cannot be attributed solely to the extra dwell.</p> <p>The run used <code>channel_trace: 1</code>. During analysis, a reporting bug was found in the newly added <code>held_dwell</code> aggregate: production <code>startRecv()</code> resets the visit timestamp after reading a packet. That aggregate therefore omitted the preceding held reception time. Do not use its 2.709 ms mean as total held occupancy. The timestamped IRQ/hop trace above is the evidence for the actual 30.7\u201337.3 ms hop-to-RxDone intervals. The failed capture had no RX restart, so its dwell rows are unaffected.</p> <p>The source now keeps a separate channel-occupancy timestamp (<code>channel_trace: 2</code>, <code>trace_format: 2</code>). Both HIL targets compiled with this reporting-only correction; it was not flashed or RF-tested, and the saved raw result was not rewritten. Scheduler, packet guard and radio commands were not changed by that correction. Regression coverage includes passive SPI observation, bounded/frozen capture, occupancy accounting, page identity, requested dwell, and stopping at the first miss.</p>"},{"location":"sf6_5p1_trace_validation/#provenance-and-device-handoff","title":"Provenance and device handoff","text":"<ul> <li>Unmodified raw result and all eight traces</li> <li>Harness and trace format</li> <li>Earlier 4.8-symbol result</li> </ul> <p>Raw result SHA-256: <code>7caa16483b7b0000b388a1906395fe3d381bd0e40de73f48cd5c876d96deab3b</code>.</p> <p>Actually tested firmware SHA-256 (trace version 1, before reporting fix):</p> <ul> <li>XIAO: <code>35c201f367b0aaa693be03542a4c115024d1a70a2be2fbdbef2c94da5a6053ae</code></li> <li>Indicator: <code>8a25d84fc99f6aeaf8318bf4533767e16a9afc0de51394fce27d3a610c63b352</code></li> </ul> <p>Base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus local changes; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. No normal production firmware change this turn.</p> <p>Fresh full 8 MiB snapshots were saved and digest-verified before flashing:</p> <ul> <li>XIAO: <code>35aa2deeb8a8145bc54435c9f87b3db1c65f320f2568ee0b489305db1a6330c2</code></li> <li>Indicator: <code>dba59cde1df3c69dd2e5995950315951f75cd43886b21be8b14e261ec4b57309</code></li> </ul> <p>Both snapshots were restored afterward, separately verified against the full flash, and hardware-reset. Snapshots remain in the private current-user backup directory. The RAK4631 and Indicator RP2040 were not modified; the XIAO soak logger was not restarted. Changes were initially handed off locally before publication.</p>"},{"location":"sf6_channel_scan_validation/","title":"SF6 / 125 kHz channel-count test","text":"<p>Measured 2026-09-13. The run stopped on the third packet at the initial four channels: two arrived intact, then the receiver timed out. No five-channel test, lower-channel test, retry or retransmission was performed. Consequently this run does not establish a maximum channel count with 100% reception.</p> <p>Follow-up: four channels at 5.1 symbols with an IRQ trace stopped at packet 8 and observed no preamble acquisition during the miss.</p>"},{"location":"sf6_channel_scan_validation/#requested-setup","title":"Requested setup","text":"<ul> <li>Receiver: XIAO ESP32-S3 + WIO SX1262, COM31.</li> <li>Reference transmitter: SenseCAP Indicator ESP32-S3 LoRa processor, COM28.</li> <li>SF6 / 125 kHz / CR4/5, fixed 32-symbol programmed preamble.</li> <li>4.8-symbol receive visits: 2,457.6 us, rounded up to 2,458 us.</li> <li>Buffered 8 MHz SPI and the production fast retune/packet-ownership guards.</li> <li>Start at four channels and add one only after 100/100 packets on every channel.</li> <li>Stop at the first missing/corrupt packet; USB/reference/scanner faults are   reported separately as inconclusive fixture errors.</li> <li>16-byte synthetic payloads at -9 dBm. No identity/channel secrets transmitted.</li> <li>Four channel centers: 909.500, 909.750, 910.000 and 910.250 MHz.</li> <li>Balanced randomized channel order, seed 606125; varied arrival timing across   approximately two idle scan cycles. Arming an expectation does not select   the receiver's channel or reset its visit clock.</li> </ul> <p>The 100-packet-per-channel target was not reached: the explicit first-miss stop rule ended the run during its first shuffled pass.</p>"},{"location":"sf6_channel_scan_validation/#observations","title":"Observations","text":"Probe Channel center Outcome 1 910.250 MHz Valid 16 bytes, RSSI -40 dBm, SNR 10.8 dB 2 910.000 MHz Valid 16 bytes, RSSI -40 dBm, SNR 11.0 dB 3 909.750 MHz Receiver timeout; transmitter returned success <p>All three transmit acknowledgements and receiver reports matched their sequence IDs, with no missing/replayed/stale USB replies. On the miss, the receiver reported RX mode and zero device errors. The scanner recorded zero retune failures, RX-mode errors, modulation-cache errors or CRC/read errors. No probe was sent on 909.500 MHz before the stop condition.</p> Timing Minimum Mean Maximum Production retune to BUSY low, 3,467 hops 504 us 514.652 us 726 us Idle receive dwell, 3,463 visits 2,458 us 2,462.480 us 2,468 us <p>These samples include scanning during the bounded 10-second wait that confirmed the missing packet. There were 2,451 deferred attempts while production preamble/header/packet ownership held a visit; this is not a count of packets or failed retunes. Held visits are excluded from idle-dwell timing. All 3,467 successful retunes used the production fast-RX path.</p> <p>The means imply about 11.91 ms per four-channel idle cycle, excluding packet-held visits and small loop bookkeeping. Fast retuning alone did not produce 100% reception in this setup. This short stop-on-first-miss experiment does not identify the exact acquisition/phase cause, estimate a stable PER, prove that three channels would pass, or establish a universal board limit.</p>"},{"location":"sf6_channel_scan_validation/#implementation-and-reproduction","title":"Implementation and reproduction","text":"<p>This is a lab-only N-channel scheduler over the real <code>tuneProfile()</code> path. It reuses the two production profile slots as staging slots for the next frequency. Normal MeshCore <code>radio2</code> remains two-profile. The explicit test schedule intentionally does not use the normal two-profile automatic-preamble fit calculation or generic 6 ms switch / 4 ms loop allowances. It keeps the existing packet-protection guards and measures real dwell/retune overhead.</p> <pre><code>python tools/hil/profile_switch_channels.py --receiver COM31 --sender COM28 --output results.json --samples 100 --preamble 32\n</code></pre> <p>The controller has regression tests for balanced samples, starting at four, incrementing only after a perfect level, stopping without another TX, and distinguishing fixture failure from an RF miss. A separate RX-only 0.5-second setup check verified the scan timing before any capacity-test packets were sent. The capacity run itself was not repeated.</p> <ul> <li>Raw result, including the failing probe</li> <li>Host controller</li> <li>Firmware scheduler</li> <li>Harness instructions</li> <li>Earlier USB and fast-switch qualification</li> </ul> <p>Build provenance: base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus the local fast-switch and HIL changes; Arduino ESP32 2.0.17, Espressif32 6.11.0, RadioLib 7.7.1 pinned at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>. This is the extended V8 harness with <code>channel_sweep: 1</code>; its binaries differ from the earlier two-profile V8 measurements, so timings should not be treated as a same-image A/B.</p> <p>Firmware SHA-256:</p> <ul> <li>XIAO: <code>b0a6dd216be8a638fe088219801290d4632afcf63048f8597037650d68cd2301</code></li> <li>Indicator: <code>f0aa43a46e5e59ebf4768a255bd8c31d7a72c0038e11173314f78908b725786d</code></li> </ul>"},{"location":"sf6_channel_scan_validation/#device-handoff","title":"Device handoff","text":"<p>After the first-miss stop, both original 8 MiB flash snapshots were restored. Separate full-flash verification matched each backup's digest, followed by hardware reset. The private backups remain in the current-user backup directory. The Indicator RP2040 and RAK4631 were not modified. The interrupted XIAO soak logger remains stopped, and the temporary PlatformIO HIL overlay was removed. Implementation, tests and reports were initially handed off locally before publication.</p>"},{"location":"sf8_5p1_trace_validation/","title":"SF8 / 125 kHz: four-channel comparison at 5.1 chirps","text":"<p>Measured 2026-09-14. 12 packets received, then packet 13 missed. The first three balanced rounds passed (3/3 on every channel); the next probe on channel 3 failed. The run stopped at that miss. The target of 100 packets per channel was not reached. No RF retry or other channel count was tested.</p>"},{"location":"sf8_5p1_trace_validation/#setup-and-comparison","title":"Setup and comparison","text":"<p>Same XIAO ESP32-S3 + WIO SX1262 scanner (COM31) and SenseCAP Indicator ESP32-S3 reference transmitter (COM28). Four centers: 909.500, 909.750, 910.000 and 910.250 MHz. CR4/5, 32-symbol programmed preamble, 16-byte synthetic packets, -9 dBm, warm production fast RX and buffered 8 MHz SPI. Same production packet guards and read-only 64 us nominal IRQ polling; events buffered until each result. Randomized balanced channel order, seed 606125, varied arrival timing.</p> Setting Earlier SF6/125 This SF8/125 One symbol 512 us 2,048 us Requested 5.1-symbol dwell, rounded up 2,612 us 10,445 us 32 programmed preamble symbols 16.384 ms 65.536 ms Whole-run average measured retune 539.427 us 524.124 us Outcome before first miss 7 received, packet 8 missed 12 received, packet 13 missed Miss trace No observed preamble or hold Off-channel preamble and prolonged hold <p>Changing SF increases real listening and preamble durations together. This is not a matched same-image A/B or an isolated post-retune settling experiment. The small retune-time difference must not be treated as a new optimization; no extra settling delay was inserted. The earlier reporting-only held-visit timestamp correction is included in this trace-version-2 run.</p>"},{"location":"sf8_5p1_trace_validation/#failed-probe-an-off-channel-hold","title":"Failed probe: an off-channel hold","text":"<p>Failed sequence <code>388715032</code> targeted channel 3 / 910.250 MHz. The scanner instead observed PreambleDetected on channel 2 / 910.000 MHz, then its normal packet guard deferred the intended jump to channel 3. It never observed a valid header, header error, CRC event, or RxDone for that preamble.</p> <p>Times are software observations relative to expectation arming:</p> Time Event 207.649 ms Last hop onto target channel 3 before the long gap 240.542 ms Hop onto channel 2 250.030 ms PreambleDetected (0x0004) observed on channel 2 251.013 ms Guard defers channel 2 \u2192 3 at the 5.1-symbol deadline 342.287 ms Guard issues a clear of the still-latched preamble bit 342.794 ms Hop onto channel 3 finally completes 342.851 ms IRQ read confirms zero bits 9,999.270 ms Expectation timeout, RX mode, zero device errors <p>Channel-2 occupancy was about 102 ms. The target channel's revisit gap grew to 135.145 ms, compared with its ordinary ~43.875 ms cycle and the 65.536 ms programmed preamble. The delayed retune itself took only 550 us.</p> <p>The preamble-to-header budget from <code>calcMaxPacketMillis()</code> is ceil((32 + 8 + 4.25) * 2.048) = 91 ms. The strict millisecond timeout in <code>CustomSX1262::isReceiving()</code> clears a preamble that does not advance to a header. The observed 92.257 ms from the first IRQ observation to that clear is consistent with this existing protection mechanism.</p> <p>This identifies a prolonged off-channel hold that removed the next listening opportunity. It does not show that the ~0.52 ms jump needs more settling time. The RF source of that preamble is not proven: adjacent-channel pickup/ false detection or unrelated RF are possibilities. There was no independent RF capture or synchronized MCU clock. The earlier SF6 miss had no observed preamble or hold; this result does not establish the same cause for that miss.</p> <p>Simply shortening the guard risks cutting off valid long-preamble packets. Successful traces show that reception legitimately keeps a channel occupied well past 10.445 ms. No production guard change was made in this diagnostic.</p> <p>Follow-up: the stationary preamble investigation reproduced transmitter-associated off-frequency indications with full RX initialization and no hopping, on both boards. It strengthens the off-channel detection explanation without independently identifying the RF source of this historical missed probe. The SF6 miss remains a separate unresolved case.</p>"},{"location":"sf8_5p1_trace_validation/#measurements-and-checks","title":"Measurements and checks","text":"<ul> <li>All 12 successful payloads were valid; RSSI -42 to -41 dBm, SNR 12.0 to   14.2 dB. First observed preamble after logged hop completion ranged   7.433\u20139.485 ms; hop-to-RxDone ranged 105.056\u2013146.836 ms.</li> <li>Entire run: 1,167 fast hops, mean retune 524.124 us, maximum 774 us. Idle   dwell mean 10,452.444 us; held visits separately accounted for.</li> <li>Failed expectation: 910 trace events, zero overflow, 903 completed hops.   The 902 unheld dwells were 10,445\u201310,480 us, mean 10,450.424 us.</li> <li>Excluding the one held cycle, target-channel revisit intervals were   43,847\u201343,928 us, mean 43,874.580 us (224 intervals).</li> <li>Failed-expectation retunes: 511\u2013617 us, mean 520.443 us. The held occupancy   accounts for the anomalous target-channel revisit gap.</li> <li>Zero retune failures, RX-mode errors, modulation-cache errors, CRC/read   errors, USB stale replies or cached transport recovery. Reference TX rc=0.</li> <li>133,217 extra IRQ polls during the failed capture; total cost 3,241,509 us,   maximum 55 us. Polls add load; timestamps are observations, not exact IRQ   edges. No per-event serial output occurs during capture.</li> </ul> <p>This first-miss sample neither estimates a stable packet-error rate nor establishes a channel count with 100% reception.</p>"},{"location":"sf8_5p1_trace_validation/#reproduction-and-provenance","title":"Reproduction and provenance","text":"<pre><code>python tools/hil/profile_switch_channels.py --receiver COM31 --sender COM28 --output tools/hil/sf8_125_5p1_trace_results.json --samples 100 --preamble 32 --max-channels 4 --dwell-symbols 5.1 --trace --sf 8\n</code></pre> <ul> <li>Raw result and all 13 traces</li> <li>Earlier SF6/125 at 5.1 chirps</li> <li>Harness instructions</li> </ul> <p>Raw result SHA-256: <code>0d7e97173937f42708febf8276cdadc36578740735058d5da39b1b576e9ca49e</code>.</p> <p>Tested firmware SHA-256:</p> <ul> <li>XIAO: <code>a68ab9834f62d0a5fb3f10c7a0b312c17d7d62795885cac4ea0dce483d6bf1ea</code></li> <li>Indicator: <code>bca1514bc6e09af6b1a9daed5bf4d3dbeeab988bcb856acbc73f59334395280d</code></li> </ul> <p>Base commit <code>c329cf1fc1e7f2e8c8733ab0d000094730458fe3</code> plus local changes; RadioLib 7.7.1 at <code>187ef24791c3d844939b2be13a68bd890bd04e4c</code>, Espressif32 6.11.0 / Arduino ESP32 2.0.17. Both HIL targets built successfully. All 27 selected host/native tests passed, including SF scaling, propagation to both RX staging slots and TX, cache checks, trace handling and first-miss stop.</p>"},{"location":"sf8_5p1_trace_validation/#device-handoff","title":"Device handoff","text":"<p>Fresh full 8 MiB backups were saved and digest-verified before flashing:</p> <ul> <li>XIAO: <code>e9533742103c9d7af11a3dc0c40496ca412b072e11880c2be785c92ef80e4310</code></li> <li>Indicator: <code>d4f39a0be1339f142ed329b68606347adeb514d26d6cc8bad43fb3d343ac1e2a</code></li> </ul> <p>Both were restored after the test, separately full-flash digest-verified, and hardware-reset. Backups remain in the private current-user backup directory. No identity or channel secrets were used in the synthetic RF probes. The RAK4631 and Indicator RP2040 were not modified; the XIAO soak logger was not restarted. The temporary HIL build overlay was removed. Source, tests and results were initially handed off locally before publication.</p>"},{"location":"spiffs_regular_file_reads/","title":"SPIFFS regular-file reads and login replay state","text":"<p>Arduino-ESP32 SPIFFS can return a truthy directory handle from a read-open of a nonexistent filename. <code>File::operator bool()</code> alone does not prove that a regular file exists. A directory's <code>size()</code> and <code>read()</code> are zero.</p> <p>The first privileged login on an upgraded G2 encountered this in <code>ClientACL::writeClientLoginReplayCeiling()</code>: opening the not-yet-created <code>/s_login_replay</code> appeared successful, then subtracting the eight-byte trailer from size zero underflowed. Copying the supposed records failed and login was rejected. Waiting or changing the repeater clock cannot fix that file-open bug.</p>"},{"location":"spiffs_regular_file_reads/#fix","title":"Fix","text":"<p>Use <code>mesh::openFileRead()</code> for regular-file reads. It checks existence and rejects directory handles, while preserving real empty files. Replay record counts also validate the minimum trailer size, record alignment, and maximum count before subtraction. An existing replay file that becomes unreadable is not treated as a new store.</p> <p>No replay records are cleared and authentication is not weakened. Invalid or unwritable replay state still fails closed. The first successful privileged login creates a 44-byte file: one 36-byte identity/ceiling record plus its eight-byte integrity trailer.</p> <p>Setting the repeater clock must not clear this file. Admission compares the sender's timestamp with that sender's saved boundary, not with the repeater's current time. Clearing the boundary could make captured requests reusable. A sender clock rollback is a separate condition and remains subject to the saved boundary after this fix.</p> <p>Companion directory enumeration uses the separate <code>openDirectory()</code> API, which deliberately permits SPIFFS virtual directories. Regular-file reads are also enforced for companion data, repeater/room logs, flood-rule verification, and HTTP packet-log downloads (missing logs return 404; real empty logs 200).</p>"},{"location":"spiffs_regular_file_reads/#audit-boundary","title":"Audit boundary","text":"<p>The audit covered file opens and size arithmetic in <code>src</code> and <code>examples</code>. Identity, region, clock, and common preference loaders already gate reads with filesystem existence checks; SPIFFS's <code>exists()</code> explicitly excludes directory handles. Relevant MQTT length subtraction follows validated headers and exact reads. ESP32 OTA staging uses partition APIs, not these SPIFFS file handles. Intentional directory enumeration must not be changed to a regular-file read.</p>"},{"location":"spiffs_regular_file_reads/#regression-checks","title":"Regression checks","text":"<ul> <li><code>test/test_client_acl_spiffs.py</code> compiles the actual <code>ClientACL.cpp</code> against   a filesystem that reproduces the misleading missing-file directory handle.   It covers first creation, fresh/stale login, reboot ceilings, corrupt and   unreadable state, short writes, failed publication, and truncated sources.</li> <li><code>test/test_regular_file_reads.py</code> executes production companion readers,   flood-file verification, and HTTP log delivery with the same filesystem   behavior, including platform-specific file API differences.</li> <li><code>test/test_esp32_tinyusb_cooperative_output.py</code> exercises both real role log   pumps, including missing logs and bounded output.</li> <li>Native ACL transaction, login persistence, and client-path persistence suites   retain the existing security and recovery coverage.</li> </ul> <p>The pre-fix actual ACL code was reproduced as <code>first_login=rejected</code>, one missing read-open, and no replay file. The fixed code accepted that identical scenario without a missing read-open and created the valid 44-byte record. Host simulations do not replace a post-flash LoRa login test on the G2.</p>"},{"location":"stats_binary_frames/","title":"Stats Binary Frame Structures","text":"<p>Binary frame structures for companion radio stats commands. All multi-byte integers use little-endian byte order.</p>"},{"location":"stats_binary_frames/#command-codes","title":"Command Codes","text":"Command Code Description <code>CMD_GET_STATS</code> 56 Get statistics (2-byte command: code + sub-type)"},{"location":"stats_binary_frames/#stats-sub-types","title":"Stats Sub-Types","text":"<p>The <code>CMD_GET_STATS</code> command uses a 2-byte frame structure: - Byte 0: <code>CMD_GET_STATS</code> (56) - Byte 1: Stats sub-type:   - <code>STATS_TYPE_CORE</code> (0) - Get core device statistics   - <code>STATS_TYPE_RADIO</code> (1) - Get radio statistics   - <code>STATS_TYPE_PACKETS</code> (2) - Get packet statistics</p>"},{"location":"stats_binary_frames/#response-codes","title":"Response Codes","text":"Response Code Description <code>RESP_CODE_STATS</code> 24 Statistics response (2-byte response: code + sub-type)"},{"location":"stats_binary_frames/#stats-response-sub-types","title":"Stats Response Sub-Types","text":"<p>The <code>RESP_CODE_STATS</code> response uses a 2-byte header structure: - Byte 0: <code>RESP_CODE_STATS</code> (24) - Byte 1: Stats sub-type (matches command sub-type):   - <code>STATS_TYPE_CORE</code> (0) - Core device statistics response   - <code>STATS_TYPE_RADIO</code> (1) - Radio statistics response   - <code>STATS_TYPE_PACKETS</code> (2) - Packet statistics response</p>"},{"location":"stats_binary_frames/#resp_code_stats-stats_type_core-24-0","title":"RESP_CODE_STATS + STATS_TYPE_CORE (24, 0)","text":"<p>Total Frame Size: 11 bytes</p> Offset Size Type Field Name Description Range/Notes 0 1 uint8_t response_code Always <code>0x18</code> (24) - 1 1 uint8_t stats_type Always <code>0x00</code> (STATS_TYPE_CORE) - 2 2 uint16_t battery_mv Battery voltage in millivolts 0 - 65,535 4 4 uint32_t uptime_secs Device uptime in seconds 0 - 4,294,967,295 8 2 uint16_t errors Error flags bitmask - 10 1 uint8_t queue_len Outbound packet queue length 0 - 255"},{"location":"stats_binary_frames/#example-structure-cc","title":"Example Structure (C/C++)","text":"<pre><code>struct StatsCore {\n    uint8_t  response_code;  // 0x18\n    uint8_t  stats_type;     // 0x00 (STATS_TYPE_CORE)\n    uint16_t battery_mv;\n    uint32_t uptime_secs;\n    uint16_t errors;\n    uint8_t  queue_len;\n} __attribute__((packed));\n</code></pre>"},{"location":"stats_binary_frames/#resp_code_stats-stats_type_radio-24-1","title":"RESP_CODE_STATS + STATS_TYPE_RADIO (24, 1)","text":"<p>Total Frame Size: 14 bytes</p> Offset Size Type Field Name Description Range/Notes 0 1 uint8_t response_code Always <code>0x18</code> (24) - 1 1 uint8_t stats_type Always <code>0x01</code> (STATS_TYPE_RADIO) - 2 2 int16_t noise_floor Radio noise floor in dBm -140 to +10 4 1 int8_t last_rssi Last received signal strength in dBm -128 to +127 5 1 int8_t last_snr SNR scaled by 4 Divide by 4.0 for dB 6 4 uint32_t tx_air_secs Cumulative transmit airtime in seconds 0 - 4,294,967,295 10 4 uint32_t rx_air_secs Cumulative receive airtime in seconds 0 - 4,294,967,295"},{"location":"stats_binary_frames/#example-structure-cc_1","title":"Example Structure (C/C++)","text":"<pre><code>struct StatsRadio {\n    uint8_t  response_code;  // 0x18\n    uint8_t  stats_type;     // 0x01 (STATS_TYPE_RADIO)\n    int16_t  noise_floor;\n    int8_t   last_rssi;\n    int8_t   last_snr;       // Divide by 4.0 to get actual SNR in dB\n    uint32_t tx_air_secs;\n    uint32_t rx_air_secs;\n} __attribute__((packed));\n</code></pre>"},{"location":"stats_binary_frames/#resp_code_stats-stats_type_packets-24-2","title":"RESP_CODE_STATS + STATS_TYPE_PACKETS (24, 2)","text":"<p>Total Frame Size: 26 bytes (legacy) or 30 bytes (includes <code>recv_errors</code>)</p> Offset Size Type Field Name Description Range/Notes 0 1 uint8_t response_code Always <code>0x18</code> (24) - 1 1 uint8_t stats_type Always <code>0x02</code> (STATS_TYPE_PACKETS) - 2 4 uint32_t recv Total packets received 0 - 4,294,967,295 6 4 uint32_t sent Total packets sent 0 - 4,294,967,295 10 4 uint32_t flood_tx Packets sent via flood routing 0 - 4,294,967,295 14 4 uint32_t direct_tx Packets sent via direct routing 0 - 4,294,967,295 18 4 uint32_t flood_rx Packets received via flood routing 0 - 4,294,967,295 22 4 uint32_t direct_rx Packets received via direct routing 0 - 4,294,967,295 26 4 uint32_t recv_errors Receive/CRC errors (RadioLib); present only in 30-byte frame 0 - 4,294,967,295"},{"location":"stats_binary_frames/#notes","title":"Notes","text":"<ul> <li>Counters are cumulative from boot and may wrap.</li> <li><code>recv = flood_rx + direct_rx</code></li> <li><code>sent = flood_tx + direct_tx</code></li> <li>Clients should accept frame length &gt;= 26; if length &gt;= 30, parse <code>recv_errors</code> at offset 26.</li> </ul>"},{"location":"stats_binary_frames/#example-structure-cc_2","title":"Example Structure (C/C++)","text":"<pre><code>struct StatsPackets {\n    uint8_t  response_code;  // 0x18\n    uint8_t  stats_type;     // 0x02 (STATS_TYPE_PACKETS)\n    uint32_t recv;\n    uint32_t sent;\n    uint32_t flood_tx;\n    uint32_t direct_tx;\n    uint32_t flood_rx;\n    uint32_t direct_rx;\n    uint32_t recv_errors;    // present when frame size is 30\n} __attribute__((packed));\n</code></pre>"},{"location":"stats_binary_frames/#command-usage-example-python","title":"Command Usage Example (Python)","text":"<pre><code># Send CMD_GET_STATS command\ndef send_get_stats_core(serial_interface):\n    \"\"\"Send command to get core stats\"\"\"\n    cmd = bytes([56, 0])  # CMD_GET_STATS (56) + STATS_TYPE_CORE (0)\n    serial_interface.write(cmd)\n\ndef send_get_stats_radio(serial_interface):\n    \"\"\"Send command to get radio stats\"\"\"\n    cmd = bytes([56, 1])  # CMD_GET_STATS (56) + STATS_TYPE_RADIO (1)\n    serial_interface.write(cmd)\n\ndef send_get_stats_packets(serial_interface):\n    \"\"\"Send command to get packet stats\"\"\"\n    cmd = bytes([56, 2])  # CMD_GET_STATS (56) + STATS_TYPE_PACKETS (2)\n    serial_interface.write(cmd)\n</code></pre>"},{"location":"stats_binary_frames/#response-parsing-example-python","title":"Response Parsing Example (Python)","text":"<pre><code>import struct\n\ndef parse_stats_core(frame):\n    \"\"\"Parse RESP_CODE_STATS + STATS_TYPE_CORE frame (11 bytes)\"\"\"\n    response_code, stats_type, battery_mv, uptime_secs, errors, queue_len = \\\n        struct.unpack('&lt;B B H I H B', frame)\n    assert response_code == 24 and stats_type == 0, \"Invalid response type\"\n    return {\n        'battery_mv': battery_mv,\n        'uptime_secs': uptime_secs,\n        'errors': errors,\n        'queue_len': queue_len\n    }\n\ndef parse_stats_radio(frame):\n    \"\"\"Parse RESP_CODE_STATS + STATS_TYPE_RADIO frame (14 bytes)\"\"\"\n    response_code, stats_type, noise_floor, last_rssi, last_snr, tx_air_secs, rx_air_secs = \\\n        struct.unpack('&lt;B B h b b I I', frame)\n    assert response_code == 24 and stats_type == 1, \"Invalid response type\"\n    return {\n        'noise_floor': noise_floor,\n        'last_rssi': last_rssi,\n        'last_snr': last_snr / 4.0,  # Unscale SNR\n        'tx_air_secs': tx_air_secs,\n        'rx_air_secs': rx_air_secs\n    }\n\ndef parse_stats_packets(frame):\n    \"\"\"Parse RESP_CODE_STATS + STATS_TYPE_PACKETS frame (26 or 30 bytes)\"\"\"\n    assert len(frame) &gt;= 26, \"STATS_TYPE_PACKETS frame too short\"\n    response_code, stats_type, recv, sent, flood_tx, direct_tx, flood_rx, direct_rx = \\\n        struct.unpack('&lt;B B I I I I I I', frame[:26])\n    assert response_code == 24 and stats_type == 2, \"Invalid response type\"\n    result = {\n        'recv': recv,\n        'sent': sent,\n        'flood_tx': flood_tx,\n        'direct_tx': direct_tx,\n        'flood_rx': flood_rx,\n        'direct_rx': direct_rx\n    }\n    if len(frame) &gt;= 30:\n        (recv_errors,) = struct.unpack('&lt;I', frame[26:30])\n        result['recv_errors'] = recv_errors\n    return result\n</code></pre>"},{"location":"stats_binary_frames/#command-usage-example-javascripttypescript","title":"Command Usage Example (JavaScript/TypeScript)","text":"<pre><code>// Send CMD_GET_STATS command\nconst CMD_GET_STATS = 56;\nconst STATS_TYPE_CORE = 0;\nconst STATS_TYPE_RADIO = 1;\nconst STATS_TYPE_PACKETS = 2;\n\nfunction sendGetStatsCore(serialInterface: SerialPort): void {\n    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_CORE]);\n    serialInterface.write(cmd);\n}\n\nfunction sendGetStatsRadio(serialInterface: SerialPort): void {\n    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_RADIO]);\n    serialInterface.write(cmd);\n}\n\nfunction sendGetStatsPackets(serialInterface: SerialPort): void {\n    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_PACKETS]);\n    serialInterface.write(cmd);\n}\n</code></pre>"},{"location":"stats_binary_frames/#response-parsing-example-javascripttypescript","title":"Response Parsing Example (JavaScript/TypeScript)","text":"<pre><code>interface StatsCore {\n    battery_mv: number;\n    uptime_secs: number;\n    errors: number;\n    queue_len: number;\n}\n\ninterface StatsRadio {\n    noise_floor: number;\n    last_rssi: number;\n    last_snr: number;\n    tx_air_secs: number;\n    rx_air_secs: number;\n}\n\ninterface StatsPackets {\n    recv: number;\n    sent: number;\n    flood_tx: number;\n    direct_tx: number;\n    flood_rx: number;\n    direct_rx: number;\n    recv_errors?: number;  // present when frame is 30 bytes\n}\n\nfunction parseStatsCore(buffer: ArrayBuffer): StatsCore {\n    const view = new DataView(buffer);\n    const response_code = view.getUint8(0);\n    const stats_type = view.getUint8(1);\n    if (response_code !== 24 || stats_type !== 0) {\n        throw new Error('Invalid response type');\n    }\n    return {\n        battery_mv: view.getUint16(2, true),\n        uptime_secs: view.getUint32(4, true),\n        errors: view.getUint16(8, true),\n        queue_len: view.getUint8(10)\n    };\n}\n\nfunction parseStatsRadio(buffer: ArrayBuffer): StatsRadio {\n    const view = new DataView(buffer);\n    const response_code = view.getUint8(0);\n    const stats_type = view.getUint8(1);\n    if (response_code !== 24 || stats_type !== 1) {\n        throw new Error('Invalid response type');\n    }\n    return {\n        noise_floor: view.getInt16(2, true),\n        last_rssi: view.getInt8(4),\n        last_snr: view.getInt8(5) / 4.0,  // Unscale SNR\n        tx_air_secs: view.getUint32(6, true),\n        rx_air_secs: view.getUint32(10, true)\n    };\n}\n\nfunction parseStatsPackets(buffer: ArrayBuffer): StatsPackets {\n    const view = new DataView(buffer);\n    if (buffer.byteLength &lt; 26) {\n        throw new Error('STATS_TYPE_PACKETS frame too short');\n    }\n    const response_code = view.getUint8(0);\n    const stats_type = view.getUint8(1);\n    if (response_code !== 24 || stats_type !== 2) {\n        throw new Error('Invalid response type');\n    }\n    const result: StatsPackets = {\n        recv: view.getUint32(2, true),\n        sent: view.getUint32(6, true),\n        flood_tx: view.getUint32(10, true),\n        direct_tx: view.getUint32(14, true),\n        flood_rx: view.getUint32(18, true),\n        direct_rx: view.getUint32(22, true)\n    };\n    if (buffer.byteLength &gt;= 30) {\n        result.recv_errors = view.getUint32(26, true);\n    }\n    return result;\n}\n</code></pre>"},{"location":"stats_binary_frames/#field-size-considerations","title":"Field Size Considerations","text":"<ul> <li>Packet counters (uint32_t): May wrap after extended high-traffic operation.</li> <li>Time fields (uint32_t): Max ~136 years.</li> <li>SNR (int8_t, scaled by 4): Range -32 to +31.75 dB, 0.25 dB precision.</li> </ul>"},{"location":"telemetry_decoder/","title":"Telemetry decoder","text":"<p>Paste raw hexadecimal packet data copied from the Let's Mesh packet analyzer to decode a repeater's scheduled temperature, battery-voltage, or external I2C-voltage snapshot. The decoder also accepts the payload hex without its MeshCore packet header and the Base64 pages returned by repeater or room-server CLI commands. Decoding happens entirely in this browser; pasted data is not uploaded or sent anywhere.</p> <p>The Source ID in a raw-packet result is the first eight bytes of the sending repeater's public key. Match that 16-character hex value against the public-key prefix recorded for your repeaters. It comes from the telemetry payload itself, so it is available even when only the payload was copied.</p>"},{"location":"telemetry_decoder/#send-raw-telemetry-packets","title":"Send raw telemetry packets","text":"<p>From an administrator CLI session, first configure a direct route to the MQTT observer that will receive and upload the raw packets. Use <code>direct</code> when the observer is a zero-hop neighbor:</p> <pre><code>set data.tx path direct\nsend telemetry.tx now\n</code></pre> <p>For a routed observer, provide its comma-separated hop hashes instead:</p> <pre><code>set data.tx path A1B2,C3D4\nsend telemetry.tx now\n</code></pre> <p>The shared route does not enable telemetry. Automatic telemetry is off on a fresh install; to explicitly keep the route manual-only before sending:</p> <pre><code>set telemetry.tx schedule off\nsend telemetry.tx now\n</code></pre> <p>The <code>send telemetry.tx now</code> command queues one <code>TTB1</code> temperature packet, one <code>TVB1</code> battery-voltage packet, and <code>IVB1</code> chunks for every connected I2C voltage channel. <code>TTB1</code> and <code>TVB1</code> carry up to 165 samples. Each <code>IVB1</code> carries 64, so a full 192-point/four-day channel takes three packets. Channels whose retained history is entirely zero are treated as disconnected and are not sent. The command requires at least one collected base sample and works even when the automatic schedule is off.</p>"},{"location":"telemetry_decoder/#decode-a-packet","title":"Decode a packetDecoded telemetry","text":"Try an analyzer example: Temperature packet Voltage packet I2C voltage packet I2C voltage CLI page Raw packet or payload hex <p>     Spaces, line breaks, colons, dashes, a leading <code>0x</code>, and a quoted     JSON field are accepted. CLI Base64 replies are also auto-detected. Paste     multiple compatible packet or reply lines together to merge them by     timestamp before downloading one CSV. Press Ctrl/Command+Enter to decode.   </p> Decode telemetry Clear        Show browser-local time      Download CSV Decode notes"},{"location":"telemetry_decoder/#analyzer-hex-examples","title":"Analyzer hex examples","text":"<p>The buttons load synthetic, protocol-valid zero-hop RAW_CUSTOM packets. A real scheduled snapshot normally has 165 samples and is much longer. Routed packets also contain path bytes before the <code>TTB1</code> or <code>TVB1</code> payload magic; the decoder finds and validates the payload automatically.</p>"},{"location":"telemetry_decoder/#temperature","title":"Temperature","text":"<pre><code>3E00545442311122334455667788800092651E0008000102354A4E5082\n</code></pre>"},{"location":"telemetry_decoder/#battery-voltage","title":"Battery voltage","text":"<pre><code>3E00545642311122334455667788800092651E000800010264C8FEFFDC\n</code></pre>"},{"location":"telemetry_decoder/#external-i2c-voltage","title":"External I2C voltage","text":"<pre><code>3E00495642311122334455667788800092651E00020800000004019026927109C427107FFF\n</code></pre> <p>All three examples identify the source as <code>1122334455667788</code>.</p>"},{"location":"telemetry_decoder/#cli-history-pages","title":"CLI history pages","text":"<p>The same page continues to decode the padded Base64 returned by these administrator commands:</p> Data Newest page Older-page example Samples per page MCU temperature <code>get telemetry.temp</code> <code>get telemetry.temp 2</code> 48 (24 hours) Battery voltage <code>get telemetry.volt</code> <code>get telemetry.volt 3</code> 48 (24 hours) I2C voltage <code>get telemetry.volt.i2c 2</code> <code>get telemetry.volt.i2c 2 4</code> 48 (24 hours) GPS position <code>get telemetry.gps</code> <code>get telemetry.gps 2</code> 24 (12 hours) <p>Paste either the complete reply beginning with <code>&gt;</code> or Base64 alone. For example:</p> <pre><code>get telemetry.volt 1\n&gt; EkDUcWoeMAAB5+bl5eTj4uLh4ODf3t7d3Nvb2tnZ2NfX1tXU1NPS0tHQ0M/Ozc3My8vKycnI/w==\n</code></pre> <p>Run <code>get telemetry.volt.i2c</code> without a channel first to list connected channels. For each channel, collect pages <code>1</code> through <code>4</code>. Paste all four reply lines into the decoder at once; it merges their timestamps into one 192-point, four-day table and downloads them as one CSV. The same merging works for the three <code>IVB1</code> analyzer packets from a full channel. Inputs must have the same telemetry type, source, LPP channel, and sample interval.</p> <p>An INA3221 exposes its three enabled hardware inputs as three consecutive LPP channels. When it is the only external sensor these are normally <code>2</code>, <code>3</code>, and <code>4</code>, in hardware-input order. Other sensors can shift the numbers, so copy the IDs reported by <code>get telemetry.volt.i2c</code> rather than assuming them.</p>"},{"location":"telemetry_decoder/#reading-the-table","title":"Reading the table","text":"<ul> <li>Timestamps default to UTC. Select Show browser-local time to convert   them for display and CSV export.</li> <li><code>TTB1</code> means a raw temperature snapshot, <code>TVB1</code> a raw battery-voltage   snapshot, and <code>IVB1</code> a packed external I2C-voltage chunk. The input summary   also reports the MeshCore route and path-hop count when a complete packet was   pasted.</li> <li>Temperature preserves exact whole degrees from <code>-50 C</code> through <code>+77 C</code>, plus   missing, below-range, and above-range states.</li> <li>Voltage preserves hundredths of a volt from <code>1.88 V</code> through <code>4.40 V</code>, plus   missing and out-of-range states.</li> <li>External I2C voltage uses a 15-bit code at <code>0.02 V</code> resolution. Code <code>0</code> is   missing/disconnected; codes <code>1</code> through <code>32767</code> cover <code>0.02 V</code> through   <code>655.34 V</code>. The LPP channel remains part of every page and raw chunk so   multiple monitor inputs cannot be mixed accidentally.</li> <li>GPS positions are reconstructed from signed 10-meter differentials. A zero   differential after the page origin is inherently ambiguous: it can represent   an unchanged fix, movement below the encoded resolution, or no fix. The table   labels those rows rather than inventing a coordinate.</li> <li>A GPS clipping warning means at least one movement exceeded the differential   range, so positions after that point can be less accurate.</li> </ul> <p>GPS history remains available through the administrator CLI, but <code>telemetry.tx</code> never puts GPS in RAW_CUSTOM packets. Location data therefore must come from a CLI Base64 page rather than analyzer hex.</p> <p>For the byte-level layouts, see Read repeater telemetry history.</p>"},{"location":"terminal_chat_cli/","title":"Terminal Chat CLI","text":"<p>Below are the commands you can enter into the Terminal Chat clients:</p> <p>For a timed RF carrier test on SX1262 or LR1110, use <code>cw on 2.5</code> or <code>cw2 on 2.5</code>, then <code>cw off</code> to stop early. See carrier-wave RF checks for profile selection, limits, and status commands.</p>"},{"location":"terminal_chat_cli/#companion-wifi-browser-terminal","title":"Companion WiFi browser terminal","text":"<p>On ESP32 WiFi Companions with WebConfig, open the node's LAN IP address and select CLI. The browser runs the same commands as the USB terminal and Full Companion's TCP terminal on port 5002, including contact import, contact selection, messages, remote login/commands, and delayed RF replies. Run <code>help</code> to list commands compiled into the device. Enable the tab with <code>set wifi.cli on</code>; the open setup AP does not expose it.</p> <p>For example, copy the complete <code>meshcore://...</code> string from <code>card</code> on another Companion, then run these commands on the receiving Companion:</p> <pre><code>import meshcore://&lt;full-contact-card-data&gt;\nlist\nto &lt;contact-name-or-prefix&gt;\n</code></pre> <p>Replace the placeholders; a bare public key is not a contact card. Import is queued for signature validation, so use <code>list</code> to confirm the contact appears. Explicit import works with manual contact addition enabled and bypasses the automatic discovery type/hop filters. It still respects contact storage limits; a full contact table follows the configured overwrite policy. <code>to</code> remains selected for subsequent <code>send</code>, <code>path</code>, <code>login</code>, and <code>cmd</code> commands within this terminal session.</p> <p>Only one USB, TCP, or browser text terminal owns the session at a time. An idle startup USB prompt can be borrowed by WiFi. Use <code>disconnect</code> or the browser's disconnect button to release it. Closing the page releases the session; if the connection disappears, it expires after 60 seconds without a poll. Long replies page into the browser automatically, and incoming replies continue appearing after a command finishes. Terminal scrollback starts at 4 KiB and can grow to 32 KiB for unread output, preferring PSRAM; it shrinks after reading and is freed when the session expires. If output exceeds the available buffer while unread, the browser reports the missing output.</p> <p>USB protocol-switch and USB MOTA ownership commands still apply to the USB connection. Use the WiFi MOTA seeder on port 5001 for a host folder over WiFi.</p>"},{"location":"terminal_chat_cli/#local-maintenance-commands","title":"Local maintenance commands","text":"<p>Local means a connection directly to the node: USB, BLE or WiFi/Ethernet Companion protocol, a TCP terminal, or the browser CLI on the LAN. These connections can use the following commands when the role and build include the corresponding feature:</p> Command Result <code>stats-core</code>, <code>stats-radio</code>, <code>stats-radio-diag</code>, <code>stats-packets</code> Runtime diagnostics <code>get prv.key</code> Node identity private key; Companion requires private key export enabled in the build <code>get password</code> Infrastructure admin password; Companion reports that it has no admin password <code>erase</code> Erase stored identity and settings; reboot for a fresh node <code>get wifi.pwd</code> Stored WiFi password on WiFi builds <code>get mqttN.password</code>, <code>get mqttN.token</code> Stored credentials for MQTT slot N <code>get acl</code>, <code>log</code> Infrastructure ACL or captured packet log; these stores do not exist on Companion <p>The command text is the same for direct connections. A binary Companion app can send <code>0x42</code> (<code>CMD_RUN_CLI_COMMAND</code>) followed by the ASCII command, without switching into terminal mode. The response is <code>0x1D</code> (<code>RESP_CODE_CLI_REPLY</code>) followed by the reply text. For example, payload <code>42 67 65 74 20 70 61 73 73 77 6f 72 64</code> runs <code>get password</code>. USB framing remains the normal Companion frame; BLE and TCP use their existing Companion transport framing.</p> <p><code>set freq &lt;MHz&gt;</code> is available on these local connections and through authorized LoRa administration, just like <code>set radio</code>. It saves the frequency without changing bandwidth, spreading factor, or coding rate and requires a reboot to apply. Infrastructure roles also apply the board's transmit-power limit.</p> <p>Commands relayed to another node using <code>cmd</code> travel over LoRa and retain the remote restrictions on local-only maintenance and secret reads. These local permissions do not add an ACL or packet-log store to Companion. Use <code>list</code> or the binary contacts operations for Companion contacts. Interactive chat commands still use the text terminal or their corresponding binary protocol operations.</p> <p>The browser CLI requires station/LAN mode and <code>wifi.cli on</code>. Infrastructure uses its admin login; Companion uses the trusted LAN. Configuration forms keep password fields masked; explicit local CLI getters return their values.</p>"},{"location":"terminal_chat_cli/#companion-contact-and-channel-tx-profiles","title":"Companion contact and channel TX profiles","text":"<p>Choose where the Companion transmits to a contact or group channel:</p> <pre><code>set tx.user \"Alice Jones\" radio2\nget tx.user \"Alice Jones\"\nset tx.channel 0 both\nset tx.channel #wardriving radio\nget tx.channel 0\n</code></pre> <p>Values are <code>auto</code>, <code>radio</code>, <code>radio2</code>, <code>both</code>, and <code>off</code>. <code>auto</code> follows <code>radio2.cross</code>; explicit choices override it. Radio2 must still be in <code>rxtx</code> mode, and a <code>radio2</code>-only send fails when it cannot transmit. These settings persist and also apply to messages sent by the phone app. Use exact names, a channel index, or <code>key:&lt;unique public-key prefix&gt;</code> for a contact. See the routing guide for which requests/replies are covered and how to reset a choice.</p>"},{"location":"terminal_chat_cli/#companion-usb-mode","title":"Companion USB mode","text":"<p>Updated 1.17.1.6 USB Companion builds, including ordinary and Full builds, start in ASCII at 115200 baud. A valid framed app command automatically selects Binary Companion. You can open a terminal without a start token:</p> <pre><code>picocom --baud 115200 /dev/ttyACM0\n</code></pre> <p>Current source waits for input before printing the USB banner. Press Enter or type a command. This preserves the clean first response needed by binary apps; see USB client validation for release status.</p> <p>For older firmware or a port already in Binary mode, use:</p> <pre><code>picocom --baud 115200 \\\n  --imap spchex \\\n  --initstring $'+++MESHCORE-TERM-START\\r' \\\n  /dev/ttyACM0\n</code></pre> <p><code>--initstring</code> sends this exact terminal-start line automatically:</p> <pre><code>+++MESHCORE-TERM-START\n</code></pre> <p>The carriage return is required in Binary mode. Control tokens are recognized only as complete CR/LF-delimited lines, so the same text embedded in unrelated unframed input cannot switch modes accidentally.</p> <p>Binary Companion frames can contain terminal control bytes. The <code>spchex</code> input map renders those bytes as bracketed hexadecimal during the short transition instead of allowing them to change the local terminal's character set or display state. It leaves high-bit bytes unchanged so a UTF-8 terminal displays emoji and non-ASCII text normally. Do not add <code>8bithex</code> unless you explicitly want UTF-8 bytes displayed as sequences such as <code>[f0][9f][91][8b]</code>. Once the terminal banner appears, the start sequence has already succeeded; do not enter it again as a terminal command.</p> <p>Send the following exact sequence to return to the binary protocol:</p> <pre><code>+++MESHCORE-TERM-STOP\n</code></pre> <p>If logging shares the primary USB port (ESP32), first run <code>set usb.logging off</code>. With logging still on, the stop token reports an error and keeps ASCII logging active. nRF52 Full's separate logging port can remain enabled.</p> <p>An observable USB session reset restores ASCII after clearing the previous client's state. Native USB with DTR can detect a terminal closing; ESP32 hardware USB Serial/JTAG detects bus resets and physical host loss. USB-to-UART bridges usually cannot detect a terminal closing. Use the start token on ports that remain in Binary mode; idle time does not select ASCII.</p> <p>Both modes use the same port at 115200. Selecting 57600 is not a portable mode switch: native USB CDC devices ignore the requested baud, while USB-to-UART devices really change the UART timing and receive corrupt data. Binary mode is the framed Companion API used by apps and <code>meshcli</code>; close the terminal before opening that port from an app.</p> <p>All USB Companion builds automatically switch when they see a complete <code>&lt;</code>-prefixed Companion frame at an empty prompt. The explicit start/stop tokens remain available. See Companion USB CLI and binary switcher for the state machine and limitations.</p>"},{"location":"terminal_chat_cli/#commands","title":"Commands","text":"<p>ESP32 and nRF52 Full Companions include an offline World English Bible lookup:</p> <pre><code>get reader 3:16\n</code></pre> <p>This returns a single complete verse from the embedded corpus, using plain ASCII punctuation with unchanged wording and capitalization, through the local USB/TCP terminal. See Reader lookup and compression for the source, supported build profiles and memory costs.</p> <pre><code>set freq {frequency}\n</code></pre> <p>Set the saved LoRa frequency. Example: <code>set freq 915.8</code>. Available over local connections and authorized LoRa CLI; reboot to apply.</p> <pre><code>set tx {tx-power-dbm}\n</code></pre> <p>Sets LoRa-chip transmit power in dBm. The firmware rejects values outside the radio/board limit; external-PA boards can have a lower input-power ceiling than the radio chip itself.</p> <pre><code>set name {name}\n</code></pre> <p>Sets your advertisement name.</p> <pre><code>get bluetooth.name\nset bluetooth.name {name|default}\n</code></pre> <p>Shows or changes the complete Bluetooth device name without changing the mesh advertisement identity. A custom name may contain spaces and is limited to 31 valid UTF-8 bytes. <code>default</code> restores <code>MeshCore-&lt;node name&gt;</code>. The saved change takes effect after reboot. <code>get ble.name</code> and <code>set ble.name</code> are short aliases.</p> <pre><code>get bluetooth.mac\nset bluetooth.mac {address|random|random-every-boot|random-after-connect|default}\nget bluetooth.stealth\nset bluetooth.stealth {on|off}\n</code></pre> <p>Shows or changes the Bluetooth identity on Companion builds with BLE. A literal address must be BLE random-static, such as <code>C2:11:22:33:44:55</code>. <code>random</code> generates and saves one address; <code>random-every-boot</code> generates a new one on each startup (<code>random everyboot</code> is also accepted). <code>random-after-connect</code> keeps its address across unused power cycles, then rotates on the next boot after an authenticated connection. <code>default</code> or <code>clear</code> restores the factory address without changing the stealth flag. Reboot, forget the old phone entry, and pair again after an address change. <code>get ble.mac</code> and <code>set ble.mac</code> are short aliases.</p> <p>The independent <code>bluetooth.stealth</code> flag defaults off and preserves the chosen address policy. With it on, the node is discoverable until its first authenticated pairing, then accepts only that bonded peer. Custom and saved random addresses keep the bond across boots; rotating modes reopen pairing when the address rotates, leaving stealth enabled. It still transmits the directed or allowlisted packets BLE requires for reconnection. Repeating <code>on</code> keeps the bond. Send <code>off</code>, then <code>on</code>, then reboot to reopen pairing manually. <code>ble.stealth</code> is the short alias. Flag changes require reboot.</p> <pre><code>set lat {latitude}\n</code></pre> <p>Sets your advertisement map latitude. (decimal degrees)</p> <pre><code>set lon {longitude}\n</code></pre> <p>Sets your advertisement map longitude. (decimal degrees)</p> <pre><code>set af {air-time-factor}\n</code></pre> <p>Sets the transmit air-time-factor. Deprecated - use <code>set dutycycle</code> instead.</p> <pre><code>get powersaving\nset powersaving {on|off}\n</code></pre> <p>Shows or changes Companion device power saving. On ESP32 this controls CPU and GPS idle behavior; it does not change LoRa RXPS or WiFi modem sleep.</p> <pre><code>get usb.logging\nset usb.logging {on|off} [reboot]\n</code></pre> <p>Shows or changes persistent live USB debug and packet output in an ordinary USB-loggable Companion or Full Companion. USB Companion and Full start off on a fresh install with logging disabled to protect framed traffic. nRF52 Full changes its interface count after a reboot and keeps Companion on interface <code>00</code>. Every ESP32 Full Companion has one TTY and needs no reboot: logging uses the active text terminal, disables framed Binary Companion on USB, and continues accepting <code>set usb.logging off</code>. Turning logging off leaves the port in the normal ASCII terminal, matching fresh firmware. Send <code>+++MESHCORE-TERM-STOP</code>, or let a Companion app send a valid framed probe, to switch it to Binary Companion afterward.</p> <pre><code>reboot\n</code></pre> <p>Sends an acknowledgement, then reboots the Companion one second later. The delay gives either the USB terminal or the Full Companion TCP terminal on port 5002 time to deliver the reply before its transport disappears.</p> <pre><code>get radio.rxps\nget radio.rxps.config\nset radio.rxps {off|on|level 1-10 [preamble 16|32]|rx_us sleep_us}\n</code></pre> <p>Shows or changes LoRa receive duty cycling on supported radios. <code>get radio.rxps.config</code> also reports the saved level and preamble assumption so automation can restore a level-based preference exactly. Fresh Cascade builds select level 8 with a 16-symbol timing assumption. The <code>preamble</code> argument controls the RXPS calculation; it does not change the physical wire preamble. A configured level is the minimum: when faster SF/BW settings shorten the timing window, firmware raises the effective level only as far as needed, up to level 10. Starting with v1.17.1.5, SF5-SF8 packets normally use a 32-symbol physical preamble. Firmware selects 64, then 128, only when every shorter choice fails to enable RXPS at any level. The configured values remain unchanged, so every radio change recalculates from the saved minimum. A slower tuple returns to that exact level and the shortest viable wire preamble.</p> <p>If neither adjustment leaves enough time for the radio to wake, RXPS stays logically enabled but receives continuously instead of rejecting the radio setting or starting an invalid duty cycle. The Companion terminal's <code>get radio.rxps</code> reports this as <code>mode=continuous-fast</code> and reports any <code>effective-level</code> or <code>effective-preamble</code> adjustment; <code>get radio.rxps.config</code> reports the persisted preference. A later compatible SF/BW change resumes duty cycling without another RXPS command.</p> <p>For the SX1262+TCXO boards tested here, these fast combinations are the useful RXPS boundary profiles (CR does not change the RXPS preamble timing):</p> SF BW (kHz) Wire preamble Effective preamble Minimum effective level RX / sleep 7 500 32 32 7 2731 / 6101 us 6 250 32 32 7 2731 / 6101 us 5 125 32 32 7 2731 / 6101 us 5 250 64 64 8 1252 / 6424 us 6 500 64 64 8 1252 / 6424 us 5 500 128 128 8 626 / 6398 us 5 62.5 32 16 10 4096 / 6272 us <p>The 64- and 128-symbol rows require the v1.17.1.5-or-newer adaptive-preamble contract on every sender that may reach the RXPS receiver. Cascade/USA builds on a Heltec V4 and WisMesh Tag (RAK4631 target) passed 16/16 packets in each direction at both SF5/BW250/64 and SF5/BW500/128, CR5, 909.950 MHz. An older sender makes a long-preamble timing window unsafe, so use continuous RX for a mixed deployment. Retry packets use the same physical preamble as other packets.</p> <pre><code>get wifi.powersave\nset wifi.powersave {none|min|max}\n</code></pre> <p>Shows or changes the persisted WiFi modem-sleep policy on ESP32 WiFi Companion builds. Full Companion requires at least <code>min</code> while BLE is present and rejects <code>none</code>. The WebConfig WiFi card and the normal binary Companion protocol expose the same setting; binary clients do not need the terminal-start token. On an ESP32 Full Companion whose primary mesh radio is ESP-NOW, <code>max</code> is also unavailable because maximum modem sleep can make the station miss ESP-NOW broadcasts, which the access point does not buffer. A previously saved <code>max</code> value is capped to and reported as <code>min</code>, and a new <code>max</code> selection is rejected. Such a WiFi/BLE/primary-ESP-NOW build therefore uses <code>min</code>.</p> <pre><code>get espnow.channel\nset espnow.channel &lt;1-13&gt;\n</code></pre> <p>On builds whose primary mesh radio is ESP-NOW, this shows or saves the primary radio's channel. The default is channel 1. Use only a channel permitted in your region, and restart or power-cycle the node after changing it. Every primary ESP-NOW peer must use the same channel.</p> <p>On Full Companion, the setup AP and infrastructure-WiFi station also share that channel, so the router's 2.4 GHz radio must remain fixed to it. Power saving does not permit separate channels. <code>wifi.powersave max</code> is unavailable on these ESP32 Full builds and <code>min</code> is the coexistence setting. This channel setting is also distinct from <code>bridge.channel</code>, which controls the optional ESP-NOW bridge transport. An updated LoRa-primary ESP-NOW bridge can join this raw primary transport by selecting the same channel and running <code>set bridge.format raw</code>; its default <code>wrapped</code> format remains the bridge-to-bridge protocol.</p> <pre><code>get radio.rxgain\nset radio.rxgain {on|off}\nget radio.fem.rxgain\nset radio.fem.rxgain {on|off}\nget radio.fem.txgain\nset radio.fem.txgain {on|off}\n</code></pre> <p><code>radio.rxgain</code> changes the radio chip's boosted receive-gain mode. The FEM settings control the external receive-path LNA or transmit-path gain on supported boards. Changes are applied immediately and saved across reboots; changing either receive-gain path also recalibrates the radio noise floor. Boards without the respective control report it as unsupported.</p> <pre><code>time {epoch-secs}\n</code></pre> <p>Set the device clock using UNIX epoch seconds. Example:  time 1738242833</p> <pre><code>advert\n</code></pre> <p>Sends an advertisement packet</p> <pre><code>clock\n</code></pre> <p>Displays current time per device's clock.</p> <pre><code>ver\n</code></pre> <p>Shows the device version and firmware build date.</p> <pre><code>card\n</code></pre> <p>Displays your 'business card', for others to manually import</p> <pre><code>import {card}\n</code></pre> <p>Imports the given card to your contacts.</p> <pre><code>list {n}\n</code></pre> <p>Lists favorite contacts first, then all remaining contacts. Each group is ordered by the most recent advertisement. Optional <code>{n}</code> limits the displayed contacts after applying that order.</p> <pre><code>show\nshow adverts {on|off}\nshow channels {on|off}\nshow emergency {on|off}\n</code></pre> <p>Controls unsolicited receive output in the USB terminal. Plain <code>show</code> reports the current settings, and <code>show {category}</code> reports one category. At boot, advertisements and ordinary channel messages are hidden while <code>#emergency</code> messages are shown. The three controls are independent, so <code>show channels on</code> does not override <code>show emergency off</code>.</p> <p>These filters affect terminal printing only. Messages still enter the offline queue and are delivered through the binary Companion protocol. Changes remain active when switching between terminal and binary mode and reset to their defaults after reboot.</p> <pre><code>to\n</code></pre> <p>Shows the name of current recipient contact. (for subsequent 'send' commands)</p> <pre><code>to {name-prefix}\n</code></pre> <p>Sets the recipient to the first matching contact (in 'list') by the name prefix. (ie. you don't have to type whole name)</p> <pre><code>path\n</code></pre> <p>Shows the saved outgoing path for the current <code>to</code> recipient. This command and all path changes require a recipient to be selected first.</p> <pre><code>path direct\npath clear\npath {hop-hash...}\n</code></pre> <p>Sets the outgoing path used by subsequent <code>login</code>, <code>send</code>, and <code>cmd</code> commands. <code>direct</code> selects a zero-hop route. <code>clear</code> forgets the saved route, causing the next operation to use flood routing and allowing normal path discovery to learn a replacement.</p> <p>Explicit paths use spaces, commas, or a mixture of both between hop hashes. Each hop must contain exactly 2, 4, or 6 hexadecimal digits, and every hop in one path must use the same width. Whitespace and hexadecimal letter case do not matter. The setting is saved with the selected contact.</p> <p>For example:</p> <pre><code>to Hilltop Repeater\npath A1B2C3,D4E5F6\npath 7773D0 7E7662\npath\nlogin my-admin-password\n</code></pre> <pre><code>login {admin-password}\n</code></pre> <p>Sends a remote login request to the current recipient. Select a repeater, room, or other remotely managed node with <code>to {name-prefix}</code> first. The password is masked with <code>*</code> while it is entered and must be 1-15 UTF-8 bytes; longer passwords are rejected instead of truncated. Login uses the route shown by <code>path</code>: a known or explicitly set route is direct, while an unknown route is flooded.</p> <p>Login results arrive asynchronously. A successful modern response displays the remote ACL permissions byte and server protocol level. A wrong password, an unreachable target, or a server that does not support remote login normally produces a timeout because those nodes do not send a rejection packet.</p> <pre><code>cmd {remote-command}\n</code></pre> <p>Sends CLI data to the current recipient. Wait for the login result before sending the first command. The remote node applies its own ACL permissions, and any reply appears asynchronously as <code>CLI -&gt; from {name}</code>. The response window is 300% of the route estimate. A routed send is displayed as <code>DIRECT via path {hop,...}</code> with the exact prefixes copied into the packet; in MeshCore, <code>DIRECT</code> is the route class for an explicit path, not a synonym for zero hops. A matched reply also shows its local round-trip time, measured from queueing the command through receiving the result. This includes both radio directions and remote execution; it is not execution-only CPU time. Only one terminal <code>cmd</code> can be pending at a time.</p> <p>For example:</p> <pre><code>to Hilltop Repeater\nlogin my-admin-password\nLOGIN -&gt; Hilltop Repeater accepted (ACL permissions 0x03, server v13)\ncmd ver\ncmd get radio\n</code></pre> <p>The exact commands and permissions depend on the target firmware. <code>cmd</code> does not run a command on the local Companion; it sends the text over LoRa to the selected node.</p> <p>Incoming direct-route messages are labeled <code>ROUTED</code>, not <code>DIRECT</code>. Forwarders consume direct-route prefixes as the packet travels, so the destination cannot recover the reply's actual hop history from the received packet. Use <code>trace</code> when the return route itself must be verified.</p> <pre><code>send {text}\n</code></pre> <p>Sends the text message (as DM) to current recipient.</p> <pre><code>trace\n</code></pre> <p>Traces the saved round-trip route to the current recipient and displays the SNR at each hop. Select the recipient first with <code>to {name-prefix}</code>.</p> <pre><code>trace {name-prefix}\n</code></pre> <p>Traces a recipient directly without changing the current <code>to</code> selection. A trace requires a known direct path; use normal messaging or path discovery first if the terminal reports that no valid path is available. Only one terminal trace can be pending at a time, and a missing response is reported as a timeout.</p> <p>For example:</p> <pre><code>to Hilltop Repeater\ntrace\ntrace Downtown\n</code></pre> <p>The displayed route uses one- or two-byte node hashes and per-hop SNR values. Saved three-byte paths are traced with two-byte prefixes because the trace packet format has no three-byte hash-size mode.</p> <p>To trace an explicit route instead of a saved contact path, provide the prefix size followed by the complete ordered route:</p> <pre><code>trace path 1 12 34 56 34 12\ntrace path 2 1234,ABCD,5678,ABCD,1234\ntrace path 4 12345678, ABCDEF01 89ABCDEF, ABCDEF01,12345678\n</code></pre> <p>Prefix separators may be spaces, commas, or any mixture of them. Each prefix must contain exactly 2, 4, or 8 hexadecimal digits for a 1-, 2-, or 4-byte trace respectively. Three-byte traces are not supported.</p> <p>The prefixes are used exactly in the order entered. To receive the trace result, enter the complete outward route followed by its return route, as in the mirrored examples above. A route that does not return to this node will eventually report a timeout.</p> <pre><code>reset path\n</code></pre> <p>Resets the path to current recipient, for new path discovery. This is retained as an alias for <code>path clear</code>.</p> <pre><code>public {text}\n</code></pre> <p>Sends the text message to the built-in <code>Public</code> group channel.</p> <pre><code>channels\n</code></pre> <p>Lists the configured channel slots and names without exposing their secrets.</p> <pre><code>channel {name-or-slot} {text}\n</code></pre> <p>Sends a message to any configured channel by its exact name or numeric slot. Use the slot shown by <code>channels</code> when a channel name contains spaces.</p> <p>For example:</p> <pre><code>channels\nchannel #rgdata Hello from Eugene\nchannel 2 Another message\nshow channels on\n</code></pre> <p>Messages are UTF-8. Emoji use multiple bytes toward the available message length, which also includes the sender-name prefix added over the air.</p>"},{"location":"usb_serial_backpressure/","title":"Native USB backpressure and radio liveness","text":"<p>ESP32-S2/S3 builds using native TinyUSB CDC (<code>ARDUINO_USB_MODE=0</code> and CDC-on-boot) must not wait for a computer to read USB output. In the bundled Arduino-ESP32 2.0.17 core, <code>USBCDC::write()</code> can wait indefinitely for transmit space; its configured timeout bounds a mutex, not that wait. This can stop the same loop that services LoRa, even while the USB connection still appears open.</p>"},{"location":"usb_serial_backpressure/#firmware-behavior","title":"Firmware behavior","text":"<ul> <li>Native CDC output uses a single FIFO attempt, not Arduino's wait-for-space   write or flush. TinyUSB's internal short mutex operations still apply; this   is a no-host-progress-wait guarantee, not a lock-free driver replacement.</li> <li>Functional text and diagnostics share one ordered 4 KiB queue. Diagnostics   leave 3 KiB reserved for commands. A diagnostic backlog alone does not prevent   command input. A stalled host may lose diagnostic records; radio work continues.</li> <li>A connected terminal that exceeds its bounded output capacity gets an explicit   dropped-byte notice when transmission resumes. Large local file dumps and   recent-repeater listings advance between radio service passes instead.</li> <li>File dumps stop at their initial file size and emit <code>-&gt; EOF</code> only after the   final accepted record. Corrupt stored lines exceeding 640 bytes are omitted   with a visible notice. Recent-repeater output is a live, bounded-cursor view;   incoming packets can change its ordering while it is being printed.</li> <li>Disconnects discard pending old-session text and reset the role's partial   command/listing state. Binary/mOTA transitions suppress pending text notices.   Bytes already transmitted cannot be recalled.</li> <li>Companion frames retain and retry short writes. An mOTA request is admitted   only when its complete, at-most-11-byte record fits.</li> <li>nRF52, UART, and USB-Serial-JTAG behavior is not changed by this native-CDC path.</li> </ul> <p>Host software must also keep reading independently of command writes. A serial relay should start its reader before the first command, use finite write and response deadlines, avoid discarding received packet logs, and cancel I/O during shutdown. A response timeout must not allow a late reply to satisfy another command: the CLI has no transaction identifiers. Updating firmware alone does not correct an indefinite host-side serial write.</p>"},{"location":"usb_serial_backpressure/#regression-checks","title":"Regression checks","text":"<p>Run only one PlatformIO process in the checkout at a time.</p> <pre><code>python test/test_esp32_tinyusb_nonblocking.py\npython test/test_esp32_tinyusb_role_hygiene.py\npython test/test_esp32_tinyusb_cooperative_output.py\npython test/test_esp32_usb_serial_hygiene.py\npython test/test_nrf52_usb_logging_contract.py\npio test -e native -f test_nrf52_debug_output -f test_serial_packet_log -f test_serial_mode_switch -f test_mesh_tables\n</code></pre> <p>The first test compiles the real USB facade against a simulated 64-byte FIFO, including stopped readers, reconnects, protocol transitions, and other-platform fallbacks. Host simulations cannot establish that every real USB driver or endpoint failure has recovered.</p> <p>A Full Station G2 validation build with USA Cascadia radio settings and the Cascade profile can be made using the normal build entry point. The portable <code>standard</code> recipe preserves the deployed partition layout but omits LoRa OTA; it still has the browser firmware uploader. The <code>auto</code>/<code>full</code> recipe instead enables the expanded feature set and partition layout: its merged image is not an app-only update for a device with the legacy layout.</p> <pre><code>MESHDEBUG_OVERRIDE=on PACKET_LOGGING_OVERRIDE=on \\\n  bash build.sh build-firmware Station_G2_repeater --build-profile full \\\n  --radio-preset usa-cascadia --profile cascade\n</code></pre> <p>Before installing on hardware, preserve the device identity, preferences, and existing partition layout. Then verify USB command responses and repeated LoRa logins with the relay running, paused, and stopped, including a host that leaves USB open without reading. Check LoRa recovery separately from USB OUT recovery; fixing transmit backpressure does not prove an unrelated OUT endpoint fault is resolved. Do not erase or repartition the radio as part of this test.</p>"},{"location":"v4_pixel5_font_trial/","title":"Small-screen message fonts","text":"<p>Small-screen Companion builds automatically select a compact font for received message text and the channel/sender line, including <code>Ch 0 Public</code>. SSD1306 and SH1106 OLEDs and the U8g2 T-Echo Card display use this on panels smaller than 160 pixels on both axes. ST7735 TFTs now use their native 160x80 dimensions and normal font. The shared renderer selects by panel dimensions, including rotation:</p> Panel size Font Capital height Line spacing At least 128 x 64, or 64 x 128 rotated; both axes below 160 Squeezed Regular 6 6 pixels 8 pixels Smaller panels, including 72 x 40, 128 x 32 and 64 x 48 Picopixel 5 pixels 7 pixels Either axis at least 160 Normal display font Depends on panel Depends on panel <p>Both fonts allow one pixel for descenders and one blank pixel row between lines. Character widths vary: most letters advance by 4 pixels, with narrow letters taking less space and <code>M</code> and <code>W</code> taking 6 pixels. Squeezed Regular 6 is a public-domain font by Oliver Kraus. Its bitmap data is stored as constants without heap allocation.</p> <p>On a 128 x 64 OLED with the single-button message reader, the compact channel/sender line starts at y=8 and message text at y=16. The header uses the same small font. Five complete 6px-font rows fit above the navigation hint at y=56. The software comparison fits three representative 160-character messages in those five rows. Capacity depends on the characters; messages with many wide letters can still overflow. Text wraps at character boundaries, with <code>...</code> on the last line if necessary. Unsupported characters appear as <code>?</code>. Long channel/sender names are ellipsized to stay on their own line. An enabled channel footer reserves its own space. Readers without the button hint retain the y=14 origin and y=22 message text.</p> <p>On V4 and other single-button builds using this reader, the home screen says <code>hold button: inbox</code>. Hold the user button for about 1.2 seconds to open it. The bottom continuously shows <code>4 &lt;&lt;-  2 &lt;- tap -&gt; 1  -&gt;&gt; 3  hold: Exit</code> without alternating or blinking. Double tap goes to the previous message, one tap advances, three taps select the next channel, and four taps select the previous channel. Channel selection cycles through All, configured channels, and direct messages, starting at the newest message in each filter. The header shows <code>All</code>, <code>Ch N</code>, or <code>DM</code>, including when a channel is empty. Hold to return home; advancing past the last message also returns home. The complete hint fits in the V4's existing 8-pixel footer at y=56, leaving five message rows. The footer keeps the same 6px font, using 108 pixels with 10-pixel margins on the V4. Narrower screens first use the compact <code>hold:X</code> hint without the extra spaces or arrow dashes, then split the same controls across fixed lines. The hint appears even when the inbox is empty. These are button taps. Touchscreen and joystick builds retain instructions appropriate to their controls. During the first eight seconds after startup, holding the button on an ordinary home page enters CLI rescue instead; wait for that startup window to finish before opening the inbox. Exiting a message preview and the WiFi setup page's hold action remain available immediately.</p> <p>The hidden Reader, opened by a long press on the radio page, uses the same button hints. Three taps jump to the first verse of the next chapter; four taps jump to the first verse of the previous chapter. Chapter navigation stops at the beginning and end of the book. It reserves the hint before pagination and resumes saved bookmarks at the page containing the same text, even after the available page size changes.</p> <p>Larger display classes keep their existing font. Menus, Bluetooth PINs and WiFi setup QR codes keep their normal layout. TFT drivers use native panel coordinates; the SenseCAP Indicator retains its existing scaling. The normal OLED font uses 7-pixel letters, 8-pixel line spacing and 6-pixel character advances.</p> <p>The preview buffer holds a complete 160-byte MeshCore message plus its terminator. Previously the main message UI allocated 78 bytes, leaving room for only 77 bytes of text. It still retains 32 previews; larger records add about 2.8 KB of RAM. The firmware RAM guard includes that increase. This history is separate from the offline queue and its mOTA policy.</p> <p>The tiny 72 x 40 T-Echo Card interface now previews the latest received message below its status bar, with three small-font message rows. A button press dismisses it. It stores one full message, and shows <code>...</code> when the screen fills. Incoming text does not replace an active Bluetooth pairing PIN.</p>"},{"location":"v4_pixel5_font_trial/#v4-hardware-trial","title":"V4 hardware trial","text":"<p>Enable <code>platformio.nimble.ini</code> in the ignored <code>platformio.local.ini</code> as shown in the NimBLE trial guide, then run:</p> <pre><code>OUTPUT_DIR=.releases/v4-smallfont bash build.sh build-firmware \\\n  heltec_v4_2_v4_3_companion_radio_full_femon_nimble \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-squeezed6-trial \\\n  --radio-preset usa-cascadia --profile cascade --standard --require-ota\n</code></pre> <p>This build keeps NimBLE, 350 contacts, 40 channels, the V4's 512-frame PSRAM queue, USB mOTA sending and WiFi OTA support. The smaller font is also the default in ordinary small-screen Companion builds from this source. The older <code>_nimble_pixel5</code> environment name remains available, but also uses the automatic 5px/6px selection.</p> <p>Use the application <code>.bin</code> for WiFi OTA. A clean USB install uses the merged image at address 0. When manually writing the application at <code>0x10000</code>, an existing OTA selector may still boot app1. Check the running <code>ver</code> afterward. On the matching V4 16 MB layout only, clearing the 8 KB <code>otadata</code> partition at <code>0xe000</code> selects the newly written app0 without clearing NVS/settings. Confirm the partition table and verify the app write before changing that selector.</p> <p>A custom build can set <code>-D UI_SMALL_MESSAGE_FONT=0</code> to restore the old font and spacing. Remove any explicit <code>UI_MSG_PREVIEW_SIZE</code> flag too if the old preview capacity is desired. These are compile-time options, not CLI commands. No settings erase is necessary when changing between matching V4 layouts.</p>"},{"location":"v4_pixel5_font_trial/#verification","title":"Verification","text":"<pre><code>python3 -B test/test_ssd1306_picopixel.py\npython3 -B test/test_firmware_ram.py\npio test -e native -f test_display_driver -f test_companion_message_history\n</code></pre> <p>The native tests exercise both capital heights, automatic font selection, 160-character messages, complete rows at display edges, long sender lines, navigation hints, reserved footers, overflow markers and tiny/rotated screen geometry. The additional rendering comparison checks all 95 printable ASCII glyphs in each font, under address/undefined-behavior sanitizers. Picopixel is compared pixel for pixel with Adafruit GFX; Squeezed Regular 6 is compared with the upstream BDF fixture independently of the converted C++ tables. This needs a cached PlatformIO Adafruit GFX library; set <code>MESHCORE_GFX_LIBRARY</code> to its directory if needed. It reports a skip when the library is absent. The native tests do not require that dependency. Run only one PlatformIO command at a time.</p>"},{"location":"v4_pixel5_font_trial/#automatic-5px6px-results-2026-09-08","title":"Automatic 5px/6px results, 2026-09-08","text":"<p>Source revision <code>469b47d1</code> passed five representative firmware builds. All five retained the same static RAM usage and startup heap margin as their earlier 5px builds. The four Full profiles also passed required OTA packaging.</p> Hardware/profile Display Selected capital height RAM beyond the required startup budget, bytes V4.2/V4.3 Full NimBLE SSD1306 6 pixels 88,072 T096 Full, FEM on ST7735 6 pixels 24,778 Station G3 ESP32 Full SH1106 6 pixels 82,080 RAK3401 Full SSD1306 6 pixels 46,108 T-Echo Card BLE Companion U8g2, 72 x 40 5 pixels 30,992 <p>The native display/history suites passed 36 tests. The Python font, RAM, pairing, display-profile, queue and QR checks passed 38 tests, including pixel comparisons for all 95 ASCII glyphs in each font. The actual SSD1306 software rendering matches the approved 6px comparison image pixel for pixel.</p> <p>Both <code>NimBLE-V4-VM</code> and <code>NimBLE-V4-Trial</code> were flashed with <code>v1.17.1.5-halo-keymind-cascade-squeezed6-trial-469b47d1</code>. Their partition tables and application hashes were verified, their settings retained, and running versions confirmed. Each passed 201 USB protocol requests without error flags. The Mercerwood V4 reconnected over bonded Bluetooth at MTU 179 and retained the factory-address policy.</p> <p>The XIAO sent a private 160-byte LoRa message to the Mercerwood V4. All bytes arrived, and the V4 stayed responsive through 20 seconds of display refreshes with no uptime reset or error flags. Both temporary channel settings were restored. After that interval the V4 had 147,196 bytes of free internal heap, a minimum of 146,328 bytes, and a largest free block of 139,252 bytes.</p> <p>These are short functional checks. Physical readability remains a user judgment. A message with many wide characters can still need truncation.</p> <p>V4 application size: 1,778,936 bytes (1,152 bytes larger than the earlier 5px trial). SHA-256: <code>8e6797b90741bf013b3757668e5a23378ac8c0b0ed9c75830939f13305c56a68</code>.</p>"},{"location":"v4_pixel5_font_trial/#earlier-5px-hardware-and-build-results-2026-09-08","title":"Earlier 5px hardware and build results, 2026-09-08","text":"<p>Source revision <code>eeea15ef</code> passed seven representative firmware builds:</p> Hardware/profile Display RAM beyond the required startup budget, bytes V4.2/V4.3 Full NimBLE Picopixel SSD1306 88,072 T096 Full, FEM on ST7735 24,778 Station G3 ESP32 Full SH1106 82,080 RAK3401 Full SSD1306 46,108 Wireless Tracker Full NimBLE capacity trial ST7735 28,022 Wio Tracker L1 Full SH1106 45,744 T-Echo Card BLE Companion U8g2 30,992 <p>These are linked-capacity checks before runtime allocation, not live free heap measurements. The six Full profiles also passed their required OTA packaging checks. The T-Echo Card row is a BLE Companion build.</p> <p>Both physical V4.3 nodes, <code>NimBLE-V4-VM</code> and <code>NimBLE-V4-Trial</code>, were flashed, their image hashes verified, and their running versions confirmed. Each passed 201 USB protocol requests with zero reported error flags. The Mercerwood V4 also reconnected over authenticated, bonded Bluetooth with MTU 179 and the existing factory-address policy.</p> <p>A private XIAO-to-V4 LoRa test delivered all 160 message bytes. The V4 continued responding during 20 seconds of message redraws, with zero error flags. Both temporary channel configurations were restored. Free internal heap after that interval was 147,200 bytes, minimum 146,340 bytes, and the largest free block was 139,252 bytes. These are short functional checks; physical readability remains a user judgment.</p> <p>A matching pre/post-boot Mercerwood measurement showed the longer preview using 2,816 additional PSRAM bytes, with unchanged internal free heap. Boards without PSRAM use their ordinary RAM for the larger preview records.</p> <p>The native display/history suites passed 31 tests. The Python font, RAM, pairing, display-profile, queue and QR checks passed 38 tests. The Adafruit comparison covers all 95 printable ASCII glyphs.</p> <p>V4 application SHA-256: <code>d914d80124b499d7b719f8427f3794ab1b6d15fd0112e3ef89ba2fac26b5a974</code>.</p>"},{"location":"releases/1.17.1.5-doc-audit/","title":"Markdown audit \u2014 1.17.1.5 USA Cascade","text":"<p>Audited on 2026-09-05 against firmware source <code>26303793</code>, the resolved build configuration, and the qualified 1.17.1.5 staging manifests. The scope was all 71 tracked Markdown files present at the start, including root documents, docs, examples, tools, tests, variants, and vendored library documentation. Generated/ignored build directories and external repositories were outside that scope.</p>"},{"location":"releases/1.17.1.5-doc-audit/#corrections","title":"Corrections","text":"<ul> <li>Added role-specific feature switches, exact   Companion/infrastructure MQTT and logging controls, board exceptions, SNMP,   and the USB web console.</li> <li>Added an exact-name variant map; every one of its   1,325 covered entries resolves to a staged firmware file. The 36 excluded   entries are identified rather than linked to substitute hardware.</li> <li>Corrected universal 254-neighbor claims, Full Companion MQTT filename/CLI   assumptions, TLora Full WebConfig availability, and partition/NVS guidance.</li> <li>Documented the power-saving guards present at audit time; current instructions   now use the shared <code>get powersaving</code> / <code>set powersaving on|off</code> command set.   Corrected the RS232 baud range and SNMP environment list.</li> <li>Linked OTAFIX 2.4.6 and its board/storage requirements from operator guides;   aligned the two manual USA OTA quickstarts with 910.525 MHz.</li> <li>Marked old provider catalogs and dated hardware results as historical;   documented the legacy tag workflow that also matches <code>repeater-room-*</code>.</li> <li>Fixed the vendored MQTT documentation link and documentation-site links   that incorrectly treated repository source files as generated site pages.</li> </ul>"},{"location":"releases/1.17.1.5-doc-audit/#verification-and-limits","title":"Verification and limits","text":"<p>All original Markdown files were scanned for relative links, section anchors, source-path references, version/default claims, and role/OTA terminology. Flagged operator instructions were checked against CommonCLI, its observer extension, Companion command handlers, board configuration, and release manifests. Brace-expanded source references and SDK-relative paths were retained as such. Historical measurements, changelogs, upstream findings, contribution/security policies, and licenses were not rewritten as new validation results.</p> <p>The documentation site passed a strict MkDocs Material build. Relative repository links and section anchors were checked separately, including documents outside the MkDocs source directory. Console and current bootloader links were checked on their primary sites. This was not a crawl of every third-party URL or a new hardware/firmware qualification; no claim is made that every board was physically tested or every protocol statement independently re-proved.</p>"},{"location":"releases/1.17.1.5-doc-audit/#original-file-coverage","title":"Original file coverage","text":"<p>\u201cRetained\u201d means no correction was identified by this documentation audit; it does not certify all historical statements as current hardware behavior.</p> File Disposition AGENTS.md Scanned; retained ALERTS.md Scanned; retained CHANGELOG.md Historical record retained CONTRIBUTING.md Scanned; retained MEMORY_MONITORING.md Scanned; retained MQTT_IMPLEMENTATION.md Corrected or clarified MQTT_INTERNALS.md Corrected or clarified MQTT_OWNERSHIP.md Historical record retained MQTT_SNMP.md Corrected or clarified README.md Corrected or clarified RELEASE.md Corrected or clarified RESTORE_UPSTREAM_NOTES.md Historical record retained SECURITY.md Scanned; retained STABILITY_TESTABILITY_HANDOFF.md Historical record retained UPSTREAM_BUGS.md Scanned; retained WEB_CONFIG_REVIEW.md Corrected or clarified arch/stm32/Adafruit_LittleFS_stm32/README.md Vendored documentation/license retained arch/stm32/Adafruit_LittleFS_stm32/src/littlefs/LICENSE.md Vendored documentation/license retained arch/stm32/Adafruit_LittleFS_stm32/src/littlefs/README.md Vendored documentation/license retained docs/WiFi.md Corrected or clarified docs/cli_build_matrix.md Corrected or clarified docs/cli_command_availability.md Corrected or clarified docs/cli_commands.md Corrected or clarified docs/companion_offline_queue.md Scanned; retained docs/companion_protocol.md Scanned; retained docs/companion_radio_full.md Corrected or clarified docs/docs.md Scanned; retained docs/esp32_memory_budget.md Scanned; retained docs/faq.md Corrected or clarified docs/filter_tool.md Scanned; retained docs/firmware_picker.md Corrected or clarified docs/flood_filtering.md Scanned; retained docs/full_companion_features.md Corrected or clarified docs/full_companion_usb_switcher.md Corrected or clarified docs/gps_tracking.md Scanned; retained docs/halo_keymind_settings.md Corrected or clarified docs/hardware_validation_checklist.md Corrected or clarified docs/host_cli_service.md Scanned; retained docs/index.md Corrected or clarified docs/kiss_modem_protocol.md Scanned; retained docs/lora_ota_automation.md Corrected or clarified docs/mbedtls-tls-footprint.md Scanned; retained docs/nrf52_companion_storage_recovery.md Scanned; retained docs/nrf52_power_management.md Scanned; retained docs/number_allocations.md Scanned; retained docs/ota_easy.md Corrected or clarified docs/ota_meshtower_v2_sdcard.md Corrected or clarified docs/ota_nrf52_bootloader_update.md Corrected or clarified docs/ota_nrf52_qspi.md Corrected or clarified docs/ota_protocol.md Corrected or clarified docs/ota_user_guide.md Corrected or clarified docs/packet_format.md Scanned; retained docs/payloads.md Scanned; retained docs/qr_codes.md Scanned; retained docs/rak3401_mota_chain.md Historical record retained docs/releases/1.17.1.5.md Corrected or clarified docs/spiffs_regular_file_reads.md Scanned; retained docs/stats_binary_frames.md Scanned; retained docs/telemetry_decoder.md Scanned; retained docs/terminal_chat_cli.md Scanned; retained docs/usb_serial_backpressure.md Scanned; retained examples/host_cli_service/README.md Scanned; retained lib/PsychicMqttClient/CHANGELOG.md Vendored documentation/license retained lib/PsychicMqttClient/README.md Corrected or clarified mesh-america/README.md Corrected or clarified test/README.md Scanned; retained test/test_mqtt_prefs_codec/FIXTURES.md Historical record retained tools/mota/README.md Scanned; retained tools/sensecap_indicator_font/README.md Scanned; retained tools/sensecap_indicator_rp2040/README.md Scanned; retained variants/sensecap_indicator-espnow/README.md Scanned; retained"},{"location":"releases/1.17.1.5/","title":"MeshCore 1.17.1.5 Dev - USA Cascade","text":"<p>Use feature switches by role for exact on/off commands for Companion, Repeater, Room Server, and Sensor, including MQTT, logging, power saving, GPS, and board exceptions. Open the USB web console for the default ASCII terminal on Full Companion and infrastructure images.</p> <p>The firmware identifier and main release tag follow <code>v1.17.1.5-halo-keymind-cascade-dev-&lt;commit&gt;</code>, matching the 1.17.1.4 naming convention. Supplemental pages retain the <code>repeater-room-</code>, <code>utility-</code>, <code>logging-</code>, <code>lora-ota-</code>, and <code>full-profiles-</code> prefixes where those outputs exist. The Companion page is marked Latest; the supplemental pages remain development prereleases.</p> <p>This release uses the USA/Canada radio preset and Cascade runtime defaults. The release build records the resolved frequency, bandwidth, spreading factor, and coding rate. The offline USA Cascadia fallback is 910.525 MHz, BW62.5, SF7, CR5. Saved node settings survive ordinary firmware updates.</p>"},{"location":"releases/1.17.1.5/#memory-corrections-in-aa20e927","title":"Memory corrections in <code>aa20e927</code>","text":"<p>All 583 published profiles (the 540-profile matrix plus 43 supplemental Full repeaters) were checked against the new runtime RAM policy. All 11 failing profiles have replacements, and the same queue sharing has been applied to the other 41 nRF52 Full profiles: 52 corrected profiles in total, initially built from <code>aa20e927</code>. The existing release tags stay in place; corrected filenames end in <code>aa20e927</code>, except Wireless Paper Full's capacity-restoring follow-up, <code>1e4d1e16</code>. Companion remains Latest. Both Mesh America catalogs and the firmware picker point to the replacement files.</p> <p>All 43 nRF52 Full Companions keep 256 offline frames normally and lend 128 slots to mOTA while needed. Wireless Paper Full now also shares its queue and keeps 350 contacts and 40 channels. The other six corrected ESP32 Full profiles below use 150 contacts, preserving their 256-frame queue and Full transports. Export contacts before upgrading if you have more than 150; entries beyond that limit may be unavailable and a later save may omit them. This warning applies to those six profiles and the superseded <code>aa20e927</code> Wireless Paper image.</p> <p>Wireless Paper Full's <code>1e4d1e16</code> update has 256 message slots normally and 128 while an mOTA session borrows its workspace. Idle WiFi listening leaves all 256 slots available. If more than 128 unread messages are queued, sync them with an app before starting mOTA. Source stop/disconnect restores all 256 slots and frees ESP32 scratch buffers. USB, Bluetooth, WiFi, the display and the partition layout are retained. The application is 1,869,976 bytes; use its app-only <code>.bin</code> for a compatible WiFi update, or its merged image for USB installation.</p> <p>The T096 and T1 LoRa OTA repeater corrections allocate the diagnostic manual staging buffer only when requested, recovering about 4 KiB at startup. Ordinary mOTA uses its existing staging store. <code>ota dev clear</code> releases a manual stage; allocation failure reports an error before writing. These same-version repairs require an explicit exact-target manual LoRa installation or USB; forward-only trusted autoinstall does not select an equal-version repair.</p> <p>Available RAM below means capacity before startup allocations, not free heap after boot. The Wireless Paper row includes its latest <code>1e4d1e16</code> update:</p> Failing original profile Original bytes Replacement bytes Required bytes <code>Generic_ESPNOW_companion_radio_full</code> 101,920 139,456 136,192 <code>Heltec_Wireless_Paper_companion_radio_full</code> 150,144 161,336 152,576 <code>Heltec_Wireless_Tracker_companion_radio_full</code> 148,496 186,032 169,986 <code>Heltec_ct62_companion_radio_full</code> 99,104 136,640 136,192 <code>Heltec_t096_companion_radio_full_femon</code> 54,724 74,060 73,728 <code>Heltec_t1_companion_radio_full</code> 55,044 74,380 73,728 <code>Heltec_v3_companion_radio_full</code> 143,840 181,376 173,056 <code>Xiao_C3_companion_radio_full</code> 98,880 136,416 136,192 <code>heltec_tracker_v2_companion_radio_full_femon</code> 133,136 170,672 169,986 <code>Heltec_t096_repeater_lora_ota_no_external_sensors</code> 61,588 65,676 65,538 <code>Heltec_t1_repeater_lora_ota_no_external_sensors</code> 61,964 66,052 65,538 <p>Each replacement has a matching <code>.memory.json</code> with its ELF hash, RAM budget and firmware-file hashes. The complete audit distinguishes original binary/log calculations from new ELF checks. All 52 exact firmware builds, their native file pairs, and 150 native mOTA tests passed, alongside memory, allocation-failure, shared-queue and picker regressions. Wireless Paper's follow-up also passed complete TCP mOTA transfers with address/leak sanitizers, repeated disconnects, queue-full refusal, idle listening and USB/TCP ownership changes. Physical boot/load/soak validation remains pending.</p>"},{"location":"releases/1.17.1.5/#g3-usb-disappearance-with-power-saving-enabled","title":"G3 USB disappearance with power saving enabled","text":"<p>The published <code>26303793</code> firmware has an ESP32 native-USB sleep bug that matches a Station G3 report: USB disappears from the connected Pi after a few minutes, the display button stops responding, but the repeater still answers over LoRa. Hardware confirmation of this report is pending.</p> <p>Cascade enables device power saving by default on fresh settings. After two minutes, the repeater can enter light sleep when no serial terminal is open, even though the Pi has enumerated the USB device. Light sleep stops USB service; the radio GPIO can still wake the CPU, while the G3 display button is only polled. Closing a terminal must not be treated as unplugging the USB host. Espressif documents the underlying native USB sleep limitation.</p> <p>To enable USB logging on an ESP32 1.17.1.5 image with logging support, disable power saving first. Use the role's text terminal, or the repeater's remote admin CLI if USB has already disappeared:</p> <pre><code>set powersaving off\nset usb.logging on\nget powersaving\nget usb.logging\n</code></pre> <p>The read-back commands should report power saving <code>off</code> and USB logging <code>on</code>. For an image without USB logging, use just <code>set powersaving off</code> and <code>get powersaving</code> to apply/check the sleep workaround. Disabling power saving saves the setting and takes effect immediately; it does not erase the node or change LoRa RX power saving (<code>radio.rxps</code>). If USB does not reappear after disabling sleep remotely, power-cycle once and check that the port and display button remain usable beyond the two-minute mark. Ordinary reflashing can retain the saved power-saving setting, so check it during comparisons with another firmware build too.</p> <p>On unified Full infrastructure, also run <code>set powersaving off</code> before enabling USB through <code>set logging.output usb</code> or <code>set logging.output both</code>. These are separate commands. Turning logging off does not automatically restore the saved power-saving setting. nRF52 logging does not need this ESP32 workaround.</p> <p>WiFi/MQTT-only logging does not need <code>set powersaving off</code> while the Repeater/Room Server MQTT bridge is running. The original <code>26303793</code> code already prevents device sleep in that state. Select <code>set logging.output wifi</code> where supported and check <code>get mqtt.running</code>; <code>get mqtt.enabled</code> alone only checks the saved preference. MQTT-capable Full Companion now uses the same <code>mqtt.enabled</code> and <code>logging.output</code> commands as infrastructure. Disabling MQTT preserves broker settings; the MQTT tab exposes the same master switch.</p> <p>The source correction keeps native USB serviced while a host is enumerated, including when its terminal is closed. Enabled live USB logging also blocks ESP32 light sleep, even without a host. FreeRTOS can still idle/yield; this does not disable the saved power-saving setting or Companion CPU scaling. With logging off, USB power from a charger still permits sleep.</p> <p>The corrected G3 uses its user button as a light-sleep wake source alongside LoRa. Button activity keeps the CPU and display awake for at least two minutes; holding or pressing the button again extends the interval. The usual display timeout can keep the screen on longer. An intentional long-press power-off retains its existing action. After the wake interval, sleep is allowed when power saving is enabled, logging is off, no native USB host is attached, and no running bridge or pending work needs service.</p> <p>Host simulations cover both native USB modes, terminal close/reconnect, logging toggles, OTA inhibition, simultaneous button/LoRa wake configuration, and the two-minute interval across timer rollover. The Station G3 repeater download remains the original <code>26303793</code> build; continue to use the logging workaround above on that image.</p>"},{"location":"releases/1.17.1.5/#t096-full-companion-bluetooth-and-menu-freeze-report","title":"T096 Full Companion Bluetooth and menu freeze report","text":"<p>A report against <code>Heltec_t096_companion_radio_full_femon</code> describes no usable Bluetooth despite a displayed PIN, followed by a freeze while stepping through the device menu. Reflashing both with and without a full wipe gave the same result. The exact freeze and Bluetooth behavior still need confirmation on a physical T096 with the source correction below.</p> <p>The published <code>26303793</code> Full image leaves only 54,724 bytes (53.4 KiB) between the linked heap boundaries. Its static RAM check did not account for the allocations made at startup: the 160x80 color framebuffer alone needs 25,602 bytes, followed by task stacks, the packet pool, filesystem buffers, and message previews. This leaves inadequate runtime headroom. The pinned Bluefruit library also ignores failure to create its BLE/SOC worker tasks, and the sensor menu could write through a failed CayenneLPP allocation. Those are code paths consistent with this report; a PIN is not proof of a working Bluetooth radio.</p> <p>The correction applies to every nRF52 Full Companion, keeping its offline queue at 256 frames during normal use. mOTA borrows the upper 128 slots for its roughly 19 KiB session state only when needed, leaving 128 message slots during mOTA use. Starting a source or a TempRadio discovery session acquires this workspace. Stopping or disconnecting the USB/Bluetooth source restores all 256 slots, even if the temporary radio window is still open. A discovery-only session returns the slots when its TempRadio window ends. No heap resizing is involved.</p> <p>Unread messages keep their order across both transitions. If more than 128 frames are pending, mOTA refuses to start and asks you to sync unread messages with a Companion app first; it does not discard them to make room. OTA configuration and signer keys survive reuse of the workspace. While mOTA owns it, the normal queue overflow policy applies to the remaining 128 slots.</p> <p>The T096 profile requires at least 72 KiB of heap space at link time. It retains 350 contacts, 40 channels, the color display, sensors, USB, Bluetooth, Bluetooth DFU, and USB/Bluetooth mOTA sending. This reserve is space for runtime allocations, not a measurement of free heap after boot. Bluetooth startup now checks both worker tasks and all registered services; a failed partial initialization does not repeat every five seconds. The sensor page reports low memory if its buffer could not be allocated.</p> <p>Regression tests transfer complete mOTA containers through the actual shared context, check queue wraparound and message order, and cover source stop, disconnect, conflicting USB/Bluetooth ownership and repeated sessions. They also inject worker-task and GATT-service failures, verify that retries do not initialize the stack again, open the sensor path with a failed allocation, and use the real linker assertion to reject the old heap budget. The original T096 Full download has been replaced by the corrected <code>aa20e927</code> image on the same release page. Another wipe is not a fix for the old compiled memory budget.</p> <p>For the corrected T096 build, use its matching application UF2 through the existing USB bootloader. Preserve the bootloader and node data. Check Bluetooth discovery, pairing and message exchange on battery power and with USB attached; then step through every menu page, return from screen-off, and check USB and Bluetooth mOTA sending. Hardware validation is pending.</p>"},{"location":"releases/1.17.1.5/#firmware-roles-and-update-support","title":"Firmware roles and update support","text":"<p>Use the exact board's Full Companion image when available. Every Full Companion must pass linked-firmware checks for MOTA sending, its text terminal, and the platform's source transports. ESP32 supplies USB and WiFi sources; nRF52 supplies USB and encrypted Bluetooth sources. Full Companions remain USB-updateable and do not require LoRa self-installation. Optional ESP32 WiFi self-update uses port 8080 where the existing partition layout has two application slots; nRF52 retains Bluetooth DFU with a compatible bootloader.</p> <p>Read Full Companion feature switches for on/off commands, USB logging, power saving, WiFi/Bluetooth selection, GPS, MQTT, MOTA sending, and update directions.</p> <p>Infrastructure artifacts must have a verified wireless self-update path. Option 3 reports and omits infrastructure on platforms without a wireless updater. The report is <code>ota-excluded-targets.txt</code>. Source/seeder capability alone does not count as self-update support. ESP32 qualification checks both application slots and OTA metadata; nRF52 Bluetooth qualification checks the linked DFU service and its application ZIP. LoRa installation on nRF52 still requires the exact matching OTAFIX bootloader and storage arrangement.</p> <p>Classic ESP32 capacity limits are recorded in each artifact's capability manifest. Generic E22, Heltec V2, Meshadventurer, and T-Beam OTA repeaters, plus the TLora MQTT repeater, use 50 neighbors where needed to preserve the required internal RAM reserve. T-Beam MQTT repeater profiles retain the full rule engine with 31 flood rules; constrained classic ESP32 ESP-NOW bridges with logging use 47. Meshadventurer Full uses 100 contacts, 30 group channels, and a 16-frame offline queue while retaining its MOTA and transport features.</p> <p>Since 1.17.1.4, this branch also includes USB session and contact-persistence fixes, automatic nRF52 ExtraFS recovery, improved Indicator setup/display handling, compressed MOTA transport, and measured ESP32 memory limits. Qualified internal-flash nRF52840 receivers now reserve 64 KiB of retained RAM to extend application MOTA staging beyond the available flash prefix. This handoff requires the exact board's OTAFIX 2.4.6 bootloader. Install that bootloader before relying on LoRa updates from these new hybrid receiver images: they reject application containers larger than one flash page when the installed bootloader lacks the retained-RAM capability. QSPI/microSD roles and Full Companions retain their existing storage layouts. An interrupted hybrid download must be fetched again after an application restart or power cycle. See the protocol for the exact admission and reset checks.</p>"},{"location":"releases/1.17.1.5/#build-using-option-3","title":"Build using option 3","text":"<p>The equivalent reproducible command is:</p> <pre><code>OUTPUT_DIR=.releases/1.17.1.5-halo-keymind-cascade-dev \\\nbash build.sh build-firmwares-logging-matrix \\\n  --firmware-version v1.17.1.5-halo-keymind-cascade-dev \\\n  --radio-preset usa-cascadia --profile cascade \\\n  --require-ota --skip-kiss --resume --background\n</code></pre> <p>Or run <code>bash build.sh</code>, select option 3, set version <code>v1.17.1.5-halo-keymind-cascade-dev</code>, and retain USA Cascadia/Cascade. Option 3 enables the infrastructure OTA requirement by default. It merges supported runtime USB logging into canonical artifacts and builds the expanded ESP32 profiles. It runs one PlatformIO process at a time.</p> <p>The background launcher prints its persistent log and status paths. Each target also gets a log in <code>OUTPUT_DIR/build-logs/</code>. Resume accepts only artifacts with the current capability schema and a successful qualification; infrastructure also needs a verified update method. Any failed target leaves the matrix unsuccessful and must be resolved before publication.</p> <p><code>--allow-no-ota</code> is an explicit development override for cable-only infrastructure. Those outputs do not belong in this OTA-required release. Use a separate output directory when changing the radio or settings profile. Use a fresh release output directory after changing the source revision or firmware version so packaging cannot mix old and new binaries.</p>"},{"location":"releases/1.17.1.5/#local-release-staging","title":"Local release staging","text":"<p>After the matrix completes successfully, <code>scripts/package_cascade_release.py</code> groups the qualified images using the previous GitHub release naming. Each group includes the firmware files, capability manifests, TSV/JSON inventory, checksums, build notes, and Full Companion directions. The staging directory's root <code>FIRMWARE-PICKER-1.17.1.5.html</code> opens the local downloads; the copies inside each release group use the planned GitHub download URLs. Staging does not push commits, create remote tags, or publish a GitHub release.</p>"},{"location":"releases/1.17.1.5/#published-release-set-and-small-slot-heltec-v4-updates","title":"Published release set and small-slot Heltec V4 updates","text":"<p>The capability JSON and target inventories now report both Bluetooth DFU and LoRa mOTA for all 60 nRF52 receiver profiles. The original report omitted the nRF52 LoRa method. Each affected manifest includes <code>ota_update_requirements.lora</code> with its storage type, accepted package types, exact-base requirement for deltas, and the matching OTAFIX bootloader link. Internal-flash receivers accept in-place deltas; supported QSPI/SD receivers also accept full application packages. The 20 retained-RAM receivers require OTAFIX 2.4.6's matching handoff support. These reports verify the released application bytes and storage layout; they do not certify the bootloader installed on a physical device. Firmware binaries and tags are unchanged. Full Companion mOTA sending remains separate from self-update capability.</p> <p>Published firmware tags remain at source commit <code>26303793</code>. Documentation can advance independently. The original matrix qualified 540 profiles (1,080 firmware files) from 551 attempts; 11 oversized portable attempts have expanded Full replacements. The variant map maps all 1,361 previous-release choices to 1,325 covered choices and 36 excluded entries. Multiple old choices map to the same current artifact.</p> <p>For Heltec V4 with an existing compatible 1.25 MiB OTA application slot, the standard <code>heltec_v4_repeater</code> application is 1,179,200 bytes and the lean <code>heltec_v4_repeater_lora_ota_no_external_sensors</code> application is 1,232,024 bytes. Both fit that slot. Start the WiFi uploader with <code>start ota ap</code>, join <code>MeshCore-OTA</code>, and open <code>http://192.168.4.1/update</code>. Upload the application <code>.bin</code>; use <code>stop ota</code> to close an unused uploader. Their merged USB installers write two 6.25 MiB application slots. Expanded Full V4 applications require the larger layout and do not fit a 1.25 MiB slot.</p> <ul> <li>Companion firmware</li> <li>Repeater and Room Server firmware</li> <li>Sensor firmware</li> <li>LoRa OTA repeater firmware</li> <li>Expanded Full infrastructure</li> </ul>"},{"location":"releases/1.17.1.6/","title":"MeshCore 1.17.1.6 Dev - USA Cascade","text":"<p>This release builds the current <code>keymindCascade</code> source after repairing the unit-test regressions. Its firmware identifier is <code>v1.17.1.6-halo-keymind-cascade-dev-&lt;commit&gt;</code>. The recorded commit identifies the source for every firmware file; binaries from earlier releases are not reused.</p> <p>Use the firmware picker to match the exact board, radio, display and flash variant. The Companion release is marked Latest. Supporting release pages retain the <code>repeater-room-</code>, <code>utility-</code>, <code>logging-</code>, <code>lora-ota-</code> and <code>full-profiles-</code> prefixes where those outputs exist, and remain development prereleases.</p> <p>The build uses the USA/Canada radio preset and Cascade runtime defaults. Build records include the resolved radio settings; the offline USA Cascadia fallback is 910.525 MHz, BW62.5, SF7, CR5. Ordinary updates retain saved node settings.</p>"},{"location":"releases/1.17.1.6/#published-matrix","title":"Published matrix","text":"<p>The GitHub release contains 553 qualified firmware profiles across five release pages. The initial matrix completed all 565 attempts: 537 passed, 16 failed, and 12 standard ESP32 profiles exceeded the 1.25 MiB portable slot. All 16 failures have passing repair builds; all 12 portable exclusions have qualified expanded Full alternatives. Smaller profiles that fit remain available.</p> <p>The initial firmware uses <code>306feebe</code>, the 14 nRF52 repairs use <code>283acd27</code>, and the two Tracker MQTT repairs use <code>1274956f</code>. Each firmware filename and target manifest records its source. Existing firmware assets and release tags were preserved when the repairs were added.</p> <p>See the failure and repair report and portable-profile exclusions. Full alternatives require their matching expanded partition layout; they do not fit a deployed 1.25 MiB slot.</p>"},{"location":"releases/1.17.1.6/#two-lora-profiles","title":"Two LoRa profiles","text":"<p><code>radio2</code>, <code>tempradio2</code>, <code>radioat2</code> and <code>tempradioat2</code> add a second profile to LoRa-equipped Companion, Repeater, Room Server, Sensor and terminal firmware. The second profile starts disabled. It supports receive-only or receive/transmit operation, separate retry ownership and backoff, and explicit off commands.</p> <p>One transceiver alternates between at most two active profiles. Reception and transmission occupy that transceiver, so a packet on one profile interrupts listening on the other. This does not provide two simultaneous receivers.</p> <p>By default, traffic can cross between two permanent profiles or two temporary profiles. A permanent/temporary pair stays isolated. <code>radio2.cross auto|on|off</code> controls this policy; receive-only still forbids transmission on profile 2. <code>tempradio2</code> can carry LoRa OTA traffic while the primary profile remains available between packets. Use a firmware profile that supports the required OTA role.</p> <p>Radio commands accept an optional trailing preamble, and their getters include the effective preamble. Automatic preambles round up in steps of eight. Paired with SF7/BW62.5/preamble 32, the automatic BW500 values are 48 symbols at SF9, 88 at SF8 and 120 at SF7. Configure transmitters with matching preambles too.</p> <p>Dual-profile receive uses normal RX with the slower profile visited first. RX power saving and device sleep are suspended while scanning, then the saved settings apply again in single-profile mode. See the setup guide and command matrix and hardware measurements.</p>"},{"location":"releases/1.17.1.6/#other-changes-since-11715","title":"Other changes since 1.17.1.5","text":"<ul> <li>Restores <code>set path.hash.mode 0|1|2</code> on infrastructure firmware, with CLI   dispatch and get/set regression coverage. Unsupported <code>extra.sf</code> commands   report an explicit error on radios without that capability.</li> <li>Uses received MeshCore packets to feed the repeater RX watchdog. Fresh   settings default to 24 hours; temporary primary-radio sessions lasting at   least 12 hours use 12 hours, while shorter sessions disable that watchdog.   Temporary-session adverts and watchdog settings revert when the session ends   or the node reboots. See CLI commands.</li> <li>Adds separate battery and USB display modes, with timeouts in seconds.   Companion inbox settings distinguish retained history, pending delivery and   the local unread count. Read previews remain browseable in Unread mode.</li> <li>Includes native-USB sleep/wake corrections, nRF52 USB startup fixes,   receive recovery and noise-calibration improvements, and the reviewed   ExpressLRS board/power changes.</li> <li>Consolidates redundant Full infrastructure builds while retaining useful   smaller-slot variants. Full profiles and smaller portable images continue   to require their matching partition and update method.</li> </ul> <p>Feature switches and update commands are documented in feature switches by role, Full Companion features and the ESP-NOW bridge guide.</p>"},{"location":"releases/1.17.1.6/#validation-and-installation","title":"Validation and installation","text":"<p>The release is gated on the unit-test workflow for its source commit. CI repairs replace stale display assertions with compiled tests of bookmark saves across battery/USB transitions and message summaries in each inbox mode. The sleep harness checks both MQTT and dual-profile scanning.</p> <p>The release packager checks each published profile's capability manifest, firmware-file hashes, native file pairs and runtime RAM budget. Infrastructure must have a verified wireless update path. The target manifests and exclusion report describe the actual published matrix; a build check is not a physical-board test.</p> <p>Dual-profile timing was measured on a Heltec V4 with a XIAO ESP32-S3/Wio LoRa transmitter. Finite strong-signal tests and an OTA catalogue exchange passed; these tests do not establish weak-signal performance, simultaneous traffic reliability, a complete hardware OTA installation, or months of uptime.</p> <p>ESP32 WiFi updates use the application <code>.bin</code>. The <code>-merged.bin</code> image includes boot and partition data for USB installation. nRF52 uses the board's <code>.uf2</code> or native application DFU <code>.zip</code>; LoRa OTA also needs the exact destination package and a compatible OTAFIX bootloader. Check the per-profile capability manifest before choosing an update method.</p>"},{"location":"releases/1.17.1.6/#reproduce-the-release","title":"Reproduce the release","text":"<p>Follow-up builds repair the constrained profiles without relaxing qualification:</p> <ul> <li>nRF52 repeaters use <code>-Os</code> instead of <code>-Ofast</code>, retaining their sensor drivers   and protocol features while reducing flash use.</li> <li>T096 and T1 LoRa OTA repeaters retain their board-defined 50 neighbors and   use 16 flood-rule slots. The complete rule engine, color display, GPS and OTA   remain enabled. The T096's available startup heap rises from 72,492 to 81,468   bytes, and the T1's from 72,868 to 81,844 bytes. Required startup allocations   fall from 88,410 to 79,010 bytes. These are linked capacity checks, not soak   measurements. Full Companion capacities are unchanged.</li> <li>Tracker v1.1 and v2 Full MQTT repeaters retain their board-defined 50   neighbors so the color display, MQTT/TLS and OTA fit in internal RAM.   Their radio, display, sensor and update features remain enabled; ordinary   Tracker repeater and Companion capacities are unchanged. Tracker v2's   available startup heap rises from 184,640 to 222,992 bytes against the   unchanged 190,386-byte requirement. Both corrected Tracker profiles pass.</li> <li>Size-failure detection keeps its temporary output log outside PlatformIO's   build tree, so SCons cleanup cannot erase the evidence needed by the measured   size fallback. CI exercises cleanup, ordinary compiler failures and log errors.</li> </ul> <p>Use a clean checkout of the release commit and a fresh output directory:</p> <pre><code>OUTPUT_DIR=.releases/1.17.1.6-halo-keymind-cascade-dev \\\nbash build.sh build-firmwares-logging-matrix \\\n  --firmware-version v1.17.1.6-halo-keymind-cascade-dev \\\n  --radio-preset usa-cascadia --profile cascade \\\n  --require-ota --skip-kiss --resume --background\n</code></pre> <p>Run only one PlatformIO process in that checkout. Let the matrix finish even when individual targets fail. The packager normally requires a successful full matrix. For an initial release with gaps, <code>scripts/package_cascade_release.py</code> accepts <code>--allow-partial</code> with <code>--version 1.17.1.6</code>, the original completed build status and source commit. It lists every failed attempt in <code>BUILD-FAILURES.md</code> and <code>BUILD-FAILURES.json</code>; each published file must still pass all qualification and memory checks. Repair the failures and add the corrected profiles afterward. <code>PORTABLE-PROFILE-EXCLUSIONS.md</code> and <code>.json</code> separately list standard ESP32 profiles that exceed the 1.25 MiB slot and are redirected to the expanded Full pass. Those size deferrals are not compiler failures. Qualified smaller images remain available; Full alternatives require their matching partition layout.</p>"}]}
\ No newline at end of file