From 2f1befa7f55b92fbeb1b520f44bb052da668799a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Martin?= Date: Tue, 6 Oct 2026 20:38:40 +0200 Subject: [PATCH] Site: the user guide (phase 2): the basics, one page per App, Settings and Updates Eleven pages under /guide/, written from the README, the milestone documents and the Apps' own source: the keys, the Launcher, the Status Bar and the first start; the LoRa Scanner, GNSS, Gemini, IRC, Wi-Fi tools, Notes, Storage and System; Settings (with Wi-Fi) and Updates. Real screenshots where the site has them, a Guide link in the navigation, and the home page points to it. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT --- docs/milestones/W1.md | 8 +++- site/content/guide/_index.md | 13 ++++++ site/content/guide/basics.md | 63 ++++++++++++++++++++++++++++++ site/content/guide/gemini.md | 42 ++++++++++++++++++++ site/content/guide/gnss.md | 30 ++++++++++++++ site/content/guide/irc.md | 51 ++++++++++++++++++++++++ site/content/guide/lora-scanner.md | 35 +++++++++++++++++ site/content/guide/notes.md | 37 ++++++++++++++++++ site/content/guide/settings.md | 42 ++++++++++++++++++++ site/content/guide/storage.md | 47 ++++++++++++++++++++++ site/content/guide/system.md | 20 ++++++++++ site/content/guide/updates.md | 44 +++++++++++++++++++++ site/content/guide/wifi-tools.md | 36 +++++++++++++++++ site/static/css/site.css | 10 +++++ site/templates/base.html | 1 + site/templates/guide-index.html | 24 ++++++++++++ site/templates/guide-page.html | 31 +++++++++++++++ site/templates/index.html | 2 +- 18 files changed, 534 insertions(+), 2 deletions(-) create mode 100644 site/content/guide/_index.md create mode 100644 site/content/guide/basics.md create mode 100644 site/content/guide/gemini.md create mode 100644 site/content/guide/gnss.md create mode 100644 site/content/guide/irc.md create mode 100644 site/content/guide/lora-scanner.md create mode 100644 site/content/guide/notes.md create mode 100644 site/content/guide/settings.md create mode 100644 site/content/guide/storage.md create mode 100644 site/content/guide/system.md create mode 100644 site/content/guide/updates.md create mode 100644 site/content/guide/wifi-tools.md create mode 100644 site/templates/guide-index.html create mode 100644 site/templates/guide-page.html diff --git a/docs/milestones/W1.md b/docs/milestones/W1.md index 31548a7..fad8ee5 100644 --- a/docs/milestones/W1.md +++ b/docs/milestones/W1.md @@ -1,6 +1,6 @@ # W1: Website -**Status:** phase 1 is built and checked in a browser (branch `site`, pull request to follow); the Install page works against the real server once Caddy allows the origin (below). Issue #12. +**Status:** phase 1 (home, Install, Downloads) is live at roro9stack.net; phase 2 (the user guide) is built, in a pull request. Issue #12. **Goal:** a public home for the project at **roro9stack.net**, separate from the blog (stories) and from Gitea (developers): what it is, how to install it, how to use each App, and the docs. @@ -76,6 +76,12 @@ Changed before it ships: - **The Downloads page** lists the last 30 releases with their files, read at build time. - **The wordmark SVGs** from the design carried an embedded C2PA content-credentials block; it is removed from the site's copies. +## As built (phase 2, the user guide) + +- **`/guide/`** is a section of 11 pages, `site/content/guide/`, each with `template` from the section's `page_template` and an order from `weight`: the basics (keys, Launcher, Status Bar, first start, the card), then one page per App (LoRa Scanner, GNSS, Gemini, IRC, Wi-Fi tools, Notes, Storage, System), Settings and Updates. Pages with real screenshots list them in `extra.screens`, looked up in `data/screens.toml`. +- **Facts come from the README, the milestone documents and the Apps' own source** (key handlers, labels, the Status Bar's drawing code), not from memory. Some wording was corrected against the source while writing: the Track folder is `/gnss/tracks`, the reasons a Track won't start, what the Status Bar shows. +- **Not covered:** the mesh messenger (planned), the debug console and Debug Builds beyond a pointer to the README. How-tos and the FAQ are phase 3. + ## Checks (2026-10-06) | Check | Result | diff --git a/site/content/guide/_index.md b/site/content/guide/_index.md new file mode 100644 index 0000000..e4f7468 --- /dev/null +++ b/site/content/guide/_index.md @@ -0,0 +1,13 @@ ++++ +title = "User guide" +description = "How to use each App on the Cardputer: the keys, what the screens show, and what is written to the SD card." +template = "guide-index.html" +sort_by = "weight" +page_template = "guide-page.html" ++++ + +This guide says what the firmware does **today** and nothing else. Start with the basics (the keys, the Launcher, the first start), then read the page of any App. It describes the latest release; the numbers and key names come from the firmware's own source. + +**The mesh messenger is planned, not built.** The LoRa Scanner listens to Meshtastic traffic and shows it, but the device sends nothing yet: that is the next milestone and waits for a second node to test with. + +Something missing or wrong? Write to the [issue tracker](https://git.twis.la/twisla/roro9stack/issues) or to contact@roro9stack.net. diff --git a/site/content/guide/basics.md b/site/content/guide/basics.md new file mode 100644 index 0000000..81355b8 --- /dev/null +++ b/site/content/guide/basics.md @@ -0,0 +1,63 @@ ++++ +title = "The basics" +description = "The keys, the Launcher, the Status Bar and what happens the first time you switch the device on." +weight = 1 +[extra] +tag = "Start here" ++++ + +## The keys + +The Cardputer's keyboard has no arrow keys and no Escape, so the firmware gives a few keys a second job: + +| Key | Does | +|---|---| +| Enter | Opens or confirms the selected item | +| ` | **Back**: one step out of a screen, and out of an App | +| Fn + ` | **Home**: back to the Launcher | +| Fn + ; . , / | The arrows: up, down, left, right | +| ; . , / alone | The same arrows, as long as you are **not** typing text | +| Tab | Switches view in an App that has more than one | +| Del | Deletes backwards when you type | +| opt then an accent, then a letter | Types an accented letter: opt ' e gives é | + +While you type text (a note, an IRC line, a setting), `;` `.` `,` `/` type their own characters and you need Fn for the arrows. The bottom of the screen shows `opt` while a compose is waiting for its letter. + +## The Launcher + +The home screen lists the Apps. Move with the arrows, open one with Enter. Back inside an App returns here. + +## The Status Bar + +A strip at the top of every screen: the name of the App on the left, and on the right, from the edge inwards: + +| Shows | Means | +|---|---| +| the time | The clock, once Wi-Fi or a GNSS fix has set it | +| `[3]` | Unread IRC messages that mention you, or private ones | +| `97%` | The battery (in the warning colour at 15% and under) | +| `SD` | A card is in; the warning colour at 80% full | +| bars and `W` | Wi-Fi connected, with its signal; `W?` is searching; `MON` is the Wi-Fi radio in its monitoring mode, which pauses IRC | +| `REC` | A GNSS Track is being recorded | +| `CAP` | A LoRa capture is being recorded | +| `L` | The radio is listening; it lights up for a moment on each packet. `SW` while a Sweep runs | +| `G` or `G12` | The GNSS receiver is searching (`G`, dim), has a 2D fix (`G`), or has a 3D fix with that many satellites (`G12`) | + +## Toasts + +News from a background service (an IRC mention, a Storage warning, an update that is out) shows as a short message over whatever App is open, and can beep and flash the LED. **Sound & LED** in Settings turns that off. + +## The first start + +On a new device a short Setup asks four things, then never appears again: + +1. **Long name**, up to 39 bytes. +2. **Short name**, up to 4 characters. +3. **Radio region.** Nothing will transmit until you confirm yours. EU868 is the supported region. +4. **Timezone.** + +## The SD card + +Put a microSD card in the Cardputer. Without one the radio, GNSS, Wi-Fi and IRC still work, but nothing can be saved: no notes, IRC logs, Wi-Fi scan logs, GPX tracks, LoRa captures or saved Gemini pages. The [Storage App](/guide/storage/) shows what is on the card. + +The firmware keeps its own folders at the top of the card (`captures`, `gemini`, `gnss`, `irc`, `updates`, `wifi`, plus `notes`). You can use the card in a computer too, but those names are the firmware's. diff --git a/site/content/guide/gemini.md b/site/content/guide/gemini.md new file mode 100644 index 0000000..1df2094 --- /dev/null +++ b/site/content/guide/gemini.md @@ -0,0 +1,42 @@ ++++ +title = "Gemini" +description = "Browse Geminispace: follow links, go back, bookmark pages and keep them on the SD card to read offline." +weight = 4 +[extra] +tag = "Gemini" +screens = ["gemini.png"] ++++ + +[Gemini](https://geminiprotocol.net/) is a small, text-first protocol: pages are plain **gemtext**, served over an encrypted connection, from **capsules** instead of sites. It needs Wi-Fi. + +## Reading + +| Key | Does | +|---|---| +| Tab / Shift+Tab | Picks the next or previous link | +| Enter | Follows the link | +| ` (Back) | Returns to the previous page, at the place where you scrolled to | +| Up and down | Scroll a line | +| Space | Pages down | +| g | Types an address | +| b | Bookmarks the page | +| s | Saves the page to the card | +| S | Saves it with the pages it links to | + +Headings, lists, quotes and preformatted blocks are drawn as gemtext intends, wrapped to the screen. Links to other protocols show their address and are not followed. A page that asks for input (a search, say) shows a prompt, and a password prompt hides what you type. Characters outside the Latin fonts show as `?`. The history keeps the last 20 pages. + +## The start page + +It lists your **bookmarks**, then your **Saved Pages**, then a few starting points: geminiprotocol.net, a search engine and an aggregator. Without a card it shows only the built-in starting points. + +## Certificates: trust on first use + +Most capsules sign their own certificate. The first certificate seen for a host is **remembered**; if it later changes, the page is not shown and you are asked whether to trust the new one, with both fingerprints on screen. Expired or self-signed certificates are fine: only a *change* counts. Client certificates are not supported. + +## Saved Pages + +s keeps the page on the card, with the address it came from and when it was saved, and you can read it with no network. S also saves the pages it links to on the **same capsule**, as text only, up to 30, in the background. On the start page, Saved Pages are listed by capsule, newest first. Inside one, r **refreshes** it and d **deletes** it. A link to another saved page opens the saved copy; any other link fetches online if Wi-Fi is up, or says it is not saved. A file that is not text (a picture, say) is saved to `/gemini/downloads/` instead of being shown. The Storage clean-up never offers Saved Pages for deletion. + +## Big pages and memory + +With a card, every page streams to the card first, so a page larger than the device's memory still arrives whole and is read from the card as you scroll. Without a card, a page is limited to what fits in memory. If there is not enough free memory to open a secure connection, the fetch says so instead of failing silently; stopping IRC frees the most. diff --git a/site/content/guide/gnss.md b/site/content/guide/gnss.md new file mode 100644 index 0000000..71eca5a --- /dev/null +++ b/site/content/guide/gnss.md @@ -0,0 +1,30 @@ ++++ +title = "GNSS" +description = "Where you are and which satellites you can see, from the Cap's receiver, with Tracks saved to the SD card as GPX." +weight = 3 +[extra] +tag = "GNSS" +screens = ["sky.png"] ++++ + +GNSS needs the **Cap LoRa-1262**, an antenna with a view of the sky, and **Settings → GNSS** switched **On**. Otherwise the App says `GNSS is off` (or `paused`, when "Pause GNSS for LoRa" has put the receiver on standby while the radio listens). A first fix outdoors can take a while: the App says how long it has been searching. + +## Position + +The first view shows the fix (`No Fix`, `2D Fix` or `3D Fix`, and how many satellites it uses), then: + +- **Lat** and **Lon**, in decimal degrees or degrees, minutes and seconds (**Settings → Coordinates**); +- the **Locator**, the Maidenhead grid square; +- **Altitude**, **Speed** and the direction you are moving; +- **HDOP**, the horizontal precision: a smaller number is better; +- the **Time**, in UTC. + +Once there is a fix, the device's clock follows it. + +## Sky + +Tab switches between Position and **Sky**: a circle with N, E, S and W, where each satellite is a dot, coloured by constellation, and filled when the receiver uses it. A legend counts, for each constellation (GPS, GLONASS, Galileo, BeiDou), the satellites used and in view. + +## Tracks + +r starts recording a **Track**: the route is saved as a **GPX** file on the SD card, in `/gnss/tracks` (named by date and time), and the Status Bar shows `REC`. Press r again to stop. A Track keeps recording with the App closed. It needs a card and a clock (a fix or Wi-Fi sets it); if it cannot start, the App says why: `GNSS is off`, `No SD card` or `Waiting for the time`. The [Storage App](/guide/storage/) opens a `.gpx` file and shows its points, start, duration and distance. diff --git a/site/content/guide/irc.md b/site/content/guide/irc.md new file mode 100644 index 0000000..4b2db66 --- /dev/null +++ b/site/content/guide/irc.md @@ -0,0 +1,51 @@ ++++ +title = "IRC" +description = "Chat on an IRC server from the keyboard, with a connection that outlives the App and daily logs on the SD card." +weight = 5 +[extra] +tag = "IRC" ++++ + +## Connecting + +The first time, type `/settings` and press Enter. The settings page has: + +- **Server** and **Port**, and **TLS** (on or off). +- **Self-signed:** for a server whose certificate no authority signed. It is *pinned on first use*: the first certificate it sees is remembered, and a different one later is refused. +- **Nick**, **SASL user** and **SASL password**, **NickServ password**: passwords show only as `(set)`. +- **Auto-join:** the channels to join after connecting. +- **Save & reconnect.** + +Opening the IRC App connects, if Wi-Fi is up. The connection belongs to a **background service**: leaving the App does not disconnect, and new messages keep arriving and being logged. It reconnects by itself after a drop, and does not start by itself after a restart. + +## Chatting + +You type at the bottom; Enter sends. A line starting with `/` is a command: + +| Command | Does | +|---|---| +| `/join #channel [key]` (or `/j`) | Joins; the `#` is optional | +| `/part [#channel] [message]` | Leaves | +| `/msg nick text` (or `/query`) | Opens a private chat, sending the text if there is any | +| `/me text` | An action line | +| `/nick newnick` | Changes your nick | +| `/topic [text]` | Shows or sets the channel topic | +| `/names [#channel]` | Lists who is there | +| `/quit [message]` | Disconnects and **stays disconnected** until you type something again | +| `/raw …` (or `/quote`) | Sends a line to the server as it is | +| `/settings` | The settings page | + +Each server, channel and private chat is a **buffer**. Tab moves to the next one, each shows how many messages are unread, and your own lines are in the accent colour. Scroll back with Alt + ; (older) and Alt + . (newer). The up and down arrows (Fn + ; and .) recall lines you sent. + +## Mentions and the unread count + +A message with your nick in it, or any private message, is a **mention**: it shows a Toast over whatever App is open, and counts in the Status Bar's `[n]`. Other traffic only adds to the buffer's unread count. + +## Logs + +Every buffer is logged to the SD card, one file per day, under `/irc`. Logs stop when the card passes 90% full, to keep the rest for captures; nothing is deleted without your asking, in the [Storage App](/guide/storage/)'s Maintenance. + +## Good to know + +- IRC **pauses** while Wi-Fi is monitoring (the Status Bar shows `MON`) and while the device **installs an update**. It reconnects and rejoins its channels afterwards; the App says `paused` in the meantime. +- A secure connection costs memory: IRC's takes about 40 KB of the 107 KB the device has, and an update's download needs about 52 KB more. That is why IRC steps aside for an update, and why the daily update check waits for IRC to be disconnected (see [Updates](/guide/updates/)). diff --git a/site/content/guide/lora-scanner.md b/site/content/guide/lora-scanner.md new file mode 100644 index 0000000..d44626d --- /dev/null +++ b/site/content/guide/lora-scanner.md @@ -0,0 +1,35 @@ ++++ +title = "LoRa Scanner" +description = "Listen to the radio: every packet it hears, a survey of signal strength from 863 to 870 MHz, and captures for Wireshark. It only listens." +weight = 2 +[extra] +tag = "LoRa Scanner" +screens = ["sniffer.png", "sweep.png"] ++++ + +The Scanner uses the **Cap LoRa-1262**. It **never transmits**: it listens and shows. + +## Sniffer + +The first view lists what the radio hears, newest first: the time, the RSSI (signal strength, in dBm) and the SNR (signal over noise, in dB). For a **Meshtastic** packet it also shows the sender and the receiver (the last four hex digits of their numbers) and the number of hops. + +| Key | Does | +|---|---| +| Enter | The details of a packet: the Meshtastic header, which is never encrypted, and a hex dump | +| p | Picks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default) | +| c | Starts or stops a **capture** | +| Tab | Switches to the Sweep | + +The Scanner shows the header and the bytes; it does not decrypt the message itself, which Meshtastic encrypts with the channel's key. + +## Capture + +A capture records packets into a **pcap** file with LoRaTap headers in `/captures/lora/` on the SD card, to open in Wireshark. It keeps recording with the App closed (the Status Bar shows `CAP`); the radio sleeps when the App is not open and no capture is running. Captures are never deleted unless you ask, in the [Storage App](/guide/storage/), which can also show a pcap's packets on the device. + +## Sweep + +Tab switches to the Sweep: the signal strength across **863 to 870 MHz** in 100 kHz steps, drawn as bars with a mark at each peak, and a waterfall under them. The frequency the Sniffer listens on is marked. The Sniffer is paused during a Sweep and picks up where it was. The Status Bar shows `SW`. + +## The GNSS receiver raises the noise + +The GNSS receiver on the same Cap makes the radio's noise floor about **8 dB** worse while it runs. **Settings → Pause GNSS for LoRa** (off by default) puts the receiver on standby while the radio listens, except while a Track is being recorded. diff --git a/site/content/guide/notes.md b/site/content/guide/notes.md new file mode 100644 index 0000000..fd91e2c --- /dev/null +++ b/site/content/guide/notes.md @@ -0,0 +1,37 @@ ++++ +title = "Notes" +description = "Plain text notes on the SD card, with no save key: the editor saves for you, and a power cut never costs the note." +weight = 7 +[extra] +tag = "Notes" +screens = ["notes.png"] ++++ + +Notes are plain text files in `/notes` on the SD card. They are ordinary `.txt` files: you can read them on a computer too. + +## The list + +Each note shows its first line and its date, newest first. s switches to sorting by file name. + +| Key | Does | +|---|---| +| n | Starts a new note | +| Enter | Opens the note | +| r | Renames its file | +| d | Deletes it, after asking | + +## The editor + +Type. Enter starts a line and Del deletes backwards. Fn with the arrow keys moves the cursor through the wrapped text, Ctrl+A and Ctrl+E go to the start and the end of the line, Tab types two spaces, and the compose key gives accents as everywhere. + +**There is no save key.** The note is written five seconds after your last key, when you press Back, when you leave the App, when the screen turns off and before the device powers off. The top line says `typing` or `saved`. + +Each save writes a temporary file and then puts it in the note's place, so a power cut costs a few seconds of typing and never the note. If a save was cut short, opening the note offers its copy back. + +## Names + +A new note has no file until you type something. The file is then named after its first line (`shopping-list.txt`), or `note--