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 an access point) or Monitoring (passively observing). It's Off unless an App asks for another mode. Avoid: network manager

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.

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, probe-request 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 serves one App at a time. Monitoring and Connected are mutually exclusive.
• 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.