Search

Fn + h, on any screen, lists the keys that work there. No screen names its keys: that key does. It works everywhere, in a text field too, and ? does the same whenever you are not typing. The arrows scroll the list; any other key closes it. The list is for the screen you are on: in Storage it is the file keys, in a dialog it is the dialog's, in a text field it is the editing keys. Each list ends with the keys that work everywhere. If you only read one paragraph of this guide, this was it.

The Cardputer's keyboard has no arrow keys and no Escape, so the firmware gives a few keys a second job: KeyDoes EnterOpens or confirms the selected item `Back: one step out of a screen, and out of an App Fn + `Home: back to the Launcher Fn + ; . , /The arrows: up, down, left, right ; . , / aloneThe same arrows, as long as you are not typing text Fn + h, or ? when not typingHelp: the keys of the screen you are on TabSwitches view in an App that has more than one DelDeletes backwards when you type opt then an accent, then a letterTypes an accented letter: opt ' e gives é While you type text (a note, an IRC line, a setting), ; . , / type their own characters and you need Fn for the arrows. The Status Bar shows opt while a compose is waiting for its letter.

The home screen lists the Apps. Move with the arrows, open one with Enter. Back inside an App returns here.

A strip at the top of every screen: the name of the App on the left, and on the right, from the edge inwards: ShowsMeans the timeThe clock, once Wi-Fi or a GNSS fix has set it [3]Unread IRC messages that mention you, or private ones 97%The battery (in the warning colour at 15% and under) SDA card is in; the warning colour at 80% full bars and WWi-Fi connected, with its signal; W? is searching; MON is the Wi-Fi radio in its monitoring mode, which pauses IRC DBGThe Debug Console is switched on (Settings → Debug Console); brighter while a PC is connected to it RECA GNSS Track is being recorded CAPA LoRa capture is being recorded LThe radio is listening; it lights up for a moment on each packet. SW while a Sweep runs G or G12The GNSS receiver is searching (G, dim), has a 2D fix (G), or has a 3D fix with that many satellites (G12)

News from a background service (an IRC mention, a Storage warning, an update that is out) shows as a short message over whatever App is open, and can beep and flash the LED. Sound & LED in Settings turns that off.

On a new device a short Setup asks four things, then never appears again. It also tells you about Fn + h, twice, and it is the only part of the firmware that names keys on the screen: Long name, up to 39 bytes. Short name, up to 4 characters. Radio region. Nothing will transmit until you confirm yours. EU868 is the supported region. Timezone.

Put a microSD card in the Cardputer. Without one the radio, GNSS, Wi-Fi and IRC still work, but nothing can be saved: no notes, IRC logs, Wi-Fi scan logs, GPX tracks, LoRa captures, screenshots or saved Gemini pages. The Storage App shows what is on the card. The firmware keeps its own folders at the top of the card (captures, gemini, gnss, irc, notes, screenshots, updates, wifi). You can use the card in a computer too, but those names are the firmware's.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Everywhere `back Fn `home, the Launcher ; . , /arrows (Fn+ while typing) Fn h ?these keys (? not typing) A question , /the other answer Enterchoose it `cancel A text field Entersave `cancel Deldelete backwards Fn , /move the cursor opt ' ean accent: é The Launcher ; .up, down Enteropen the App

The first view lists what the radio hears, newest first: the time, the RSSI (signal strength, in dBm) and the SNR (signal over noise, in dB). For a Meshtastic packet it also shows the sender and the receiver (the last four hex digits of their numbers) and the number of hops. KeyDoes EnterThe details of a packet: the Meshtastic header, which is never encrypted, and a hex dump pPicks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default) cStarts or stops a capture TabSwitches to the Sweep The Scanner shows the header and the bytes; it does not decrypt the message itself, which Meshtastic encrypts with the channel's key.

A capture records packets into a pcap file with LoRaTap headers in /captures/lora/ on the SD card, to open in Wireshark. It keeps recording with the App closed (the Status Bar shows CAP); the radio sleeps when the App is not open and no capture is running. Captures are never deleted unless you ask, in the Storage App, which can also show a pcap's packets on the device.

Tab switches to the Sweep: the signal strength across 863 to 870 MHz in 100 kHz steps, drawn as bars with a mark at each peak, and a waterfall under them. The frequency the Sniffer listens on is marked. The Sniffer is paused during a Sweep and picks up where it was. The Status Bar shows SW.

The GNSS receiver on the same Cap makes the radio's noise floor about 8 dB worse while it runs. Settings → Pause GNSS for LoRa (off by default) puts the receiver on standby while the radio listens, except while a Track is being recorded.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. LoRa Scanner, the packets ; .up, down Enterthe packet's details ppick a Meshtastic preset cstart a Capture, or stop it Tabthe Sweep LoRa Scanner, a packet ; .scroll Enterback to the list LoRa Scanner, the presets ; .up, down Enterlisten with this preset LoRa Scanner, the Sweep Tabthe Sniffer

The first view shows the fix (No Fix, 2D Fix or 3D Fix, and how many satellites it uses), then: Lat and Lon, in decimal degrees or degrees, minutes and seconds (Settings → Coordinates); the Locator, the Maidenhead grid square; Altitude, Speed and the direction you are moving; HDOP, the horizontal precision: a smaller number is better; the Time, in UTC. Once there is a fix, the device's clock follows it.

Tab switches between Position and Sky: a circle with N, E, S and W, where each satellite is a dot, coloured by constellation, and filled when the receiver uses it. A legend counts, for each constellation (GPS, GLONASS, Galileo, BeiDou), the satellites used and in view.

r starts recording a Track: the route is saved as a GPX file on the SD card, in /gnss/tracks (named by date and time), and the Status Bar shows REC. Press r again to stop. A Track keeps recording with the App closed. It needs a card and a clock (a fix or Wi-Fi sets it); if it cannot start, the App says why: GNSS is off, No SD card or Waiting for the time. The Storage App opens a .gpx file and shows its points, start, duration and distance.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. GNSS Tabthe position, or the sky rrecord a Track, or stop it

KeyDoes Tab / Shift+TabPicks the next or previous link EnterFollows the link ` (Back)Returns to the previous page, at the place where you scrolled to Up and downScroll a line SpacePages down gTypes an address bBookmarks the page sSaves the page to the card SSaves it with the pages it links to Headings, lists, quotes and preformatted blocks are drawn as gemtext intends, wrapped to the screen. Links to other protocols show their address and are not followed. A page that asks for input (a search, say) shows a prompt, and a password prompt hides what you type. Characters outside the Latin fonts show as ?. The history keeps the last 20 pages.

It lists your bookmarks, then your Saved Pages, then a few starting points: geminiprotocol.net, a search engine and an aggregator. Without a card it shows only the built-in starting points.

Most capsules sign their own certificate. The first certificate seen for a host is remembered; if it later changes, the page is not shown and you are asked whether to trust the new one, with both fingerprints on screen. Expired or self-signed certificates are fine: only a change counts. Client certificates are not supported.

s keeps the page on the card, with the address it came from and when it was saved, and you can read it with no network. S also saves the pages it links to on the same capsule, as text only, up to 30, in the background. On the start page, Saved Pages are listed by capsule, newest first. Inside one, r refreshes it and d deletes it. A link to another saved page opens the saved copy; any other link fetches online if Wi-Fi is up, or says it is not saved. A file that is not text (a picture, say) is saved to /gemini/downloads/ instead of being shown. The Storage clean-up never offers Saved Pages for deletion.

With a card, every page streams to the card first, so a page larger than the device's memory still arrives whole and is read from the card as you scroll. Without a card, a page is limited to what fits in memory. If there is not enough free memory to open a secure connection, the fetch says so instead of failing silently; stopping IRC frees the most.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Gemini, a page Tabthe next link Aa Tabthe link before Enterfollow the link ` Delthe page before ; .scroll Spacea page down , /sideways, in wide blocks gtype an address bbookmark this page ssave the page to the card S...with the pages it links to Gemini, a Saved Page Tabthe next link Aa Tabthe link before Enterfollow the link ` Delthe page before ; .scroll Spacea page down , /sideways, in wide blocks gtype an address bbookmark this page rrefresh this Saved Page ddelete this Saved Page Gemini, an address Entergo there `cancel Deldelete backwards Fn , /move the cursor Gemini, an answer to a page Entersend it `cancel Deldelete backwards Fn , /move the cursor

The first time, type /settings and press Enter. The settings page has: Server and Port, and TLS (on or off). Self-signed: for a server whose certificate no authority signed. It is pinned on first use: the first certificate it sees is remembered, and a different one later is refused. Nick, SASL user and SASL password, NickServ password: passwords show only as (set). Auto-join: the channels to join after connecting. Save & reconnect. Opening the IRC App connects, if Wi-Fi is up. The connection belongs to a background service: leaving the App does not disconnect, and new messages keep arriving and being logged. It reconnects by itself after a drop, and does not start by itself after a restart.

You type at the bottom; Enter sends. A line starting with / is a command: CommandDoes /join #channel [key] (or /j)Joins; the # is optional /part [#channel] [message]Leaves /msg nick text (or /query)Opens a private chat, sending the text if there is any /me textAn action line /nick newnickChanges your nick /topic [text]Shows or sets the channel topic /names [#channel]Lists who is there /quit [message]Disconnects and stays disconnected until you type something again /raw … (or /quote)Sends a line to the server as it is /settingsThe settings page Each server, channel and private chat is a buffer. Tab moves to the next one, each shows how many messages are unread, and your own lines are in the accent colour. Scroll back with Alt + ; (older) and Alt + . (newer). The up and down arrows (Fn + ; and .) recall lines you sent.

A message with your nick in it, or any private message, is a mention: it shows a Toast over whatever App is open, and counts in the Status Bar's [n]. Other traffic only adds to the buffer's unread count.

Every buffer is logged to the SD card, one file per day, under /irc. Logs stop when the card passes 90% full, to keep the rest for captures; nothing is deleted without your asking, in the Storage App's Maintenance.

IRC pauses while Wi-Fi is monitoring (the Status Bar shows MON) and while the device installs an update. It reconnects and rejoins its channels afterwards; the App says paused in the meantime. A secure connection costs memory: IRC's takes about 40 KB of the 107 KB the device has, and an update's download needs about 52 KB more. That is why IRC steps aside for an update, and why the daily update check waits for IRC to be disconnected (see Updates).

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. IRC Entersend the line Tabthe next buffer Alt ; .scroll back, forward Fn ; .lines you sent before Fn , /move the cursor Deldelete backwards /settingsserver, nick, passwords /join #xjoin a channel /partleave it /msg nicka private chat /mean action /nickchange your nick /topicsee or set the topic /nameswho is there /quitdisconnect, and stay so /rawa line as it is `leave: IRC stays connected IRC settings ; .up, down Enteredit, switch, or save `leave without saving IRC, a setting Enterkeep it `cancel Deldelete backwards Fn , /move the cursor

Three entries: Networks nearby, Channel occupancy and Signal tracker. Pick one with the arrows and press Enter.

A list that refreshes by itself: each network's name (or (hidden)), channel, signal in dBm and security. The top line says how it is sorted and filtered. KeyDoes sSorts by signal, channel or name, in turn oShows only open networks hHides the hidden networks wShows only the strong ones lStarts and stops logging EnterOpens the Signal tracker on that network Logging adds each scan to /wifi/scans/<date>.csv on the SD card, one row per network, once the device knows the date; LOG and a row count show while it runs. Logs stop when the card passes 90% full.

One bar for each of the 13 Wi-Fi channels shows how busy it is: how many networks use it, and how strong they are. The top line counts the networks and names the quietest of the three channels that don't overlap, 1, 6 and 11. It is the quick answer to "which channel should my router use?". ` (Back) returns to the menu.

Follows one network: its name, address and channel, then the signal in dBm in large type, a strength bar, and a graph of the recent readings, so you can walk towards the strongest signal. m turns audible clicks on and off. If the network is no longer heard the screen says lost. ` (Back) returns to the list.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Wi-Fi Tools ; .up, down Enteropen Networks nearby ; .up, down Entertrack its signal ssort: signal, channel, name oopen networks only hhide the hidden ones wstrong ones only llog the scans to the card Signal tracker mclicks on or off

Each note shows its first line and its date, newest first. s switches to sorting by file name. KeyDoes nStarts a new note EnterOpens the note rRenames its file dDeletes it, after asking

Type. Enter starts a line and Del deletes backwards. Fn with the arrow keys moves the cursor through the wrapped text, Ctrl+A and Ctrl+E go to the start and the end of the line, Ctrl with Fn and up or down to the start and the end of the note, Tab types two spaces, and the compose key gives accents as everywhere. There is no save key. The note is written five seconds after your last key, when you press Back, when you leave the App, when the screen turns off and before the device powers off. The top line says typing or saved. Each save writes a temporary file and then puts it in the note's place, so a power cut costs a few seconds of typing and never the note. If a save was cut short, opening the note offers its copy back.

A new note has no file until you type something. The file is then named after its first line (shopping-list.txt), or note-<date>-<time>.txt if that line gives no usable name.

A note can be any size. The editor keeps the part around the cursor in memory and the rest on the card, so a file of a megabyte opens as fast as a short one and uses no more memory. What changes with size is how it is saved: Up to 64 KB, every save rewrites the file, as above. Above, the five-second save writes only what you changed, to a file next to the note (<note>.edit). The note itself is rewritten when you leave it, with a progress bar: about a second for each 450 KB. After a power cut, or if the device was switched off with the note open, opening the note again brings your saved changes back, and says so. Until then the file itself still has the old text, if you look at it from a computer. Saving a long note needs room on the card for a second copy of it. If the file was replaced by something else while its changes were waiting, they can't be applied: they are kept as <note>.edit.lost and the editor tells you.

In Storage, e on a text file opens it in the same editor, anywhere on the card, unless the file is read-only. Notes are never offered for deletion by the clean-up.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Notes, the list ; .up, down Enteropen the note , /a page up, down na new note rrename its file d Deldelete it ssort: newest, or by name Notes, the editor Entera new line Deldelete backwards Tabtwo spaces Fn ; . , /move the cursor Alt Fn ; .a page up, down Ctrl Fn ; .start, end of the note Ctrl a estart, end of the line opt ' ean accent: é `done: it saves by itself Notes, a file name Enterrename the file `cancel Deldelete backwards Fn , /move the cursor

KeyDoes c / xCopies or cuts the selected file or folder; the footer shows what is waiting to be pasted vPastes it into the folder shown. A copy next to its original is named name (2).txt; anything in the way is asked about first rRenames dDeletes, after saying what is inside: "Delete saved and its 42 files (1.2 MB)?" nMakes a folder iDetails: type, exact size, date, and why an item is read-only if it is A copy runs in the background of the card (about 400 KB a second), in short turns, so logs and captures keep being written. It shows its progress, Back cancels it and takes back what was copied, and each file's size is checked afterwards.

the top-level folders the firmware keeps its files in (what is inside them can be); /gemini/cache; a file being written right now: today's IRC log, a Track or a capture being recorded. The App says why when it refuses.

Enter on a file opens it by its type, and Tab switches the same file to a hex dump or to text: Text (.txt, .log, .gmi, .csv, and anything that looks like text): only a screenful is read from the card, so a file of any size opens at once, and logs open at the end. Up and down move a line, left and right a page, t and b go to the top and the end, and e edits it (up to 16 KB, as in Notes). Captures (.pcap): the packets as the LoRa Scanner lists them; Enter shows one with its Meshtastic header and bytes. Tracks (.gpx): the number of points, the start, the duration and the distance. Update files (.ota): the version, and whether the file would install: it is checked as an install checks it, signature and contents, without writing anything. Enter then installs it (see Updates). Anything else: a hex dump.

At the top of the card, the last row, Maintenance (or m), shows the card's usage and holds Storage clean-up and Erase SD card. They delete for good, so they sit behind a warning. Clean-up deletes old logs and captures by category and age, showing the space it would free first. Notes and Saved Pages are never offered. The firmware warns once per start when the card passes 80% full; past 90%, logs stop being written so that the rest is kept for captures.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Storage, a folder ; .up, down Enteropen the folder or the file , /a page up, down c xcopy, cut vpaste here rrename d Deldelete, after asking na new folder idetails: size, date, type ssort: name, date, size mMaintenance: clean-up, erase `the folder above Storage, an item's details ; .scroll Enterback to the folder Storage, a name Enterrename it, or make the folder `cancel Deldelete backwards Fn , /move the cursor Storage, while it copies or deletes `stop the copy or the delete Storage, Maintenance ; .up, down Enteropen, or choose A file, as text ; .a line up, down , /a page up, down t bthe top, the end eedit it Tabthe file as hex, or back A file, as hex ; .a line up, down , /a page up, down t bthe top, the end Tabthe file as text, or back A Capture ; .up, down Enterthe packet , /a page up, down Tabthe file as hex A Capture's packet ; .scroll Enterback to the packets A Track Tabthe file as text An Update File Enterinstall it, if it's genuine Tabthe file as hex

Type a command and press Enter. help lists them all; the command reference says what each does. A few to start with: CommandShows infoThe firmware's version, uptime, memory, Wi-Fi, the SD card and both firmware slots wifi statusThe network, the address, and where the DNS and time servers came from ls /notesA folder of the SD card, with sizes and dates crashThe last crash, if there was one update checkWhether a newer release exists lora statusWhat the radio is set to and what it has heard Tab completes what you are typing: the command, word by word (lora st gives lora status, and gnss track with Tab lists start stop), then a path on the SD card. ls /no and Tab gives ls /notes/; Tab again goes on inside the folder. If several names fit, it completes as far as they agree and lists them. You can type the name in any case, and after a file command you can leave out the first slash: cat no and Tab gives cat /notes/. A name with a space in it isn't completed. Fn with up and down brings back lines you typed before. Alt with up and down scrolls back through what was printed. clear empties the screen, and quit (or Back) leaves.

The replies to your own commands, and nothing else. The firmware prints a lot besides: IRC connecting, a packet received, whatever a PC on the USB port or the Debug Console is asking for. None of that reaches the Shell. The firmware knows who each line is printed for, so an answer that comes a moment later from another part of it (a folder listing, tasks) is still yours. Ctrl + b shows everything the firmware prints instead, and all shows in the corner. Press it again to go back.

Type an App's name with a capital letter to open it, without going back to the Launcher: Irc Wifi Gnss Gemini Lora Storage Notes System Settings The capital is the difference: every command is in small letters, every App starts with a capital. Tab completes them too.

rm works as it does on Unix, with one addition: it asks. You typeWhat happens rm /notes/a.txtAsks, then deletes the file rm -f /notes/a.txtDeletes it without asking rm /captures/oldRefused: it is a folder, and a folder needs -r rm -r /captures/oldRemoved at once if it is empty. If not, asks first rm -rf /captures/oldRemoved with everything in it, without asking

* stands for any run of characters in a name and ? for exactly one, in ls, du, rm, cp and mv: You typeWhat happens ls /notes/*.txtOnly the notes ending in .txt du /captures/lora/*.pcapThe size of each capture cp /gnss/2026-10-0?.gpx /backupCopies the tracks of the 1st to the 9th into /backup, which must exist rm /screenshots/2026*Asks once, saying how many match, then deletes them rm -f /screenshots/*Deletes them all without asking The pattern goes in the last part of the path (/notes/*.txt, not /*/a.txt), and capitals don't matter. A folder that matches is left alone by rm unless you add -r. At most 64 names at a time: past that nothing is done, and you are asked for a narrower pattern. cancel stops what is left. The folders the firmware keeps its own files in can't be removed, as in the Storage App.

screenshot the screen, now screenshot 5 the screen in 5 seconds: time to go to another App The picture is saved as a PNG in /screenshots on the SD card, named by date and time, and a Toast says so once it is written (so the Toast is never in the picture). From the Shell, "now" is always a picture of the Shell: use the pause to get to the screen you want. The Storage App shows the files; to look at them, take the card to a computer.

Nothing while it is closed. Open, about 7 KB of memory, given back when you leave: with IRC connected and a Gemini page open, that can be the difference (see the memory limit).

What Fn + h shows on this screen. This table is generated from the firmware's own lists, so it is always the current one. Shell Enterrun the line Tabcomplete: a command, a path * ?several files: /notes/*.txt Fn ; .lines you typed before Alt ; .scroll back, forward Ctrl byour replies only, or all Fn , /move the cursor Deldelete backwards helpevery command clearan empty screen Notesan App, by its name rm -rfdelete without being asked quit `leave the Shell

The device has about 107 KB of free memory and no PSRAM, so memory is the resource that decides what can run together: a secure connection takes about 52 KB at its peak. System makes that visible, and is how the project measures its own changes.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. System, any view Tabthe next view Aa Tabthe view before System, the tasks Tabthe next view Aa Tabthe view before ; .scroll ssort: cpu, stack, name System, the system view Tabthe next view Aa Tabthe view before ; .scroll

