Site: the developer docs (phase 4), with the Debug Builds and the Debug Console first

/dev/ has Debug Builds and the Debug Console (builds and the token, the console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, the command reference), Build, test and release (including how an update works), the architecture decisions and the milestone plans. Generated from the repository by site/tools/gen_dev_docs.py: the ADRs, the milestones, the README's sections, and the command reference, read from the firmware's own `help` text. The pages are committed (Zola cannot read outside its folder); the Site workflow checks they are current, and now also runs when src/main.cpp changes. M0, M1 and CONTEXT.md are not published. README: the gnss commands that the table lacked. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2026-10-06 21:25:33 +02:00
parent 8f95bee744
commit 3b4100dc6a
43 changed files with 2284 additions and 6 deletions
@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 352" role="img" aria-label="Four ways in, one gate. scripts/flash.sh --ota signs the firmware and pushes it over Wi-Fi to TCP port 3232, straight to the Update Service. rdbg.py put over Wi-Fi, sd_put.sh over USB serial, or the card by hand all put an Update File in /updates on the SD card, where Settings, Firmware, or the install command picks it up. The Update Service checks the header and signature first, writes the image to the other app slot while hashing it, and makes it the next boot only if the hash matches. Then it restarts into Probation. If anything is wrong, a Toast says so and nothing changes.">
+  <defs>
+    <marker id="wi-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
+    <marker id="wi-arrow-hot" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-accent" d="M0,0 L10,5 L0,10 z"/></marker>
+    <marker id="wi-arrow-bad" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-red" d="M0,0 L10,5 L0,10 z"/></marker>
+  </defs>
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <rect class="wi-box" x="16" y="32" width="220" height="56" rx="6"/>
+    <text x="30" y="55" font-size="12" font-weight="600">flash.sh --ota</text>
+    <text x="30" y="75" font-size="11" class="wi-dim">builds, signs, pushes</text>
+    <rect class="wi-box" x="16" y="112" width="220" height="56" rx="6"/>
+    <text x="30" y="135" font-size="12" font-weight="600">rdbg.py put</text>
+    <text x="30" y="155" font-size="11" class="wi-dim">Debug Build, Wi-Fi 2323</text>
+    <rect class="wi-box" x="16" y="192" width="220" height="56" rx="6"/>
+    <text x="30" y="215" font-size="12" font-weight="600">sd_put.sh</text>
+    <text x="30" y="235" font-size="11" class="wi-dim">USB serial, card stays in</text>
+    <rect class="wi-box" x="16" y="272" width="220" height="56" rx="6" stroke-dasharray="4 3"/>
+    <text x="30" y="295" font-size="12" font-weight="600">the card, by hand</text>
+    <text x="30" y="315" font-size="11" class="wi-dim">the 1990s way</text>
+
+    <rect class="wi-panel" x="288" y="176" width="200" height="88" rx="8"/>
+    <text x="302" y="200" font-size="12" font-weight="600">SD card</text>
+    <text x="302" y="219" font-size="11">/updates/*.ota</text>
+    <text x="302" y="238" font-size="11" class="wi-dim">Settings → Firmware,</text>
+    <text x="302" y="254" font-size="11" class="wi-dim">or install &lt;path&gt;</text>
+
+    <rect class="wi-hot" x="536" y="32" width="208" height="158" rx="8"/>
+    <text x="550" y="56" font-size="12" font-weight="600">Update Service</text>
+    <text x="550" y="80" font-size="11">1 header, signature:</text>
+    <text x="550" y="96" font-size="11" class="wi-dim">  checked first</text>
+    <text x="550" y="118" font-size="11">2 image → other slot,</text>
+    <text x="550" y="134" font-size="11" class="wi-dim">  hashed on the way</text>
+    <text x="550" y="156" font-size="11">3 hash matches:</text>
+    <text x="550" y="172" font-size="11" class="wi-dim">  boot it next</text>
+
+    <rect class="wi-box" x="576" y="216" width="168" height="44" rx="6"/>
+    <text x="660" y="243" font-size="12" text-anchor="middle">restart → Probation</text>
+    <rect class="wi-bad" x="536" y="280" width="208" height="56" rx="6"/>
+    <text x="550" y="303" font-size="11">anything wrong: a Toast,</text>
+    <text x="550" y="321" font-size="11">and nothing changes</text>
+
+    <path class="wi-line-hot" d="M236 60 H532" marker-end="url(#wi-arrow-hot)"/>
+    <text class="f-accent" x="300" y="52" font-size="11">Wi-Fi · TCP 3232</text>
+    <path class="wi-line" d="M236 140 H262 V198 H284" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line" d="M236 220 H284" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line" d="M236 300 H262 V242 H284" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line" d="M488 220 H512 V150 H532" marker-end="url(#wi-arrow)"/>
+    <text x="492" y="238" font-size="10" class="wi-dim">storage</text>
+    <text x="492" y="250" font-size="10" class="wi-dim">task</text>
+    <path class="wi-line" d="M660 190 V212" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line-bad" d="M556 190 V276" marker-end="url(#wi-arrow-bad)"/>
+  </g>
+</svg>