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)

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.

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. Selecting it opens 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.

Firmware Update: Installing a new firmware image without a USB cable: pushed over Wi-Fi from the developer's PC, or read from the SD card. 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 in a Debug Build), so it can be fixed without a cable. A normal restart leaves it. Avoid: recovery mode, failsafe

Debug Build: A firmware built with the remote debugging aids compiled in (+debug in its version). Release builds have none of them. Avoid: dev build, test build (a test build is one made to fail on purpose, such as a crashing update)

Debug Console: The console of a Debug Build over Wi-Fi: live log lines and the serial commands, behind a token. Avoid: telnet, remote shell

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.
• 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 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).