roro9stack/CONTEXT.md

roro9stack

A multi-app handheld operating environment for the M5Stack Cardputer ADV with the Cap LoRa-1262, whose first job is to be a Meshtastic-compatible mesh messenger.

Language

App: A foreground, user-facing program chosen from the Launcher. Only one App is on screen at a time; Apps show and act on what Services hold. Avoid: program, tool, screen

Launcher: The App that lists every other App and starts them. It's the home screen. Avoid: menu, home

Service: A long-lived background capability that keeps running whichever App is in the foreground (e.g. Mesh Service, GNSS Service). Avoid: daemon, task, driver

Mesh Service: The Service that keeps the device participating in a mesh network at all times: receiving, relaying, and sending on behalf of Apps. Avoid: radio, LoRa app

Radio Service: The Service that owns the LoRa radio on the Cap: it configures it, shares the SPI bus with the SD card, and receives in the background. The LoRa Scanner uses it directly; the Mesh Service sits on top of it. Avoid: LoRa driver, modem

Mesh Protocol: One on-air language the Mesh Service can speak (Meshtastic first; others may follow). The Mesh Service speaks Mesh Protocols; Apps don't. Avoid: stack, mode

Node: Any device participating in the mesh, including this one. It's identified by a node number and has a long and a short name. Avoid: peer, device, station

Channel: A named mesh conversation space defined by a name and a shared key. Every Node on the same Channel can read its traffic. Avoid: group, room

Direct Message: A text message addressed to a single Node instead of a Channel. Avoid: DM (in docs), private message

Relaying: Rebroadcasting another Node's packet so it travels further across the mesh. Avoid: forwarding, repeating

Capsule: A Gemini site: everything served by one host on Geminispace. Avoid: site, server (when the content is meant)

Saved Page: A Gemini page kept on the SD card to read offline, with the URL it came from and when it was saved. Kept until the user deletes it; Storage Clean-up never offers it. Avoid: cache, download (a download is a non-text file saved from Gemini)

GNSS Service: The Service that owns the GNSS receiver on the Cap: it reads its NMEA sentences in the background and holds the current Fix, position, time and satellites. Avoid: GPS (GPS is one constellation among several)

Fix: What the receiver currently knows: none, 2D (position without altitude) or 3D (with altitude), from how many satellites, at what HDOP. Avoid: lock, signal

Track: A route recorded from GNSS positions to a GPX file on the SD card, started and stopped by the user. Avoid: trace, log (a Log is recorded on its own)

Compass: The third view of the GNSS App: a rose turned by the Heading, and the way to the target Place.

Heading: Where the top of the device points, in degrees from true north. It is given by the course over ground while walking or by aiming at the sun, and held by the gyroscope in between. Avoid: course (the course is the direction of travel, from the receiver), bearing (a bearing is the direction to somewhere else)

Place: A named position the user marked, kept as a GPX waypoint on the SD card, that the Compass can lead back to. Avoid: waypoint, POI

Wi-Fi Service: The Service that owns the Wi-Fi radio. It's always in exactly one mode: Off, Connected (joined to a Saved Network) or Monitoring (passively observing). When Wi-Fi is enabled in Settings, it stays Connected whenever a Saved Network is in range. It goes Monitoring only while Wi-Fi Tools needs it, then reconnects. Avoid: network manager

Saved Network: A Wi-Fi network the device may join on its own: its name, its password, and how it gets its address, Automatic (DHCP) or Fixed (an address, a prefix and an optional gateway typed in Settings). When several are in range, the strongest wins. Avoid: profile, known network

IRC Service: The Service that keeps the IRC connection alive in the background once the IRC App has started it, until the user stops it (/quit, or irc stop on the console). Once stopped by hand, opening the App again doesn't reconnect; typing a line does. It reconnects after drops, and pauses while the Wi-Fi Service is Monitoring. It does not start by itself after a reboot. Avoid: IRC client (that's the App)

Buffer: One IRC conversation shown in the IRC App: the server, a channel, or a private chat with one nick. Each Buffer counts its unread messages. Avoid: window, tab, room

Mention: An IRC message containing the user's nick, or any private message. Mentions raise Notifications; other traffic only counts as unread. Avoid: highlight, ping

Status Bar: The strip shown on every screen with system state at a glance: battery, GNSS fix, mesh activity, Wi-Fi mode and unread count. Avoid: header, top bar

Notification: News from a Service that reaches the user while another App is in the foreground. It shows as a brief Toast and may beep or flash. Avoid: alert, popup

Sniffer: The LoRa Scanner mode that passively listens with the Mesh Service's own radio settings. It never interrupts mesh participation. Avoid: monitor (that word belongs to Wi-Fi)

Sweep: The LoRa Scanner mode that takes over the radio to survey frequencies. It pauses the Mesh Service while active. Avoid: scan (ambiguous with Wi-Fi scanning)

Region: The regulatory band plan the device transmits under (here EU868). It sets the allowed frequencies, power and duty cycle. Nothing transmits until it has been confirmed.

Duty Cycle Budget: The share of airtime the Region allows this device to transmit. When it's used up, outgoing traffic waits.

Shell: The App that runs the console's commands on the device itself, and shows what the console prints. Trusted like the USB port, not like the network. Avoid: terminal, command line, REPL

Tunnel: The WireGuard connection to one server, over whatever Wi-Fi the device is on. It carries either everything or the one subnet the device's address in it belongs to. Wanted or not is the user's switch; up or not depends on Wi-Fi, the clock and the server. Avoid: VPN connection, link, session

