dandri/HaloKeymind
1
0 Fork 0
mirror of https://github.com/mikecarper/MeshCore.git synced 2026-10-29 16:12:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

deploy: b4096901eb

Browse Source
This commit is contained in:
mikecarper committed 2026-08-14 06:48:44 +00:00
1 parent 3404bc06de
commit d7cdeb07c0
2 files changed
+173 -321
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

rak3401_mota_chain/index.html
+172 -320
View File
@@ -938,10 +938,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#withdrawn-second-v11701-candidate" class="md-nav__link">
<a href="#exact-destination" class="md-nav__link">
<span class="md-ellipsis">
Withdrawn second v1.17.01 candidate
Exact destination
</span>
</a>
@@ -949,10 +949,10 @@
</li>
<li class="md-nav__item">
<a href="#requirements-for-the-next-chain" class="md-nav__link">
<a href="#what-was-tested" class="md-nav__link">
<span class="md-ellipsis">
Requirements for the next chain
What was tested
</span>
</a>
@@ -960,10 +960,10 @@
</li>
<li class="md-nav__item">
<a href="#withdrawn-v11702-chain-smoke-test-result" class="md-nav__link">
<a href="#host-requirements" class="md-nav__link">
<span class="md-ellipsis">
Withdrawn v1.17.02-chain smoke-test result
Host requirements
</span>
</a>
@@ -971,10 +971,10 @@
</li>
<li class="md-nav__item">
<a href="#recover-the-lab-rak" class="md-nav__link">
<a href="#verify-the-release-offline" class="md-nav__link">
<span class="md-ellipsis">
Recover the lab RAK
Verify the release offline
</span>
</a>
@@ -982,10 +982,10 @@
</li>
<li class="md-nav__item">
<a href="#intended-runner-safety-behavior" class="md-nav__link">
<a href="#direct-recoverable-bench-run-bw500sf5" class="md-nav__link">
<span class="md-ellipsis">
Intended runner safety behavior
Direct recoverable bench run: BW500/SF5
</span>
</a>
@@ -993,10 +993,10 @@
</li>
<li class="md-nav__item">
<a href="#host-and-radio-requirements" class="md-nav__link">
<a href="#live-deployment-with-two-intermediate-relays-bw250sf5" class="md-nav__link">
<span class="md-ellipsis">
Host and radio requirements
Live deployment with two intermediate relays: BW250/SF5
</span>
</a>
@@ -1004,10 +1004,10 @@
</li>
<li class="md-nav__item">
<a href="#verify-without-touching-a-radio" class="md-nav__link">
<a href="#guarded-no-endf-rescue" class="md-nav__link">
<span class="md-ellipsis">
Verify without touching a radio
Guarded no-EndF rescue
</span>
</a>
@@ -1015,43 +1015,10 @@
</li>
<li class="md-nav__item">
<a href="#withdrawn-release-verification" class="md-nav__link">
<a href="#safety-and-completion" class="md-nav__link">
<span class="md-ellipsis">
Withdrawn-release verification
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#future-direct-lab-template" class="md-nav__link">
<span class="md-ellipsis">
Future direct lab template
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#relayed-lab-template" class="md-nav__link">
<span class="md-ellipsis">
Relayed lab template
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#completion-checks" class="md-nav__link">
<span class="md-ellipsis">
Completion checks
Safety and completion
</span>
</a>
@@ -1174,10 +1141,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#withdrawn-second-v11701-candidate" class="md-nav__link">
<a href="#exact-destination" class="md-nav__link">
<span class="md-ellipsis">
Withdrawn second v1.17.01 candidate
Exact destination
</span>
</a>
@@ -1185,10 +1152,10 @@
</li>
<li class="md-nav__item">
<a href="#requirements-for-the-next-chain" class="md-nav__link">
<a href="#what-was-tested" class="md-nav__link">
<span class="md-ellipsis">
Requirements for the next chain
What was tested
</span>
</a>
@@ -1196,10 +1163,10 @@
</li>
<li class="md-nav__item">
<a href="#withdrawn-v11702-chain-smoke-test-result" class="md-nav__link">
<a href="#host-requirements" class="md-nav__link">
<span class="md-ellipsis">
Withdrawn v1.17.02-chain smoke-test result
Host requirements
</span>
</a>
@@ -1207,10 +1174,10 @@
</li>
<li class="md-nav__item">
<a href="#recover-the-lab-rak" class="md-nav__link">
<a href="#verify-the-release-offline" class="md-nav__link">
<span class="md-ellipsis">
Recover the lab RAK
Verify the release offline
</span>
</a>
@@ -1218,10 +1185,10 @@
</li>
<li class="md-nav__item">
<a href="#intended-runner-safety-behavior" class="md-nav__link">
<a href="#direct-recoverable-bench-run-bw500sf5" class="md-nav__link">
<span class="md-ellipsis">
Intended runner safety behavior
Direct recoverable bench run: BW500/SF5
</span>
</a>
@@ -1229,10 +1196,10 @@
</li>
<li class="md-nav__item">
<a href="#host-and-radio-requirements" class="md-nav__link">
<a href="#live-deployment-with-two-intermediate-relays-bw250sf5" class="md-nav__link">
<span class="md-ellipsis">
Host and radio requirements
Live deployment with two intermediate relays: BW250/SF5
</span>
</a>
@@ -1240,10 +1207,10 @@
</li>
<li class="md-nav__item">
<a href="#verify-without-touching-a-radio" class="md-nav__link">
<a href="#guarded-no-endf-rescue" class="md-nav__link">
<span class="md-ellipsis">
Verify without touching a radio
Guarded no-EndF rescue
</span>
</a>
@@ -1251,43 +1218,10 @@
</li>
<li class="md-nav__item">
<a href="#withdrawn-release-verification" class="md-nav__link">
<a href="#safety-and-completion" class="md-nav__link">
<span class="md-ellipsis">
Withdrawn-release verification
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#future-direct-lab-template" class="md-nav__link">
<span class="md-ellipsis">
Future direct lab template
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#relayed-lab-template" class="md-nav__link">
<span class="md-ellipsis">
Relayed lab template
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#completion-checks" class="md-nav__link">
<span class="md-ellipsis">
Completion checks
Safety and completion
</span>
</a>
@@ -1321,266 +1255,184 @@
<h1 id="rak3401-1w-repeater-lora-update-chain">RAK3401 1W repeater LoRa update chain</h1>
<blockquote>
<p>Status: the second corrected v1.17.01 candidate is withdrawn. A physical
RAK3401 run passed steps 1 through 15, then step 16 booted but could not
validate its EndF. The runner blocks this exact bundle before device access.</p>
<p>Status: physically passed. The exact 29-step chain completed from the
c1caa5ad v1.16.7.0 test image through v1.17.01 on a RAK3401 1W. Every step
passed its post-boot version, EndF, rescue-command, and watchdog checks.</p>
</blockquote>
<p>This procedure records the exact 26-step update chain from the release
<p>The release is
<a href="https://github.com/mikecarper/MeshCore/releases/tag/rak3401-mota-v1.16.07-c1caa5ad-to-v1.17.01-c96bdd6e"><code>rak3401-mota-v1.16.07-c1caa5ad-to-v1.17.01-c96bdd6e</code></a>.
It is intentionally specific to the following destination firmware:</p>
Use this asset:</p>
<pre><code class="language-text">RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.01-cd824765.zip
</code></pre>
<ul>
<li>ZIP SHA-256: <code>eac67a0be12690b7e22c4d1f6a15bfdeb5bd627c4850b246b1be4220e5607b34</code></li>
<li>inner <code>SHA256SUMS.txt</code> SHA-256: <code>8097d75c5d11b9e32e3ebd4971068bf743eaa108054ab39eb0049016f89d185d</code></li>
<li>endpoint image SHA-256: <code>5c8d94bb23e87c23b0374ffb5a46e0c1205d6eebcb9d8bae3be6fda2613f9f79</code></li>
<li>endpoint EndF body hash: <code>DD45E7A23438B051</code></li>
</ul>
<p>The older v1.17.01 candidates and the v1.17.02 chain are retained only for
diagnosis. The runner recognizes their hashes and refuses live installation
before opening a device or reading a password.</p>
<h2 id="exact-destination">Exact destination</h2>
<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>starting version: <code>1.16.7.0</code>, build <code>c1caa5ad</code></li>
<li>starting EndF body hash: <code>71F4026CBE4B8B74</code></li>
<li>destination key used for this deployment:
<code>63d8df6387eaffd2e25db7d2a8ad967a65202182a48d681d7e7a9260f917280d</code></li>
<li>start: <code>v1.16.7.0-c1caa5ad</code>, EndF <code>71F4026CBE4B8B74</code></li>
<li>endpoint: <code>v1.17.01-halo-keymind-cascade-dev-cd824765</code>, EndF <code>DD45E7A23438B051</code></li>
<li>deployment target key: <code>63d8df6387eaffd2e25db7d2a8ad967a65202182a48d681d7e7a9260f917280d</code></li>
</ul>
<p>Do not use this chain on another node, and do not start it on another RAK3401.
The physical test has withdrawn this exact chain. Use it only for offline
diagnosis; the runner refuses live deployment even with
<code>--accept-test-candidate</code>.</p>
<h2 id="withdrawn-second-v11701-candidate">Withdrawn second v1.17.01 candidate</h2>
<p>The replacement rebuilt steps 6 through 15 around the first observed SHA
failure. Step 15 used software SHA-256 and passed its physical EndF check.
Step 16 re-enabled CC310 SHA with checked return codes. It downloaded and
applied successfully, booted <code>v1.16.9.112-ea3843e0</code>, then returned <code>ERR no
EndF</code>. This proves that CC310 can report success yet produce a wrong digest
for the memory-mapped application image; return-code fallback is insufficient.</p>
<pre><code class="language-text">/home/mesh/git/MeshCore/out-rak3401-mota-v1.17.01-corrected/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.01-c96bdd6e.zip
</code></pre>
<p>ZIP SHA-256:
<code>46c7480ed6bdc2aa01fb23a0f70e34c4012ffdd42b616d07bde66cf66d594630</code>.
The largest package is 88,280 bytes, leaving 1,832 bytes below the staging
limit. All 26 deltas reconstruct with both zero-filled and 0xFF-filled
workspaces. The endpoint has whole-image SHA-256
<code>e923f6209e0f071a5862ffbc7690e0b355c1e74829067e0bfdacd0de6c316065</code>
and EndF body hash <code>AC267B02E055F42E</code>.</p>
<p>The withdrawn bundle includes the exact v1.16.7 test-start UF2/Nordic DFU ZIP, a
diagnostic corrected step-6 image, and the final recovery UF2/ZIP. Restore the
lab node locally to the included test-start image before rerunning the chain.
The bundle's <code>RUNBOOK.md</code> is retained for diagnosis only.</p>
<h2 id="requirements-for-the-next-chain">Requirements for the next chain</h2>
<p>The next chain must use software SHA-256 for every bridge. CC310 may remain
enabled for AES, HMAC, and entropy, but not for either <code>Utils::sha256</code>
overload. The guarded <code>ota rescue install &lt;base_hash16&gt;</code> command must be in
the first installed bridge (step 1) and every target after it. Offline
validation must reconstruct each target and prove that command is present;
the live runner also probes <code>ota help</code> after every successful transition and
refuses to expose a bridge without the rescue path to another update.</p>
<h2 id="withdrawn-v11702-chain-smoke-test-result">Withdrawn v1.17.02-chain smoke-test result</h2>
<p>The lab topology used a Heltec V4.3 OLED ESP32 Full Companion on
<code>/dev/ttyACM0</code> and a direct LoRa path to <code>RAK3401 1W Repeater</code>. The remote
admin password is the lowercase default <code>password</code>, not <code>Password</code>.</p>
<p>Steps 1 through 5 completed and passed an exact post-boot version and EndF
body-hash check. Step 6 then did all of the following successfully:</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>
<h2 id="what-was-tested">What was tested</h2>
<p>The direct physical run used:</p>
<ul>
<li>downloaded all 79 blocks of mOTA ID <code>7C8BC884</code>;</li>
<li>verified the watchdog was off immediately before install;</li>
<li>returned <code>verified (unsigned); applying</code>;</li>
<li>booted <code>v1.16.08.7-halo-keymind-cascade-b-0c4ed3ac</code>;</li>
<li>retained a soft-reset boot record consistent with OTAFIX apply success.</li>
<li>a Heltec V4.3 OLED 2 MB Full Companion on <code>/dev/ttyACM0</code>;</li>
<li>the same Full Companion at <code>192.168.1.51</code>, with mOTA seeding on TCP <code>5001</code>
and its local OTA/TempRadio console on TCP <code>5002</code>;</li>
<li>Full Companion key
<code>8ce031bc322f3cf77376eeacfe8800b30d8c5dfe927f3636d801f3455a2dd4cf</code>;</li>
<li>one direct RF link to <code>RAK3401 1W Repeater</code>;</li>
<li>temporary radio <code>909.950 MHz</code>, <code>500 kHz</code>, <code>SF5</code>, <code>CR5</code>;</li>
<li>all 29 freshly rebuilt 1 KiB-block mOTA packages.</li>
</ul>
<p>The resulting bridge returns <code>ERR no EndF (firmware lacks the trailer?)</code> from
<code>ota self</code>. The release package is not corrupt: independently applying its
delta reconstructs the expected 524,204-byte image with whole-image SHA-256
<code>61ced8b63953c614748c2fa1b04c2c01e8eb6626a604f6ef95fd2594d6d8ce71</code>
and valid EndF body hash <code>A0130F9BD6760D47</code>.</p>
<p>The regression is in the intermediate application. This is the first bridge
in the chain built with the old CC310 hardware-crypto SHA path. That path
passes the memory-mapped application body to CC310 and ignores a failed return
code instead of falling back to software SHA. The preceding v1.16.08 image
uses software SHA, while later code contains the required checked fallback.
The normal nRF52 install gate correctly refuses step 7 when it cannot validate
the running body. Forcing the bootloader trigger would bypass an application
safety gate and is not an acceptable recovery.</p>
<p>The lab RAK remains alive on v1.16.08.7. Its normal radio is restored to
<code>910.525,62.5,7,5</code>, and <code>system.watchdog</code> is restored and verified <code>on</code>.</p>
<h2 id="recover-the-lab-rak">Recover the lab RAK</h2>
<p>The latest physical run stopped on <code>v1.16.9.112-ea3843e0</code>: normal radio is
restored to <code>910.525,62.5,7,5</code> and <code>system.watchdog</code> is verified <code>on</code>, but the
application reports <code>ERR no EndF</code>. That bridge predates the guarded rescue
command, so recovery requires a local data path to the RAK3401 itself. The
Heltec controller cable cannot recover the remote RAK.</p>
<ol>
<li>Connect the RAK3401 itself to this host by USB.</li>
<li>Enter its exact-board UF2 bootloader, using a local <code>uf2reset</code> command or
the board's double-reset gesture.</li>
<li>For another chain test, flash the exact c1caa5ad test-start UF2 from the
withdrawn bundle's <code>recovery/test-start/</code> directory. Do not use its final
recovery image as a production recovery target; it predates the new
software-only SHA rule.</li>
<li>After it boots, require the c1caa5ad start identity, target <code>2FA509C1</code>,
hardware <code>RAK_3401</code>, a valid <code>ota self</code> reply, normal radio settings, and
watchdog <code>on</code>.</li>
</ol>
<p>Do not force an apply or issue a remote recovery reboot. Once the
RAK USB cable is attached, the port and UF2 mount can be detected and the
recovery completed without guessing device paths.</p>
<h2 id="intended-runner-safety-behavior">Intended runner safety behavior</h2>
<p>Stable OTAFIX 2.4 cannot feed a system watchdog inherited by the bootloader.
The dormant live path implements the release's watchdog sequence:</p>
<ol>
<li>Persist <code>system.watchdog off</code> without issuing a normal reboot.</li>
<li>Wait 90 seconds for the already-running watchdog to reset the node.</li>
<li>Require the node to report <code>&gt; off</code>.</li>
<li>Prove another 90 seconds of stable uptime.</li>
<li>Enforce the requested <code>ota config hops</code> reach before every chain step.</li>
<li>Recheck <code>&gt; off</code> immediately before every <code>ota install</code> command.</li>
<li>Re-enable the watchdog only after the exact step 26 image boots and passes
both version and EndF body-hash verification.</li>
</ol>
<p>These controls remain requirements for the next candidate. They cannot repair
a running bridge that lacks both valid app-side EndF validation and the rescue
command. A replacement must pass a complete physical-board run before its
lab-only gate is removed.</p>
<p>An interrupted download is resumable. Avoid interrupting power or radio
coverage while <code>ota install</code> is applying a package. Physical USB recovery is
the fallback if an apply is interrupted at the wrong instant.</p>
<h2 id="host-and-radio-requirements">Host and radio requirements</h2>
<p>The first verified transition completed at <code>2026-08-14T01:50:24Z</code>; the final
endpoint completed at <code>2026-08-14T06:41:36Z</code>. The ZIP contains the complete
29-row physical record as <code>PHYSICAL-TEST.jsonl</code>.</p>
<p>The largest package is 89,844 bytes and leaves 268 bytes of staging margin.
Every delta was also reconstructed offline with both zero-filled and
<code>0xFF</code>-filled workspaces and verified independently with <code>motatool</code>. Step 25 is
an intentional extra bridge that keeps the compiler-layout transition small.</p>
<p>Step 1 installs both the guarded rescue command and the accelerated four-block
primary requester. The old requester used for the first transfer is serial, so
step 1 is expected to be slower. Steps 2 through 29 use the accelerated
requester. Some historical bridge text still says <code>low priority</code>; those
images were built with <code>OTA_TX_PRIORITY=0</code>, so their transfer traffic is
actually primary.</p>
<h2 id="host-requirements">Host requirements</h2>
<p>Install:</p>
<ul>
<li>Python 3.9 or newer</li>
<li><code>meshcli</code> 1.6.0 or newer</li>
<li>a current <code>motatool</code></li>
<li>a Full Companion or OTA-enabled repeater to seed the files</li>
<li>Python 3.9 or newer;</li>
<li><code>meshcli</code> 1.6.0 or newer;</li>
<li>the current <code>motatool</code>;</li>
<li>a Full Companion or OTA-enabled repeater that can seed mOTA files.</li>
</ul>
<p>The ESP32 Full Companion serves mOTA data through its dedicated TCP port
<code>5001</code>; its USB port remains the Binary API controller. Its local OTA and
TempRadio console is TCP port <code>5002</code>. For a Heltec Full Companion at
<code>192.168.1.51</code>, use these three connections together:</p>
<pre><code class="language-text">controller: /dev/ttyACM0
mOTA source: 192.168.1.51:5001
source CLI: 192.168.1.51:5002
</code></pre>
<p>Before a deployment, verify that USB and TCP port <code>5000</code> report the same
Companion public key:</p>
<pre><code class="language-bash">meshcli -s /dev/ttyACM0 -j -c off infos
meshcli -t 192.168.1.51 -p 5000 -j -c off infos
</code></pre>
<p>The tested Heltec key is
<code>8ce031bc322f3cf77376eeacfe8800b30d8c5dfe927f3636d801f3455a2dd4cf</code>.
Change the IP address for a different deployment.</p>
<p>The source, controller, destination, and every intermediate relay must support
the temporary tuple <code>909.950,250,5,5</code>. Confirm that this frequency and
bandwidth are legal at the deployment location. All nodes return to their
ordinary radio after each step.</p>
<h2 id="verify-without-touching-a-radio">Verify without touching a radio</h2>
<p>The chain runner pins the release ZIP SHA-256 to
<code>46c7480ed6bdc2aa01fb23a0f70e34c4012ffdd42b616d07bde66cf66d594630</code>.
It also pins and verifies the inner checksum list, checks complete checksum
coverage, parses every manifest, verifies the chain continuity, and runs
<code>motatool verify</code> on all 26 containers.</p>
<p>It downloads the release automatically when <code>--bundle</code> is omitted:</p>
<p>The runner maintains one persistent controller connection. It logs into the
destination once, keeps that authenticated radio-node session across
application reboots, and does not treat a silent packet as lost
authentication. The source seeder reconnects for each isolated package but
does not need remote-admin login.</p>
<h2 id="verify-the-release-offline">Verify the release offline</h2>
<p>No password or device is needed:</p>
<pre><code class="language-bash">python3 tools/lora_ota/rak3401_mota_chain.py \
--bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.01-cd824765.zip \
--work-dir ./rak3401-mota-chain-work \
--motatool /path/to/motatool \
--verify-only
</code></pre>
<p>An already-downloaded asset can be supplied with <code>--bundle</code>. Only the pinned
ZIP or its extracted root is accepted.</p>
<h2 id="withdrawn-release-verification">Withdrawn-release verification</h2>
<p>No password or device connection is needed for offline verification:</p>
<pre><code class="language-bash">python3 tools/lora_ota/rak3401_mota_chain.py \
--work-dir ./rak3401-mota-chain-work \
--motatool /path/to/motatool \
--verify-only
</code></pre>
<p>Use <code>--verify-only</code> for this withdrawn bundle. Every live invocation exits
before connecting to a device, including one with <code>--accept-test-candidate</code>.
The older failed v1.17.01 and v1.17.02 chains are also recognized and blocked.</p>
<h2 id="future-direct-lab-template">Future direct lab template</h2>
<p>This template becomes usable only after a new ZIP and its hashes are pinned in
the runner. Use it only on a locally recoverable test RAK3401. Keep the work
directory for resume, and retain the explicit <code>--accept-test-candidate</code> gate.</p>
<p>When <code>--bundle</code> is omitted, the runner downloads the pinned release asset. It
checks the outer ZIP hash, complete inner checksum coverage, all 29 manifests,
chain continuity, audited image anchors, final recovery image, and every mOTA
container with <code>motatool</code>.</p>
<h2 id="direct-recoverable-bench-run-bw500sf5">Direct recoverable bench run: BW500/SF5</h2>
<p>Restore the test RAK locally with the ZIP's
<code>recovery/test-start/RAK3401-test-start-v1.16.7-c1caa5ad.uf2</code>. Before starting,
require start version <code>1.16.7.0</code>, body hash <code>71F4026CBE4B8B74</code>, target
<code>2FA509C1</code>, hardware <code>RAK_3401</code>, and OTAFIX mOTA ABI 2 with codec 2.</p>
<p>For the tested direct topology:</p>
<pre><code class="language-bash">export MESHCORE_ADMIN_PASSWORD='password'
python3 tools/lora_ota/rak3401_mota_chain.py \
--bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.01-cd824765.zip \
--work-dir ./rak3401-mota-chain-work \
--controller-serial /dev/ttyACM0 \
--source-tcp 192.168.1.51:5001 \
--source-cli-tcp 192.168.1.51:5002 \
--source-shares-controller \
--ota-hops 3 \
--accept-test-candidate \
--target-key 63d8df63 \
--temp-radio 909.950,500,5,5,120 \
--ota-hops 1 \
--motatool /path/to/motatool \
--yes
</code></pre>
<p>The intended runner logs each isolated step attempt below <code>steps/</code>, records every
verified transition in <code>progress.jsonl</code>, and prints the source log path. Rerun
the exact command after a host restart or recoverable RF failure. Status polling
starts at 60 seconds, expands adaptively when replies are slow or the link is
contended, and contracts after quick replies. The transfer itself is primary
traffic, so reserve the TempRadio window for OTA on a busy or relayed mesh.</p>
<h2 id="relayed-lab-template">Relayed lab template</h2>
<p>Every intermediate relay must enter the same TempRadio tuple. Add one
<code>--relay</code> argument for each intermediate repeater, ordered from the destination
side back toward the controller. In other words, list the farthest relay first
and the nearest relay last. A bare relay name uses
<code>MESHCORE_ADMIN_PASSWORD</code>; append <code>=PASSWORD</code> only when that relay has a
different password.</p>
<p>The word "hop" is sometimes counted two ways:</p>
<ul>
<li><code>controller -&gt; relay -&gt; destination</code> is two RF links but has one
intermediate relay, so pass one <code>--relay</code>.</li>
<li><code>controller -&gt; near relay -&gt; far relay -&gt; destination</code> has two intermediate
relays, so pass two <code>--relay</code> values, <code>far</code> first and <code>near</code> second.</li>
</ul>
<p>For one intermediate relay:</p>
<pre><code class="language-bash">python3 tools/lora_ota/rak3401_mota_chain.py \
<p>BW500 is for the controlled direct bench setup. Confirm that the selected
frequency and bandwidth are legal at the test location.</p>
<p>Keep the work directory. Each package gets an isolated attempt directory, and
each exact transition is appended to <code>progress.jsonl</code>. After a host or RF
interruption, rerun the identical command with the same work directory. The
runner resumes only when the live body hash matches the recorded chain; never
manually skip to a package.</p>
<h2 id="live-deployment-with-two-intermediate-relays-bw250sf5">Live deployment with two intermediate relays: BW250/SF5</h2>
<p>For the intended private TempRadio deployment, use BW250/SF5 and two
intermediate relays. List relays from the destination side toward the
controller: farthest first, nearest last. With two relays there are three RF
links, so use <code>--ota-hops 3</code>.</p>
<p>Run a non-mutating preflight first:</p>
<pre><code class="language-bash">export MESHCORE_ADMIN_PASSWORD='your-destination-and-relay-password'
python3 tools/lora_ota/rak3401_mota_chain.py \
--bundle /path/to/RAK3401-update-chain-v1.16.7-c1caa5ad-to-v1.17.01-cd824765.zip \
--work-dir ./rak3401-mota-chain-work \
--controller-serial /dev/ttyACM0 \
--source-tcp 192.168.1.51:5001 \
--source-cli-tcp 192.168.1.51:5002 \
--source-tcp SOURCE_IP:5001 \
--source-cli-tcp SOURCE_IP:5002 \
--source-shares-controller \
--ota-hops 3 \
--relay 'Intermediate Repeater' \
--accept-test-candidate \
--motatool /path/to/motatool \
--yes
</code></pre>
<p>For two intermediate relays:</p>
<pre><code class="language-bash">python3 tools/lora_ota/rak3401_mota_chain.py \
--work-dir ./rak3401-mota-chain-work \
--controller-serial /dev/ttyACM0 \
--source-tcp 192.168.1.51:5001 \
--source-cli-tcp 192.168.1.51:5002 \
--source-shares-controller \
--ota-hops 3 \
--target-key 63d8df63 \
--relay 'Far Repeater' \
--relay 'Near Repeater' \
--accept-test-candidate \
--temp-radio 909.950,250,5,5,120 \
--ota-hops 3 \
--motatool /path/to/motatool \
--yes
--preflight-only
</code></pre>
<p>Do not begin a production deployment until a replacement bundle passes a
direct physical smoke test from start to endpoint. Run <code>--preflight-only</code> with
the same relay arguments first. The runner sends
the destination to TempRadio, then the relays farthest-to-nearest while their
remaining normal routes still exist. It checks that the 120-minute TempRadio
window covers the selected relay count and all configured timeouts. The
starting build may report <code>hops=0</code> after the watchdog-driven reset, so the
runner re-enforces <code>--ota-hops 3</code> before every step. That setting accepts OTA
packets received through up to three intermediate repeaters.</p>
<p>For a lossy multi-hop path, increase <code>--reply-timeout</code>,
<code>--discovery-timeout</code>, or <code>--transfer-timeout-minutes</code> as needed. If their sum
no longer fits the TempRadio window, also increase the minutes in
<code>--temp-radio</code>; the runner rejects an unsafe combination before connecting.</p>
<h2 id="completion-checks">Completion checks</h2>
<p>A bare relay name uses <code>MESHCORE_ADMIN_PASSWORD</code>. Append <code>=PASSWORD</code> only for
a relay with a different password. After preflight succeeds, rerun the same
command with <code>--yes</code> in place of <code>--preflight-only</code>.</p>
<p>Arm the relay chain farthest-to-nearest while all nodes are still reachable on
the ordinary mesh. The runner then moves the source and controller to the same
temporary tuple. Keep the private TempRadio network reserved for OTA during
the run; public-mesh flooding does not improve this transfer. A 120-minute
window is the minimum used here—raise it if the selected timeouts and relay
count require more time.</p>
<h2 id="guarded-no-endf-rescue">Guarded no-EndF rescue</h2>
<p>The rescue command is present from the first installed bridge onward. If a
bridge remains reachable but <code>ota self</code> reports no EndF, serve and fetch only
its exact successor package. Read that row's 16-hex <code>base_body_hash</code> from
<code>CHAIN.csv</code>, then issue:</p>
<pre><code class="language-text">ota rescue install &lt;base_body_hash&gt;
</code></pre>
<p>This is not a force command. It refuses a valid normal EndF, a base mismatch,
wrong target or hardware, or invalid payload. OTAFIX hashes the physical
running application before its first write. A missing/corrupt EndF can
therefore continue through its exact successor instead of becoming stuck,
provided the installed bridge already contains the rescue command. The
c1caa5ad starting image predates rescue, so a failure before step 1 completes
still requires local USB recovery.</p>
<h2 id="safety-and-completion">Safety and completion</h2>
<p>The runner performs the following guarded sequence:</p>
<ol>
<li>Persist <code>system.watchdog off</code>, allow the already-running watchdog to reset
once, and prove stable uptime with the watchdog off.</li>
<li>Recheck destination identity, OTA reach, source identity, and exact package
base before every step.</li>
<li>Require <code>system.watchdog</code> to report <code>off</code> immediately before every install.</li>
<li>After every reboot, require the exact version and EndF body hash, then prove
the rescue command is present before exposing that bridge to another step.</li>
<li>Re-enable the watchdog only after the exact step-29 endpoint boots.</li>
</ol>
<p>Success requires all of the following:</p>
<ul>
<li>version <code>v1.17.1.0</code></li>
<li>target ID <code>2FA509C1</code></li>
<li>hardware <code>RAK_3401</code></li>
<li>final EndF body hash <code>AC267B02E055F42E</code></li>
<li><code>get system.watchdog</code> returning <code>&gt; on</code></li>
<li>version <code>v1.17.01-halo-keymind-cascade-dev-cd824765</code>;</li>
<li>EndF body hash <code>DD45E7A23438B051</code>;</li>
<li>target <code>2FA509C1</code>, hardware <code>RAK_3401</code>;</li>
<li>normal radio <code>910.525 MHz</code>, <code>62.5 kHz</code>, <code>SF7</code>, <code>CR5</code>;</li>
<li><code>system.watchdog</code> verified <code>on</code>.</li>
</ul>
<p>Do not treat a successful transfer alone as completion. Each temporary bridge
is a complete bootable image, but the RAK should not be left on a bridge
version between planned maintenance sessions.</p>
<p>See <a href="../lora_ota_automation/">LoRa OTA automation</a> for the generic single-step
workflow and source topology details.</p>
<p>A completed download or an accepted install reply is not success without the
post-reboot identity checks. The bundle includes exact test-start and final
local recovery UF2/ZIP files if USB recovery is ever needed.</p>
search/search_index.json
+1 -1
View File
@@ -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>Frequently Asked Questions</li> <li>CLI Commands</li> <li>Filter Policy Playground</li> <li>Telemetry History Decoder</li> <li>CLI Availability by Firmware Build</li> <li>Easy LoRa OTA: ESP32 full images and nRF52 deltas</li> <li>Scripted LoRa OTA: Bash and PowerShell</li> <li>MeshTower V2 microSD self-updates</li> <li>GPS Tracking</li> <li>Companion Protocol</li> <li>Full Companion: ESP32 and nRF52</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. For example, a logging repeater is not an MQTT observer, and a WiFi companion does not publish to MQTT unless its target name also contains <code>mqtt</code>.</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 USB, BLE, or serial companion 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; 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>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 bridge.enabled on|off</code> starts or stops the MQTT bridge;</li> <li><code>set Line truncated
{"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>Frequently Asked Questions</li> <li>CLI Commands</li> <li>Filter Policy Playground</li> <li>Telemetry History Decoder</li> <li>CLI Availability by Firmware Build</li> <li>Easy LoRa OTA: ESP32 full images and nRF52 deltas</li> <li>Scripted LoRa OTA: Bash and PowerShell</li> <li>MeshTower V2 microSD self-updates</li> <li>GPS Tracking</li> <li>Companion Protocol</li> <li>Full Companion: ESP32 and nRF52</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. For example, a logging repeater is not an MQTT observer, and a WiFi companion does not publish to MQTT unless its target name also contains <code>mqtt</code>.</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 USB, BLE, or serial companion 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; 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>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 bridge.enabled on|off</code> starts or stops the MQTT bridge;</li> <li><code>set Line truncated