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

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