Wi-Fi on its own page switches the radio on and off. The page also has: Status: whether it is searching, joining, or connected, and to what. Add a network: scans, lets you pick one, and asks for the password (leave it empty for an open network). Add a hidden network asks for the name first. DNS and NTP: see below. Your saved networks. The device joins one on its own whenever it is in range, the strongest first. Enter on a network opens its page. An address by hand A network normally gives the device its address by itself (DHCP, Automatic). On a network without DHCP, open its page and set IP address to Fixed: then it takes an address, a prefix (24 is 255.255.255.0) and an optional gateway. Switching to Fixed starts from what the network is giving the device at that moment, and the setting is checked and applied when you leave the page. IPv4 only. Forget this network is on the same page. DNS and NTP Two DNS servers (9.9.9.9 and 1.1.1.1 by default), used on Fixed networks, or on every network if Always use my DNS is on; and two NTP servers (pool.ntp.org and time.cloudflare.com), used after any that the network's DHCP offers. Enter on Status shows what is in use and where each value came from.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Settings ; .up, down Enteredit, or open the page , /change a switch or a slider Settings, a choice ; .up, down Enterchoose it Settings, Wi-Fi ; .up, down Enteropen, or change , /switch Wi-Fi on or off Settings, DNS and NTP ; .up, down Enteredit , /Always use my DNS: on, off Settings, a saved network ; .up, down Enteredit, or forget , /Automatic or Fixed Settings, the Wi-Fi status Enterback Settings, adding a network ; .up, down Enterchoose this network Settings, a hidden network's name Enternext: the password `cancel Deldelete backwards Fn , /move the cursor Settings, Debug Console ; .up, down Enterswitch, or open , /switch the console on or off

The page shows the version running, its status, the address to push updates to over Wi-Fi, and: Latest release: Enter (or c) asks the server and says v0.11.0 (new) or (current). Enter again opens the release: its version, date, size and the tag's message, with Install when it is newer. Older releases: the last ten, newest first. Opening an older one offers to go back to it, with a different question. On the SD card: the .ota files found in /updates, ready to install. Copy one there with a computer or the Storage App; the Storage App also opens an .ota file and says whether it would install. An install needs Wi-Fi if it is a download. The new firmware is checked before anything is written (the signature after the first 160 bytes) and again at the end (the image's hash). Then the device restarts. It will wait up to 60 seconds if you are typing, so that a restart never eats a note.

Settings → Check for updates is on by default. Once a day, with Wi-Fi up and the clock set, the device looks at the latest release and says v0.11.0 is out: see Settings > Firmware, once per version. It installs nothing by itself, and it does not announce a version that already failed and rolled back on this device.

A newly installed firmware runs on Probation: it must boot, draw its screen, start its services and run 30 seconds without a crash, and reconnect Wi-Fi if that is configured (within 3 minutes), before it is confirmed for good. If it crashes or restarts, or cannot get Wi-Fi back, the device rolls back to the previous firmware by itself and says so.

If a confirmed firmware crashes and restarts 3 times in a row, the device starts in Safe Mode instead: only Wi-Fi and firmware updates, so a fix can be installed without a cable. A normal restart leaves it.

A secure connection takes about 52 KB of memory at its peak, and IRC's own takes about 40 KB of the 107 KB there is. So a check or an install that you ask for makes IRC disconnect for the few seconds it takes, and reconnect afterwards. The daily check never does that: with IRC connected it waits for a moment when IRC is not, so if IRC stays connected for days the daily check does not run, and Latest release is the way to check.

The connection to the project's server is checked against the two root certificates that Let's Encrypt's chains end in, not against the usual bundle of about 130 authorities. Whatever the connection, the update file's own signature decides what gets installed.

Updates can also be pushed from a PC over Wi-Fi, with scripts/flash.sh --ota <ip>, or put on the card with scripts/sd_put.sh: see the README. The firmware's console can be reached over Wi-Fi too: see The Debug Console.

What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. Settings, Firmware ; .up, down Entercheck, open, or install clook for a newer release Settings, a release ; .scroll Enterinstall it ccheck again Settings, older releases ; .up, down Enterits details cread the list again

A charge-only USB-C cable powers the device but never shows up as a serial port. If a cable has worked for data before, use that one.

Hold G0, the button next to the screen, while you plug in the USB cable, or while you press the reset button. Then try again. This is the first thing to try when an upload "can't connect".

The Install page flashes through the browser's Web Serial feature, which Firefox and Safari don't have. In Chrome or Edge, the browser asks you to pick the serial port from a list: pick the one that appears when you plug the Cardputer in. If the list is empty, go back to steps 1 and 2.

Your user needs access to serial devices. Run this once, then log out and back in: sudo usermod -aG dialout "$USER"

USB passthrough can fail with OSError: [Errno 71] Protocol error. Retrying alone doesn't help; resetting the Cardputer does, and putting it in download mode moves the serial port to a new name, so pick the port again afterwards.

The esptool steps on the Install page flash the same file without a browser, and their error messages are more detailed. If it still fails, open an issue and say what you see.

Eject first. A file being written (today's IRC log, a Track or a capture being recorded) is not complete until it stops. Stop it, or switch the device off, before you take the card out. Notes are yours. You can edit them on a computer and they show up on the device; the clean-up never offers them for deletion. Don't rename the top-level folders. The firmware looks for them by name. Logs stop at 90% full, so the remaining space is kept for captures. The Storage App's Maintenance shows what is using the card and clears old logs and captures, after showing what it would free.

DNS and NTP on the Wi-Fi page holds two DNS servers (9.9.9.9 and 1.1.1.1 by default) and two NTP servers (pool.ntp.org and time.cloudflare.com). They are used on Fixed networks, or on every network if Always use my DNS is on. Leave a second server empty if you only have one. IPv4 only. To go back, set IP address to Automatic. Forget this network is at the bottom of the same page.

r refreshes a saved page from the web, and d deletes it. Bookmarks (b) are a list of addresses, not copies: they need Wi-Fi to open. Saved Pages are never offered for deletion by the clean-up. They are in /gemini/saved/ if you want to move them. A file that is not text (a picture, say) is saved to /gemini/downloads/ and cannot be shown on the device.

Opening a Gemini page fails with not enough memory: stop IRC or retry. Or an update check or install makes IRC disconnect for a moment.

Stop IRC. In the IRC App, type /quit and press Enter. IRC disconnects and stays disconnected until you type something again, so it does not take the memory back. Try again. A Gemini fetch needs 55 KB free before it starts. Start IRC again when you are done: type a line in the IRC App, and it reconnects and rejoins its channels.

The System App's Memory view shows free memory, the lowest since the device started, and the largest free block, drawn against the three memory floors (55, 40 and 20 KB). Watch it fall when a connection opens, and recover when it closes.

The Cardputer's chip has no extra memory (no PSRAM). A secure (TLS) connection costs about 52 KB at its peak, and IRC's own connection holds about 40 KB of the 107 KB there is. A second secure connection on top does not fit, so the firmware refuses it early instead of crashing. This is also why IRC steps aside during an update, and why the daily update check waits until IRC is not connected: see Updates.

Press Fn + h, on any screen: it lists the keys that work there, then the ones that work everywhere. ? does the same when you are not typing text. The screens themselves never name their keys, so this is the one key to remember. See The basics.

Not yet. The LoRa Scanner listens to Meshtastic traffic and shows what it hears, but nothing is transmitted. A mesh messenger is the goal and is planned in two milestones, one for receiving and one for transmitting; it waits for a second node to test against.

No. roro9stack is its own firmware, written from scratch, which aims to be compatible with Meshtastic on the air. Today that means the Scanner can read a Meshtastic packet's header. The project isn't affiliated with or endorsed by Meshtastic or M5Stack.

No. The radio is receive-only in the current firmware. Nothing will transmit until you have confirmed your region in Settings, and the region's limits (frequencies, power, duty cycle) will bound anything that does.

an M5Stack Cardputer ADV: that is the device the firmware is built and tested for; the Cap LoRa-1262, for the LoRa Scanner and GNSS only: the other Apps do not need it; a microSD card, for notes, logs, tracks, captures and saved pages; Wi-Fi (2.4 GHz) for IRC, Gemini and updates.

EU868 only, today. Setup asks for your region once, and the radio does not transmit until you confirm it.

The browser flasher uses Web Serial, which Chrome and Edge have on desktop and Firefox and Safari don't. Without it, the esptool steps on the Install page flash the same file from a terminal.

Three ways, all with the same signed update file: from the project's releases on the device itself (Settings → Firmware), from the SD card, or pushed over Wi-Fi from a PC. See Updates and Install an update from the SD card.

A new firmware runs on Probation: if it crashes, restarts, or cannot get Wi-Fi back within 3 minutes, the device returns to the previous version by itself. If a confirmed firmware crashes 3 times in a row, it starts in Safe Mode with only Wi-Fi and updates, so a fix can be installed without a cable. And an update that is not signed with the project's key is refused before anything is written.

Yes: it is open source (GPL-3.0). The device only accepts updates signed with the key that its firmware was built with, so a build of your own, signed with your own key, is flashed once over USB (the README explains it); after that, your own updates go over Wi-Fi or the card. Releases from this project are signed with the project's key.

The firmware contacts the project's server once a day, to see whether a new release exists: Settings → Check for updates, on by default, only when Wi-Fi is up and the clock is set. It installs nothing by itself, and you can switch it off. Besides that, the device talks to what you ask it to: the IRC server and Gemini capsules you open, DNS servers (9.9.9.9 and 1.1.1.1 by default) and time servers (pool.ntp.org and time.cloudflare.com by default), all of which you can change. There is no account, no analytics and no telemetry. This website sets no cookies and has no analytics, loads nothing from other sites, and its server logs keep only a masked part of visitors' addresses. The Install page asks the project's own server for the latest release.

A secure connection takes about 52 KB of the 107 KB the device has, and IRC's takes about 40 KB. Both together do not always fit. See When a connection says "not enough memory".

For the radio, GNSS position, Wi-Fi tools, IRC chat and Gemini browsing, no. For anything that is kept, yes: notes, IRC logs, Wi-Fi scan logs, GNSS Tracks, LoRa captures, saved Gemini pages and update files. See Find your files on the SD card.

Any size the card has room for. The editor only keeps the part around the cursor in memory, so a megabyte of text opens at once. A long note is rewritten when you leave it, which takes about a second for each 450 KB. See Long notes.

The firmware keeps its files in the top-level folders of the card, and /gemini/cache and any file being written right now are protected. What is inside the top-level folders can be changed. The Storage App says why when it refuses.

Try a data cable, put the Cardputer in download mode (hold G0 while plugging in USB), and see When flashing fails.

Write to the issue tracker or to contact@roro9stack.net. Security problems: the address in the site's security.txt, and please not in the public tracker.

There is no special build. Every roro9stack firmware has the Debug Console, the same one, and the commands made for testing (crash on purpose, fake an installed version, damage a download, inject a LoRa packet). It is off until its owner switches it on. Off means nothing is there: no socket listens, the console's task does not exist, and neither does its 4 KB buffer. A device that never uses it pays 30 KB of flash and 88 bytes of memory. Before version 0.12 this was a separate Debug Build with a token compiled in from the builder's machine, which is why it could not be published. ADR 0010 says why that changed.

Settings → Debug Console: RowDoes Debug ConsoleThe switch. Switching it on asks first (the question opens on Cancel: move to Switch on), and makes a token if there is none Connect toThe address and port: 10.39.39.12:2323 New tokenMakes another one. The old one stops working, and whoever is connected is cut off Type a tokenOne of your own, of 16 to 64 characters Under the rows, the token, in large type on two lines, in groups of four: K7QF-3M2X-9WBD-HT4P-6RNC. This page is the only place it is ever shown. The Status Bar shows DBG while the console listens, and brighter while someone is connected. The setting stays across restarts and updates, and in Safe Mode.

The device makes it, from its hardware random generator, the first time the console is switched on: 100 bits, written as 20 characters without the letters that get misread (no I, L, O or U). Dashes and case do not count, and an O, I or L is taken for the 0 or 1 it was. Type it as you read it. One you type must have at least 16 characters. A short one would be the weakest part of the whole thing. It is never printed on a console, and it never crosses the network (the Debug Console says how). It guards against the network, not against someone who holds the device: anyone with USB access can flash anything anyway (ADR 0003).

scripts/rdbg.py looks for it in this order: scripts/rdbg.py -t K7QF-3M2X-9WBD-HT4P-6RNC info # 1. on the command line (also --token) RORO_DEBUG_TOKEN=K7QF-3M2X-9WBD-HT4P-6RNC scripts/rdbg.py info # 2. in the environment echo K7QF-3M2X-9WBD-HT4P-6RNC > ~/.config/roro9stack/debug-token # 3. in a file, for the device you use every day

With the device on a cable, the console can be set up from the PC: scripts/flash.sh --debug # flashes over USB, then switches the console on and gives it your token It sends two commands over the serial port, which you can also type there yourself: debug on # switch it on (a token is made if there is none) debug token <value> # give it this token: 16 to 64 characters debug token new # make a new one debug status # on or off, token set or not, a client or not (the token itself is never shown) debug off # switch it off debug off 30 # ...for 30 seconds: it comes back by itself debug on and debug token work over USB serial only: the console cannot be used to open itself wider. debug status and debug off work from anywhere, and a screenshot taken over the console while this page is open shows the token, to someone who already had it. Your token file is made by the first build (scripts/_docker.sh), 32 hex digits, and is never committed. Since the setting survives updates, this is needed once for a device, not at each flash. Later builds go over Wi-Fi with scripts/flash.sh --ota.

On your own network, on a device you are working on: yes, that is what it is for. Remember what it gives to whoever has the token and is on the same network: the console, the keys, the files on the SD card, a restart. It does not give them the firmware: an update still has to be signed. On a network you share with strangers, switch it off, or at least know that what the console prints is not encrypted. The token is safe there; the conversation is not.

export RORO_OTA_HOST=10.39.39.12 # or pass -H <ip> scripts/rdbg.py # interactive: the backlog, then live lines; type commands scripts/rdbg.py info # one command, and its reply scripts/rdbg.py -b tasks # the same, with the backlog shown first scripts/rdbg.py is a Python script with no dependencies. A one-shot command prints the reply and what follows, until the console has been quiet for a moment (1.5 seconds). It takes the token from -t, $RORO_DEBUG_TOKEN or ~/.config/roro9stack/debug-token (Switch the console on) and talks to TCP 2323 on the device's address. In interactive mode, Ctrl+D or quit leaves. Piped input works too, but rdbg.py leaves as soon as its input ends, before the replies arrive: keep the input open for a few seconds, as in (printf 'info\ntasks\n'; sleep 3) | scripts/rdbg.py. For one command, the one-shot form above is simpler. The device listens only while the console is switched on and Wi-Fi is connected, and the console follows Wi-Fi: it stops listening when Wi-Fi drops and starts again when it is back.

On connecting, in order: a banner: roro9stack v0.12.0 debug console. 'help' lists the commands. Backlog follows. the backlog: the last 4 KB of console output, oldest first (a ring buffer in RAM, kept while the console is switched on: boot messages included, if it was on at boot); then every new line, live: everything the firmware prints, and ESP-IDF's own log lines, which are copied into the same stream (they still reach the USB port too); the replies to your commands, in the same stream, each preceded by the > command line when it runs. A line status: heap <free> min <lowest> appears every 10 seconds in the stream: a free-memory trace you get without asking. > net net: IRC in 0 out 0 net: Gemini in 0 out 0 net: Debug Console in 1038 out 205115 net: Updates in 4788 out 204 If you are not reading fast enough (a slow link), the device says so in the stream instead of stalling: [... 312 bytes lost: the console ran faster than the network].

It is a plain line protocol, easy to speak from anything. This is what rdbg.py does, and all it needs: StepDetail ConnectTCP 2323. One client at a time: a second one waits until the first leaves ChallengeThe device sends one line: roro9stack debug console, challenge <32 hex digits>. Those are 16 random bytes, new each time AnswerWithin 10 seconds, send the HMAC-SHA256 of those 16 bytes, keyed by the token, as 64 hex digits and \n. The token is the tidied one: capitals, no dashes AcceptedThe banner line, then the backlog RefusedAfter about a second the device sends denied\n and hangs up, and prints debug: refused a client from <ip> on its own console LockedFive wrong answers in a row close the console to everyone for 60 seconds: it answers locked\n and hangs up, and a Toast on the device names the address they came from CommandsOne line each, up to 240 bytes. The device queues at most 8; past that, debug: busy, command dropped Leavequit or exit closes the connection Binary commandsget, put, screenshot, coredump get: a text header line, then raw bytes (see files and screens) The token never crosses the network. Someone on the same Wi-Fi who records a login gets a challenge and its answer, which are no use for the next challenge. The comparison on the device takes the same time whatever it is given. A command that never runs has not been dropped by the network: the main loop is busy or stuck. That is what the next section is about.

your PC rdbg.py token first Debug Console task token check, one client ring → socket, live lines → command queue answers these itself: get · put · screenshot coredump get · reset (they work with the loop stuck) main loop runCommand(): the same commands as USB serial console 4 KB ring + USB serial, if there's room ESP-IDF logs (tee) storage task SD card jobs ls rm install get put TCP 2323 queue read printf jobs The console task only queues command lines. The main loop runs them with the same code as USB serial commands. Binary commands are answered by the console task itself, so they work when the main loop is stuck. Text commands run on the main loop, exactly like serial ones: they touch the Apps and the Services from the one task allowed to. The main loop prints > command as it starts, and the reply follows in the stream. Binary commands run on the console's own task: get, put, screenshot, coredump get and reset. A failed put closes the connection, so the rest of the file is never read as commands. That split is the point: with the main loop stuck (an infinite loop, a deadlock), text commands queue forever, but reset still restarts the device at once, coredump get still reads the dump, and get still reads files. A loop stuck for 5 seconds is a panic with a core dump anyway: see Crashes and Safe Mode. Card work stays on the storage task: ls, rm, cp and install from the main loop, get and put from the console task, all as jobs the storage task runs, so the card is only ever touched from one place. Writes to the console never wait for USB: a host attached to the USB port but not reading used to stall the main loop for up to two seconds per line.

Off by default. Nothing listens until the console is switched on at the device, or over USB. The login is a challenge and an answer: the token itself is never sent, and five wrong answers close the console for a minute. Anyone on the same network with the token can read the console, press keys, copy the SD card's files and restart the device. The console never prints stored secrets (the token, Wi-Fi and IRC passwords), but the IRC traffic it shows is readable. They cannot change the firmware: an update still has to be signed. The stream after the login is plain text: fine on a home network, not across the internet. Do not forward port 2323. The decisions are ADR 0010 and, for how the console works inside, ADR 0004.

Anything that can open a TCP connection and compute an HMAC works: import hashlib, hmac, socket token = "K7QF3M2X9WBDHT4P6RNC" # tidied: capitals, no dashes s = socket.create_connection(("10.39.39.12", 2323)) challenge = s.makefile().readline().split()[-1] # "... challenge 0f1e2d..." answer = hmac.new(token.encode(), bytes.fromhex(challenge), hashlib.sha256).hexdigest() s.sendall((answer + "\n").encode()) # then read the banner line s.sendall(b"info\n") # and what follows, until the stream goes quiet scripts/rdbg.py adds the parts that need work on the PC side: decoding crash backtraces, saving files and screenshots, and checking checksums.

scripts/rdbg.py get /gnss/tracks/20261004-142530.gpx # saved here, under its own name scripts/rdbg.py get /captures/lora/capture.pcap my-capture.pcap The device answers get: data <size>, then exactly <size> bytes, then get: end. A path it cannot open (missing, or a folder) gives get: error cannot open <path>. The script prints the size and the speed.

scripts/rdbg.py put roro9stack-v0.12.0.ota # to /updates/roro9stack-v0.12.0.ota scripts/rdbg.py put notes.txt /notes/from-the-pc.txt # to a path you choose The default destination is /updates/<name>, so this is also the way to install an update from the SD card without touching the device: put the .ota file, then scripts/rdbg.py install /updates/<name>. The device does a few things you want from a file transfer: the PC sends the size and the SHA-256 first (put <path> <size> <sha256>); the device answers put: ready <size> or put: error <why> (no card, not enough space: it wants the size plus 64 KB free, or a path or size it refuses); it writes to a temporary .part file, creating missing folders, and only renames it into place after the whole file has been read back from the card and its SHA-256 matches: the checksum covers what is on the card, not what arrived; a write the card refuses is retried up to 3 times, cutting the file back to the last good byte, and gives up rather than leave a hole in the middle; it ends with put: done <path> <size> B, or put: error <why> and a closed connection (so the rest of the file is never read as commands). A failed transfer leaves nothing on the card. Speed is about 300 KB/s. The same transfer exists over USB serial, for a device with no Wi-Fi: scripts/sd_put.sh <file> [card path] (about 30 seconds for 1.6 MB, with the card left in).

scripts/rdbg.py screenshot ui.png # 480x270: the 240x135 screen at 2x The device sends screenshot: rgb332 <width> <height> and then one byte per pixel: the frame the UI composed off-screen, in RGB332 (RRRGGGBB), the way M5GFX stores an 8-bit sprite. The script expands it and doubles it into a PNG. It is read as it stands, while the UI may be drawing, so it can tear. It is for looking at, not for pixel-exact comparison. It is the real thing: the screenshots on this site, in the user guide and the devlog, were taken this way. With a number, it saves to the card instead: screenshot 5 (or screenshot 0) writes a PNG to /screenshots on the SD card after that many seconds, as the Shell does. A bare screenshot over the console is the binary one above. Its main use is in a loop: send a key, wait a moment, take a screenshot, look. See Drive the UI.

The raw contents of the core dump partition: coredump: data <size>, the bytes, coredump: end, or coredump: none. scripts/rdbg.py coredump fetches and decodes it in one go: see Crashes and Safe Mode.

scripts/rdbg.py reset The console prints debug: restarting now and restarts the chip after a moment. It does not go through the main loop, so it works when the loop is stuck. (The text command reboot does go through the main loop: a clean restart. boot other restarts into the other app slot: a manual rollback.)

key up|down|left|right|select|back|home|del|tab|space|help key a # any single character: it is typed Two things to know before you use them: A name key does not know is select. key sleect presses Enter. A single character is typed as that character; anything else that is not a known name is treated as Enter. Check what you type. A key that wakes a dark screen only wakes it. The device's power policy swallows the key press that turns the screen back on, as it does for the real keyboard: the first key after the screen went off does nothing else. Send key back (harmless) first, or keep the screen on with the normal and short commands below. Ctrl, Alt and Shift go before the name: key ctrl-down, key alt-up, key ctrl-b, key shift-alt-down. Fn combinations and the compose key have no command: the arrows are key up|down|left|right (what Fn with ; . , / gives on the device), and key back is the back key (` on the device). Text is typed one character at a time. key help opens the help panel (Fn+h on the device): the keys of the screen that is showing. A screenshot of it is the quickest way to learn what a screen accepts, and it is how every screen's list was checked. Any key but the arrows closes it.

Notes # an App's name, with a capital: opens it Shell # Irc Wifi Gnss Gemini Lora Storage Notes Shell System Settings info # ...and `app: Notes` says which App is in front Far better than key home, some key down and key select: it doesn't depend on where the Launcher's selection was.

Take a screenshot before any key that deletes, renames or installs. A blind sequence of key commands goes wrong the moment the screen is not where you think it is, and the screen is often not where you think it is: a Toast, a dialog that has not closed, a different App. A sequence that was meant to open a note once renamed real data instead. scripts/rdbg.py key home # to the Launcher scripts/rdbg.py screenshot a.png # look: is it the Launcher? scripts/rdbg.py key down scripts/rdbg.py key select scripts/rdbg.py screenshot b.png # look again before the next destructive step Check the App in front before typing anything. info prints app: <name>. A crash restarts the device into the Launcher, and a script that goes on typing is typing somewhere else: one of this project's own test scripts sent a word to an IRC channel that way. Prefer reading a state to assuming it: info, ls <folder>, cat <file>, irc dump, gnss status, lora status, wifi status, update status. Test on a scratch folder on the card, not on your real files. For anything that deletes (rm, a delete dialog), ls first and ls after.

short # screen dims after 5 s, turns off after 10 s: to test the screen policy normal # back to 30 s and 60 s burst # five Toasts at once: to test notifications sound on | sound off

Each of these puts something in, without the outside world: CommandWhat it does lora inject <hex> [rssi] [snr]A packet into the LoRa Scanner as if the radio had received it. Nothing is sent irc say <buffer> <text>Types into an IRC buffer, commands included: irc say 0 /join #test log <text>Adds a line to a test IRC log gnss send <sentence>Sends an NMEA sentence to the GNSS receiver (the checksum is added), to configure it gemini get <url>Fetches a page and reports header, size, certificate and heap use, without the App gemini trust <host> <port> <sha256>Pins a certificate by hand sd fill <folder> <count>Makes that many small files in a folder, to test a crowded one (the Storage App shows the first 256) wifi add <ssid><TAB><password>Adds a Saved Network, so credentials stay out of the repository

