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

2026-10-06T19:25:36Z

twisla commented

2026-10-06 19:25:36 +00:00

Phase 4 of the site (docs/milestones/W1.md, Q179): the developer docs, with an emphasis on the Debug Builds and the Debug Console.

/dev/, linked as Developers in the navigation:

Debug Builds and the Debug Console (first, hand-written, the longest): Debug Builds (build, flash, the token, why to keep one in the fallback slot), the Console and its protocol, files/screenshots/put/get/coredump/reset, driving the UI (keys, "look before you press", testing the update path and a network change without losing the console, measuring), crashes and Safe Mode (decoding against the archived ELF), and the command reference, generated from the firmware's own help text.
Build, test and release: the README's build, CI and flash sections (generated), and how an update works (the update file, the four ways in, Probation), with three of the devlog's diagrams.
Decisions (the 9 ADRs) and Milestones (8 plans), generated.

Generated, not copied: site/tools/gen_dev_docs.py writes those pages from docs/, the README and src/main.cpp. Zola can't read outside its folder, even through a symlink (tried), so the pages are committed; the Site workflow runs gen_dev_docs.py --check, and now also when src/main.cpp changes, because the command list lives there. pull; zola build on the server is unchanged.

Left out on purpose: docs/milestones/M0.md, M1.md and CONTEXT.md describe Wi-Fi monitoring, which the site does not publish.

Checked: the console protocol (token, banner, 4 KB backlog, replies, denied after about a second, screenshot, get errors, rdbg -b) against a Debug Build v0.11.0-3 over Wi-Fi, with read-only commands only; Zola build; check_site.py 65 pages / 0 problems (every internal link); 17 new pages in Chromium under the production CSP at 1100 and 390 px, no violation and no sideways scroll.

Not checked: crash abort, crash wdt and Safe Mode were not run (described from ADR 0005 and the code); update damage/force and wifi ip ... try are described from the code, not run on the device.

Found on the way (documented, not changed): the README's table lacked the gnss commands (rows added here); piping commands into rdbg.py returns before the replies unless the input stays open; update install on a Debug Build needs force.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

Phase 4 of the site (docs/milestones/W1.md, Q179): the developer docs, with an emphasis on the Debug Builds and the Debug Console. **`/dev/`**, linked as **Developers** in the navigation: - **Debug Builds and the Debug Console** (first, hand-written, the longest): Debug Builds (build, flash, the token, why to keep one in the fallback slot), the Console and its protocol, files/screenshots/`put`/`get`/`coredump`/`reset`, driving the UI (keys, "look before you press", testing the update path and a network change without losing the console, measuring), crashes and Safe Mode (decoding against the archived ELF), and the **command reference**, generated from the firmware's own `help` text. - **Build, test and release**: the README's build, CI and flash sections (generated), and how an update works (the update file, the four ways in, Probation), with three of the devlog's diagrams. - **Decisions** (the 9 ADRs) and **Milestones** (8 plans), generated. **Generated, not copied:** `site/tools/gen_dev_docs.py` writes those pages from `docs/`, the README and `src/main.cpp`. Zola can't read outside its folder, even through a symlink (tried), so the pages are committed; the Site workflow runs `gen_dev_docs.py --check`, and now also when `src/main.cpp` changes, because the command list lives there. `pull; zola build` on the server is unchanged. **Left out on purpose:** `docs/milestones/M0.md`, `M1.md` and `CONTEXT.md` describe Wi-Fi monitoring, which the site does not publish. **Checked:** the console protocol (token, banner, 4 KB backlog, replies, `denied` after about a second, `screenshot`, `get` errors, `rdbg -b`) against a Debug Build v0.11.0-3 over Wi-Fi, with read-only commands only; Zola build; `check_site.py` 65 pages / 0 problems (every internal link); 17 new pages in Chromium under the production CSP at 1100 and 390 px, no violation and no sideways scroll. **Not checked:** `crash abort`, `crash wdt` and Safe Mode were not run (described from ADR 0005 and the code); `update damage`/`force` and `wifi ip ... try` are described from the code, not run on the device. **Found on the way** (documented, not changed): the README's table lacked the `gnss` commands (rows added here); piping commands into `rdbg.py` returns before the replies unless the input stays open; `update install` on a Debug Build needs `force`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

twisla added 1 commit 2026-10-06 19:25:37 +00:00

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

Site / build (pull_request) Successful in 9s

Details

CI / build (pull_request) Successful in 8m38s

Details

3b4100dc6a

/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

twisla merged commit 1353e6a5f9 into main

2026-10-06 19:34:41 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: twisla/roro9stack#66