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

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

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 (name, password). 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 disconnects. 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.

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