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