twislaandClaude Opus 5.5
b7aed8e91c
The Storage App browses the SD card: folders first with sizes and dates, three sorts, one item at a time with a clipboard (c, x, v), rename, delete after counting what's inside, new folder, details. A listing holds 256 entries and says when a folder has more. FileOps does the card's work for the App and the console alike, one operation at a time on the storage task in turns of about 150 ms, so Logs and Captures are still written during a long copy. A copy shows progress, can be cancelled (what it wrote is taken back) and compares sizes after. The read-only rules are checked there: the firmware's top-level folders, /gemini/cache, and files being written (a Track, a Capture, an upload, today's IRC Logs). A listing reads the folder straight from FatFs: through the Arduino File, 329 entries took over two seconds. Viewers by type: text read a screen at a time whatever the file's size (logs open at the end), a hex dump, a Capture's packets as the LoRa Scanner lists them, a Track's summary, and an Update File checked as an install would check it, without writing anything. Tab shows any file as hex or text. Settings > Storage is gone: usage, Storage Clean-up and Erase are the App's Maintenance, behind a warning. The Storage Warning points there. The Clock sets the system time whatever its source, so files are dated correctly with a GNSS Fix alone (Q137). Console: cp, mv, mkdir, du, cancel; rm takes folders and follows the rules; ls shows dates; Debug Builds get `sd fill`. 424 host tests. Checked on the device: docs/milestones/F1.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
9.7 KiB
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.
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.
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, 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.
- 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 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).