diff --git a/CONTEXT.md b/CONTEXT.md index 20944ea..195a06d 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -110,6 +110,18 @@ The share of airtime the Region allows this device to transmit. When it's used u 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 + +**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 @@ -188,6 +200,8 @@ _Avoid_: telnet, remote shell, Debug Build (there is one firmware) - 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 diff --git a/README.md b/README.md index 0404f01..2f4134d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,23 @@ [![CI](https://git.twis.la/twisla/roro9stack/actions/workflows/ci.yml/badge.svg?branch=main)](https://git.twis.la/twisla/roro9stack/actions?workflow=ci.yml) [![Coverage of lib/ by the host tests](https://git.twis.la/twisla/roro9stack/raw/branch/badges/coverage.svg)](#build-and-test-local-ci) [![Latest release](https://git.twis.la/twisla/roro9stack/raw/branch/badges/release.svg)](https://git.twis.la/twisla/roro9stack/releases/latest) -A multi-app firmware for the **M5Stack Cardputer ADV** with the **Cap LoRa-1262**. It's a Meshtastic-compatible mesh messenger, plus Wi-Fi tools, IRC, GNSS and more. Licensed GPL-3.0. +A multi-app firmware for the **M5Stack Cardputer ADV** with the **Cap LoRa-1262**. Licensed GPL-3.0. The user guide, the how-tos and every release are at **[roro9stack.net](https://roro9stack.net)**. + +What it does today: + +- **LoRa Scanner:** every packet it hears, with the Meshtastic header read; a spectrum Sweep; captures for Wireshark. It listens and never transmits: the mesh messenger is the next milestone. +- **GNSS:** position, sky view, tracks as GPX. +- **Gemini:** a browser, with bookmarks and pages saved for offline. +- **IRC:** over TLS, with logs on the card. +- **Wi-Fi Tools:** the networks around, sorted, filtered, logged. +- **Notes:** plain text files of any size, saved by themselves. +- **Storage:** the SD card: copy, move, rename, delete; viewers for text, hex, pictures (PNG, JPEG, BMP, GIF), tracks, captures and update files; **sharing with a phone's browser**. +- **Shell:** the firmware's commands on the device itself, with completion. +- **System:** load, tasks, memory, network, battery, live. +- **VPN:** a WireGuard tunnel. +- **Everywhere:** Fn+h lists the keys of the screen you are on; Fn+p takes a screenshot. +- **Updates:** signed, from the project's server, the card or a PC, with a rollback if the new firmware fails. +- **Debug Console:** the device's console over Wi-Fi, off until switched on. - Domain language: [CONTEXT.md](CONTEXT.md) - Decisions: [docs/adr/](docs/adr/) @@ -10,6 +26,8 @@ A multi-app firmware for the **M5Stack Cardputer ADV** with the **Cap LoRa-1262* ## On the device: one key +**Fn+p, on any screen, saves a screenshot** to `/screenshots` on the card (not on the page that shows the Debug Console's token; issue #83). + **Fn+h, on any screen, lists the keys that work there** (`?` does the same outside a text field). No screen names its keys itself (docs/milestones/U1.md). Every screen's keys are one table in `lib/core/src/app_keys.h`: the help panel shows the table of the state an App is in, and the website's key tables are generated from the same file. ## Requirements diff --git a/docs/milestones/F1.md b/docs/milestones/F1.md index d4dd4d6..471efe6 100644 --- a/docs/milestones/F1.md +++ b/docs/milestones/F1.md @@ -1,6 +1,6 @@ # F1 — Files and Notes -**Status:** in progress. The Storage App (issue #3) shipped as **v0.9.0** on 2026-10-06. Notes (#19) shipped as **v0.10.0** the same day. The card as a USB drive (#1) comes after. +**Status:** in progress. Shipped: the Storage App (issue #3, **v0.9.0**), Notes (#19, **v0.10.0**), notes of any size (#47, **v0.15.0**), pictures in the Storage App (#45, **v0.16.0**), sharing the card with a browser (#88, **v0.18.0**). Not started: the card as a USB drive (#1), selecting several items (#41), finding files by name (#42), opening a `.gmi` in Gemini (#43), a table view for `.csv` (#44), search, undo and copy-paste in Notes (#48, #49, #50). **Goal:** get at what's on the SD card from the device itself: browse it, look inside the files the firmware writes, copy, move, rename and delete, and keep notes. A side milestone, like G1 and S1; Files and Notes were M3's original second half (Q30, Q89). diff --git a/docs/milestones/N1.md b/docs/milestones/N1.md index 6b6c614..0609475 100644 --- a/docs/milestones/N1.md +++ b/docs/milestones/N1.md @@ -1,6 +1,6 @@ # N1 — Network tools -**Status:** in progress. The WireGuard tunnel (issue #8) is built. SSH (#2) is not started. +**Status:** in progress. The WireGuard tunnel (issue #8) shipped as **v0.19.0**. SSH (#2) is not started. **Goal:** reach things from the device that aren't on the Wi-Fi it happens to be on, and keep its traffic private on a network that isn't yours. diff --git a/docs/milestones/R1.md b/docs/milestones/R1.md index 611192d..8f54df8 100644 --- a/docs/milestones/R1.md +++ b/docs/milestones/R1.md @@ -1,6 +1,6 @@ # R1 — Releases -**Status:** in progress. CI and signed releases on Gitea (issue #5) are in place since 2026-10-06: every tag from v0.1.0 to v0.10.0 has its release. Updates from Gitea (issue #6) is built and checked on the device, on branch `gitea-updates`, not merged yet. The Issues App (#4) comes after. +**Status:** in progress. Shipped: CI and signed releases on Gitea (issue #5), a release for every tag; updates from Gitea (#6, **v0.11.0**); one firmware with the Debug Console in it (#68, **v0.12.0**); CI in about a minute (#74, **v0.13.0**). Not started: the Issues App (#4), automatic installs (#52), release channels (#53), resuming a download (#54). **Goal:** a tag is a release, built the same way every time and published where a device can find it. diff --git a/docs/milestones/S1.md b/docs/milestones/S1.md index 66e5ea3..82c6096 100644 --- a/docs/milestones/S1.md +++ b/docs/milestones/S1.md @@ -1,6 +1,6 @@ # S1 — System basics -**Status:** the three planned items are done: the SD driver fix in v0.6.1 (issue #21, ADR 0007), fixed IPv4 settings in v0.7.0 (issue #7), the System App in v0.8.0 (issue #11). v0.8.1 adds the resting main loop (issue #40) and the GNSS pause for the radio's noise (issue #20, still open for the 11 dB that remain). Still open in the milestone: #39, following the SD driver upstream. +**Status:** the three planned items are done: the SD driver fix in v0.6.1 (issue #21, ADR 0007), fixed IPv4 settings in v0.7.0 (issue #7), the System App in v0.8.0 (issue #11). v0.8.1 adds the resting main loop (issue #40) and the GNSS pause for the radio's noise (issue #20, still open for the 11 dB that remain). Still open in the milestone: #39, following the SD driver upstream. The **Shell** (issue #67) shipped as **v0.14.0**; the Shell in Safe Mode (#77) is not started. **Goal:** the device works on any network, the card can be trusted, and you can see what the system is doing. A side milestone, like G1. diff --git a/docs/milestones/U1.md b/docs/milestones/U1.md index b24bbae..2ee23af 100644 --- a/docs/milestones/U1.md +++ b/docs/milestones/U1.md @@ -1,6 +1,6 @@ # U1 — Look and feel -**Status:** in progress. The help key (issue #69) is merged; the website's key tables generated from the same lists (issue #72) are in a pull request. Screen recording (#17) and the rest of the milestone are not started. +**Status:** in progress. Shipped: the help key (issue #69) and the key tables the website shares with it (#72), both in **v0.13.0**; the screenshot key (#83, **v0.17.0**). Not started: screen recording (#17), a Launcher of tiles (#9), themes (#10). **Goal:** the interface is consistent and uncrowded: the same thing is done the same way on every screen, and the 135 pixels of height go to content. diff --git a/docs/milestones/W1.md b/docs/milestones/W1.md index 6ff169f..3a3ef7c 100644 --- a/docs/milestones/W1.md +++ b/docs/milestones/W1.md @@ -1,6 +1,6 @@ # W1: Website -**Status:** phases 1 to 3 (home, Install and Downloads; the user guide; how-tos and the FAQ) and the devlog are live at roro9stack.net; phase 4 (the developer docs) is in a pull request. Issue #12. +**Status:** live at roro9stack.net: the home, Install and Downloads pages, the user guide, the how-tos and the FAQ, the developer docs and the devlog (issue #12), published by CI since issue #79, with a search since issue #60. Not started: a Gemini mirror (#57), a French translation (#58), the docs of each version (#59). **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. diff --git a/site/content/dev/debug/files-and-screens.md b/site/content/dev/debug/files-and-screens.md index 29d2bb0..484e2cd 100644 --- a/site/content/dev/debug/files-and-screens.md +++ b/site/content/dev/debug/files-and-screens.md @@ -8,6 +8,8 @@ tag = "Console" These are the **binary commands**: a text header line, then raw bytes. The console task answers them itself, so they keep working when the main loop is stuck. `scripts/rdbg.py` handles each one on the PC side; the protocol is given too, for your own tools. +**Without a PC,** the device does both by itself now: Fn + p saves a screenshot to the card ([how-to](/howto/screenshot/)), and w in the Storage App serves the card to a browser ([how-to](/howto/phone-files/)). What follows is the scripted way, with checksums. + ## `get`: card to PC ```sh diff --git a/site/content/dev/milestones/f1.md b/site/content/dev/milestones/f1.md index 47891eb..573bc33 100644 --- a/site/content/dev/milestones/f1.md +++ b/site/content/dev/milestones/f1.md @@ -8,7 +8,7 @@ docs = true source = "docs/milestones/F1.md" tag = "F1" +++ -**Status:** in progress. The Storage App (issue #3) shipped as **v0.9.0** on 2026-10-06. Notes (#19) shipped as **v0.10.0** the same day. The card as a USB drive (#1) comes after. +**Status:** in progress. Shipped: the Storage App (issue #3, **v0.9.0**), Notes (#19, **v0.10.0**), notes of any size (#47, **v0.15.0**), pictures in the Storage App (#45, **v0.16.0**), sharing the card with a browser (#88, **v0.18.0**). Not started: the card as a USB drive (#1), selecting several items (#41), finding files by name (#42), opening a `.gmi` in Gemini (#43), a table view for `.csv` (#44), search, undo and copy-paste in Notes (#48, #49, #50). **Goal:** get at what's on the SD card from the device itself: browse it, look inside the files the firmware writes, copy, move, rename and delete, and keep notes. A side milestone, like G1 and S1; Files and Notes were M3's original second half (Q30, Q89). diff --git a/site/content/dev/milestones/n1.md b/site/content/dev/milestones/n1.md index 2071154..27bcb2a 100644 --- a/site/content/dev/milestones/n1.md +++ b/site/content/dev/milestones/n1.md @@ -8,7 +8,7 @@ docs = true source = "docs/milestones/N1.md" tag = "N1" +++ -**Status:** in progress. The WireGuard tunnel (issue #8) is built. SSH (#2) is not started. +**Status:** in progress. The WireGuard tunnel (issue #8) shipped as **v0.19.0**. SSH (#2) is not started. **Goal:** reach things from the device that aren't on the Wi-Fi it happens to be on, and keep its traffic private on a network that isn't yours. diff --git a/site/content/dev/milestones/r1.md b/site/content/dev/milestones/r1.md index 9643067..fad2694 100644 --- a/site/content/dev/milestones/r1.md +++ b/site/content/dev/milestones/r1.md @@ -8,7 +8,7 @@ docs = true source = "docs/milestones/R1.md" tag = "R1" +++ -**Status:** in progress. CI and signed releases on Gitea (issue #5) are in place since 2026-10-06: every tag from v0.1.0 to v0.10.0 has its release. Updates from Gitea (issue #6) is built and checked on the device, on branch `gitea-updates`, not merged yet. The Issues App (#4) comes after. +**Status:** in progress. Shipped: CI and signed releases on Gitea (issue #5), a release for every tag; updates from Gitea (#6, **v0.11.0**); one firmware with the Debug Console in it (#68, **v0.12.0**); CI in about a minute (#74, **v0.13.0**). Not started: the Issues App (#4), automatic installs (#52), release channels (#53), resuming a download (#54). **Goal:** a tag is a release, built the same way every time and published where a device can find it. diff --git a/site/content/dev/milestones/s1.md b/site/content/dev/milestones/s1.md index 968f25e..a3ba9b8 100644 --- a/site/content/dev/milestones/s1.md +++ b/site/content/dev/milestones/s1.md @@ -8,7 +8,7 @@ docs = true source = "docs/milestones/S1.md" tag = "S1" +++ -**Status:** the three planned items are done: the SD driver fix in v0.6.1 (issue #21, ADR 0007), fixed IPv4 settings in v0.7.0 (issue #7), the System App in v0.8.0 (issue #11). v0.8.1 adds the resting main loop (issue #40) and the GNSS pause for the radio's noise (issue #20, still open for the 11 dB that remain). Still open in the milestone: #39, following the SD driver upstream. +**Status:** the three planned items are done: the SD driver fix in v0.6.1 (issue #21, ADR 0007), fixed IPv4 settings in v0.7.0 (issue #7), the System App in v0.8.0 (issue #11). v0.8.1 adds the resting main loop (issue #40) and the GNSS pause for the radio's noise (issue #20, still open for the 11 dB that remain). Still open in the milestone: #39, following the SD driver upstream. The **Shell** (issue #67) shipped as **v0.14.0**; the Shell in Safe Mode (#77) is not started. **Goal:** the device works on any network, the card can be trusted, and you can see what the system is doing. A side milestone, like G1. diff --git a/site/content/dev/milestones/u1.md b/site/content/dev/milestones/u1.md index bbe2f95..972878b 100644 --- a/site/content/dev/milestones/u1.md +++ b/site/content/dev/milestones/u1.md @@ -8,7 +8,7 @@ docs = true source = "docs/milestones/U1.md" tag = "U1" +++ -**Status:** in progress. The help key (issue #69) is merged; the website's key tables generated from the same lists (issue #72) are in a pull request. Screen recording (#17) and the rest of the milestone are not started. +**Status:** in progress. Shipped: the help key (issue #69) and the key tables the website shares with it (#72), both in **v0.13.0**; the screenshot key (#83, **v0.17.0**). Not started: screen recording (#17), a Launcher of tiles (#9), themes (#10). **Goal:** the interface is consistent and uncrowded: the same thing is done the same way on every screen, and the 135 pixels of height go to content. diff --git a/site/content/dev/milestones/w1.md b/site/content/dev/milestones/w1.md index 89a92b0..960fb84 100644 --- a/site/content/dev/milestones/w1.md +++ b/site/content/dev/milestones/w1.md @@ -8,7 +8,7 @@ docs = true source = "docs/milestones/W1.md" tag = "W1" +++ -**Status:** phases 1 to 3 (home, Install and Downloads; the user guide; how-tos and the FAQ) and the devlog are live at roro9stack.net; phase 4 (the developer docs) is in a pull request. Issue #12. +**Status:** live at roro9stack.net: the home, Install and Downloads pages, the user guide, the how-tos and the FAQ, the developer docs and the devlog (issue #12), published by CI since issue #79, with a search since issue #60. Not started: a Gemini mirror (#57), a French translation (#58), the docs of each version (#59). **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. diff --git a/site/content/faq.md b/site/content/faq.md index 61bfadb..b01cd74 100644 --- a/site/content/faq.md +++ b/site/content/faq.md @@ -53,6 +53,8 @@ Yes: it is [open source](https://git.twis.la/twisla/roro9stack) (GPL-3.0). The d **The firmware contacts the project's server once a day,** to see whether a new release exists: **Settings → Check for updates**, on by default, only when Wi-Fi is up and the clock is set. It installs nothing by itself, and you can switch it off. Besides that, the device talks to what you ask it to: the IRC server and Gemini capsules you open, DNS servers (9.9.9.9 and 1.1.1.1 by default) and time servers (pool.ntp.org and time.cloudflare.com by default), all of which you can change. There is no account, no analytics and no telemetry. +**It listens on the network only for what you switched on:** the port that receives signed firmware updates, always; the Debug Console, the card shared with a browser and the VPN, only while you have them on. + **This website** sets no cookies and has no analytics, loads nothing from other sites, and its server logs keep only a masked part of visitors' addresses. The Install page asks the project's own server for the latest release. ## Why does IRC disconnect when I update, or when I open a Gemini page? @@ -67,6 +69,10 @@ Yes, WireGuard: one tunnel to one server, set up by copying the client's `.conf` In the Storage App, press w: the device serves a small web page to any browser on the same Wi-Fi. Scan the QR code it shows, type the code, and upload or download. Nothing to install. See [From a phone](/guide/storage/#from-a-phone). +## How do I take a screenshot? + +Fn + p, on any screen. The picture goes to `/screenshots` on the SD card. See [Take a screenshot](/howto/screenshot/). + ## Do I need an SD card? For the radio, GNSS position, Wi-Fi tools, IRC chat and Gemini browsing, no. For anything that is *kept*, yes: notes, IRC logs, Wi-Fi scan logs, GNSS Tracks, LoRa captures, saved Gemini pages and update files. See [Find your files on the SD card](/howto/sd-files/). diff --git a/site/content/guide/_index.md b/site/content/guide/_index.md index 99ce495..2fe89a2 100644 --- a/site/content/guide/_index.md +++ b/site/content/guide/_index.md @@ -10,6 +10,8 @@ This guide says what the firmware does **today** and nothing else. Start with th **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. +**Three things work on every screen:** Fn + h for the keys, Fn + p for a screenshot, and Fn + ` to go back to the Launcher. + Looking for a recipe or a quick answer? There are [how-tos](/howto/) and a [FAQ](/faq/). 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 index b0cb152..0ab5db3 100644 --- a/site/content/guide/basics.md +++ b/site/content/guide/basics.md @@ -4,6 +4,7 @@ description = "The keys, the Launcher, the Status Bar and what happens the first weight = 1 [extra] tag = "Start here" +screens = ["help.png"] +++ ## One key to remember @@ -48,6 +49,7 @@ A strip at the top of every screen: the name of the App on the left, and on the | `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 | +| `VPN` | The [WireGuard tunnel](/guide/vpn/) is wanted; brighter once the server has answered | | `DBG` | The Debug Console is switched on (Settings → Debug Console); brighter while a PC is connected to it | | `REC` | A GNSS Track is being recorded | | `CAP` | A LoRa capture is being recorded | diff --git a/site/content/guide/settings.md b/site/content/guide/settings.md index fd0e2ff..88605ed 100644 --- a/site/content/guide/settings.md +++ b/site/content/guide/settings.md @@ -1,6 +1,6 @@ +++ title = "Settings" -description = "The device's names, region, screen, sound, GNSS and Wi-Fi, and where firmware updates are found." +description = "The device's names, region, screen, sound, GNSS, Wi-Fi and VPN, and where firmware updates are found." weight = 11 [extra] tag = "Settings" @@ -22,6 +22,7 @@ Move with the arrows. On a toggle, a choice or a slider, left and right change t | **Wi-Fi** | The page below | | **Check for updates** | Once a day, see [Updates](/guide/updates/) | | **Firmware** | The page described in [Updates](/guide/updates/) | +| **VPN** | A WireGuard tunnel: its switch, "Start with Wi-Fi", and importing its configuration from the card. See [VPN](/guide/vpn/) | | **Debug Console** | Off unless you switch it on. It lets a PC on the same network read the device's console and drive it, with a token shown on this page: see [the developer docs](/dev/debug/switch-it-on/). Leave it off if that means nothing to you | | **About** | The firmware version, the node number, battery, memory, uptime, clock and licence | @@ -46,4 +47,4 @@ Two DNS servers (9.9.9.9 and 1.1.1.1 by default), used on Fixed networks, or on What Fn + h shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones. -{{ keys(scopes=["settings", "settings-choice", "wifi", "wifi-servers", "wifi-network", "wifi-status", "wifi-scan", "wifi-name", "debug-console"]) }} +{{ keys(scopes=["settings", "settings-choice", "wifi", "wifi-servers", "wifi-network", "wifi-status", "wifi-scan", "wifi-name", "vpn", "debug-console"]) }} diff --git a/site/content/guide/shell.md b/site/content/guide/shell.md index 5198552..d365416 100644 --- a/site/content/guide/shell.md +++ b/site/content/guide/shell.md @@ -4,6 +4,7 @@ description = "The firmware's own commands, typed on the device: look at its sta weight = 9 [extra] tag = "Shell" +screens = ["shell.png"] +++ The firmware has a set of **commands**, made for working on it from a PC. The Shell runs them **on the device itself**: no computer, no cable, no Wi-Fi. It is the tool for the day something is wrong and you are nowhere near a desk. diff --git a/site/content/guide/storage.md b/site/content/guide/storage.md index 743a0e1..9b8dcdb 100644 --- a/site/content/guide/storage.md +++ b/site/content/guide/storage.md @@ -4,7 +4,7 @@ description = "Browse the SD card: copy, move, rename and delete with a clipboar weight = 8 [extra] tag = "Storage" -screens = ["storage.png"] +screens = ["storage.png", "picture.png", "share.png"] +++ Storage shows what is on the SD card: each folder's entries with their size and date, folders first. Enter opens a folder, Back goes up, and s sorts by name, date or size. A folder with more than 256 entries shows the first 256 by name, and says so. diff --git a/site/content/guide/vpn.md b/site/content/guide/vpn.md index 43c1039..b7f44dd 100644 --- a/site/content/guide/vpn.md +++ b/site/content/guide/vpn.md @@ -4,6 +4,7 @@ description = "A WireGuard tunnel: reach your own network from any Wi-Fi, or sen weight = 12 [extra] tag = "WireGuard" +screens = ["vpn.png"] +++ The Cardputer can join a **WireGuard** network over whatever Wi-Fi it is on. Two uses: reaching your own machines from anywhere (an IRC bouncer, the device's own [Debug Console](/dev/debug/)), and keeping its traffic private on a hotel or café network. diff --git a/site/content/howto/_index.md b/site/content/howto/_index.md index cd50ba9..6fa9caa 100644 --- a/site/content/howto/_index.md +++ b/site/content/howto/_index.md @@ -1,6 +1,6 @@ +++ title = "How-tos" -description = "Short recipes for things you will want to do: put a file on the card, record a track, capture radio packets, and what to try when something does not work." +description = "Short recipes for things you will want to do: move files with your phone, set up the VPN, take a screenshot, record a track, capture radio packets, and what to try when something does not work." template = "guide-index.html" page_template = "guide-page.html" sort_by = "weight" diff --git a/site/content/howto/not-enough-memory.md b/site/content/howto/not-enough-memory.md index 5b5b2c6..0daa27d 100644 --- a/site/content/howto/not-enough-memory.md +++ b/site/content/howto/not-enough-memory.md @@ -20,6 +20,18 @@ Opening a Gemini page fails with *not enough memory: stop IRC or retry*. Or an u The [System App](/guide/system/)'s **Memory** view shows free memory, the lowest since the device started, and the largest free block, drawn against the three memory floors (55, 40 and 20 KB). Watch it fall when a connection opens, and recover when it closes. +## What the other things cost + +Small next to a secure connection, but they add up when memory is already short: + +| | While it is in use | +|---|---| +| A note open in the editor, whatever its size | 17 KB | +| Sharing the card with a browser | 13 KB | +| The Shell | 7 KB | +| The VPN tunnel | under 2 KB | +| Showing a PNG | one free block of 32 KB, while it is decoded | + ## Why it happens The Cardputer's chip has no extra memory (no PSRAM). A secure (TLS) connection costs about **52 KB** at its peak, and IRC's own connection holds about 40 KB of the 107 KB there is. A second secure connection on top does not fit, so the firmware refuses it early instead of crashing. This is also why IRC steps aside during an update, and why the daily update check waits until IRC is not connected: see [Updates](/guide/updates/). diff --git a/site/content/howto/phone-files.md b/site/content/howto/phone-files.md new file mode 100644 index 0000000..8445055 --- /dev/null +++ b/site/content/howto/phone-files.md @@ -0,0 +1,30 @@ ++++ +title = "Move files with your phone" +description = "Open the SD card in your phone's browser, over Wi-Fi: download what the device wrote, upload what it needs. Nothing to install." +weight = 9 +[extra] +tag = "SD card" ++++ + +The phone and the Cardputer must be on the **same Wi-Fi network**. + +1. On the Cardputer, open **Storage** and press w. You should see a QR code, an address and a six-digit code. +2. On the phone, **scan the QR code** with the camera and open the link. The page opens on the card's folders. (Without a camera: type the address in a browser, then the code.) +3. **To download:** tap a folder to go in, tap a file to download it. +4. **To upload:** go to the folder you want, tap **Upload files** and pick one or several. A bar shows the progress; if a file with that name is there already, the page asks before replacing it. +5. **New folder** and **Delete** do what they say. A folder must be empty to be deleted. +6. On the Cardputer, press Back. Sharing stops, and the code is no longer good. + +## What to expect + +- About **200 KB a second**: a 3 MB photo takes a quarter of a minute. +- **One thing at a time.** While a big file moves, the page waits. +- The device's screen shows how much has gone in and out, and the last thing that was asked. + +## Good to know + +- **It is not encrypted.** Use it on a network you trust, or [through the VPN](/guide/vpn/). +- Five wrong codes close it for a minute. +- It works from a computer's browser too. + +More in [Storage: From a phone](/guide/storage/#from-a-phone). diff --git a/site/content/howto/screenshot.md b/site/content/howto/screenshot.md new file mode 100644 index 0000000..7dbc76a --- /dev/null +++ b/site/content/howto/screenshot.md @@ -0,0 +1,18 @@ ++++ +title = "Take a screenshot" +description = "Save what the screen shows as a picture, look at it on the device, and get it onto your phone." +weight = 11 +[extra] +tag = "Screen" ++++ + +1. On any screen, press Fn + p. A [Toast](/guide/basics/#toasts) says "Screenshot saved in /screenshots". The Toast itself is never in the picture; a dialog or the help panel that is open is. +2. **To look at it on the device:** open **Storage**, go into `screenshots` and press Enter on the file. Enter again shows it at its own size. +3. **To get it out:** in Storage press w and [open the card in your phone's browser](/howto/phone-files/); the pictures are in `screenshots`. + +## Good to know + +- It needs an SD card. +- The files are PNGs of 240 by 135 pixels, named by date and time. +- **It refuses on Settings → Debug Console**, the page that shows the console's token: a picture of it would be a copy of the token. +- From the [Shell](/guide/shell/), `screenshot 5` takes the picture five seconds later, for a screen you can't press keys on. diff --git a/site/content/howto/sd-files.md b/site/content/howto/sd-files.md index a15bedb..dc5826d 100644 --- a/site/content/howto/sd-files.md +++ b/site/content/howto/sd-files.md @@ -6,7 +6,7 @@ weight = 2 tag = "SD card" +++ -Everything the firmware writes goes in a folder at the top of the card. Switch the Cardputer off, take the card out and read it in a computer; or look at the same folders in the [Storage App](/guide/storage/). +Everything the firmware writes goes in a folder at the top of the card. To get at it: look at the folders in the [Storage App](/guide/storage/); or [open the card in your phone's browser](/howto/phone-files/), with nothing to install; or switch the Cardputer off, take the card out and read it in a computer. | What | Where | Kind of file | |---|---|---| @@ -19,7 +19,8 @@ Everything the firmware writes goes in a folder at the top of the card. Switch t | Gemini bookmarks | `/gemini/bookmarks.gmi` | gemtext | | Files saved from Gemini that are not text | `/gemini/downloads` | whatever they were | | Update files | `/updates` | `.ota` | -| Screenshots (the Shell's `screenshot`) | `/screenshots` | `.png`, named by date and time | +| [Screenshots](/howto/screenshot/) (Fn + p) | `/screenshots` | `.png`, named by date and time | +| A VPN configuration waiting to be imported | `/vpn/wg0.conf` | you put it there; delete it once imported | ## Rules worth knowing diff --git a/site/content/howto/vpn.md b/site/content/howto/vpn.md new file mode 100644 index 0000000..1a788a6 --- /dev/null +++ b/site/content/howto/vpn.md @@ -0,0 +1,36 @@ ++++ +title = "Set up the VPN" +description = "Put a WireGuard configuration on the device with your phone, import it, and check that the tunnel is up." +weight = 10 +[extra] +tag = "VPN" ++++ + +You need a WireGuard server, and a **client configuration** made on it for the Cardputer, as you would make one for a phone: a `.conf` file. + +1. Get the `.conf` onto the phone (or a computer on the same Wi-Fi), and name it **`wg0.conf`**. +2. On the Cardputer, open **Storage** and press w; open the page on the phone ([Move files with your phone](/howto/phone-files/)). +3. In the page, tap **New folder**, name it `vpn`, go into it, and **upload `wg0.conf`**. +4. On the Cardputer, press Back to stop sharing. +5. Open **Settings → VPN → Import /vpn/wg0.conf**. You should see "Imported", and a question: **delete the file**. Say yes: the configuration is now in the device, and the file still holds the private key in clear. +6. Switch **VPN** to On. `VPN` appears in the Status Bar, and turns bright once the server has answered, usually within seconds. The page says "It is up". +7. To have it start by itself, switch on **Start with Wi-Fi**. + +## Check it + +From another machine on the VPN, ping the Cardputer's tunnel address (the `Address` line of the file). Or on the device, in the [Shell](/guide/shell/): `vpn status`. + +## If it stays dim + +| The page says | Try | +|---|---| +| waiting for Wi-Fi | Connect to a network first | +| waiting for the clock | Give it a moment after Wi-Fi connects: the time comes from the network | +| looking up the server | The server's name doesn't resolve from this network | +| no answer yet | The server's address or port, a firewall on the way, or the keys: check the server's side has this client's public key | + +## What goes through it + +Everything, if the file says `AllowedIPs = 0.0.0.0/0`; otherwise only the VPN's own subnet. To reach your home network behind the server, you need the first. See [VPN](/guide/vpn/#what-goes-through-it). + +**The upload in step 3 is not encrypted,** and the file holds a private key: do it on a network you trust, with a key made for this device. diff --git a/site/data/apps.toml b/site/data/apps.toml index f8175e3..9400ddd 100644 --- a/site/data/apps.toml +++ b/site/data/apps.toml @@ -45,7 +45,7 @@ icon = 3 num = "06" tag = "Notes" title = "Write it down" -text = "Keep plain text notes on the SD card. There is no save key: the editor writes five seconds after you stop typing, through a temporary file, so a power cut never costs the note." +text = "Keep plain text notes on the SD card, of any size: a megabyte opens as fast as a line. There is no save key: the editor writes five seconds after you stop typing, so a power cut never costs the note." fact = "Plain .txt files in /notes" icon = 6 @@ -53,7 +53,7 @@ icon = 6 num = "07" tag = "Storage" title = "Manage the SD card" -text = "Browse, copy, cut, rename and delete with a clipboard. Copies run in the background and Back cancels one. Opens text, hex, captures, tracks and update files." +text = "Browse, copy, cut, rename and delete with a clipboard. Opens text, pictures, hex, captures, tracks and update files. Press w and the card is a web page in your phone's browser: upload and download with nothing to install." fact = "Checks every copy by size" icon = 8 diff --git a/site/data/screens.toml b/site/data/screens.toml index 8a20f86..af60b2c 100644 --- a/site/data/screens.toml +++ b/site/data/screens.toml @@ -38,3 +38,28 @@ caption = "Storage" file = "update.png" alt = "The full-screen progress of a firmware update: Receiving v0.10.0, a bar at 28 percent" caption = "A firmware update" + +[[screen]] +file = "shell.png" +alt = "The Shell after rm -f /gt2/*: the command in blue, then rm: 5 match /gt2/* and five lines rm: ok 1 files, above an empty input line" +caption = "Shell" + +[[screen]] +file = "picture.png" +alt = "A picture open in the Storage App: colour bars, grey and colour gradients and a yellow ellipse, shrunk to fit the screen and dithered to its 256 colours" +caption = "Storage, a picture" + +[[screen]] +file = "share.png" +alt = "The Storage App's Share screen: a QR code, the address 172.16.42.25, the code 825 132, Nothing asked yet, Not encrypted, and the key that stops sharing" +caption = "Storage, sharing with a browser" + +[[screen]] +file = "vpn.png" +alt = "Settings, VPN: VPN On, Start with Wi-Fi On, Import /vpn/wg0.conf, Forget it; then It is up, heard 66 s ago, the server's address, and This device 10.9.0.2, through it everything. VPN shows in the Status Bar" +caption = "Settings, VPN" + +[[screen]] +file = "help.png" +alt = "The help panel over the Launcher: Keys: Launcher, up and down, Enter opens the App, then Everywhere: back, home, the arrows, Fn h for these keys and Fn p for a screenshot" +caption = "The help panel (Fn+h)" diff --git a/site/static/screens/help.png b/site/static/screens/help.png new file mode 100644 index 0000000..f483079 Binary files /dev/null and b/site/static/screens/help.png differ diff --git a/site/static/screens/picture.png b/site/static/screens/picture.png new file mode 100644 index 0000000..cd49e14 Binary files /dev/null and b/site/static/screens/picture.png differ diff --git a/site/static/screens/share.png b/site/static/screens/share.png new file mode 100644 index 0000000..4bd43f3 Binary files /dev/null and b/site/static/screens/share.png differ diff --git a/site/static/screens/shell.png b/site/static/screens/shell.png new file mode 100644 index 0000000..efee2f8 Binary files /dev/null and b/site/static/screens/shell.png differ diff --git a/site/static/screens/vpn.png b/site/static/screens/vpn.png new file mode 100644 index 0000000..46e57ea Binary files /dev/null and b/site/static/screens/vpn.png differ diff --git a/site/templates/index.html b/site/templates/index.html index d807487..4b6d6be 100644 --- a/site/templates/index.html +++ b/site/templates/index.html @@ -68,7 +68,7 @@ {% endfor %} -

Plus a Shell that runs the firmware's commands on the device, and Settings, with its Wi-Fi and Firmware pages. Every App has a page in the user guide.

+

Plus a Shell that runs the firmware's commands on the device, a WireGuard VPN, a screenshot key that works on every screen, and Settings, with its Wi-Fi and Firmware pages. Every App has a page in the user guide.