An update that goes wrong is the case you most want to rehearse, and the firmware can make it go wrong on purpose: update status # what the device runs, what failed here before, the daily check, heap update check | update list # look at the server: the latest release, or the last ten update pretend v0.9.0 # take the running version to be v0.9.0: the latest release now counts as "new" update damage cut 50000 # the next download is cut after 50000 bytes update damage flip 100000 # ...or has the byte at offset 100000 damaged update install v0.11.0 # try the install update probe git.twis.la # is that server's certificate accepted? (the two ISRG roots only) update daily # forget today's daily check: it runs again at the next tick update pretend off # back to the real version A damaged download must be refused cleanly: the Update Service checks the signature after the first 160 bytes and the image hash at the end, so a cut or a flipped byte must end in a refusal with nothing switched. Check info afterwards: both slots, and update: confirmed. An undamaged install really installs the release, into the other slot, and the device restarts into it. Your build stays in the slot it was in until the next update overwrites it, and the console's setting and token are untouched: the release has the console too. The server is read by the device itself, with Wi-Fi up; the download is one TLS connection, about 52 KB of heap at its peak, so IRC steps aside (see the memory limit). status: heap in the stream shows it happen. For crashes during Probation, see Crashes and Safe Mode.

The Debug Console runs over the Wi-Fi you are about to change, which is the usual way to lock yourself out. A trial IP setting takes care of it: wifi ip MyNet 10.39.39.50/24 10.39.39.1 try 60 # use this address for 60 s... wifi ip keep # ...and keep it, if you could still reach the device If you do not send wifi ip keep in time, the device goes back to the previous setting by itself, and the console comes back with it.

info # firmware, uptime, last start reason, heap now/lowest/largest block, chip temperature, Wi-Fi, SD faults, both app slots tasks # each task over the next second: state, priority, least free stack, CPU share; each core's load; main-loop passes net # bytes each network service has read and written since start tasks takes a second to answer. A low number in the stack column is a risk (the System App shows it in the warning colour under 512 bytes). loop spin on|off makes the main loop spin without resting, to compare load and radio noise. And the status: heap line every 10 seconds in the stream is the cheapest memory trace there is: watch it while you do the thing you suspect. task st pri stack cpu% core loopTask R 1 1828 1.3 1 wifi B 23 4072 0.7 0 debug B 1 3088 0.5 -1 ... load: core 0 2 %, core 1 1 % loop: 50 passes in the last second, chip 35.3 C The System App shows the same, live, on the device.

lora preset <name> and lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble] change what the receiver listens to (receive only: the radio never transmits), lora sweep on [from] [to] [step] takes a survey, and lora noise test [gnss|quiet] runs a Sweep under one changed condition at a time, with Wi-Fi off for a moment, to find what raises the noise floor. lora probe finds the radio and reports its chip, oscillator, antenna switch, interrupt line and noise floor. Details in the command reference.

A core dump in a flash partition: ESP-IDF writes it on a panic. A crash record in NVS, written first thing at the next boot: which version was running (so after a Rollback has switched slots, the firmware still knows which one crashed), and how many starts in a row followed a crash. A summary on the console after the restart (task, program counter, reason, backtrace), and a Notification on screen. The crash command prints it again whenever you like: > crash crash: last one in v0.9.0-1-g4ab873e-dirty (panic) crash: task loopTask, pc 0x4037e179, cause 0, address 0x00000000 crash: reason: abort() was called at PC 0x421209b3 on core 1 crash: backtrace 0x4037e179 0x4037e141 0x4038582d 0x421209b3 ... crash: elf sha256 3c6a185e5 coredump erase forgets the dump.

An address is no use without the exact build that crashed. Every build archives its ELF in .pio/elves/, named by version and the first 16 hex digits of its SHA-256 (scripts/version.py); the core dump names the crashed firmware by the same digest. So a crash can be decoded after later builds, including a build you have since replaced: scripts/rdbg.py crash # the crash report, with the backtrace turned into functions and source lines scripts/rdbg.py coredump # fetch the whole core dump, then decode it scripts/rdbg.py coredump my.bin # ...to a file you name crash runs the device's crash, finds the ELF by digest (or by version), and passes the backtrace to scripts/decode_backtrace.sh, which runs addr2line from the build container: one line for each frame, with function and file:line. coredump fetches the raw dump over the console (it works when the main loop is stuck) and runs scripts/decode_coredump.sh: esp-coredump and GDB, giving every task's backtrace, the registers, and the crashed task's stack. By hand: scripts/decode_backtrace.sh <version|digest> <address>..., and scripts/decode_coredump.sh <core.bin> <version|digest>. Both say which ELF they used. A release's ELF is fetched for you. When the crash names a released version (v0.12.0) and no local ELF matches, rdbg.py downloads roro9stack-<version>.elf.gz from the release on Gitea into .pio/elves/, so a crash on a firmware you did not build can be decoded. Decoding itself still runs in the build container. If nothing matches, the scripts say so: an unreleased build made on another machine, or .pio/ was cleaned.

Arduino-ESP32 puts only core 0's idle task on the task watchdog, and the main loop runs on core 1: a stuck loop used to hang the device for good, with a frozen screen and a console that could not run commands. Now a loop stuck for 5 seconds is a panic, with a core dump, counted towards Safe Mode. The rule that follows: nothing in the main loop may block for 5 seconds. Network and card work already run on their own tasks. An installed update no longer depends on the main loop either: the Update Service restarts into it by itself after 90 seconds.

The count of starts that follow a crash (a panic or the watchdog) is kept in NVS. After three in a row, the firmware starts Safe Mode instead of everything else: only the clock, Wi-Fi, the Update Service and, if it is switched on, the Debug Console start: no Apps, no IRC, no SD card; the screen says so, with the address to push an update to; only a few commands run (the command reference lists them); anything else answers not available in Safe Mode. Any normal restart (reboot, an update) or a minute of uptime resets the count. So Safe Mode is reached by crashing three times quickly, and a crash loop costs about half a minute before the device becomes reachable. To leave it: push a fix (scripts/flash.sh --ota), or reboot. Over USB, debug on works in Safe Mode too, if the console was off. Its limit: if Wi-Fi or the Update Service is what crashes, Safe Mode cannot help, and it takes USB.

crash abort # abort(): a panic with a core dump crash wdt # hang the main loop until the task watchdog fires Use them to see a real report and decode it, to check that the counter reaches Safe Mode, and to prove that a build you are about to rely on will survive its own crashes. The device restarts by itself after either, and the report is there to read when the console comes back.

