Public Access
Keys: one table file for the device's help panel and the website's key tables (#72)
Every screen's keys are constant tables in lib/core/src/app_keys.h (52 of them, each under an `// id: Title` comment). An App's help() picks the table of the state it is in. site/tools/gen_dev_docs.py reads the same file and writes site/data/keys.toml; the `keys` shortcode shows a screen's tables on its guide page, and /guide/keys/ shows all of them. The Site job fails when the data file is out of date or a page asks for a table that doesn't exist, and now also runs when app_keys.h changes. A key added to an App shows up on the website without anyone editing a page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
This commit is contained in:
Claude Opus 5.5
@@ -8,7 +8,7 @@ docs = true
|
||||
source = "docs/milestones/U1.md"
|
||||
tag = "U1"
|
||||
+++
|
||||
**Status:** in progress. The help key (issue #69) is built and checked on the device, in a pull request. Screen recording (#17) and the rest of the milestone are not started.
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -45,4 +45,10 @@ Every screen used to say something about its keys, differently: a footer of abbr
|
||||
| On the device, `key help` and a screenshot | The Launcher and all nine Apps, and these states: Storage scrolled, System's tasks, a Settings text field, Wi-Fi Tools' networks. The panel is titled with the scope, lists the right keys, scrolls, and closes on Tab |
|
||||
| The one-time Toast | `notification: Fn+h: the keys of any screen` on the first start after the update |
|
||||
|
||||
### One source for the device and the website (issue #72)
|
||||
|
||||
The lists first lived in each App's `help()`, as code. They are now **data, in one file**: `lib/core/src/app_keys.h`, 52 constant tables, each under a comment `// id: Title`. An App's `help()` picks the table of the state it is in. `site/tools/gen_dev_docs.py` reads the same file and writes `site/data/keys.toml`; the `keys` shortcode shows a screen's tables on its guide page, and `/guide/keys/` shows all of them. The Site job fails when the data file is out of date, or when a page asks for a table that doesn't exist, and it now runs when `app_keys.h` changes. A key added to an App shows up on the website without anyone editing a page.
|
||||
|
||||
Three rows lost their second wording on the way, since a table is constant: GNSS's `Tab` and `r`, and the Scanner's `c`, now say both things they do ("record a Track, or stop it") instead of the one that applies. The guide pages keep their written tables too, where they say more than a key list can; those can still drift, and the generated ones under them are the reference.
|
||||
|
||||
**Not checked:** the real Fn+h and `?` on the keyboard (the mapper is host-tested; the device was driven with `key help`); the Setup screens, which only a device that was never set up shows, so their new text has not been seen on a screen; and the states that need something to happen first (a dialog, a copy in progress, a Gemini prompt, a packet's details): their lists were read against the key handling, not looked at.
|
||||
|
||||
@@ -71,3 +71,9 @@ On a new device a short Setup asks four things, then never appears again. It als
|
||||
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.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["launcher", "everywhere", "dialog", "text"]) }}
|
||||
|
||||
@@ -40,3 +40,9 @@ Most capsules sign their own certificate. The first certificate seen for a host
|
||||
## 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.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["gemini", "gemini-saved", "gemini-address", "gemini-answer"]) }}
|
||||
|
||||
@@ -28,3 +28,9 @@ Once there is a fix, the device's clock follows it.
|
||||
## Tracks
|
||||
|
||||
<kbd>r</kbd> 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 <kbd>r</kbd> 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.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["gnss"]) }}
|
||||
|
||||
@@ -49,3 +49,9 @@ Every buffer is logged to the SD card, one file per day, under `/irc`. Logs stop
|
||||
|
||||
- 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/)).
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["irc", "irc-settings", "irc-field"]) }}
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
+++
|
||||
title = "Every key"
|
||||
description = "The keys of every screen of the firmware, as the help panel lists them on the device: one table for each screen and state."
|
||||
weight = 12
|
||||
[extra]
|
||||
tag = "Reference"
|
||||
+++
|
||||
|
||||
On the device, <kbd>Fn</kbd> + <kbd>h</kbd> lists the keys of the screen you are on (and <kbd>?</kbd> does, when you are not typing). This page is all of those lists at once, generated from the same source the firmware reads: `lib/core/src/app_keys.h`.
|
||||
|
||||
In the tables, `; . , /` are the arrow keys (up, down, left, right): alone when you are not typing, with <kbd>Fn</kbd> when you are. `` ` `` is Back, `Aa` is Shift, and two keys separated by spaces are two keys that do the two things listed.
|
||||
|
||||
{{ keys(all=true) }}
|
||||
@@ -33,3 +33,9 @@ A capture records packets into a **pcap** file with LoRaTap headers in `/capture
|
||||
## 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.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["lora", "lora-packet", "lora-presets", "lora-sweep"]) }}
|
||||
|
||||
@@ -35,3 +35,9 @@ A new note has no file until you type something. The file is then named after it
|
||||
## Limits
|
||||
|
||||
A note holds up to **16 KB** while it is edited. A bigger text file opens read-only in the [Storage App](/guide/storage/); editing a file of any size is planned. In Storage, <kbd>e</kbd> on a text file opens it in the same editor, anywhere on the card, unless the file is read-only. Notes are never offered for deletion by the clean-up.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["notes", "notes-editor", "notes-name"]) }}
|
||||
|
||||
@@ -41,3 +41,9 @@ A network normally gives the device its address by itself (DHCP, **Automatic**).
|
||||
### DNS and NTP
|
||||
|
||||
Two DNS servers (9.9.9.9 and 1.1.1.1 by default), used on Fixed networks, or on every network if **Always use my DNS** is on; and two NTP servers (pool.ntp.org and time.cloudflare.com), used after any that the network's DHCP offers. <kbd>Enter</kbd> on **Status** shows what is in use and where each value came from.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> 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"]) }}
|
||||
|
||||
@@ -45,3 +45,9 @@ The App says why when it refuses.
|
||||
At the top of the card, the last row, **Maintenance** (or <kbd>m</kbd>), shows the card's usage and holds **Storage clean-up** and **Erase SD card**. They delete for good, so they sit behind a warning. Clean-up deletes old logs and captures by category and age, showing the space it would free first. Notes and Saved Pages are never offered.
|
||||
|
||||
The firmware warns once per start when the card passes **80%** full; past **90%**, logs stop being written so that the rest is kept for captures.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["storage", "storage-details", "storage-name", "storage-busy", "maintenance", "viewer-text", "viewer-hex", "viewer-pcap", "viewer-packet", "viewer-gpx", "viewer-ota"]) }}
|
||||
|
||||
@@ -18,3 +18,9 @@ System changes nothing: it shows. It samples once a second and keeps its history
|
||||
## Why it exists
|
||||
|
||||
The device has about 107 KB of free memory and no PSRAM, so memory is the resource that decides what can run together: a secure connection takes about 52 KB at its peak. System makes that visible, and is how the project measures its own changes.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["system", "system-tasks", "system-system"]) }}
|
||||
|
||||
@@ -42,3 +42,9 @@ The connection to the project's server is checked against the two root certifica
|
||||
## For developers
|
||||
|
||||
Updates can also be pushed from a PC over Wi-Fi, with `scripts/flash.sh --ota <ip>`, or put on the card with `scripts/sd_put.sh`: see the [README](https://git.twis.la/twisla/roro9stack#firmware-updates-over-wi-fi-ota). The firmware's console can be reached over Wi-Fi too: see [The Debug Console](/dev/debug/).
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["firmware", "firmware-release", "firmware-older"]) }}
|
||||
|
||||
@@ -34,3 +34,9 @@ One bar for each of the 13 Wi-Fi channels shows how busy it is: how many network
|
||||
## Signal tracker
|
||||
|
||||
Follows one network: its name, address and channel, then the signal in dBm in large type, a strength bar, and a graph of the recent readings, so you can walk towards the strongest signal. <kbd>m</kbd> turns audible clicks on and off. If the network is no longer heard the screen says `lost`. <kbd>`</kbd> (Back) returns to the list.
|
||||
|
||||
## The keys, as the device lists them
|
||||
|
||||
What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
|
||||
|
||||
{{ keys(scopes=["wifi-tools", "wifi-networks", "wifi-tracker"]) }}
|
||||
|
||||
@@ -0,0 +1,516 @@
|
||||
# Generated by site/tools/gen_dev_docs.py from lib/core/src/app_keys.h: the keys of every screen, as the
|
||||
# help panel (Fn+h) lists them on the device. Edit that header, not this file.
|
||||
|
||||
[[scope]]
|
||||
id = "everywhere"
|
||||
title = "Everywhere"
|
||||
rows = [
|
||||
["`", "back"],
|
||||
["Fn `", "home, the Launcher"],
|
||||
["; . , /", "arrows (Fn+ while typing)"],
|
||||
["Fn h ?", "these keys (? not typing)"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "dialog"
|
||||
title = "A question"
|
||||
rows = [
|
||||
[", /", "the other answer"],
|
||||
["Enter", "choose it"],
|
||||
["`", "cancel"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "text"
|
||||
title = "A text field"
|
||||
rows = [
|
||||
["Enter", "save"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
["opt ' e", "an accent: é"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "launcher"
|
||||
title = "The Launcher"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "open the App"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "setup"
|
||||
title = "Setup, a step"
|
||||
rows = [
|
||||
["Enter", "continue"],
|
||||
["`", "the step before"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "setup-choice"
|
||||
title = "Setup, a choice"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "choose it, next step"],
|
||||
["`", "the step before"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "setup-text"
|
||||
title = "Setup, a name"
|
||||
rows = [
|
||||
["Enter", "next step"],
|
||||
["`", "the step before"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
["opt ' e", "an accent: é"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "irc"
|
||||
title = "IRC"
|
||||
rows = [
|
||||
["Enter", "send the line"],
|
||||
["Tab", "the next buffer"],
|
||||
["Alt ; .", "scroll back, forward"],
|
||||
["Fn ; .", "lines you sent before"],
|
||||
["Fn , /", "move the cursor"],
|
||||
["Del", "delete backwards"],
|
||||
["/settings", "server, nick, passwords"],
|
||||
["/join #x", "join a channel"],
|
||||
["/part", "leave it"],
|
||||
["/msg nick", "a private chat"],
|
||||
["/me", "an action"],
|
||||
["/nick", "change your nick"],
|
||||
["/topic", "see or set the topic"],
|
||||
["/names", "who is there"],
|
||||
["/quit", "disconnect, and stay so"],
|
||||
["/raw", "a line as it is"],
|
||||
["`", "leave: IRC stays connected"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "irc-settings"
|
||||
title = "IRC settings"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "edit, switch, or save"],
|
||||
["`", "leave without saving"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "irc-field"
|
||||
title = "IRC, a setting"
|
||||
rows = [
|
||||
["Enter", "keep it"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-tools"
|
||||
title = "Wi-Fi Tools"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "open"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-networks"
|
||||
title = "Networks nearby"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "track its signal"],
|
||||
["s", "sort: signal, channel, name"],
|
||||
["o", "open networks only"],
|
||||
["h", "hide the hidden ones"],
|
||||
["w", "strong ones only"],
|
||||
["l", "log the scans to the card"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-tracker"
|
||||
title = "Signal tracker"
|
||||
rows = [
|
||||
["m", "clicks on or off"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "gnss"
|
||||
title = "GNSS"
|
||||
rows = [
|
||||
["Tab", "the position, or the sky"],
|
||||
["r", "record a Track, or stop it"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "gemini"
|
||||
title = "Gemini, a page"
|
||||
rows = [
|
||||
["Tab", "the next link"],
|
||||
["Aa Tab", "the link before"],
|
||||
["Enter", "follow the link"],
|
||||
["` Del", "the page before"],
|
||||
["; .", "scroll"],
|
||||
["Space", "a page down"],
|
||||
[", /", "sideways, in wide blocks"],
|
||||
["g", "type an address"],
|
||||
["b", "bookmark this page"],
|
||||
["s", "save the page to the card"],
|
||||
["S", "...with the pages it links to"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "gemini-saved"
|
||||
title = "Gemini, a Saved Page"
|
||||
rows = [
|
||||
["Tab", "the next link"],
|
||||
["Aa Tab", "the link before"],
|
||||
["Enter", "follow the link"],
|
||||
["` Del", "the page before"],
|
||||
["; .", "scroll"],
|
||||
["Space", "a page down"],
|
||||
[", /", "sideways, in wide blocks"],
|
||||
["g", "type an address"],
|
||||
["b", "bookmark this page"],
|
||||
["r", "refresh this Saved Page"],
|
||||
["d", "delete this Saved Page"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "gemini-address"
|
||||
title = "Gemini, an address"
|
||||
rows = [
|
||||
["Enter", "go there"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "gemini-answer"
|
||||
title = "Gemini, an answer to a page"
|
||||
rows = [
|
||||
["Enter", "send it"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "lora"
|
||||
title = "LoRa Scanner, the packets"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "the packet's details"],
|
||||
["p", "pick a Meshtastic preset"],
|
||||
["c", "start a Capture, or stop it"],
|
||||
["Tab", "the Sweep"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "lora-packet"
|
||||
title = "LoRa Scanner, a packet"
|
||||
rows = [
|
||||
["; .", "scroll"],
|
||||
["Enter", "back to the list"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "lora-presets"
|
||||
title = "LoRa Scanner, the presets"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "listen with this preset"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "lora-sweep"
|
||||
title = "LoRa Scanner, the Sweep"
|
||||
rows = [
|
||||
["Tab", "the Sniffer"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "storage"
|
||||
title = "Storage, a folder"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "open the folder or the file"],
|
||||
[", /", "a page up, down"],
|
||||
["c x", "copy, cut"],
|
||||
["v", "paste here"],
|
||||
["r", "rename"],
|
||||
["d Del", "delete, after asking"],
|
||||
["n", "a new folder"],
|
||||
["i", "details: size, date, type"],
|
||||
["s", "sort: name, date, size"],
|
||||
["m", "Maintenance: clean-up, erase"],
|
||||
["`", "the folder above"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "storage-details"
|
||||
title = "Storage, an item's details"
|
||||
rows = [
|
||||
["; .", "scroll"],
|
||||
["Enter", "back to the folder"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "storage-name"
|
||||
title = "Storage, a name"
|
||||
rows = [
|
||||
["Enter", "rename it, or make the folder"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "storage-busy"
|
||||
title = "Storage, while it copies or deletes"
|
||||
rows = [
|
||||
["`", "stop the copy or the delete"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "maintenance"
|
||||
title = "Storage, Maintenance"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "open, or choose"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "viewer-text"
|
||||
title = "A file, as text"
|
||||
rows = [
|
||||
["; .", "a line up, down"],
|
||||
[", /", "a page up, down"],
|
||||
["t b", "the top, the end"],
|
||||
["e", "edit it (up to 16 KB)"],
|
||||
["Tab", "the file as hex, or back"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "viewer-hex"
|
||||
title = "A file, as hex"
|
||||
rows = [
|
||||
["; .", "a line up, down"],
|
||||
[", /", "a page up, down"],
|
||||
["t b", "the top, the end"],
|
||||
["Tab", "the file as text, or back"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "viewer-pcap"
|
||||
title = "A Capture"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "the packet"],
|
||||
[", /", "a page up, down"],
|
||||
["Tab", "the file as hex"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "viewer-packet"
|
||||
title = "A Capture's packet"
|
||||
rows = [
|
||||
["; .", "scroll"],
|
||||
["Enter", "back to the packets"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "viewer-gpx"
|
||||
title = "A Track"
|
||||
rows = [
|
||||
["Tab", "the file as text"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "viewer-ota"
|
||||
title = "An Update File"
|
||||
rows = [
|
||||
["Enter", "install it, if it's genuine"],
|
||||
["Tab", "the file as hex"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "notes"
|
||||
title = "Notes, the list"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "open the note"],
|
||||
[", /", "a page up, down"],
|
||||
["n", "a new note"],
|
||||
["r", "rename its file"],
|
||||
["d Del", "delete it"],
|
||||
["s", "sort: newest, or by name"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "notes-editor"
|
||||
title = "Notes, the editor"
|
||||
rows = [
|
||||
["Enter", "a new line"],
|
||||
["Del", "delete backwards"],
|
||||
["Tab", "two spaces"],
|
||||
["Fn ; . , /", "move the cursor"],
|
||||
["Alt Fn ; .", "a page up, down"],
|
||||
["Ctrl a e", "start, end of the line"],
|
||||
["opt ' e", "an accent: é"],
|
||||
["`", "done: it saves by itself"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "notes-name"
|
||||
title = "Notes, a file name"
|
||||
rows = [
|
||||
["Enter", "rename the file"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "system"
|
||||
title = "System, any view"
|
||||
rows = [
|
||||
["Tab", "the next view"],
|
||||
["Aa Tab", "the view before"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "system-tasks"
|
||||
title = "System, the tasks"
|
||||
rows = [
|
||||
["Tab", "the next view"],
|
||||
["Aa Tab", "the view before"],
|
||||
["; .", "scroll"],
|
||||
["s", "sort: cpu, stack, name"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "system-system"
|
||||
title = "System, the system view"
|
||||
rows = [
|
||||
["Tab", "the next view"],
|
||||
["Aa Tab", "the view before"],
|
||||
["; .", "scroll"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "settings"
|
||||
title = "Settings"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "edit, or open the page"],
|
||||
[", /", "change a switch or a slider"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "settings-choice"
|
||||
title = "Settings, a choice"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "choose it"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi"
|
||||
title = "Settings, Wi-Fi"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "open, or change"],
|
||||
[", /", "switch Wi-Fi on or off"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-servers"
|
||||
title = "Settings, DNS and NTP"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "edit"],
|
||||
[", /", "Always use my DNS: on, off"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-network"
|
||||
title = "Settings, a saved network"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "edit, or forget"],
|
||||
[", /", "Automatic or Fixed"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-status"
|
||||
title = "Settings, the Wi-Fi status"
|
||||
rows = [
|
||||
["Enter", "back"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-scan"
|
||||
title = "Settings, adding a network"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "choose this network"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "wifi-name"
|
||||
title = "Settings, a hidden network's name"
|
||||
rows = [
|
||||
["Enter", "next: the password"],
|
||||
["`", "cancel"],
|
||||
["Del", "delete backwards"],
|
||||
["Fn , /", "move the cursor"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "firmware"
|
||||
title = "Settings, Firmware"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "check, open, or install"],
|
||||
["c", "look for a newer release"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "firmware-release"
|
||||
title = "Settings, a release"
|
||||
rows = [
|
||||
["; .", "scroll"],
|
||||
["Enter", "install it"],
|
||||
["c", "check again"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "firmware-older"
|
||||
title = "Settings, older releases"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "its details"],
|
||||
["c", "read the list again"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "debug-console"
|
||||
title = "Settings, Debug Console"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "switch, or open"],
|
||||
[", /", "switch the console on or off"],
|
||||
]
|
||||
|
||||
[[scope]]
|
||||
id = "demo"
|
||||
title = "The widget demo"
|
||||
rows = [
|
||||
["; .", "up, down"],
|
||||
["Enter", "try the widget"],
|
||||
]
|
||||
@@ -254,3 +254,12 @@ footer small { display: block; max-width: 760px; }
|
||||
.source { max-width: 820px; font-size: 14px; line-height: 20px; }
|
||||
.source code { background: var(--s2); padding: 0 6px; }
|
||||
.card.featured { flex-basis: 100%; }
|
||||
|
||||
/* The keys of a screen, as the device's help panel lists them (the `keys` shortcode) */
|
||||
.keys { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 16px 32px; }
|
||||
.keys-scope { background: var(--s2); padding: 16px 20px; }
|
||||
.keys-scope h4 { font: 500 12px/16px var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--cyantext); margin: 0 0 8px; }
|
||||
.prose .keys table { width: 100%; }
|
||||
.prose .keys td { padding: 4px 8px 4px 0; border-bottom: 0; font-size: 15px; }
|
||||
.prose .keys td:first-child { white-space: nowrap; width: 1%; padding-right: 16px; }
|
||||
.prose .keys kbd { white-space: pre; }
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
{#- The keys of one or more screens, as the help panel (Fn+h) lists them on the device:
|
||||
{{ keys(scopes=["storage", "storage-details"]) }}, or {{ keys(all=true) }} for every screen.
|
||||
The tables come from site/data/keys.toml, generated from lib/core/src/app_keys.h (issue #72):
|
||||
a key added to an App shows up here without anyone editing a page. -#}
|
||||
{%- set data = load_data(path="data/keys.toml", format="toml") -%}
|
||||
{%- set everything = all is defined and all -%}
|
||||
<div class="keys">
|
||||
{%- for s in data.scope %}{% if everything or (scopes is defined and s.id in scopes) %}
|
||||
<div class="keys-scope">
|
||||
<h4 id="keys-{{ s.id }}">{{ s.title }}</h4>
|
||||
<table>
|
||||
{%- for r in s.rows %}
|
||||
<tr><td><kbd>{{ r.0 }}</kbd></td><td>{{ r.1 }}</td></tr>
|
||||
{%- endfor %}
|
||||
</table>
|
||||
</div>
|
||||
{%- endif %}{% endfor %}
|
||||
</div>
|
||||
@@ -9,6 +9,8 @@ Zola cannot read a file outside its own folder, so the pages are generated and c
|
||||
milestones/ one page for each docs/milestones/*.md
|
||||
build/build-and-test, build/flash sections of README.md
|
||||
debug/commands the commands the firmware's `help` prints (parsed from src/main.cpp), then README's table of them
|
||||
site/data/keys.toml every screen's keys, from lib/core/src/app_keys.h: what the help panel (Fn+h) shows on the
|
||||
device, for the `keys` shortcode of the user guide (issue #72)
|
||||
Every generated page says where it comes from; edit that file, not the page. Hand-written pages sit next to them.
|
||||
"""
|
||||
import json
|
||||
@@ -139,8 +141,38 @@ def safe_mode_commands():
|
||||
return exact, prefix
|
||||
|
||||
|
||||
def key_tables():
|
||||
"""Every table of lib/core/src/app_keys.h: [(id, title, [(keys, action), ...])], in the file's order."""
|
||||
src = (REPO / "lib" / "core" / "src" / "app_keys.h").read_text()
|
||||
|
||||
def text(literal): # a C string literal's contents: \xHH bytes are UTF-8
|
||||
raw = re.sub(r"\\x([0-9A-Fa-f]{2})", lambda m: chr(int(m.group(1), 16)), literal).replace('\\"', '"')
|
||||
return raw.encode("latin-1").decode("utf-8")
|
||||
|
||||
tables = []
|
||||
for m in re.finditer(r"// ([a-z0-9-]+): ([^\n]+)\ninline constexpr KeyHelp k\w+\[\] = \{\n(.*?)\n\};", src, re.S):
|
||||
rows = [(text(k), text(a)) for k, a in re.findall(r'\{"((?:[^"\\]|\\.)*)", "((?:[^"\\]|\\.)*)"\},', m.group(3))]
|
||||
if len(rows) != len([l for l in m.group(3).splitlines() if l.strip()]):
|
||||
sys.exit(f"gen_dev_docs: a row of `{m.group(1)}` in app_keys.h isn't in the form {{\"keys\", \"action\"}},")
|
||||
tables.append((m.group(1), m.group(2).strip(), rows))
|
||||
declared = len(re.findall(r"^inline constexpr KeyHelp k\w+\[\]", src, re.M))
|
||||
if len(tables) != declared or len({t[0] for t in tables}) != len(tables):
|
||||
sys.exit(f"gen_dev_docs: app_keys.h has {declared} tables, {len(tables)} with an `// id: Title` comment and a unique id")
|
||||
return tables
|
||||
|
||||
|
||||
def keys_toml():
|
||||
out = ["# Generated by site/tools/gen_dev_docs.py from lib/core/src/app_keys.h: the keys of every screen, as the",
|
||||
"# help panel (Fn+h) lists them on the device. Edit that header, not this file.", ""]
|
||||
for ident, title, rows in key_tables():
|
||||
out += ["[[scope]]", f"id = {json.dumps(ident)}", f"title = {json.dumps(title, ensure_ascii=False)}", "rows = ["]
|
||||
out += [f" [{json.dumps(k, ensure_ascii=False)}, {json.dumps(a, ensure_ascii=False)}]," for k, a in rows]
|
||||
out += ["]", ""]
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
def build():
|
||||
pages = {}
|
||||
pages = {"../../data/keys.toml": keys_toml()}
|
||||
|
||||
for path in sorted((REPO / "docs" / "adr").glob("*.md")):
|
||||
title, body = title_and_body(path.read_text())
|
||||
@@ -179,9 +211,25 @@ def build():
|
||||
return pages
|
||||
|
||||
|
||||
def unknown_scopes():
|
||||
"""Scopes a page asks the `keys` shortcode for that app_keys.h doesn't have."""
|
||||
known = {t[0] for t in key_tables()}
|
||||
bad = []
|
||||
for path in sorted((SITE / "content").rglob("*.md")):
|
||||
for call in re.findall(r"keys\(scopes=\[([^\]]*)\]", path.read_text()):
|
||||
for ident in re.findall(r'"([^"]+)"', call):
|
||||
if ident not in known:
|
||||
bad.append(f"{path.relative_to(SITE)}: no key table `{ident}` in lib/core/src/app_keys.h")
|
||||
return bad
|
||||
|
||||
|
||||
def main():
|
||||
check = "--check" in sys.argv
|
||||
pages = build()
|
||||
for problem in unknown_scopes():
|
||||
print("gen_dev_docs:", problem)
|
||||
if unknown_scopes():
|
||||
sys.exit(1)
|
||||
stale = []
|
||||
for rel, text in sorted(pages.items()):
|
||||
path = OUT / rel
|
||||
@@ -193,10 +241,10 @@ def main():
|
||||
path.write_text(text)
|
||||
if check:
|
||||
for rel in stale:
|
||||
print(f"gen_dev_docs: content/dev/{rel} is out of date: run site/tools/gen_dev_docs.py and commit the result")
|
||||
print(f"gen_dev_docs: {len(pages)} pages, {len(stale)} out of date")
|
||||
print(f"gen_dev_docs: {os.path.normpath(os.path.join('site/content/dev', rel))} is out of date: run site/tools/gen_dev_docs.py and commit the result")
|
||||
print(f"gen_dev_docs: {len(pages)} files, {len(stale)} out of date")
|
||||
sys.exit(1 if stale else 0)
|
||||
print(f"gen_dev_docs: {len(pages)} pages, {len(stale)} written")
|
||||
print(f"gen_dev_docs: {len(pages)} files, {len(stale)} written")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
Reference in New Issue
Block a user