S1 plan: the resting loop and the GNSS pause ship in v0.8.1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

.gitignore

@@ -0,0 +1,11 @@
+.pio/
+.vscode/
+*.pyc
+
+# Private signing keys never belong in the repository (ADR 0003)
+*key.pem
+
+# Generated by pioarduino's hybrid compile from custom_sdkconfig (platformio.ini)
+.dummy/
+managed_components/
+sdkconfig.*

CONTEXT.md

@@ -0,0 +1,177 @@
+# 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. Selecting it opens 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.
+
+**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).

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -0,0 +1,158 @@
+# roro9stack
+
+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.
+
+- Domain language: [CONTEXT.md](CONTEXT.md)
+- Decisions: [docs/adr/](docs/adr/)
+- Milestones: [docs/milestones/](docs/milestones/)
+
+## Requirements
+
+Only **Docker** is needed. PlatformIO and the ESP32 toolchain run inside a container, and are cached in the `roro9stack-pio` Docker volume. The first build downloads about 1 GB and takes a few minutes.
+
+## Build and test (local CI)
+
+```sh
+scripts/ci.sh
+```
+
+This runs the host-side unit tests (`test/`, `native` environment), then builds the firmware. The output is `.pio/build/cardputer-adv/firmware.factory.bin`.
+
+The framework is rebuilt with the TLS settings in `platformio.ini` (`custom_sdkconfig`, ADR 0006), so the first build after a fresh checkout takes about 4 minutes; later builds take under a minute.
+
+## Flash
+
+1. Connect the Cardputer by USB-C.
+2. Run:
+
+   ```sh
+   scripts/flash.sh            # auto-detects the port; or: scripts/flash.sh /dev/ttyACM1
+   ```
+
+   This uploads the firmware, then opens the serial monitor. Quit the monitor with `Ctrl+C`.
+
+**If the upload can't connect,** put the device in download mode: hold **G0** (the button next to the screen) while plugging in USB, or while pressing reset. Then retry.
+
+**If you get "permission denied" on the port,** your user needs access to the serial device. Run this once, then log out and back in:
+
+```sh
+sudo usermod -aG dialout "$USER"
+```
+
+## Firmware Updates over Wi-Fi (OTA)
+
+Once the Cardputer runs an OTA-capable firmware (flashed once over USB), updates can go over Wi-Fi:
+
+```sh
+scripts/ota_keygen.sh                  # once: creates the signing key (see ADR 0003)
+scripts/flash.sh --ota 10.39.39.12     # build, sign and push; or set RORO_OTA_HOST
+```
+
+The device shows the push address in **Settings → Firmware**. It installs a correctly signed update right away, restarts (waiting up to 60 s if you're typing), and runs the new firmware on **Probation**. If the new firmware crashes, or can't reconnect Wi-Fi within 3 minutes, it rolls back to the previous one and says so.
+
+To install from the SD card instead, copy the `.ota` file from `.pio/build/cardputer-adv/` into `/updates` on the card, then use **Settings → Firmware**. With the Cardputer on USB, the card can stay in: `scripts/sd_put.sh <file.ota>` sends it over the serial console into `/updates` (about 30 s for 1.6 MB, checked with SHA-256 before it's renamed into place; `SD_PUT_DEBUG=1` shows the console while it runs).
+
+**The private key** lives in `~/.config/roro9stack/ota-key.pem` and must never be committed. If it's lost, generate a new pair and flash once over USB.
+
+## Networks without DHCP
+
+Each Saved Network gets its address automatically (DHCP) or has a Fixed one (docs/milestones/S1.md): in Settings > Wi-Fi, Enter on a network opens its page, where "IP address" switches between Automatic and Fixed, with an address, a prefix length (24 is 255.255.255.0) and an optional gateway. Switching to Fixed starts from what the network is giving the device at that moment. The setting is checked and applied when you leave the page. IPv4 only.
+
+"DNS and NTP" on the same screen holds two DNS servers (9.9.9.9 and 1.1.1.1 by default), used on Fixed networks, or on every network with "Always use my DNS"; and two NTP servers (pool.ntp.org and time.cloudflare.com), used after any the network's DHCP offers. Enter on "Status" shows what's in use and where each value came from.
+
+## System
+
+The System App (docs/milestones/S1.md) shows what the device is doing, live and read-only, in any build. Tab moves between five views:
+
+- **Overview:** each core's load, free memory, network traffic, battery, uptime and chip temperature, and both cores' load over the last two minutes.
+- **Tasks:** every FreeRTOS task with its core, its share of a core over the last second, and the least stack it ever had left (in the warning colour under 512 bytes). `s` sorts by share, stack or name.
+- **Memory:** free heap, the lowest since boot and the largest free block, with two minutes of free heap drawn against the three memory floors (55, 40 and 20 KB).
+- **Network:** the connection, then for IRC, Gemini, the Debug Console and Firmware Updates the bytes read and written since boot and what's moving now. For TLS connections these are the bytes the service sees, without the encryption overhead.
+- **System:** what `info` prints, plus the battery, the SD card with its write faults, the radio and the GNSS receiver.
+
+It samples once a second and keeps its history only while it's open.
+
+## Gemini
+
+The Gemini App browses Geminispace (docs/milestones/G1.md): Tab and Shift+Tab pick a link, Enter follows it, Back returns (to where the page was scrolled), Space pages down, `g` types an address. Certificates are trusted on first use; a changed one stops the page and asks.
+
+On a page, `b` bookmarks it, `s` saves it to the SD card to read offline (a non-text file goes to `/gemini/downloads/`), `S` saves it with the pages it links to on the same capsule (up to 30). The start page lists bookmarks and Saved Pages; inside a Saved Page, `r` refreshes it and `d` deletes it. With a card, every page streams through `/gemini/cache/` so a large one arrives whole even with IRC connected; what doesn't fit in memory stays on the card.
+
+## LoRa Scanner
+
+The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **never transmits**. The Sniffer lists what it hears, newest first: time, RSSI, SNR, and for Meshtastic packets the sender and receiver (their last 4 hex digits) and hops. Enter shows a packet's details: 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: a pcap file with LoRaTap headers in `/captures/lora/`, for Wireshark. A Capture keeps recording with the App closed; otherwise the radio sleeps when the App isn't open. Tab switches to **Sweep**: the signal strength across 863–870 MHz in 100 kHz steps, as bars with peak hold and a waterfall, with the Sniffer's frequency marked; the Sniffer is paused meanwhile and picks up where it was. The GNSS receiver on the same Cap raises the radio's noise floor by 8 dB while it runs: Settings > "Pause GNSS for LoRa" (off by default) puts it in standby while the radio listens, except during a Track. The Status Bar shows `L` while the radio listens (bright for a moment on each packet), `SW` while sweeping, and `CAP` while capturing.
+
+## Development aids
+
+`scripts/serial_log.sh [seconds] [command…]` records the serial output, and can send commands to the firmware first. For example, `scripts/serial_log.sh 30 short sleep:12 burst` sets short screen timeouts, waits 12 s, then sends a burst of Toasts.
+
+| Command | Effect |
+|---|---|
+| `burst` | Publishes 5 Notifications at once |
+| `key up\|down\|left\|right\|select\|back\|home`, or `key <char>` | Injects a key press |
+| `sound on` / `sound off` | Toggles the Sound setting (beep + LED) |
+| `short` / `normal` | Screen timeouts 5 s / 10 s, or 30 s / 60 s |
+| `wifi add <ssid><TAB><password>` | Adds a Saved Network (so credentials stay out of the repo) |
+| `wifi ip <ssid> dhcp` / `wifi ip <ssid> <address>/<prefix> [gateway]` | A Saved Network's IP setting: Automatic, or Fixed. Debug Builds: add `try <seconds>` to go back to the previous setting unless `wifi ip keep` follows |
+| `wifi dns <a> [b]` / `wifi dns always on\|off` / `wifi ntp <a> [b]` | DNS servers (used on Fixed networks, or always), and NTP servers |
+| `log <text>` | Appends a line to a test IRC Log (`/irc/dev/#test/<date>.log`) |
+| `sd card` | What the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date) |
+| `sd list` | Lists the files of each Storage Clean-up category |
+| `cat <path>` | Prints the first ~1.2 KB of a file on the SD card |
+| `irc start` | Starts the IRC Service (normally done by opening the IRC App) |
+| `irc stop` | Stops it, as `/quit` does: QUIT if connected, no more retries, and the App stays disconnected until you type |
+| `gemini get <url>` | Fetches a Gemini page and prints its header, size, certificate fingerprint and heap use |
+| `gemini trust <host> <port> <sha256>` | Pins a certificate by hand (the Gemini App asks when one changes) |
+| `irc say <buffer> <text>` | Types into a Buffer, commands included (`irc say 0 /join #test`) |
+| `irc dump` | Prints IRC status, memory, and the last lines of each Buffer |
+| `wifi status` | Prints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from |
+| `info` | Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, and both app slots with their versions and OTA states |
+| `tasks` | FreeRTOS tasks over the next second: state, priority, lowest free stack, share of a core, each core's load, and how many passes the main loop made |
+| `net` | Bytes each network service has read and written since boot |
+| `reboot` / `boot other` | Restart, or restart into the other app slot (a manual Rollback) |
+| `log level <0-5>` | ESP-IDF log level |
+| `ls [folder]` / `rm <path>` | Lists a folder of the SD card, or deletes a file |
+| `install <path>` | Update from SD with that `.ota` file, as Settings → Firmware does |
+| `lora probe` | Finds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor |
+| `lora status` | Radio settings, who's listening, packet and error counters, noise floor, task stack |
+| `lora rx on` / `lora rx off` | Listens and prints each packet on the console |
+| `lora preset <name>` / `lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]` | Receive settings: a Meshtastic preset, or anything else (`lora custom 868.1 125 7 5 34 8` for LoRaWAN) |
+| `lora capture start` / `lora capture stop` | A LoRa Capture, as `c` in the App |
+| `lora sweep on [from MHz] [to MHz] [step kHz]` / `lora sweep off` / `lora sweep dump` | Sweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass |
+| `gnss quiet on` / `gnss quiet off` | The "Pause GNSS for LoRa" setting |
+| `lora noise test [gnss\|quiet]` / `lora noise report` | Debug Builds: Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result |
+| `lora inject <hex> [rssi] [snr]` | Debug Builds: a packet into the Scanner as if received (nothing is sent) |
+| `crash` | The last crash: which firmware, why, task, PC and backtrace (from the core dump in flash) |
+| `coredump erase` | Forgets the core dump |
+| `loop spin on` / `loop spin off` | Debug Builds: make the main loop spin without resting, to compare load and radio noise |
+| `crash abort` / `crash wdt` | Debug Builds: crash on purpose, or hang the main loop until the watchdog fires |
+| `help` | Lists the commands |
+
+`scripts/flash.sh` stops a running serial log first, since it would hold the port.
+
+### Debug Builds and the Debug Console
+
+`scripts/flash.sh --debug` (USB) or `scripts/flash.sh --debug --ota <ip>` (Wi-Fi) installs a Debug Build: the same firmware plus the Debug Console on TCP 2323 (ADR 0004). Then, with `RORO_OTA_HOST` set to the device's IP:
+
+```sh
+scripts/rdbg.py                 # interactive: the console backlog, live lines, and commands
+scripts/rdbg.py info            # one command and its reply
+scripts/rdbg.py -b tasks        # the same, after the backlog (boot messages and so on)
+```
+
+Every command above works there too, plus a few handled by the PC side or the console's own task:
+
+```sh
+scripts/rdbg.py crash           # the last crash, its backtrace decoded against that exact build's ELF
+scripts/rdbg.py coredump        # fetch the core dump and decode it all (registers, every task) with esp-coredump
+scripts/rdbg.py reset           # restart at once, even if the main loop is stuck
+scripts/rdbg.py screenshot      # the screen as a PNG (2x)
+scripts/rdbg.py put <file> [card path]    # to the SD card (default /updates/<name>), SHA-256 checked, ~300 KB/s
+scripts/rdbg.py get <card path> [file]    # from the SD card
+```
+
+So a Firmware Update can also go `rdbg.py put roro9stack-….ota` then `rdbg.py install /updates/roro9stack-….ota`: the Update from SD path, without touching the device.
+
+Every build keeps its ELF in `.pio/elves/` (version and digest in the name) for that; `scripts/decode_backtrace.sh <version|digest> <addresses>` decodes any backtrace by hand.
+
+After 3 crash restarts in a row the firmware starts in **Safe Mode** (ADR 0005): only Wi-Fi, Firmware Updates and the Debug Console, so a fix can be pushed as usual. `reboot` leaves it. The token is in `~/.config/roro9stack/debug-token`, made by the first build; keep developing on Debug Builds, so the firmware a Rollback returns to always has the console.

coverage.svg

@@ -1,7 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="117" height="20" role="img" aria-label="lib coverage: 95%">
-<title>lib coverage: 95% of the lines of lib/ are run by the host tests</title>
-<linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
-<clipPath id="r"><rect width="117" height="20" rx="3" fill="#fff"/></clipPath>
-<g clip-path="url(#r)"><rect width="84" height="20" fill="#555"/><rect x="84" width="33" height="20" fill="#4c1"/><rect width="117" height="20" fill="url(#s)"/></g>
-<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
-<text x="42.0" y="14">lib coverage</text><text x="100.5" y="14">95%</text></g></svg>

default_8MB.csv

@@ -0,0 +1,7 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x5000,
+otadata,  data, ota,     0xe000,  0x2000,
+app0,     app,  ota_0,   0x10000, 0x330000,
+app1,     app,  ota_1,   0x340000,0x330000,
+spiffs,   data, spiffs,  0x670000,0x180000,
+coredump, data, coredump,0x7F0000,0x10000,

docker/Dockerfile

@@ -0,0 +1,13 @@
+# Build/test/flash environment for roro9stack. No toolchain needed on the host.
+FROM python:3.12-slim
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git build-essential \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir platformio
+
+# Toolchains and libraries are cached in a named volume mounted here.
+RUN mkdir -p /pio && chmod 777 /pio
+ENV PLATFORMIO_CORE_DIR=/pio
+WORKDIR /work

docs/adr/0001-own-firmware-speaking-meshtastic.md

@@ -0,0 +1,15 @@
+# Own firmware that speaks Meshtastic, not a Meshtastic fork
+
+We build our own firmware from existing libraries (PlatformIO + Arduino-ESP32, M5Cardputer/M5Unified, RadioLib, TinyGPSPlus, nanopb with Meshtastic's published protobufs). We implement the Meshtastic protocol ourselves as one pluggable Mesh Protocol, rather than forking the Meshtastic firmware, which already supports this exact hardware.
+
+A fork would give full compatibility on day one, but its architecture is built around being a single-purpose Meshtastic node. That conflicts with our goals: a multi-app OS with a fully custom UX, and room for other mesh protocols (e.g. MeshCore) later.
+
+## Consequences
+
+- We accept partial Meshtastic compatibility at first: text on channels, Direct Messages, node list, position and relaying.
+- The phone-app (BLE) API and PKI-encrypted Direct Messages are deferred, and we must re-implement protocol details ourselves.
+- Multi-boot with stock Meshtastic via a launcher was rejected: it gives none of our own UX.
+
+## Note (2026-10-04, M2)
+
+NMEA is parsed by our own small, host-tested parser instead of TinyGPSPlus: the GNSS App's Sky view needs the satellite list (GSV) across several constellations, which TinyGPSPlus doesn't track. See docs/milestones/M2.md, Q66.

docs/adr/0002-own-widget-kit-on-m5gfx.md

@@ -0,0 +1,10 @@
+# Own small widget kit on M5GFX, not LVGL
+
+The UI is drawn with M5GFX into an off-screen buffer, using a small widget kit we own: list, text view, line editor, dialog, Status Bar and Toast. We chose this over LVGL.
+
+LVGL would give us ready-made widgets, but it costs roughly 40–60 KB of RAM on a device with no PSRAM. It would also need to coexist with the Mesh Service, the Wi-Fi stack and TLS, and it brings a large learning surface. Most of our Apps are lists and text on a 240×135 screen, and full control of the UX is a primary goal.
+
+## Consequences
+
+- We write and maintain our own widgets.
+- Switching to LVGL later would mean rewriting every App's view layer.

docs/adr/0003-own-signature-check-not-secure-boot.md

@@ -0,0 +1,12 @@
+# Signed Update Files checked by the firmware, not ESP32 Secure Boot
+
+Firmware Updates are accepted only when their Update File carries a valid ECDSA P-256 signature over the image's SHA-256. The firmware itself checks it, against a public key compiled into it, before switching the boot partition. The private key lives outside the repository, in `~/.config/roro9stack/ota-key.pem`.
+
+We chose this over the ESP32's hardware Secure Boot. Secure Boot is enforced by the chip, but it burns eFuses one-way: a mistake bricks the device, and the device can never run unsigned firmware again, which makes recovery over USB harder. On a single development device, a software check that refuses unsigned pushes is enough, and it stays reversible: a new firmware can carry a new public key.
+
+## Consequences
+
+- Someone with physical USB access can still flash anything. Only Wi-Fi and SD card updates are guarded.
+- **Losing the private key** means the next update has to go over USB, carrying a new public key.
+- P-256 rather than Ed25519, because the firmware's TLS library (mbedTLS) already verifies it, so it costs no extra code.
+- **Rollback: the bootloader first, the firmware as a second line.** Arduino-ESP32 marks a new image valid before `setup()` unless the sketch overrides `verifyRollbackLater()`, which once made every update look good and hid the bootloader's rollback (it had looked like the prebuilt bootloader ignored it). With the override, an image stays pending until Probation confirms it, and the bootloader reverts one that restarts unconfirmed, however early it crashes. The firmware also counts its own boots on Probation, very first thing in `setup()`, and reverts itself on the second unconfirmed start.

docs/adr/0004-debug-console-in-debug-builds.md

@@ -0,0 +1,23 @@
+# A Debug Console over Wi-Fi, in Debug Builds only
+
+The goal of Firmware Updates is to manage the device without a cable, and that includes finding out what went wrong. So a **Debug Build** (`cardputer-adv-debug`, `-DRORO_DEBUG`, version suffix `+debug`) adds a **Debug Console** on TCP 2323: the serial console, over Wi-Fi. A client sends a token as its first line, then gets the last 4 KB of console output (boot messages included), every new line live, and runs the same commands as the serial port, plus a few that only make sense remotely. ESP-IDF's own log lines are teed into it.
+
+It's compiled out of release builds entirely, rather than switched off by a setting. A console that runs commands is a remote control: in a release build, nothing listens.
+
+## How it fits
+
+- **Console, not Serial.** All human-readable output goes through `console`, which writes to the USB port and, in a Debug Build, to a ring buffer the Debug Console drains. Writes never wait for USB: a host that's attached but not reading used to stall the main loop for up to 2 s per line.
+- **Commands run on the main loop.** The socket lives on the Debug Console's own task, which only queues command lines. The main loop runs them, as it does serial commands, so they touch Apps and Services from the one task allowed to.
+- **The token** is 128 random bits in `~/.config/roro9stack/debug-token`, made by the first build and passed into the container. It's never committed; a Debug Build refuses to compile without one. Like the OTA key, it guards against the network, not against someone holding the device.
+- **One client at a time**, to keep memory flat (4 KB for the ring since M2, 6 KB of task stack).
+- **Binary commands are answered on the console's own task**, not queued: `get`/`put` (SD card files, run as one Storage Service job each so card access stays on the storage task, with TCP doing the flow control), `screenshot` (the 32 KB RGB332 frame the UI composes into, read as it stands, so it may tear), `coredump get` and `reset`. These keep working when the main loop is stuck. A failed `put` closes the connection, so the rest of the file is never read as commands.
+
+## Keep a Debug Build in the fallback slot
+
+Rollback returns to the previous firmware, whatever it is. As long as development goes through Debug Builds, the firmware a crash falls back to has the Debug Console, so a bad update never costs remote access. A release build pushed over a Debug Build leaves the Debug Build in the other slot until the next update overwrites it.
+
+## Consequences
+
+- Anyone on the same network with the token can read the console, inject keys and reboot the device. The console never prints stored secrets (Wi-Fi and IRC passwords), but the IRC traffic it shows is readable.
+- The TCP stream is plain text: fine on a home network, not across the internet.
+- `+debug` versions compare equal to their release counterparts, so moving between the two is never refused as a downgrade.

docs/adr/0005-safe-mode-crash-reports-watchdog.md

@@ -0,0 +1,13 @@
+# Safe Mode, crash reports and a watched main loop, in every build
+
+Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. Without a cable, such a device would restart forever. Three measures, in release and Debug Builds alike, keep it reachable:
+
+- **Safe Mode.** The firmware counts starts that follow a crash (panic or watchdog) in NVS, first thing at boot. After 3 in a row, it starts only the clock, Wi-Fi, the Update Service and, in a Debug Build, the Debug Console: no Apps, no IRC, no SD card, and a screen that says so with the address to push an update to. Any normal restart (a `reboot`, an update), or a minute of uptime, resets the count.
+- **Crash reports.** The same boot record keeps which version was running, so after a crash the firmware knows which one crashed, even when a Rollback has switched slots since. ESP-IDF already writes a core dump to its flash partition on a panic; after the restart the firmware prints its summary (task, PC, reason, backtrace) and raises a Notification. The `crash` command shows it again later. In a Debug Build, `scripts/rdbg.py crash` decodes the backtrace and `scripts/rdbg.py coredump` fetches the whole dump for `esp-coredump`, against the ELF of that exact build (`.pio/elves/`, named by version and ELF digest).
+- **The main loop is watched.** Arduino-ESP32 subscribes only core 0's idle task to the task watchdog, and the main loop runs on core 1: a stuck loop used to hang the device for good, with the screen frozen and the Debug Console unable to run commands. `enableLoopWDT()` makes a loop stuck for 5 s a panic, with a core dump, counted towards Safe Mode. And an installed update no longer depends on the main loop: the Update Service restarts into it by itself after 90 s.
+
+## Consequences
+
+- Nothing in the main loop may block for 5 s. Network and card work already run on their own tasks.
+- Safe Mode can't help when Wi-Fi or the Update Service itself is what crashes; that still needs USB.
+- Three crashes within a minute of each restart are needed to reach Safe Mode, so a crash loop costs about half a minute before the device becomes reachable.

docs/adr/0006-framework-rebuilt-for-smaller-tls-buffers.md

@@ -0,0 +1,19 @@
+# The framework is rebuilt with our own SDK settings, for smaller TLS buffers
+
+Arduino-ESP32 ships its ESP-IDF libraries prebuilt, with one `sdkconfig` for every ESP32-S3 board. Its TLS settings give every connection a 16 KB receive buffer and a 16 KB send buffer for its whole life. On a device with no PSRAM and about 340 KB of RAM, an IRC connection over TLS left a 12.6 KB low in M2, against a 40 KB floor.
+
+Those settings are compiled into the libraries, so changing them means rebuilding them. pioarduino supports this as a "hybrid compile": `custom_sdkconfig` in `platformio.ini` lists the settings, and the build regenerates the framework's libraries from ESP-IDF (the same 5.5.5 the prebuilt ones come from) before building the app. We set:
+
+- `MBEDTLS_ASYMMETRIC_CONTENT_LEN`, with 16 KB to receive (servers send full TLS records) and **4 KB to send** (IRC lines are short): 12 KB less per connection.
+- `MBEDTLS_DYNAMIC_BUFFER`, `DYNAMIC_FREE_CONFIG_DATA`, `DYNAMIC_FREE_CA_CERT`: buffers allocated when needed, and handshake-only data (the CA chain) freed once connected.
+
+The rebuild also follows the board definition instead of the generic one: PSRAM support is off (the Cardputer ADV has none) and the flash size is 8 MB.
+
+## Consequences
+
+- With IRC connected over TLS, a Debug Build has 78 KB free and a 59 KB low (it was 31 KB and 12.6 KB), and 46 KB at the lowest under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get).
+- The first build after a fresh checkout, or after changing `custom_sdkconfig`, takes about 4 minutes instead of 45 s: it downloads ESP-IDF into the PlatformIO volume and compiles it. Later builds reuse it.
+- Everything the firmware depends on was checked in the regenerated `sdkconfig`: app rollback, core dumps to flash (ELF), the 5 s task watchdog, FreeRTOS run-time stats, the certificate bundle.
+- The project now owns its partition table (`default_8MB.csv`, identical to the framework's), which the hybrid build requires. Changing it would break updates over the air: the app slots must stay where they are.
+- Generated files (`sdkconfig.*`, `managed_components/`, `.dummy/`) are ignored by git.
+- A TLS server that sends records over 16 KB would still fail, as before; one that needs us to send records over 4 KB would now fail. Neither happens with IRC.

docs/adr/0007-own-copy-of-the-sd-driver.md

@@ -0,0 +1,20 @@
+# Our own copy of the SD driver, for one missing byte
+
+Arduino-ESP32's `SD` library talks to the card over SPI through `sd_diskio.cpp`. That driver gives up on a write without saying why, and about once in 1,500 multi-block writes it gave up on one that had worked (issue #21). A 1.7 MB upload failed about three times in ten; before M3, the retry on top of it then filled the gap with zeros.
+
+The cause, measured with a driver that records where it stops: after the "Stop Tran" token that ends a multi-block write, a card takes about a byte of clock to signal busy. The driver deselects, selects again, and reads one byte to see whether the card is ready. Read too early, that byte is 0xFF, "ready"; the status check (CMD13) then goes out while the card is still programming, and its answer (0xFF, 0x1F) is taken for an error. Every failure seen was this one: all blocks accepted, then a status that isn't one. ChaN's reference driver, which FatFs ships as its example, sends a dummy byte after selecting the card for this reason. Arduino's doesn't.
+
+PlatformIO links the framework's library objects directly, so one file can't be replaced from `src`. A project library with the same name takes its place: **`lib/SD` is Arduino-ESP32 3.3.12's SD library (Apache-2.0), with `sd_diskio.cpp` changed** and the other files as they came. The changes are marked `roro:`:
+
+- A dummy byte after selecting the card, before the ready test, and one after Stop Tran.
+- Each place a write gives up records the step and the card's answer (`sd_fault.h`): `info` shows the count, and the Debug Console's `put` prints the detail.
+
+Halving the SPI clock to 10 MHz didn't change the failure rate, so the card stays at 20 MHz.
+
+## Consequences
+
+- 30 uploads of 1.7 MB in a row, each read back and compared by SHA-256, ten of them with the LoRa radio listening on the same bus: no write fault. Before: 3 failures in 10.
+- Every writer gains: Logs, Tracks, Gemini pages, Saved Pages, Captures and Update Files installed from the card all go through this driver, and none of them checked.
+- **The copy has to follow the framework.** When the platform is updated, compare `lib/SD` with the new `libraries/SD` and carry the `roro:` changes over. If upstream fixes the ready test, drop the copy. Reported as [arduino-esp32#12970](https://github.com/espressif/arduino-esp32/issues/12970); issue #39 follows it.
+- One more defect was read in the code and left alone, because nothing here exercises it: the driver tests the card's answer to a data block against 0x0A and 0x0C, values it can't take (accepted is 0x05, CRC error 0x0B, write error 0x0D), so a block rejected for a CRC error is never resent. No such rejection was seen in any failure. If `DataToken` faults ever show in `info`, that's the next fix.
+- A fault is now counted and explained instead of silent, so the next cause, if there is one, starts with evidence.

docs/milestones/G1.md

@@ -0,0 +1,61 @@
+# G1 — Gemini client
+
+**Status:** done, tagged v0.5.0. Every step was checked on the device; reading Saved Pages with Wi-Fi off was checked by hand (2026-10-05).
+
+**Goal:** browse Geminispace from the Cardputer: fetch and read gemtext over TLS, follow links, answer input prompts, keep bookmarks, and save pages to the SD card to read later, offline. A side milestone between M2 and M3, tagged v0.5.0 when done.
+
+Gemini (geminiprotocol.net): one request per TLS connection on port 1965, the request is the URL and CRLF, the response a `<status> <meta>` header line, then the body. Most capsules use self-signed certificates: trust on first use is the norm.
+
+## Decisions (design round 2026-10-05)
+
+| # | Decision |
+|---|---|
+| Q70 | A milestone of its own, **G1**, before M3: plan, tests first, measured on the device, tagged v0.5.0. |
+| Q71 | **TOFU:** the first certificate seen for a host is pinned (SHA-256, in NVS). If it changes, the page isn't shown; a dialog shows both fingerprints and asks whether to trust the new one. Self-signed or expired certificates are fine; only a change counts. |
+| Q72 | Responses: 1x input (11 hidden, for passwords), 2x content, up to 5 redirects (3x), 4x/5x errors with the server's message. 6x (client certificates): "not supported". |
+| Q73 | `text/gemini` is rendered, other `text/*` shown as plain text. Anything else can be saved to `/gemini/downloads/`, not shown. |
+| Q74 | Up to **64 KB on screen**, larger pages truncated with a notice. Saving streams to the card, so a larger page is saved whole. |
+| Q75 | Gemtext rendering: text wrapped to the 40-column screen; `#`/`##`/`###` headings in bold and accent; `*` lists with bullets; `>` quotes indented and muted; preformatted blocks unwrapped, Left/Right to scroll; `=>` links with their label, numbered. |
+| Q76 | Up/Down scroll; Tab and Shift+Tab move between links; Enter follows; Backspace goes back; `g` opens the address line. Links to other protocols show their URL and aren't followed. |
+| Q77 | Back history of 20 URLs in RAM, with scroll positions; going back refetches (or reopens a Saved Page). **Bookmarks** in `/gemini/bookmarks.gmi` (a gemtext page, shown on the start page); `b` adds the current page. Without a card, a built-in start page. |
+| Q78 | Start page: bookmarks, then Saved Pages, then defaults: geminiprotocol.net, a search engine (kennedy.gemi.dev), an aggregator (Cosmos; Antenna was down when measured). |
+| Q79 | UTF-8 decoded; characters outside the Latin-1 fonts shown as `?`. |
+| Q80 | IRC and Gemini can run together: each fetch opens one connection, reads and closes it. If there isn't memory for a second TLS connection, the fetch fails with a clear message and IRC is untouched. Measured in step 1. |
+| Q81 | Debug aid: `gemini get <url>` prints the status, MIME type, size, certificate fingerprint and the first lines. URL resolution (RFC 3986), the response header and gemtext parsing are host-tested. |
+| Q82 | `s` saves the page on screen as a **Saved Page**: `/gemini/saved/<host>/<path>.gmi`, the gemtext as received plus a first line with its URL and save date. Saving again replaces it, and says so. |
+| Q83 | `S` saves the page and the pages it links to, one level deep: gemtext only, same host only, at most 30 pages, in the background with a progress Toast. |
+| Q84 | The start page lists Saved Pages, newest first, grouped by capsule; they open with no network. In a Saved Page, a link to another Saved Page opens the saved copy; other links fetch online if Wi-Fi is up, or say "not saved, offline". A Saved Page shows when it was saved; `r` refreshes it. |
+| Q86 | *Decided after step 1, revised after Q88.* **Two floors:** free heap stays above 40 KB in steady state; a fetch refuses to start below **55 KB** free ("not enough memory: stop IRC or retry"). The firmware's own allocations during a fetch (a page in RAM, a window) keep 20 KB free. With IRC connected, the TLS connection itself can briefly take the heap lower, depending on the server's record sizes: measured 24, 19.5, 15.5 and **13 KB**. *Accepted:* about 12 KB for a moment during a fetch with IRC up, rather than refusing most fetches (a 70 KB start floor) or dropping IRC's connection for each page. |
+| Q87 | *Decided in step 3.* **With a card, every page streams to `/gemini/cache/page.gmi`** in 1 KB pieces while its TLS connection is open; once the connection closes and its ~45 KB is back, the page is loaded into RAM as far as the 40 KB floor allows. The whole page stays on the card (Saved Pages copy it). Without a card, the page goes straight to RAM under the same two floors. Pages are held as lines in 4 KB chunks, never one large block (the largest free block with IRC connected is about 31 KB). |
+| Q88 | *Added after step 6.* **A page bigger than memory allows is read from the card as you scroll.** Opening it, one pass over its file counts the lines, records where every 64th starts (and whether it's inside a preformatted block), and loads the first window. Scrolling near either end of the window reads the next or previous one in the background, keeping the line on top of the screen where it is; the scrollbar follows the whole page. Display pages alternate between two cache files, so the one on screen is never overwritten by the next fetch; background jobs use a third. |
+| Q85 | Saved Pages are deleted from the App only (`d`, with confirmation), never by Storage Clean-up's age rules, like Notes. |
+
+## Measured (step 1)
+
+- `gemini://geminiprotocol.net/`: `20 text/gemini`, 1,184 bytes, TLS handshake 0.7–1.1 s, whole fetch 0.7–1.1 s; kennedy.gemi.dev 1.9 s. The fetch task's stack peaks at about 3.6 KB of 6.
+- **Heap, Debug Build, IRC connected over TLS:** about 68 KB free before a fetch. After the handshake the fetch holds about 32 KB (36–40 KB left); the handshake itself (certificate chain parsed with the 16 KB receive buffer allocated) dips to about **24 KB** for a second or two. Nothing leaks: the heap after matches the heap before.
+- **Step 3, Cosmos (31.6 KB) with IRC connected:** first stopped at 4.6 KB (RAM only, the transfer's 20 KB floor). Streamed to the card: the whole page on the card, 20 KB of it loaded, lowest free heap 19.5 KB during the transfer and 43 KB once loaded. Without IRC: the whole page in RAM. Redirects (Cosmos `31`), input (`10`), not found (`51`) and a changed certificate (refused, both fingerprints shown) all checked on the device.
+- **Steps 4–6 on the device:** Project Gemini and its relative links, Back with the scroll restored, a refused YouTube link; `b` bookmarks, `s` saves (and says when it replaced an older copy), `S` saved 6 of 6 pages, the start page lists both; a Saved Page opens from the card with its origin, its saved links open saved copies, `r` refreshes, `d` asks first; Kennedy's input prompt sent "cardputer" and got 87 results; emoji drawn as `?`.
+- **A bug found there:** refreshing first loaded the whole Saved Page into RAM just to read its origin, next to the App's copy and a TLS connection: the heap fell to 436 bytes. Now only the first line is read, and every fetch (pages, saves, refreshes) checks the 55 KB start floor. Lowest since boot afterwards: 53.8 KB.
+- **Windowed pages (Q88), Cosmos with IRC connected:** 226 of 419 lines in memory at first; paging down loaded lines 192–419 in one window, scrolling back up loaded 64 onwards, then 0 onwards. Window budgets count the memory the old window gives back.
+- **Heap during a fetch with IRC connected:** lowest 13–15.5 KB in later runs (24 and 19.5 KB earlier), the TLS receive buffers varying with the server's records. Accepted (Q86, revised).
+- Antenna (`warmedal.se`) doesn't answer, from the PC either; the default aggregator becomes Cosmos (`gemini://skyjake.fi/~Cosmos/`, which redirects to `cosmos.skyjake.fi`).
+
+## Done when
+
+- `gemini get gemini://geminiprotocol.net/` prints the header, size and fingerprint on the console.
+- The Gemini App opens the start page, follows links (relative ones included), goes back, and follows redirects.
+- An input prompt (e.g. a search) takes a query and shows the results.
+- A changed certificate stops the page and asks.
+- `s` saves a page, `S` a page and its links; with Wi-Fi off, Saved Pages open and their saved links work.
+- Bookmarks are added with `b` and listed on the start page.
+- With IRC connected over TLS, a fetch still works, and the free heap stays above 40 KB.
+
+## Work breakdown
+
+1. **Two TLS connections:** measure the heap with IRC connected while a Gemini fetch runs.
+2. **Parsers** (host-tested): URL parsing and relative resolution, the response header, gemtext lines.
+3. **Fetch** on its own task, with TOFU and `gemini get`.
+4. **Gemini App:** rendering, scrolling, links, history, the address line.
+5. **Input prompts, redirects, bookmarks, downloads.**
+6. **Saved Pages,** then saving with linked pages.

docs/milestones/M0.md

@@ -0,0 +1,89 @@
+# M0 — Skeleton: Launcher, Status Bar, Settings, battery
+
+**Status:** done on 2026-10-02, tagged `v0.1.0`.
+
+## Outcome
+
+Every "Done when" item below works on the device, apart from the gaps listed here. Changes made along the way:
+
+- **Not done, carried over:**
+  - **Charging indicator:** the battery voltage alone can't tell charging apart reliably. Revisit if the hardware exposes a charger status.
+  - **Waking from power-off with a keyboard key:** G0 only for now.
+  - **Status Bar placeholders** for GNSS, mesh, Wi-Fi and unread count are left out until those Services exist (M1, M2, M4).
+- **Added:**
+  - **SD card erase**, in Settings → Storage.
+  - **A Notification wakes an Off screen** (dimmed) while its Toast shows.
+  - **Navigation arrows without Fn** outside Text Entry.
+  - **Serial dev commands** and `scripts/serial_log.sh`.
+- **Measured on the device:**
+  - About 225 KB free heap with the 64 KB frame buffer.
+  - About 15 ms per frame.
+  - 19% of the app flash used.
+
+**Goal:** a firmware you can flash and hold. It boots to a Launcher, shows a live Status Bar, navigates with the keyboard and saves Settings. It proves the App/Service architecture that every later milestone plugs into.
+
+## Done when
+
+- Building, testing and flashing each work with one command, run inside a local Docker container (no toolchain on the host).
+- First boot runs the setup wizard (names, Region, timezone), and later boots skip it.
+- The Launcher lists Apps. Enter starts one, `` ` `` goes back, and Fn+`` ` `` returns home from anywhere.
+- The Status Bar shows battery %, a charging indicator and the clock (relative until set), with placeholders for GNSS, mesh, Wi-Fi and unread count.
+- The Settings App edits and persists: long and short name, Region, timezone, brightness, dim and off timeouts, sound on/off, and probe-request MAC handling (raw by default).
+- An About screen shows the version, free heap, battery voltage, SD status and usage, and uptime.
+- The screen dims at 30 s and turns off at 60 s. Any key wakes it without the key also acting on the App.
+- A long press of G0 powers off (deep sleep). G0 or a key wakes the device.
+- The Compose Key types accented characters in the line editor (`opt` `'` `e` → é).
+- Toast Notifications work. A demo App can raise one, with a beep and LED flash.
+- SD usage is watched: a Storage Warning appears once per boot above 80%. The Log-write cutoff flag is set at 90%, with no Log writers yet.
+
+## Out of scope for M0
+
+Storage Clean-up screen (M1, once IRC Logs exist), any radio, GNSS, Wi-Fi.
+
+## Work breakdown
+
+1. **Project scaffold**
+   - PlatformIO project with the pioarduino platform (Arduino-ESP32 3.x on ESP-IDF 5.x). Board `m5stack-stamps3`, 8 MB partitions, USB-CDC on boot.
+   - Dependencies: `M5Cardputer` (pulls in M5Unified and M5GFX).
+   - `LICENSE` (GPL-3.0), `README.md` with build and flash steps, a version string injected from git at build time (semver tags).
+   - A `native` environment for host-side unit tests (Unity).
+   - **Local CI** in a Docker image with PlatformIO. One script builds the firmware and runs the native tests, and the same container flashes over USB. The repo is hosted on self-hosted Gitea, and a Gitea Actions workflow can reuse this image later.
+2. **Hardware bring-up checks** (manual, on the device)
+   - Display, keyboard (TCA8418) and speaker through M5Cardputer.
+   - Confirm there's no PSRAM, and record the heap at boot.
+   - Investigate the G38 backlight/LED power-rail coupling, then decide how dimming works without killing the LED.
+   - Battery ADC on G10 (×2 divider): calibrate the voltage-to-% curve.
+   - SD card mount on the shared SPI bus (CS=12), behind a bus lock ready for the LoRa radio in M3.
+3. **Core runtime**
+   - **Event bus:** Services publish events (battery changed, notification, storage threshold), and the UI consumes them on the UI task.
+   - **Service interface:** start, stop, periodic tick, state snapshot for the Status Bar.
+   - **App interface:** enter, exit, key event, draw. Plus a registry, so adding an App means one file and one registration line.
+   - **App lifecycle:** one foreground App; Home and Back handling.
+4. **Services for M0**
+   - **Settings store:** typed keys in NVS (internal flash), with defaults and change events.
+   - **Battery Service:** sampled voltage, smoothed %, charging detection if the hardware allows it.
+   - **Clock Service:** no time source yet. API for "set from source X", plus relative-time formatting and Europe/Brussels conversion.
+   - **Storage Service:** SD present/absent, usage %, 80% and 90% thresholds raising events, Log-write permission flag.
+   - **Power Service:** dim and off timers, wake-key swallowing, G0 long-press → deep sleep.
+5. **Widget kit** (ADR 0002): an off-screen buffer pushed to the display.
+   - Status Bar, list, text view, line editor (with the Compose Key), dialog and Toast.
+   - A Latin-1 font set.
+6. **Input layer**
+   - Map key events to logical keys: arrows (Fn + `;` `.` `,` `/`), Back, Home, Select.
+   - Compose Key dead-key state machine. This is pure logic, unit-tested on the host.
+7. **Apps:** Launcher, Settings (including About), first-boot wizard, and a hidden Demo App for exercising Toasts and widgets.
+8. **Docs:** a short walkthrough for a first-time setup: install PlatformIO, USB permissions on Linux, flash, recover via download mode.
+
+## Host-tested logic (TDD candidates)
+
+- Compose Key state machine
+- Battery voltage → % curve and smoothing
+- Storage threshold and once-per-boot warning logic
+- Relative-time formatting and timezone conversion
+- Settings defaults and validation (e.g. Region must be confirmed before any transmit flag)
+
+## Risks to resolve early
+
+- **G38 shared rail:** if the backlight and LED really share power, "screen off" may also need to turn the LED off.
+- **RAM headroom:** the off-screen buffer is 240×135×2 ≈ 64 KB at 16-bit, or about 32 KB at 8-bit. Measure the free heap now, because Wi-Fi + TLS (M1) is the tightest point.
+- **Keyboard library maturity** for the ADV's TCA8418 in `M5Cardputer`. Fall back to Adafruit_TCA8418 directly if needed.

docs/milestones/M1.md

@@ -0,0 +1,70 @@
+# M1 — Wi-Fi Service, Wi-Fi Tools, IRC
+
+**Status:** done on 2026-10-03, tagged `v0.2.0`.
+
+## Outcome
+
+The "Done when" items below work on the device, against irc.libera.chat over TLS, with the following changes.
+
+- **Changed:**
+  - **Wi-Fi Tools is built from ordinary scans only:** networks nearby, channel occupancy and a signal tracker. Monitoring-mode views and captures are deferred (revised Q42). The Monitoring mode stays in the Wi-Fi Service and the IRC pause logic, unused for now.
+  - **The frame buffer is 8-bit colour** (Q46), applied as soon as IRC on TLS measured a 51 KB low.
+- **Not done, carried over:**
+  - **Wi-Fi scan logs** (a CSV of the access points each scan sees) can be recorded from Wi-Fi Tools; monitoring-mode captures remain deferred.
+  - **IRC has no input history** (up-arrow recall). Each Buffer keeps only 50 lines in RAM; the full history is in the Logs.
+- **Measured on the device:**
+  - With Wi-Fi and IRC on TLS: about 92 KB free heap, about 77–81 KB at the lowest. The floor was 40 KB.
+  - 44% of the app flash used.
+  - 231 host tests.
+
+**Goal:** the device joins your Wi-Fi by itself, syncs its clock, keeps an IRC session alive in the background, and gives passive Wi-Fi diagnostics with full-frame captures.
+
+## Decisions (design round 2026-10-02)
+
+| # | Decision |
+|---|---|
+| Q40 | Up to 8 **Saved Networks**, joined strongest-first. Added from a scan or as a hidden network. Open networks are allowed; enterprise (802.1X) is not. |
+| Q41 / Q48 | The Wi-Fi Service stays **Connected** whenever enabled and a Saved Network is in range. Settings has a Wi-Fi On/Off switch. **Monitoring** happens only while Wi-Fi Tools is open; the device reconnects on exit. |
+| Q42 | *Revised 2026-10-02:* Wi-Fi Tools is built from ordinary scans only (access points, channel occupancy, signal tracker). Monitoring-mode views and captures are deferred, to be revisited later. |
+| Q43 | The signal tracker clicks faster as the signal gets stronger. On by default, mutable. |
+| Q44 | IRC shows one Buffer at a time; Tab cycles Buffers. Commands: `/join /part /msg /me /nick /topic /names /quit /raw`. Logs go to `/irc/<network>/<buffer>/YYYY-MM-DD.log`. |
+| Q45 | TLS verifies server certificates against the bundled certificate authorities. Per server, a self-signed certificate can be pinned on first use. |
+| Q46 | If RAM is short: switch the frame buffer to 8-bit colour. Keep the AtomS3 Wi-Fi co-processor in mind. |
+| Q47 | Passwords are stored in NVS without flash encryption (revisit before any public release). |
+| IRC | The **IRC Service** stays connected in the background once the App has started it, until `/quit` or disconnect. It does not start at boot. |
+| Q49 | Opening a Monitoring view while IRC is connected asks first. IRC then pauses, and reconnects and rejoins afterwards; its Buffers show the gap. |
+| Q50 | Reconnects after drops wait 5 s, 10 s, 30 s … up to 5 min. |
+| Q51 | Mentions and private messages raise Notifications. Other traffic only counts as unread (Status Bar shows the total). |
+| M0 | The **Storage Clean-up** screen lands here, once IRC Logs and Captures exist. |
+
+## Done when
+
+- Wi-Fi joins the strongest Saved Network at boot. The Status Bar shows Wi-Fi state, and the clock is set over NTP.
+- Settings → Wi-Fi: On/Off, scan and add a network (with password), add a hidden network, forget a network.
+- The IRC App configures one server (host, port, TLS, nick, SASL or NickServ, auto-join IRC channels). It connects and keeps running after you leave the App. Mentions notify.
+- IRC reconnects after Wi-Fi loss or a server drop, and rejoins its IRC channels. Logs are written to the SD card (and stop past 90% usage).
+- Wi-Fi Tools: access-point list, channel occupancy with the quietest of channels 1/6/11, and a signal tracker that clicks faster as the signal gets stronger. None of it interrupts the connection or IRC.
+- Settings → Storage → Clean-up deletes IRC Logs, probe Logs and Wi-Fi Captures older than a chosen age, with a preview of the space freed.
+- Free heap stays above about 40 KB with Wi-Fi, TLS-connected IRC and the UI running.
+
+## Work breakdown (proposed order)
+
+1. **Memory baseline:** measure the heap with Wi-Fi Connected plus one TLS connection. Switch the frame buffer to 8-bit if the margin is too thin.
+2. **Wi-Fi Service:**
+   - Saved Networks in NVS.
+   - Choosing the network (host-tested).
+   - The Off / Connecting / Connected / Monitoring state machine (host-tested).
+   - NTP → Clock.
+   - Status Bar indicator.
+   - Settings → Wi-Fi pages.
+3. **Log writing:** a Log writer that respects the Storage rules, daily files, and the Storage Clean-up screen (selection logic host-tested).
+4. **IRC Service** (host-tested core):
+   - message parser and serializer;
+   - registration, SASL PLAIN and NickServ;
+   - PING/PONG;
+   - Buffers with unread counts and Mention detection;
+   - reconnect backoff, and pause/resume around Monitoring.
+
+   Then the TLS transport with the certificate bundle.
+5. **IRC App:** Buffer view, input line, command parser (host-tested), server settings page.
+6. **Wi-Fi Tools App:** access-point list, channel occupancy and signal tracker from scans (occupancy and tracker logic host-tested). Monitoring mode is deferred.

docs/milestones/M2.md

@@ -0,0 +1,59 @@
+# M2 — GNSS
+
+**Status:** done on the device (branch `m2`): every "Done when" item below is met.
+
+## Measured
+
+- **Cold start** (`$PCAS10,2`) to a 3D Fix, by a window: **73 s**, 5 satellites used of 8 in view. A restart of the ESP32 alone keeps the receiver's Fix (the Cap stays powered).
+- By a window: 3D Fix from GPS, GLONASS, Galileo and BeiDou, up to 14 of 17 satellites used, HDOP 1.0–1.3.
+- **Heap, Debug Build, GNSS on, IRC on TLS** (floor 40 KB; v0.2.1 had a 79 KB low):
+
+  | | Free | Lowest |
+  |---|---|---|
+  | Start of M2 | 31 KB | 12.6 KB |
+  | Stacks and buffers trimmed by measurement | 46 KB | 18 KB |
+  | mDNS removed | 54 KB | 34 KB |
+  | Framework rebuilt with smaller TLS buffers (ADR 0006) | **78 KB** | **59 KB** |
+
+  Under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get), the low is 46 KB. The cost had come mostly from the OTA and Debug Build work, not GNSS. Stacks were set to measured peak plus about 2 KB (loop 6 KB, update 5, storage 6, irc 6); after a TLS handshake the irc task has 1.7 KB left. IRC can now be stopped by hand (`/quit` in any state, `irc stop`), which frees its TLS memory.
+
+**Goal:** the device knows where it is and what time it is without a network: a GNSS Service in the background, a GNSS App with the position and a sky view of the satellites, the clock set from satellites when there's no NTP, and Tracks recorded to the SD card.
+
+**Hardware:** the Cap LoRa-1262 carries an ATGM336H-6N (AT6668), multi-constellation (GPS, BeiDou, Galileo, GLONASS, QZSS), with a ceramic antenna. NMEA over UART, 115200 8N1. **Measured (step 1, `gnss probe`): RX GPIO 15, TX GPIO 13, 115200 8N1**, as in Meshtastic's board file; M5Stack's page names GPIO 8 and 9, which are the internal I2C bus the keyboard controller sits on. Output is NMEA 4.10 style: `GN` RMC, VTG and GGA, one GSA per constellation with the system ID (1 GPS, 2 GLONASS, 3 Galileo, 4 BeiDou, 5 QZSS) in its last field, and a GSV sequence per constellation and signal (`GP`, `GL`, `GA`, …) with the signal ID last. RMC carries a time even without a Fix (status `V`), so only a Fix makes it trustworthy.
+
+## Decisions (design round 2026-10-04)
+
+| # | Decision |
+|---|---|
+| Q58 | Settings has a GNSS On/Off switch, **On by default**. Off puts the receiver in standby. *Measured:* `$PCAS12,<seconds>` (CASIC) stops its output within a second, for up to at least 65535 s, and any command wakes it within a second; Off sends `PCAS12,65535` (renewed hourly), On sends a hot start, `PCAS10,0`. |
+| Q59 | The **GNSS App** has two views, switched with Tab. *Position*: latitude, longitude, altitude, speed, course, Fix (none / 2D / 3D), satellites used and in view, HDOP, UTC time. *Sky*: the satellites placed by azimuth and elevation, coloured by constellation, filled when used in the Fix. |
+| Q60 | "Radar" in M2 means the Sky view. A radar of other Nodes by distance and bearing needs the mesh: M4. |
+| Q61 | The **Status Bar** shows a GNSS mark: absent when off, muted while searching, normal with a 2D Fix, with the satellite count with a 3D Fix. |
+| Q62 | GNSS time **sets the clock once there's a Fix**, and refreshes it every 10 minutes. *Revised in step 3:* the clock's trust order from M0 (Mesh < NTP < GNSS) already ranks GNSS above NTP, which is right: GNSS time is at least as accurate. So GNSS also corrects a clock NTP set, not only an unset one. |
+| Q63 | A **Track** is started and stopped in the GNSS App. It's written as GPX to `/gnss/tracks/<YYYYMMDD-HHMMSS>.gpx`, a point every 5 s when the position moved more than 5 m. It keeps recording with the App closed, with a Toast on start and stop and a Status Bar mark, and gets its own Storage Clean-up category. |
+| Q64 | Coordinates in **decimal degrees plus the Maidenhead locator**; a Settings switch for degrees, minutes and seconds. Metric units only. |
+| Q65 | **The position never leaves the device in M2.** Sharing it over the mesh, and at what precision, is decided in M4. |
+| Q66 | **Our own NMEA parser**, host-tested: RMC, GGA, GSA and GSV, with each talker ID mapped to its constellation. TinyGPSPlus (named in ADR 0001) doesn't track the satellite list across constellations, which the Sky view needs. |
+| Q67 | The receiver keeps its **defaults** (all constellations, 1 Hz). No receiver settings. Time to first fix is measured and recorded here. |
+| Q68 | Debug aids: `gnss status`, and `gnss nmea on/off` to stream the raw sentences to the console (USB serial and Debug Console). Raw NMEA is never written to the card. |
+
+**Lesson (step 3):** the first probe also tried the pins swapped, driving the receiver's output line from the ESP32 for about a second. The receiver then went silent until a full power cycle (an ESP32 restart doesn't cut the Cap's power). Never drive GPIO 15.
+
+## Done when
+
+- The GNSS Service reads NMEA in the background whatever App is on screen, and a 3D Fix appears outdoors.
+- The GNSS App shows the Position and Sky views, both live.
+- The Status Bar shows the GNSS mark per Q61.
+- With no Wi-Fi, the clock is set from GNSS after the first Fix.
+- A Track records while the App is closed, survives the screen turning off, and opens as valid GPX on the PC.
+- Settings → GNSS Off stops it (and the Status Bar mark goes away); On brings it back.
+- Free heap stays above about 40 KB with GNSS, Wi-Fi, IRC on TLS and the UI running.
+
+## Work breakdown
+
+1. **Hardware check:** a `gnss probe` command reads the candidate UART pins and reports which carries NMEA, at what baud rate, and which talker IDs. Then the standby command (Q58) and a first time to first fix.
+2. **NMEA parser** (host-tested): checksum, RMC, GGA, GSA, GSV across constellations, merged into one GNSS state (Fix, position, time, satellites).
+3. **GNSS Service:** UART on its own task, the parser, `gnss status` and `gnss nmea`, Settings On/Off.
+4. **Clock from GNSS** (Q62), and the Status Bar mark (Q61).
+5. **GNSS App:** Position view, Maidenhead and coordinate formats (host-tested), then the Sky view.
+6. **Tracks:** the 5 s / 5 m rule and GPX writing (host-tested), background recording, Clean-up category.

docs/milestones/M3.md

@@ -0,0 +1,69 @@
+# M3 — Radio bring-up: the LoRa Scanner
+
+**Status:** done, tagged v0.6.0. Everything was checked on the device except one "Done when" item: Sweep was never tried against a known transmitter (see below). The listening hour heard nothing, so by Q104 **a reference Meshtastic node is a requirement for M4**.
+
+**Goal:** the LoRa radio on the Cap works, receive only: a Radio Service owns it and shares the SPI bus with the SD card safely, and a LoRa Scanner App shows what's on the air, either packets (Sniffer) or energy across the band (Sweep). Nothing in M3 can transmit. The mesh comes on top of this in M4 (receive) and M5 (transmit).
+
+**Hardware:** the Cap LoRa-1262 carries an SX1262 (868–923 MHz, +22 dBm) with an RP-SMA antenna. Pins, as in Meshtastic's board file for the Cardputer ADV: **NSS 5, RST 3, DIO1 (IRQ) 4, BUSY 6**, on the SPI bus shared with the microSD card (SCK 40, MISO 39, MOSI 14; card CS 12). Meshtastic uses DIO2 as the RF switch and DIO3 for a 1.8 V TCXO, marked optional. M5Stack's page adds an FM8625H antenna switch enabled by P0 of a PI4IOE5V6408 I/O expander on the internal I2C bus, address not given; Meshtastic doesn't mention it. Step 1 measures which is true.
+
+**No other LoRa device yet.** meshmap.net (2026-10-05) lists two Meshtastic nodes within 10 km of the desk and six within 30 km, with positions blurred by a few km; none is known to be in range. M3 needs none: it only receives.
+
+## Measured
+
+- **Internal I2C bus (8/9):** 0x18 (ES8311 codec), 0x34 (TCA8418 keyboard), **0x43 (PI4IOE5V6408, ID register 0xA2)**, 0x69 (BMI270 IMU).
+- **The SX1262 answers** on NSS 5, RST 3, DIO1 4, BUSY 6. Its version string reads `SX1261 V2D 2D02`, which SX1262 chips report too. **The 1.8 V TCXO works** on the first try; the radio is ready 38 ms after `begin`.
+- **The expander's P0 connects the antenna; it's required.** At power-on P0 is an input (direction 0x00, high-impedance 0xFF), and the receiver reads a flat **-111.9 dBm** at 869.525 MHz, BW 250 kHz: the chip's own floor, deaf. With P0 driven high, the noise floor is **-87 to -94 dBm**: the antenna hearing the room. So the Radio Service drives P0 high at boot (Q91).
+- **DIO2 doesn't change reception** (within ±2 dB over three runs, P0 high). It likely selects TX versus RX in the FM8625H; it stays the RF switch, as in Meshtastic.
+- **The noise floor at the desk is high** (-87 to -94 dBm, varying run to run), about 25 dB above thermal noise for 250 kHz. Something nearby is loud, possibly the Cardputer itself or the PC; Sweep (step 5) should show where it sits.
+- **Step 2:** presets, frequencies and the channel hash are checked against Meshtastic's source (`MeshRadio.h`, `RadioInterface.cpp`): LongFast and the default key give hash 8, MediumFast 31, as Meshtastic shows. Captures were checked with TShark 4.2.5: every LoRaTap field reads back. Wireshark ignores the spec's quarter-dB packet RSSI below 0 dB SNR, so packet RSSI is plain dBm.
+- **Step 3:** the DIO1 interrupt works (a 100 ms receive timeout wakes the task after 105 ms). While listening: four 1.7 MB uploads and Gemini pages to the card, no radio or card errors (the card refuses a write about once in five uploads with the radio asleep too; `put` now catches it, and issue #21 follows the cause). The ring takes 9.8 KB while listening; the radio task's stack peaks at 2.0 KB.
+- **No packets yet, and a loud desk.** Twenty minutes on LongFast and on LoRaWAN's three uplink frequencies (SF7, SF9, SF12): no packet and no header, valid or not. The noise floor reads -83 to -94 dBm, against -112 dBm with the antenna switched off: 20 to 30 dB lost to something nearby, not the screen and not the GNSS receiver. Preamble detections are false alarms at this noise level (more on an empty frequency, 869.0 MHz, than on LongFast).
+- **Step 4:** a Capture made on the device reads back in TShark field for field (time, frequency, SF, RSSI, SNR, payload). A Capture keeps the radio listening with the App closed; stopping it puts the radio back to sleep.
+- **Step 5:** a pass across 863–870 MHz (71 steps, the strongest of three RSSI readings at each, measured at 125 kHz) takes about 607 ms. At the desk the band is **flat at -100 to -102 dBm**, about 15 dB above the chip's own floor at 125 kHz, with a steady carrier at 863.2 MHz (-89 dBm at its strongest) and fainter lines elsewhere: broadband noise from nearby electronics rather than a transmitter. Sweep's waterfall takes 2.6 KB while shown; 91.9 KB free during a Sweep. The radio task's stack peaks at 1.9 KB.
+- **Outside, on battery (step 6).** The noise is no lower than at the desk: a Sweep floor of -96 to -99 dBm (median -97) with Wi-Fi on, -99 to -100 with Wi-Fi off, so Wi-Fi accounts for 2 or 3 dB. The same narrow peaks come back on every pass, at 863.2, 863.6, 864.4, 864.8, 865.9, 866.3, 867.8, 869.0 and 869.4 MHz (-88 to -91 dBm), several of them 400 kHz apart; 869.4 MHz is the lower edge of LongFast's channel. A source that follows the device outside and onto its battery is the device: **about 15 dB of the floor is the Cardputer's own** (issue #20). At SF11 that puts the weakest decodable packet near -114 dBm on LongFast, against about -130 dBm for a quiet receiver.
+- **The listening hour (step 6, Q104):** 20:33 to 21:34 on 2026-10-05, outside, on battery, LongFast, with a Capture running. **0 packets, 0 headers**, 0 radio errors; noise -85 to -87 dBm at 250 kHz throughout; 860 preamble detections, all false alarms. The Capture holds its 24-byte header and nothing else. No restart in 1 h 10 min.
+- **Floors (Q86):** with the radio listening, Wi-Fi and IRC connected over TLS, 52.6 KB free (lowest 22.7 KB during the TLS handshake, the dip accepted in G1). Without IRC, 93 KB.
+- **Receive only:** nothing in `src` or `lib` calls a transmit function.
+- **Cost:** RadioLib 7.8.1 and the probe add 23.6 KB of flash and 656 bytes of static RAM to the release firmware (1,679,843 bytes of 3,342,336). The whole milestone: 51.8 KB of flash (1,708,091 bytes), 365 tests (27 new).
+
+## Decisions (design round 2026-10-05)
+
+| # | Decision |
+|---|---|
+| Q89 | **M3 is the radio only:** Radio Service, Sniffer, Sweep. Notes and the File Browser (Q30) move out to issue #3 and a Notes issue, as a later side milestone. |
+| Q90 | **RadioLib**, pinned (ADR 0001). SX1262 on NSS 5, RST 3, DIO1 4, BUSY 6; DIO2 as RF switch; TCXO at 1.8 V tried first, falling back to the crystal (Meshtastic's `TCXO_OPTIONAL`). |
+| Q91 | Step 1 is `lora probe`: chip status and version, which oscillator setting worked, and an I2C scan of the internal bus for the PI4IOE5V6408. If present, its P0 is set high at boot (harmless) and DIO2 stays the switch. A wrong switch receives deaf, so compare noise floors. |
+| Q92 | A **Radio Service** owns the SX1262: driver, bus lock, IRQ task. The LoRa Scanner uses it in M3; the Mesh Service sits on top of it in M4. |
+| Q93 | Every radio transfer takes the shared bus lock (`SPI.beginTransaction`, as the card does). DIO1's interrupt only wakes the task; no SPI in the ISR. **Done when** a Gemini page streams to the card while the Sniffer receives, with no lost packets and no card errors (`lora status` counters). |
+| Q94 | **Receive only:** the Radio Service has no transmit function in M3. It doesn't exist, rather than being unused. |
+| Q95 | Sniffer defaults: **EU868 LongFast**, 869.525 MHz, BW 250 kHz, SF 11, CR 4/5, sync word 0x2B, preamble 16 (Q19). The other Meshtastic presets are offered, plus custom settings. |
+| Q96 | The Sniffer lists packets (time, RSSI, SNR, frequency error, length; hex dump on Enter) **and decodes the Meshtastic header**: the first 16 bytes are never encrypted (destination, sender, packet ID, hop limit and hop start, channel hash, next hop, relay node). Host-tested. Payload decryption is M4. |
+| Q97 | A Sniffer **Capture** is pcap with **LoRaTap** headers (link type 270), for Wireshark. Started by hand, Status Bar mark, its own Clean-up category, the 90% rule. |
+| Q98 | **Sweep** steps across the Region's band (863–870 MHz) in 100 kHz steps by default, reading instant RSSI: bars with peak hold, and a waterfall, Wi-Fi Tools style. Optionally CAD on the preset's frequency to tell LoRa traffic from noise. |
+| Q99 | Sweep takes the radio and pauses the Sniffer, visibly (Q18). From M4 it pauses the Mesh Service the same way. |
+| Q100 | The Sniffer runs while the App is open **or a Capture is recording**; otherwise the radio sleeps. From M4 the Mesh Service keeps it on. |
+| Q101 | **Status Bar:** a radio mark while receiving, flashing on each packet; muted during a Sweep. |
+| Q102 | Debug aids: `lora status` (settings, counters, last RSSI/SNR, noise floor), `lora probe`, `lora rx on/off` (packets on the consoles). Raw packets are never written to the card outside a Capture. |
+| Q103 | A ring of the **last 32 packets** in RAM (about 9 KB at full length); older ones are dropped unless capturing. IRQ task stack trimmed by measurement; RadioLib's flash and RAM measured in step 1 against the floors. |
+| Q104 | **Done when** (below) includes an hour of listening on LongFast by a window. Real packets heard become M4 test fixtures. If none are heard, M3 still closes, and a reference Meshtastic node (Q21) becomes a requirement for M4. |
+
+## Done when
+
+- `lora probe` reports the SX1262, its oscillator setting and the RF switch arrangement, and the result is written here.
+- The Sniffer receives on LongFast with the App open or a Capture running, and the radio sleeps otherwise.
+- Sweep shows the noise floor across 863–870 MHz, and a known signal (a remote key fob, a 868 MHz sensor, anything) stands out. *Half met: the floor and the device's own steady peaks show; no known transmitter was tried.*
+- The shared-bus test passes (Q93): a Gemini page to the card while the Sniffer receives, no lost packets, no card errors.
+- A Capture opens in Wireshark with LoRaTap fields.
+- The Status Bar mark follows Q101.
+- One hour of LongFast listening by a window has been run and its result recorded here. *Run outside, on battery.*
+- Free heap stays above the floors (Q86) with the Sniffer, Wi-Fi, IRC on TLS and the UI running.
+- Nothing in the firmware can transmit.
+
+## Work breakdown
+
+1. **Hardware check:** RadioLib in the build, `lora probe` (Q91), flash and RAM cost measured.
+2. **Meshtastic header and LoRaTap** (host-tested): header parsing, presets and their radio settings, pcap/LoRaTap writing.
+3. **Radio Service:** receive on its own task behind the bus lock, the packet ring, `lora status` and `lora rx`, the shared-bus test.
+4. **LoRa Scanner App, Sniffer:** the packet list, details, preset choice, Captures, Status Bar mark.
+5. **Sweep:** the RSSI sweep, bars and waterfall, pausing the Sniffer.
+6. **Listening hour** and the measurements above, recorded here.

docs/milestones/OTA.md

@@ -0,0 +1,33 @@
+# OTA — Firmware Updates over Wi-Fi and from the SD card
+
+**Goal:** install new firmware without a USB cable. Push it from the PC over Wi-Fi, or drop it on the SD card. Unsigned images are refused, and a broken update rolls back by itself.
+
+## Decisions (design round 2026-10-03)
+
+| # | Decision |
+|---|---|
+| Q52 | Two sources: **push over Wi-Fi** from the PC, and **from the SD card**. Pulling from Gitea releases is deferred. |
+| Q53 | **Signed Update Files** (ECDSA P-256 over SHA-256). The private key stays in `~/.config/roro9stack/`, and the firmware embeds the public key (ADR 0003). |
+| Q54 | The device **always listens** for pushes on the LAN while Wi-Fi is Connected. *Revised in M2:* it was announced over mDNS as `roro9stack-<id>.local`; mDNS was removed to save RAM (it never crossed the dev box's routed network anyway). Pushes go to the IP shown in Settings → Firmware. |
+| Q55 | New firmware runs on **Probation**. It's confirmed once booted, UI drawn, Services started, 30 s without a crash, and Wi-Fi connected (if configured). Otherwise **Rollback**. A Toast reports either outcome. |
+| Q56 | **Downgrades are allowed**, with "older than the installed version" shown. |
+| Q57 | A valid push **installs right away**: progress screen, then reboot. The reboot waits for Text Entry to end, 60 s at most. |
+
+## Done when
+
+- `scripts/ota_keygen.sh` creates the key pair once. The public key is committed; the private key never is.
+- `scripts/flash.sh --ota` builds, signs and pushes to `roro9stack-<id>.local`. The device shows progress, reboots, and a Toast confirms the new version.
+- An Update File with a bad signature, a truncated or corrupted image, or no signature is refused, and the device keeps running.
+- Settings → About → **Update from SD** lists the `.ota` files in `/updates` and installs one.
+- A firmware that crashes during Probation rolls back to the previous version, and says so after the reboot.
+
+## Work breakdown
+
+1. **Update File format** (host-tested): header (magic, format, version, image size, SHA-256), signature, image. A streaming parser that hashes as it goes and decides accept / refuse / downgrade. The signature verifier sits behind an interface, so tests can inject one.
+2. **PC side:** key generation, `make_ota.py` (wraps `firmware.bin` into a signed `.ota`), and the push client. `flash.sh --ota` ties them together.
+3. **Device:** the Update Service.
+   - A listener on TCP 3232 plus mDNS.
+   - Writes the image to the inactive app slot, with the ECDSA check through mbedTLS.
+   - A progress screen, and a reboot that waits out Text Entry.
+4. **Probation and Rollback:** the health checks, confirming the image, and detecting a rollback after reboot to report it.
+5. **Update from SD:** the same parser, fed from the Storage Service's task (all card access stays there).

docs/milestones/S1.md

@@ -0,0 +1,138 @@
+# 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.
+
+**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.
+
+## Fixed IPv4, DNS and NTP (issue #7)
+
+Not every network has a DHCP server: a lab bench, a direct link to a router, a network where addresses are handed out by hand. Until now every Saved Network used DHCP, DNS always came from DHCP, and the NTP server was `pool.ntp.org`, hard-coded.
+
+**IPv4 only.** IPv6 isn't part of this, now or as a planned follow-up.
+
+### Decisions (design round 2026-10-05)
+
+| # | Decision |
+|---|---|
+| Q105 | The IP setting is **per Saved Network**: *Automatic* (DHCP, as before) or *Fixed*, with its own address, prefix and gateway. New networks start Automatic. |
+| Q106 | The subnet is entered as a **prefix length** (`24`), with the mask shown next to it. |
+| Q107 | The **gateway is optional**: left empty, the device talks to its own subnet only. |
+| Q108 | **DNS is global:** two servers in Settings, used on every Fixed network. On Automatic networks DHCP's DNS is used, unless **"Always use my DNS"** is on. |
+| Q109 | DNS defaults: **9.9.9.9** (Quad9), then **1.1.1.1** (Cloudflare). |
+| Q110 | **NTP is global:** two servers in Settings, names or addresses, defaulting to `pool.ntp.org` and `time.cloudflare.com`. NTP servers offered by DHCP are used first. GNSS still outranks NTP for the clock. |
+| Q111 | What's typed is checked, host-tested in `lib/wifi`: an address is four numbers from 0 to 255; a prefix is 1 to 30; the address isn't the subnet's network or broadcast address; the gateway is inside the subnet and isn't the device's own address. Refusals say why. |
+| Q112 | Addresses are typed in the line editor, limited to digits and dots. |
+| Q113 | Enter on a Saved Network opens **its page** (IP, Address, Prefix, Gateway, Forget) instead of asking to forget it. Settings > Wi-Fi gains DNS servers, "Always use my DNS" and NTP servers. The Status row opens **connection details**: address, mask, gateway, DNS and NTP in use, and where each came from. |
+| Q114 | A change applies **at once**: the network in use reconnects with the new settings. No automatic way back; the keyboard still works if Wi-Fi is cut. |
+| Q115 | Console: `wifi status` shows address, gateway, DNS, NTP and their sources; `wifi ip <ssid> dhcp`, `wifi ip <ssid> <address>/<prefix> [gateway]`, `wifi dns <a> [b]`, `wifi ntp <a> [b]`. Debug Builds: `wifi ip … try 60` goes back to the previous setting after 60 s unless confirmed with `wifi ip keep`. |
+| Q116 | Left out: checking whether the address is already taken, and per-network DNS. |
+
+The SDK already allows 3 NTP servers and 3 DNS servers and can take NTP servers from DHCP (`CONFIG_LWIP_SNTP_MAX_SERVERS=3`, `CONFIG_LWIP_DHCP_GET_NTP_SRV=y`), so the framework isn't rebuilt for this.
+
+### Done when
+
+- A Saved Network set to Fixed joins with that address, mask and gateway, and the device reaches the internet (IRC, Gemini, NTP) through the DNS servers from Settings.
+- Set back to Automatic, it gets its address from DHCP again.
+- With "Always use my DNS" on, an Automatic network resolves through the servers from Settings.
+- The NTP servers from Settings set the clock.
+- Wrong entries are refused with a reason, in Settings and on the console.
+- Connection details show what's in use and where it came from.
+- Tested on `knbg-guests` with 10.39.39.12 (the device's DHCP lease) and 10.39.39.13 (free: the device is alone on that network).
+
+### Measured (2026-10-05 and 06, on `knbg-guests`)
+
+The network is 10.39.39.0/24, gateway 10.39.39.1; DHCP gives 10.39.39.1 as DNS and offers no NTP server.
+
+- **Fixed 10.39.39.12/24** (the device's own lease) and **Fixed 10.39.39.13/24**, gateway 10.39.39.1: the device joins with that address, DNS is 9.9.9.9 and 1.1.1.1 from Settings, and a Gemini page loads (name resolution, routing, TLS). On .13, .12 no longer answers.
+- **A wrong gateway** (10.39.39.254) on a 60 s trial: the device stops answering from another subnet, and comes back by itself with the previous setting.
+- **Back to Automatic:** 10.39.39.12 by DHCP again, DNS 10.39.39.1 from DHCP.
+- **"Always use my DNS"** on an Automatic network: DNS becomes 9.9.9.9 and 1.1.1.1; switched off, the device joins again and has DHCP's DNS back.
+- **NTP:** `pool.ntp.org` answers; set to `time.cloudflare.com` alone, that one answers within 25 s.
+- **Refusals**, on the console and in Settings: the network's own address, a gateway outside the subnet, a prefix of 31 or 99, 10.39.39.300, an unknown network, a DNS name where an address is needed, a host name with an underscore.
+- **In Settings:** the network's page pre-fills Fixed with the address, prefix and gateway in use; leaving the page applies it; connection details show each value and where it came from.
+- **Not tested:** NTP servers offered by DHCP (this network offers none), and a Fixed network with no gateway.
+
+### Work breakdown
+
+1. **IPv4 logic** (host-tested): parsing and formatting addresses, prefix and mask, the checks of Q111.
+2. **Storage:** the IP setting in each Saved Network; DNS, "Always use my DNS" and NTP in Settings.
+3. **Wi-Fi Service:** apply it when joining; DNS and NTP; `wifi status` and the console commands.
+4. **Settings:** the network page, the DNS and NTP rows, connection details.
+5. **Tests on the device**, recorded here.
+
+## System Monitor (issue #11)
+
+Every milestone so far was driven by measurements, heap floors, stack sizes, TLS dips, that needed a Debug Build and a computer. The System App shows them on the device, in any build.
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q117 | An App of its own, **System**, in release builds too. Read-only. |
+| Q118 | Four views, switched with Tab: **Overview** (CPU per core, memory, network, battery), **Tasks**, **Memory**, **System**. |
+| Q119 | Sampled once a second. A task's share is its run time over the last second; a core's load is 100 % minus its idle task's share. |
+| Q120 | **History only while the App is open:** two minutes at one sample a second, about 1 KB. The system already keeps what matters afterwards: the lowest free heap since boot and each task's lowest free stack. |
+| Q121 | **Bytes are counted per service:** IRC, Gemini, the Debug Console and Firmware Updates add what they read and write to a shared counter. The network view shows the connection details, each service's bytes in and out, and the signal strength. |
+| Q122 | Tasks: name, core, share, state and lowest free stack, sorted by share; `s` cycles the sort (share, stack, name). **Under 512 bytes of stack left shows in the warning colour.** |
+| Q123 | Memory: free heap, lowest since boot, largest free block, and a two-minute graph of free heap **with the floors of Q86 drawn as lines** (55, 40 and 20 KB). |
+| Q124 | System: uptime and why it last started, firmware and both app slots, chip temperature and CPU frequency, battery voltage and percentage, SD usage and write faults, the radio's and the GNSS receiver's state. |
+| Q125 | `info` and `tasks` are split into a **snapshot** that the console and the App share; the arithmetic (shares from two samples, sorting, the stack warning) is host-tested. |
+| Q126 | Left out: acting on tasks, an event log, exporting snapshots to the card. |
+| Q127 | The main loop uses about 81 % of a core. The App shows it; fixing it is issue #40, not part of #11. |
+
+The App has five views, not four: Q121's network view is one of its own (Overview, Tasks, Memory, Network, System).
+
+### Measured (2026-10-06)
+
+- **Traffic counters are exact.** A Gemini fetch of a 164,970-byte page counts 164,986 bytes in (the page and its 16-byte header line) and 42 out (the 40-character URL and CRLF). A 1,797,760-byte upload counts 1,798,123 in for the Debug Console, commands included.
+- **The Memory view shows a TLS dip as it happens.** Starting IRC and a 165 KB Gemini fetch together: free heap falls from about 100 KB through the three floors to a low of 12.1 KB, then settles near 50 KB. That's the dip accepted in G1 (Q86).
+- **A run-time counter only moves when its task is switched out.** FreeRTOS adds to a task's run time at the context switch. The main loop takes the samples, and with core 1 to itself it's never switched out: its counter said 2 % while the core's idle task had 0 %. So the task that samples gets what's left of its core. With that: **the main loop uses 100 % of core 1 at rest** (issue #40 said 81 %, an average since boot).
+- **`tasks` on the console** sampled twice inside one command at first, a quarter second apart, and showed the loop at 1 %: it was asleep in the command's own wait. It now samples, lets the loop run for a second, and prints.
+- **Low stack, flagged:** `IDLE0` (232 bytes left), `IDLE1` (328 to 352) and `spk_task` (256 to 264), all the framework's own tasks.
+- **Cost:** 15.6 KB of flash for the App and the counters (1,742,723 bytes, release). Nothing while it's closed; about 2 KB of history and samples while it's open.
+
+## The main loop rests (issue #40)
+
+The loop polled the keyboard, ticked the Services, ran the consoles and redrew when needed, then came straight back: 50,000 passes a second, and core 1 100 % busy with the device idle and the screen off.
+
+Nothing needs that. The keyboard controller buffers key events; the consoles and the radio have their own tasks or interrupts; no Service asks for a tick more often than every 50 ms. So after each pass the loop now rests: **5 ms with the screen on, 20 ms with it off**, and not at all during a serial file transfer (`sd put`), which reads its bytes from the loop. Safe Mode's loop rests 5 ms too. Debug Builds have `loop spin on|off` to bring the old behaviour back for comparison.
+
+### Measured (2026-10-06, Debug Build, Wi-Fi connected, GNSS on, on USB power)
+
+| | Spinning | Resting |
+|---|---|---|
+| Passes a second, screen off | 50,160 | 50 |
+| Core 1 load, screen off | 100 % | 1 % |
+| Passes a second, screen on (Launcher) | 1,203 | 167 |
+| Core 1 load, screen on | 62 % | 10 % |
+| Chip temperature at rest, settled | 38.3 C | 34.3 C |
+| A 1.8 MB upload over the Debug Console | about 230 KB/s | 288 KB/s |
+
+- Still working at this pace: GNSS (a 3D Fix, 22 satellites), a Gemini fetch (52 KB), the upload read back by SHA-256, the Sweep (still 606 to 610 ms a pass), the radio's DIO1 interrupt.
+- **Not measured:** the current drawn (no meter on the battery line), and how typing feels on the real keyboard: a key now waits up to 5 ms for the loop, 20 ms if it's the one that wakes the screen.
+- **The radio's noise floor didn't move** (-97 to -99 dBm at 125 kHz either way): the spinning loop wasn't the source (issue #20).
+- **Not done:** real sleep. The framework is built without power management (`CONFIG_PM_ENABLE` is off), so an idle core only halts until the next interrupt. Automatic light sleep would need the framework rebuilt with it, Wi-Fi in modem sleep, and the USB serial port's behaviour checked. A next step if battery life calls for it.
+
+## The radio's noise: the GNSS receiver (issue #20)
+
+M3 found the LoRa radio's noise floor about 15 dB above what the chip hears alone, and that the source travels with the device. Which part? Debug Builds got a self-test, `lora noise test`: it changes one thing at a time, Sweeps the band eight passes (568 readings), records the median as the floor, and puts the thing back. It runs on the device by itself, because one condition switches Wi-Fi off, and `lora noise report` prints the result afterwards.
+
+### Measured (2026-10-06, indoors, on USB power, dBm at 125 kHz)
+
+| Condition | Floor |
+|---|---|
+| Antenna switched off (the chip alone) | -117 |
+| Antenna on, GNSS in standby | -106 |
+| Antenna on, GNSS running (as shipped) | -98 |
+
+- **The GNSS receiver, while it runs, raises the floor by 8 dB.** Three runs: -98 or -99 with it running, -106 in standby, every time. On LongFast (250 kHz) the Sniffer's own reading goes from about -93.5 to -101.5 dBm.
+- **It's the receiver working, not its serial line:** with one NMEA sentence a second instead of twenty (`PCAS03`), the receiver still tracking, the floor stays at -98.
+- **Nothing else moves it by more than 1 dB**, with GNSS running or in standby: the main loop spinning or resting, the CPU at 240, 160 or 80 MHz, Wi-Fi on or off, the screen on or off, the radio chip's regulator as DC-DC or LDO, its receive gain boosted or not.
+- **11 dB remain** between the antenna connected with GNSS quiet (-106) and the chip alone (-117). It comes in through the antenna and none of those switches changes it: the surroundings, or parts of the Cardputer that can't be switched off. Not separated: that needs another place, or the antenna on a cable away from the case.
+- M3's quick check had GNSS at "1 or 2 dB": it read one frequency for a few seconds, in a noisier spot. The median over the band is the better measure.
+
+### What the firmware does about it
+
+**Settings > Pause GNSS for LoRa**, off by default: while the LoRa radio listens or sweeps, the GNSS receiver waits in standby, and wakes when the radio goes back to sleep (a Fix again after about 7 s here). Never during a Track. The GNSS App says "GNSS is paused" meanwhile. `gnss quiet on|off` on the console.
+
+It's off by default because GNSS on by default was decided in M2 (Q58), and from M4 the radio listens all the time: then "pause while listening" means GNSS mostly off, which is a decision about position, the clock and Tracks, for M4's design round (issue #23).

keys/ota-public.pem

@@ -0,0 +1,4 @@
+-----BEGIN PUBLIC KEY-----
+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIWzT07fvTpQxWjTdewMipYH6f42+
+mM8niHm+T8y+Mvjanb3H8hpYXg3VjuJGFtcHw/hFX0Q2f2AiSHMF0DhMbQ==
+-----END PUBLIC KEY-----

lib/SD/library.json

@@ -0,0 +1,7 @@
+{
+  "name": "SD",
+  "version": "3.3.12",
+  "description": "roro9stack's copy of Arduino-ESP32's SD library (Apache-2.0), shadowing the framework's. Only sd_diskio.cpp is changed (marked \"roro:\"): it records why a write failed and resends a block the card rejects. See issue #21.",
+  "frameworks": "arduino",
+  "platforms": "espressif32"
+}

lib/SD/src/SD.cpp

@@ -0,0 +1,134 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "vfs_api.h"
+#include "sd_diskio.h"
+#include "ff.h"
+#include "FS.h"
+#include "SD.h"
+
+using namespace fs;
+
+SDFS::SDFS(FSImplPtr impl) : FS(impl), _pdrv(0xFF) {}
+
+SDFS::~SDFS() {
+  end();
+}
+
+bool SDFS::begin(uint8_t ssPin, SPIClass &spi, uint32_t frequency, const char *mountpoint, uint8_t max_files, bool format_if_empty) {
+  if (_pdrv != 0xFF) {
+    return true;
+  }
+
+  if (!spi.begin()) {
+    return false;
+  }
+
+  _pdrv = sdcard_init(ssPin, &spi, frequency);
+  if (_pdrv == 0xFF) {
+    return false;
+  }
+
+  if (!sdcard_mount(_pdrv, mountpoint, max_files, format_if_empty)) {
+    sdcard_unmount(_pdrv);
+    sdcard_uninit(_pdrv);
+    _pdrv = 0xFF;
+    return false;
+  }
+
+  _impl->mountpoint(mountpoint);
+  return true;
+}
+
+void SDFS::end() {
+  if (_pdrv != 0xFF) {
+    _impl->mountpoint(NULL);
+    sdcard_unmount(_pdrv);
+
+    sdcard_uninit(_pdrv);
+    _pdrv = 0xFF;
+  }
+}
+
+sdcard_type_t SDFS::cardType() {
+  if (_pdrv == 0xFF) {
+    return CARD_NONE;
+  }
+  return sdcard_type(_pdrv);
+}
+
+uint64_t SDFS::cardSize() {
+  if (_pdrv == 0xFF) {
+    return 0;
+  }
+  size_t sectors = sdcard_num_sectors(_pdrv);
+  size_t sectorSize = sdcard_sector_size(_pdrv);
+  return (uint64_t)sectors * sectorSize;
+}
+
+size_t SDFS::numSectors() {
+  if (_pdrv == 0xFF) {
+    return 0;
+  }
+  return sdcard_num_sectors(_pdrv);
+}
+
+size_t SDFS::sectorSize() {
+  if (_pdrv == 0xFF) {
+    return 0;
+  }
+  return sdcard_sector_size(_pdrv);
+}
+
+uint64_t SDFS::totalBytes() {
+  FATFS *fsinfo;
+  DWORD fre_clust;
+  char drv[3] = {(char)(48 + _pdrv), ':', 0};
+  if (f_getfree(drv, &fre_clust, &fsinfo) != 0) {
+    return 0;
+  }
+  uint64_t size = ((uint64_t)(fsinfo->csize)) * (fsinfo->n_fatent - 2)
+#if _MAX_SS != 512
+                  * (fsinfo->ssize);
+#else
+                  * 512;
+#endif
+  return size;
+}
+
+uint64_t SDFS::usedBytes() {
+  FATFS *fsinfo;
+  DWORD fre_clust;
+  char drv[3] = {(char)(48 + _pdrv), ':', 0};
+  if (f_getfree(drv, &fre_clust, &fsinfo) != 0) {
+    return 0;
+  }
+  uint64_t size = ((uint64_t)(fsinfo->csize)) * ((fsinfo->n_fatent - 2) - (fsinfo->free_clst))
+#if _MAX_SS != 512
+                  * (fsinfo->ssize);
+#else
+                  * 512;
+#endif
+  return size;
+}
+
+bool SDFS::readRAW(uint8_t *buffer, uint32_t sector) {
+  return sd_read_raw(_pdrv, buffer, sector);
+}
+
+bool SDFS::writeRAW(uint8_t *buffer, uint32_t sector) {
+  return sd_write_raw(_pdrv, buffer, sector);
+}
+
+SDFS SD = SDFS(FSImplPtr(new VFSImpl()));

lib/SD/src/SD.h

@@ -0,0 +1,55 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef _SD_H_
+#define _SD_H_
+
+#include "FS.h"
+#include "SPI.h"
+#include "sd_defines.h"
+
+namespace fs {
+
+class SDFS : public FS {
+protected:
+  uint8_t _pdrv;
+
+public:
+  SDFS(FSImplPtr impl);
+  ~SDFS();
+  bool begin(
+    uint8_t ssPin = SS, SPIClass &spi = SPI, uint32_t frequency = 4000000, const char *mountpoint = "/sd", uint8_t max_files = 5, bool format_if_empty = false
+  );
+  void end();
+  sdcard_type_t cardType();
+  uint64_t cardSize();
+  size_t numSectors();
+  size_t sectorSize();
+  uint64_t totalBytes();
+  uint64_t usedBytes();
+  bool readRAW(uint8_t *buffer, uint32_t sector);
+  bool writeRAW(uint8_t *buffer, uint32_t sector);
+};
+
+}  // namespace fs
+
+#if !defined(NO_GLOBAL_INSTANCES) && !defined(NO_GLOBAL_SD)
+extern fs::SDFS SD;
+#endif
+
+using namespace fs;
+typedef fs::File SDFile;
+typedef fs::SDFS SDFileSystemClass;
+#define SDFileSystem SD
+
+#endif /* _SD_H_ */

lib/SD/src/sd_defines.h

@@ -0,0 +1,25 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef _SD_DEFINES_H_
+#define _SD_DEFINES_H_
+
+typedef enum {
+  CARD_NONE,
+  CARD_MMC,
+  CARD_SD,
+  CARD_SDHC,
+  CARD_UNKNOWN
+} sdcard_type_t;
+
+#endif /* _SD_DISKIO_H_ */

lib/SD/src/sd_diskio.cpp

@@ -0,0 +1,949 @@
+// roro9stack's copy of the SD-over-SPI driver from Arduino-ESP32 3.3.12 (libraries/SD/src/
+// sd_diskio.cpp), linked instead of the framework's: defining every function the SD class needs
+// keeps the library's file out of the link. Changes are marked "roro:". Why (issue #21): the
+// original gives up on a write without saying why, and never resends a block the card rejects.
+//
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Disable the automatic pin remapping of the API calls in this file
+#define ARDUINO_CORE_BUILD
+
+#include "Arduino.h"
+#include "sd_diskio.h"
+#include "esp_system.h"
+#include "esp32-hal-periman.h"
+
+extern "C" {
+#include "ff.h"
+#include "diskio.h"
+#if ESP_IDF_VERSION_MAJOR > 3
+#include "diskio_impl.h"
+#endif
+//#include "esp_vfs.h"
+#include "esp_vfs_fat.h"
+
+char CRC7(const char *data, int length);
+unsigned short CRC16(const char *data, int length);
+}
+
+// roro: why the last write failed.
+#include "sd_fault.h"
+static roro::SdFault s_fault;
+static bool sdFault(roro::SdFault::Step step, uint8_t token = 0, uint32_t resp = 0) {
+  s_fault.step = step;
+  s_fault.token = token;
+  s_fault.resp = resp;
+  s_fault.count++;
+  return false;
+}
+namespace roro {
+SdFault sdLastFault() { return s_fault; }
+}  // namespace roro
+
+typedef enum {
+  GO_IDLE_STATE = 0,
+  SEND_OP_COND = 1,
+  SEND_CID = 2,
+  SEND_RELATIVE_ADDR = 3,
+  SEND_SWITCH_FUNC = 6,
+  SEND_IF_COND = 8,
+  SEND_CSD = 9,
+  STOP_TRANSMISSION = 12,
+  SEND_STATUS = 13,
+  SET_BLOCKLEN = 16,
+  READ_BLOCK_SINGLE = 17,
+  READ_BLOCK_MULTIPLE = 18,
+  SEND_NUM_WR_BLOCKS = 22,
+  SET_WR_BLK_ERASE_COUNT = 23,
+  WRITE_BLOCK_SINGLE = 24,
+  WRITE_BLOCK_MULTIPLE = 25,
+  APP_OP_COND = 41,
+  APP_CLR_CARD_DETECT = 42,
+  APP_CMD = 55,
+  READ_OCR = 58,
+  CRC_ON_OFF = 59
+} ardu_sdcard_command_t;
+
+// Align with ESP-IDF sdmmc SPI init (ACMD41 timeout must be >1s per SD spec)
+static constexpr uint32_t sd_go_idle_delay_ms = 20;
+static constexpr uint32_t sd_op_cond_timeout_ms = 3000;
+
+typedef struct {
+  uint8_t ssPin;
+  SPIClass *spi;
+  int frequency;
+  char *base_path;
+  sdcard_type_t type;
+  unsigned long sectors;
+  bool supports_crc;
+  int status;
+} ardu_sdcard_t;
+
+static ardu_sdcard_t *s_cards[FF_VOLUMES] = {NULL};
+
+#if ARDUHAL_LOG_LEVEL >= ARDUHAL_LOG_LEVEL_ERROR
+const char *fferr2str[] = {
+  "(0) Succeeded",
+  "(1) A hard error occurred in the low level disk I/O layer",
+  "(2) Assertion failed",
+  "(3) The physical drive cannot work",
+  "(4) Could not find the file",
+  "(5) Could not find the path",
+  "(6) The path name format is invalid",
+  "(7) Access denied due to prohibited access or directory full",
+  "(8) Access denied due to prohibited access",
+  "(9) The file/directory object is invalid",
+  "(10) The physical drive is write protected",
+  "(11) The logical drive number is invalid",
+  "(12) The volume has no work area",
+  "(13) There is no valid FAT volume",
+  "(14) The f_mkfs() aborted due to any problem",
+  "(15) Could not get a grant to access the volume within defined period",
+  "(16) The operation is rejected according to the file sharing policy",
+  "(17) LFN working buffer could not be allocated",
+  "(18) Number of open files > FF_FS_LOCK",
+  "(19) Given parameter is invalid"
+};
+#endif
+
+/*
+ * SD SPI
+ * */
+
+bool sdWait(uint8_t pdrv, int timeout) {
+  char resp;
+  uint32_t start = millis();
+
+  do {
+    resp = s_cards[pdrv]->spi->transfer(0xFF);
+  } while (resp == 0x00 && (millis() - start) < (unsigned int)timeout);
+
+  if (!resp) {
+    log_w("Wait Failed");
+  }
+  return (resp > 0x00);
+}
+
+void sdStop(uint8_t pdrv) {
+  s_cards[pdrv]->spi->write(0xFD);
+}
+
+void sdDeselectCard(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  digitalWrite(card->ssPin, HIGH);
+}
+
+bool sdSelectCard(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  digitalWrite(card->ssPin, LOW);
+  // roro: one dummy byte before asking whether the card is ready, as ChaN's reference driver does.
+  // A card that has just been given a write takes about a byte of clock to signal busy; without
+  // this, that first byte reads 0xFF, "ready", and the next command (the status check after a
+  // write) goes out while the card is still programming and comes back as garbage (#21).
+  card->spi->transfer(0xFF);
+  bool s = sdWait(pdrv, 500);
+  if (!s) {
+    log_e("Select Failed");
+    digitalWrite(card->ssPin, HIGH);
+    return false;
+  }
+  return true;
+}
+
+char sdCommand(uint8_t pdrv, char cmd, unsigned int arg, unsigned int *resp) {
+  char token;
+  ardu_sdcard_t *card = s_cards[pdrv];
+
+  for (int f = 0; f < 3; f++) {
+    if (cmd == SEND_NUM_WR_BLOCKS || cmd == SET_WR_BLK_ERASE_COUNT || cmd == APP_OP_COND || cmd == APP_CLR_CARD_DETECT) {
+      token = sdCommand(pdrv, APP_CMD, 0, NULL);
+      sdDeselectCard(pdrv);
+      if (token > 1) {
+        break;
+      }
+      if (!sdSelectCard(pdrv)) {
+        token = 0xFF;
+        break;
+      }
+    }
+
+    char cmdPacket[7];
+    cmdPacket[0] = cmd | 0x40;
+    cmdPacket[1] = arg >> 24;
+    cmdPacket[2] = arg >> 16;
+    cmdPacket[3] = arg >> 8;
+    cmdPacket[4] = arg;
+    if (card->supports_crc || cmd == GO_IDLE_STATE || cmd == SEND_IF_COND) {
+      cmdPacket[5] = (CRC7(cmdPacket, 5) << 1) | 0x01;
+    } else {
+      cmdPacket[5] = 0x01;
+    }
+    cmdPacket[6] = 0xFF;
+
+    card->spi->writeBytes((uint8_t *)cmdPacket, (cmd == STOP_TRANSMISSION) ? 7 : 6);
+
+    for (int i = 0; i < 9; i++) {
+      token = card->spi->transfer(0xFF);
+      if (!(token & 0x80)) {
+        break;
+      }
+    }
+
+    if (token == 0xFF) {
+      log_w("no token received");
+      sdDeselectCard(pdrv);
+      delay(100);
+      sdSelectCard(pdrv);
+      continue;
+    } else if (token & 0x08) {
+      log_w("crc error");
+      sdDeselectCard(pdrv);
+      delay(100);
+      sdSelectCard(pdrv);
+      continue;
+    } else if (token > 1) {
+      log_w("token error [%u] 0x%x", cmd, token);
+      break;
+    }
+
+    if (cmd == SEND_STATUS && resp) {
+      *resp = card->spi->transfer(0xFF);
+    } else if ((cmd == SEND_IF_COND || cmd == READ_OCR) && resp) {
+      *resp = card->spi->transfer32(0xFFFFFFFF);
+    }
+
+    break;
+  }
+  if (token == 0xFF) {
+    log_e("Card Failed! cmd: 0x%02x", cmd);
+    card->status = STA_NOINIT;
+  }
+  return token;
+}
+
+bool sdReadBytes(uint8_t pdrv, char *buffer, int length) {
+  char token;
+  unsigned short crc;
+  ardu_sdcard_t *card = s_cards[pdrv];
+
+  uint32_t start = millis();
+  do {
+    token = card->spi->transfer(0xFF);
+  } while (token == 0xFF && (millis() - start) < 500);
+
+  if (token != 0xFE) {
+    return false;
+  }
+
+  card->spi->transferBytes(NULL, (uint8_t *)buffer, length);
+  crc = card->spi->transfer16(0xFFFF);
+  return (!card->supports_crc || crc == CRC16(buffer, length));
+}
+
+char sdWriteBytes(uint8_t pdrv, const char *buffer, char token) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  unsigned short crc = (card->supports_crc) ? CRC16(buffer, 512) : 0xFFFF;
+  if (!sdWait(pdrv, 500)) {
+    return 0;
+  }
+
+  card->spi->write(token);
+  card->spi->writeBytes((uint8_t *)buffer, 512);
+  card->spi->write16(crc);
+  return (card->spi->transfer(0xFF) & 0x1F);
+}
+
+/*
+ * SPI SDCARD Communication
+ * */
+
+char sdTransaction(uint8_t pdrv, char cmd, unsigned int arg, unsigned int *resp) {
+  if (!sdSelectCard(pdrv)) {
+    return 0xFF;
+  }
+  char token = sdCommand(pdrv, cmd, arg, resp);
+  sdDeselectCard(pdrv);
+  return token;
+}
+
+bool sdReadSector(uint8_t pdrv, char *buffer, unsigned long long sector) {
+  for (int f = 0; f < 3; f++) {
+    if (!sdSelectCard(pdrv)) {
+      return false;
+    }
+    if (!sdCommand(pdrv, READ_BLOCK_SINGLE, (s_cards[pdrv]->type == CARD_SDHC) ? sector : sector << 9, NULL)) {
+      bool success = sdReadBytes(pdrv, buffer, 512);
+      sdDeselectCard(pdrv);
+      if (success) {
+        return true;
+      }
+    } else {
+      break;
+    }
+  }
+  sdDeselectCard(pdrv);
+  return false;
+}
+
+bool sdReadSectors(uint8_t pdrv, char *buffer, unsigned long long sector, int count) {
+  for (int f = 0; f < 3;) {
+    if (!sdSelectCard(pdrv)) {
+      return false;
+    }
+
+    if (!sdCommand(pdrv, READ_BLOCK_MULTIPLE, (s_cards[pdrv]->type == CARD_SDHC) ? sector : sector << 9, NULL)) {
+      do {
+        if (!sdReadBytes(pdrv, buffer, 512)) {
+          f++;
+          break;
+        }
+
+        sector++;
+        buffer += 512;
+        f = 0;
+      } while (--count);
+
+      if (sdCommand(pdrv, STOP_TRANSMISSION, 0, NULL)) {
+        log_e("command failed");
+        break;
+      }
+
+      sdDeselectCard(pdrv);
+      if (count == 0) {
+        return true;
+      }
+    } else {
+      break;
+    }
+  }
+  sdDeselectCard(pdrv);
+  return false;
+}
+
+bool sdWriteSector(uint8_t pdrv, const char *buffer, unsigned long long sector) {
+  using roro::SdFault;
+  for (int f = 0; f < 3; f++) {
+    if (!sdSelectCard(pdrv)) {
+      return sdFault(SdFault::Select);  // roro: say why
+    }
+    if (!sdCommand(pdrv, WRITE_BLOCK_SINGLE, (s_cards[pdrv]->type == CARD_SDHC) ? sector : sector << 9, NULL)) {
+      char token = sdWriteBytes(pdrv, buffer, 0xFE);
+      sdDeselectCard(pdrv);
+
+      if (token == 0x0A) {
+        continue;
+      } else if (token == 0x0C) {
+        return sdFault(SdFault::DataToken, token);
+      }
+
+      unsigned int resp;
+      char status = sdTransaction(pdrv, SEND_STATUS, 0, &resp);
+      if (status || resp) {
+        return token != 0x05 ? sdFault(SdFault::DataToken, token, resp) : sdFault(SdFault::Status, status, resp);
+      }
+      return true;
+    } else {
+      break;
+    }
+  }
+  sdDeselectCard(pdrv);
+  return sdFault(SdFault::Command);
+}
+
+bool sdWriteSectors(uint8_t pdrv, const char *buffer, unsigned long long sector, int count) {
+  using roro::SdFault;
+  char token;
+  const char *currentBuffer = buffer;
+  unsigned long long currentSector = sector;
+  int currentCount = count;
+  ardu_sdcard_t *card = s_cards[pdrv];
+  SdFault::Step why = SdFault::Command;  // roro: what stopped it, for the last return
+  uint8_t whyToken = 0;
+
+  for (int f = 0; f < 3;) {
+    if (card->type != CARD_MMC) {
+      char refused = sdTransaction(pdrv, SET_WR_BLK_ERASE_COUNT, currentCount, NULL);
+      if (refused) {
+        return sdFault(SdFault::EraseCount, refused);
+      }
+    }
+
+    if (!sdSelectCard(pdrv)) {
+      return sdFault(SdFault::Select);
+    }
+
+    if (!sdCommand(pdrv, WRITE_BLOCK_MULTIPLE, (card->type == CARD_SDHC) ? currentSector : currentSector << 9, NULL)) {
+      do {
+        token = sdWriteBytes(pdrv, currentBuffer, 0xFC);
+        if (token != 0x05) {
+          f++;
+          break;
+        }
+        currentBuffer += 512;
+        f = 0;
+      } while (--currentCount);
+
+      if (!sdWait(pdrv, 500)) {
+        why = SdFault::BusyAfter;
+        break;
+      }
+
+      if (currentCount == 0) {
+        sdStop(pdrv);
+        card->spi->transfer(0xFF);  // roro: the byte the card takes to go busy after Stop Tran (#21)
+        sdDeselectCard(pdrv);
+
+        unsigned int resp;
+        char status = sdTransaction(pdrv, SEND_STATUS, 0, &resp);
+        if (status || resp) {
+          return sdFault(SdFault::Status, status, resp);
+        }
+        return true;
+      } else {
+        if (sdCommand(pdrv, STOP_TRANSMISSION, 0, NULL)) {
+          why = SdFault::StopCommand;
+          whyToken = token;
+          break;
+        }
+
+        if (token == 0x0A) {
+          sdDeselectCard(pdrv);
+          unsigned int writtenBlocks = 0;
+          if (card->type != CARD_MMC && sdSelectCard(pdrv)) {
+            if (!sdCommand(pdrv, SEND_NUM_WR_BLOCKS, 0, NULL)) {
+              char acmdData[4];
+              if (sdReadBytes(pdrv, acmdData, 4)) {
+                writtenBlocks = acmdData[0] << 24;
+                writtenBlocks |= acmdData[1] << 16;
+                writtenBlocks |= acmdData[2] << 8;
+                writtenBlocks |= acmdData[3];
+              }
+            }
+            sdDeselectCard(pdrv);
+          }
+          currentBuffer = buffer + (writtenBlocks << 9);
+          currentSector = sector + writtenBlocks;
+          currentCount = count - writtenBlocks;
+          continue;
+        } else {
+          why = SdFault::DataToken;
+          whyToken = token;
+          break;
+        }
+      }
+    } else {
+      break;
+    }
+  }
+  sdDeselectCard(pdrv);
+  return sdFault(why, whyToken);
+}
+
+unsigned long sdGetSectorsCount(uint8_t pdrv) {
+  for (int f = 0; f < 3; f++) {
+    if (!sdSelectCard(pdrv)) {
+      return 0;
+    }
+
+    if (!sdCommand(pdrv, SEND_CSD, 0, NULL)) {
+      char csd[16];
+      bool success = sdReadBytes(pdrv, csd, 16);
+      sdDeselectCard(pdrv);
+      if (success) {
+        if ((csd[0] >> 6) == 0x01) {
+          unsigned long size = (((unsigned long)(csd[7] & 0x3F) << 16) | ((unsigned long)csd[8] << 8) | csd[9]) + 1;
+          return size << 10;
+        }
+        unsigned long size = (((unsigned long)(csd[6] & 0x03) << 10) | ((unsigned long)csd[7] << 2) | ((csd[8] & 0xC0) >> 6)) + 1;
+        size <<= ((((csd[9] & 0x03) << 1) | ((csd[10] & 0x80) >> 7)) + 2);
+        size <<= (csd[5] & 0x0F);
+        return size >> 9;
+      }
+    } else {
+      break;
+    }
+  }
+
+  sdDeselectCard(pdrv);
+  return 0;
+}
+
+namespace {
+
+struct AcquireSPI {
+  ardu_sdcard_t *card;
+  explicit AcquireSPI(ardu_sdcard_t *card) : card(card) {
+    card->spi->beginTransaction(SPISettings(card->frequency, MSBFIRST, SPI_MODE0));
+  }
+  AcquireSPI(ardu_sdcard_t *card, int frequency) : card(card) {
+    card->spi->beginTransaction(SPISettings(frequency, MSBFIRST, SPI_MODE0));
+  }
+  ~AcquireSPI() {
+    card->spi->endTransaction();
+  }
+
+private:
+  AcquireSPI(AcquireSPI const &);
+  AcquireSPI &operator=(AcquireSPI const &);
+};
+
+}  // namespace
+
+/*
+ * FATFS API
+ * */
+
+/**
+ * @brief Initialize an SD card for use with FatFs
+ *
+ * This function implements the complete SD card initialization sequence according to
+ * the SD card specification. It performs card detection, type identification,
+ * and configuration for SPI mode operation.
+ *
+ * The initialization sequence follows the SD card protocol (SPI mode, aligned with IDF):
+ * 1. Power-up sequence with 74+ clock cycles
+ * 2. Two GO_IDLE_STATE attempts to enter SPI mode
+ * 3. CRC_ON_OFF to enable CRC checking (with retry)
+ * 4. SEND_IF_COND to identify SDHC/SDXC cards
+ * 5. APP_OP_COND / SEND_OP_COND (SPI args; timeout >1s)
+ * 6. Card type detection (SD/SDHC/MMC)
+ * 7. Final configuration and sector count retrieval
+ *
+ * @param pdrv Physical drive number (0-9)
+ * @return DSTATUS Status of the initialization (0 = success, STA_NOINIT = failed)
+ */
+DSTATUS ff_sd_initialize(uint8_t pdrv) {
+  char token;
+  unsigned int resp;
+  unsigned int start;
+
+  // Get the card structure for the given drive number
+  ardu_sdcard_t *card = s_cards[pdrv];
+
+  // If the card is already initialized, return its current status
+  if (!(card->status & STA_NOINIT)) {
+    return card->status;
+  }
+
+  // Lock the SPI bus and set it to a low frequency (400kHz) for initialization
+  // Low frequency is required during initialization for reliable communication
+  AcquireSPI card_locked(card, 400000);
+
+  // Step 1: Power-up sequence - Send at least 74 clock cycles with CS high and MOSI high
+  // This is required by the SD card specification to ensure proper card state reset
+  // We send 20 bytes (160 clock cycles) to exceed the minimum requirement
+  digitalWrite(card->ssPin, HIGH);
+  for (uint8_t i = 0; i < 20; i++) {
+    card->spi->transfer(0XFF);
+  }
+
+  // Step 2: Perform two GO_IDLE_STATE (CMD0) attempts in SPI mode.
+  // Per SD Simplified Spec (figure 4-1) / IDF: some cards enter SD mode on the
+  // first attempt, so the first response may fail; the second must succeed.
+  // (sdCommand may also retry internally on no-token/CRC errors.)
+  // Fix mount issue - sdWait fail ignored before each CMD0 attempt
+  digitalWrite(card->ssPin, LOW);
+  if (!sdWait(pdrv, 500)) {
+    log_w("sdWait fail ignored, card initialize continues");
+  }
+  (void)sdCommand(pdrv, GO_IDLE_STATE, 0, NULL);
+  sdDeselectCard(pdrv);
+  delay(sd_go_idle_delay_ms);
+
+  digitalWrite(card->ssPin, LOW);
+  if (!sdWait(pdrv, 500)) {
+    log_w("sdWait fail ignored, card initialize continues");
+  }
+  if (sdCommand(pdrv, GO_IDLE_STATE, 0, NULL) != 1) {
+    sdDeselectCard(pdrv);
+    log_w("GO_IDLE_STATE failed");
+    goto unknown_card;
+  }
+  sdDeselectCard(pdrv);
+  delay(sd_go_idle_delay_ms);
+
+  // Step 3: Configure CRC checking
+  // Enable CRC for data transfers in SPI mode (required for reliable communication).
+  // Some cards reject the first CRC_ON_OFF; retry once (same as IDF).
+  token = sdTransaction(pdrv, CRC_ON_OFF, 1, NULL);
+  if (token != 1 && token != 0x5) {
+    delay(10);
+    token = sdTransaction(pdrv, CRC_ON_OFF, 1, NULL);
+  }
+  if (token == 0x5) {
+    // Old card that doesn't support CRC - disable CRC checking
+    card->supports_crc = false;
+  } else if (token != 1) {
+    log_w("CRC_ON_OFF failed: %u", token);
+    goto unknown_card;
+  }
+
+  // Step 4: Card type detection and initialization
+  // Try to identify SDHC/SDXC cards using SEND_IF_COND command
+  if (sdTransaction(pdrv, SEND_IF_COND, 0x1AA, &resp) == 1) {
+    // Card responded to SEND_IF_COND - likely SDHC/SDXC
+    if ((resp & 0xFFF) != 0x1AA) {
+      log_w("SEND_IF_COND failed: %03" PRIX32, (uint32_t)(resp & 0xFFF));
+      goto unknown_card;
+    }
+
+    // Read Operating Conditions Register to check card capabilities
+    if (sdTransaction(pdrv, READ_OCR, 0, &resp) != 1 || !(resp & (1 << 20))) {
+      log_w("READ_OCR failed: %X", resp);
+      goto unknown_card;
+    }
+
+    // Send APP_OP_COND to set operating conditions for SDHC/SDXC.
+    // In SPI mode only HCS (bit 30) is valid; voltage bits must be 0 (same as IDF).
+    // Timeout must be >1s per SD spec (IDF uses ~3s).
+    start = millis();
+    do {
+      token = sdTransaction(pdrv, APP_OP_COND, 0x40000000, NULL);
+    } while (token == 1 && (millis() - start) < sd_op_cond_timeout_ms);
+
+    if (token) {
+      log_w("APP_OP_COND failed: %u", token);
+      goto unknown_card;
+    }
+
+    // Determine if it's SDHC (high capacity) or regular SD
+    if (!sdTransaction(pdrv, READ_OCR, 0, &resp)) {
+      if (resp & (1 << 30)) {
+        card->type = CARD_SDHC;  // High capacity card (SDHC/SDXC)
+      } else {
+        card->type = CARD_SD;  // Standard capacity card
+      }
+    } else {
+      log_w("READ_OCR failed: %X", resp);
+      goto unknown_card;
+    }
+  } else {
+    // Card didn't respond to SEND_IF_COND - try SD or MMC initialization
+    if (sdTransaction(pdrv, READ_OCR, 0, &resp) != 1 || !(resp & (1 << 20))) {
+      log_w("READ_OCR failed: %X", resp);
+      goto unknown_card;
+    }
+
+    // Try SD card initialization first (SPI mode: ACMD41 arg must be 0)
+    start = millis();
+    do {
+      token = sdTransaction(pdrv, APP_OP_COND, 0, NULL);
+    } while (token == 0x01 && (millis() - start) < sd_op_cond_timeout_ms);
+
+    if (!token) {
+      card->type = CARD_SD;  // Standard SD card
+    } else {
+      // Try MMC card initialization (SPI mode: CMD1 arg must be 0)
+      start = millis();
+      do {
+        token = sdTransaction(pdrv, SEND_OP_COND, 0, NULL);
+      } while (token != 0x00 && (millis() - start) < sd_op_cond_timeout_ms);
+
+      if (token == 0x00) {
+        card->type = CARD_MMC;  // MMC card
+      } else {
+        log_w("SEND_OP_COND failed: %u", token);
+        goto unknown_card;
+      }
+    }
+  }
+
+  // Step 5: Clear card detection for SD cards (not needed for MMC)
+  if (card->type != CARD_MMC) {
+    if (sdTransaction(pdrv, APP_CLR_CARD_DETECT, 0, NULL)) {
+      log_w("APP_CLR_CARD_DETECT failed");
+      goto unknown_card;
+    }
+  }
+
+  // Step 6: Set block length for non-SDHC cards
+  // SDHC cards have fixed 512-byte blocks, others need explicit block length setting
+  if (card->type != CARD_SDHC) {
+    if (sdTransaction(pdrv, SET_BLOCKLEN, 512, NULL) != 0x00) {
+      log_w("SET_BLOCKLEN failed");
+      goto unknown_card;
+    }
+  }
+
+  // Step 7: Get card capacity and finalize initialization
+  card->sectors = sdGetSectorsCount(pdrv);
+
+  // Limit frequency to 25MHz for compatibility (SD spec maximum for non-UHS cards)
+  if (card->frequency > 25000000) {
+    card->frequency = 25000000;
+  }
+
+  // Mark card as initialized
+  card->status &= ~STA_NOINIT;
+  return card->status;
+
+unknown_card:
+  // Mark card as unknown type if initialization failed
+  card->type = CARD_UNKNOWN;
+  return card->status;
+}
+
+DSTATUS ff_sd_status(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  AcquireSPI lock(card);
+
+  if (sdTransaction(pdrv, SEND_STATUS, 0, NULL)) {
+    log_e("Check status failed");
+    return STA_NOINIT;
+  }
+  return s_cards[pdrv]->status;
+}
+
+DRESULT ff_sd_read(uint8_t pdrv, uint8_t *buffer, DWORD sector, UINT count) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (card->status & STA_NOINIT) {
+    return RES_NOTRDY;
+  }
+  DRESULT res = RES_OK;
+
+  AcquireSPI lock(card);
+
+  if (count > 1) {
+    res = sdReadSectors(pdrv, (char *)buffer, sector, count) ? RES_OK : RES_ERROR;
+  } else {
+    res = sdReadSector(pdrv, (char *)buffer, sector) ? RES_OK : RES_ERROR;
+  }
+  return res;
+}
+
+DRESULT ff_sd_write(uint8_t pdrv, const uint8_t *buffer, DWORD sector, UINT count) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (card->status & STA_NOINIT) {
+    return RES_NOTRDY;
+  }
+
+  if (card->status & STA_PROTECT) {
+    return RES_WRPRT;
+  }
+  DRESULT res = RES_OK;
+
+  AcquireSPI lock(card);
+
+  if (count > 1) {
+    res = sdWriteSectors(pdrv, (const char *)buffer, sector, count) ? RES_OK : RES_ERROR;
+  } else {
+    res = sdWriteSector(pdrv, (const char *)buffer, sector) ? RES_OK : RES_ERROR;
+  }
+  return res;
+}
+
+DRESULT ff_sd_ioctl(uint8_t pdrv, uint8_t cmd, void *buff) {
+  switch (cmd) {
+    case CTRL_SYNC:
+    {
+      AcquireSPI lock(s_cards[pdrv]);
+      if (sdSelectCard(pdrv)) {
+        sdDeselectCard(pdrv);
+        return RES_OK;
+      }
+    }
+      return RES_ERROR;
+    case GET_SECTOR_COUNT: *((unsigned long *)buff) = s_cards[pdrv]->sectors; return RES_OK;
+    case GET_SECTOR_SIZE:  *((WORD *)buff) = 512; return RES_OK;
+    case GET_BLOCK_SIZE:   *((uint32_t *)buff) = 1; return RES_OK;
+  }
+  return RES_PARERR;
+}
+
+bool sd_read_raw(uint8_t pdrv, uint8_t *buffer, DWORD sector) {
+  return ff_sd_read(pdrv, buffer, sector, 1) == ESP_OK;
+}
+
+bool sd_write_raw(uint8_t pdrv, uint8_t *buffer, DWORD sector) {
+  return ff_sd_write(pdrv, buffer, sector, 1) == ESP_OK;
+}
+
+/*
+ * Public methods
+ * */
+
+uint8_t sdcard_uninit(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (pdrv >= FF_VOLUMES || card == NULL) {
+    return 1;
+  }
+  {
+    AcquireSPI lock(card);
+    sdTransaction(pdrv, GO_IDLE_STATE, 0, NULL);
+  }  // lock is destructed here
+  ff_diskio_register(pdrv, NULL);
+  s_cards[pdrv] = NULL;
+  esp_err_t err = ESP_OK;
+  if (card->base_path) {
+    err = esp_vfs_fat_unregister_path(card->base_path);
+    free(card->base_path);
+  }
+  free(card);
+  return err;
+}
+
+uint8_t sdcard_init(uint8_t cs, SPIClass *spi, int hz) {
+
+  uint8_t pdrv = 0xFF;
+  if (ff_diskio_get_drive(&pdrv) != ESP_OK || pdrv == 0xFF) {
+    return pdrv;
+  }
+
+  ardu_sdcard_t *card = (ardu_sdcard_t *)malloc(sizeof(ardu_sdcard_t));
+  if (!card) {
+    return 0xFF;
+  }
+
+  card->base_path = NULL;
+  card->frequency = hz;
+  card->spi = spi;
+  card->ssPin = digitalPinToGPIONumber(cs);
+
+  card->supports_crc = true;
+  card->type = CARD_NONE;
+  card->status = STA_NOINIT;
+
+  pinMode(card->ssPin, OUTPUT);
+  digitalWrite(card->ssPin, HIGH);
+  perimanSetPinBusExtraType(card->ssPin, "SD_SS");
+
+  s_cards[pdrv] = card;
+
+  static const ff_diskio_impl_t sd_impl = {
+    .init = &ff_sd_initialize, .status = &ff_sd_status, .read = &ff_sd_read, .write = &ff_sd_write, .ioctl = &ff_sd_ioctl
+  };
+  ff_diskio_register(pdrv, &sd_impl);
+
+  return pdrv;
+}
+
+uint8_t sdcard_unmount(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (pdrv >= FF_VOLUMES || card == NULL) {
+    return 1;
+  }
+  card->status |= STA_NOINIT;
+  card->type = CARD_NONE;
+
+  char drv[3] = {(char)('0' + pdrv), ':', 0};
+  f_mount(NULL, drv, 0);
+  return 0;
+}
+
+bool sdcard_mount(uint8_t pdrv, const char *path, uint8_t max_files, bool format_if_empty) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (pdrv >= FF_VOLUMES || card == NULL) {
+    return false;
+  }
+
+  if (card->base_path) {
+    free(card->base_path);
+  }
+  card->base_path = strdup(path);
+
+  FATFS *fs;
+  char drv[3] = {(char)('0' + pdrv), ':', 0};
+
+#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(6, 0, 0)
+  esp_err_t err = esp_vfs_fat_register(path, drv, max_files, &fs);
+#else
+  esp_vfs_fat_conf_t conf = {.base_path = path, .fat_drive = drv, .max_files = max_files};
+  esp_err_t err = esp_vfs_fat_register(&conf, &fs);
+#endif
+
+  if (err == ESP_ERR_INVALID_STATE) {
+    log_e("esp_vfs_fat_register failed 0x(%x): SD is registered.", err);
+    return false;
+  } else if (err != ESP_OK) {
+    log_e("esp_vfs_fat_register failed 0x(%x)", err);
+    return false;
+  }
+
+  FRESULT res = f_mount(fs, drv, 1);
+  if (res != FR_OK) {
+    log_e("f_mount failed: %s", fferr2str[res]);
+    if (res == 13 && format_if_empty) {
+      BYTE *work = (BYTE *)malloc(sizeof(BYTE) * FF_MAX_SS);
+      if (!work) {
+        log_e("alloc for f_mkfs failed");
+        return false;
+      }
+      //FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len);
+      const MKFS_PARM opt = {(BYTE)FM_ANY, 0, 0, 0, 0};
+      res = f_mkfs(drv, &opt, work, sizeof(BYTE) * FF_MAX_SS);
+      free(work);
+      if (res != FR_OK) {
+        log_e("f_mkfs failed: %s", fferr2str[res]);
+        esp_vfs_fat_unregister_path(path);
+        return false;
+      }
+      res = f_mount(fs, drv, 1);
+      if (res != FR_OK) {
+        log_e("f_mount failed: %s", fferr2str[res]);
+        esp_vfs_fat_unregister_path(path);
+        return false;
+      }
+    } else {
+      esp_vfs_fat_unregister_path(path);
+      return false;
+    }
+  }
+  AcquireSPI lock(card);
+  card->sectors = sdGetSectorsCount(pdrv);
+  return true;
+}
+
+uint32_t sdcard_num_sectors(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (pdrv >= FF_VOLUMES || card == NULL) {
+    return 0;
+  }
+  return card->sectors;
+}
+
+uint32_t sdcard_sector_size(uint8_t pdrv) {
+  if (pdrv >= FF_VOLUMES || s_cards[pdrv] == NULL) {
+    return 0;
+  }
+  return 512;
+}
+
+// roro: the card's CID. CMD10 in SPI mode (the enum's SEND_CID, 2, is the SD-mode command).
+namespace roro {
+bool sdReadCid(uint8_t cid[16]) {
+  for (uint8_t pdrv = 0; pdrv < FF_VOLUMES; ++pdrv) {
+    ardu_sdcard_t *card = s_cards[pdrv];
+    if (!card) {
+      continue;
+    }
+    AcquireSPI lock(card);
+    if (!sdSelectCard(pdrv)) {
+      return false;
+    }
+    bool ok = !sdCommand(pdrv, 10, 0, NULL) && sdReadBytes(pdrv, (char *)cid, 16);
+    sdDeselectCard(pdrv);
+    return ok;
+  }
+  return false;
+}
+}  // namespace roro
+
+sdcard_type_t sdcard_type(uint8_t pdrv) {
+  ardu_sdcard_t *card = s_cards[pdrv];
+  if (pdrv >= FF_VOLUMES || card == NULL) {
+    return CARD_NONE;
+  }
+  return card->type;
+}

lib/SD/src/sd_diskio.h

@@ -0,0 +1,34 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef _SD_DISKIO_H_
+#define _SD_DISKIO_H_
+
+#include "Arduino.h"
+#include "SPI.h"
+#include "sd_defines.h"
+// #include "diskio.h"
+
+uint8_t sdcard_init(uint8_t cs, SPIClass *spi, int hz);
+uint8_t sdcard_uninit(uint8_t pdrv);
+
+bool sdcard_mount(uint8_t pdrv, const char *path, uint8_t max_files, bool format_if_empty);
+uint8_t sdcard_unmount(uint8_t pdrv);
+
+sdcard_type_t sdcard_type(uint8_t pdrv);
+uint32_t sdcard_num_sectors(uint8_t pdrv);
+uint32_t sdcard_sector_size(uint8_t pdrv);
+bool sd_read_raw(uint8_t pdrv, uint8_t *buffer, uint32_t sector);
+bool sd_write_raw(uint8_t pdrv, uint8_t *buffer, uint32_t sector);
+
+#endif /* _SD_DISKIO_H_ */

lib/SD/src/sd_diskio_crc.c

@@ -0,0 +1,61 @@
+/* SD/MMC File System Library
+ * Copyright (c) 2014 Neil Thiessen
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const char m_CRC7Table[] = {0x00, 0x09, 0x12, 0x1B, 0x24, 0x2D, 0x36, 0x3F, 0x48, 0x41, 0x5A, 0x53, 0x6C, 0x65, 0x7E, 0x77, 0x19, 0x10, 0x0B, 0x02, 0x3D, 0x34,
+                            0x2F, 0x26, 0x51, 0x58, 0x43, 0x4A, 0x75, 0x7C, 0x67, 0x6E, 0x32, 0x3B, 0x20, 0x29, 0x16, 0x1F, 0x04, 0x0D, 0x7A, 0x73, 0x68, 0x61,
+                            0x5E, 0x57, 0x4C, 0x45, 0x2B, 0x22, 0x39, 0x30, 0x0F, 0x06, 0x1D, 0x14, 0x63, 0x6A, 0x71, 0x78, 0x47, 0x4E, 0x55, 0x5C, 0x64, 0x6D,
+                            0x76, 0x7F, 0x40, 0x49, 0x52, 0x5B, 0x2C, 0x25, 0x3E, 0x37, 0x08, 0x01, 0x1A, 0x13, 0x7D, 0x74, 0x6F, 0x66, 0x59, 0x50, 0x4B, 0x42,
+                            0x35, 0x3C, 0x27, 0x2E, 0x11, 0x18, 0x03, 0x0A, 0x56, 0x5F, 0x44, 0x4D, 0x72, 0x7B, 0x60, 0x69, 0x1E, 0x17, 0x0C, 0x05, 0x3A, 0x33,
+                            0x28, 0x21, 0x4F, 0x46, 0x5D, 0x54, 0x6B, 0x62, 0x79, 0x70, 0x07, 0x0E, 0x15, 0x1C, 0x23, 0x2A, 0x31, 0x38, 0x41, 0x48, 0x53, 0x5A,
+                            0x65, 0x6C, 0x77, 0x7E, 0x09, 0x00, 0x1B, 0x12, 0x2D, 0x24, 0x3F, 0x36, 0x58, 0x51, 0x4A, 0x43, 0x7C, 0x75, 0x6E, 0x67, 0x10, 0x19,
+                            0x02, 0x0B, 0x34, 0x3D, 0x26, 0x2F, 0x73, 0x7A, 0x61, 0x68, 0x57, 0x5E, 0x45, 0x4C, 0x3B, 0x32, 0x29, 0x20, 0x1F, 0x16, 0x0D, 0x04,
+                            0x6A, 0x63, 0x78, 0x71, 0x4E, 0x47, 0x5C, 0x55, 0x22, 0x2B, 0x30, 0x39, 0x06, 0x0F, 0x14, 0x1D, 0x25, 0x2C, 0x37, 0x3E, 0x01, 0x08,
+                            0x13, 0x1A, 0x6D, 0x64, 0x7F, 0x76, 0x49, 0x40, 0x5B, 0x52, 0x3C, 0x35, 0x2E, 0x27, 0x18, 0x11, 0x0A, 0x03, 0x74, 0x7D, 0x66, 0x6F,
+                            0x50, 0x59, 0x42, 0x4B, 0x17, 0x1E, 0x05, 0x0C, 0x33, 0x3A, 0x21, 0x28, 0x5F, 0x56, 0x4D, 0x44, 0x7B, 0x72, 0x69, 0x60, 0x0E, 0x07,
+                            0x1C, 0x15, 0x2A, 0x23, 0x38, 0x31, 0x46, 0x4F, 0x54, 0x5D, 0x62, 0x6B, 0x70, 0x79};
+
+char CRC7(const char *data, int length) {
+  char crc = 0;
+  for (int i = 0; i < length; i++) {
+    crc = m_CRC7Table[(crc << 1) ^ data[i]];
+  }
+  return crc;
+}
+
+const unsigned short m_CRC16Table[256] = {
+  0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50A5, 0x60C6, 0x70E7, 0x8108, 0x9129, 0xA14A, 0xB16B, 0xC18C, 0xD1AD, 0xE1CE, 0xF1EF, 0x1231, 0x0210, 0x3273,
+  0x2252, 0x52B5, 0x4294, 0x72F7, 0x62D6, 0x9339, 0x8318, 0xB37B, 0xA35A, 0xD3BD, 0xC39C, 0xF3FF, 0xE3DE, 0x2462, 0x3443, 0x0420, 0x1401, 0x64E6, 0x74C7,
+  0x44A4, 0x5485, 0xA56A, 0xB54B, 0x8528, 0x9509, 0xE5EE, 0xF5CF, 0xC5AC, 0xD58D, 0x3653, 0x2672, 0x1611, 0x0630, 0x76D7, 0x66F6, 0x5695, 0x46B4, 0xB75B,
+  0xA77A, 0x9719, 0x8738, 0xF7DF, 0xE7FE, 0xD79D, 0xC7BC, 0x48C4, 0x58E5, 0x6886, 0x78A7, 0x0840, 0x1861, 0x2802, 0x3823, 0xC9CC, 0xD9ED, 0xE98E, 0xF9AF,
+  0x8948, 0x9969, 0xA90A, 0xB92B, 0x5AF5, 0x4AD4, 0x7AB7, 0x6A96, 0x1A71, 0x0A50, 0x3A33, 0x2A12, 0xDBFD, 0xCBDC, 0xFBBF, 0xEB9E, 0x9B79, 0x8B58, 0xBB3B,
+  0xAB1A, 0x6CA6, 0x7C87, 0x4CE4, 0x5CC5, 0x2C22, 0x3C03, 0x0C60, 0x1C41, 0xEDAE, 0xFD8F, 0xCDEC, 0xDDCD, 0xAD2A, 0xBD0B, 0x8D68, 0x9D49, 0x7E97, 0x6EB6,
+  0x5ED5, 0x4EF4, 0x3E13, 0x2E32, 0x1E51, 0x0E70, 0xFF9F, 0xEFBE, 0xDFDD, 0xCFFC, 0xBF1B, 0xAF3A, 0x9F59, 0x8F78, 0x9188, 0x81A9, 0xB1CA, 0xA1EB, 0xD10C,
+  0xC12D, 0xF14E, 0xE16F, 0x1080, 0x00A1, 0x30C2, 0x20E3, 0x5004, 0x4025, 0x7046, 0x6067, 0x83B9, 0x9398, 0xA3FB, 0xB3DA, 0xC33D, 0xD31C, 0xE37F, 0xF35E,
+  0x02B1, 0x1290, 0x22F3, 0x32D2, 0x4235, 0x5214, 0x6277, 0x7256, 0xB5EA, 0xA5CB, 0x95A8, 0x8589, 0xF56E, 0xE54F, 0xD52C, 0xC50D, 0x34E2, 0x24C3, 0x14A0,
+  0x0481, 0x7466, 0x6447, 0x5424, 0x4405, 0xA7DB, 0xB7FA, 0x8799, 0x97B8, 0xE75F, 0xF77E, 0xC71D, 0xD73C, 0x26D3, 0x36F2, 0x0691, 0x16B0, 0x6657, 0x7676,
+  0x4615, 0x5634, 0xD94C, 0xC96D, 0xF90E, 0xE92F, 0x99C8, 0x89E9, 0xB98A, 0xA9AB, 0x5844, 0x4865, 0x7806, 0x6827, 0x18C0, 0x08E1, 0x3882, 0x28A3, 0xCB7D,
+  0xDB5C, 0xEB3F, 0xFB1E, 0x8BF9, 0x9BD8, 0xABBB, 0xBB9A, 0x4A75, 0x5A54, 0x6A37, 0x7A16, 0x0AF1, 0x1AD0, 0x2AB3, 0x3A92, 0xFD2E, 0xED0F, 0xDD6C, 0xCD4D,
+  0xBDAA, 0xAD8B, 0x9DE8, 0x8DC9, 0x7C26, 0x6C07, 0x5C64, 0x4C45, 0x3CA2, 0x2C83, 0x1CE0, 0x0CC1, 0xEF1F, 0xFF3E, 0xCF5D, 0xDF7C, 0xAF9B, 0xBFBA, 0x8FD9,
+  0x9FF8, 0x6E17, 0x7E36, 0x4E55, 0x5E74, 0x2E93, 0x3EB2, 0x0ED1, 0x1EF0
+};
+
+unsigned short CRC16(const char *data, int length) {
+  unsigned short crc = 0;
+  for (int i = 0; i < length; i++) {
+    crc = (crc << 8) ^ m_CRC16Table[((crc >> 8) ^ data[i]) & 0x00FF];
+  }
+  return crc;
+}

lib/SD/src/sd_fault.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+// Why the SD driver last gave up on a write (see sd_diskio.cpp, issue #21). The framework's driver
+// fails without saying why; ours records it.
+struct SdFault {
+    enum Step : uint8_t {
+        None,
+        EraseCount,   // ACMD23 before a multi-block write was refused
+        Select,       // the card stayed busy for 500 ms
+        Command,      // the write command itself was refused
+        DataToken,    // the card's answer to a data block: 0x0B CRC error, 0x0D write error
+        BusyAfter,    // still busy 500 ms after the last block
+        Status,       // CMD13 after the write reported an error (resp)
+        StopCommand,  // CMD12 after a rejected block was refused
+    };
+    Step step = None;
+    uint8_t token = 0;   // the driver's or the card's answer at that step
+    uint32_t resp = 0;   // CMD13's status bits, for Status
+    uint32_t count = 0;  // failed writes since boot
+    uint32_t retried = 0;  // blocks resent after a CRC error, since boot
+};
+
+SdFault sdLastFault();
+
+// The mounted card's identity register (CID, CMD10): who made it, its name, serial and date.
+// Call it where card access is allowed (the storage task).
+bool sdReadCid(uint8_t cid[16]);
+
+}  // namespace roro

lib/apps_model/src/settings_menu.cpp

@@ -0,0 +1,154 @@
+#include "settings_menu.h"
+
+#include "choices.h"
+
+namespace roro {
+
+namespace {
+
+using Row = SettingsMenu::Row;
+using Kind = SettingsMenu::Kind;
+
+struct RowDef {
+    Row row;
+    Kind kind;
+    const char* label;
+};
+
+const RowDef kRows[] = {
+    {Row::LongName, Kind::Text, "Long name"},   {Row::ShortName, Kind::Text, "Short name"},
+    {Row::Region, Kind::Choice, "Region"},      {Row::Timezone, Kind::Choice, "Timezone"},
+    {Row::Brightness, Kind::Slider, "Brightness"}, {Row::DimTimeout, Kind::Choice, "Dim after"},
+    {Row::OffTimeout, Kind::Choice, "Screen off after"}, {Row::Sound, Kind::Toggle, "Sound & LED"},
+    {Row::Gnss, Kind::Toggle, "GNSS"}, {Row::GnssQuiet, Kind::Toggle, "Pause GNSS for LoRa"},
+    {Row::Coordinates, Kind::Toggle, "Coordinates"},
+    {Row::ProbeMacs, Kind::Toggle, "Probe MACs"}, {Row::Wifi, Kind::Page, "Wi-Fi"},
+    {Row::Storage, Kind::Page, "Storage"},
+    {Row::Firmware, Kind::Page, "Firmware"},
+    {Row::About, Kind::Page, "About"},
+};
+
+const int kDimSeconds[] = {10, 15, 30, 60, 120, 300};
+const int kOffSeconds[] = {30, 60, 120, 300, 600, 1800};
+
+std::string formatSeconds(int s) { return s < 60 ? std::to_string(s) + " s" : std::to_string(s / 60) + " min"; }
+
+template <size_t N>
+std::vector<std::string> labels(const Choice (&table)[N]) {
+    std::vector<std::string> out;
+    for (auto& c : table) out.push_back(c.label);
+    return out;
+}
+
+template <size_t N>
+std::vector<std::string> durations(const int (&seconds)[N]) {
+    std::vector<std::string> out;
+    for (int s : seconds) out.push_back(formatSeconds(s));
+    return out;
+}
+
+template <size_t N>
+int indexOf(const Choice (&table)[N], const std::string& value) {
+    for (size_t i = 0; i < N; i++)
+        if (value == table[i].value) return static_cast<int>(i);
+    return -1;
+}
+
+template <size_t N>
+int indexOf(const int (&table)[N], int value) {
+    for (size_t i = 0; i < N; i++)
+        if (table[i] == value) return static_cast<int>(i);
+    return -1;
+}
+
+}  // namespace
+
+int SettingsMenu::count() const { return sizeof(kRows) / sizeof(kRows[0]); }
+SettingsMenu::Row SettingsMenu::row(int i) const { return kRows[i].row; }
+SettingsMenu::Kind SettingsMenu::kind(int i) const { return kRows[i].kind; }
+std::string SettingsMenu::label(int i) const { return kRows[i].label; }
+
+std::string SettingsMenu::value(int i) const {
+    switch (row(i)) {
+        case Row::LongName: return settings_.getString(Setting::LongName);
+        case Row::ShortName: return settings_.getString(Setting::ShortName);
+        case Row::Region: return settings_.getString(Setting::Region);
+        case Row::Timezone: {
+            int c = currentChoice(i);
+            return c >= 0 ? kTimezones[c].label : "Custom";
+        }
+        case Row::Brightness: return std::to_string(settings_.getInt(Setting::Brightness)) + "%";
+        case Row::DimTimeout: return formatSeconds(settings_.getInt(Setting::DimTimeoutS));
+        case Row::OffTimeout: return formatSeconds(settings_.getInt(Setting::OffTimeoutS));
+        case Row::Sound: return settings_.getBool(Setting::Sound) ? "On" : "Off";
+        case Row::Gnss: return settings_.getBool(Setting::GnssEnabled) ? "On" : "Off";
+        case Row::GnssQuiet: return settings_.getBool(Setting::GnssQuietForLora) ? "On" : "Off";
+        case Row::Coordinates: return settings_.getBool(Setting::CoordinatesDms) ? "Deg min sec" : "Decimal";
+        case Row::ProbeMacs: return settings_.getBool(Setting::ProbeMacRaw) ? "Raw" : "Pseudonymised";
+        case Row::Wifi: return settings_.getBool(Setting::WifiEnabled) ? "On" : "Off";
+        default: return "";
+    }
+}
+
+std::vector<std::string> SettingsMenu::choices(int i) const {
+    switch (row(i)) {
+        case Row::Region: return labels(kRegions);
+        case Row::Timezone: return labels(kTimezones);
+        case Row::DimTimeout: return durations(kDimSeconds);
+        case Row::OffTimeout: return durations(kOffSeconds);
+        default: return {};
+    }
+}
+
+int SettingsMenu::currentChoice(int i) const {
+    switch (row(i)) {
+        case Row::Region: return indexOf(kRegions, settings_.getString(Setting::Region));
+        case Row::Timezone: return indexOf(kTimezones, settings_.getString(Setting::Timezone));
+        case Row::DimTimeout: return indexOf(kDimSeconds, settings_.getInt(Setting::DimTimeoutS));
+        case Row::OffTimeout: return indexOf(kOffSeconds, settings_.getInt(Setting::OffTimeoutS));
+        default: return -1;
+    }
+}
+
+std::string SettingsMenu::choose(int i, int c) {
+    switch (row(i)) {
+        case Row::Region:
+            settings_.setString(Setting::Region, kRegions[c].value);
+            settings_.setBool(Setting::RegionConfirmed, true);
+            return "";
+        case Row::Timezone: settings_.setString(Setting::Timezone, kTimezones[c].value); return "";
+        case Row::DimTimeout:
+            return settings_.setInt(Setting::DimTimeoutS, kDimSeconds[c]) ? "" : "Dimming must happen before screen off";
+        case Row::OffTimeout:
+            return settings_.setInt(Setting::OffTimeoutS, kOffSeconds[c]) ? "" : "Screen off must come after dimming";
+        default: return "Not a choice";
+    }
+}
+
+void SettingsMenu::toggle(int i) {
+    if (row(i) == Row::Sound) settings_.setBool(Setting::Sound, !settings_.getBool(Setting::Sound));
+    if (row(i) == Row::Gnss) settings_.setBool(Setting::GnssEnabled, !settings_.getBool(Setting::GnssEnabled));
+    if (row(i) == Row::GnssQuiet) settings_.setBool(Setting::GnssQuietForLora, !settings_.getBool(Setting::GnssQuietForLora));
+    if (row(i) == Row::Coordinates) settings_.setBool(Setting::CoordinatesDms, !settings_.getBool(Setting::CoordinatesDms));
+    if (row(i) == Row::ProbeMacs) settings_.setBool(Setting::ProbeMacRaw, !settings_.getBool(Setting::ProbeMacRaw));
+}
+
+void SettingsMenu::adjust(int i, int direction) {
+    if (row(i) != Row::Brightness) return;
+    int next = settings_.getInt(Setting::Brightness) + (direction > 0 ? 10 : -10);
+    if (next < 10) next = 10;
+    if (next > 100) next = 100;
+    settings_.setInt(Setting::Brightness, next);
+}
+
+int SettingsMenu::maxBytes(int i) const {
+    return row(i) == Row::ShortName ? 4 : row(i) == Row::LongName ? 39 : 0;
+}
+
+std::string SettingsMenu::setText(int i, const std::string& text) {
+    Setting s = row(i) == Row::ShortName ? Setting::ShortName : Setting::LongName;
+    if (settings_.setString(s, text)) return "";
+    return "Must be 1 to " + std::to_string(maxBytes(i)) + " bytes";
+}
+
+}  // namespace roro

lib/apps_model/src/settings_menu.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "settings.h"
+
+namespace roro {
+
+// What the Settings App lists: one row per user-facing setting (plus sub-pages), with readable
+// values, choice lists and validation messages. Rendering and navigation live in the App.
+class SettingsMenu {
+   public:
+    enum class Row { LongName, ShortName, Region, Timezone, Brightness, DimTimeout, OffTimeout, Sound, Gnss, GnssQuiet, Coordinates, ProbeMacs, Wifi, Storage, Firmware, About };
+    enum class Kind { Text, Choice, Toggle, Slider, Page };
+
+    explicit SettingsMenu(Settings& settings) : settings_(settings) {}
+
+    int count() const;
+    Row row(int i) const;
+    Kind kind(int i) const;
+    std::string label(int i) const;
+    std::string value(int i) const;
+
+    // Choice rows
+    std::vector<std::string> choices(int i) const;
+    int currentChoice(int i) const;  // -1 if the current value isn't one of the choices
+    std::string choose(int i, int choice);  // empty on success, otherwise why it was refused
+
+    // Toggle and Slider rows
+    void toggle(int i);
+    void adjust(int i, int direction);
+
+    // Text rows
+    int maxBytes(int i) const;
+    std::string setText(int i, const std::string& text);  // empty on success, otherwise why
+
+   private:
+    Settings& settings_;
+};
+
+}  // namespace roro

lib/apps_model/src/setup_wizard.cpp

@@ -0,0 +1,88 @@
+#include "setup_wizard.h"
+
+#include "choices.h"
+
+namespace roro {
+
+SetupWizard::SetupWizard(Settings& settings, std::string defaultLongName, std::string defaultShortName)
+    : settings_(settings), longName_(std::move(defaultLongName)), shortName_(std::move(defaultShortName)) {}
+
+int SetupWizard::choiceCount() const {
+    if (step_ == Step::Region) return sizeof(kRegions) / sizeof(kRegions[0]);
+    if (step_ == Step::Timezone) return sizeof(kTimezones) / sizeof(kTimezones[0]);
+    return 0;
+}
+
+std::string SetupWizard::choiceLabel(int i) const {
+    return step_ == Step::Region ? kRegions[i].label : kTimezones[i].label;
+}
+
+int SetupWizard::selectedChoice() const { return step_ == Step::Region ? region_ : timezone_; }
+
+void SetupWizard::selectChoice(int i) {
+    if (i < 0 || i >= choiceCount()) return;
+    (step_ == Step::Region ? region_ : timezone_) = i;
+}
+
+void SetupWizard::enter(Step step) {
+    step_ = step;
+    error_.clear();
+    if (step == Step::LongName) {
+        editor_ = LineEditor(39);
+        editor_.setText(longName_);
+    } else if (step == Step::ShortName) {
+        editor_ = LineEditor(4);
+        editor_.setText(shortName_);
+    }
+}
+
+bool SetupWizard::next() {
+    switch (step_) {
+        case Step::Welcome: enter(Step::LongName); return true;
+        case Step::LongName:
+            if (editor_.text().empty()) {
+                error_ = "Please enter a name";
+                return false;
+            }
+            longName_ = editor_.text();
+            enter(Step::ShortName);
+            return true;
+        case Step::ShortName:
+            if (editor_.text().empty()) {
+                error_ = "Please enter 1 to 4 characters";
+                return false;
+            }
+            shortName_ = editor_.text();
+            enter(Step::Region);
+            return true;
+        case Step::Region: enter(Step::Timezone); return true;
+        case Step::Timezone: enter(Step::Done); return true;
+        case Step::Done:
+            save();
+            finished_ = true;
+            return true;
+    }
+    return false;
+}
+
+void SetupWizard::back() {
+    switch (step_) {
+        case Step::LongName: longName_ = editor_.text(); enter(Step::Welcome); break;
+        case Step::ShortName: shortName_ = editor_.text(); enter(Step::LongName); break;
+        case Step::Region: enter(Step::ShortName); break;
+        case Step::Timezone: enter(Step::Region); break;
+        case Step::Done: enter(Step::Timezone); break;
+        case Step::Welcome: break;
+    }
+}
+
+void SetupWizard::save() {
+    settings_.setString(Setting::LongName, longName_);
+    settings_.setString(Setting::ShortName, shortName_);
+    settings_.setString(Setting::Region, kRegions[region_].value);
+    settings_.setString(Setting::Timezone, kTimezones[timezone_].value);
+    settings_.setBool(Setting::RegionConfirmed, true);
+    settings_.setBool(Setting::SetupDone, true);
+}
+
+}  // namespace roro

lib/apps_model/src/setup_wizard.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include <string>
+
+#include "line_editor.h"
+#include "settings.h"
+
+namespace roro {
+
+// The first-boot setup flow: names, Region confirmation, timezone. Nothing is saved until the
+// last step, so an interrupted setup simply starts again at the next boot.
+class SetupWizard {
+   public:
+    enum class Step { Welcome, LongName, ShortName, Region, Timezone, Done };
+
+    SetupWizard(Settings& settings, std::string defaultLongName, std::string defaultShortName);
+
+    Step step() const { return step_; }
+    bool finished() const { return finished_; }
+
+    // Name steps edit text; Region and Timezone steps pick a choice.
+    LineEditor& editor() { return editor_; }
+    int choiceCount() const;
+    std::string choiceLabel(int i) const;
+    int selectedChoice() const;
+    void selectChoice(int i);
+
+    bool next();  // validates the step; false (with error()) if it can't advance
+    void back();
+    const std::string& error() const { return error_; }
+
+   private:
+    void enter(Step step);
+    void save();
+
+    Settings& settings_;
+    Step step_ = Step::Welcome;
+    bool finished_ = false;
+    std::string error_;
+    LineEditor editor_{39};
+    std::string longName_, shortName_;
+    int region_ = 0;
+    int timezone_ = 0;
+};
+
+}  // namespace roro

lib/core/src/app.h

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <cstdint>
+
+#include "key_event.h"
+
+namespace roro {
+
+class Canvas;  // provided by the widget kit
+
+// A foreground, user-facing program (see CONTEXT.md). Exactly one App is on screen at a time.
+class App {
+   public:
+    virtual ~App() = default;
+
+    virtual void onEnter() {}
+    virtual void onExit() {}
+
+    // Return true if the key was consumed. An unconsumed Back leaves the App.
+    virtual bool onKey(const KeyEvent& event) {
+        (void)event;
+        return false;
+    }
+
+    // True while the App is editing text: the arrow keys then type ; . , / and need Fn to move.
+    virtual bool textEntryActive() const { return false; }
+
+    // Called every main-loop pass while in the foreground (e.g. to refresh live values).
+    virtual void update(uint32_t nowMs) { (void)nowMs; }
+
+    virtual void draw(Canvas& canvas) = 0;
+
+    void requestRedraw() { redraw_ = true; }
+
+    bool consumeRedraw() {
+        bool r = redraw_;
+        redraw_ = false;
+        return r;
+    }
+
+   private:
+    bool redraw_ = false;
+};
+
+}  // namespace roro

lib/core/src/app_manager.cpp

@@ -0,0 +1,87 @@
+#include "app_manager.h"
+
+#include <cstring>
+
+namespace roro {
+
+AppManager::AppManager(App& launcher) : launcher_(launcher), foreground_(&launcher) {}
+
+void AppManager::registerApp(const AppInfo& info) { apps_.push_back(info); }
+
+std::vector<const AppInfo*> AppManager::visibleApps() const {
+    std::vector<const AppInfo*> visible;
+    for (auto& info : apps_)
+        if (!info.hidden) visible.push_back(&info);
+    return visible;
+}
+
+void AppManager::begin() {
+    foreground_ = &launcher_;
+    launcher_.onEnter();
+    redraw_ = true;
+}
+
+App* AppManager::find(const char* id) const {
+    for (auto& info : apps_)
+        if (std::strcmp(info.id, id) == 0) return info.app;
+    return nullptr;
+}
+
+bool AppManager::open(const char* id) {
+    App* app = find(id);
+    if (!app || modal_) return false;
+    switchTo(*app);
+    return true;
+}
+
+void AppManager::home() {
+    if (!modal_) switchTo(launcher_);
+}
+
+bool AppManager::openModal(const char* id) {
+    App* app = find(id);
+    if (!app) return false;
+    switchTo(*app);
+    modal_ = true;
+    return true;
+}
+
+void AppManager::endModal() {
+    modal_ = false;
+    switchTo(launcher_);
+}
+
+void AppManager::handleKey(const KeyEvent& event) {
+    if (modal_) {
+        foreground_->onKey(event);
+        return;
+    }
+    if (event.key == Key::Home) {
+        home();
+        return;
+    }
+    bool consumed = foreground_->onKey(event);
+    if (!consumed && event.key == Key::Back) home();
+}
+
+const char* AppManager::foregroundTitle() const {
+    for (auto& info : apps_)
+        if (info.app == foreground_) return info.title;
+    return nullptr;
+}
+
+bool AppManager::takeRedraw() {
+    bool r = redraw_ | foreground_->consumeRedraw();
+    redraw_ = false;
+    return r;
+}
+
+void AppManager::switchTo(App& app) {
+    if (&app == foreground_) return;
+    foreground_->onExit();
+    foreground_ = &app;
+    foreground_->onEnter();
+    redraw_ = true;
+}
+
+}  // namespace roro

lib/core/src/app_manager.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <vector>
+
+#include "app.h"
+
+namespace roro {
+
+struct AppInfo {
+    const char* id;
+    const char* title;
+    bool hidden;  // not listed in the Launcher, but can still be opened
+    App* app;
+};
+
+// Owns which App is in the foreground and routes keys. Home always returns to the Launcher;
+// Back is offered to the App first and returns to the Launcher if the App doesn't consume it.
+class AppManager {
+   public:
+    explicit AppManager(App& launcher);
+
+    void registerApp(const AppInfo& info);
+    std::vector<const AppInfo*> visibleApps() const;
+
+    void begin();
+    bool open(const char* id);  // refused while a modal App runs
+    void home();
+
+    // A modal App (e.g. the first-boot wizard) can't be left with Home or Back: those keys go to it,
+    // and it ends itself with endModal(), which returns to the Launcher.
+    bool openModal(const char* id);
+    void endModal();
+
+    void handleKey(const KeyEvent& event);
+    void update(uint32_t nowMs) { foreground_->update(nowMs); }
+
+    App& foreground() const { return *foreground_; }
+    const char* foregroundTitle() const;  // nullptr for the Launcher
+
+    // True once after the screen needs redrawing (App switch, or the App asked for it).
+    bool takeRedraw();
+
+   private:
+    void switchTo(App& app);
+    App* find(const char* id) const;
+
+    App& launcher_;
+    App* foreground_;
+    std::vector<AppInfo> apps_;
+    bool redraw_ = true;
+    bool modal_ = false;
+};
+
+}  // namespace roro

lib/core/src/event.h

@@ -0,0 +1,43 @@
+#pragma once
+
+#include <cstdint>
+#include <cstring>
+
+namespace roro {
+
+enum class NotificationLevel : int32_t { Info, Warning, Message };
+
+// Everything Services announce to the UI. Add new kinds before Count.
+enum class EventType : uint8_t {
+    BatteryChanged,    // a = percent, b = millivolts
+    Notification,      // text = message, a = NotificationLevel
+    StorageThreshold,  // a = usage percent, b = level now in effect (0 / 80 / 90 / 100)
+    SettingChanged,    // a = Setting, text = storage key
+    Count
+};
+
+// Small, fixed-size and copyable so it can cross tasks through a queue without allocating.
+struct Event {
+    static constexpr size_t kTextCapacity = 48;
+
+    EventType type;
+    int32_t a = 0;
+    int32_t b = 0;
+    char text[kTextCapacity] = {};
+
+    static Event withValues(EventType type, int32_t a, int32_t b = 0) {
+        Event e{type};
+        e.a = a;
+        e.b = b;
+        return e;
+    }
+
+    static Event withText(EventType type, const char* text, int32_t a = 0) {
+        Event e{type};
+        e.a = a;
+        std::strncpy(e.text, text, kTextCapacity - 1);
+        return e;
+    }
+};
+
+}  // namespace roro

lib/core/src/event_bus.cpp

@@ -0,0 +1,46 @@
+#include "event_bus.h"
+
+namespace roro {
+
+EventBus::EventBus(size_t capacity) : queue_(capacity) {}
+
+bool EventBus::publish(const Event& event) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (count_ == queue_.size()) {
+        dropped_++;
+        return false;
+    }
+    queue_[(head_ + count_) % queue_.size()] = event;
+    count_++;
+    return true;
+}
+
+void EventBus::subscribe(EventType type, Handler handler) {
+    handlers_[static_cast<size_t>(type)].push_back(std::move(handler));
+}
+
+size_t EventBus::dispatch() {
+    size_t pending;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        pending = count_;
+    }
+    for (size_t i = 0; i < pending; i++) {
+        Event event;
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            event = queue_[head_];
+            head_ = (head_ + 1) % queue_.size();
+            count_--;
+        }
+        for (auto& handler : handlers_[static_cast<size_t>(event.type)]) handler(event);
+    }
+    return pending;
+}
+
+uint32_t EventBus::dropped() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return dropped_;
+}
+
+}  // namespace roro

lib/core/src/event_bus.h

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <array>
+#include <functional>
+#include <mutex>
+#include <vector>
+
+#include "event.h"
+
+namespace roro {
+
+// Services publish from any task; the UI task calls dispatch() to deliver events to subscribers.
+// Subscribe only during setup, from the UI task.
+class EventBus {
+   public:
+    using Handler = std::function<void(const Event&)>;
+
+    explicit EventBus(size_t capacity = 32);
+
+    // Thread-safe. Returns false (and counts a drop) if the queue is full.
+    bool publish(const Event& event);
+
+    void subscribe(EventType type, Handler handler);
+
+    // Delivers the events queued before this call; events published meanwhile wait for the next one.
+    // Returns how many events were delivered.
+    size_t dispatch();
+
+    uint32_t dropped() const;
+
+   private:
+    std::vector<Event> queue_;
+    size_t head_ = 0;
+    size_t count_ = 0;
+    uint32_t dropped_ = 0;
+    mutable std::mutex mutex_;
+    std::array<std::vector<Handler>, static_cast<size_t>(EventType::Count)> handlers_;
+};
+
+}  // namespace roro

lib/core/src/key_event.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+// Logical keys, already translated from the physical keyboard (Fn combos, Esc position, etc.).
+enum class Key : uint8_t {
+    Char,  // a printable character in `ch` (Unicode code point, accents already composed)
+    Up,
+    Down,
+    Left,
+    Right,
+    Select,
+    Back,
+    Home,
+    Tab,
+    Delete,
+};
+
+struct KeyEvent {
+    Key key = Key::Char;
+    uint32_t ch = 0;
+    bool shift = false;
+    bool ctrl = false;
+    bool alt = false;
+
+    static KeyEvent of(Key key) {
+        KeyEvent e;
+        e.key = key;
+        return e;
+    }
+
+    static KeyEvent character(uint32_t codePoint) {
+        KeyEvent e;
+        e.ch = codePoint;
+        return e;
+    }
+};
+
+}  // namespace roro

lib/core/src/service.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+// A long-lived background capability (see CONTEXT.md). Services are ticked cooperatively from the
+// main loop; one that needs real concurrency (e.g. the radio) may run its own task internally and
+// report through the EventBus.
+class Service {
+   public:
+    virtual ~Service() = default;
+    virtual const char* name() const = 0;
+    virtual void start() {}
+    virtual void stop() {}
+    virtual void tick(uint32_t nowMs) { (void)nowMs; }
+    virtual uint32_t tickIntervalMs() const { return 1000; }
+};
+
+}  // namespace roro

lib/core/src/service_manager.cpp

@@ -0,0 +1,33 @@
+#include "service_manager.h"
+
+namespace roro {
+
+void ServiceManager::add(Service& service) { entries_.push_back({&service, 0, true}); }
+
+void ServiceManager::startAll(uint32_t nowMs) {
+    for (auto& e : entries_) {
+        e.service->start();
+        e.lastTickMs = nowMs;
+        e.due = true;
+    }
+    running_ = true;
+}
+
+void ServiceManager::stopAll() {
+    for (auto it = entries_.rbegin(); it != entries_.rend(); ++it) it->service->stop();
+    running_ = false;
+}
+
+void ServiceManager::tick(uint32_t nowMs) {
+    if (!running_) return;
+    for (auto& e : entries_) {
+        // Unsigned subtraction keeps working across the 49-day millis() wraparound.
+        if (e.due || nowMs - e.lastTickMs >= e.service->tickIntervalMs()) {
+            e.due = false;
+            e.lastTickMs = nowMs;
+            e.service->tick(nowMs);
+        }
+    }
+}
+
+}  // namespace roro

lib/core/src/service_manager.h

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <vector>
+
+#include "service.h"
+
+namespace roro {
+
+class ServiceManager {
+   public:
+    void add(Service& service);
+
+    // Starts services in the order added; each gets its first tick on the next tick() call.
+    void startAll(uint32_t nowMs);
+    // Stops services in reverse order.
+    void stopAll();
+
+    // Ticks every service whose interval has elapsed. Missed intervals are not replayed.
+    void tick(uint32_t nowMs);
+
+   private:
+    struct Entry {
+        Service* service;
+        uint32_t lastTickMs;
+        bool due;
+    };
+    std::vector<Entry> entries_;
+    bool running_ = false;
+};
+
+}  // namespace roro

lib/gemini/src/gemini_response.cpp

@@ -0,0 +1,59 @@
+#include "gemini_response.h"
+
+#include <cctype>
+
+namespace roro::gemini {
+
+namespace {
+std::string trim(const std::string& s) {
+    size_t a = s.find_first_not_of(" \t"), b = s.find_last_not_of(" \t");
+    return a == std::string::npos ? "" : s.substr(a, b - a + 1);
+}
+std::string lower(std::string s) {
+    for (auto& c : s) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return s;
+}
+}  // namespace
+
+bool parseHeader(const std::string& line, Header& out) {
+    if (line.size() < 2 || !std::isdigit(static_cast<unsigned char>(line[0])) ||
+        !std::isdigit(static_cast<unsigned char>(line[1])))
+        return false;
+    if (line.size() > 2 && line[2] != ' ') return false;
+    std::string meta = line.size() > 3 ? line.substr(3) : "";
+    if (meta.size() > 1024) return false;
+    out.status = (line[0] - '0') * 10 + (line[1] - '0');
+    out.meta = meta;
+    return true;
+}
+
+Category Header::category() const {
+    switch (status / 10) {
+        case 1: return Category::Input;
+        case 2: return Category::Success;
+        case 3: return Category::Redirect;
+        case 4: return Category::TemporaryFailure;
+        case 5: return Category::PermanentFailure;
+        case 6: return Category::ClientCertificate;
+        default: return Category::Unknown;
+    }
+}
+
+std::string Header::mimeType() const {
+    std::string type = lower(trim(meta.substr(0, meta.find(';'))));
+    return type.empty() ? "text/gemini" : type;
+}
+
+std::string Header::parameter(const std::string& name) const {
+    size_t pos = meta.find(';');
+    while (pos != std::string::npos) {
+        size_t next = meta.find(';', pos + 1);
+        std::string item = trim(meta.substr(pos + 1, next == std::string::npos ? std::string::npos : next - pos - 1));
+        size_t eq = item.find('=');
+        if (eq != std::string::npos && lower(trim(item.substr(0, eq))) == lower(name)) return trim(item.substr(eq + 1));
+        pos = next;
+    }
+    return "";
+}
+
+}  // namespace roro::gemini

lib/gemini/src/gemini_response.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <string>
+
+namespace roro::gemini {
+
+enum class Category { Input, Success, Redirect, TemporaryFailure, PermanentFailure, ClientCertificate, Unknown };
+
+// The response header: "<two digits> <meta>", at most 1024 bytes of meta.
+struct Header {
+    int status = 0;
+    std::string meta;
+
+    Category category() const;
+    bool sensitiveInput() const { return status == 11; }
+    // 2x: the MIME type, lower-cased, without parameters ("text/gemini" when meta is empty).
+    std::string mimeType() const;
+    std::string parameter(const std::string& name) const;  // e.g. "charset"
+};
+
+bool parseHeader(const std::string& line, Header& out);
+
+}  // namespace roro::gemini

lib/gemini/src/gemini_url.cpp

@@ -0,0 +1,215 @@
+#include "gemini_url.h"
+
+#include <cctype>
+#include <cstdio>
+#include <cstdlib>
+#include <vector>
+
+#include "storage_paths.h"
+
+namespace roro::gemini {
+
+namespace {
+
+// RFC 3986, appendix B: ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
+struct Parts {
+    std::string scheme, authority, path, query, fragment;
+    bool hasScheme = false, hasAuthority = false, hasQuery = false, hasFragment = false;
+};
+
+Parts split(const std::string& s) {
+    Parts p;
+    size_t i = 0;
+    size_t colon = s.find(':');
+    size_t stop = s.find_first_of("/?#");
+    if (colon != std::string::npos && colon > 0 && (stop == std::string::npos || colon < stop)) {
+        p.scheme = s.substr(0, colon);
+        p.hasScheme = true;
+        i = colon + 1;
+    }
+    if (s.compare(i, 2, "//") == 0) {
+        size_t end = s.find_first_of("/?#", i + 2);
+        if (end == std::string::npos) end = s.size();
+        p.authority = s.substr(i + 2, end - i - 2);
+        p.hasAuthority = true;
+        i = end;
+    }
+    size_t end = s.find_first_of("?#", i);
+    if (end == std::string::npos) end = s.size();
+    p.path = s.substr(i, end - i);
+    i = end;
+    if (i < s.size() && s[i] == '?') {
+        end = s.find('#', i);
+        if (end == std::string::npos) end = s.size();
+        p.query = s.substr(i + 1, end - i - 1);
+        p.hasQuery = true;
+        i = end;
+    }
+    if (i < s.size() && s[i] == '#') {
+        p.fragment = s.substr(i + 1);
+        p.hasFragment = true;
+    }
+    return p;
+}
+
+std::string lower(std::string s) {
+    for (auto& c : s) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return s;
+}
+
+// RFC 3986, section 5.2.4.
+std::string removeDotSegments(std::string in) {
+    std::string out;
+    while (!in.empty()) {
+        if (in.compare(0, 3, "../") == 0) in.erase(0, 3);
+        else if (in.compare(0, 2, "./") == 0) in.erase(0, 2);
+        else if (in.compare(0, 3, "/./") == 0) in.replace(0, 3, "/");
+        else if (in == "/.") in = "/";
+        else if (in.compare(0, 4, "/../") == 0 || in == "/..") {
+            in = in == "/.." ? "/" : in.substr(3);
+            size_t slash = out.rfind('/');
+            out.erase(slash == std::string::npos ? 0 : slash);
+        } else if (in == "." || in == "..") in.clear();
+        else {
+            size_t next = in.find('/', in[0] == '/' ? 1 : 0);
+            if (next == std::string::npos) next = in.size();
+            out += in.substr(0, next);
+            in.erase(0, next);
+        }
+    }
+    return out;
+}
+
+// RFC 3986, section 5.2.3.
+std::string merge(const Parts& base, const std::string& refPath) {
+    if (base.hasAuthority && base.path.empty()) return "/" + refPath;
+    size_t slash = base.path.rfind('/');
+    return slash == std::string::npos ? refPath : base.path.substr(0, slash + 1) + refPath;
+}
+
+// RFC 3986, section 5.3.
+std::string recompose(const Parts& p) {
+    std::string out;
+    if (p.hasScheme) out += p.scheme + ":";
+    if (p.hasAuthority) out += "//" + p.authority;
+    out += p.path;
+    if (p.hasQuery) out += "?" + p.query;
+    if (p.hasFragment) out += "#" + p.fragment;
+    return out;
+}
+
+}  // namespace
+
+bool parseUrl(const std::string& text, Url& out) {
+    Parts p = split(text);
+    if (!p.hasScheme || !p.hasAuthority) return false;
+    out = Url();
+    out.scheme = lower(p.scheme);
+    out.authority = p.authority;
+    std::string hostPort = p.authority.substr(p.authority.find('@') == std::string::npos ? 0 : p.authority.find('@') + 1);
+    size_t colon = hostPort.rfind(':');
+    if (colon != std::string::npos && hostPort.find(']', colon) == std::string::npos) {
+        out.port = std::atoi(hostPort.c_str() + colon + 1);
+        hostPort = hostPort.substr(0, colon);
+    }
+    out.host = lower(hostPort);
+    if (out.host.empty()) return false;
+    out.path = p.path;
+    out.query = p.query;
+    out.fragment = p.fragment;
+    out.hasAuthority = true;
+    out.hasQuery = p.hasQuery;
+    out.hasFragment = p.hasFragment;
+    return true;
+}
+
+bool isGemini(const std::string& url) {
+    Parts p = split(url);
+    return p.hasScheme && lower(p.scheme) == "gemini";
+}
+
+std::string resolve(const std::string& baseText, const std::string& refText) {
+    Parts base = split(baseText), r = split(refText), t;
+    if (r.hasScheme) {
+        t = r;
+        t.path = removeDotSegments(r.path);
+    } else {
+        if (r.hasAuthority) {
+            t.authority = r.authority;
+            t.hasAuthority = true;
+            t.path = removeDotSegments(r.path);
+            t.query = r.query;
+            t.hasQuery = r.hasQuery;
+        } else {
+            if (r.path.empty()) {
+                t.path = base.path;
+                t.query = r.hasQuery ? r.query : base.query;
+                t.hasQuery = r.hasQuery || base.hasQuery;
+            } else {
+                t.path = removeDotSegments(r.path[0] == '/' ? r.path : merge(base, r.path));
+                t.query = r.query;
+                t.hasQuery = r.hasQuery;
+            }
+            t.authority = base.authority;
+            t.hasAuthority = base.hasAuthority;
+        }
+        t.scheme = base.scheme;
+        t.hasScheme = base.hasScheme;
+    }
+    t.fragment = r.fragment;
+    t.hasFragment = r.hasFragment;
+    return recompose(t);
+}
+
+std::string requestUrl(const std::string& url) {
+    Url u;
+    if (!parseUrl(url, u)) return url;
+    std::string out = u.scheme + "://" + u.host;
+    if (u.port > 0 && u.port != 1965) out += ":" + std::to_string(u.port);
+    out += u.path.empty() ? "/" : u.path;
+    if (u.hasQuery) out += "?" + u.query;
+    return out;
+}
+
+std::string encodeQuery(const std::string& text) {
+    std::string out;
+    for (unsigned char c : text) {
+        if (std::isalnum(c) || c == '-' || c == '_' || c == '.' || c == '~') out += static_cast<char>(c);
+        else {
+            char buf[4];
+            std::snprintf(buf, sizeof buf, "%%%02X", c);
+            out += buf;
+        }
+    }
+    return out;
+}
+
+std::string savedPath(const std::string& url) {
+    Url u;
+    if (!parseUrl(url, u)) return "/gemini/saved/unknown.gmi";
+    std::string out = "/gemini/saved/" + storage::sanitize(u.host + (u.port > 0 && u.port != 1965 ? "_" + std::to_string(u.port) : ""));
+    std::string path = u.path.empty() ? "/" : u.path;
+    std::vector<std::string> parts;
+    size_t start = 1;
+    while (start <= path.size()) {
+        size_t slash = path.find('/', start);
+        if (slash == std::string::npos) slash = path.size();
+        parts.push_back(path.substr(start, slash - start));
+        start = slash + 1;
+    }
+    if (parts.empty() || parts.back().empty()) {
+        if (!parts.empty()) parts.pop_back();
+        parts.push_back("index");
+    }
+    for (size_t i = 0; i < parts.size(); i++) {
+        std::string name = parts[i];
+        if (i + 1 == parts.size()) {
+            if (u.hasQuery) name += "~" + u.query;
+            if (name.size() < 4 || name.compare(name.size() - 4, 4, ".gmi") != 0) name += ".gmi";
+        }
+        out += "/" + storage::sanitize(name);
+    }
+    return out;
+}
+
+}  // namespace roro::gemini

lib/gemini/src/gemini_url.h

@@ -0,0 +1,28 @@
+#pragma once
+
+#include <string>
+
+namespace roro::gemini {
+
+// A URL split per RFC 3986 (appendix B). For Gemini, the host is lower-cased and the port
+// defaults to 1965.
+struct Url {
+    std::string scheme, authority, host, path, query, fragment;
+    int port = -1;
+    bool hasAuthority = false, hasQuery = false, hasFragment = false;
+    int portOrDefault() const { return port > 0 ? port : 1965; }
+};
+
+// False unless it has a scheme and a host: only absolute URLs are fetched.
+bool parseUrl(const std::string& text, Url& out);
+bool isGemini(const std::string& url);
+// `ref` against `base`, per RFC 3986 section 5.2 (dot segments included).
+std::string resolve(const std::string& base, const std::string& ref);
+// What goes on the wire: no fragment, lower-case host, never an empty path.
+std::string requestUrl(const std::string& url);
+// For input prompts: everything but unreserved characters percent-encoded (UTF-8 bytes).
+std::string encodeQuery(const std::string& text);
+// Where a Saved Page lives (Q82): /gemini/saved/<host>[_<port>]/<path>[~<query>].gmi
+std::string savedPath(const std::string& url);
+
+}  // namespace roro::gemini

lib/gemini/src/gemtext.cpp

@@ -0,0 +1,100 @@
+#include "gemtext.h"
+
+#include <cstdint>
+
+namespace roro::gemini {
+
+namespace {
+std::string trim(const std::string& s) {
+    size_t a = s.find_first_not_of(" \t"), b = s.find_last_not_of(" \t");
+    return a == std::string::npos ? "" : s.substr(a, b - a + 1);
+}
+}  // namespace
+
+GemLine parseGemLine(const std::string& line, bool& pre) {
+    GemLine g;
+    if (line.compare(0, 3, "```") == 0) {
+        g.type = LineType::PreToggle;
+        g.text = trim(line.substr(3));
+        pre = !pre;
+    } else if (pre) {
+        g.type = LineType::Preformatted;
+        g.text = line;
+    } else if (line.compare(0, 2, "=>") == 0) {
+        g.type = LineType::Link;
+        std::string rest = trim(line.substr(2));
+        size_t gap = rest.find_first_of(" \t");
+        g.url = rest.substr(0, gap);
+        g.text = gap == std::string::npos ? "" : trim(rest.substr(gap));
+        if (g.text.empty()) g.text = g.url;
+    } else if (line.compare(0, 3, "###") == 0) {
+        g.type = LineType::Heading3;
+        g.text = trim(line.substr(3));
+    } else if (line.compare(0, 2, "##") == 0) {
+        g.type = LineType::Heading2;
+        g.text = trim(line.substr(2));
+    } else if (line.compare(0, 1, "#") == 0) {
+        g.type = LineType::Heading1;
+        g.text = trim(line.substr(1));
+    } else if (line.compare(0, 2, "* ") == 0) {
+        g.type = LineType::ListItem;
+        g.text = trim(line.substr(2));
+    } else if (line.compare(0, 1, ">") == 0) {
+        g.type = LineType::Quote;
+        g.text = trim(line.substr(1));
+    } else {
+        g.text = line;
+    }
+    return g;
+}
+
+std::vector<GemLine> parseGemtext(const std::string& document) {
+    std::vector<GemLine> lines;
+    bool pre = false;
+    size_t start = 0;
+    while (start < document.size()) {
+        size_t end = document.find('\n', start);
+        if (end == std::string::npos) end = document.size();
+        std::string line = document.substr(start, end - start);
+        if (!line.empty() && line.back() == '\r') line.pop_back();
+        start = end + 1;
+        lines.push_back(parseGemLine(line, pre));
+    }
+    return lines;
+}
+
+std::string displayText(const std::string& s) {
+    std::string out;
+    size_t column = 0;
+    for (size_t i = 0; i < s.size();) {
+        unsigned char c = static_cast<unsigned char>(s[i]);
+        if (c == '\t') {
+            do out += ' ';
+            while (++column % 4);
+            i++;
+            continue;
+        }
+        if (c < 0x80) {
+            out += static_cast<char>(c);
+            i++;
+        } else {
+            int len = (c & 0xE0) == 0xC0 ? 2 : (c & 0xF0) == 0xE0 ? 3 : (c & 0xF8) == 0xF0 ? 4 : 0;
+            bool valid = len > 0 && i + len <= s.size();
+            for (int k = 1; valid && k < len; k++) valid = (static_cast<unsigned char>(s[i + k]) & 0xC0) == 0x80;
+            if (!valid) {
+                out += '?';
+                i++;
+            } else {
+                uint32_t cp = len == 2 ? (c & 0x1F) : len == 3 ? (c & 0x0F) : (c & 0x07);
+                for (int k = 1; k < len; k++) cp = (cp << 6) | (static_cast<unsigned char>(s[i + k]) & 0x3F);
+                if (cp <= 0xFF) out.append(s, i, len);  // Latin-1: the fonts have it
+                else out += '?';
+                i += len;
+            }
+        }
+        column++;
+    }
+    return out;
+}
+
+}  // namespace roro::gemini

lib/gemini/src/gemtext.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace roro::gemini {
+
+enum class LineType { Text, Link, Heading1, Heading2, Heading3, ListItem, Quote, PreToggle, Preformatted };
+
+// One gemtext line. Link: `url` and its label in `text` (the URL itself without a label).
+// PreToggle: the ``` line, with its alt text. Preformatted: kept exactly.
+struct GemLine {
+    LineType type = LineType::Text;
+    std::string text, url;
+};
+
+// One line; `preformatted` carries the ``` state from line to line (start with false).
+GemLine parseGemLine(const std::string& line, bool& preformatted);
+std::vector<GemLine> parseGemtext(const std::string& document);
+
+// For the Latin-1 fonts (Q79): valid UTF-8 up to U+00FF kept, anything else '?', and tabs
+// expanded to 4-column stops.
+std::string displayText(const std::string& utf8);
+
+}  // namespace roro::gemini

lib/gemini/src/text_buffer.cpp

@@ -0,0 +1,47 @@
+#include "text_buffer.h"
+
+#include <algorithm>
+
+namespace roro::gemini {
+
+void TextBuffer::append(const char* data, size_t len) {
+    bytes_ += len;
+    for (size_t i = 0; i < len; i++) {
+        if (data[i] == '\n') endLine();
+        else partial_ += data[i];
+    }
+}
+
+void TextBuffer::finish() {
+    if (!partial_.empty()) endLine();
+}
+
+void TextBuffer::endLine() {
+    if (!partial_.empty() && partial_.back() == '\r') partial_.pop_back();
+    size_t len = std::min<size_t>(partial_.size(), 0xFFFF);
+    // A line never spans two chunks: a new chunk when it doesn't fit (bigger if the line is).
+    if (chunks_.empty() || chunks_.back().size() + len > chunks_.back().capacity()) {
+        chunks_.emplace_back();
+        chunks_.back().reserve(std::max(kChunk, len));
+    }
+    std::string& chunk = chunks_.back();
+    lines_.push_back({static_cast<uint16_t>(chunks_.size() - 1), static_cast<uint16_t>(chunk.size()),
+                      static_cast<uint16_t>(len)});
+    chunk.append(partial_, 0, len);
+    partial_.clear();
+}
+
+std::string TextBuffer::line(size_t i) const {
+    if (i >= lines_.size()) return "";
+    const Ref& r = lines_[i];
+    return chunks_[r.chunk].substr(r.offset, r.length);
+}
+
+void TextBuffer::clear() {
+    chunks_.clear();
+    lines_.clear();
+    partial_.clear();
+    bytes_ = 0;
+}
+
+}  // namespace roro::gemini

lib/gemini/src/text_buffer.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::gemini {
+
+// A page's text, kept as lines in 4 KB chunks: no large contiguous block (with IRC connected the
+// largest free block is about 31 KB) and no copy when it grows. About 4 bytes per line on top of
+// the text itself. Bytes are fed as they arrive; lines end at LF, a CR before it is dropped.
+class TextBuffer {
+   public:
+    static constexpr size_t kChunk = 4096;
+
+    void append(const char* data, size_t len);
+    void finish();  // the last line, if it has no line end
+    size_t lineCount() const { return lines_.size(); }
+    std::string line(size_t i) const;
+    size_t bytes() const { return bytes_; }
+    void clear();
+
+   private:
+    struct Ref {
+        uint16_t chunk;
+        uint16_t offset;
+        uint16_t length;
+    };
+    void endLine();
+
+    std::vector<std::string> chunks_;
+    std::vector<Ref> lines_;
+    std::string partial_;  // the line being received
+    size_t bytes_ = 0;
+};
+
+}  // namespace roro::gemini

lib/gnss/src/geo_format.cpp

@@ -0,0 +1,50 @@
+#include "geo_format.h"
+
+#include <cmath>
+#include <cstdio>
+
+namespace roro::gnss {
+
+namespace {
+const char* hemisphere(double degrees, bool latitude) {
+    return latitude ? (degrees < 0 ? "S" : "N") : (degrees < 0 ? "W" : "E");
+}
+}  // namespace
+
+std::string formatDecimal(double degrees, bool latitude) {
+    char buf[32];
+    std::snprintf(buf, sizeof buf, "%.5f\xC2\xB0 %s", std::fabs(degrees), hemisphere(degrees, latitude));
+    return buf;
+}
+
+std::string formatDms(double degrees, bool latitude) {
+    // Work in tenths of a second, so rounding carries into minutes and degrees.
+    long tenths = std::lround(std::fabs(degrees) * 36000.0);
+    long d = tenths / 36000, m = tenths / 600 % 60, s10 = tenths % 600;
+    char buf[40];
+    std::snprintf(buf, sizeof buf, "%ld\xC2\xB0 %02ld' %02ld.%ld\" %s", d, m, s10 / 10, s10 % 10,
+                  hemisphere(degrees, latitude));
+    return buf;
+}
+
+std::string maidenhead(double latitude, double longitude) {
+    double lon = std::fmin(std::fmax(longitude + 180.0, 0.0), 359.999999);
+    double lat = std::fmin(std::fmax(latitude + 90.0, 0.0), 179.999999);
+    std::string out;
+    out += static_cast<char>('A' + static_cast<int>(lon / 20));
+    out += static_cast<char>('A' + static_cast<int>(lat / 10));
+    out += static_cast<char>('0' + static_cast<int>(std::fmod(lon, 20) / 2));
+    out += static_cast<char>('0' + static_cast<int>(std::fmod(lat, 10)));
+    out += static_cast<char>('a' + static_cast<int>(std::fmod(lon, 2) * 12));
+    out += static_cast<char>('a' + static_cast<int>(std::fmod(lat, 1) * 24));
+    return out;
+}
+
+SkyPoint skyPosition(int azimuthDeg, int elevationDeg, int cx, int cy, int radius) {
+    int elevation = elevationDeg < 0 ? 0 : elevationDeg > 90 ? 90 : elevationDeg;
+    double r = radius * (90 - elevation) / 90.0;
+    double az = azimuthDeg * M_PI / 180.0;
+    return {cx + static_cast<int>(std::lround(r * std::sin(az))), cy - static_cast<int>(std::lround(r * std::cos(az)))};
+}
+
+}  // namespace roro::gnss

lib/gnss/src/geo_format.h

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <string>
+
+namespace roro::gnss {
+
+// "50.86920° N": five decimals, about a metre.
+std::string formatDecimal(double degrees, bool latitude);
+// "50° 52' 09.1\" N" (Settings → Coordinates, Q64).
+std::string formatDms(double degrees, bool latitude);
+// The 6-character Maidenhead locator ("JO20ef"), as radio amateurs give their square.
+std::string maidenhead(double latitude, double longitude);
+
+// Where a satellite goes on the Sky view: the zenith in the centre, the horizon on the circle,
+// north up and east right (as seen looking at the sky from above, like a map).
+struct SkyPoint {
+    int x, y;
+};
+SkyPoint skyPosition(int azimuthDeg, int elevationDeg, int cx, int cy, int radius);
+
+}  // namespace roro::gnss

lib/gnss/src/nmea_parser.cpp

@@ -0,0 +1,234 @@
+#include "nmea_parser.h"
+
+#include <cstdlib>
+
+namespace roro::gnss {
+
+namespace {
+
+constexpr double kKmhPerKnot = 1.852;
+
+int hexValue(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    return -1;
+}
+
+Constellation fromTalker(const std::string& t) {
+    if (t == "GP") return Constellation::Gps;
+    if (t == "GL") return Constellation::Glonass;
+    if (t == "GA") return Constellation::Galileo;
+    if (t == "GB" || t == "BD") return Constellation::BeiDou;
+    if (t == "GQ" || t == "QZ") return Constellation::Qzss;
+    if (t == "GI") return Constellation::Navic;
+    return Constellation::Unknown;  // GN: combined
+}
+
+// GSA's system ID field (NMEA 4.10).
+Constellation fromSystemId(int id) {
+    switch (id) {
+        case 1: return Constellation::Gps;
+        case 2: return Constellation::Glonass;
+        case 3: return Constellation::Galileo;
+        case 4: return Constellation::BeiDou;
+        case 5: return Constellation::Qzss;
+        case 6: return Constellation::Navic;
+        default: return Constellation::Unknown;
+    }
+}
+
+bool number(const std::string& s, double& out) {
+    if (s.empty()) return false;
+    char* end;
+    out = std::strtod(s.c_str(), &end);
+    return *end == '\0';
+}
+
+int integer(const std::string& s, int fallback = 0) {
+    double v;
+    return number(s, v) ? static_cast<int>(v) : fallback;
+}
+
+// "ddmm.mmmm" / "dddmm.mmmm" with its hemisphere letter.
+bool coordinate(const std::string& value, const std::string& hemisphere, double& out) {
+    double raw;
+    if (!number(value, raw) || hemisphere.empty()) return false;
+    int degrees = static_cast<int>(raw / 100);
+    out = degrees + (raw - degrees * 100) / 60.0;
+    if (hemisphere == "S" || hemisphere == "W") out = -out;
+    return true;
+}
+
+// Days since 1970-01-01 for a civil date (Howard Hinnant's algorithm).
+int64_t daysFromCivil(int y, int m, int d) {
+    y -= m <= 2;
+    const int64_t era = (y >= 0 ? y : y - 399) / 400;
+    const unsigned yoe = static_cast<unsigned>(y - era * 400);
+    const unsigned doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + d - 1;
+    const unsigned doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    return era * 146097 + static_cast<int64_t>(doe) - 719468;
+}
+
+}  // namespace
+
+const char* constellationName(Constellation c) {
+    switch (c) {
+        case Constellation::Gps: return "GPS";
+        case Constellation::Glonass: return "GLONASS";
+        case Constellation::Galileo: return "Galileo";
+        case Constellation::BeiDou: return "BeiDou";
+        case Constellation::Qzss: return "QZSS";
+        case Constellation::Navic: return "NavIC";
+        default: return "?";
+    }
+}
+
+int64_t GnssState::utcSeconds() const {
+    return daysFromCivil(year, month, day) * 86400 + hour * 3600 + minute * 60 + second;
+}
+
+void NmeaParser::feed(const char* data, size_t len) {
+    for (size_t i = 0; i < len; i++) {
+        char c = data[i];
+        if (c == '\n') {
+            if (!overflow_ && !line_.empty()) {
+                if (onLine) onLine(line_);
+                sentence(line_);
+            }
+            line_.clear();
+            overflow_ = false;
+        } else if (c != '\r') {
+            if (line_.size() >= kMaxLine) overflow_ = true;
+            else line_ += c;
+        }
+    }
+}
+
+bool NmeaParser::sentence(const std::string& line) {
+    size_t star = line.rfind('*');
+    if (line.size() < 7 || line[0] != '$' || star == std::string::npos || star + 3 != line.size()) {
+        bad_++;
+        return false;
+    }
+    uint8_t sum = 0;
+    for (size_t i = 1; i < star; i++) sum ^= static_cast<uint8_t>(line[i]);
+    int hi = hexValue(line[star + 1]), lo = hexValue(line[star + 2]);
+    if (hi < 0 || lo < 0 || sum != (hi << 4 | lo)) {
+        bad_++;
+        return false;
+    }
+    good_++;
+
+    Fields f;
+    size_t start = 1;
+    for (size_t i = 1; i <= star; i++)
+        if (i == star || line[i] == ',') {
+            f.push_back(line.substr(start, i - start));
+            start = i + 1;
+        }
+    if (f[0].size() < 5) return true;
+    std::string talker = f[0].substr(0, 2), type = f[0].substr(f[0].size() - 3);
+    if (type == "RMC") rmc(f);
+    else if (type == "GGA") gga(f);
+    else if (type == "GSA") gsa(f, fromTalker(talker));
+    else if (type == "GSV") gsv(f, fromTalker(talker));
+    return true;
+}
+
+void NmeaParser::rmc(const Fields& f) {
+    if (f.size() < 10) return;
+    bool active = f[2] == "A";
+    double lat, lon;
+    state_.positionValid = active && coordinate(f[3], f[4], lat) && coordinate(f[5], f[6], lon);
+    if (state_.positionValid) {
+        state_.latitude = lat;
+        state_.longitude = lon;
+    }
+    double knots, course;
+    state_.speedKmh = active && number(f[7], knots) ? static_cast<float>(knots * kKmhPerKnot) : 0;
+    state_.courseValid = active && number(f[8], course);
+    if (state_.courseValid) state_.courseDeg = static_cast<float>(course);
+
+    const std::string &t = f[1], &d = f[9];
+    state_.timeValid = active && t.size() >= 6 && d.size() == 6;
+    if (state_.timeValid) {
+        state_.hour = integer(t.substr(0, 2));
+        state_.minute = integer(t.substr(2, 2));
+        state_.second = integer(t.substr(4, 2));
+        state_.day = integer(d.substr(0, 2));
+        state_.month = integer(d.substr(2, 2));
+        state_.year = 2000 + integer(d.substr(4, 2));
+    }
+}
+
+void NmeaParser::gga(const Fields& f) {
+    if (f.size() < 10) return;
+    int quality = integer(f[6]);
+    double lat, lon, hdop, alt;
+    state_.positionValid = quality > 0 && coordinate(f[2], f[3], lat) && coordinate(f[4], f[5], lon);
+    if (state_.positionValid) {
+        state_.latitude = lat;
+        state_.longitude = lon;
+    }
+    state_.satellitesUsed = integer(f[7]);
+    if (number(f[8], hdop)) state_.hdop = static_cast<float>(hdop);
+    state_.altitudeValid = quality > 0 && number(f[9], alt);
+    if (state_.altitudeValid) state_.altitudeM = static_cast<float>(alt);
+}
+
+void NmeaParser::gsa(const Fields& f, Constellation talker) {
+    if (f.size() < 18) return;
+    int mode = integer(f[2], 1);
+    state_.fix = mode == 3 ? FixType::ThreeD : mode == 2 ? FixType::TwoD : FixType::None;
+    Constellation system = f.size() > 18 ? fromSystemId(integer(f[18])) : talker;
+    if (system == Constellation::Unknown) return;  // can't tell whose satellites these are
+    std::set<int>& used = used_[static_cast<int>(system)];
+    used.clear();
+    for (size_t i = 3; i <= 14; i++)
+        if (!f[i].empty()) used.insert(integer(f[i]));
+    rebuildSatellites();
+}
+
+void NmeaParser::gsv(const Fields& f, Constellation talker) {
+    if (f.size() < 4 || talker == Constellation::Unknown) return;
+    int total = integer(f[1]), number = integer(f[2]);
+    size_t extra = f.size() - 4;
+    int signal = extra % 4 == 1 ? integer(f.back()) : 0;  // NMEA 4.10 signal ID, last
+    auto key = std::make_pair(static_cast<int>(talker), signal);
+    std::vector<Satellite>& pending = pending_[key];
+    if (number == 1) pending.clear();
+    for (size_t i = 4; i + 3 < f.size(); i += 4) {
+        Satellite s;
+        s.system = talker;
+        s.prn = integer(f[i]);
+        s.elevation = integer(f[i + 1]);
+        s.azimuth = integer(f[i + 2]);
+        s.snr = integer(f[i + 3], -1);
+        if (s.prn > 0) pending.push_back(s);
+    }
+    if (number == total) {
+        inView_[key] = pending;
+        pending.clear();
+        rebuildSatellites();
+    }
+}
+
+void NmeaParser::rebuildSatellites() {
+    std::vector<Satellite> merged;
+    for (auto& [key, list] : inView_)
+        for (const Satellite& s : list) {
+            Satellite* same = nullptr;
+            for (auto& m : merged)
+                if (m.system == s.system && m.prn == s.prn) same = &m;
+            if (!same) merged.push_back(s);
+            else if (s.snr > same->snr) same->snr = s.snr;
+        }
+    for (auto& s : merged) {
+        auto it = used_.find(static_cast<int>(s.system));
+        s.used = it != used_.end() && it->second.count(s.prn) > 0;
+    }
+    state_.satellites = std::move(merged);
+}
+
+}  // namespace roro::gnss

lib/gnss/src/nmea_parser.h

@@ -0,0 +1,82 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <map>
+#include <set>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace roro::gnss {
+
+enum class Constellation : uint8_t { Unknown, Gps, Glonass, Galileo, BeiDou, Qzss, Navic };
+const char* constellationName(Constellation c);
+
+enum class FixType : uint8_t { None, TwoD, ThreeD };
+
+struct Satellite {
+    Constellation system = Constellation::Unknown;
+    int prn = 0;
+    int elevation = 0;  // degrees above the horizon
+    int azimuth = 0;    // degrees from north, clockwise
+    int snr = -1;       // dB-Hz; -1 when not tracked
+    bool used = false;  // part of the current Fix
+};
+
+// Everything the receiver has said, as of the last sentence (see CONTEXT.md: Fix).
+struct GnssState {
+    FixType fix = FixType::None;
+    bool positionValid = false;
+    double latitude = 0, longitude = 0;  // degrees, south and west negative
+    bool altitudeValid = false;
+    float altitudeM = 0;  // above mean sea level
+    float speedKmh = 0;
+    bool courseValid = false;
+    float courseDeg = 0;
+    int satellitesUsed = 0;
+    float hdop = 99.9f;
+    // UTC, trusted only with a Fix: the receiver reports a time without one, from its own clock.
+    bool timeValid = false;
+    int year = 0, month = 0, day = 0, hour = 0, minute = 0, second = 0;
+    std::vector<Satellite> satellites;  // in view, all constellations, one entry per satellite
+
+    int64_t utcSeconds() const;  // seconds since 1970-01-01 UTC; meaningful when timeValid
+};
+
+// NMEA 0183 (4.10 style, as the Cap's AT6668 sends it): RMC, GGA, GSA and GSV, with the
+// constellation taken from the talker ID or GSA's system ID field. Host-tested; no hardware here.
+class NmeaParser {
+   public:
+    // Raw bytes from the UART, in any chunks.
+    void feed(const char* data, size_t len);
+    // One sentence without its line end. False if malformed or its checksum is wrong.
+    bool sentence(const std::string& line);
+
+    // Called with every complete line fed in, valid or not (`gnss nmea on` echoes them).
+    std::function<void(const std::string&)> onLine;
+
+    const GnssState& state() const { return state_; }
+    uint32_t goodSentences() const { return good_; }
+    uint32_t badSentences() const { return bad_; }
+
+   private:
+    using Fields = std::vector<std::string>;
+    void rmc(const Fields& f);
+    void gga(const Fields& f);
+    void gsa(const Fields& f, Constellation talker);
+    void gsv(const Fields& f, Constellation talker);
+    void rebuildSatellites();
+
+    static constexpr size_t kMaxLine = 120;
+    std::string line_;
+    bool overflow_ = false;
+    uint32_t good_ = 0, bad_ = 0;
+    GnssState state_;
+    // GSV sequences per (constellation, signal): pending until their last message.
+    std::map<std::pair<int, int>, std::vector<Satellite>> pending_, inView_;
+    std::map<int, std::set<int>> used_;  // per constellation, from GSA
+};
+
+}  // namespace roro::gnss

lib/gnss/src/track.cpp

@@ -0,0 +1,76 @@
+#include "track.h"
+
+#include <cmath>
+#include <cstdio>
+#include <ctime>
+
+namespace roro::gnss {
+
+namespace {
+
+constexpr double kEarthRadiusM = 6371000.0;
+
+double radians(double degrees) { return degrees * M_PI / 180.0; }
+
+// UTC fields from seconds since 1970 (gmtime_r works on the device and the PC alike).
+struct tm utc(int64_t seconds) {
+    time_t t = static_cast<time_t>(seconds);
+    struct tm out;
+    gmtime_r(&t, &out);
+    return out;
+}
+
+}  // namespace
+
+double distanceMeters(double lat1, double lon1, double lat2, double lon2) {
+    double dLat = radians(lat2 - lat1), dLon = radians(lon2 - lon1);
+    double h = std::sin(dLat / 2) * std::sin(dLat / 2) +
+               std::cos(radians(lat1)) * std::cos(radians(lat2)) * std::sin(dLon / 2) * std::sin(dLon / 2);
+    return 2 * kEarthRadiusM * std::asin(std::sqrt(h));
+}
+
+bool TrackRule::due(uint32_t nowMs, double lat, double lon) {
+    if (any_ && (nowMs - lastMs_ < kEveryMs || distanceMeters(lat_, lon_, lat, lon) < kMinMeters)) return false;
+    any_ = true;
+    lastMs_ = nowMs;
+    lat_ = lat;
+    lon_ = lon;
+    return true;
+}
+
+std::string trackPath(int64_t utcSeconds) {
+    struct tm t = utc(utcSeconds);
+    char buf[48];
+    std::snprintf(buf, sizeof buf, "/gnss/tracks/%04d%02d%02d-%02d%02d%02d.gpx", t.tm_year + 1900, t.tm_mon + 1,
+                  t.tm_mday, t.tm_hour, t.tm_min, t.tm_sec);
+    return buf;
+}
+
+namespace gpx {
+
+std::string header(const std::string& name) {
+    return "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
+           "<gpx version=\"1.1\" creator=\"roro9stack\" xmlns=\"http://www.topografix.com/GPX/1/1\">\n"
+           "<trk><name>" + name + "</name><trkseg>";
+}
+
+std::string point(double lat, double lon, bool hasElevation, float elevationM, int64_t utcSeconds) {
+    struct tm t = utc(utcSeconds);
+    char buf[160], ele[32] = "";
+    if (hasElevation) std::snprintf(ele, sizeof ele, "<ele>%.1f</ele>", elevationM);
+    std::snprintf(buf, sizeof buf,
+                  "<trkpt lat=\"%.7f\" lon=\"%.7f\">%s<time>%04d-%02d-%02dT%02d:%02d:%02dZ</time></trkpt>", lat, lon,
+                  ele, t.tm_year + 1900, t.tm_mon + 1, t.tm_mday, t.tm_hour, t.tm_min, t.tm_sec);
+    return buf;
+}
+
+std::string footer() { return "</trkseg></trk></gpx>"; }
+
+bool finished(const std::string& tail) {
+    size_t end = tail.find_last_not_of(" \r\n\t");
+    return end != std::string::npos && end + 1 >= 6 && tail.compare(end + 1 - 6, 6, "</gpx>") == 0;
+}
+
+}  // namespace gpx
+
+}  // namespace roro::gnss

lib/gnss/src/track.h

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace roro::gnss {
+
+// Great-circle distance in metres (haversine, mean Earth radius).
+double distanceMeters(double lat1, double lon1, double lat2, double lon2);
+
+// When a Track takes its next point (Q63): the first one always, then at least every 5 s and only
+// after moving at least 5 m, so standing still doesn't fill the card.
+class TrackRule {
+   public:
+    static constexpr uint32_t kEveryMs = 5000;
+    static constexpr double kMinMeters = 5.0;
+
+    // True if this position should be recorded (and is then remembered as the last point).
+    bool due(uint32_t nowMs, double lat, double lon);
+    void reset() { any_ = false; }
+
+   private:
+    bool any_ = false;
+    uint32_t lastMs_ = 0;
+    double lat_ = 0, lon_ = 0;
+};
+
+// "/gnss/tracks/YYYYMMDD-HHMMSS.gpx", from the UTC start time (Storage Clean-up reads its date).
+std::string trackPath(int64_t utcSeconds);
+
+// GPX 1.1, written a line at a time: the header when a Track starts, a point per line, the footer
+// when it stops. A file whose footer never came (power lost) is closed at the next boot.
+namespace gpx {
+std::string header(const std::string& name);
+std::string point(double lat, double lon, bool hasElevation, float elevationM, int64_t utcSeconds);
+std::string footer();
+bool finished(const std::string& tail);  // the end of a file: does it close the GPX?
+}  // namespace gpx
+
+}  // namespace roro::gnss

lib/input/src/key_mapper.cpp

@@ -0,0 +1,114 @@
+#include "key_mapper.h"
+
+#include <algorithm>
+
+namespace roro {
+
+namespace {
+
+constexpr char kArmed = '*';
+
+bool isAccent(char c) { return c == '\'' || c == '`' || c == '^' || c == '"' || c == ',' || c == '~'; }
+
+// Latin-1 code point for accent + base letter, or 0.
+uint32_t composeLatin1(char accent, char base) {
+    struct Entry {
+        char accent;
+        const char* bases;
+        const uint32_t* codes;
+    };
+    static const uint32_t acute[] = {0xE1, 0xE9, 0xED, 0xF3, 0xFA, 0xFD, 0xC1, 0xC9, 0xCD, 0xD3, 0xDA, 0xDD};
+    static const uint32_t grave[] = {0xE0, 0xE8, 0xEC, 0xF2, 0xF9, 0xC0, 0xC8, 0xCC, 0xD2, 0xD9};
+    static const uint32_t circ[] = {0xE2, 0xEA, 0xEE, 0xF4, 0xFB, 0xC2, 0xCA, 0xCE, 0xD4, 0xDB};
+    static const uint32_t diaer[] = {0xE4, 0xEB, 0xEF, 0xF6, 0xFC, 0xFF, 0xC4, 0xCB, 0xCF, 0xD6, 0xDC};
+    static const uint32_t cedil[] = {0xE7, 0xC7};
+    static const uint32_t tilde[] = {0xE3, 0xF1, 0xF5, 0xC3, 0xD1, 0xD5};
+    static const Entry table[] = {
+        {'\'', "aeiouyAEIOUY", acute}, {'`', "aeiouAEIOU", grave}, {'^', "aeiouAEIOU", circ},
+        {'"', "aeiouyAEIOU", diaer},   {',', "cC", cedil},         {'~', "anoANO", tilde},
+    };
+    for (auto& e : table) {
+        if (e.accent != accent) continue;
+        for (int i = 0; e.bases[i]; i++)
+            if (e.bases[i] == base) return e.codes[i];
+    }
+    return 0;
+}
+
+KeyEvent charEvent(uint32_t cp, const RawKeys& keys) {
+    KeyEvent e = KeyEvent::character(cp);
+    e.shift = keys.shift;
+    e.ctrl = keys.ctrl;
+    e.alt = keys.alt;
+    return e;
+}
+
+}  // namespace
+
+std::vector<KeyEvent> KeyMapper::update(const RawKeys& keys) {
+    std::vector<KeyEvent> out;
+
+    if (keys.opt && !previous_.opt && keys.chars.empty()) {
+        compose_ = compose_ ? 0 : kArmed;  // a second opt cancels
+    }
+    if (keys.enter && !previous_.enter) out.push_back(KeyEvent::of(Key::Select));
+    if (keys.del && !previous_.del) out.push_back(KeyEvent::of(Key::Delete));
+    if (keys.tab && !previous_.tab) out.push_back(KeyEvent::of(Key::Tab));
+
+    for (char c : keys.chars) {
+        bool wasHeld = std::find(previous_.chars.begin(), previous_.chars.end(), c) != previous_.chars.end();
+        if (!wasHeld) onChar(c, keys, out);
+    }
+
+    previous_ = keys;
+    return out;
+}
+
+void KeyMapper::onChar(char c, const RawKeys& keys, std::vector<KeyEvent>& out) {
+    // Holding opt while typing the accent is the same as pressing opt first.
+    if (keys.opt && !compose_) compose_ = kArmed;
+
+    if (compose_ == kArmed) {
+        if (isAccent(c)) {
+            compose_ = c;
+            return;
+        }
+        compose_ = 0;  // not an accent: type it normally below
+    } else if (compose_) {
+        char accent = compose_;
+        compose_ = 0;
+        uint32_t composed = composeLatin1(accent, c);
+        if (composed) {
+            out.push_back(charEvent(composed, keys));
+        } else {
+            out.push_back(charEvent(static_cast<unsigned char>(accent), keys));
+            out.push_back(charEvent(static_cast<unsigned char>(c), keys));
+        }
+        return;
+    }
+
+    if (keys.fn || !textEntry_) {
+        switch (c) {
+            case ';': out.push_back(KeyEvent::of(Key::Up)); return;
+            case '.': out.push_back(KeyEvent::of(Key::Down)); return;
+            case ',': out.push_back(KeyEvent::of(Key::Left)); return;
+            case '/': out.push_back(KeyEvent::of(Key::Right)); return;
+            case '`':
+                if (keys.fn) {
+                    out.push_back(KeyEvent::of(Key::Home));
+                    return;
+                }
+                break;
+            default:
+                if (keys.fn) return;  // other Fn combos are unassigned
+                break;
+        }
+    }
+    if (c == '`') {
+        out.push_back(KeyEvent::of(Key::Back));
+        return;
+    }
+    out.push_back(charEvent(static_cast<unsigned char>(c), keys));
+}
+
+}  // namespace roro

lib/input/src/key_mapper.h

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <cstdint>
+#include <vector>
+
+#include "key_event.h"
+
+namespace roro {
+
+// The physical keyboard state as reported by the keyboard driver: every character key currently
+// held (already shifted) plus the modifier and special keys.
+struct RawKeys {
+    std::vector<char> chars;
+    bool fn = false;
+    bool opt = false;
+    bool ctrl = false;
+    bool alt = false;
+    bool shift = false;
+    bool enter = false;
+    bool del = false;
+    bool tab = false;
+};
+
+// Turns keyboard state changes into logical KeyEvents: only newly pressed keys produce events;
+// Fn + ; . , / are arrows, and so are ; . , / alone when no text is being entered; ` is Back and
+// Fn + ` is Home; the Compose Key (opt) followed by an accent and a letter types the accented
+// letter (opt ' e -> é).
+class KeyMapper {
+   public:
+    std::vector<KeyEvent> update(const RawKeys& keys);
+
+    // Whether the foreground App is editing text (default). Outside text entry, the arrow keys
+    // don't need Fn.
+    void setTextEntry(bool active) { textEntry_ = active; }
+
+    // 0 when idle, '*' when opt was pressed, or the accent character waiting for its letter.
+    char pendingCompose() const { return compose_; }
+
+   private:
+    void onChar(char c, const RawKeys& keys, std::vector<KeyEvent>& out);
+
+    RawKeys previous_;
+    char compose_ = 0;
+    bool textEntry_ = true;
+};
+
+}  // namespace roro

lib/irc/src/base64.h

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <string>
+
+namespace roro {
+
+inline std::string base64Encode(const std::string& in) {
+    static const char* kAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    std::string out;
+    size_t i = 0;
+    while (i + 2 < in.size()) {
+        uint32_t n = (static_cast<uint8_t>(in[i]) << 16) | (static_cast<uint8_t>(in[i + 1]) << 8) | static_cast<uint8_t>(in[i + 2]);
+        out += kAlphabet[n >> 18];
+        out += kAlphabet[(n >> 12) & 63];
+        out += kAlphabet[(n >> 6) & 63];
+        out += kAlphabet[n & 63];
+        i += 3;
+    }
+    size_t rest = in.size() - i;
+    if (rest) {
+        uint32_t n = static_cast<uint8_t>(in[i]) << 16;
+        if (rest == 2) n |= static_cast<uint8_t>(in[i + 1]) << 8;
+        out += kAlphabet[n >> 18];
+        out += kAlphabet[(n >> 12) & 63];
+        out += rest == 2 ? kAlphabet[(n >> 6) & 63] : '=';
+        out += '=';
+    }
+    return out;
+}
+
+}  // namespace roro

lib/irc/src/irc_config.cpp

@@ -0,0 +1,84 @@
+#include "irc_config.h"
+
+#include <cctype>
+#include <cstring>
+
+namespace roro {
+
+namespace {
+bool validNick(const std::string& n) {
+    if (n.empty() || n.size() > 30) return false;
+    if (std::isdigit(static_cast<unsigned char>(n[0])) || n[0] == '-') return false;
+    for (char c : n)
+        if (!std::isalnum(static_cast<unsigned char>(c)) && !std::strchr("[]\\`_^{|}-", c)) return false;
+    return true;
+}
+}  // namespace
+
+void IrcConfig::load(const std::string& defaultNick) {
+    nick = defaultNick;
+    std::string s;
+    int32_t i;
+    if (store_.getString("irc_host", s)) host = s;
+    if (store_.getInt("irc_port", i)) port = i;
+    if (store_.getInt("irc_tls", i)) tls = i != 0;
+    if (store_.getInt("irc_selfsign", i)) allowSelfSigned = i != 0;
+    store_.getString("irc_pin", pinnedSha256);
+    if (store_.getString("irc_nick", s)) nick = s;
+    store_.getString("irc_sasl_user", saslUser);
+    store_.getString("irc_sasl_pass", saslPassword);
+    store_.getString("irc_ns_pass", nickservPassword);
+    if (store_.getString("irc_join", s)) autojoin = parseChannels(s);
+}
+
+std::string IrcConfig::validate() const {
+    if (host.empty() || host.size() > 63) return "Server must be 1 to 63 characters";
+    if (port < 1 || port > 65535) return "Port must be 1 to 65535";
+    if (!validNick(nick)) return "Nick: letters, digits and []\\`_^{|}- only, not starting with a digit";
+    for (auto& c : autojoin)
+        if (c.channel.size() < 2 || (c.channel[0] != '#' && c.channel[0] != '&'))
+            return "Auto-join: IRC channels start with # or &, each followed by its key if it has one";
+    return "";
+}
+
+std::string IrcConfig::save() {
+    std::string error = validate();
+    if (!error.empty()) return error;
+    store_.putString("irc_host", host);
+    store_.putInt("irc_port", port);
+    store_.putInt("irc_tls", tls ? 1 : 0);
+    store_.putInt("irc_selfsign", allowSelfSigned ? 1 : 0);
+    store_.putString("irc_pin", pinnedSha256);
+    store_.putString("irc_nick", nick);
+    store_.putString("irc_sasl_user", saslUser);
+    store_.putString("irc_sasl_pass", saslPassword);
+    store_.putString("irc_ns_pass", nickservPassword);
+    store_.putString("irc_join", formatChannels(autojoin));
+    return "";
+}
+
+std::vector<IrcChannel> IrcConfig::parseChannels(const std::string& text) {
+    std::vector<IrcChannel> out;
+    std::string word;
+    auto take = [&]() {
+        if (word.empty()) return;
+        bool channel = word[0] == '#' || word[0] == '&';
+        if (!channel && !out.empty() && out.back().key.empty()) out.back().key = word;
+        else out.push_back({word, ""});  // a stray word fails validation as a channel
+        word.clear();
+    };
+    for (char c : text) {
+        if (c == ' ' || c == ',') take();
+        else word += c;
+    }
+    take();
+    return out;
+}
+
+std::string IrcConfig::formatChannels(const std::vector<IrcChannel>& channels) {
+    std::string out;
+    for (auto& c : channels) out += (out.empty() ? "" : ", ") + c.channel + (c.key.empty() ? "" : " " + c.key);
+    return out;
+}
+
+}  // namespace roro

lib/irc/src/irc_config.h

@@ -0,0 +1,58 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "key_value_store.h"
+
+namespace roro {
+
+struct IrcChannel {
+    std::string channel;  // "#roro"
+    std::string key;      // empty when the IRC channel has none
+};
+
+// The one IRC server the IRC Service connects to, persisted in internal flash.
+class IrcConfig {
+   public:
+    explicit IrcConfig(KeyValueStore& store) : store_(store) {}
+
+    std::string host = "irc.libera.chat";
+    int port = 6697;
+    bool tls = true;
+    bool allowSelfSigned = false;  // pin the certificate on first use instead of checking a CA
+    std::string pinnedSha256;      // hex fingerprint once pinned
+    std::string nick;
+    std::string saslUser, saslPassword;  // SASL PLAIN when both are set
+    std::string nickservPassword;        // otherwise IDENTIFY with NickServ, if set
+    std::vector<IrcChannel> autojoin;
+
+    // A copy is a draft the UI can edit freely; copySettingsFrom() applies one.
+    IrcConfig(const IrcConfig&) = default;
+    void copySettingsFrom(const IrcConfig& other) {
+        host = other.host;
+        port = other.port;
+        tls = other.tls;
+        allowSelfSigned = other.allowSelfSigned;
+        pinnedSha256 = other.pinnedSha256;
+        nick = other.nick;
+        saslUser = other.saslUser;
+        saslPassword = other.saslPassword;
+        nickservPassword = other.nickservPassword;
+        autojoin = other.autojoin;
+    }
+
+    void load(const std::string& defaultNick);
+    std::string save();  // empty on success, otherwise why it was refused
+    std::string validate() const;
+
+    // "#private key, #public": a word starting with # or & is an IRC channel, the word after it
+    // (if it doesn't) its key. Spaces or commas separate entries, so "#a #b" also reads.
+    static std::vector<IrcChannel> parseChannels(const std::string& text);
+    static std::string formatChannels(const std::vector<IrcChannel>& channels);
+
+   private:
+    KeyValueStore& store_;
+};
+
+}  // namespace roro

lib/irc/src/irc_message.cpp

@@ -0,0 +1,43 @@
+#include "irc_message.h"
+
+namespace roro {
+
+IrcMessage IrcMessage::parse(const std::string& raw) {
+    IrcMessage m;
+    std::string line = raw;
+    while (!line.empty() && (line.back() == '\r' || line.back() == '\n')) line.pop_back();
+
+    size_t pos = 0;
+    auto word = [&]() {
+        size_t end = line.find(' ', pos);
+        std::string w = line.substr(pos, end == std::string::npos ? std::string::npos : end - pos);
+        pos = end == std::string::npos ? line.size() : end + 1;
+        while (pos < line.size() && line[pos] == ' ') pos++;
+        return w;
+    };
+    if (pos < line.size() && line[pos] == '@') word();
+    if (pos < line.size() && line[pos] == ':') m.prefix = word().substr(1);
+    m.command = word();
+    while (pos < line.size()) {
+        if (line[pos] == ':') {
+            m.params.push_back(line.substr(pos + 1));
+            break;
+        }
+        m.params.push_back(word());
+    }
+    return m;
+}
+
+std::string IrcMessage::serialize(const std::string& command, std::initializer_list<std::string> params) {
+    std::string out = command;
+    size_t i = 0;
+    for (auto& p : params) {
+        bool last = ++i == params.size();
+        out += ' ';
+        if (last && (p.empty() || p[0] == ':' || p.find(' ') != std::string::npos)) out += ':';
+        out += p;
+    }
+    return out;
+}
+
+}  // namespace roro

lib/irc/src/irc_message.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <initializer_list>
+#include <string>
+#include <vector>
+
+namespace roro {
+
+// One IRC protocol line: [@tags] [:prefix] COMMAND params... [:trailing] (tags are ignored).
+struct IrcMessage {
+    std::string prefix;
+    std::string command;
+    std::vector<std::string> params;
+
+    std::string nick() const { return prefix.substr(0, prefix.find('!')); }
+    std::string param(size_t i) const { return i < params.size() ? params[i] : ""; }
+
+    static IrcMessage parse(const std::string& line);
+    // Builds a line; the last parameter gets a ':' when it needs one.
+    static std::string serialize(const std::string& command, std::initializer_list<std::string> params);
+};
+
+}  // namespace roro

lib/irc/src/irc_session.cpp

@@ -0,0 +1,369 @@
+#include "irc_session.h"
+
+#include <algorithm>
+#include <cctype>
+
+#include "base64.h"
+
+namespace roro {
+
+namespace {
+
+const char kCtcp = '\x01';
+
+std::string lower(std::string s) {
+    for (auto& c : s) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return s;
+}
+
+bool isChannel(const std::string& name) { return !name.empty() && (name[0] == '#' || name[0] == '&'); }
+
+bool nickChar(char c) { return std::isalnum(static_cast<unsigned char>(c)) || std::string("[]\\`_^{|}-").find(c) != std::string::npos; }
+
+std::string join(const std::vector<std::string>& params, size_t from) {
+    std::string out;
+    for (size_t i = from; i < params.size(); i++) out += (out.empty() ? "" : " ") + params[i];
+    return out;
+}
+
+// Splits "word rest of text" into the first word and the rest.
+std::pair<std::string, std::string> firstWord(const std::string& text) {
+    size_t space = text.find(' ');
+    if (space == std::string::npos) return {text, ""};
+    return {text.substr(0, space), text.substr(space + 1)};
+}
+
+}  // namespace
+
+IrcSession::IrcSession(const IrcConfig& config) : config_(config), nick_(config.nick) {
+    buffers_.push_back({config.host, IrcBuffer::Type::Server, {}, 0, false, true, ""});
+    for (auto& c : config.autojoin)
+        if (!c.key.empty()) keys_[lower(c.channel)] = c.key;
+}
+
+void IrcSession::tick(uint32_t nowMs) {
+    nowMs_ = nowMs;
+    if (joinsHeld_ && nowMs - heldSinceMs_ >= kNickservWaitMs) joinChannels();
+}
+
+int IrcSession::totalUnread() const {
+    int n = 0;
+    for (auto& b : buffers_) n += b.unread;
+    return n;
+}
+
+IrcEffects IrcSession::takeEffects() {
+    IrcEffects out;
+    std::swap(out, effects_);
+    return out;
+}
+
+int IrcSession::findBuffer(const std::string& name) const {
+    for (int i = 0; i < bufferCount(); i++)
+        if (lower(buffers_[i].name) == lower(name)) return i;
+    return -1;
+}
+
+int IrcSession::bufferFor(const std::string& name, IrcBuffer::Type type) {
+    int i = findBuffer(name);
+    if (i >= 0) return i;
+    if (bufferCount() >= kMaxBuffers) return 0;  // full: fall back to the server Buffer
+    buffers_.push_back({name, type, {}, 0, false, false, ""});
+    revision_++;
+    return bufferCount() - 1;
+}
+
+void IrcSession::setViewing(int buffer) {
+    viewing_ = buffer;
+    revision_++;
+    if (buffer >= 0 && buffer < bufferCount()) {
+        buffers_[buffer].unread = 0;
+        buffers_[buffer].mentioned = false;
+    }
+}
+
+bool IrcSession::mentionsMe(const std::string& text) const {
+    std::string hay = lower(text), needle = lower(nick_);
+    for (size_t pos = hay.find(needle); pos != std::string::npos; pos = hay.find(needle, pos + 1)) {
+        bool startOk = pos == 0 || !nickChar(hay[pos - 1]);
+        size_t end = pos + needle.size();
+        bool endOk = end >= hay.size() || !nickChar(hay[end]);
+        if (startOk && endOk) return true;
+    }
+    return false;
+}
+
+void IrcSession::add(int b, IrcLine::Kind kind, const std::string& nick, const std::string& text, int64_t utc,
+                     bool mention) {
+    IrcBuffer& buf = buffers_[b];
+    revision_++;
+    IrcLine line{utc, kind, nick, text};
+    buf.lines.push_back(line);
+    if (buf.lines.size() > kLinesPerBuffer) buf.lines.pop_front();
+    effects_.logs.push_back({buf.name, line});
+
+    bool fromOthers = kind == IrcLine::Kind::Message || kind == IrcLine::Kind::Action || kind == IrcLine::Kind::Notice;
+    if (b != viewing_ && fromOthers && buf.type != IrcBuffer::Type::Server) {
+        buf.unread++;
+        if (mention) {
+            buf.mentioned = true;
+            std::string where = buf.type == IrcBuffer::Type::Query ? nick : nick + " in " + buf.name;
+            effects_.notifications.push_back(where + ": " + text);
+        }
+    }
+}
+
+void IrcSession::connected(int64_t) {
+    registered_ = false;
+    joinsHeld_ = false;
+    saslFailed_ = false;
+    quit_ = false;
+    nick_ = config_.nick;
+    if (!config_.saslUser.empty() && !config_.saslPassword.empty()) send("CAP REQ :sasl");
+    send(IrcMessage::serialize("NICK", {nick_}));
+    send(IrcMessage::serialize("USER", {nick_, "0", "*", "roro9stack"}));
+}
+
+void IrcSession::disconnected(int64_t utc, const std::string& reason) {
+    registered_ = false;
+    quit_ = false;
+    rejoin_.clear();
+    for (int i = 0; i < bufferCount(); i++) {
+        if (buffers_[i].type == IrcBuffer::Type::Channel && buffers_[i].joined) rejoin_.push_back(buffers_[i].name);
+        if (buffers_[i].type == IrcBuffer::Type::Channel) buffers_[i].joined = false;
+        info(i, "-- " + reason + " --", utc);
+    }
+}
+
+void IrcSession::onWelcome(const IrcMessage& m, int64_t utc) {
+    registered_ = true;
+    nick_ = m.param(0);
+    info(0, "Connected to " + config_.host + " as " + nick_, utc);
+    // NickServ when it's the configured login, or as the fallback when SASL failed.
+    // The account is named explicitly: we may be on a fallback nick if a stale session holds ours.
+    bool sasl = !config_.saslUser.empty() && !config_.saslPassword.empty();
+    std::string account = sasl ? config_.saslUser : config_.nick;
+    std::string identify;
+    if (!config_.nickservPassword.empty() && (!sasl || saslFailed_)) identify = account + " " + config_.nickservPassword;
+    else if (sasl && saslFailed_) identify = account + " " + config_.saslPassword;
+    if (!identify.empty()) {
+        // IRC channels for registered users only would refuse us until NickServ has logged us in.
+        send(IrcMessage::serialize("PRIVMSG", {"NickServ", "IDENTIFY " + identify}));
+        joinsHeld_ = true;
+        heldSinceMs_ = nowMs_;
+        return;
+    }
+    joinChannels();
+}
+
+void IrcSession::joinChannels() {
+    joinsHeld_ = false;
+    std::vector<std::string> channels;
+    auto addOnce = [&](const std::string& c) {
+        for (auto& existing : channels)
+            if (lower(existing) == lower(c)) return;
+        channels.push_back(c);
+    };
+    for (auto& c : config_.autojoin) addOnce(c.channel);
+    for (auto& c : rejoin_) addOnce(c);
+    rejoin_.clear();
+    if (channels.empty()) return;
+
+    // JOIN #keyed,#open key: IRC pairs keys with the first channels listed.
+    std::string keyed, open, keys;
+    for (auto& c : channels) {
+        auto k = keys_.find(lower(c));
+        if (k != keys_.end()) {
+            keyed += (keyed.empty() ? "" : ",") + c;
+            keys += (keys.empty() ? "" : ",") + k->second;
+        } else {
+            open += (open.empty() ? "" : ",") + c;
+        }
+    }
+    std::string list = keyed + (!keyed.empty() && !open.empty() ? "," : "") + open;
+    send(keys.empty() ? IrcMessage::serialize("JOIN", {list}) : IrcMessage::serialize("JOIN", {list, keys}));
+}
+
+void IrcSession::receive(const std::string& raw, int64_t utc) {
+    IrcMessage m = IrcMessage::parse(raw);
+    const std::string& cmd = m.command;
+    bool fromMe = lower(m.nick()) == lower(nick_);
+
+    if (cmd == "PING") {
+        send(IrcMessage::serialize("PONG", {m.param(0)}));
+    } else if (cmd == "001") {
+        onWelcome(m, utc);
+    } else if (cmd == "433" && !registered_) {
+        nick_ += "_";
+        send(IrcMessage::serialize("NICK", {nick_}));
+    } else if (cmd == "CAP") {
+        std::string sub = m.param(1);
+        if (sub == "ACK" && m.param(2).find("sasl") != std::string::npos) send("AUTHENTICATE PLAIN");
+        else if (sub == "NAK") send("CAP END");
+    } else if (cmd == "AUTHENTICATE" && m.param(0) == "+") {
+        std::string user = config_.saslUser;
+        send("AUTHENTICATE " + base64Encode(user + '\0' + user + '\0' + config_.saslPassword));
+    } else if (cmd == "900") {
+        // Logged in. Take our nick back from a stale session, then join.
+        if (lower(nick_) != lower(config_.nick))
+            send(IrcMessage::serialize("PRIVMSG", {"NickServ", "REGAIN " + config_.nick}));
+        if (joinsHeld_) joinChannels();
+    } else if (cmd == "903") {
+        info(0, "SASL login succeeded", utc);
+        send("CAP END");
+    } else if (cmd == "904" || cmd == "905" || cmd == "906" || cmd == "902") {
+        info(0, "SASL login failed: " + m.param(m.params.size() - 1) + " (trying NickServ instead)", utc);
+        saslFailed_ = true;
+        send("CAP END");
+    } else if (cmd == "PRIVMSG" || cmd == "NOTICE") {
+        onPrivmsg(m, utc, cmd == "NOTICE");
+    } else if (cmd == "JOIN") {
+        if (fromMe) {
+            int b = bufferFor(m.param(0), IrcBuffer::Type::Channel);
+            buffers_[b].joined = true;
+            info(b, "Joined " + m.param(0), utc);
+        }
+    } else if (cmd == "PART") {
+        int b = findBuffer(m.param(0));
+        if (fromMe && b > 0) {
+            buffers_[b].joined = false;
+            info(b, "Left " + m.param(0), utc);
+        }
+    } else if (cmd == "KICK") {
+        int b = findBuffer(m.param(0));
+        if (lower(m.param(1)) == lower(nick_) && b > 0) {
+            buffers_[b].joined = false;
+            add(b, IrcLine::Kind::Notice, m.nick(), "kicked you: " + m.param(2), utc, true);
+        }
+    } else if (cmd == "NICK") {
+        if (fromMe) {
+            nick_ = m.param(0);
+            info(0, "You are now " + nick_, utc);
+        } else {
+            int b = findBuffer(m.nick());
+            if (b > 0) {
+                buffers_[b].name = m.param(0);
+                info(b, m.nick() + " is now " + m.param(0), utc);
+            }
+        }
+    } else if (cmd == "TOPIC") {
+        int b = findBuffer(m.param(0));
+        if (b > 0) {
+            buffers_[b].topic = m.param(1);
+            info(b, m.nick() + " set the topic: " + m.param(1), utc);
+        }
+    } else if (cmd == "332") {
+        int b = findBuffer(m.param(1));
+        if (b > 0) {
+            buffers_[b].topic = m.param(2);
+            info(b, "Topic: " + m.param(2), utc);
+        }
+    } else if (cmd == "353") {
+        std::string channel = m.param(2);
+        int b = findBuffer(channel);
+        if (namesRequested_.count(lower(channel)) && b >= 0) info(b, "Names: " + m.param(3), utc);
+    } else if (cmd == "366") {
+        namesRequested_.erase(lower(m.param(1)));
+    } else if (cmd == "ERROR") {
+        info(0, "Server: " + m.param(0), utc);
+    } else if (cmd.size() == 3 && std::isdigit(static_cast<unsigned char>(cmd[0])) && cmd != "333" && cmd != "353") {
+        info(0, join(m.params, 1), utc);  // other numerics, minus our own nick
+    }
+}
+
+void IrcSession::onPrivmsg(const IrcMessage& m, int64_t utc, bool notice) {
+    std::string target = m.param(0), text = m.param(1), from = m.nick();
+    bool toMe = lower(target) == lower(nick_);
+
+    // CTCP: ACTION is shown, VERSION answered, anything else ignored.
+    bool action = false;
+    if (!text.empty() && text[0] == kCtcp) {
+        std::string body = text.substr(1, text.size() >= 2 && text.back() == kCtcp ? text.size() - 2 : std::string::npos);
+        auto [verb, rest] = firstWord(body);
+        if (verb == "ACTION") {
+            action = true;
+            text = rest;
+        } else {
+            if (verb == "VERSION" && !notice) send(std::string("NOTICE ") + from + " :" + kCtcp + "VERSION roro9stack" + kCtcp);
+            return;
+        }
+    }
+
+    int b;
+    if (notice && (from.empty() || from.find('.') != std::string::npos || !registered_ || target == "*")) {
+        b = 0;  // server notices
+    } else if (toMe) {
+        b = notice ? (findBuffer(from) > 0 ? findBuffer(from) : 0) : bufferFor(from, IrcBuffer::Type::Query);
+    } else {
+        b = bufferFor(target, IrcBuffer::Type::Channel);
+    }
+    auto kind = notice ? IrcLine::Kind::Notice : action ? IrcLine::Kind::Action : IrcLine::Kind::Message;
+    bool mention = !notice && (toMe || mentionsMe(text));
+    add(b, kind, from, text, utc, mention);
+}
+
+void IrcSession::say(int b, const std::string& text, int64_t utc, bool action) {
+    const IrcBuffer& buf = buffers_[b];
+    if (buf.type == IrcBuffer::Type::Server) {
+        info(b, "This is the server Buffer: /join #name an IRC channel, or /msg nick text", utc);
+        return;
+    }
+    std::string payload = action ? std::string(1, kCtcp) + "ACTION " + text + kCtcp : text;
+    send(IrcMessage::serialize("PRIVMSG", {buf.name, payload}));
+    add(b, action ? IrcLine::Kind::OwnAction : IrcLine::Kind::Own, nick_, text, utc);
+}
+
+void IrcSession::input(int b, const std::string& text, int64_t utc) {
+    if (b < 0 || b >= bufferCount() || text.empty()) return;
+    if (text.size() >= 2 && text[0] == '/' && text[1] == '/') return say(b, text.substr(1), utc, false);
+    if (text[0] == '/') return command(b, text.substr(1), utc);
+    say(b, text, utc, false);
+}
+
+void IrcSession::command(int b, const std::string& text, int64_t utc) {
+    auto [verb, rest] = firstWord(text);
+    verb = lower(verb);
+    const IrcBuffer& buf = buffers_[b];
+    bool inChannel = buf.type == IrcBuffer::Type::Channel;
+
+    if (verb == "join" || verb == "j") {
+        auto [channel, key] = firstWord(rest);
+        if (channel.empty()) return info(b, "Usage: /join #channel", utc);
+        if (!isChannel(channel)) channel = "#" + channel;
+        if (!key.empty()) keys_[lower(channel)] = key;  // reused when rejoining
+        send(key.empty() ? IrcMessage::serialize("JOIN", {channel}) : IrcMessage::serialize("JOIN", {channel, key}));
+    } else if (verb == "part") {
+        std::string channel = inChannel ? buf.name : "";
+        std::string message = rest;
+        if (isChannel(rest)) std::tie(channel, message) = firstWord(rest);
+        if (channel.empty()) return info(b, "Usage: /part #channel", utc);
+        send(message.empty() ? IrcMessage::serialize("PART", {channel}) : IrcMessage::serialize("PART", {channel, message}));
+    } else if (verb == "msg" || verb == "query") {
+        auto [who, message] = firstWord(rest);
+        if (who.empty()) return info(b, "Usage: /msg nick text", utc);
+        int target = bufferFor(who, isChannel(who) ? IrcBuffer::Type::Channel : IrcBuffer::Type::Query);
+        if (!message.empty()) say(target, message, utc, false);
+    } else if (verb == "me") {
+        say(b, rest, utc, true);
+    } else if (verb == "nick") {
+        if (rest.empty()) return info(b, "Usage: /nick newnick", utc);
+        send(IrcMessage::serialize("NICK", {rest}));
+    } else if (verb == "topic") {
+        if (!inChannel) return info(b, "Use /topic in an IRC channel", utc);
+        send(rest.empty() ? IrcMessage::serialize("TOPIC", {buf.name}) : IrcMessage::serialize("TOPIC", {buf.name, rest}));
+    } else if (verb == "names") {
+        std::string channel = rest.empty() ? (inChannel ? buf.name : "") : rest;
+        if (channel.empty()) return info(b, "Usage: /names #channel", utc);
+        namesRequested_.insert(lower(channel));
+        send(IrcMessage::serialize("NAMES", {channel}));
+    } else if (verb == "quit") {
+        quit_ = true;
+        send(IrcMessage::serialize("QUIT", {rest.empty() ? "roro9stack" : rest}));
+    } else if (verb == "raw" || verb == "quote") {
+        if (!rest.empty()) send(rest);
+    } else {
+        info(b, "Unknown command /" + verb + " (try /join or /j, /part /msg /me /nick /topic /names /quit /raw)", utc);
+    }
+}
+
+}  // namespace roro

lib/irc/src/irc_session.h

@@ -0,0 +1,114 @@
+#pragma once
+
+#include <cstdint>
+#include <deque>
+#include <map>
+#include <set>
+#include <string>
+#include <vector>
+
+#include "irc_config.h"
+#include "irc_message.h"
+
+namespace roro {
+
+struct IrcLine {
+    enum class Kind { Message, Action, Notice, Info, Own, OwnAction };
+    int64_t utc;  // -1 if the clock wasn't set
+    Kind kind;
+    std::string nick;
+    std::string text;
+};
+
+// One IRC conversation (see Buffer in CONTEXT.md).
+struct IrcBuffer {
+    enum class Type { Server, Channel, Query };
+    std::string name;
+    Type type;
+    std::deque<IrcLine> lines;  // the most recent kLinesPerBuffer; full history goes to Logs
+    int unread = 0;
+    bool mentioned = false;
+    bool joined = false;
+    std::string topic;
+};
+
+struct IrcLogEntry {
+    std::string buffer;
+    IrcLine line;
+};
+
+// What the session wants done: lines to send, Log entries, Notification texts.
+struct IrcEffects {
+    std::vector<std::string> send;
+    std::vector<IrcLogEntry> logs;
+    std::vector<std::string> notifications;
+};
+
+// The IRC protocol, without any networking: registration (SASL PLAIN or NickServ), Buffers,
+// unread counts, Mentions, the user's commands, and rejoining after a pause. The IRC Service
+// feeds it received lines and carries out the effects.
+class IrcSession {
+   public:
+    static constexpr size_t kLinesPerBuffer = 50;
+    static constexpr int kMaxBuffers = 12;
+
+    explicit IrcSession(const IrcConfig& config);
+
+    // Joins wait this long for NickServ to confirm a login before going ahead anyway.
+    static constexpr uint32_t kNickservWaitMs = 2000;
+
+    // Uptime in ms, called regularly: releases joins held back for NickServ.
+    void tick(uint32_t nowMs);
+
+    void connected(int64_t utc);
+    void disconnected(int64_t utc, const std::string& reason);
+    void receive(const std::string& raw, int64_t utc);
+    void input(int buffer, const std::string& text, int64_t utc);
+
+    // The Buffer the user is looking at (-1: none); it neither counts unread nor notifies.
+    void setViewing(int buffer);
+
+    bool registered() const { return registered_; }
+    bool quitRequested() const { return quit_; }
+    const std::string& nick() const { return nick_; }
+
+    int bufferCount() const { return static_cast<int>(buffers_.size()); }
+    const IrcBuffer& buffer(int i) const { return buffers_[i]; }
+    int totalUnread() const;
+    // Changes whenever a Buffer gains a line or changes, so a view knows when to redraw.
+    uint32_t revision() const { return revision_; }
+
+    IrcEffects takeEffects();
+
+   private:
+    void send(const std::string& line) { effects_.send.push_back(line); }
+    int findBuffer(const std::string& name) const;
+    int bufferFor(const std::string& name, IrcBuffer::Type type);  // creates if needed and possible
+    void add(int buffer, IrcLine::Kind kind, const std::string& nick, const std::string& text, int64_t utc,
+             bool countsAsMention = false);
+    void info(int buffer, const std::string& text, int64_t utc) { add(buffer, IrcLine::Kind::Info, "", text, utc); }
+    bool mentionsMe(const std::string& text) const;
+    void onPrivmsg(const IrcMessage& m, int64_t utc, bool notice);
+    void onWelcome(const IrcMessage& m, int64_t utc);
+    void joinChannels();
+    void command(int buffer, const std::string& text, int64_t utc);
+    void say(int buffer, const std::string& text, int64_t utc, bool action);
+
+    const IrcConfig& config_;
+    std::vector<IrcBuffer> buffers_;
+    std::string nick_;
+    bool registered_ = false;
+    bool quit_ = false;
+    int viewing_ = -1;
+    std::set<std::string> namesRequested_;
+    std::vector<std::string> rejoin_;  // IRC channels to join again after a reconnect
+    std::map<std::string, std::string> keys_;  // lower-case IRC channel -> key, from config and /join
+    bool joinsHeld_ = false;            // waiting for NickServ before joining
+    bool saslFailed_ = false;
+    uint32_t heldSinceMs_ = 0;
+    uint32_t nowMs_ = 0;
+    IrcEffects effects_;
+    uint32_t revision_ = 0;
+};
+
+}  // namespace roro

lib/irc/src/reconnect_policy.h

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+// Waits between IRC reconnection attempts: 5 s, 10 s, 30 s, 1 min, 2 min, then every 5 min.
+class ReconnectPolicy {
+   public:
+    uint32_t nextDelayMs() {
+        static const uint32_t kDelays[] = {5000, 10000, 30000, 60000, 120000, 300000};
+        const int n = sizeof(kDelays) / sizeof(kDelays[0]);
+        return kDelays[attempt_ < n ? attempt_++ : n - 1];
+    }
+    void reset() { attempt_ = 0; }
+
+   private:
+    int attempt_ = 0;
+};
+
+}  // namespace roro

lib/lora/src/loratap.cpp

@@ -0,0 +1,64 @@
+#include "loratap.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <ctime>
+
+namespace roro::lora {
+
+static void le16(std::vector<uint8_t>& o, uint16_t v) { o.insert(o.end(), {uint8_t(v), uint8_t(v >> 8)}); }
+static void le32(std::vector<uint8_t>& o, uint32_t v) {
+    o.insert(o.end(), {uint8_t(v), uint8_t(v >> 8), uint8_t(v >> 16), uint8_t(v >> 24)});
+}
+
+// LoRaTap's dBm encoding: -139 dBm plus the byte, clamped to what a byte holds.
+static uint8_t dbmByte(float dbm) {
+    long v = std::lround(dbm + 139);
+    return static_cast<uint8_t>(std::clamp(v, 0L, 255L));
+}
+
+std::string capturePath(int64_t utcSeconds) {
+    time_t t = static_cast<time_t>(utcSeconds);
+    struct tm u;
+    gmtime_r(&t, &u);
+    char buf[48];
+    std::snprintf(buf, sizeof buf, "/captures/lora/%04d%02d%02d-%02d%02d%02d.pcap", u.tm_year + 1900, u.tm_mon + 1,
+                  u.tm_mday, u.tm_hour, u.tm_min, u.tm_sec);
+    return buf;
+}
+
+void appendPcapHeader(std::vector<uint8_t>& out) {
+    le32(out, 0xA1B2C3D4);
+    le16(out, 2);
+    le16(out, 4);
+    le32(out, 0);      // time zone
+    le32(out, 0);      // timestamp accuracy
+    le32(out, 65535);  // snap length
+    le32(out, 270);    // LINKTYPE_LORATAP
+}
+
+void appendRecord(std::vector<uint8_t>& out, uint32_t seconds, uint32_t micros, const RxInfo& rx, const uint8_t* data,
+                  size_t len) {
+    uint32_t captured = static_cast<uint32_t>(kLoraTapSize + len);
+    le32(out, seconds);
+    le32(out, micros);
+    le32(out, captured);
+    le32(out, captured);
+
+    uint32_t f = rx.frequencyHz;
+    // The spec puts packet RSSI in quarter dB below 0 dB SNR (an SX127x formula), but Wireshark
+    // reads it as -139 dBm plus the byte either way, and the SX1262 already gives dBm.
+    uint8_t packetRssi = dbmByte(rx.rssi);
+    long snr = std::clamp(std::lround(rx.snr * 4), -128L, 127L);
+    out.insert(out.end(), {
+                              0, 0, 0, uint8_t(kLoraTapSize),  // version 0, padding, length
+                              uint8_t(f >> 24), uint8_t(f >> 16), uint8_t(f >> 8), uint8_t(f),
+                              uint8_t(std::lround(rx.bandwidthKHz / 125)), rx.spreadingFactor,
+                              packetRssi, dbmByte(rx.rssi), dbmByte(rx.noiseFloor),
+                              static_cast<uint8_t>(static_cast<int8_t>(snr)), rx.syncWord,
+                          });
+    if (len) out.insert(out.end(), data, data + len);
+}
+
+}  // namespace roro::lora

lib/lora/src/loratap.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::lora {
+
+// What the radio knew about one received packet.
+struct RxInfo {
+    uint32_t frequencyHz = 0;
+    float bandwidthKHz = 0;
+    uint8_t spreadingFactor = 0;
+    float rssi = 0;        // dBm
+    float snr = 0;         // dB
+    float noiseFloor = 0;  // dBm, instantaneous RSSI just before the packet, when known
+    uint8_t syncWord = 0;
+};
+
+// A Capture file (M3, Q97): pcap with LoRaTap v0 headers (LINKTYPE_LORATAP, 270), which Wireshark
+// reads. pcap fields are little-endian, LoRaTap fields big-endian.
+void appendPcapHeader(std::vector<uint8_t>& out);
+void appendRecord(std::vector<uint8_t>& out, uint32_t seconds, uint32_t micros, const RxInfo& rx, const uint8_t* data,
+                  size_t len);
+
+// "/captures/lora/YYYYMMDD-HHMMSS.pcap" in UTC, dated like Tracks so Storage Clean-up can age it.
+std::string capturePath(int64_t utcSeconds);
+
+constexpr size_t kLoraTapSize = 15;
+constexpr size_t kRecordOverhead = 16 + kLoraTapSize;
+
+}  // namespace roro::lora

lib/lora/src/packet_view.cpp

@@ -0,0 +1,83 @@
+#include "packet_view.h"
+
+#include <cmath>
+#include <cstdio>
+
+#include "meshtastic_header.h"
+#include "meshtastic_presets.h"
+
+namespace roro::lora {
+
+using namespace meshtastic;
+
+std::string row(const PacketSummary& p, const std::string& time) {
+    char s[64];
+    int n = std::snprintf(s, sizeof s, "%s %ld %.1f ", time.c_str(), std::lround(p.rssi), p.snr);
+    std::string out(s, n);
+    PacketHeader h;
+    if (!p.crcOk) return out + "bad CRC, " + std::to_string(p.len) + " B";
+    if (!p.meshtastic || !parseHeader(p.data, p.len, h)) return out + std::to_string(p.len) + " B";
+    auto shortId = [](uint32_t node) {
+        if (node == kBroadcast) return std::string("all");
+        char id[8];
+        std::snprintf(id, sizeof id, "%04x", static_cast<unsigned>(node & 0xFFFF));
+        return std::string(id);
+    };
+    out += shortId(h.from) + ">" + shortId(h.to);
+    if (h.hopsAway() >= 0) out += " " + std::to_string(h.hopsAway()) + "/" + std::to_string(h.hopStart());
+    return out;
+}
+
+std::vector<std::string> hexDump(const uint8_t* data, size_t len) {
+    std::vector<std::string> lines;
+    for (size_t at = 0; at < len; at += 8) {
+        char s[48];
+        int n = std::snprintf(s, sizeof s, "%04x", static_cast<unsigned>(at));
+        std::string text;
+        for (size_t i = 0; i < 8; ++i) {
+            if (at + i < len) {
+                n += std::snprintf(s + n, sizeof s - n, " %02x", data[at + i]);
+                uint8_t b = data[at + i];
+                text += b >= 0x20 && b < 0x7F ? static_cast<char>(b) : '.';
+            } else {
+                n += std::snprintf(s + n, sizeof s - n, "   ");
+            }
+        }
+        lines.push_back(std::string(s, n) + " " + text);
+    }
+    return lines;
+}
+
+std::vector<std::string> headerLines(const uint8_t* data, size_t len) {
+    PacketHeader h;
+    if (!parseHeader(data, len, h)) return {};
+    char s[64];
+    std::vector<std::string> lines;
+    lines.push_back("From " + nodeId(h.from) + " to " + nodeId(h.to));
+    std::snprintf(s, sizeof s, "Packet %08x%s%s", static_cast<unsigned>(h.id), h.wantAck() ? ", wants an ack" : "",
+                  h.viaMqtt() ? ", via MQTT" : "");
+    lines.push_back(s);
+    if (h.hopsAway() >= 0)
+        std::snprintf(s, sizeof s, "Hops %d of %u, limit %u left", h.hopsAway(), h.hopStart(), h.hopLimit());
+    else
+        std::snprintf(s, sizeof s, "Hop limit %u left (old firmware)", h.hopLimit());
+    lines.push_back(s);
+    // Which preset's default Channel (named after it, with the public key) has this hash.
+    std::string channel;
+    for (size_t i = 0; i < kEu868PresetCount && channel.empty(); ++i)
+        if (channelHash(kEu868Presets[i].name, kDefaultKey, sizeof kDefaultKey) == h.channelHash)
+            channel = std::string(" (") + kEu868Presets[i].name + ", default key)";
+    std::snprintf(s, sizeof s, "Channel 0x%02x%s", h.channelHash, channel.c_str());
+    lines.push_back(s);
+    if (h.relayNode) {
+        std::snprintf(s, sizeof s, "Relayed by ..%02x", h.relayNode);
+        lines.push_back(s);
+    }
+    if (h.nextHop) {
+        std::snprintf(s, sizeof s, "Next hop ..%02x", h.nextHop);
+        lines.push_back(s);
+    }
+    return lines;
+}
+
+}  // namespace roro::lora

lib/lora/src/packet_view.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::lora {
+
+// What the LoRa Scanner shows of one packet (M3, Q96).
+struct PacketSummary {
+    const uint8_t* data;
+    size_t len;
+    float rssi, snr;
+    bool crcOk;
+    bool meshtastic;  // received on Meshtastic settings (sync word 0x2B): read its clear header
+};
+
+// One list row, at most about 36 characters: "21:45:07 -97 6.2 5678>all 1/3". Nodes by their default
+// short name (the last 4 hex digits); headerLines() has the full numbers.
+std::string row(const PacketSummary& p, const std::string& time);
+
+// Eight bytes a line, with the printable ones: "0000 ff ff ff ff 78 56 34 12 ....xV4.".
+std::vector<std::string> hexDump(const uint8_t* data, size_t len);
+
+// The Meshtastic header, one field a line; empty when the packet is too short to have one.
+std::vector<std::string> headerLines(const uint8_t* data, size_t len);
+
+}  // namespace roro::lora

lib/lora/src/sweep_view.cpp

@@ -0,0 +1,48 @@
+#include "sweep_view.h"
+
+#include <algorithm>
+
+namespace roro::lora {
+
+namespace {
+constexpr int kPeakAboveFloorDb = 10;
+constexpr size_t kMaxPeaks = 3;
+}  // namespace
+
+SweepStats summarize(const int8_t* dbm, size_t steps, uint32_t fromHz, uint32_t stepHz) {
+    SweepStats s;
+    if (!steps) return s;
+    std::vector<int8_t> sorted(dbm, dbm + steps);
+    std::nth_element(sorted.begin(), sorted.begin() + steps / 2, sorted.end());
+    s.floor = sorted[steps / 2];
+    s.top = *std::max_element(dbm, dbm + steps);
+    for (size_t i = 0; i < steps; ++i) {
+        int v = dbm[i];
+        bool localMax = (i == 0 || v >= dbm[i - 1]) && (i + 1 == steps || v > dbm[i + 1]);
+        if (localMax && v >= s.floor + kPeakAboveFloorDb) s.peaks.push_back({fromHz + static_cast<uint32_t>(i) * stepHz, v});
+    }
+    std::stable_sort(s.peaks.begin(), s.peaks.end(), [](const SweepPeak& a, const SweepPeak& b) { return a.dbm > b.dbm; });
+    if (s.peaks.size() > kMaxPeaks) s.peaks.resize(kMaxPeaks);
+    return s;
+}
+
+uint8_t heatLevel(int dbm, int low, int high) {
+    if (dbm <= low) return 0;
+    if (dbm >= high) return 255;
+    return static_cast<uint8_t>((dbm - low) * 255 / (high - low) + ((dbm - low) * 255 % (high - low) ? 1 : 0));
+}
+
+uint16_t heatColor(uint8_t level) {
+    // Five segments of 51 steps each.
+    auto rgb = [](int r, int g, int b) { return static_cast<uint16_t>((r >> 3) << 11 | (g >> 2) << 5 | (b >> 3)); };
+    int seg = std::min(level / 51, 4), t = (level - seg * 51) * 255 / 51;
+    switch (seg) {
+        case 0: return rgb(0, 0, t);              // black to blue
+        case 1: return rgb(0, t, 255);            // blue to cyan
+        case 2: return rgb(0, 255, 255 - t);      // cyan to green
+        case 3: return rgb(t, 255, 0);            // green to yellow
+        default: return rgb(255, 255 - t, 0);     // yellow to red
+    }
+}
+
+}  // namespace roro::lora

lib/lora/src/sweep_view.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace roro::lora {
+
+// What a Sweep pass says about the band (M3, Q98): one RSSI reading (dBm) per step.
+struct SweepPeak {
+    uint32_t hz;
+    int dbm;
+};
+struct SweepStats {
+    int floor = 0;  // the median: the band's noise floor, whatever a few signals do
+    int top = 0;    // the strongest reading
+    std::vector<SweepPeak> peaks;  // at most 3, strongest first, each a local maximum >= 10 dB above the floor
+};
+
+SweepStats summarize(const int8_t* dbm, size_t steps, uint32_t fromHz, uint32_t stepHz);
+
+// The waterfall's colours: a reading between `low` and `high` dBm as 0..255, then RGB565 along
+// black, blue, cyan, green, yellow, red.
+uint8_t heatLevel(int dbm, int low, int high);
+uint16_t heatColor(uint8_t level);
+
+}  // namespace roro::lora

lib/meshtastic/src/meshtastic_header.cpp

@@ -0,0 +1,28 @@
+#include "meshtastic_header.h"
+
+#include <cstdio>
+
+namespace roro::meshtastic {
+
+static uint32_t le32(const uint8_t* p) { return p[0] | p[1] << 8 | p[2] << 16 | static_cast<uint32_t>(p[3]) << 24; }
+
+bool parseHeader(const uint8_t* data, size_t len, PacketHeader& out) {
+    if (!data || len < kHeaderSize) return false;
+    out.to = le32(data);
+    out.from = le32(data + 4);
+    out.id = le32(data + 8);
+    out.flags = data[12];
+    out.channelHash = data[13];
+    out.nextHop = data[14];
+    out.relayNode = data[15];
+    return true;
+}
+
+std::string nodeId(uint32_t node) {
+    if (node == kBroadcast) return "all";
+    char s[10];
+    std::snprintf(s, sizeof s, "!%08x", static_cast<unsigned>(node));
+    return s;
+}
+
+}  // namespace roro::meshtastic

lib/meshtastic/src/meshtastic_header.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace roro::meshtastic {
+
+constexpr uint32_t kBroadcast = 0xFFFFFFFF;
+
+// The 16 bytes every Meshtastic packet starts with, sent in clear (little-endian). The payload
+// after it is encrypted with the Channel's key.
+struct PacketHeader {
+    uint32_t to = 0, from = 0, id = 0;
+    uint8_t flags = 0;
+    uint8_t channelHash = 0;  // the Channel's name and key folded into a byte (see channelHash())
+    uint8_t nextHop = 0;      // last byte of the Node meant to relay it next; 0 when flooding
+    uint8_t relayNode = 0;    // last byte of the Node that relayed it to us
+
+    uint8_t hopLimit() const { return flags & 0x07; }
+    bool wantAck() const { return flags & 0x08; }
+    bool viaMqtt() const { return flags & 0x10; }
+    uint8_t hopStart() const { return flags >> 5; }
+    bool broadcast() const { return to == kBroadcast; }
+    // How many times it was relayed before we heard it; -1 when the sender didn't say (hop start 0).
+    int hopsAway() const { return hopStart() == 0 ? -1 : hopStart() - hopLimit(); }
+};
+
+constexpr size_t kHeaderSize = 16;
+
+bool parseHeader(const uint8_t* data, size_t len, PacketHeader& out);
+
+// "!12345678", as Meshtastic writes node numbers; "all" for broadcast.
+std::string nodeId(uint32_t node);
+
+}  // namespace roro::meshtastic

lib/meshtastic/src/meshtastic_presets.cpp

@@ -0,0 +1,47 @@
+#include "meshtastic_presets.h"
+
+#include <cmath>
+#include <cstring>
+
+namespace roro::meshtastic {
+
+const uint8_t kDefaultKey[16] = {0xd4, 0xf1, 0xbb, 0x3a, 0x20, 0x29, 0x07, 0x59,
+                                 0xf0, 0xbc, 0xff, 0xab, 0xcf, 0x4e, 0x69, 0x01};
+
+// firmware src/mesh/MeshRadio.h (modemPresetToParams) and RadioInterface.cpp (PRESETS_EU_868).
+const Preset kEu868Presets[] = {
+    {"LongFast", 250, 11, 5},  {"LongSlow", 125, 12, 8},  {"MediumSlow", 250, 10, 5}, {"MediumFast", 250, 9, 5},
+    {"ShortSlow", 250, 8, 5},  {"ShortFast", 250, 7, 5},  {"LongMod", 125, 11, 8},
+};
+const size_t kEu868PresetCount = sizeof kEu868Presets / sizeof kEu868Presets[0];
+
+const Preset* findPreset(const char* name) {
+    for (const Preset& p : kEu868Presets)
+        if (std::strcmp(p.name, name) == 0) return &p;
+    return nullptr;
+}
+
+uint32_t djb2(const char* s) {
+    uint32_t h = 5381;
+    for (; *s; ++s) h = (h << 5) + h + static_cast<unsigned char>(*s);
+    return h;
+}
+
+uint8_t channelHash(const char* name, const uint8_t* key, size_t keyLen) {
+    uint8_t h = 0;
+    for (; *name; ++name) h ^= static_cast<uint8_t>(*name);
+    for (size_t i = 0; i < keyLen; ++i) h ^= key[i];
+    return h;
+}
+
+uint32_t eu868FrequencyHz(const Preset& preset, const char* channelName) {
+    constexpr double kStartMHz = 869.4, kEndMHz = 869.65;
+    double slotMHz = preset.bwKHz / 1000.0;
+    uint32_t slots = static_cast<uint32_t>(std::lround((kEndMHz - kStartMHz) / slotMHz));
+    const char* name = channelName && *channelName ? channelName : preset.name;
+    uint32_t slot = slots ? djb2(name) % slots : 0;
+    double mhz = kStartMHz + slotMHz / 2 + slot * slotMHz;
+    return static_cast<uint32_t>(std::lround(mhz * 1e6));
+}
+
+}  // namespace roro::meshtastic

lib/meshtastic/src/meshtastic_presets.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace roro::meshtastic {
+
+// Radio settings shared by every Meshtastic preset (firmware src/mesh/RadioInterface.h).
+constexpr uint8_t kSyncWord = 0x2B;
+constexpr uint16_t kPreambleLength = 16;
+
+// The default Channel key ("AQ==", expanded): public, so the default Channel is readable by anyone.
+extern const uint8_t kDefaultKey[16];
+
+// A modem preset: bandwidth, spreading factor and coding rate (4/cr). Named as Meshtastic shows them.
+struct Preset {
+    const char* name;
+    float bwKHz;
+    uint8_t sf;
+    uint8_t cr;
+};
+
+// The presets Meshtastic allows in EU_868, its order, LongFast (the default) first.
+extern const Preset kEu868Presets[];
+extern const size_t kEu868PresetCount;
+const Preset* findPreset(const char* name);  // nullptr when EU_868 doesn't allow it
+
+// djb2, as Meshtastic hashes a Channel's name to pick a frequency slot.
+uint32_t djb2(const char* s);
+
+// The byte in every packet header naming its Channel: the name's bytes XORed with the key's.
+uint8_t channelHash(const char* name, const uint8_t* key, size_t keyLen);
+
+// EU_868 is 869.4 to 869.65 MHz: the slot comes from the Channel's name (the preset's name for
+// an unnamed Channel, which is the default).
+uint32_t eu868FrequencyHz(const Preset& preset, const char* channelName = nullptr);
+
+}  // namespace roro::meshtastic

lib/net/src/ipv4.cpp

@@ -0,0 +1,97 @@
+#include "ipv4.h"
+
+#include <cstdio>
+
+namespace roro::net {
+
+bool parseIpv4(const std::string& text, uint32_t& out) {
+    uint32_t value = 0;
+    int parts = 0, digits = 0, part = 0;
+    for (char c : text) {
+        if (c >= '0' && c <= '9') {
+            if (++digits > 3) return false;
+            part = part * 10 + (c - '0');
+            if (part > 255) return false;
+        } else if (c == '.') {
+            if (digits == 0 || ++parts > 3) return false;
+            value = value << 8 | part;
+            part = digits = 0;
+        } else {
+            return false;
+        }
+    }
+    if (digits == 0 || parts != 3) return false;
+    out = value << 8 | part;
+    return true;
+}
+
+std::string formatIpv4(uint32_t a) {
+    char s[16];
+    std::snprintf(s, sizeof s, "%u.%u.%u.%u", static_cast<unsigned>(a >> 24), static_cast<unsigned>(a >> 16 & 255),
+                  static_cast<unsigned>(a >> 8 & 255), static_cast<unsigned>(a & 255));
+    return s;
+}
+
+uint32_t maskOf(int prefix) { return prefix <= 0 ? 0 : prefix >= 32 ? 0xFFFFFFFFu : ~0u << (32 - prefix); }
+
+std::string checkFixed(const FixedIp& f) {
+    if (f.prefix < 1 || f.prefix > 30) return "The prefix must be 1 to 30";
+    if (f.address == 0) return "0.0.0.0 isn't an address a device can have";
+    uint32_t mask = maskOf(f.prefix), network = f.address & mask, broadcast = network | ~mask;
+    if (f.address == network) return formatIpv4(f.address) + " is the network's own address";
+    if (f.address == broadcast) return formatIpv4(f.address) + " is the broadcast address";
+    if (f.gateway == 0) return "";
+    if (f.gateway == f.address) return "The gateway can't be this device's address";
+    if ((f.gateway & mask) != network)
+        return "The gateway " + formatIpv4(f.gateway) + " isn't in " + formatIpv4(network) + "/" + std::to_string(f.prefix);
+    if (f.gateway == broadcast) return "The gateway " + formatIpv4(f.gateway) + " is the broadcast address";
+    if (f.gateway == network) return "The gateway " + formatIpv4(f.gateway) + " is the network's own address";
+    return "";
+}
+
+std::string parseFixed(const std::string& text, FixedIp& out) {
+    size_t slash = text.find('/');
+    if (slash == std::string::npos) return "Write it as address/prefix, then the gateway if there is one";
+    size_t space = text.find(' ', slash);
+    std::string address = text.substr(0, slash);
+    std::string prefix = text.substr(slash + 1, space == std::string::npos ? std::string::npos : space - slash - 1);
+    std::string gateway = space == std::string::npos ? "" : text.substr(space + 1);
+    FixedIp f;
+    if (!parseIpv4(address, f.address)) return address + " isn't an IPv4 address";
+    int p = 0;
+    if (prefix.empty() || prefix.size() > 2) return "The prefix must be 1 to 30";
+    for (char c : prefix) {
+        if (c < '0' || c > '9') return "The prefix must be 1 to 30";
+        p = p * 10 + (c - '0');
+    }
+    f.prefix = static_cast<uint8_t>(p);
+    if (!gateway.empty() && !parseIpv4(gateway, f.gateway)) return gateway + " isn't an IPv4 address";
+    std::string why = checkFixed(f);
+    if (why.empty()) out = f;
+    return why;
+}
+
+std::string formatFixed(const FixedIp& f) {
+    std::string s = formatIpv4(f.address) + "/" + std::to_string(f.prefix);
+    if (f.gateway) s += " " + formatIpv4(f.gateway);
+    return s;
+}
+
+bool validHost(const std::string& text) {
+    if (text.empty() || text.size() > 63) return false;
+    uint32_t ignored;
+    if (parseIpv4(text, ignored)) return true;
+    bool allNumeric = true;  // digits and dots only, but not an address: "1.2.3", "999.1.1.1"
+    char previous = '.';
+    for (char c : text) {
+        bool letter = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'), digit = c >= '0' && c <= '9';
+        if (!letter && !digit && c != '-' && c != '.') return false;
+        if (c == '.' && (previous == '.' || previous == '-')) return false;  // empty label, or one ending in '-'
+        if (c == '-' && previous == '.') return false;                       // a label starting with '-'
+        if (letter || c == '-') allNumeric = false;
+        previous = c;
+    }
+    return previous != '.' && previous != '-' && !allNumeric;
+}
+
+}  // namespace roro::net

lib/net/src/ipv4.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace roro::net {
+
+// IPv4 addresses as 32-bit numbers, most significant byte first: 10.39.39.12 is 0x0A27270C.
+bool parseIpv4(const std::string& text, uint32_t& out);  // strict: four decimal numbers, 0 to 255
+std::string formatIpv4(uint32_t address);
+uint32_t maskOf(int prefix);  // 24 -> 255.255.255.0
+
+// A Saved Network's Fixed setting (S1, Q105 to Q107). gateway 0: none.
+struct FixedIp {
+    uint32_t address = 0;
+    uint8_t prefix = 24;
+    uint32_t gateway = 0;
+};
+
+// "" when a device can use it, otherwise why not, for a human (Q111).
+std::string checkFixed(const FixedIp& f);
+
+// "address/prefix [gateway]", as typed on the console and kept in flash. parseFixed() also checks.
+std::string parseFixed(const std::string& text, FixedIp& out);
+std::string formatFixed(const FixedIp& f);
+
+// An IPv4 address or a host name, as an NTP server may be (Q110).
+bool validHost(const std::string& text);
+
+}  // namespace roro::net

lib/net/src/traffic.cpp

@@ -0,0 +1,46 @@
+#include "traffic.h"
+
+#include <atomic>
+#include <cstdio>
+
+namespace roro::net {
+
+namespace {
+constexpr size_t kUsers = static_cast<size_t>(User::Count);
+std::atomic<uint32_t> in_[kUsers], out_[kUsers];
+}  // namespace
+
+const char* userName(User user) {
+    switch (user) {
+        case User::Irc: return "IRC";
+        case User::Gemini: return "Gemini";
+        case User::DebugConsole: return "Debug Console";
+        case User::Updates: return "Updates";
+        default: return "?";
+    }
+}
+
+void received(User user, size_t bytes) { in_[static_cast<size_t>(user)] += static_cast<uint32_t>(bytes); }
+void sent(User user, size_t bytes) { out_[static_cast<size_t>(user)] += static_cast<uint32_t>(bytes); }
+Traffic traffic(User user) { return {in_[static_cast<size_t>(user)], out_[static_cast<size_t>(user)]}; }
+
+void resetTraffic() {
+    for (size_t i = 0; i < kUsers; i++) in_[i] = out_[i] = 0;
+}
+
+uint32_t bytesPerSecond(uint32_t before, uint32_t now, uint32_t elapsedMs) {
+    if (!elapsedMs) return 0;
+    return static_cast<uint32_t>(static_cast<uint64_t>(now - before) * 1000 / elapsedMs);  // wraps with the counter
+}
+
+std::string formatTraffic(uint32_t bytes) {
+    char s[16];
+    if (bytes < 1000) std::snprintf(s, sizeof s, "%u B", static_cast<unsigned>(bytes));
+    else if (bytes < 10 * 1024) std::snprintf(s, sizeof s, "%.1f KB", bytes / 1024.0);
+    else if (bytes < 1000 * 1024) std::snprintf(s, sizeof s, "%u KB", static_cast<unsigned>(bytes / 1024));
+    else if (bytes < 10u * 1024 * 1024) std::snprintf(s, sizeof s, "%.1f MB", bytes / 1048576.0);
+    else std::snprintf(s, sizeof s, "%u MB", static_cast<unsigned>(bytes / 1048576));
+    return s;
+}
+
+}  // namespace roro::net

lib/net/src/traffic.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace roro::net {
+
+// Bytes each network service has read and written since boot (S1, Q121), as the service sees
+// them: for TLS connections that's the plain text, without the handshake or record overhead.
+// Counted from the services' own tasks, read from the main loop.
+enum class User : uint8_t { Irc, Gemini, DebugConsole, Updates, Count };
+const char* userName(User user);
+
+struct Traffic {
+    uint32_t in = 0, out = 0;
+};
+void received(User user, size_t bytes);
+void sent(User user, size_t bytes);
+Traffic traffic(User user);
+void resetTraffic();  // for tests
+
+uint32_t bytesPerSecond(uint32_t before, uint32_t now, uint32_t elapsedMs);
+std::string formatTraffic(uint32_t bytes);  // "999 B", "1.5 KB", "12 KB", "1.7 MB"
+
+}  // namespace roro::net

lib/ota/src/file_receiver.cpp

@@ -0,0 +1,119 @@
+#include "file_receiver.h"
+
+#include <algorithm>
+#include <cstdlib>
+#include <cstring>
+
+namespace roro {
+
+namespace {
+
+int hexDigit(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    return -1;
+}
+
+// Splits on spaces (no iostreams: they cost about 200 KB of flash on the device).
+std::vector<std::string> words(const std::string& s) {
+    std::vector<std::string> out;
+    size_t i = 0;
+    while (i < s.size()) {
+        if (s[i] == ' ') {
+            i++;
+            continue;
+        }
+        size_t end = s.find(' ', i);
+        if (end == std::string::npos) end = s.size();
+        out.push_back(s.substr(i, end - i));
+        i = end;
+    }
+    return out;
+}
+
+}  // namespace
+
+std::string FileReceiver::begin(const std::string& args, uint32_t nowMs) {
+    reset();
+    std::vector<std::string> w = words(args);
+    if (w.size() != 3) return "usage: sd put <path> <size> <sha256>";
+    const std::string &path = w[0], &size = w[1], &sha = w[2];
+    if (path.empty() || path[0] != '/' || path.size() > 128 || path.find("..") != std::string::npos)
+        return "the path must be absolute, without ..";
+    if (size.empty() || size.size() > 9 || size.find_first_not_of("0123456789") != std::string::npos)
+        return "bad size";
+    uint32_t bytes = static_cast<uint32_t>(std::strtoul(size.c_str(), nullptr, 10));
+    if (bytes == 0 || bytes > kMaxBytes) return "bad size";
+    if (sha.size() != 64) return "bad sha256";
+    for (size_t i = 0; i < 32; i++) {
+        int hi = hexDigit(sha[2 * i]), lo = hexDigit(sha[2 * i + 1]);
+        if (hi < 0 || lo < 0) return "bad sha256";
+        expected_[i] = static_cast<uint8_t>(hi << 4 | lo);
+    }
+    path_ = path;
+    size_ = bytes;
+    lastActivityMs_ = nowMs;
+    chunk_.reserve(kChunk);
+    state_ = State::Receiving;
+    return "";
+}
+
+size_t FileReceiver::wanted() const {
+    if (state_ != State::Receiving) return 0;
+    return std::min<size_t>(kChunk, size_ - received_) - chunk_.size();
+}
+
+size_t FileReceiver::feed(const uint8_t* data, size_t len, uint32_t nowMs) {
+    if (state_ != State::Receiving || len == 0) return 0;
+    size_t take = std::min(len, wanted());
+    chunk_.insert(chunk_.end(), data, data + take);
+    sha_.update(data, take);
+    lastActivityMs_ = nowMs;
+    if (wanted() > 0) return take;
+
+    if (received_ + chunk_.size() == size_) {
+        // The last chunk: refuse it before writing if the file arrived damaged.
+        uint8_t got[32];
+        sha_.finish(got);
+        if (std::memcmp(got, expected_, sizeof got) != 0) {
+            fail("checksum mismatch");
+            return take;
+        }
+    }
+    state_ = State::Writing;
+    return take;
+}
+
+void FileReceiver::chunkWritten(bool ok, uint32_t nowMs) {
+    if (state_ != State::Writing) return;
+    if (!ok) return fail("write failed");
+    received_ += static_cast<uint32_t>(chunk_.size());
+    chunk_.clear();
+    lastActivityMs_ = nowMs;
+    state_ = received_ == size_ ? State::Finishing : State::Receiving;
+}
+
+void FileReceiver::cardChecked(const uint8_t digest[32]) {
+    if (state_ != State::Finishing) return;
+    if (std::memcmp(digest, expected_, sizeof expected_) != 0) fail("the copy on the card differs");
+}
+
+void FileReceiver::finished(bool ok) {
+    if (state_ != State::Finishing) return;
+    if (!ok) return fail("rename failed");
+    state_ = State::Done;
+}
+
+void FileReceiver::tick(uint32_t nowMs) {
+    if (state_ != State::Receiving && state_ != State::Writing && state_ != State::Finishing) return;
+    if (nowMs - lastActivityMs_ >= kTimeoutMs) fail(state_ == State::Receiving ? "timed out" : "card not writable");
+}
+
+void FileReceiver::fail(const char* why) {
+    error_ = why;
+    chunk_.clear();
+    state_ = State::Failed;
+}
+
+}  // namespace roro

lib/ota/src/file_receiver.h

@@ -0,0 +1,69 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "sha256.h"
+
+namespace roro {
+
+// One file sent over the USB serial console (scripts/sd_put.py), to put an Update File on the SD
+// card without taking the card out. The sender writes `sd put <path> <size> <sha256>`, then the raw
+// bytes, one chunk at a time, and waits for each chunk to be written before sending the next: the
+// serial driver drops bytes once its receive buffer is full. The file lands as `<path>.part` and is
+// renamed to `<path>` only once every byte has arrived and the checksum matches.
+class FileReceiver {
+   public:
+    static constexpr size_t kChunk = 1024;           // must stay below the serial receive buffer
+    static constexpr uint32_t kTimeoutMs = 5000;     // silence, or a card job that never completes
+    static constexpr uint32_t kMaxBytes = 8u << 20;  // larger than any app partition
+
+    enum class State {
+        Idle,
+        Receiving,  // waiting for bytes of the current chunk
+        Writing,    // chunk() is complete: write it to partPath(), then call chunkWritten()
+        Finishing,  // everything written and checked: rename partPath() to path(), then finished()
+        Done,
+        Failed,     // error() says why; partPath() should be removed
+    };
+
+    // Parses "<path> <size> <sha256 hex>". Returns "" when the transfer starts, or what's wrong.
+    std::string begin(const std::string& args, uint32_t nowMs);
+    // Takes bytes for the current chunk; returns how many were used (none while a chunk waits).
+    size_t feed(const uint8_t* data, size_t len, uint32_t nowMs);
+    void chunkWritten(bool ok, uint32_t nowMs);
+    // While Finishing: the SHA-256 of the file as read back from the card. The checksum on the
+    // received bytes doesn't prove the card kept them (a failed write can lose buffered data).
+    void cardChecked(const uint8_t digest[32]);
+    void finished(bool ok);
+    void tick(uint32_t nowMs);
+    void reset() { *this = FileReceiver(); }
+
+    State state() const { return state_; }
+    bool active() const { return state_ != State::Idle; }
+    // Bytes still missing from the current chunk: read no more than this from the serial port.
+    size_t wanted() const;
+    const std::vector<uint8_t>& chunk() const { return chunk_; }
+    const std::string& path() const { return path_; }
+    std::string partPath() const { return path_ + ".part"; }
+    uint32_t size() const { return size_; }
+    uint32_t received() const { return received_; }
+    const std::string& error() const { return error_; }
+
+   private:
+    void fail(const char* why);
+
+    State state_ = State::Idle;
+    std::string path_;
+    uint32_t size_ = 0;
+    uint32_t received_ = 0;  // bytes in chunks already written
+    uint8_t expected_[32] = {};
+    Sha256 sha_;
+    std::vector<uint8_t> chunk_;
+    uint32_t lastActivityMs_ = 0;
+    std::string error_;
+};
+
+}  // namespace roro

lib/ota/src/probation.h

@@ -0,0 +1,28 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+// Decides when new firmware on Probation (see CONTEXT.md) has proven healthy, or has failed in a
+// way that would leave no means to push a fix (Wi-Fi configured but never connecting).
+class Probation {
+   public:
+    enum class Verdict { Wait, Confirm, RollBack };
+    static constexpr uint32_t kHealthyAfterMs = 30000;
+    static constexpr uint32_t kWifiDeadlineMs = 180000;
+
+    // Checked first thing at boot, before anything that could crash. `attemptsBefore` counts earlier
+    // boots of this image on Probation; a second start means the first one died before confirming.
+    // (A second line behind the bootloader's own rollback, which aborts an image still pending.)
+    static bool rollBackAtBoot(bool onProbation, int attemptsBefore) { return onProbation && attemptsBefore >= 1; }
+
+    static Verdict judge(uint32_t uptimeMs, bool firstFrameDrawn, bool wifiConfigured, bool wifiConnected) {
+        if (wifiConfigured && !wifiConnected && uptimeMs >= kWifiDeadlineMs) return Verdict::RollBack;
+        if (uptimeMs < kHealthyAfterMs || !firstFrameDrawn) return Verdict::Wait;
+        if (wifiConfigured && !wifiConnected) return Verdict::Wait;
+        return Verdict::Confirm;
+    }
+};
+
+}  // namespace roro

lib/ota/src/safe_mode.h

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+// Safe Mode (CONTEXT.md): after kCrashLimit starts in a row that ended in a crash, the firmware
+// starts only what it takes to be fixed over the air (Wi-Fi, Firmware Updates, the Debug Console).
+// Rollback covers new firmware; this covers firmware that was confirmed and crashes anyway.
+struct SafeMode {
+    static constexpr int kCrashLimit = 3;
+    static constexpr uint32_t kStableAfterMs = 60000;  // then the count starts over
+
+    // Called first thing at boot with the count so far; returns the new count.
+    static int countAtBoot(bool lastStartWasCrash, int crashesBefore) {
+        return lastStartWasCrash ? crashesBefore + 1 : 0;
+    }
+    static bool active(int crashes) { return crashes >= kCrashLimit; }
+};
+
+}  // namespace roro

lib/ota/src/sha256.cpp

@@ -0,0 +1,85 @@
+#include "sha256.h"
+
+#include <cstring>
+
+namespace roro {
+
+namespace {
+const uint32_t K[64] = {
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2};
+
+inline uint32_t rotr(uint32_t x, int n) { return (x >> n) | (x << (32 - n)); }
+}  // namespace
+
+Sha256::Sha256() {
+    const uint32_t init[8] = {0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+                              0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};
+    std::memcpy(h_, init, sizeof(h_));
+}
+
+void Sha256::block(const uint8_t* p) {
+    uint32_t w[64];
+    for (int i = 0; i < 16; i++)
+        w[i] = (uint32_t(p[4 * i]) << 24) | (uint32_t(p[4 * i + 1]) << 16) | (uint32_t(p[4 * i + 2]) << 8) | p[4 * i + 3];
+    for (int i = 16; i < 64; i++) {
+        uint32_t s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >> 3);
+        uint32_t s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >> 10);
+        w[i] = w[i - 16] + s0 + w[i - 7] + s1;
+    }
+    uint32_t a = h_[0], b = h_[1], c = h_[2], d = h_[3], e = h_[4], f = h_[5], g = h_[6], h = h_[7];
+    for (int i = 0; i < 64; i++) {
+        uint32_t t1 = h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i];
+        uint32_t t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c));
+        h = g;
+        g = f;
+        f = e;
+        e = d + t1;
+        d = c;
+        c = b;
+        b = a;
+        a = t1 + t2;
+    }
+    h_[0] += a; h_[1] += b; h_[2] += c; h_[3] += d;
+    h_[4] += e; h_[5] += f; h_[6] += g; h_[7] += h;
+}
+
+void Sha256::update(const uint8_t* data, size_t len) {
+    bits_ += static_cast<uint64_t>(len) * 8;
+    while (len > 0) {
+        size_t take = 64 - used_ < len ? 64 - used_ : len;
+        std::memcpy(buf_ + used_, data, take);
+        used_ += take;
+        data += take;
+        len -= take;
+        if (used_ == 64) {
+            block(buf_);
+            used_ = 0;
+        }
+    }
+}
+
+void Sha256::finish(uint8_t out[32]) {
+    uint64_t bits = bits_;
+    uint8_t pad = 0x80;
+    update(&pad, 1);
+    uint8_t zero = 0;
+    while (used_ != 56) update(&zero, 1);
+    uint8_t len[8];
+    for (int i = 0; i < 8; i++) len[i] = static_cast<uint8_t>(bits >> (56 - 8 * i));
+    update(len, 8);
+    for (int i = 0; i < 8; i++) {
+        out[4 * i] = h_[i] >> 24;
+        out[4 * i + 1] = h_[i] >> 16;
+        out[4 * i + 2] = h_[i] >> 8;
+        out[4 * i + 3] = h_[i];
+    }
+}
+
+}  // namespace roro

lib/ota/src/sha256.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace roro {
+
+// Plain SHA-256 (FIPS 180-4), streaming. Small and dependency-free, so the same code runs in the
+// PC tests and on the device.
+class Sha256 {
+   public:
+    Sha256();
+    void update(const uint8_t* data, size_t len);
+    void finish(uint8_t out[32]);
+
+    static void hash(const uint8_t* data, size_t len, uint8_t out[32]) {
+        Sha256 s;
+        s.update(data, len);
+        s.finish(out);
+    }
+
+   private:
+    void block(const uint8_t* p);
+    uint32_t h_[8];
+    uint8_t buf_[64];
+    size_t used_ = 0;
+    uint64_t bits_ = 0;
+};
+
+}  // namespace roro

lib/ota/src/update_parser.cpp

@@ -0,0 +1,87 @@
+#include "update_parser.h"
+
+#include <cstring>
+
+#include "version_compare.h"
+
+namespace roro {
+
+namespace {
+uint16_t u16(const uint8_t* p) { return p[0] | (p[1] << 8); }
+uint32_t u32(const uint8_t* p) { return p[0] | (p[1] << 8) | (p[2] << 16) | (uint32_t(p[3]) << 24); }
+}  // namespace
+
+void UpdateParser::fail(const std::string& why) {
+    if (state_ == State::Image) sink_.abort();
+    state_ = State::Failed;
+    error_ = why;
+}
+
+void UpdateParser::parseHeader() {
+    const uint8_t* h = header_;
+    if (std::memcmp(h, update::kMagic, 8) != 0) return fail("not an update file");
+    if (u16(h + 8) != update::kFormat || u16(h + 10) != update::kHeaderSize) return fail("unsupported update format");
+    imageSize_ = u32(h + 12);
+    if (imageSize_ == 0 || imageSize_ > maxImage_) return fail("image doesn't fit the update slot");
+    std::memcpy(expectedHash_, h + 16, 32);
+    version_.assign(reinterpret_cast<const char*>(h + 48), strnlen(reinterpret_cast<const char*>(h + 48), 32));
+
+    size_t sigLen = u16(h + 80);
+    if (sigLen == 0 || sigLen > update::kMaxSignature) return fail("missing signature");
+    uint8_t digest[32];
+    Sha256::hash(h, update::kSignedBytes, digest);
+    if (!verifier_.verify(digest, h + 82, sigLen)) return fail("bad signature (wrong key)");
+
+    downgrade_ = versionOlder(version_, installed_);
+    if (!sink_.begin(imageSize_)) return fail("could not prepare the update slot");
+    state_ = State::Image;
+}
+
+void UpdateParser::feed(const uint8_t* data, size_t len) {
+    while (len > 0 && (state_ == State::Header || state_ == State::Image)) {
+        if (state_ == State::Header) {
+            size_t take = std::min(len, update::kHeaderSize - headerUsed_);
+            std::memcpy(header_ + headerUsed_, data, take);
+            headerUsed_ += take;
+            data += take;
+            len -= take;
+            if (headerUsed_ == update::kHeaderSize) parseHeader();
+        } else {
+            size_t take = std::min(len, imageSize_ - received_);
+            if (take == 0) return fail("data after the end of the image");
+            hash_.update(data, take);
+            if (!sink_.write(data, take)) return fail("writing the update failed");
+            received_ += take;
+            data += take;
+            len -= take;
+        }
+    }
+    if (len > 0 && state_ == State::Image) fail("data after the end of the image");
+}
+
+bool UpdateParser::end() {
+    if (state_ == State::Done) return true;
+    if (state_ != State::Image) {
+        if (state_ == State::Header) fail("update file too short");
+        return false;
+    }
+    if (received_ != imageSize_) {
+        fail("update file too short");
+        return false;
+    }
+    uint8_t got[32];
+    hash_.finish(got);
+    if (std::memcmp(got, expectedHash_, 32) != 0) {
+        fail("image corrupted (hash mismatch)");
+        return false;
+    }
+    if (!sink_.finish()) {
+        state_ = State::Failed;
+        error_ = "could not switch to the new image";
+        return false;
+    }
+    state_ = State::Done;
+    return true;
+}
+
+}  // namespace roro

lib/ota/src/update_parser.h

@@ -0,0 +1,82 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+#include "sha256.h"
+
+namespace roro {
+
+// The Update File (see CONTEXT.md): a 160-byte header, then the firmware image. All integers are
+// little-endian.
+//   0  magic "RORO-OTA"     8  u16 format (1)    10 u16 header size (160)   12 u32 image size
+//  16  image SHA-256[32]   48  version, NUL-padded [32]
+//  80  u16 signature length   82  signature (DER, up to 72 bytes)   154 reserved
+// The signature covers SHA-256 of bytes 0..79, which include the image's hash, so a bad signature
+// is caught before anything is written, and a bad image when its hash is checked at the end.
+namespace update {
+constexpr char kMagic[] = "RORO-OTA";
+constexpr uint16_t kFormat = 1;
+constexpr size_t kHeaderSize = 160;
+constexpr size_t kSignedBytes = 80;
+constexpr size_t kMaxSignature = 72;
+}  // namespace update
+
+class SignatureVerifier {
+   public:
+    virtual ~SignatureVerifier() = default;
+    virtual bool verify(const uint8_t digest[32], const uint8_t* signature, size_t len) = 0;
+};
+
+// Where the image goes (the inactive app slot on the device).
+class UpdateSink {
+   public:
+    virtual ~UpdateSink() = default;
+    virtual bool begin(size_t imageSize) = 0;
+    virtual bool write(const uint8_t* data, size_t len) = 0;
+    virtual bool finish() = 0;  // make it the image to boot next
+    virtual void abort() = 0;
+};
+
+// Streams an Update File into a sink: checks the header and signature first, then hashes the image
+// as it passes through, and only finishes the sink if everything matches.
+class UpdateParser {
+   public:
+    enum class State { Header, Image, Done, Failed };
+
+    UpdateParser(SignatureVerifier& verifier, UpdateSink& sink, size_t maxImageSize, std::string installedVersion)
+        : verifier_(verifier), sink_(sink), maxImage_(maxImageSize), installed_(std::move(installedVersion)) {}
+
+    void feed(const uint8_t* data, size_t len);
+    bool end();  // no more data: true if the update was installed
+    // The whole image the header announced has arrived (the sender need not close the connection).
+    bool complete() const { return state_ == State::Image && received_ == imageSize_; }
+
+    State state() const { return state_; }
+    const std::string& error() const { return error_; }
+    const std::string& version() const { return version_; }
+    bool isDowngrade() const { return downgrade_; }
+    int percent() const { return imageSize_ ? static_cast<int>(received_ * 100 / imageSize_) : 0; }
+
+   private:
+    void parseHeader();
+    void fail(const std::string& why);
+
+    SignatureVerifier& verifier_;
+    UpdateSink& sink_;
+    size_t maxImage_;
+    std::string installed_;
+
+    State state_ = State::Header;
+    uint8_t header_[update::kHeaderSize];
+    size_t headerUsed_ = 0;
+    uint8_t expectedHash_[32];
+    size_t imageSize_ = 0;
+    size_t received_ = 0;
+    Sha256 hash_;
+    std::string version_, error_;
+    bool downgrade_ = false;
+};
+
+}  // namespace roro

lib/ota/src/version_compare.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <cstdlib>
+#include <string>
+
+namespace roro {
+
+// True if `a` is an older release than `b`, comparing "vMAJOR.MINOR.PATCH" and ignoring any
+// git-describe suffix ("-3-gabc1234-dirty"). Anything that doesn't parse is never called older.
+inline bool parseVersion(const std::string& s, int out[3]) {
+    size_t pos = s.size() > 0 && s[0] == 'v' ? 1 : 0;
+    for (int i = 0; i < 3; i++) {
+        if (pos >= s.size() || s[pos] < '0' || s[pos] > '9') return false;
+        char* end;
+        out[i] = static_cast<int>(std::strtol(s.c_str() + pos, &end, 10));
+        pos = end - s.c_str();
+        if (i < 2) {
+            if (pos >= s.size() || s[pos] != '.') return false;
+            pos++;
+        }
+    }
+    return true;
+}
+
+inline bool versionOlder(const std::string& a, const std::string& b) {
+    int x[3], y[3];
+    if (!parseVersion(a, x) || !parseVersion(b, y)) return false;
+    for (int i = 0; i < 3; i++)
+        if (x[i] != y[i]) return x[i] < y[i];
+    return false;
+}
+
+}  // namespace roro

lib/services/src/battery_estimator.cpp

@@ -0,0 +1,49 @@
+#include "battery_estimator.h"
+
+#include <algorithm>
+
+namespace roro {
+
+namespace {
+struct Point {
+    int millivolts;
+    int percent;
+};
+const Point kCurve[] = {
+    {3270, 0},  {3610, 5},  {3690, 10}, {3710, 15}, {3730, 20}, {3750, 25}, {3770, 30},
+    {3790, 35}, {3800, 40}, {3820, 45}, {3840, 50}, {3850, 55}, {3870, 60}, {3910, 65},
+    {3950, 70}, {3980, 75}, {4020, 80}, {4080, 85}, {4110, 90}, {4150, 95}, {4200, 100},
+};
+const size_t kPoints = sizeof(kCurve) / sizeof(kCurve[0]);
+}  // namespace
+
+int BatteryEstimator::percentFromMillivolts(int mv) {
+    if (mv <= kCurve[0].millivolts) return 0;
+    if (mv >= kCurve[kPoints - 1].millivolts) return 100;
+    for (size_t i = 1; i < kPoints; i++) {
+        if (mv <= kCurve[i].millivolts) {
+            const auto& lo = kCurve[i - 1];
+            const auto& hi = kCurve[i];
+            return lo.percent + (mv - lo.millivolts) * (hi.percent - lo.percent) /
+                                    (hi.millivolts - lo.millivolts);
+        }
+    }
+    return 100;
+}
+
+void BatteryEstimator::addSample(int mv) {
+    samples_[next_] = mv;
+    next_ = (next_ + 1) % kWindow;
+    if (count_ < kWindow) count_++;
+}
+
+int BatteryEstimator::millivolts() const {
+    if (count_ == 0) return 0;
+    // Median: ignores short sags (radio transmit bursts) that would drag an average down.
+    std::array<int, kWindow> sorted = samples_;
+    auto middle = sorted.begin() + count_ / 2;
+    std::nth_element(sorted.begin(), middle, sorted.begin() + count_);
+    return *middle;
+}
+
+}  // namespace roro

lib/services/src/battery_estimator.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+
+namespace roro {
+
+// Smooths battery voltage samples and turns them into a charge percentage.
+class BatteryEstimator {
+   public:
+    // Typical single-cell LiPo discharge curve under light load.
+    static int percentFromMillivolts(int millivolts);
+
+    void addSample(int millivolts);
+    bool hasReading() const { return count_ > 0; }
+    int millivolts() const;  // median of the recent samples
+    int percent() const { return percentFromMillivolts(millivolts()); }
+
+   private:
+    static constexpr size_t kWindow = 8;
+    std::array<int, kWindow> samples_{};
+    size_t next_ = 0;
+    size_t count_ = 0;
+};
+
+}  // namespace roro

lib/services/src/choices.h

@@ -0,0 +1,24 @@
+#pragma once
+
+namespace roro {
+
+struct Choice {
+    const char* label;
+    const char* value;
+};
+
+// Timezones offered in Settings and the setup wizard (POSIX TZ strings).
+inline const Choice kTimezones[] = {
+    {"Brussels", "CET-1CEST,M3.5.0,M10.5.0/3"},  // also Paris, Amsterdam, Berlin...
+    {"London", "GMT0BST,M3.5.0/1,M10.5.0"},
+    {"Lisbon", "WET0WEST,M3.5.0/1,M10.5.0"},
+    {"Helsinki", "EET-2EEST,M3.5.0/3,M10.5.0/4"},
+    {"UTC", "UTC0"},
+};
+
+// Regions the radio may be used in (see Region in CONTEXT.md).
+inline const Choice kRegions[] = {
+    {"EU868 (Europe, 869.5 MHz)", "EU868"},
+};
+
+}  // namespace roro

lib/services/src/clock_model.cpp

@@ -0,0 +1,58 @@
+#include "clock_model.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <ctime>
+
+namespace roro {
+
+bool ClockModel::set(int64_t utcSeconds, TimeSource source, uint32_t nowMs) {
+    if (source < source_) return false;
+    source_ = source;
+    utcAtSet_ = utcSeconds;
+    msAtSet_ = nowMs;
+    return true;
+}
+
+int64_t ClockModel::utcNow(uint32_t nowMs) const {
+    // Unsigned subtraction handles the millis() wraparound. Uptime beyond 49 days between two
+    // sets would lose 49 days; sources refresh far more often than that.
+    return utcAtSet_ + static_cast<int64_t>(static_cast<uint32_t>(nowMs - msAtSet_) / 1000);
+}
+
+void ClockModel::applyTimezone(const char* posixTz) {
+    setenv("TZ", posixTz, 1);
+    tzset();
+}
+
+std::string ClockModel::formatLocalTime(int64_t utcSeconds) {
+    time_t t = static_cast<time_t>(utcSeconds);
+    struct tm local;
+    localtime_r(&t, &local);
+    char buf[8];
+    std::snprintf(buf, sizeof(buf), "%02d:%02d", local.tm_hour, local.tm_min);
+    return buf;
+}
+
+std::string ClockModel::formatLocalDate(int64_t utcSeconds) {
+    time_t t = static_cast<time_t>(utcSeconds);
+    struct tm local;
+    localtime_r(&t, &local);
+    char buf[12];
+    std::snprintf(buf, sizeof(buf), "%04d-%02d-%02d", local.tm_year + 1900, local.tm_mon + 1, local.tm_mday);
+    return buf;
+}
+
+std::string ClockModel::formatAge(int64_t seconds) {
+    char buf[24];
+    if (seconds < 60) return "now";
+    if (seconds < 3600)
+        std::snprintf(buf, sizeof(buf), "%d min ago", static_cast<int>(seconds / 60));
+    else if (seconds < 86400)
+        std::snprintf(buf, sizeof(buf), "%d h ago", static_cast<int>(seconds / 3600));
+    else
+        std::snprintf(buf, sizeof(buf), "%d d ago", static_cast<int>(seconds / 86400));
+    return buf;
+}
+
+}  // namespace roro

lib/services/src/clock_model.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace roro {
+
+// Ordered by trust: a source can only replace the time set by an equal or less trusted one.
+enum class TimeSource : uint8_t { None, Mesh, Ntp, Gnss };
+
+// Wall-clock time on a device with no battery-backed clock: unset until a TimeSource provides
+// it, then advanced from uptime. Stored in UTC; local display uses the POSIX TZ applied globally.
+class ClockModel {
+   public:
+    // Returns false if a more trusted source already set the time.
+    bool set(int64_t utcSeconds, TimeSource source, uint32_t nowMs);
+
+    bool isSet() const { return source_ != TimeSource::None; }
+    TimeSource source() const { return source_; }
+    int64_t utcNow(uint32_t nowMs) const;
+
+    static void applyTimezone(const char* posixTz);
+    static std::string formatLocalTime(int64_t utcSeconds);  // "HH:MM"
+    static std::string formatLocalDate(int64_t utcSeconds);  // "YYYY-MM-DD"
+    static std::string formatAge(int64_t seconds);           // "now", "5 min ago", "3 h ago", "2 d ago"
+
+   private:
+    TimeSource source_ = TimeSource::None;
+    int64_t utcAtSet_ = 0;
+    uint32_t msAtSet_ = 0;
+};
+
+}  // namespace roro

lib/services/src/key_value_store.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace roro {
+
+// Persistent key/value storage (NVS on the device, a map in tests). Keys are at most 15 chars.
+class KeyValueStore {
+   public:
+    virtual ~KeyValueStore() = default;
+    virtual bool getInt(const char* key, int32_t& out) = 0;
+    virtual bool getString(const char* key, std::string& out) = 0;
+    virtual void putInt(const char* key, int32_t value) = 0;
+    virtual void putString(const char* key, const std::string& value) = 0;
+};
+
+}  // namespace roro

lib/services/src/power_policy.cpp

@@ -0,0 +1,42 @@
+#include "power_policy.h"
+
+namespace roro {
+
+bool PowerPolicy::activity(uint32_t nowMs) {
+    bool swallow = state_ == ScreenState::Off;
+    lastActivityMs_ = nowMs;
+    state_ = ScreenState::On;
+    return swallow;
+}
+
+ScreenState PowerPolicy::update(uint32_t nowMs) {
+    uint32_t idle = nowMs - lastActivityMs_;
+    state_ = idle >= offMs_ ? ScreenState::Off : idle >= dimMs_ ? ScreenState::Dimmed : ScreenState::On;
+    if (notifying_) {
+        if (static_cast<int32_t>(nowMs - notifyUntilMs_) >= 0)
+            notifying_ = false;
+        else if (state_ == ScreenState::Off)
+            state_ = ScreenState::Dimmed;
+    }
+    return state_;
+}
+
+ButtonAction PowerButton::update(bool pressed, uint32_t nowMs) {
+    if (pressed && !pressed_) {
+        pressed_ = true;
+        longFired_ = false;
+        pressedAtMs_ = nowMs;
+        return ButtonAction::None;
+    }
+    if (pressed && !longFired_ && nowMs - pressedAtMs_ >= longMs_) {
+        longFired_ = true;
+        return ButtonAction::LongPress;
+    }
+    if (!pressed && pressed_) {
+        pressed_ = false;
+        return longFired_ ? ButtonAction::None : ButtonAction::ShortPress;
+    }
+    return ButtonAction::None;
+}
+
+}  // namespace roro

lib/services/src/power_policy.h

@@ -0,0 +1,57 @@
+#pragma once
+
+#include <cstdint>
+
+namespace roro {
+
+enum class ScreenState : uint8_t { On, Dimmed, Off };
+
+// Screen power from user activity. Services keep running whatever the screen does.
+class PowerPolicy {
+   public:
+    PowerPolicy(uint32_t dimAfterMs, uint32_t offAfterMs) : dimMs_(dimAfterMs), offMs_(offAfterMs) {}
+
+    void setTimeouts(uint32_t dimAfterMs, uint32_t offAfterMs) {
+        dimMs_ = dimAfterMs;
+        offMs_ = offAfterMs;
+    }
+
+    // Records a key press. Returns true if the key only woke an Off screen and must not reach the App.
+    bool activity(uint32_t nowMs);
+
+    // A Notification is showing until untilMs: an Off screen lights up Dimmed meanwhile. It's not
+    // user activity, so it doesn't restart the timeouts.
+    void notify(uint32_t nowMs, uint32_t untilMs) {
+        (void)nowMs;
+        notifyUntilMs_ = untilMs;
+        notifying_ = true;
+    }
+
+    ScreenState update(uint32_t nowMs);
+    ScreenState state() const { return state_; }
+
+   private:
+    uint32_t dimMs_;
+    uint32_t offMs_;
+    uint32_t lastActivityMs_ = 0;
+    uint32_t notifyUntilMs_ = 0;
+    bool notifying_ = false;
+    ScreenState state_ = ScreenState::On;
+};
+
+enum class ButtonAction : uint8_t { None, ShortPress, LongPress };
+
+// G0 button: a long press fires as soon as the hold time is reached (power off); a short press on release.
+class PowerButton {
+   public:
+    explicit PowerButton(uint32_t longPressMs) : longMs_(longPressMs) {}
+    ButtonAction update(bool pressed, uint32_t nowMs);
+
+   private:
+    uint32_t longMs_;
+    bool pressed_ = false;
+    bool longFired_ = false;
+    uint32_t pressedAtMs_ = 0;
+};
+
+}  // namespace roro

lib/services/src/settings.cpp

@@ -0,0 +1,135 @@
+#include "settings.h"
+
+#include "ipv4.h"
+
+namespace roro {
+
+namespace {
+
+enum class Kind : uint8_t { Bool, Int, String };
+
+struct Definition {
+    const char* key;
+    Kind kind;
+    int32_t defaultInt;
+    const char* defaultString;
+    int32_t min;
+    int32_t max;  // for strings: max length in bytes
+};
+
+// Order must match the Setting enum.
+const Definition kDefinitions[] = {
+    {"setup_done", Kind::Bool, 0, nullptr, 0, 1},
+    {"long_name", Kind::String, 0, "", 1, 39},
+    {"short_name", Kind::String, 0, "", 1, 4},
+    {"region", Kind::String, 0, "EU868", 1, 8},
+    {"region_ok", Kind::Bool, 0, nullptr, 0, 1},
+    {"timezone", Kind::String, 0, "CET-1CEST,M3.5.0,M10.5.0/3", 1, 63},
+    {"brightness", Kind::Int, 60, nullptr, 10, 100},
+    {"dim_s", Kind::Int, 30, nullptr, 5, 600},
+    {"off_s", Kind::Int, 60, nullptr, 10, 3600},
+    {"sound", Kind::Bool, 1, nullptr, 0, 1},
+    {"probe_mac_raw", Kind::Bool, 1, nullptr, 0, 1},
+    {"wifi_on", Kind::Bool, 1, nullptr, 0, 1},
+    {"gnss_on", Kind::Bool, 1, nullptr, 0, 1},
+    {"coord_dms", Kind::Bool, 0, nullptr, 0, 1},
+    {"lora_preset", Kind::Int, 0, nullptr, 0, 6},  // LongFast first
+    {"dns1", Kind::String, 0, "9.9.9.9", 7, 15},  // Quad9
+    {"dns2", Kind::String, 0, "1.1.1.1", 0, 15},  // Cloudflare
+    {"dns_always", Kind::Bool, 0, nullptr, 0, 1},
+    {"ntp1", Kind::String, 0, "pool.ntp.org", 1, 63},
+    {"ntp2", Kind::String, 0, "time.cloudflare.com", 0, 63},
+    {"gnss_quiet", Kind::Bool, 0, nullptr, 0, 1},  // off: GNSS stays on, as decided in M2 (Q58)
+};
+static_assert(sizeof(kDefinitions) / sizeof(kDefinitions[0]) == static_cast<size_t>(Setting::Count),
+              "every Setting needs a definition");
+
+const char* const kKnownRegions[] = {"EU868"};
+
+const Definition& def(Setting s) { return kDefinitions[static_cast<size_t>(s)]; }
+
+}  // namespace
+
+Settings::Settings(KeyValueStore& store, EventBus& bus) : store_(store), bus_(bus) {}
+
+const char* Settings::key(Setting s) { return def(s).key; }
+
+void Settings::load() {
+    for (size_t i = 0; i < values_.size(); i++) {
+        auto s = static_cast<Setting>(i);
+        const auto& d = def(s);
+        auto& v = values_[i];
+        if (d.kind == Kind::String) {
+            v.str = d.defaultString;
+            std::string stored;
+            if (store_.getString(d.key, stored) && validString(s, stored)) v.str = stored;
+        } else {
+            v.i = d.defaultInt;
+            int32_t stored;
+            if (store_.getInt(d.key, stored) && validInt(s, stored)) v.i = stored;
+        }
+    }
+}
+
+int32_t Settings::getInt(Setting s) const { return values_[static_cast<size_t>(s)].i; }
+bool Settings::getBool(Setting s) const { return getInt(s) != 0; }
+const std::string& Settings::getString(Setting s) const { return values_[static_cast<size_t>(s)].str; }
+
+bool Settings::validInt(Setting s, int32_t value) const {
+    const auto& d = def(s);
+    if (d.kind == Kind::String || value < d.min || value > d.max) return false;
+    if (s == Setting::DimTimeoutS) return value < getInt(Setting::OffTimeoutS);
+    if (s == Setting::OffTimeoutS) return value > getInt(Setting::DimTimeoutS);
+    return true;
+}
+
+bool Settings::validString(Setting s, const std::string& value) const {
+    const auto& d = def(s);
+    if (d.kind != Kind::String) return false;
+    if (value.size() < static_cast<size_t>(d.min) || value.size() > static_cast<size_t>(d.max)) return false;
+    if (s == Setting::Region) {
+        for (auto region : kKnownRegions)
+            if (value == region) return true;
+        return false;
+    }
+    uint32_t address;
+    if (s == Setting::Dns1) return net::parseIpv4(value, address);
+    if (s == Setting::Dns2) return value.empty() || net::parseIpv4(value, address);
+    if (s == Setting::Ntp1) return net::validHost(value);
+    if (s == Setting::Ntp2) return value.empty() || net::validHost(value);
+    return true;
+}
+
+bool Settings::setInt(Setting s, int32_t value) {
+    if (def(s).kind == Kind::Bool) return false;
+    if (!validInt(s, value)) return false;
+    if (getInt(s) == value) return true;
+    values_[static_cast<size_t>(s)].i = value;
+    store_.putInt(key(s), value);
+    changed(s);
+    return true;
+}
+
+bool Settings::setBool(Setting s, bool value) {
+    if (def(s).kind != Kind::Bool) return false;
+    if (getBool(s) == value) return true;
+    values_[static_cast<size_t>(s)].i = value ? 1 : 0;
+    store_.putInt(key(s), value ? 1 : 0);
+    changed(s);
+    return true;
+}
+
+bool Settings::setString(Setting s, const std::string& value) {
+    if (!validString(s, value)) return false;
+    if (getString(s) == value) return true;
+    values_[static_cast<size_t>(s)].str = value;
+    store_.putString(key(s), value);
+    changed(s);
+    return true;
+}
+
+void Settings::changed(Setting s) {
+    bus_.publish(Event::withText(EventType::SettingChanged, key(s), static_cast<int32_t>(s)));
+}
+
+}  // namespace roro