The firmware's own list, read from src/main.cpp. Every firmware has all of them, over USB serial and over the Debug Console. The ones marked Debug Console only exist only over Wi-Fi, where rdbg.py speaks them, and the ones marked USB serial only only over the cable: info firmware, uptime, memory, Wi-Fi, app slots tasks FreeRTOS tasks over the next second: state, priority, free stack, CPU share net bytes each network service has read and written since boot reboot restart boot other restart into the other app slot (manual Rollback) log level <0-5> ESP-IDF log level (0 none ... 5 verbose) ls [folder] | du <path> | mkdir <path> | rm [-r] [-f] <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel the SD card, with the Storage App's rules (rm -r for a folder; -f: the Shell doesn't ask; * and ? in a name: /notes/*.txt) screenshot [seconds] the screen as a PNG in /screenshots on the card, now or after a pause lora probe | lora status | lora rx on|off | lora preset <name> the LoRa radio, receive only lora capture start|stop a LoRa Capture to /captures/lora (pcap, LoRaTap) lora sweep on [from MHz] [to MHz] [step kHz] | lora sweep off | lora sweep dump RSSI across a band (863 870 100) lora custom <MHz> <BW kHz> <SF> <CR 5-8> <sync hex> [preamble] e.g. 868.1 125 7 5 34 8 (LoRaWAN) gnss quiet on|off pause the GNSS receiver while the LoRa radio listens (it costs the radio 8 dB) gnss status | gnss restart | gnss track start|stop | gnss nmea on|off | gnss send <sentence without $ and checksum> crash the last crash: firmware, reason, task, backtrace coredump erase forget the core dump in flash key <name|char> press a key: up down left right select back home del tab space help, or one character; ctrl- alt- shift- before it (key ctrl-down) wifi status | wifi add <ssid><TAB><password> wifi ip <ssid> dhcp | wifi ip <ssid> <address>/<prefix> [gateway] a Saved Network's IP setting wifi dns <a> [b] | wifi dns always on|off | wifi ntp <a> [b] DNS and NTP servers gemini get <url> fetch a Gemini page and report header, size, certificate, heap irc start | irc stop | irc dump | irc say <buffer> <text> install <path.ota> Update from SD update check | update list | update status | update install <tag> the project's releases on Gitea sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal Irc | Wifi | Gnss | Gemini | Lora | Storage | Notes | Shell | System | Settings open that App: a capital letter is an App, not a command debug status | debug off [seconds] the Debug Console over Wi-Fi (Settings > Debug Console); with seconds, it comes back debug on | debug token <16 to 64 characters> | debug token new (USB serial only) switch it on, set its token crash abort|wdt crash on purpose (to test crash reports and Safe Mode) wifi ip ... try <seconds> | wifi ip keep a trial IP setting: back to the previous one unless kept loop spin on|off make the main loop spin without resting, to compare load and radio noise lora noise test [gnss|quiet] | lora noise report Sweep under one changed condition at a time (Wi-Fi goes off for a moment) lora inject <hex> [rssi] [snr] a packet into the LoRa Scanner as if received (nothing is sent) sd fill <folder> <count> makes that many small files there, to test a crowded folder coredump get (Debug Console only) send the raw core dump: use scripts/rdbg.py coredump reset (Debug Console only) restart at once, even if the main loop is stuck get <path> | put <path> <size> <sha256> | screenshot (Debug Console only) binary, see rdbg.py: there, a bare `screenshot` sends the screen instead of saving it quit close the Debug Console connection In Safe Mode (see Crashes and Safe Mode) only a few run: help, info, tasks, net, reboot, boot other, wifi status, and anything starting with log level, crash, coredump, wifi add, debug. Anything else answers not available in Safe Mode.

scripts/serial_log.sh [seconds] [command…] records the serial output, and can send commands to the firmware first. For example, scripts/serial_log.sh 30 short sleep:12 burst sets short screen timeouts, waits 12 s, then sends a burst of Toasts. CommandEffect burstPublishes 5 Notifications at once key up|down|left|right|select|back|home|del|tab|space|help, or key <char>Injects a key press (help is Fn+h: the keys of the screen that is showing). ctrl-, alt- and shift- before it hold that key: key ctrl-down, key alt-up, key ctrl-b sound on / sound offToggles the Sound setting (beep + LED) short / normalScreen timeouts 5 s / 10 s, or 30 s / 60 s wifi add <ssid><TAB><password>Adds a Saved Network (so credentials stay out of the repo) wifi ip <ssid> dhcp / wifi ip <ssid> <address>/<prefix> [gateway]A Saved Network's IP setting: Automatic, or Fixed. Add try <seconds> to go back to the previous setting unless wifi ip keep follows wifi dns <a> [b] / wifi dns always on|off / wifi ntp <a> [b]DNS servers (used on Fixed networks, or always), and NTP servers log <text>Appends a line to a test IRC Log (/irc/dev/#test/<date>.log) sd cardWhat the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date) sd listLists the files of each Storage Clean-up category sd fill <folder> <count>Makes that many small files in a folder, to test a crowded one cat <path>Prints the first ~1.2 KB of a file on the SD card irc startStarts the IRC Service (normally done by opening the IRC App) irc stopStops it, as /quit does: QUIT if connected, no more retries, and the App stays disconnected until you type gemini get <url>Fetches a Gemini page and prints its header, size, certificate fingerprint and heap use gemini trust <host> <port> <sha256>Pins a certificate by hand (the Gemini App asks when one changes) irc say <buffer> <text>Types into a Buffer, commands included (irc say 0 /join #test) irc dumpPrints IRC status, memory, and the last lines of each Buffer wifi statusPrints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from infoFirmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, which App is in front, and both app slots with their versions and OTA states Notes, Irc, Wifi, Gnss, Gemini, Lora, Storage, Shell, System, SettingsOpens that App: a capital letter is an App, not a command tasksFreeRTOS tasks over the next second: state, priority, lowest free stack, share of a core, each core's load, and how many passes the main loop made netBytes each network service has read and written since boot reboot / boot otherRestart, or restart into the other app slot (a manual Rollback) log level <0-5>ESP-IDF log level ls [folder] / du <path>Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path screenshot [seconds]The screen as a PNG in /screenshots on the card, now or after a pause to get to the screen you want (240 x 135, about 33 KB). Over the Debug Console a bare screenshot sends the screen to the PC instead cp [-f] <from> <to> / mv [-f] <from> <to> / rm [-r] [-f] <path> / mkdir <path> / cancelWhat the Storage App does, with its rules: copy (folders too), move or rename, delete (rm -r for a folder and what's in it, as Unix has it), new folder. -f replaces a file that's in the way; * and ? in the last part of a path (ls, du, rm, cp, mv) run the command for each name matched, 64 at most; a tab separates paths that hold spaces; cancel stops a copy or a delete install <path>Update from SD with that .ota file, as Settings → Firmware does update check / update list / update status / update install <tag>The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one update pretend <version> / update probe <host> / update damage cut|flip <n> / update dailyPretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again lora probeFinds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor lora statusRadio settings, who's listening, packet and error counters, noise floor, task stack lora rx on / lora rx offListens and prints each packet on the console lora preset <name> / lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]Receive settings: a Meshtastic preset, or anything else (lora custom 868.1 125 7 5 34 8 for LoRaWAN) lora capture start / lora capture stopA LoRa Capture, as c in the App lora sweep on [from MHz] [to MHz] [step kHz] / lora sweep off / lora sweep dumpSweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass gnss quiet on / gnss quiet offThe "Pause GNSS for LoRa" setting gnss status / gnss restartThe receiver's state, and a restart of it gnss track start / gnss track stopA Track, as r in the GNSS App (the reason is printed if it can't start) gnss nmea on / gnss nmea offPrints each NMEA sentence the receiver sends, as nmea: … gnss send <sentence>Sends a sentence to the receiver, without the $ and the checksum (it adds them) lora noise test [gnss|quiet] / lora noise reportSweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result lora inject <hex> [rssi] [snr]A packet into the Scanner as if received (nothing is sent) crashThe last crash: which firmware, why, task, PC and backtrace (from the core dump in flash) coredump eraseForgets the core dump loop spin on / loop spin offMake the main loop spin without resting, to compare load and radio noise crash abort / crash wdtCrash on purpose, or hang the main loop until the watchdog fires debug status / debug off [seconds]The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long debug on / debug token <value> / debug token newUSB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed helpLists the commands scripts/flash.sh stops a running serial log first, since it would hold the port.

Only Docker is needed. PlatformIO and the ESP32 toolchain run inside a container, and are cached in the roro9stack-pio Docker volume. The first build downloads about 1 GB and takes a few minutes.

scripts/ci.sh This runs the host-side unit tests (test/, native environment), then builds the firmware. The output is .pio/build/cardputer-adv/firmware.factory.bin. scripts/coverage.sh runs the same tests with coverage counters and writes a line-by-line report to .pio/coverage/index.html. The badge above is its figure for main: the share of the lines of lib/ that the host tests run. lib/ is the logic that compiles on a PC; lib/SD (the card's driver) and src/ (the Apps, the Services, everything that needs the device) have no host tests and aren't in that figure. The framework is rebuilt with the TLS settings in platformio.ini (custom_sdkconfig, ADR 0006), so the first build after a fresh checkout takes about 6 minutes; later builds take about 15 seconds when little has changed. The platform knows the framework is already rebuilt by sdkconfig.defaults in the project folder, which it writes and git ignores: delete it and the next build rebuilds the framework. CI keeps that file, a build cache and ccache in its volume (docs/milestones/R1.md).

Gitea Actions (.gitea/workflows/ci.yml, docs/milestones/R1.md) runs the host tests on every push to main, and on a pull request also builds the firmware: changes reach main through pull requests. Pushing a tag v* runs all of it and publishes a release on Gitea with: roro9stack-<version>.ota, the signed Update File; roro9stack-<version>-factory.bin, the whole flash image for a first install over USB; roro9stack-<version>.elf.gz, to decode crash reports from that build; SHA256SUMS. CI signs with the project's key, held as a repository secret (ADR 0008). There is one firmware: the Debug Console is in every build, switched off until its owner switches it on (ADR 0010). scripts/ota_verify.py <file.ota> checks an Update File on a PC the way a device does. scripts/release_build.sh and scripts/release_publish.py are what the workflow runs; they work the same by hand.

Connect the Cardputer by USB-C. Run: scripts/flash.sh # auto-detects the port; or: scripts/flash.sh /dev/ttyACM1 This uploads the firmware, then opens the serial monitor. Quit the monitor with Ctrl+C. If the upload can't connect, put the device in download mode: hold G0 (the button next to the screen) while plugging in USB, or while pressing reset. Then retry. If you get "permission denied" on the port, your user needs access to the serial device. Run this once, then log out and back in: sudo usermod -aG dialout "$USER"

Once the Cardputer runs an OTA-capable firmware (flashed once over USB), updates can go over Wi-Fi: scripts/ota_keygen.sh # once: creates the signing key (see ADR 0003) scripts/flash.sh --ota 10.39.39.12 # build, sign and push; or set RORO_OTA_HOST The device shows the push address in Settings → Firmware. It installs a correctly signed update right away, restarts (waiting up to 60 s if you're typing), and runs the new firmware on Probation. If the new firmware crashes, or can't reconnect Wi-Fi within 3 minutes, it rolls back to the previous one and says so. To install from the SD card instead, copy the .ota file from .pio/build/cardputer-adv/ into /updates on the card, then use Settings → Firmware. With the Cardputer on USB, the card can stay in: scripts/sd_put.sh <file.ota> sends it over the serial console into /updates (about 30 s for 1.6 MB, checked with SHA-256 before it's renamed into place; SD_PUT_DEBUG=1 shows the console while it runs). The private key lives in ~/.config/roro9stack/ota-key.pem and must never be committed. If it's lost, generate a new pair and flash once over USB. (CI signs releases with a copy kept as a repository secret, ADR 0008.) Updates from Gitea With no PC and no card, the device can install the project's releases itself (docs/milestones/R1.md). In Settings → Firmware: Latest release checks the server (Enter, or c) and says v0.11.0 (new) or (current). Enter again opens the release: its version, date, size and the tag's message, with Install when it's newer. The download goes straight into the inactive slot, so no card is needed; the signature is checked after the first 160 bytes, before anything is written, and the image's hash at the end. The new firmware then runs on Probation as for any update. Older releases lists the last ten, newest first. Opening an older one offers to go back to it, with a different question. Settings → Check for updates (on by default): once a day, with Wi-Fi up and the clock set, the device looks at the latest release and says v0.11.0 is out: see Settings > Firmware, once per version. It installs nothing by itself, and doesn't announce a version that already failed and rolled back on this device. The connection is checked against the two ISRG roots Let's Encrypt chains end in (ADR 0009), not the usual bundle of about 130 authorities. Whatever the connection, the Update File's own signature is what decides what gets installed. IRC steps aside. A secure connection takes about 52 KB of memory at its peak, and IRC's own takes 40 KB of the 107 KB there is. A check or an install you ask for makes IRC disconnect for the few seconds it takes and reconnect afterwards. The daily check never does that: with IRC connected it waits for a moment when IRC isn't, so while IRC stays connected for days it doesn't run, and Latest release is the way to check. There is no separate Debug Build any more (ADR 0010): every firmware installs releases, and the Debug Console is a setting, which an update leaves as it was.

Update File (.ota) a 160-byte header, little-endian, then the image RORO-OTA fmt hdr size image SHA-256 version len signature 0… the image, ~1.6 MB 081012 16488082 154160 signed: ECDSA P-256 over SHA-256(bytes 0–79) checked before a single byte is written hashed while it's written; must match bytes 16–47 A 160-byte header, then the image. Bytes 0 to 79 are signed. A 160-byte header: the magic RORO-OTA, the format, the header size, the image size, the image's SHA-256 and the version (bytes 0 to 79, the signed part), then the signature's length, the signature and reserved bytes. The signature is ECDSA P-256 over the SHA-256 of bytes 0 to 79, checked by the firmware against a public key compiled into it (keys/ota-public.pem, committed), before anything is written. Then the image, hashed while it is written; at the end the hash must equal the one in the header. Make, check and push one: scripts/ota_keygen.sh # once: creates the key pair. The private key goes to ~/.config/roro9stack/ota-key.pem (never committed); the public key to keys/ and the firmware source scripts/make_ota.py firmware.bin v0.12.0 out.ota # wraps and signs an image (the key: $RORO_OTA_KEY or the default path) scripts/ota_verify.py out.ota # checks a file the way a device does, on the PC scripts/ota_push.py out.ota 10.39.39.12 # pushes it to the Update Service, TCP 3232 scripts/flash.sh --ota 10.39.39.12 # builds, signs and pushes in one go ota_push.py prints the device's answer (OK …), or says the device refused the update and hung up, with the reason on the device's screen: the header is checked first, so a refused file stops mid-transfer.

flash.sh --ota builds, signs, pushes rdbg.py put Debug Console, Wi-Fi 2323 sd_put.sh USB serial, card stays in the card, by hand the 1990s way SD card /updates/*.ota Settings → Firmware, or install <path> Update Service 1 header, signature: checked first 2 image → other slot, hashed on the way 3 hash matches: boot it next restart → Probation anything wrong: a Toast, and nothing changes Wi-Fi · TCP 3232 storage task Every path ends at the same Update Service and the same signature check. Push over Wi-Fi to TCP 3232: scripts/flash.sh --ota. The device always listens while Wi-Fi is connected. From the SD card: a .ota in /updates, installed from Settings → Firmware, from the Storage App, or with the install <path> command. Put it there by hand, with scripts/rdbg.py put over Wi-Fi, or with scripts/sd_put.sh over USB. From the project's releases on Gitea, which the device downloads itself over TLS (Settings → Firmware, or update check / update install <tag>): see Flash and update. All three feed the same parser: the header and signature are checked first, the image is written to the other app slot while it is hashed, and the slot becomes the next boot only if the hash matches. Anything wrong ends in a Toast and nothing changes. A downgrade is allowed, and shows "older than the installed version". The device then restarts (waiting up to 60 seconds if you are typing) into Probation.

1 install image → app1 otadata: NEW 2 restart bootloader: NEW → PENDING_VERIFY 3 Probation 30 s up, a frame Wi-Fi within 3 min 4 confirmed → VALID Toast: Updated to… crash or restart before 4 bootloader: PENDING_VERIFY → ABORTED boots app0: "Update to … failed" (second line: bootGuard() in setup() rolls back a second unconfirmed start by itself) app0 keeps the previous firmware: the way back the trap initArduino() marks it VALID before setup(), unless verify- RollbackLater() The life of an update The life of an update: install, restart, Probation, confirmed. A crash or a restart before the last step sends the device back to the previous firmware. A new image is not trusted at first: Install: the image goes to the other slot and the OTA data marks it new. Restart: the bootloader turns new into pending verify and boots it. Probation: the new firmware must boot, draw its UI, start its Services, run 30 seconds without a crash, and reconnect Wi-Fi within 3 minutes if one is configured. Confirmed: it marks itself valid and a Toast says Updated. If it crashes or restarts first, the bootloader marks the image aborted and boots the previous firmware again, which says the update failed. Meanwhile that previous firmware stayed in its slot: it is the way back. Two lines of defence. The bootloader's rollback is the first. The firmware counts its own boots on Probation, very first thing in setup(), and reverts itself on the second unconfirmed start, as a second line. And Arduino-ESP32 normally marks an image valid before setup() runs, which once hid the bootloader's rollback entirely; the firmware overrides verifyRollbackLater() so an image stays pending until Probation confirms it.

A tag v* is built, signed and published by Gitea Actions, with the signing key held as a repository secret as well as on the maintainer's machine (ADR 0008 says what that costs and what limits it). The release step checks the signed file against the public key in the sources it built, so a wrong secret stops the release instead of publishing a file no device accepts. If the private key is ever lost, the next update has to go over USB, carrying a new public key. Someone with USB access can always flash anything: only Wi-Fi and SD card updates are guarded, by design (ADR 0003).

We accept partial Meshtastic compatibility at first: text on channels, Direct Messages, node list, position and relaying. The phone-app (BLE) API and PKI-encrypted Direct Messages are deferred, and we must re-implement protocol details ourselves. Multi-boot with stock Meshtastic via a launcher was rejected: it gives none of our own UX.

NMEA is parsed by our own small, host-tested parser instead of TinyGPSPlus: the GNSS App's Sky view needs the satellite list (GSV) across several constellations, which TinyGPSPlus doesn't track. See docs/milestones/M2.md, Q66.

We write and maintain our own widgets. Switching to LVGL later would mean rewriting every App's view layer.

Someone with physical USB access can still flash anything. Only Wi-Fi and SD card updates are guarded. Losing the private key means the next update has to go over USB, carrying a new public key. P-256 rather than Ed25519, because the firmware's TLS library (mbedTLS) already verifies it, so it costs no extra code. Rollback: the bootloader first, the firmware as a second line. Arduino-ESP32 marks a new image valid before setup() unless the sketch overrides verifyRollbackLater(), which once made every update look good and hid the bootloader's rollback (it had looked like the prebuilt bootloader ignored it). With the override, an image stays pending until Probation confirms it, and the bootloader reverts one that restarts unconfirmed, however early it crashes. The firmware also counts its own boots on Probation, very first thing in setup(), and reverts itself on the second unconfirmed start.

Console, not Serial. All human-readable output goes through console, which writes to the USB port and, in a Debug Build, to a ring buffer the Debug Console drains. Writes never wait for USB: a host that's attached but not reading used to stall the main loop for up to 2 s per line. Commands run on the main loop. The socket lives on the Debug Console's own task, which only queues command lines. The main loop runs them, as it does serial commands, so they touch Apps and Services from the one task allowed to. The token is 128 random bits in ~/.config/roro9stack/debug-token, made by the first build and passed into the container. It's never committed; a Debug Build refuses to compile without one. Like the OTA key, it guards against the network, not against someone holding the device. One client at a time, to keep memory flat (4 KB for the ring since M2, 6 KB of task stack). Binary commands are answered on the console's own task, not queued: get/put (SD card files, run as one Storage Service job each so card access stays on the storage task, with TCP doing the flow control), screenshot (the 32 KB RGB332 frame the UI composes into, read as it stands, so it may tear), coredump get and reset. These keep working when the main loop is stuck. A failed put closes the connection, so the rest of the file is never read as commands.

Rollback returns to the previous firmware, whatever it is. As long as development goes through Debug Builds, the firmware a crash falls back to has the Debug Console, so a bad update never costs remote access. A release build pushed over a Debug Build leaves the Debug Build in the other slot until the next update overwrites it.

Anyone on the same network with the token can read the console, inject keys and reboot the device. The console never prints stored secrets (Wi-Fi and IRC passwords), but the IRC traffic it shows is readable. The TCP stream is plain text: fine on a home network, not across the internet. +debug versions compare equal to their release counterparts, so moving between the two is never refused as a downgrade.

Nothing in the main loop may block for 5 s. Network and card work already run on their own tasks. Safe Mode can't help when Wi-Fi or the Update Service itself is what crashes; that still needs USB. Three crashes within a minute of each restart are needed to reach Safe Mode, so a crash loop costs about half a minute before the device becomes reachable.

With IRC connected over TLS, a Debug Build has 78 KB free and a 59 KB low (it was 31 KB and 12.6 KB), and 46 KB at the lowest under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get). The first build after a fresh checkout, or after changing custom_sdkconfig, takes about 4 minutes instead of 45 s: it downloads ESP-IDF into the PlatformIO volume and compiles it. Later builds reuse it. Everything the firmware depends on was checked in the regenerated sdkconfig: app rollback, core dumps to flash (ELF), the 5 s task watchdog, FreeRTOS run-time stats, the certificate bundle. The project now owns its partition table (default_8MB.csv, identical to the framework's), which the hybrid build requires. Changing it would break updates over the air: the app slots must stay where they are. Generated files (sdkconfig.*, managed_components/, .dummy/) are ignored by git. A TLS server that sends records over 16 KB would still fail, as before; one that needs us to send records over 4 KB would now fail. Neither happens with IRC.

30 uploads of 1.7 MB in a row, each read back and compared by SHA-256, ten of them with the LoRa radio listening on the same bus: no write fault. Before: 3 failures in 10. Every writer gains: Logs, Tracks, Gemini pages, Saved Pages, Captures and Update Files installed from the card all go through this driver, and none of them checked. The copy has to follow the framework. When the platform is updated, compare lib/SD with the new libraries/SD and carry the roro: changes over. If upstream fixes the ready test, drop the copy. Reported as arduino-esp32#12970; issue #39 follows it. One more defect was read in the code and left alone, because nothing here exercises it: the driver tests the card's answer to a data block against 0x0A and 0x0C, values it can't take (accepted is 0x05, CRC error 0x0B, write error 0x0D), so a block rejected for a CRC error is never resent. No such rejection was seen in any failure. If DataToken faults ever show in info, that's the next fix. A fault is now counted and explained instead of silent, so the next cause, if there is one, starts with evidence.

Whoever can run a workflow in this repository can sign firmware every device accepts. That means: anyone who can push to it, the runner's host and whoever administers it, and the Gitea instance with its database, where the secret is stored. Before, it took the development machine. The runner executes jobs on its own host, not in a container, as a user who can use Docker. A workflow is not confined. Pull requests from forks must never run with this secret. Gitea doesn't pass secrets to them; the workflow also only runs on pushes and by hand.

The release step checks the signed file against the public key in the sources it built (scripts/ota_verify.py): a wrong or replaced secret stops the release instead of publishing a file no device takes. ADR 0003's way out stays: a firmware release can carry a new public key. If the secret is ever in doubt, make a new pair, ship it in a release signed with the old key, and replace the secret. A device still only installs what it's told to (until #6), keeps a new image on Probation, and rolls back one that doesn't hold.

If the server moves to another CA, the device can no longer reach it, and the next firmware, carrying that CA's root, has to come from the PC or the SD card. Both still work; they don't use TLS. The roots are public data checked against the published fingerprints (listed in the file), refreshed by hand if Let's Encrypt ever changes them.

The Update File's own signature (ADR 0003) is what decides what gets installed. A hijacked connection could hide a release, or serve an older signed one, but never make the device install firmware that isn't ours. The TLS check matters more for #4, where a token will travel over it.

A TLS connection to this server peaks at about 52 KB of heap, the same whether the certificate is checked or not, so skipping the check would have saved nothing. The cost is the connection itself (record buffers and handshake), not the trust decision.

Off means nothing is there. With the setting off, no socket listens, the console's task doesn't exist and neither does its 4 KB ring: a device that never uses the console pays for it in flash (30 KB more than the release build was) and 88 bytes of static RAM, measured. A missing or invalid stored setting counts as off. The token is the device's. The first time the console is switched on, the device makes one from its hardware random generator: 100 bits, as 20 characters of Crockford's base32 (K7QF-3M2X-9WBD-HT4P-6RNC), shown on the Debug Console page and nowhere else. It can be replaced by one typed by hand, of 16 to 64 characters. It is stored with the other settings and is never printed on a console. The token never crosses the network. The device sends 16 random bytes; the client answers with their HMAC-SHA256 keyed by the token. Someone on the same Wi-Fi who records a login has nothing they can use for the next one. Five wrong answers in a row close the console to everyone for a minute, with a Notification naming the address they came from. A wrong answer still costs a second. DBG in the Status Bar while the console listens, bright while a client is connected. USB serial can set it up: debug on, debug token <value>, debug token new. scripts/flash.sh --debug uses them to give a freshly flashed device the developer's token. Whoever holds the cable can flash anything anyway (ADR 0003); the console itself can only switch itself off. Safe Mode starts the console if it's switched on: the settings are read before Safe Mode is decided.

"Nothing listens" now rests on one stored setting, not on absent code. That setting is typed, validated and host-tested, and its default is off; a bug that flipped it would have to come from code that already runs on the device. Whoever has the token and the network has the device: the console, its keys, the SD card's files, a restart. Not its firmware: an update still has to be signed (ADR 0003). The stream is still plain text. The token is safe from an eavesdropper; what the console prints, and the files it carries, are not. TLS would cost about 52 KB of the 107 KB there is, next to IRC's own connection: not for a console. An old rdbg.py can't talk to a new firmware, and the reverse: the first line of the protocol changed. Accepted, with one user. A device whose settings are damaged has no console in Safe Mode, only the signed update push. Before, a Debug Build always had it. The commands that crash, damage a download or fill a folder on purpose are in every build. They need the cable or the token, like everything else. Releases already publish their ELF, so rdbg.py crash fetches it when it isn't in .pio/elves/: crash reports can be decoded without having built the firmware.

#Decision Q52Two sources: push over Wi-Fi from the PC, and from the SD card. Pulling from Gitea releases is deferred. Q53Signed Update Files (ECDSA P-256 over SHA-256). The private key stays in ~/.config/roro9stack/, and the firmware embeds the public key (ADR 0003). Q54The device always listens for pushes on the LAN while Wi-Fi is Connected. Revised in M2: it was announced over mDNS as roro9stack-<id>.local; mDNS was removed to save RAM (it never crossed the dev box's routed network anyway). Pushes go to the IP shown in Settings → Firmware. Q55New firmware runs on Probation. It's confirmed once booted, UI drawn, Services started, 30 s without a crash, and Wi-Fi connected (if configured). Otherwise Rollback. A Toast reports either outcome. Q56Downgrades are allowed, with "older than the installed version" shown. Q57A valid push installs right away: progress screen, then reboot. The reboot waits for Text Entry to end, 60 s at most.

scripts/ota_keygen.sh creates the key pair once. The public key is committed; the private key never is. scripts/flash.sh --ota builds, signs and pushes to roro9stack-<id>.local. The device shows progress, reboots, and a Toast confirms the new version. An Update File with a bad signature, a truncated or corrupted image, or no signature is refused, and the device keeps running. Settings → About → Update from SD lists the .ota files in /updates and installs one. A firmware that crashes during Probation rolls back to the previous version, and says so after the reboot.

Update File format (host-tested): header (magic, format, version, image size, SHA-256), signature, image. A streaming parser that hashes as it goes and decides accept / refuse / downgrade. The signature verifier sits behind an interface, so tests can inject one. PC side: key generation, make_ota.py (wraps firmware.bin into a signed .ota), and the push client. flash.sh --ota ties them together. Device: the Update Service. A listener on TCP 3232 plus mDNS. Writes the image to the inactive app slot, with the ECDSA check through mbedTLS. A progress screen, and a reboot that waits out Text Entry. Probation and Rollback: the health checks, confirming the image, and detecting a rollback after reboot to report it. Update from SD: the same parser, fed from the Storage Service's task (all card access stays there).

Cold start ($PCAS10,2) to a 3D Fix, by a window: 73 s, 5 satellites used of 8 in view. A restart of the ESP32 alone keeps the receiver's Fix (the Cap stays powered). By a window: 3D Fix from GPS, GLONASS, Galileo and BeiDou, up to 14 of 17 satellites used, HDOP 1.0–1.3. Heap, Debug Build, GNSS on, IRC on TLS (floor 40 KB; v0.2.1 had a 79 KB low): FreeLowest Start of M231 KB12.6 KB Stacks and buffers trimmed by measurement46 KB18 KB mDNS removed54 KB34 KB Framework rebuilt with smaller TLS buffers (ADR 0006)78 KB59 KB Under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get), the low is 46 KB. The cost had come mostly from the OTA and Debug Build work, not GNSS. Stacks were set to measured peak plus about 2 KB (loop 6 KB, update 5, storage 6, irc 6); after a TLS handshake the irc task has 1.7 KB left. IRC can now be stopped by hand (/quit in any state, irc stop), which frees its TLS memory. Goal: the device knows where it is and what time it is without a network: a GNSS Service in the background, a GNSS App with the position and a sky view of the satellites, the clock set from satellites when there's no NTP, and Tracks recorded to the SD card. Hardware: the Cap LoRa-1262 carries an ATGM336H-6N (AT6668), multi-constellation (GPS, BeiDou, Galileo, GLONASS, QZSS), with a ceramic antenna. NMEA over UART, 115200 8N1. Measured (step 1, gnss probe): RX GPIO 15, TX GPIO 13, 115200 8N1, as in Meshtastic's board file; M5Stack's page names GPIO 8 and 9, which are the internal I2C bus the keyboard controller sits on. Output is NMEA 4.10 style: GN RMC, VTG and GGA, one GSA per constellation with the system ID (1 GPS, 2 GLONASS, 3 Galileo, 4 BeiDou, 5 QZSS) in its last field, and a GSV sequence per constellation and signal (GP, GL, GA, …) with the signal ID last. RMC carries a time even without a Fix (status V), so only a Fix makes it trustworthy.

#Decision Q58Settings has a GNSS On/Off switch, On by default. Off puts the receiver in standby. Measured: $PCAS12,<seconds> (CASIC) stops its output within a second, for up to at least 65535 s, and any command wakes it within a second; Off sends PCAS12,65535 (renewed hourly), On sends a hot start, PCAS10,0. Q59The GNSS App has two views, switched with Tab. Position: latitude, longitude, altitude, speed, course, Fix (none / 2D / 3D), satellites used and in view, HDOP, UTC time. Sky: the satellites placed by azimuth and elevation, coloured by constellation, filled when used in the Fix. Q60"Radar" in M2 means the Sky view. A radar of other Nodes by distance and bearing needs the mesh: M4. Q61The Status Bar shows a GNSS mark: absent when off, muted while searching, normal with a 2D Fix, with the satellite count with a 3D Fix. Q62GNSS time sets the clock once there's a Fix, and refreshes it every 10 minutes. Revised in step 3: the clock's trust order from M0 (Mesh < NTP < GNSS) already ranks GNSS above NTP, which is right: GNSS time is at least as accurate. So GNSS also corrects a clock NTP set, not only an unset one. Q63A Track is started and stopped in the GNSS App. It's written as GPX to /gnss/tracks/<YYYYMMDD-HHMMSS>.gpx, a point every 5 s when the position moved more than 5 m. It keeps recording with the App closed, with a Toast on start and stop and a Status Bar mark, and gets its own Storage Clean-up category. Q64Coordinates in decimal degrees plus the Maidenhead locator; a Settings switch for degrees, minutes and seconds. Metric units only. Q65The position never leaves the device in M2. Sharing it over the mesh, and at what precision, is decided in M4. Q66Our own NMEA parser, host-tested: RMC, GGA, GSA and GSV, with each talker ID mapped to its constellation. TinyGPSPlus (named in ADR 0001) doesn't track the satellite list across constellations, which the Sky view needs. Q67The receiver keeps its defaults (all constellations, 1 Hz). No receiver settings. Time to first fix is measured and recorded here. Q68Debug aids: gnss status, and gnss nmea on/off to stream the raw sentences to the console (USB serial and Debug Console). Raw NMEA is never written to the card. Lesson (step 3): the first probe also tried the pins swapped, driving the receiver's output line from the ESP32 for about a second. The receiver then went silent until a full power cycle (an ESP32 restart doesn't cut the Cap's power). Never drive GPIO 15.

The GNSS Service reads NMEA in the background whatever App is on screen, and a 3D Fix appears outdoors. The GNSS App shows the Position and Sky views, both live. The Status Bar shows the GNSS mark per Q61. With no Wi-Fi, the clock is set from GNSS after the first Fix. A Track records while the App is closed, survives the screen turning off, and opens as valid GPX on the PC. Settings → GNSS Off stops it (and the Status Bar mark goes away); On brings it back. Free heap stays above about 40 KB with GNSS, Wi-Fi, IRC on TLS and the UI running.

Hardware check: a gnss probe command reads the candidate UART pins and reports which carries NMEA, at what baud rate, and which talker IDs. Then the standby command (Q58) and a first time to first fix. NMEA parser (host-tested): checksum, RMC, GGA, GSA, GSV across constellations, merged into one GNSS state (Fix, position, time, satellites). GNSS Service: UART on its own task, the parser, gnss status and gnss nmea, Settings On/Off. Clock from GNSS (Q62), and the Status Bar mark (Q61). GNSS App: Position view, Maidenhead and coordinate formats (host-tested), then the Sky view. Tracks: the 5 s / 5 m rule and GPX writing (host-tested), background recording, Clean-up category.

#Decision Q70A milestone of its own, G1, before M3: plan, tests first, measured on the device, tagged v0.5.0. Q71TOFU: the first certificate seen for a host is pinned (SHA-256, in NVS). If it changes, the page isn't shown; a dialog shows both fingerprints and asks whether to trust the new one. Self-signed or expired certificates are fine; only a change counts. Q72Responses: 1x input (11 hidden, for passwords), 2x content, up to 5 redirects (3x), 4x/5x errors with the server's message. 6x (client certificates): "not supported". Q73text/gemini is rendered, other text/* shown as plain text. Anything else can be saved to /gemini/downloads/, not shown. Q74Up to 64 KB on screen, larger pages truncated with a notice. Saving streams to the card, so a larger page is saved whole. Q75Gemtext rendering: text wrapped to the 40-column screen; #/##/### headings in bold and accent; * lists with bullets; > quotes indented and muted; preformatted blocks unwrapped, Left/Right to scroll; => links with their label, numbered. Q76Up/Down scroll; Tab and Shift+Tab move between links; Enter follows; Backspace goes back; g opens the address line. Links to other protocols show their URL and aren't followed. Q77Back history of 20 URLs in RAM, with scroll positions; going back refetches (or reopens a Saved Page). Bookmarks in /gemini/bookmarks.gmi (a gemtext page, shown on the start page); b adds the current page. Without a card, a built-in start page. Q78Start page: bookmarks, then Saved Pages, then defaults: geminiprotocol.net, a search engine (kennedy.gemi.dev), an aggregator (Cosmos; Antenna was down when measured). Q79UTF-8 decoded; characters outside the Latin-1 fonts shown as ?. Q80IRC and Gemini can run together: each fetch opens one connection, reads and closes it. If there isn't memory for a second TLS connection, the fetch fails with a clear message and IRC is untouched. Measured in step 1. Q81Debug aid: gemini get <url> prints the status, MIME type, size, certificate fingerprint and the first lines. URL resolution (RFC 3986), the response header and gemtext parsing are host-tested. Q82s saves the page on screen as a Saved Page: /gemini/saved/<host>/<path>.gmi, the gemtext as received plus a first line with its URL and save date. Saving again replaces it, and says so. Q83S saves the page and the pages it links to, one level deep: gemtext only, same host only, at most 30 pages, in the background with a progress Toast. Q84The start page lists Saved Pages, newest first, grouped by capsule; they open with no network. In a Saved Page, a link to another Saved Page opens the saved copy; other links fetch online if Wi-Fi is up, or say "not saved, offline". A Saved Page shows when it was saved; r refreshes it. Q86Decided after step 1, revised after Q88. Two floors: free heap stays above 40 KB in steady state; a fetch refuses to start below 55 KB free ("not enough memory: stop IRC or retry"). The firmware's own allocations during a fetch (a page in RAM, a window) keep 20 KB free. With IRC connected, the TLS connection itself can briefly take the heap lower, depending on the server's record sizes: measured 24, 19.5, 15.5 and 13 KB. Accepted: about 12 KB for a moment during a fetch with IRC up, rather than refusing most fetches (a 70 KB start floor) or dropping IRC's connection for each page. Q87Decided in step 3. With a card, every page streams to /gemini/cache/page.gmi in 1 KB pieces while its TLS connection is open; once the connection closes and its ~45 KB is back, the page is loaded into RAM as far as the 40 KB floor allows. The whole page stays on the card (Saved Pages copy it). Without a card, the page goes straight to RAM under the same two floors. Pages are held as lines in 4 KB chunks, never one large block (the largest free block with IRC connected is about 31 KB). Q88Added after step 6. A page bigger than memory allows is read from the card as you scroll. Opening it, one pass over its file counts the lines, records where every 64th starts (and whether it's inside a preformatted block), and loads the first window. Scrolling near either end of the window reads the next or previous one in the background, keeping the line on top of the screen where it is; the scrollbar follows the whole page. Display pages alternate between two cache files, so the one on screen is never overwritten by the next fetch; background jobs use a third. Q85Saved Pages are deleted from the App only (d, with confirmation), never by Storage Clean-up's age rules, like Notes.

gemini://geminiprotocol.net/: 20 text/gemini, 1,184 bytes, TLS handshake 0.7–1.1 s, whole fetch 0.7–1.1 s; kennedy.gemi.dev 1.9 s. The fetch task's stack peaks at about 3.6 KB of 6. Heap, Debug Build, IRC connected over TLS: about 68 KB free before a fetch. After the handshake the fetch holds about 32 KB (36–40 KB left); the handshake itself (certificate chain parsed with the 16 KB receive buffer allocated) dips to about 24 KB for a second or two. Nothing leaks: the heap after matches the heap before. Step 3, Cosmos (31.6 KB) with IRC connected: first stopped at 4.6 KB (RAM only, the transfer's 20 KB floor). Streamed to the card: the whole page on the card, 20 KB of it loaded, lowest free heap 19.5 KB during the transfer and 43 KB once loaded. Without IRC: the whole page in RAM. Redirects (Cosmos 31), input (10), not found (51) and a changed certificate (refused, both fingerprints shown) all checked on the device. Steps 4–6 on the device: Project Gemini and its relative links, Back with the scroll restored, a refused YouTube link; b bookmarks, s saves (and says when it replaced an older copy), S saved 6 of 6 pages, the start page lists both; a Saved Page opens from the card with its origin, its saved links open saved copies, r refreshes, d asks first; Kennedy's input prompt sent "cardputer" and got 87 results; emoji drawn as ?. A bug found there: refreshing first loaded the whole Saved Page into RAM just to read its origin, next to the App's copy and a TLS connection: the heap fell to 436 bytes. Now only the first line is read, and every fetch (pages, saves, refreshes) checks the 55 KB start floor. Lowest since boot afterwards: 53.8 KB. Windowed pages (Q88), Cosmos with IRC connected: 226 of 419 lines in memory at first; paging down loaded lines 192–419 in one window, scrolling back up loaded 64 onwards, then 0 onwards. Window budgets count the memory the old window gives back. Heap during a fetch with IRC connected: lowest 13–15.5 KB in later runs (24 and 19.5 KB earlier), the TLS receive buffers varying with the server's records. Accepted (Q86, revised). Antenna (warmedal.se) doesn't answer, from the PC either; the default aggregator becomes Cosmos (gemini://skyjake.fi/~Cosmos/, which redirects to cosmos.skyjake.fi).

gemini get gemini://geminiprotocol.net/ prints the header, size and fingerprint on the console. The Gemini App opens the start page, follows links (relative ones included), goes back, and follows redirects. An input prompt (e.g. a search) takes a query and shows the results. A changed certificate stops the page and asks. s saves a page, S a page and its links; with Wi-Fi off, Saved Pages open and their saved links work. Bookmarks are added with b and listed on the start page. With IRC connected over TLS, a fetch still works, and the free heap stays above 40 KB.

Two TLS connections: measure the heap with IRC connected while a Gemini fetch runs. Parsers (host-tested): URL parsing and relative resolution, the response header, gemtext lines. Fetch on its own task, with TOFU and gemini get. Gemini App: rendering, scrolling, links, history, the address line. Input prompts, redirects, bookmarks, downloads. Saved Pages, then saving with linked pages.

Internal I2C bus (8/9): 0x18 (ES8311 codec), 0x34 (TCA8418 keyboard), 0x43 (PI4IOE5V6408, ID register 0xA2), 0x69 (BMI270 IMU). The SX1262 answers on NSS 5, RST 3, DIO1 4, BUSY 6. Its version string reads SX1261 V2D 2D02, which SX1262 chips report too. The 1.8 V TCXO works on the first try; the radio is ready 38 ms after begin. The expander's P0 connects the antenna; it's required. At power-on P0 is an input (direction 0x00, high-impedance 0xFF), and the receiver reads a flat -111.9 dBm at 869.525 MHz, BW 250 kHz: the chip's own floor, deaf. With P0 driven high, the noise floor is -87 to -94 dBm: the antenna hearing the room. So the Radio Service drives P0 high at boot (Q91). DIO2 doesn't change reception (within ±2 dB over three runs, P0 high). It likely selects TX versus RX in the FM8625H; it stays the RF switch, as in Meshtastic. The noise floor at the desk is high (-87 to -94 dBm, varying run to run), about 25 dB above thermal noise for 250 kHz. Something nearby is loud, possibly the Cardputer itself or the PC; Sweep (step 5) should show where it sits. Step 2: presets, frequencies and the channel hash are checked against Meshtastic's source (MeshRadio.h, RadioInterface.cpp): LongFast and the default key give hash 8, MediumFast 31, as Meshtastic shows. Captures were checked with TShark 4.2.5: every LoRaTap field reads back. Wireshark ignores the spec's quarter-dB packet RSSI below 0 dB SNR, so packet RSSI is plain dBm. Step 3: the DIO1 interrupt works (a 100 ms receive timeout wakes the task after 105 ms). While listening: four 1.7 MB uploads and Gemini pages to the card, no radio or card errors (the card refuses a write about once in five uploads with the radio asleep too; put now catches it, and issue #21 follows the cause). The ring takes 9.8 KB while listening; the radio task's stack peaks at 2.0 KB. No packets yet, and a loud desk. Twenty minutes on LongFast and on LoRaWAN's three uplink frequencies (SF7, SF9, SF12): no packet and no header, valid or not. The noise floor reads -83 to -94 dBm, against -112 dBm with the antenna switched off: 20 to 30 dB lost to something nearby, not the screen and not the GNSS receiver. Preamble detections are false alarms at this noise level (more on an empty frequency, 869.0 MHz, than on LongFast). Step 4: a Capture made on the device reads back in TShark field for field (time, frequency, SF, RSSI, SNR, payload). A Capture keeps the radio listening with the App closed; stopping it puts the radio back to sleep. Step 5: a pass across 863–870 MHz (71 steps, the strongest of three RSSI readings at each, measured at 125 kHz) takes about 607 ms. At the desk the band is flat at -100 to -102 dBm, about 15 dB above the chip's own floor at 125 kHz, with a steady carrier at 863.2 MHz (-89 dBm at its strongest) and fainter lines elsewhere: broadband noise from nearby electronics rather than a transmitter. Sweep's waterfall takes 2.6 KB while shown; 91.9 KB free during a Sweep. The radio task's stack peaks at 1.9 KB. Outside, on battery (step 6). The noise is no lower than at the desk: a Sweep floor of -96 to -99 dBm (median -97) with Wi-Fi on, -99 to -100 with Wi-Fi off, so Wi-Fi accounts for 2 or 3 dB. The same narrow peaks come back on every pass, at 863.2, 863.6, 864.4, 864.8, 865.9, 866.3, 867.8, 869.0 and 869.4 MHz (-88 to -91 dBm), several of them 400 kHz apart; 869.4 MHz is the lower edge of LongFast's channel. A source that follows the device outside and onto its battery is the device: about 15 dB of the floor is the Cardputer's own (issue #20). At SF11 that puts the weakest decodable packet near -114 dBm on LongFast, against about -130 dBm for a quiet receiver. The listening hour (step 6, Q104): 20:33 to 21:34 on 2026-10-05, outside, on battery, LongFast, with a Capture running. 0 packets, 0 headers, 0 radio errors; noise -85 to -87 dBm at 250 kHz throughout; 860 preamble detections, all false alarms. The Capture holds its 24-byte header and nothing else. No restart in 1 h 10 min. Floors (Q86): with the radio listening, Wi-Fi and IRC connected over TLS, 52.6 KB free (lowest 22.7 KB during the TLS handshake, the dip accepted in G1). Without IRC, 93 KB. Receive only: nothing in src or lib calls a transmit function. Cost: RadioLib 7.8.1 and the probe add 23.6 KB of flash and 656 bytes of static RAM to the release firmware (1,679,843 bytes of 3,342,336). The whole milestone: 51.8 KB of flash (1,708,091 bytes), 365 tests (27 new).

#Decision Q89M3 is the radio only: Radio Service, Sniffer, Sweep. Notes and the File Browser (Q30) move out to issue #3 and a Notes issue, as a later side milestone. Q90RadioLib, pinned (ADR 0001). SX1262 on NSS 5, RST 3, DIO1 4, BUSY 6; DIO2 as RF switch; TCXO at 1.8 V tried first, falling back to the crystal (Meshtastic's TCXO_OPTIONAL). Q91Step 1 is lora probe: chip status and version, which oscillator setting worked, and an I2C scan of the internal bus for the PI4IOE5V6408. If present, its P0 is set high at boot (harmless) and DIO2 stays the switch. A wrong switch receives deaf, so compare noise floors. Q92A Radio Service owns the SX1262: driver, bus lock, IRQ task. The LoRa Scanner uses it in M3; the Mesh Service sits on top of it in M4. Q93Every radio transfer takes the shared bus lock (SPI.beginTransaction, as the card does). DIO1's interrupt only wakes the task; no SPI in the ISR. Done when a Gemini page streams to the card while the Sniffer receives, with no lost packets and no card errors (lora status counters). Q94Receive only: the Radio Service has no transmit function in M3. It doesn't exist, rather than being unused. Q95Sniffer defaults: EU868 LongFast, 869.525 MHz, BW 250 kHz, SF 11, CR 4/5, sync word 0x2B, preamble 16 (Q19). The other Meshtastic presets are offered, plus custom settings. Q96The Sniffer lists packets (time, RSSI, SNR, frequency error, length; hex dump on Enter) and decodes the Meshtastic header: the first 16 bytes are never encrypted (destination, sender, packet ID, hop limit and hop start, channel hash, next hop, relay node). Host-tested. Payload decryption is M4. Q97A Sniffer Capture is pcap with LoRaTap headers (link type 270), for Wireshark. Started by hand, Status Bar mark, its own Clean-up category, the 90% rule. Q98Sweep steps across the Region's band (863–870 MHz) in 100 kHz steps by default, reading instant RSSI: bars with peak hold, and a waterfall, Wi-Fi Tools style. Optionally CAD on the preset's frequency to tell LoRa traffic from noise. Q99Sweep takes the radio and pauses the Sniffer, visibly (Q18). From M4 it pauses the Mesh Service the same way. Q100The Sniffer runs while the App is open or a Capture is recording; otherwise the radio sleeps. From M4 the Mesh Service keeps it on. Q101Status Bar: a radio mark while receiving, flashing on each packet; muted during a Sweep. Q102Debug aids: lora status (settings, counters, last RSSI/SNR, noise floor), lora probe, lora rx on/off (packets on the consoles). Raw packets are never written to the card outside a Capture. Q103A ring of the last 32 packets in RAM (about 9 KB at full length); older ones are dropped unless capturing. IRQ task stack trimmed by measurement; RadioLib's flash and RAM measured in step 1 against the floors. Q104Done when (below) includes an hour of listening on LongFast by a window. Real packets heard become M4 test fixtures. If none are heard, M3 still closes, and a reference Meshtastic node (Q21) becomes a requirement for M4.

lora probe reports the SX1262, its oscillator setting and the RF switch arrangement, and the result is written here. The Sniffer receives on LongFast with the App open or a Capture running, and the radio sleeps otherwise. Sweep shows the noise floor across 863–870 MHz, and a known signal (a remote key fob, a 868 MHz sensor, anything) stands out. Half met: the floor and the device's own steady peaks show; no known transmitter was tried. The shared-bus test passes (Q93): a Gemini page to the card while the Sniffer receives, no lost packets, no card errors. A Capture opens in Wireshark with LoRaTap fields. The Status Bar mark follows Q101. One hour of LongFast listening by a window has been run and its result recorded here. Run outside, on battery. Free heap stays above the floors (Q86) with the Sniffer, Wi-Fi, IRC on TLS and the UI running. Nothing in the firmware can transmit.

Hardware check: RadioLib in the build, lora probe (Q91), flash and RAM cost measured. Meshtastic header and LoRaTap (host-tested): header parsing, presets and their radio settings, pcap/LoRaTap writing. Radio Service: receive on its own task behind the bus lock, the packet ring, lora status and lora rx, the shared-bus test. LoRa Scanner App, Sniffer: the packet list, details, preset choice, Captures, Status Bar mark. Sweep: the RSSI sweep, bars and waterfall, pausing the Sniffer. Listening hour and the measurements above, recorded here.

Not every network has a DHCP server: a lab bench, a direct link to a router, a network where addresses are handed out by hand. Until now every Saved Network used DHCP, DNS always came from DHCP, and the NTP server was pool.ntp.org, hard-coded. IPv4 only. IPv6 isn't part of this, now or as a planned follow-up. Decisions (design round 2026-10-05) #Decision Q105The IP setting is per Saved Network: Automatic (DHCP, as before) or Fixed, with its own address, prefix and gateway. New networks start Automatic. Q106The subnet is entered as a prefix length (24), with the mask shown next to it. Q107The gateway is optional: left empty, the device talks to its own subnet only. Q108DNS is global: two servers in Settings, used on every Fixed network. On Automatic networks DHCP's DNS is used, unless "Always use my DNS" is on. Q109DNS defaults: 9.9.9.9 (Quad9), then 1.1.1.1 (Cloudflare). Q110NTP is global: two servers in Settings, names or addresses, defaulting to pool.ntp.org and time.cloudflare.com. NTP servers offered by DHCP are used first. GNSS still outranks NTP for the clock. Q111What's typed is checked, host-tested in lib/wifi: an address is four numbers from 0 to 255; a prefix is 1 to 30; the address isn't the subnet's network or broadcast address; the gateway is inside the subnet and isn't the device's own address. Refusals say why. Q112Addresses are typed in the line editor, limited to digits and dots. Q113Enter on a Saved Network opens its page (IP, Address, Prefix, Gateway, Forget) instead of asking to forget it. Settings > Wi-Fi gains DNS servers, "Always use my DNS" and NTP servers. The Status row opens connection details: address, mask, gateway, DNS and NTP in use, and where each came from. Q114A change applies at once: the network in use reconnects with the new settings. No automatic way back; the keyboard still works if Wi-Fi is cut. Q115Console: wifi status shows address, gateway, DNS, NTP and their sources; wifi ip <ssid> dhcp, wifi ip <ssid> <address>/<prefix> [gateway], wifi dns <a> [b], wifi ntp <a> [b]. Debug Builds: wifi ip … try 60 goes back to the previous setting after 60 s unless confirmed with wifi ip keep. Q116Left out: checking whether the address is already taken, and per-network DNS. The SDK already allows 3 NTP servers and 3 DNS servers and can take NTP servers from DHCP (CONFIG_LWIP_SNTP_MAX_SERVERS=3, CONFIG_LWIP_DHCP_GET_NTP_SRV=y), so the framework isn't rebuilt for this. Done when A Saved Network set to Fixed joins with that address, mask and gateway, and the device reaches the internet (IRC, Gemini, NTP) through the DNS servers from Settings. Set back to Automatic, it gets its address from DHCP again. With "Always use my DNS" on, an Automatic network resolves through the servers from Settings. The NTP servers from Settings set the clock. Wrong entries are refused with a reason, in Settings and on the console. Connection details show what's in use and where it came from. Tested on knbg-guests with 10.39.39.12 (the device's DHCP lease) and 10.39.39.13 (free: the device is alone on that network). Measured (2026-10-05 and 06, on knbg-guests) The network is 10.39.39.0/24, gateway 10.39.39.1; DHCP gives 10.39.39.1 as DNS and offers no NTP server. Fixed 10.39.39.12/24 (the device's own lease) and Fixed 10.39.39.13/24, gateway 10.39.39.1: the device joins with that address, DNS is 9.9.9.9 and 1.1.1.1 from Settings, and a Gemini page loads (name resolution, routing, TLS). On .13, .12 no longer answers. A wrong gateway (10.39.39.254) on a 60 s trial: the device stops answering from another subnet, and comes back by itself with the previous setting. Back to Automatic: 10.39.39.12 by DHCP again, DNS 10.39.39.1 from DHCP. "Always use my DNS" on an Automatic network: DNS becomes 9.9.9.9 and 1.1.1.1; switched off, the device joins again and has DHCP's DNS back. NTP: pool.ntp.org answers; set to time.cloudflare.com alone, that one answers within 25 s. Refusals, on the console and in Settings: the network's own address, a gateway outside the subnet, a prefix of 31 or 99, 10.39.39.300, an unknown network, a DNS name where an address is needed, a host name with an underscore. In Settings: the network's page pre-fills Fixed with the address, prefix and gateway in use; leaving the page applies it; connection details show each value and where it came from. Not tested: NTP servers offered by DHCP (this network offers none), and a Fixed network with no gateway. Work breakdown IPv4 logic (host-tested): parsing and formatting addresses, prefix and mask, the checks of Q111. Storage: the IP setting in each Saved Network; DNS, "Always use my DNS" and NTP in Settings. Wi-Fi Service: apply it when joining; DNS and NTP; wifi status and the console commands. Settings: the network page, the DNS and NTP rows, connection details. Tests on the device, recorded here.

Every milestone so far was driven by measurements, heap floors, stack sizes, TLS dips, that needed a Debug Build and a computer. The System App shows them on the device, in any build. Decisions (design round 2026-10-06) #Decision Q117An App of its own, System, in release builds too. Read-only. Q118Four views, switched with Tab: Overview (CPU per core, memory, network, battery), Tasks, Memory, System. Q119Sampled once a second. A task's share is its run time over the last second; a core's load is 100 % minus its idle task's share. Q120History only while the App is open: two minutes at one sample a second, about 1 KB. The system already keeps what matters afterwards: the lowest free heap since boot and each task's lowest free stack. Q121Bytes are counted per service: IRC, Gemini, the Debug Console and Firmware Updates add what they read and write to a shared counter. The network view shows the connection details, each service's bytes in and out, and the signal strength. Q122Tasks: name, core, share, state and lowest free stack, sorted by share; s cycles the sort (share, stack, name). Under 512 bytes of stack left shows in the warning colour. Q123Memory: free heap, lowest since boot, largest free block, and a two-minute graph of free heap with the floors of Q86 drawn as lines (55, 40 and 20 KB). Q124System: uptime and why it last started, firmware and both app slots, chip temperature and CPU frequency, battery voltage and percentage, SD usage and write faults, the radio's and the GNSS receiver's state. Q125info and tasks are split into a snapshot that the console and the App share; the arithmetic (shares from two samples, sorting, the stack warning) is host-tested. Q126Left out: acting on tasks, an event log, exporting snapshots to the card. Q127The main loop uses about 81 % of a core. The App shows it; fixing it is issue #40, not part of #11. The App has five views, not four: Q121's network view is one of its own (Overview, Tasks, Memory, Network, System). Measured (2026-10-06) Traffic counters are exact. A Gemini fetch of a 164,970-byte page counts 164,986 bytes in (the page and its 16-byte header line) and 42 out (the 40-character URL and CRLF). A 1,797,760-byte upload counts 1,798,123 in for the Debug Console, commands included. The Memory view shows a TLS dip as it happens. Starting IRC and a 165 KB Gemini fetch together: free heap falls from about 100 KB through the three floors to a low of 12.1 KB, then settles near 50 KB. That's the dip accepted in G1 (Q86). A run-time counter only moves when its task is switched out. FreeRTOS adds to a task's run time at the context switch. The main loop takes the samples, and with core 1 to itself it's never switched out: its counter said 2 % while the core's idle task had 0 %. So the task that samples gets what's left of its core. With that: the main loop uses 100 % of core 1 at rest (issue #40 said 81 %, an average since boot). tasks on the console sampled twice inside one command at first, a quarter second apart, and showed the loop at 1 %: it was asleep in the command's own wait. It now samples, lets the loop run for a second, and prints. Low stack, flagged: IDLE0 (232 bytes left), IDLE1 (328 to 352) and spk_task (256 to 264), all the framework's own tasks. Cost: 15.6 KB of flash for the App and the counters (1,742,723 bytes, release). Nothing while it's closed; about 2 KB of history and samples while it's open.

The loop polled the keyboard, ticked the Services, ran the consoles and redrew when needed, then came straight back: 50,000 passes a second, and core 1 100 % busy with the device idle and the screen off. Nothing needs that. The keyboard controller buffers key events; the consoles and the radio have their own tasks or interrupts; no Service asks for a tick more often than every 50 ms. So after each pass the loop now rests: 5 ms with the screen on, 20 ms with it off, and not at all during a serial file transfer (sd put), which reads its bytes from the loop. Safe Mode's loop rests 5 ms too. Debug Builds have loop spin on|off to bring the old behaviour back for comparison. Measured (2026-10-06, Debug Build, Wi-Fi connected, GNSS on, on USB power) SpinningResting Passes a second, screen off50,16050 Core 1 load, screen off100 %1 % Passes a second, screen on (Launcher)1,203167 Core 1 load, screen on62 %10 % Chip temperature at rest, settled38.3 C34.3 C A 1.8 MB upload over the Debug Consoleabout 230 KB/s288 KB/s Still working at this pace: GNSS (a 3D Fix, 22 satellites), a Gemini fetch (52 KB), the upload read back by SHA-256, the Sweep (still 606 to 610 ms a pass), the radio's DIO1 interrupt. Not measured: the current drawn (no meter on the battery line), and how typing feels on the real keyboard: a key now waits up to 5 ms for the loop, 20 ms if it's the one that wakes the screen. The radio's noise floor didn't move (-97 to -99 dBm at 125 kHz either way): the spinning loop wasn't the source (issue #20). Not done: real sleep. The framework is built without power management (CONFIG_PM_ENABLE is off), so an idle core only halts until the next interrupt. Automatic light sleep would need the framework rebuilt with it, Wi-Fi in modem sleep, and the USB serial port's behaviour checked. A next step if battery life calls for it.

M3 found the LoRa radio's noise floor about 15 dB above what the chip hears alone, and that the source travels with the device. Which part? Debug Builds got a self-test, lora noise test: it changes one thing at a time, Sweeps the band eight passes (568 readings), records the median as the floor, and puts the thing back. It runs on the device by itself, because one condition switches Wi-Fi off, and lora noise report prints the result afterwards. Measured (2026-10-06, indoors, on USB power, dBm at 125 kHz) ConditionFloor Antenna switched off (the chip alone)-117 Antenna on, GNSS in standby-106 Antenna on, GNSS running (as shipped)-98 The GNSS receiver, while it runs, raises the floor by 8 dB. Three runs: -98 or -99 with it running, -106 in standby, every time. On LongFast (250 kHz) the Sniffer's own reading goes from about -93.5 to -101.5 dBm. It's the receiver working, not its serial line: with one NMEA sentence a second instead of twenty (PCAS03), the receiver still tracking, the floor stays at -98. Nothing else moves it by more than 1 dB, with GNSS running or in standby: the main loop spinning or resting, the CPU at 240, 160 or 80 MHz, Wi-Fi on or off, the screen on or off, the radio chip's regulator as DC-DC or LDO, its receive gain boosted or not. 11 dB remain between the antenna connected with GNSS quiet (-106) and the chip alone (-117). It comes in through the antenna and none of those switches changes it: the surroundings, or parts of the Cardputer that can't be switched off. Not separated: that needs another place, or the antenna on a cable away from the case. M3's quick check had GNSS at "1 or 2 dB": it read one frequency for a few seconds, in a noisier spot. The median over the band is the better measure. What the firmware does about it Settings > Pause GNSS for LoRa, off by default: while the LoRa radio listens or sweeps, the GNSS receiver waits in standby, and wakes when the radio goes back to sleep (a Fix again after about 7 s here). Never during a Track. The GNSS App says "GNSS is paused" meanwhile. gnss quiet on|off on the console. It's off by default because GNSS on by default was decided in M2 (Q58), and from M4 the radio listens all the time: then "pause while listening" means GNSS mostly off, which is a decision about position, the clock and Tracks, for M4's design round (issue #23).

The console's commands could only be typed on a PC: over USB, or over Wi-Fi with the Debug Console. A device in a bag, or on a network that is down, could not be asked anything. The Shell is an App that runs the same commands on the device's own screen and keyboard. Decisions (design round 2026-10-07) #Decision Q204An App, "Shell", in the Launcher, in every firmware: its commands already work over USB for anyone holding the device. Q205Trusted like USB serial, not like the network: debug on and debug token work from it, as they do in Settings. The token is never shown. Q206Revised the same day, after trying it. It shows the replies to its own commands, and only those. The console knows who each line is printed for (Console::Origin): a command run from the Shell prints as the Shell's, and so does what answers it later from another task, which notes who asked and takes it back when it prints (ls, tasks, du, cp, update check, sd list, screenshot, gemini get). What USB or the Debug Console asked for, and the system's own lines, are not the Shell's. Ctrl+b shows everything instead. The first version kept whatever was printed in the ten seconds after a command, which was a guess, and a noisy one. Q207Nothing while it's closed. Open, a 4 KB ring of the console's and up to 4 KB of lines; both go when the App is left, with the list of commands for Tab. Q208Enter runs the line; Fn with up and down recalls the last 16; Alt with up and down scrolls back. Tab completes the command, every word of it (the first only, at first): lora st gives lora status, gnss track lists start stop, key its eleven names. The words come from the firmware's help text, read as it is written, so a new command completes without a table to keep. (Added the same day) past the command, a path on the SD card: a folder keeps its slash to go on from, a file completed whole gets a space, several candidates are listed. Whatever the case typed, the name's own is taken, since the card doesn't tell them apart. After a file command the first slash is understood (cat no is /no). A name with a space in it isn't completed. Q209Revised the same day. rm is Unix's, with a question. A folder needs -r, here and over the consoles (where rm <folder> used to remove it with what was in it). In the Shell, a file, or a folder with something in it, is asked about unless -f (-rf, -r -f); an empty folder with -r goes without a word; what rm would refuse anyway, it refuses itself. Over the consoles nothing is asked: scripts delete as before. screenshot [seconds] saves the screen as a PNG in /screenshots, now or after a pause, since from the Shell "now" is the Shell. get, put, coredump get and reset answer Debug Console only. (Added the same day) * and ? in a name, for ls, du, rm, cp and mv, here and over the consoles: rm /notes/*.txt, cp /gnss/2026-10-0?.gpx /backup. In the last part of the path only, any case, as the card has it. It is the same command once for each name matched, in the name's order; cp and mv then need a folder that exists to put them in. Over 64 matches is refused whole, as is none. In the Shell rm with a pattern asks once, with the count. Q210Commands are echoed as > command into the console, so a session reads the same from afar. A token being set is not echoed. Q211Not in Safe Mode, which starts no Apps: issue #77. Q212Its keys are a table in app_keys.h, so the help panel and the website have them; a page in the user guide. Q213Added the same day. An App's name with a capital opens it: Irc, Wifi, Gnss, Gemini, Lora, Storage, Notes, Shell, System, Settings (the App's id, up to its first dash). From the Shell, without going back to the Launcher, and from the consoles too. The capital says "an App": every command of the firmware is in small letters. Tab completes them. As built ShellApp (src/apps/shell_app.cpp), with its model host-tested in lib/apps_model/src/shell_log.h: lines arriving in pieces, the 4 KB limit, the words of every command out of the help text (Apps' names included), and Tab. Who a line is for: Console::As marks the calling task as printing for the Shell while it lives, and Console::origin() lets a command that answers later carry that to wherever it prints. The console has a second ring for the Shell, which gets the lines marked so, or everything. The Shell hands its lines to the main loop, which runs them like the consoles' commands. See below for why. info says which App is in front (app: Shell): so that a hand driving the device from afar can look before it types. screenshot writes the PNG a row at a time with no buffer: 8-bit indexed colour, the 256 colours of RGB332 as the palette, the pixels in one stored deflate block (lib/files/src/png_rgb332.h, 4 tests). 33,383 bytes for the 240 x 135 screen. A Toast says so once it is on the card, so the Toast is never in the picture. The help text lost its shorthand (update check | list | status is written out), since Tab reads its words from there: | between two commands, on|off between two words, three spaces before the description. The Shell's own words (clear, quit, key's names) are added in the same notation. Tab on a path reads the folder on the storage task while the main loop waits, so it is bounded: 400 entries looked at, 24 candidates given back, and ... after the list when there were more. A pattern is matched in lib/files/src/file_names.h (globMatch, host-tested), and the names it matches are lined up as so many commands, which the main loop runs one after the other as each finishes. cancel empties the line-up. 2000 entries looked at, 64 matches at most. Cost: 21 KB of flash, 96 bytes of static RAM. Open: 7 KB of heap (107.6 KB free before, 100.7 with it open, 106.1 after leaving). What went wrong while building it The device crashed, and the test sent a message to an IRC channel. The first version ran a command from inside the key handler. Driven from the Debug Console, that is: the main loop, a remote command, key select, the App manager, the Shell, runCommand a second time, the file command, and printf under all of it. The main loop has under 2 KB of stack to spare; rm on a folder went past it. The crash report decoded to exactly that chain. The device restarted into the Launcher, and the test script, which did not look, went on typing. Its next Enter opened IRC, which connected, and a few lines later it typed "No" into a channel and pressed Enter. One word, sent to real people, that can't be taken back. Two changes came of it. The Shell now queues its line and the main loop runs it, at the same stack depth as a console's command. And info reports the App in front, which the test script now checks before every line it types. Checks on the device (2026-10-07, driven over the Debug Console with key) CheckResult Open it from the Launcher, type ls /, EnterThe folders are listed Tab on ininfo install is shown and the line stays; on u it becomes update ; on l, log ls lora loop UpThe line before comes back screenshot/screenshots/20261007-104357.png, 33,383 bytes. Fetched and decoded on the PC: 240 x 135, indexed, every chunk's CRC right, the pixels the Shell's screen OutputWith a Debug Console client connecting and disconnecting for every key, the Shell shows the commands and their replies and nothing else: info, ls / (answered by the storage task), tasks (answered a second later) rm on a folder, without -rRefused, the folder stays rm -r on an empty folderRemoved, no question rm -r on a folder with filesAsks; Cancel leaves it. rm -rf removes it without asking rm on a fileAsks; Delete removes it Tab on a pathls /no becomes ls /notes/, and again, with one note in it, the note's whole name and a space. ls /g lists gemini/ gnss/. cat no becomes cat /notes/. rm -r /CAP becomes rm -r /captures/. ls /zz stays as it is Tab past the first wordlora st becomes lora status ; gnss tr becomes gnss track and Tab again lists start stop; key lists its eleven names; upd becomes update and lists check list status install ls with a patternls /gt/*.txt the five files, ls /gt/*2* the one, ls /gt3/*6?.txt ten of seventy. ls /g*/x: refused, a pattern goes in the last part cp /gt/file-000?.txt /gt2, du /gt2/*1*Five copies; one size rm /gt2/* in the Shell"The 5 that match /gt2/*": Cancel leaves the five. rm /gt3/*6?.txt, Delete: ten gone, sixty left. rm -f /gt2/*: gone without a question rm /gt/* where one match is a folderThe files go, the folder stays (no -r) No match, and seventyrm: error nothing matches; rm: error more than 64 match: a narrower pattern, please, and all seventy still there No, Tab, EnterCompletes to Notes and opens Notes. Shell from the Debug Console opens the Shell screenshot 4, then HomeThe picture, taken four seconds later, is of the Launcher: the pause works, and the Toast isn't in it quitBack to the Launcher, and the memory comes back The help panel in the ShellIts keys, then the ones that work everywhere Not checked: Ctrl+b and the Alt scroll, which key can't press (no modifiers): the filter itself is host-tested, the key that flips it is not; the real keyboard altogether; the Toast after a screenshot, which was published but not looked at; and mv with a pattern and cancel in the middle of a line-up, which share their code with cp and rm but were not run. The main loop's lowest free stack after all of it: 1.8 KB, where it was.

Until now the card could be looked at only through the Debug Console (ls, get, put), and Settings > Storage could only delete whole categories by age. On the card today: six top-level folders, irc, wifi, updates, gnss, gemini and captures. No notes yet; settings are in flash, not on the card. Decisions (design round 2026-10-06) #Decision Q128An App of its own, Storage, in the Launcher. Settings > Storage goes away: its usage figures, Storage Clean-up and "Erase SD card" move into the App, under Maintenance, behind a warning that these delete things for good. Q129A row shows the name, then the size or "folder", then the date modified. Folders first, then by name; s cycles the sort (name, date, size). The top line shows the path and the card's free space. Q130Nothing is hidden. Read-only: /gemini/cache; any file the firmware has open right now (today's IRC log, a Track or Capture being recorded, a file being received); and the top-level folders themselves, which can't be renamed or deleted though their contents can. Everything else, the user's own data included, can be renamed, moved or deleted, always after a confirmation. Q131One item at a time, with a clipboard: Enter opens; Back goes up, and leaves the App at the top; c copy, x cut, v paste into the current folder; r rename; d delete; n new folder; i details. Q132Copy, move and delete work on folders too, recursively. The confirmation says what's inside: "Delete saved and its 42 files?". Q133A copy is a job on the storage task in 4 KB pieces, with a progress Toast; Back cancels it. It checks free space first and asks before replacing anything. Afterwards the sizes are compared, not the contents: the driver is trusted since v0.6.1 (ADR 0007). A move within the card is a rename. Q134Viewers by type. Text (.txt, .log, .gmi, .csv, .gpx, and anything that looks like text): read from the card as you scroll, so size doesn't matter; logs open at the end. .pcap: the LoRa Scanner's packet list. .gpx: a summary (start, duration, points, distance), Tab for the text. .ota: version, size, whether the signature is valid; Enter installs through Update from SD. Anything else: a hex dump. Q135No editing: that comes with Notes (#19). Q136A listing holds up to 256 entries, packed, about 10 KB; a bigger folder shows the first 256 by name and says how many more there are. The App refuses to open below the memory floors (Q86). Q137The Clock also sets the system time, so files are dated correctly with GNSS alone and not only after NTP. A file dated before 2020 shows "-". Q138Console: cp, mv and mkdir, next to ls and rm. Q139Left out, each with its issue: selecting several items (#41), finding files by name (#42), opening a .gmi in the Gemini App (#43), a table view for .csv (#44), images (#45). Q140Ships as v0.9.0 when done and checked. Done when The Storage App lists any folder of the card with sizes and dates, sorted three ways, and says so when a folder has more than 256 entries. A file can be copied, moved, renamed and deleted, and a folder too; a new folder can be made. Each destructive action asks first; a copy shows progress and can be cancelled. The read-only rules of Q130 hold, with a reason given when something is refused. Each viewer of Q134 opens its type, and a 1 MB text file scrolls without loading whole. Maintenance shows the card's usage and does what Settings > Storage did, behind its warning; Settings no longer has a Storage row; the Storage Warning points at the Storage App. A file written with only a GNSS Fix (no Wi-Fi) is dated correctly. Free heap stays above the floors with the App open, Wi-Fi and IRC on TLS. Work breakdown Model (host-tested): paths and names, the read-only rules, the packed listing and its sorts, file types, sizes and dates for display, the GPX summary. Card operations: listing a folder, copy, move, delete (recursive, counted), new folder, as storage jobs with progress and cancel; cp, mv, mkdir; the Clock sets the system time. The App: browsing, the clipboard, dialogs, details. Maintenance: usage, Clean-up and Erase moved in from Settings, with the warning. Viewers: text, hex, .pcap, .gpx, .ota. Checks on the device, recorded here. As built FileOps (src/services/file_ops) does the card's work for the App and for the console alike: list, count, copy, move, delete, new folder. One operation at a time on the storage task, in turns of about 150 ms that queue themselves again, so Log lines and a Capture are written in between. The rules of Q130 are checked there, whoever asks. A listing reads the folder straight from FatFs. Through the Arduino File, every entry was looked up by name again for its size and again for its date: 329 entries took over two seconds. One pass now, and it's there before the screen has redrawn. Counting, copying and deleting still walk with File; they show progress and can be stopped. A copy shows its progress in a box in the App, not a Toast (Q133): it has a bar and says Back cancels. A cancelled or failed copy deletes what it had written. The copy gets today's date, like cp. The viewers (src/apps/file_viewer, models in lib/files): text through TextPager, which reads about a kilobyte around the screen and wraps at spaces, 38 columns; going back a line wraps the paragraph before again, so a file reads the same in both directions. A .pcap, a .gpx and an .ota are read through once by a storage job, in the same 150 ms turns. An Update File is fed to the installer's own parser with a sink that writes nothing, so "would it install" is the same answer an install gives. Tab in a viewer shows the same file as hex, or as text (not in Q134). Maintenance is the last row at the top of the card, and m anywhere in the App. It's the old Settings > Storage page behind a dialog. The Storage Warning was only ever a Toast; "selecting it opens Storage Clean-up" (CONTEXT.md) was never built. It now reads "SD card over 80% full: see Storage". Console: cp, mv, mkdir (Q138), and rm and du through the same code, so rm now takes folders and follows the rules; ls shows dates. Debug Builds: sd fill <folder> <count> makes test files. Checks on the device (2026-10-06, v0.8.1-2 Debug Build) All in a scratch folder, /f1test, removed afterwards. CheckResult Host tests424 pass (411 before the viewers' models) BrowsingFolders first, sizes and dates, the three sorts; a 300-file and a 329-file folder show "first 256 of 300" and "of 329" New folder, rename, copy, cut and paste, deleteEach works on a file and on a folder; a copy next to its original is named (2); a name in the way asks "Replace it?" A folder of 11 files, 8.4 MB, copied19.4 s, 435 KB/s, the bar moving; two Log lines queued meanwhile were written The same copy cancelled at 1.8 MB"Cancelled: nothing was copied", and nothing was left behind Delete341 files in 9.7 s; the dialog had counted them first Read-only rules/irc, /gnss (top-level folders), /, /gemini/cache and a folder made inside it, a folder into itself, a name with :; a Capture being recorded and the folder holding it; a folder under /irc while IRC runs. Each refused with its reason; the Capture could still be copied TextA 1 MB log opens at its last line at once; top, pages, lines; a file without an extension that looks like text opens as text HexA 5 KB binary file; Tab from any other viewer .pcapA LoRa Capture: 3 packets as the Scanner lists them, Enter shows the Meshtastic header and bytes .gpx400 points: start, 33 min 15 s, 4.68 km; Tab shows the text .otaA signed file: version, "intact", "older than what's running", Enter asks to install (not confirmed). A tampered one: "image corrupted (hash mismatch)" MaintenanceThe warning, then usage, Clean-up's categories and Erase (not run) Date with GNSS onlyNTP pointed at an address that doesn't answer, restart: the Clock came from the Fix, and a folder made then is dated 2026-10-06 08:39. A Track from the day before, written the same way by v0.8.1, shows "-" MemoryIRC connected, the App open on 256 entries: 61 KB free (70 KB before opening). Lowest since boot 29.7 KB, during IRC's TLS handshake Stacksstorage 3.1 KB free of 6 KB at worst, loopTask 1.5 KB Not checked by hand: how the keys feel on the device itself; everything above was driven through the Debug Console's key command and screenshots. One slip during the checks: a scripted key sequence ran in the wrong folder and renamed /gemini/saved to saved2, then copied it to the top of the card. Both were put right at once (renamed back, the copy deleted; 7 files, 53,798 bytes, as before). Found on the way: a panic at Wi-Fi join, there since v0.7.0 (SNTP started twice, issue #46). Fixed in v0.9.0.

Plain text notes on the SD card, written on the device. Q30 settled the base: .txt files in /notes, created, edited and deleted from the device, never offered by Storage Clean-up. Decisions (design round 2026-10-06) #Decision Q141A Notes App in the Launcher. One row per note: its first line as the title, then the date. Newest first; s switches to by name. n new, Enter opens, d deletes after a confirmation, r renames the file. Q142A new note's file name is never typed: it comes from the first line when the note is first saved (shopping-list.txt), or note-20261006-0919.txt if that line is empty. It doesn't change afterwards unless the note is renamed. Q143Autosave, no "discard changes?" prompt: five seconds after the last key, on leaving the note or the App, and when the screen turns off. A save writes a temporary file and renames it over the note, so a power cut loses the last few seconds at most. A temporary file left behind is offered back at the next open. Q144The whole note is in memory while it's edited, up to 16 KB. A bigger text file opens read-only in the Storage App's viewer. The App refuses to open below the memory floors (Q86). (Lifted by issue #47: see "Notes of any size" below.) Editing files of any size must come in a later release: issue #47. Q145The editor wraps at spaces, 38 columns by 8 rows, with a line for the name and the state. Enter is a new line, Del deletes backwards, Fn+arrows move (the Text Entry rule), Ctrl+A and Ctrl+E go to the start and the end of the line, Tab types two spaces, Back saves and returns. The Compose Key works as elsewhere. Q146The Storage App's text viewer gets e: edit this file with the same editor, for a text file up to 16 KB that isn't read-only. That lifts Q135 without Apps opening each other (#43 stays). Q147The list is flat: the files directly in /notes. Sub-folders are reached through the Storage App. Q148UTF-8, LF line ends; a file with CRLF is saved back with LF. Characters the font lacks are kept on save. Q149Left out, each with its issue: editing files of any size (#47), searching inside notes (#48), undo (#49), selecting and copying text (#50). Q150Ships as v0.10.0 when built and checked on the device. Done when A note can be started, typed with accents, left and found again in the list under its first line; renamed; deleted after a confirmation. What's typed is on the card five seconds after the last key, and after Back, Home, or the screen turning off, without a prompt. Pulling the power while typing loses a few seconds at most, and the note is never left empty or half-written. The cursor moves by character and by line through wrapped text, and the screen follows it; a 16 KB note edits without lag. A note at 16 KB refuses more text and says so; a bigger file opens read-only. e in the Storage App's text viewer edits a file; a read-only one is refused with its reason. Free heap stays above the floors with a 16 KB note open and IRC connected. Work breakdown Model (host-tested): the text buffer with its cursor, wrapping and scrolling; file names from first lines. The editor on the device: loading, drawing, keys, autosave through a temporary file, recovery. The Notes App: the list with titles, new, rename, delete. e in the Storage App. Checks on the device, recorded here. As built NoteText (lib/notes, host-tested) is the text, its cursor and the screen around it. A line owns the space or the newline it ends with, so every byte is on exactly one line and the cursor has one place for each. No index of lines is kept: a note of newlines alone would need twice its own size for one. Where a line starts is worked out from the start of its paragraph. One buffer, 16 KB, for as long as the editor is open. It's reserved when the note is opened, the file is read straight into it, and typing never makes it grow. On this device a failed allocation is an abort, and with IRC connected the largest free block is about 31 KB whatever the total says: the first version read the file into one string and copied it into another, and opening a full note with IRC connected restarted the device. The editor now also refuses to open without a free block of 24 KB. NoteEditor (src/apps/note_editor) is shared by the Notes App and the Storage App's e. A save runs on the storage task while the main loop waits for it: no second copy of the note, and at 16 KB the wait is a fraction of a second at a moment when nobody has typed for five. A save writes <note>.tmp, checks its size, deletes the note and renames the temporary file (FAT can't rename onto a file). A cut between the last two steps leaves only the .tmp: the Notes list puts such a file back under its name. A .tmp next to its note is an unfinished save: opening the note offers it. Titles in the list are read from the card for the eight rows on screen, when the list moves. Before powering off, the firmware now leaves the foreground App (PowerService::beforePowerOff), which makes the editor save. Shift or Alt with Fn+Up and Fn+Down moves a page (not in Q145). Found on the way The screen could go "off" for one tick after a key sent through the Debug Console, and the next key was then swallowed as a wake-up: the key command stamps the power timer from millis(), the power tick compares with its pass's older time, and the unsigned difference read as 49 days idle. The same shape as #46. Fixed in PowerPolicy::update with a test. Keys from the keyboard were never affected. It explains remote keys "lost" in earlier sessions. scripts/rdbg.py held back piped lines written while it was still connecting, until the next line came (a buffered readline() behind select()). Fixed. Checks on the device (2026-10-06, Debug Build of branch notes) Test notes were made in /notes and removed afterwards; the folder is left, empty. CheckResult Host tests439 pass A first note"No notes yet", n, typed three lines: the top line says "typing", then "saved" five seconds after the last key, under shopping-list.txt. 63 keys in a row all arrived LeavingBack saves and returns to the list, which shows the note under its first line. Home in the middle of a new note saved it as ideas.txt The cursorDown, Right, an insertion in the middle of a line; the screen scrolls through a note of about 230 lines A power cutTyped, waited seven seconds, typed more and restarted the device at once (reset): the note has what was saved, whole, and not the last keys An unfinished saveA .tmp next to its note: "Unsaved copy... Keep the note / Use the copy"; using it brings its text back and saves it. A .tmp alone was put back under its name when the list opened 16 KBA note of exactly 16,384 bytes opens and scrolls; one more character: "This note is full: 16 KB". A file of 16,398 bytes: "Too big to edit: 16 KB at most" Rename, delete, sortr renamed orphan.txt to orphan2.txt; d asked, then deleted; s switched between newest first and by file name e in the Storage AppA note opened from the text viewer, edited, saved on Back; the listing shows its new size MemoryIRC connected, the full 16 KB note open: 55 KB free, largest block 31.7 KB (72 KB free before opening) Not checked: accents through the Compose Key and Ctrl+A / Ctrl+E (the remote key command can't send them; the model's tests cover both), the power button's save (it needs a hand on the device), a missing card, and how typing feels on the keyboard itself. One slip during the checks: a key sequence sent right after a restart opened IRC instead of Notes, and the test letters went into IRC's input line. Nothing was sent: the line was cleared and the App left. IRC connected to Libera as it does when opened.

Q144 held the whole note in memory and stopped at 16 KB, for the first version only. This lifts it: the editor opens a text file whatever its size. Decisions (design round 2026-10-07) #Decision Q223The note is the file on the card plus one window in memory. The window is the NoteText of before, up to 16 KB around the cursor; the rest is a list of pieces: runs of the file, and runs of a side file. The cursor leaving the window writes it to the side file if it was changed, and loads the next. Typing never fills a note: a full window is written away and loaded smaller. Q224The five-second save: up to 64 KB it rewrites the file, as before (about 150 ms). Above, it appends the window and the list of pieces to <note>.edit: 8 KB or so, whatever the note's size. "saved" means "on the card" either way. Q225The file itself is rewritten on leaving the note (Back, Home, another App), with a progress bar. The screen turning off and the device powering off write the side file only: powering off never waits. Q226After a power cut, opening the note picks the edit up where it was last saved, without a question, and says so. Until then the file has the old text for anything else that reads it. Q227If the file was changed elsewhere meanwhile, the side file no longer fits it: it is kept as <note>.edit.lost and the editor says so. Typed text is never deleted without a word. Q228No limit but the card: a note over 16 KB needs room for a second copy to be opened for editing. No warning for a big file; the progress bar on leaving tells the cost. Q229A side file over 1 MB, or a list of over 256 pieces, makes the next save a rewrite. Q230CRLF becomes LF (Q148) for a long file too: in the window as it is read, and in the rest of the file as the rewrite streams it, so a saved file is never of both kinds. Q231One path. A 16 KB note is the case with no pieces: there is no second editor for small notes. Q232Notes, and e in the Storage App's viewer, which no longer says "Too big to edit". As built NoteDocument (lib/notes/src/note_document.h, host-tested against a card in memory) is the list of pieces, the window's moves, the side file and the recovery. NoteText is unchanged but for being refilled. The window moves when the cursor comes within 2 KB of an end of it that isn't an end of the note: it is then 4 KB on each side of the cursor. It starts where a line starts on screen whenever that can be known (after a newline, or where the window before had a line start), so the same text wraps the same from one window to the next, and never in the middle of a character. The cursor keeps its row on screen. Looking writes nothing: a window that wasn't changed goes back as the pieces it was read from. The side file starts with a line of text, the note's size and checksums of its first and last kilobyte, which is how a file changed elsewhere is told. After that, text that left a window, and snapshots of the list of pieces, each with its checksum. The newest snapshot that checks out is the note as last saved; anything after it is ignored. The rewrite streams the pieces and the window into <note>.tmp, checks its size, then writes a mark at the end of the side file: from that mark on, the rewrite counts as done, and opening the note finishes it whatever was cut (remove the old file, rename, remove the side file). Before the mark, the note and its side file are still the truth and the temporary file is dropped. On the device the card is reached through an adapter that keeps the file being read and the file being appended to open between calls; every call runs on the storage task while the main loop waits. The rewrite runs in steps of 64 KB with the progress drawn between them. The Notes list doesn't show .edit and .edit.lost files, and a note's side file is deleted and renamed with it. Ctrl with Fn+Up and Fn+Down go to the start and the end of the note. key ctrl-down: the consoles' key command takes ctrl-, alt- and shift-, which these checks needed. It also lets the checks S1 couldn't make (Ctrl+b, the Alt scroll) be made. Cost: 15 KB of flash. Memory with a note open is what it was: 17.5 KB, for 62 bytes or for 1.2 MB. Host tests (15, test/test_note_document) A walk down 3,000 lines and back up through the windows; start and end; an edit in the middle rewritten into the file; 48 KB typed into a new note; a journal picked up after a cut; a cut at every 997th byte of a sequence of two saves and a rewrite, after which the note is always one of the three texts it should be, what was reported saved is there, and no stray file is left; a file changed elsewhere; CRLF; windows on text with no space and no newline, made of 2, 3 and 4-byte characters; a full card; and 36,000 random keys (typing, deleting, moving, jumping, saving, power cuts) on six notes of 30 to 130 KB, compared with a plain string after every key. Checks on the device (2026-10-07, driven over the Debug Console) Test notes were copied to /notes and removed afterwards; the note that was already there was not touched. CheckResult A 36 KB noteOpens (it was refused before). Two letters at the top, 400 lines down across the windows, four more: the file fetched back is exactly that, and no other file is left A 1.2 MB noteOpens at once. Free memory 104.2 KB before, 86.7 KB with it open Its five-second savezz-big.txt.edit, 4 KB; the note's file untouched Ctrl with Down, Ctrl with UpThe end and the start, as fast as any key A restart with unsaved keys"Your unsaved changes are back", the cursor where it was, the unsaved keys gone and nothing else Leaving itThe progress bar, then one file: 1.2 MB rewritten in 2.6 s. Fetched back: the original with what was typed at both ends, byte for byte A restart in the middle of that rewriteThe note, its side file and an empty .tmp remain; opening picks the edit up, leaving rewrites it, the result is right A new noteNo file until typed in, then zz-test-note.txt from its first line e in the Storage App on the 1.2 MB fileThe same editor; edited and rewritten The Notes listSide files are not listed as notes Not checked: the power button's path (side file only), the screen turning off, a card pulled while editing, and memory with IRC connected, which wasn't connected for these checks: the editor's own use hasn't changed, and it still refuses to open without a free block of 24 KB. The real keyboard's Ctrl with Fn and the arrows. A file of tens of megabytes. Renaming or deleting a note from the Storage App leaves its side file behind. Measured against what was said: the first build rewrote 1.2 MB in 3.5 to 4.5 s, with 2 KB blocks. With 4 KB blocks it is 2.6 s, about 450 KB a second, which is what the card gives a plain copy.

Until now the tests, the builds, the signing and the flashing all happened on one machine, through scripts/ci.sh and scripts/flash.sh. Nothing was published. Decisions (design round 2026-10-06) #Decision Q151A push to main: the host tests (with their coverage). A push to another branch: nothing, its pull request is what runs (a branch with an open pull request ran twice, once for each). A pull request: the same and both builds; changes reach main through pull requests. A tag v*: all of it, then a release. (First: everything on every push, which rebuilt the firmware far more often than anyone looked at it.) Q152CI signs. The signing key is the repository secret OTA_SIGNING_KEY; a tag push makes a complete, signed release with no manual step (ADR 0008). Q153Revised by Q188: there is one firmware. The Debug Build is built in CI with a token of the runner's own, to prove it compiles, and isn't published: it would hand everyone its Debug Console token. Q154Pull requests from forks don't start a run. Q155A release carries roro9stack-<version>.ota (signed), -factory.bin for USB, .elf.gz to decode crashes, and SHA256SUMS. Q156Its text is the tag's message, what the files are, and the commits since the tag before. Q157No cache service to begin with: measure first. Q158Reproducible builds aren't needed for signing any more (Q152); not pursued here. Q159The tags from before CI get their releases too, v0.1.0 to v0.10.0, built from each tag's own sources by running the workflow by hand. Q160Actions is switched on for the repository. Q161Changes reach main through pull requests, merged as "rebase, then a merge commit", the only style the repository allows: the branch's commits keep their messages, the merge commit marks the pull request, and what CI tested is what lands. No squash, no fast-forward. As built One workflow, .gitea/workflows/ci.yml, one job, on the runner runner0 (label ubuntu). The job asks for a python:3.12-slim container, installs git, a compiler, openssl and PlatformIO, and runs the same scripts as a developer's machine. No Docker inside the job. The cache is a Docker volume, roro9stack-pio, mounted at /pio; the runner's config.yaml allows it under container.valid_volumes. A first run downloads about 1 GB and rebuilds the framework. Measured from the jobs' own start and end times: the first full run on an empty cache took 11.4 minutes (tests and both builds); the first run in a container, 8.1; a pull request now takes about 8.7 (tests, coverage and both builds), a release build alone 5.5, and a push to main (tests and coverage) 1.1. (An earlier version of this note said 17 minutes: that was the waiting time, not the job's.) No JavaScript actions, so the image needs no Node and nothing is fetched from GitHub: the checkout is four git commands. scripts/_docker.sh runs the command in place when RORO_NO_DOCKER is set (a CI job is already in a build container), and in the project's image otherwise. The Debug Build's token is made on the spot in CI and goes with the container. scripts/release_build.sh <checkout> <out> builds a tag's own sources with today's tools, signs, verifies against the public key in those sources, and writes the files and the release's text. scripts/release_publish.py creates the Gitea release or completes it; run twice, it replaces what's there. Both run the same on a developer's machine. scripts/ota_verify.py checks an Update File as a device does, on a PC. The job's own token (secrets.GITEA_TOKEN) is enough to create a release and upload its files. Old tags. v0.1.0 to v0.3.0 are from before the framework was rebuilt with our settings (ADR 0006) and can't link against a rebuilt one left in the cache: the release build puts the stock framework libraries back for them. v0.1.0 to v0.2.1 have no public key in their sources (Firmware Updates came with v0.3.0); their files are checked against today's. How it went The runner's label took three tries. Registered as ubuntu://docker:ubuntu:resolute and then as ubuntu::docker://..., Gitea took the whole string for the label's name; with the first, jobs ran on the runner's host itself. The first version of the workflow was written for that (plain shell, docker run for the build) and published v0.10.0 that way. ubuntu:docker://docker.gitea.com/runner-images:ubuntu-latest is the form that works. Gitea 1.27's API can't cancel a run that isn't finished, only delete a finished one; switching Actions off and on for the repository doesn't either. Runs queued for a label that no longer exists stay queued until cancelled in the web UI. CI's image isn't byte-identical to a local build of the same tag (same size, different bytes). Not pursued (Q158).

The device looks at the project's Gitea for a newer release, says so, and installs it on request, with the same signed Update Files, Probation and rollback as a push from the PC or an install from the card. What the server gives (checked 2026-10-06) Its certificate is Let's Encrypt, all ECDSA: leaf git.twis.la (renewed every few months, next expiry 2026-12-14) under the intermediate YE2, Root YE and ISRG Root X2, which X1 cross-signs. Pinning the leaf would ask a question at every renewal. The API answers over HTTP/1.1, chunked: releases/latest is 3.2 KB (about 350 bytes of it matter), a list of ten releases is 33 KB. A download is a direct 200 with Content-Length and no redirect; ranges work. Decisions (design round 2026-10-06) #Decision Q162Trust: the firmware carries ISRG Root X1 and X2 and checks the server's chain and name against them, not the framework's bundle of about 130 CAs (ADR 0009). Shared with #4. If the server moves to another CA, the next firmware comes from the PC. Q163The Update File's own signature stays the real guard. A hijacked connection could hide a release or offer an older signed one, never install firmware that isn't ours. Q164The source, git.twis.la and twisla/roro9stack, is a constant in the firmware. A fork changes it, and has its own key. Q165When: on request in Settings > Firmware, and once a day in the background while Wi-Fi is up and the Clock is set (certificate dates need it). A setting, Check for updates, on by default. It installs nothing by itself; it skips quietly below the memory floor and never runs during an install. Q166A Toast, "Update v0.11.0 available: see Settings > Firmware", once per version per boot. Q167The download goes straight into the inactive slot, no card needed. A truncated or tampered file is refused after 160 bytes or at its end, and the running firmware is untouched. A failed download starts over. Q168A version that failed (rolled back) isn't announced again by the background check until a newer one exists; it can still be installed by hand. Q169Older releases: a list of the last ten, newest first, the running one marked. Installing an older one asks with a stronger warning. Q170Enter on a release shows its version, date, size and the tag message, with Install. Q171Revised by Q188: there is no Debug Build, every firmware installs releases. Debug Builds check and show the latest release, but don't install it: it would replace the Debug Build and its console (Q153: Debug Builds aren't published). Their updates come from the PC. Q172Memory, as measured: a TLS connection peaks at about 52 KB of heap, with or without checking the certificate, so it starts with 80 KB free (Q86's 20 KB spare on top), not 55 KB. A check, list or install someone asked for makes IRC step aside and come back after; the daily check never does, and with IRC connected it waits. (First: 55 KB and nothing else. With IRC connected a check left 3 KB and a download 836 bytes.) Q173Left out, each with its issue: installing automatically (#52), a release channel (#53), resuming a download (#54). Q174Ships as v0.11.0. Tested on the device with the real signed releases; a Debug Build command pretends the device runs an older version, so v0.10.0 counts as an update. Done when A check, by hand or daily, tells the right thing: up to date, newer available, no network, bad certificate, no clock, too little memory. A newer release installs from the Firmware page with no card and no PC, and the device restarts into it and confirms it. A tampered or truncated download is refused and the running firmware keeps running. The Older releases list shows ten, and installing one asks first. A release that rolled back isn't announced again. A Debug Build shows the latest release and doesn't install it. The daily check never runs below the memory floor, during an install, or without a clock. Work breakdown Model (host-tested): a streaming JSON scanner, the release list read from it, HTTP response heads and chunked bodies, URLs, which release counts as an update. The connection: the root certificates, an HTTPS client, a check and a list from the Update Service's task; console commands to try them. The download: an HTTPS source for the existing install path. The screens: the Firmware page's release rows, the release page, Older releases, the setting, the daily check and its Toast. Checks on the device, recorded here. As built lib/release (host-tested): a streaming JSON scanner, the release reader built on it, HTTP heads and chunked bodies, URLs, and the decisions (which release is an update, whether to announce it, which download URLs are taken). A list of ten releases is 33 KB of JSON and costs a few hundred bytes of memory, because nothing is kept but the path. HttpsGet (src/platform): one GET, the answer read as a stream, redirects not followed. GiteaReleases keeps the latest and the list. The Update Service serves the requests on its own task (about 5.4 KB of its 7 KB stack at the peak) and installs through the install path that already existed, with an HTTPS source in place of the card or the TCP port. The daily check is scheduled from the Update Service's tick: Wi-Fi up, the Clock set, no Probation, nothing else going on, memory for a connection. The day it last succeeded is kept in flash. A version that failed (rolled back) is remembered as ota_failed, and isn't announced again by the daily check. The screens: the Firmware page's Latest release and Older releases rows, a release page with the tag's message, and the install dialog. Debug Builds get knobs to try what can't be tried otherwise: update pretend, probe, damage and daily. The first message, ... available: see Settings > Firmware, was cut at 48 bytes by the notification's own limit; it now reads v0.11.0 is out: see Settings > Firmware. Checks on the device (2026-10-06, Debug Builds of branch gitea-updates) CheckResult Host tests456 pass Check and list against the live serverThe certificate is accepted against the two embedded roots; releases/latest read; a list of ten (33 KB) streamed Servers that must be refusedgithub.com, example.com, expired.badssl.com, self-signed.badssl.com, wrong.host.badssl.com, untrusted-root.badssl.com and the router: each "isn't accepted" or a TLS error A download cut short at 800,000 bytesRefused, "update file too short"; the running firmware untouched One byte flipped in the signatureRefused after 160 bytes, "bad signature"; the image isn't read further One byte flipped in the imageDownloaded in full, refused at its end, "image corrupted (hash mismatch)" The real v0.10.0, from the console and then from the screenDownloaded, restarted, confirmed on Probation: the slot table read v0.10.0, valid both times. The Debug Build was pushed back from the PC after each The screensLatest release (checking, then (current) or (new)), the release page with the tag's message, Older releases with ten rows, the install dialog (Cancel by default, Back cancels), the progress screen at 28% IRC connected, before the holdA check left 3 KB of heap; a full download, 836 bytes IRC connected, with the holdThe lowest free heap during a full download: 38 KB. IRC reconnected afterwards (its counters kept growing) The daily checkIt ran by itself, announced v0.10.0 is out: see Settings > Firmware once; with IRC connected (68 KB free) it didn't run Speed1.9 MB in about 46 s, 40 KB/s, over the guest Wi-Fi at -65 dBm; not investigated further Not checked: the certificate's name on its own. Connecting by IP makes the server end the handshake before it shows its certificate, so that test proved nothing; the library sets the name it verifies, and OpenSSL on the PC refused the wrong name against the same chain. A failed daily check retrying, the clock not being set, the release that failed before not being announced (host-tested, not on the device), and the hold when IRC isn't connected but Gemini holds memory. Limits worth knowing: With IRC connected for days, the daily check doesn't run. It would have to take IRC down to make room. Opening Latest release does. A server that changes CA can't be reached until a firmware carrying the new root comes from the PC (ADR 0009). No resuming: a broken download starts over (#54). A key press during the hold: Back on the Firmware page while a check is going doesn't cancel it. Two slips during the checks: a blind sequence of keys on the Firmware page opened the SD card's install dialog (the page keeps its selection between visits); it was cancelled with Back, nothing installed. And my port-polling while waiting for a restart took the Debug Console's only client slot, which made the first install attempt look like a failure.

The issue asked for a token that could be set, so that Debug Builds could be published. The design round ended somewhere simpler: no Debug Builds. The console is in every firmware, off until switched on, with a token that belongs to the device (ADR 0010, which supersedes part of ADR 0004). Decisions (design round 2026-10-06) #Decision Q188One firmware, with the Debug Console and the test commands compiled in. The cardputer-adv-debug environment, RORO_DEBUG, the +debug version and scripts/debug_flags.py go; CI builds one firmware. Revises Q153 and Q171. Q189Off by default, and off when the stored setting is missing or invalid. Off, nothing listens and no memory is used: the task and the 4 KB ring exist only while it's on. Q190Settings → Debug Console: the switch, where to connect, the token, "New token", "Type a token". It stays on across restarts and in Safe Mode. DBG in the Status Bar while it listens, bright with a client connected. Q191The device makes the token the first time the console is switched on: 100 bits as 20 characters of Crockford's base32, shown in groups of four. It can be replaced by one typed by hand, of at least 16 characters. Case and dashes don't count. Q192USB serial can set it up: debug on, debug token <value>, debug token new, over USB only; debug status and debug off from anywhere. scripts/flash.sh --debug gives a device the developer's token. The token is never printed. Q193Challenge and answer: the device sends 16 random bytes, the client their HMAC-SHA256 keyed by the token. Five wrong answers in a row close the console for a minute, with a Notification. Old clients and old firmwares don't talk to each other: accepted, this far from v1 and with one user. Q194rdbg.py takes the token from -t/--token, then $RORO_DEBUG_TOKEN, then ~/.config/roro9stack/debug-token. Q195The test commands are in every build (crash abort, crash wdt, update pretend, update damage, lora inject, sd fill, loop spin, wifi ip … try). update install … force goes: there's nothing left to protect. As built lib/debug (host-tested, 9 tests): the token maker, tidying what a person types, HMAC-SHA256 on the project's own SHA-256 (checked against RFC 4231), the answer to a challenge (the same vector as rdbg.py's), a comparison that takes the same time whatever it's given, and the pause after five wrong answers, right across the clock's wrap. Two settings, DebugConsole and DebugToken, with the others: validated, and invalid stored values count as missing. The console's task and ring come and go with the setting. Console::openRing allocates the ring; switching off closes the socket, frees it and ends the task. tick follows the settings once a second, so a switch off and on again takes a second or two. Measured against the two builds it replaces: 1,881,799 bytes of flash and 54,700 of static RAM. The release build was 1,851,387 and 54,612 (so 30 KB more flash and 88 bytes more RAM); the Debug Build was 1,874,887 and 58,780 (4 KB of RAM back: the ring is no longer a static array). The listener is asked whether it listens. The framework's begin() returns nothing and fails without a word; the task now checks, says so on the console, and tries again every two seconds. debug off <seconds> closes the console and brings it back by itself: the only way to try its closing and reopening from afar, since switching it on is for the device and the cable only. scripts/rdbg.py answers the challenge, and fetches a release's ELF from Gitea when a crash names a version that isn't in .pio/elves/. Checks CheckResult Host tests468 pass (456 before) The firmware buildsOne environment, 1,881,799 bytes of flash used Pushed over Wi-Fi to a device running a Debug BuildInstalled, restarted; the update port answers and port 2323 refuses connections: off by default Switched on at the device (Settings → Debug Console)A token is made and shown. Its first drawing, in bold at normal size, was misread once: it is now at twice the size, in two lines, and O, I and L are taken for 0 and 1 A login with scripts/rdbg.pyThe challenge is answered; info, screenshot and the backlog work DBG in the Status BarThere while the console is on, bright while a client is connected (screenshots) debug on and debug token over the consoleRefused: over USB serial only Six logins with a wrong tokenFive are refused, a second apart; the sixth, and the right token after it, get locked. After a minute the right token works again. The console's own log and a Notification say so Three crash abort in a rowSafe Mode, with the console reachable: info works, ls / says not available in Safe Mode. rdbg.py crash decodes the backtrace to runCommand at the abort() line. reboot leaves Safe Mode An update over Wi-Fi with the console onThe setting and the token survive: the console is back by itself after the restart debug off over the consoleThe client is dropped and port 2323 refuses connections; the update port still answers debug off 2, 10 times in a row, then 15It came back each time, a second after the pause. Free heap dips by about 270 bytes for each connection the device closes and is all back two minutes later (107.2 KB before, 103.2 right after 15, 107.0 at two minutes): TCP holds a closed connection that long. Not a leak, though it looked like one for an hour Memory, console on with a client108 KB free (the Debug Build it replaces: 104 KB). In Safe Mode: 178 KB free One false alarm: after the tests the console "wouldn't come back on". It was off: the setting had been left off by debug off, and the page's "Switch it on?" dialog opens on Cancel, so Enter twice leaves it off. Nothing was lost. Not checked: scripts/flash.sh --debug over USB (no device on USB here); "New token" and "Type a token" from the page (the code paths are the ones debug token uses, which need the cable); the Toast itself on screen (the console is closed while it shows; its Notification is in the log); free memory with the console off, which only the serial port could say (the static figures above are the evidence); fetching a release's ELF, which needs a crash on a released version.

A pull request's run took over seven minutes, a tag's thirteen and a half. The goal: a firmware build under a minute. Where the time went (run 81, a pull request, 2026-10-06) StepTime Tools (apt, pip)15 s Check out2 s Host tests and coverage55 s The firmware358 s of which: CMake configuring ESP-IDF87 s of which: compiling ESP-IDF's libraries171 s of which: our own build (the Arduino core, the libraries, src/)91 s A tag's run did the firmware step, then built the same commit again for the release: twice 356 s. Why the framework was rebuilt every time The framework is rebuilt with our SDK settings (ADR 0006), and the rebuilt libraries stay in the toolchain volume. But the platform decides whether they match by reading sdkconfig.defaults in the project folder, whose first line carries a hash of the settings. That file is generated, and not in git. A fresh checkout has none, so the platform concluded "different settings", reinstalled the framework and rebuilt it: 260 seconds, at every run, to arrive at the libraries that were already there. On a developer's machine the file is simply still there from the last build, which is why nobody saw it. What changed ChangeEffect The file is kept in the volume, inside the libraries it describes (framework-arduinoespressif32-libs/.roro-sdkconfig.defaults), copied into the checkout before a build and back after one that passed. The platform still checks its hash against platformio.ini: changed settings rebuild, as they must. Kept there and not beside them, it disappears when the libraries are reinstalled, so it can't describe libraries that are gone358 s to 92 s The version is no longer a -D on every compiler command line. scripts/version.py writes lib/version/src/version_generated.h (not in git, written only when it changes), read by one file. Before, every commit recompiled everything, on a developer's machine too, and no cache could have helpedA rebuild with nothing changed: 77 s to 13 s, locally PlatformIO's build cache (PLATFORMIO_BUILD_CACHE_DIR, SCons's CacheDir) in the volume, for the firmware of pull requests: objects by the signature of their sources and command line92 s to 26 s, with a new version and one changed file ccache for the host tests. They are built with coverage counters, and the build cache would return objects without their .gcno files; ccache keeps both49 s to 33 s. What's left is PlatformIO starting 51 test programs A tag builds its firmware once, in the release stepminus 6 minutes PlatformIO and gcovr in a virtual environment in the volumea few seconds A release compiles its own sources from nothing: it reuses the rebuilt framework (the platform checks the hash) but not the build cache, so no published file contains an object that came from another commit's build. Measured (a development machine, fresh copies of the tree, the same volume) BeforeAfter The firmware, fresh checkout, nothing cached for it358 s82 s (it fills the cache) The firmware, fresh checkout, a new version and one file changed358 s27 s Host tests and coverage49 s33 s Rebuilding locally with nothing changed77 s13 s Measured on the runner (pull request #76, 2026-10-07) RunToolsTests and coverageThe firmwareThe whole job Before (run 81)15 s55 s358 s434 s The first with the new workflow: no mark yet, the framework is rebuilt once more and the caches fill16 s59 s354 s431 s The next commit (only the workflow changed)10 s36 s51 s100 s The same commit again10 s36 s18 s66 s In the 51-second run, 245 objects came from the cache and 43 were compiled: version.cpp, as expected, and all 42 files of src/, which had not changed. In the run after it, all 290 came from the cache. So the objects of src/ made by the run that rebuilt the framework were not reusable by a normal run, and those of a normal run are: the two-pass build that rebuilds the framework compiles src/ with something different on its command line. It costs one 51-second run after each framework rebuild, which is rare; I did not look for what differs. The firmware step with everything cached is 18 seconds: the libraries are downloaded and unpacked (4 s), the dependency scan (5 s), fetching 290 objects, the link and the image (the last 11 s). A pull request that changes a few files should land between that and 51 seconds. What it costs: the build cache grows by about 40 MB a run (each linked firmware is kept) and is started again past 3 GB; ccache is held to 1 GB.

roro9stack.net already points at the server that hosts Gitea. Plain HTTP redirects to HTTPS; HTTPS has no certificate yet, which is the server's side to set up. Release downloads from Gitea carry no CORS header, so a browser can't fetch the factory image from another origin as things are. Gitea is behind Caddy, which can add the header (below). Zola can read JSON from a URL at build time (load_data), so the home page's "latest version" can come from the Gitea API. There is no Gitea wiki: the design's "Wiki" links would 404. The blog is published by pulling its repository on the web server and running zola build. The site does the same.

#Decision Q175The site lives in this repository, in site/, so the documentation is built from docs/, CONTEXT.md and the README instead of being copied. Q176Zola, like the blog. The design becomes a template, its tokens CSS custom properties. Dark and light follow the visitor's setting, with a visible switch. No JavaScript except the flasher's. Q177Domain: roro9stack.net. The blog stays at experiments.twis.la. Q178Publishing is the blog's way: the web server pulls main and runs zola build; that part is the maintainer's. (Since issue #79, CI asks the server to do it: see "Published by CI" below.) Changes reach main through pull requests as everywhere. CI is split: a dedicated site job builds the site (zola build) when site/, docs/, README.md or CONTEXT.md change, and the firmware tests and builds skip a change that touches nothing else. A change that touches both runs both. Q179Phases, each its own pull request: 1. the CI split, the home page, an Install page with the browser flasher, downloads and the changelog. 2. a user guide page per App. 3. how-tos and the FAQ. 4. developer docs generated from the repository. Q180A browser flasher (ESP Web Tools), without copying the firmware. Caddy, in front of Gitea, adds Access-Control-Allow-Origin: https://roro9stack.net (and Vary: Origin) to GET and HEAD on /twisla/roro9stack/releases/download/* and /api/v1/repos/twisla/roro9stack/releases*: both are public already. The Install page asks the API for the latest release in the browser, finds the asset ending -factory.bin, and gives ESP Web Tools a manifest built on the spot, so it offers a new release as soon as it exists, with no rebuild. The library is vendored into site/static/ (Apache-2.0), not loaded from a CDN. The file's SHA-256 is shown on the page. Chrome or Edge on a desktop only; other browsers, and visitors without JavaScript, get the esptool steps on the same page. Q181Docs for the latest version only. The changelog is the Gitea releases, read at build time. Q182English only. Q183The FAQ starts from real questions: the README, and issues labelled kind/docs. Q184Fonts are self-hosted (no request to a third party). The hero keeps the design's illustrations, labelled as illustrations, and a section of real device screenshots is added. Q185The site says only what the firmware does today. Planned features are marked as planned, with their milestone. The mesh messenger is planned: the LoRa Scanner listens, nothing is sent. Q186Left out, each with its issue: a Gemini capsule mirror (#57), French (#58), docs per version (#59), search (#60). Q187The site has no version of its own. Contact is contact@roro9stack.net, and the issue tracker.

Kept as designed: the layout, the tokens, the nine App cards (their facts check out against the code: Probation 3 minutes, Safe Mode after 3 crashes, 60 seconds of typing before an update restarts the device). Changed before it ships: Install, not Download, is the first action. Downloads are for developers; a visitor wants to try it. A "what you need" strip: Cardputer ADV, the Cap LoRa-1262 (only the radio needs it), a microSD card, Wi-Fi. And a plain status line: the version, and what isn't there yet. The mesh card and the hero no longer promise sending and reading mesh messages. The latest version is read from the API, not typed. "Wiki" is replaced by Docs. The updates section gains what v0.11.0 added: the device installs releases from the project's server itself. An independence line: not affiliated with or endorsed by M5Stack or Meshtastic. No cookies, no analytics, no third-party requests, said on the page (fonts self-hosted). The keyboard focus ring is invisible on the notched buttons: clip-path clips an outline. Another way to show focus is needed. The wordmark SVGs carry an embedded C2PA content-credentials block: stripped from the site's copies.

Pushing a change under site/ runs the site job and not the firmware tests; a firmware change runs the firmware jobs and not the site's. The home page renders in both themes, at phone width, with the keyboard, and says nothing the firmware doesn't do. The latest version on the page is the latest release. The browser flasher installs the latest release on a Cardputer ADV from Chrome (tried by hand), the page shows the file's SHA-256, and the esptool steps are on the same page. A release published after the site was built is the one the Install page offers. The home and Downloads pages make no request to another origin, and the Install page only asks git.twis.la.

CI split: a site workflow, path filters on the firmware workflow. The skeleton: site/ with the tokens, fonts, base template and the theme switch. The home page, from the design, with the changes above. Install and downloads: the flasher with its manifest built in the page, the esptool steps, the changelog. Needs the Caddy headers on the Gitea host (the maintainer's side); the page is tested against them once they're in. Checks, recorded here.

CI is split. ci.yml (the firmware) has paths-ignore: site/**, docs/**, README.md, CONTEXT.md on pushes to main and on pull requests. site.yml runs zola check and zola build with a Zola pinned by its checksum, then site/tools/check_site.py, when those files change. Gitea's own source (v1.24, read, not run against the 1.27 server) shows that path filters count as matched for tag pushes, so a tag still releases. A change that touches both runs both. The build output goes to public/ at the root of the repository, not into site/: output_dir = "../public" in site/config.toml, so zola build in site/ and zola --root site build from the root agree, and git ignores /public/. The site is in site/: config.toml, templates (base, home, install, downloads, 404), data/ for the App cards and the screenshots' captions, static/ (stylesheet, theme switch, fonts, wordmark, icons, real screenshots, the vendored flasher). site/README.md says how to build it and what the server needs. The home page follows the design. Changed from it: the hero and the mesh card promise nothing that isn't built (the mesh messenger is a "planned" card), an Install button first, a status box, a "what you need" row, a section of real screenshots, the updates section says the device installs releases itself, an independence line and a statement about cookies and third-party requests in the footer, the latest version read from the Gitea API at build time, and the nav's Wiki replaced. The two hero drawings are generated by site/tools/make_illustrations.py (a port of the design's scripted shapes) as inline SVG. The focus ring. clip-path clips outlines, so a focused notched control drops its notches and shows square corners and its ring. The Install page asks the API for the latest release in the browser, builds the ESP Web Tools manifest as a blob, shows the version, size and SHA-256, and only ever hands the flasher a download from the project's own server for this repository. The flasher library (ESP Web Tools 10.4.0, Apache-2.0) is vendored, trimmed to the ESP32-S3. Fonts (DM Mono, Hanken Grotesk, SIL OFL) are self-hosted. The Downloads page lists the last 30 releases with their files, read at build time. The wordmark SVGs from the design carried an embedded C2PA content-credentials block; it is removed from the site's copies.

/guide/ is a section of 11 pages, site/content/guide/, each with template from the section's page_template and an order from weight: the basics (keys, Launcher, Status Bar, first start, the card), then one page per App (LoRa Scanner, GNSS, Gemini, IRC, Wi-Fi tools, Notes, Storage, System), Settings and Updates. Pages with real screenshots list them in extra.screens, looked up in data/screens.toml. Facts come from the README, the milestone documents and the Apps' own source (key handlers, labels, the Status Bar's drawing code), not from memory. Some wording was corrected against the source while writing: the Track folder is /gnss/tracks, the reasons a Track won't start, what the Status Bar shows. Not covered: the mesh messenger (planned), the debug console and Debug Builds beyond a pointer to the README. How-tos and the FAQ are phase 3.

Not one of the planned phases: the blog's seven roro9stack posts, imported into site/content/devlog/ and shown in the site's own style, with the Blog link in the navigation and the footer replaced by Devlog. The posts' text, tone and structure are unchanged; what changed: Links: the posts' links to each other point to /devlog/<same name>/, and one link to an unpublished work-in-progress post became plain text. Each post keeps its old directory name, so the old URL /<name>/ maps to /devlog/<name>/. The posts' parts (the sign, the cast, the steps, asides, folded sections, diagrams, captions) are shortcodes in site/templates/shortcodes/, restyled in static/css/devlog.css: the site's palette, notched boxes, DM Mono and Hanken Grotesk. The two older posts about other subjects (a vinyl remote, a ZFS rescue) stay on the blog. The 17 diagrams are inline SVG, and carried <style> blocks and style attributes that the site's Content-Security-Policy refuses. Their rules moved to static/css/devlog-diagrams.css (one block per diagram, plus colour classes for what the attributes did), and a diagram's minimum width is a class, not a style attribute. The Caddy policy needs no change. The diagrams' four colours (red, green, yellow, accent) are defined for .devlog on the site's RGB332 grid, one value for each theme. Links between posts: every post's reference to another ("the last post", "the first post", the milestone lists) is a link to it. check_site.py now also checks every link inside the site, and its #fragment: a broken one fails the Site job. External links are checked by zola check run by hand (without --skip-external-links, which CI uses); its only complaints today are line-range and heading anchors on Gitea, which Gitea resolves in the browser. An Atom feed at /devlog/atom.xml, linked from every devlog page. Checked in Chromium with the production CSP applied to every response: the index and the seven posts, at 1100 and 390 px, no policy violation, no broken image, no sideways scroll; check_site.py 24 pages, 0 problems.

CheckResult The Site workflow's own commands, in a clean container with the pinned Zolazola check clean, build and page checks pass tools/check_site.py4 pages, 0 problems: titles, descriptions, a language, every image with alt text, every local file referenced exists, nothing loaded from another origin Browser tests (Chromium, 16 checks)All pass: no request to another origin from the home, Downloads and 404 pages; no horizontal scroll at 1280 and 390 px; a visible focus ring on a notched button; the Install page reads the latest release, shows its version, size and SHA-256, builds a blob manifest naming an ESP32-S3 factory image at offset 0, and loads only git.twis.la; a download on another host is refused; the real server (no CORS header today) makes the page fall back to the esptool steps The pages looked atHome in dark and light, at desktop and phone width; Install; Downloads esptool against the real v0.11.0 factory imageAn ESP32-S3 image, bootloader at 0x0, partition table at 0x8000: flashing at offset 0 is right. The command's syntax was checked, not a flash Not checked: Flashing a real Cardputer from Chrome. It needs the device on a machine with a browser; the page's flasher logic is tested, the flashing itself isn't. Caddy's headers on the real server (not applied yet), and HTTPS on roro9stack.net (the name resolves, the certificate isn't there). The CI split on a change that touches only site/ or docs/. This pull request touches both the workflows and the site, so it runs both; the first docs-only pull request will show it. Firefox and Safari rendering, screen readers, and a printed page. The unverified wording in the Install text is kept to what's known: nothing about how long flashing takes, or what the screen shows in download mode.

/howto/ has eight short recipes: when flashing fails, find your files on the SD card, install an update from the card, use a network without DHCP, record a Track, capture LoRa packets for Wireshark, read Gemini pages offline, and what to do when a connection says "not enough memory". /faq/ is one page of questions with a list at the top. Both use the guide's templates (guide-index.html, guide-page.html, now generic: the page's parent section gives the eyebrow, the title and the pager). The FAQ starts from the README and from the problems the project met (Q183): the flash troubles and the memory limit are the two that were hit most. The issues labelled kind/docs turned out to be design rounds for the mesh, not user questions, so they gave nothing to answer. Every step comes from the README, the milestone documents or the Apps' source. The privacy answer says plainly that the device contacts the project's server once a day for the update check (on by default, one switch to turn it off). Linked from the guide's index, not the navigation, which stays short.

/dev/ has four sections: Debug Builds and the Debug Console (first, and the longest: Debug Builds, the Console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, and the command reference), Build, test and release (the README's build, CI and flash sections, and how an update works, with the update file, the four ways in and Probation drawn), Decisions (the ADRs) and Milestones (the plans). Generated from the repository, not copied by hand: site/tools/gen_dev_docs.py writes the ADR pages, the milestone pages, the README's sections, and the command reference, which is read from the firmware's own help text in src/main.cpp and then the README's table of what each command does. Zola can't read outside its own folder (not even through a symlink), so the generated pages are committed, and the Site workflow runs gen_dev_docs.py --check and fails when one is out of date; it now also runs when src/main.cpp changes, because the command list lives there. The server's pull; zola build is unchanged. Left out on purpose: the M0 and M1 milestone documents and CONTEXT.md (the glossary) describe Wi-Fi monitoring, which the site does not publish. They stay in the repository. The Debug Console pages were written against the source and the live console: the protocol (the token line, the banner, the 4 KB backlog, one client, 8 queued commands, 240-byte lines, denied after a second) and the replies shown were checked on a Debug Build, v0.11.0-3, over Wi-Fi. Not run: crash abort, crash wdt and Safe Mode, which are described from ADR 0005 and the code. Found while writing it: the README's table lacked the gnss commands (rows added); piping commands into rdbg.py returns before the replies unless the input stays open (documented, not changed); update install on a Debug Build needs force (documented).

Q178 left publishing to the maintainer: a merge, then a command typed on the web server, each time. #Decision Q214A plain ed25519 key with a forced command, not a certificate: one line in the web server user's authorized_keys, restrict,command="/full/path/to/the/refresh". restrict takes away the terminal and every forwarding. A certificate could carry the same and an expiry date, at the price of a CA to keep and a key to sign again each time: too much for one key and one command. Q215The CI sends no command. The server runs the forced one whatever is asked for, so there is nothing to keep secret about it and nothing a leaked key could choose. The full path is written once, on the server (a command over SSH doesn't get the user's login PATH). Q216Four secrets: SITE_DEPLOY_KEY, SITE_DEPLOY_HOST (or host:port), SITE_DEPLOY_USER, and SITE_DEPLOY_KNOWN_HOSTS, the server's host key: the job connects to that server or to nothing. None of them is in the repository, which is public. Q217from="<the runner's address>" on the same line: the key works from the runner only. Q218The last step of the Site workflow, after the build and the checks, on a push to main only. A pull request never reaches it, and the secrets are given to that step alone. Q219After a release too. The Install page asks Gitea for the latest release when it is opened, but the home page and Downloads read it when the site is built: so the release workflow refreshes the site once the release is published. Q220A refresh that fails makes the run red, with what the server's script printed: it has to exit with an error when it fails. Q221Two refreshes at once are the server script's to refuse or queue (flock). Q222The key is a file only while the step runs, in the job's container, as the signing key is. As built scripts/site_refresh.sh is what both workflows run: it writes the key and the host key to a temporary folder, connects with no configuration but its own line (-F none, strict host key checking, that one key, no command), and removes them. With none of the four secrets it does nothing and says so (a fork, or a repository without them); with only some it fails. scripts/site_deploy_keygen.sh makes the key pair once, in ~/.config/roro9stack/, and prints the authorized_keys line and what goes in each secret. It never prints the private key. The server's script should start like this, for Q220 and Q221: #!/bin/sh set -e exec 9>/tmp/rororefresh.lock flock -w 120 9 Checks (2026-10-07, against an SSH server in a throwaway container) CheckResult The refreshThe forced command runs as the server's user; the script ends with site refresh: done The same key, asking for id; cat /etc/passwdThe refresh runs instead; what was asked for is only handed to it as text A terminalRefused: PTY allocation request failed scp with the keyNothing is copied Another host key in the secretHost key verification failed, the run fails, nothing is sent The server's script exits with an errorSo does the step No secrets at all; only one of the fourDoes nothing and says so; fails and says which are needed Not checked: the real web server and the runner, which wait for the key to be installed: whether the runner reaches the server's SSH port is the first thing the first run will tell. Port forwarding, which restrict switches off, was not tried. from= was not tried either.

A search over the documentation: the user guide, the how-tos, the questions and answers, and the developer docs. Not the devlog. The index is the search page itself (/search/, templates/search.html): one list item for each page and for each ## heading of it, with that part's text, written by Zola from the pages' own content when the site is built. Nothing is fetched and nothing typed leaves the browser, so the Content-Security-Policy needs nothing new, and the web server still only runs zola build. Without JavaScript the page is a list of every page and heading of the documentation, each a link. With it, js/search.js filters and ranks the items as you type: every word has to be in the part; a word in a heading counts for most, the words side by side for more than scattered, and the user guide, the how-tos and the FAQ come before the developer docs, the milestones last. A result links to its heading, with the text around the match. The content pages get no script for it: the navigation has a link, and the index pages of the guide, the how-tos and the developer docs have a box that is a plain form to /search/?q=. Size: about 245 items, about 310 KB of HTML, under 100 KB compressed, loaded only by who searches. Checked in Chromium with the production Content-Security-Policy on every response, no violation: "probation" (the guide's "Probation and Rollback" first), "safe mode", "rm -r", "how big can a note" (the FAQ's question first), a word that isn't there; typing, following a result to its heading, the box on the guide's index, 390 px wide with no sideways scroll, and JavaScript off. check_site.py follows every link of the page, so an index entry can't point at a heading that doesn't exist. Not checked: other browsers, and a screen reader.

Every screen used to say something about its keys, differently: a footer of abbreviations in one place (c x v:paste r:name d:del n:new i:info s:sort), a line under a text field in another (Enter: save \: cancel), Tab: sky` in a corner, and nothing at all in several. About 30 such strings, each costing a line of a small screen, and none of them complete. Decisions (design round 2026-10-07) #Decision Q196Fn+h, on every screen, text fields included (Fn is held, so nothing is typed). ? too, outside Text Entry. Q197It opens a panel over the content area, titled with where you are: the screen's own keys, then an "Everywhere" group (Back, Home, the arrows, the help key). The arrows scroll it; any other key closes it and is not passed on. Q198Each App answers "what are your keys right now?" for the state it is in; pages, viewers, dialogs and text fields answer for themselves, with shared lists for dialogs, lists and text entry. The lists are constants; the panel's rows exist only while it is open. Q199Every hint that names a key goes, text fields included. What stays is state: REC 12 points, LOG 42, sort:signal, typing/saved, what is waiting to be pasted, the Sweep's floor. Messages were reworded where they named a key ("v pastes a copy of…" is "Copied …: paste it where you like"). Q200The first-start Setup keeps its hints, and is the one place that does: someone in their first minute doesn't know the help key yet. It tells them about it on its first and last screens. Q201Loud everywhere else: the user guide opens with it, the FAQ has it first, and a device set up before this firmware gets one Toast, once: "Fn+h: the keys of any screen". Q202key help over the consoles. Generating the website's key tables from the same lists is a follow-up, not this issue. Q203The key and the panel first, host-tested; then one App at a time, declaring its keys and losing its hints in the same step; then every screen looked at on the device. As built Key::Help from the key mapper: Fn+h in both modes, ? only outside Text Entry (lib/input, 3 tests). App::help() and App::helpTitle() (lib/core/src/app.h), KeyHelp rows and HelpModel (key_help.h). The App manager opens the panel, appends the "Everywhere" group, and while it is open takes every key: nothing reaches the App, Home included. It closes when the App changes (5 tests). Every App declares its keys by state: the Launcher, IRC (chat, settings, a field), Wi-Fi Tools (4 views), GNSS, Gemini (page, saved page, address, answer, dialogs), the LoRa Scanner (4 views), Storage (browse, details, a name, the viewer's 6 modes, the editor, Maintenance, busy), Notes (list, editor, a file name), System (5 views), Settings (menu, text, choice, and the Wi-Fi, Firmware and Debug Console pages with their own states), Setup and the widget demo. The hints are gone from all of them. The footers that remain say state only. It costs 8.5 KB of flash and 40 bytes of static RAM. Checks CheckResult Host tests476 pass (468 before) On the device, key help and a screenshotThe Launcher and all nine Apps, and these states: Storage scrolled, System's tasks, a Settings text field, Wi-Fi Tools' networks. The panel is titled with the scope, lists the right keys, scrolls, and closes on Tab The one-time Toastnotification: Fn+h: the keys of any screen on the first start after the update One source for the device and the website (issue #72) The lists first lived in each App's help(), as code. They are now data, in one file: lib/core/src/app_keys.h, 52 constant tables, each under a comment // id: Title. An App's help() picks the table of the state it is in. site/tools/gen_dev_docs.py reads the same file and writes site/data/keys.toml; the keys shortcode shows a screen's tables on its guide page, and /guide/keys/ shows all of them. The Site job fails when the data file is out of date, or when a page asks for a table that doesn't exist, and it now runs when app_keys.h changes. A key added to an App shows up on the website without anyone editing a page. Three rows lost their second wording on the way, since a table is constant: GNSS's Tab and r, and the Scanner's c, now say both things they do ("record a Track, or stop it") instead of the one that applies. The guide pages keep their written tables too, where they say more than a key list can; those can still drift, and the generated ones under them are the reference. Not checked: the real Fn+h and ? on the keyboard (the mapper is host-tested; the device was driven with key help); the Setup screens, which only a device that was never set up shows, so their new text has not been seen on a screen; and the states that need something to happen first (a dialog, a copy in progress, a Gemini prompt, a packet's details): their lists were read against the key handling, not looked at.