# 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.

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