Session: The one SSH connection to a shell on another machine, from login until either side ends it. It belongs to the SSH Service, not to the SSH App: it goes on while another App is in front. Avoid: connection, tunnel, terminal (the terminal is what draws it)

Device Key: The Ed25519 key pair the device makes for itself to log in over SSH. The private half never leaves the device and is never shown; the public half is meant to be copied to servers. Avoid: identity, SSH key file, certificate

Sharing: Serving the SD card as a web page to a browser on the same network, for as long as the Storage App's Share screen is open, to whoever typed the code that screen shows. Avoid: file server, web server, FTP, upload mode

Screenshot: The screen as a PNG in /screenshots, taken with Fn+p on any screen or the Shell's screenshot. Not the Debug Console's screenshot, which sends the screen to a PC. Avoid: capture (a Capture is radio packets), screen grab

Help panel: The list of the keys that work on the screen you are on, opened with Fn+h anywhere (or ? outside Text Entry). Each App answers for its current state; no screen names keys any other way, except the first-start Setup. Avoid: hints, cheat sheet, shortcuts bar

Text Entry: When an App is editing text. During Text Entry, ; . , / type their characters and Fn makes them arrows. Otherwise they are arrows on their own. Avoid: edit mode, insert mode

Compose Key: The opt key used as a dead key. Pressing it and then a base letter types an accented character (e.g. opt ' e → é). Avoid: modifier, alt

Log: History the device records automatically in the background: mesh message history, IRC logs, Wi-Fi scan logs. Avoid: history file, dump

Capture: Data the user explicitly starts recording, such as Wi-Fi packet captures and LoRa Sniffer captures. Avoid: dump, log

Storage Warning: The Notification raised once per boot when the SD card passes 80% full. It points at the Storage App, where Maintenance holds Storage Clean-up.

Storage Clean-up: The screen where the user deletes old Logs and Captures by category and age, with a preview of the space freed. Notes are never offered for deletion. It lives in the Storage App, under Maintenance.

Note: A plain text file in /notes, written on the device in the Notes App. Listed by its first line. Saved without being asked; never offered by Storage Clean-up. Avoid: memo, document

Storage App: The App that browses the SD card: folders and files, a clipboard for one item at a time (copy, cut, paste), rename, delete, new folder, and a viewer for each kind of file the firmware writes. The top-level folders, /gemini/cache and files being written are read-only. Avoid: file manager, Files, explorer

Maintenance: The part of the Storage App that deletes in bulk: the card's usage, Storage Clean-up and erasing the card. Reached through a warning. Avoid: Settings > Storage

Firmware Update: Installing a new firmware image without a USB cable: pushed over Wi-Fi from the developer's PC, read from the SD card, or downloaded from the project's Gitea Release.

Release: A tag v* on the project's Gitea with a signed Update File, a factory image for USB, the ELF to decode crashes and checksums, built and published by CI. The device reads them to look for updates. Avoid: flash, upgrade (alone)

Update File: One signed file (.ota) that carries a firmware version, its image and a signature. The same file works over Wi-Fi and from the SD card. Anything not signed with the project's key is refused. Avoid: binary, bin

Probation: The state of newly installed firmware until it proves healthy: booted, UI drawn, Services started, 30 s without a crash, and Wi-Fi connected if it's configured. Then it's confirmed for good. Avoid: trial, test mode

Rollback: Returning automatically to the previous firmware when new firmware resets or crashes during Probation. Avoid: revert, downgrade (a downgrade is installing an older version on purpose)

Safe Mode: What the firmware starts instead of everything else after 3 crash restarts in a row: Wi-Fi and Firmware Updates (and the Debug Console if it's switched on), so it can be fixed without a cable. A normal restart leaves it. Avoid: recovery mode, failsafe

Debug Console: The console over Wi-Fi, in every firmware but off until switched on in Settings: live log lines and the serial commands, for whoever holds the device's token. Avoid: telnet, remote shell, Debug Build (there is one firmware)

Relationships

• The Launcher starts Apps. Exactly one App is in the foreground.
• Services keep running underneath, regardless of which App is in the foreground.
• The Mesh Service speaks one or more Mesh Protocols and tracks the known Nodes.
• The Wi-Fi Service is either Connected or Monitoring, never both. Monitoring pauses the IRC Service, which reconnects and rejoins its Buffers afterwards.
• The SSH App draws the one Session; the Session and the IRC Service's connection don't fit in memory together, so each waits for the other.
• Services raise Notifications; the Status Bar summarises Service state.
• The Radio Service owns the radio; the Mesh Service and the LoRa Scanner use it.
• A Sweep pauses the Mesh Service; a Sniffer does not.
• Every transmission is bounded by the Region and its Duty Cycle Budget.
• Past 90% SD usage, Logs stop being written; the remaining space is kept for Captures. Nothing is deleted without the user's confirmation.
• A Firmware Update installs an Update File; the new firmware runs on Probation, and fails back by Rollback.
• Rollback covers new firmware; Safe Mode covers confirmed firmware that keeps crashing.
• A Tunnel rides on the Wi-Fi Service's connection and ends with it; the next connection starts it afresh.
• Sharing lasts as long as its screen: leaving the Storage App ends it.
• A Node may be in several Channels. A Direct Message targets exactly one Node.

Flagged ambiguities

• "LoRa" was used both for the radio and for the mesh. Resolved: say Mesh Service for the always-on participation and Mesh Protocol for the on-air format. The LoRa Scanner App uses the radio directly and doesn't speak a Mesh Protocol.
• "Channel" has three meanings here. Resolved: an unqualified Channel is the mesh one. The others are always qualified as "IRC channel" (a kind of Buffer) and "Wi-Fi channel" (radio frequency, 1–13).