Public Access
twislaandClaude Opus 5.5
6b71aace4f
The SSH App opens one session to a shell, over libssh (LibSSH-ESP32 5.10.0) on mbedTLS. A server is trusted the first time on its fingerprint, and a changed key is a warning with Cancel selected. The password is typed each time and kept nowhere; or the device makes itself an Ed25519 key, whose public half is shown, written to /ssh/id_ed25519.pub and printed by `ssh status`. lib/term is the terminal: what a shell, less, top, nano and vim send, with sixteen colours, scroll regions, the alternate screen and 100 lines of scrollback. Five text sizes with Ctrl and + or -, from 60x20 to 26x8, told to the far end. The session goes on when the App is left; SSH shows in the Status Bar. `ssh user@host` in the Shell opens the App. Also: - Keys that aren't characters carry Shift, Ctrl and Alt. The terminal needs it, and it makes Ctrl+Fn+up/down in a note and Shift+Tab in Gemini work from the real keyboard. - IRC doesn't try to connect under 60 KB free: started with a session open, its TLS handshake took the heap down to 236 bytes. - libssh's own curve25519 is left out of the build (scripts/libssh_filter.py): libsodium's has the same names. Costs 292 KB of flash and about 50 KB of heap while a session is open; not started under 75 KB free. Docs: guide page, how-to, FAQ, home page, Status Bar, SD card folders, the memory how-to, README, glossary, N1 notes with Q254 to Q266 and the checks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
220 lines
12 KiB
Markdown
220 lines
12 KiB
Markdown
# 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.
|
||
|
||
**Shell**:
|
||
The App that runs the console's commands on the device itself, and shows what the console prints. Trusted like the USB port, not like the network.
|
||
_Avoid_: terminal, command line, REPL
|
||
|
||
**Tunnel**:
|
||
The WireGuard connection to one server, over whatever Wi-Fi the device is on. It carries either everything or the one subnet the device's address in it belongs to. Wanted or not is the user's switch; up or not depends on Wi-Fi, the clock and the server.
|
||
_Avoid_: VPN connection, link, session
|
||
|
||
**Session**:
|
||
The one SSH connection to a shell on another machine, from login until either side ends it. It belongs to the SSH Service, not to the SSH App: it goes on while another App is in front.
|
||
_Avoid_: connection, tunnel, terminal (the terminal is what draws it)
|
||
|
||
**Device Key**:
|
||
The Ed25519 key pair the device makes for itself to log in over SSH. The private half never leaves the device and is never shown; the public half is meant to be copied to servers.
|
||
_Avoid_: identity, SSH key file, certificate
|
||
|
||
**Sharing**:
|
||
Serving the SD card as a web page to a browser on the same network, for as long as the Storage App's Share screen is open, to whoever typed the code that screen shows.
|
||
_Avoid_: file server, web server, FTP, upload mode
|
||
|
||
**Screenshot**:
|
||
The screen as a PNG in `/screenshots`, taken with Fn+p on any screen or the Shell's `screenshot`. Not the Debug Console's `screenshot`, which sends the screen to a PC.
|
||
_Avoid_: capture (a **Capture** is radio packets), screen grab
|
||
|
||
**Help panel**:
|
||
The list of the keys that work on the screen you are on, opened with Fn+h anywhere (or `?` outside Text Entry). Each App answers for its current state; no screen names keys any other way, except the first-start Setup.
|
||
_Avoid_: hints, cheat sheet, shortcuts bar
|
||
|
||
**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.
|
||
- The SSH App draws the one **Session**; the **Session** and the **IRC Service**'s connection don't fit in memory together, so each waits for the other.
|
||
- **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 **Tunnel** rides on the **Wi-Fi Service**'s connection and ends with it; the next connection starts it afresh.
|
||
- **Sharing** lasts as long as its screen: leaving the **Storage App** ends it.
|
||
- 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).
|