From ca1351aff1b4708ca87d0becc0a68972f95b0b52 Mon Sep 17 00:00:00 2001
From: MarekZegare4 <mineupper@gmail.com>
Date: Wed, 12 Aug 2026 23:16:19 +0200
Subject: [PATCH] docs: cover the new boards and !gps fix in solo-specific docs

README's Supported Devices table and Flashing section gain the
Cardputer ADV and T-Echo Lite + KeyShield rows/headings (both marked
experimental, matching release-notes.md and the Heltec V3/V4 entries).
external_keyboard.md gets a new section for their built-in TCA8418
keypads -- a separate mechanism from CardKB, not documented anywhere
before. settings_screen.md's GPS pwr row now lists !gps fix among the
things that hold GPS continuously on, matching the actual code.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md                                     | 12 +++++----
 docs/solo_features/external_keyboard.md       | 26 ++++++++++++++++---
 .../settings_screen/settings_screen.md        |  2 +-
 3 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 8e1e1be7..5778cf09 100644
--- a/README.md
+++ b/README.md
@@ -15,14 +15,16 @@ Solo firmware thread: https://discord.com/channels/1495203904898728149/150529433
 | Seeed Wio Tracker L1 (OLED) | nRF52840 | SSD1306 / SH1106 128 × 64 | `solo-<version>-WioTrackerL1.uf2` |
 | Seeed Wio Tracker L1 (E-ink) | nRF52840 | GxEPD2 250 × 122 | `solo-<version>-WioTrackerL1Eink.uf2` |
 | GAT562 30S Mesh Kit | nRF52840 | SSD1306 128 × 64 | `solo-<version>-GAT562-30S-Mesh-Kit.uf2` |
-| Heltec LoRa32 V3 | ESP32-S3 | SSD1306 128 × 64 | `solo-<version>-Heltec-v3-merged.bin` |
-| Heltec LoRa32 V4 | ESP32-S3 | SSD1306 128 × 64 | `solo-<version>-heltec-v4-merged.bin` |
+| Heltec LoRa32 V3 *(experimental)* | ESP32-S3 | SSD1306 128 × 64 | `solo-<version>-Heltec-v3-merged.bin` |
+| Heltec LoRa32 V4 *(experimental)* | ESP32-S3 | SSD1306 128 × 64 | `solo-<version>-heltec-v4-merged.bin` |
+| M5Stack Cardputer ADV *(experimental)* | ESP32-S3 | ST7789 TFT 240 × 135 | `solo-<version>-M5Stack-Cardputer-ADV-merged.bin` |
+| LilyGO T-Echo Lite + KeyShield *(experimental)* | nRF52840 | GxEPD2 250 × 122 | `solo-<version>-LilyGo-T-Echo-Lite-keyshield.uf2` |
 
 All firmware files are published on the [releases page](https://github.com/MarekZegare4/MeshCore-Solo/releases). Each binary supports both BLE and USB serial — there are no separate BLE/USB builds.
 
 The MCU column decides how you flash: nRF52840 boards take a drag-and-drop `.uf2`, ESP32-S3 boards take a `.bin` written with a flasher — see [Flashing](#flashing).
 
-The three nRF52840 boards work out of the box. The two Heltec boards have no joystick and no keyboard of their own, so they need [a keyboard or a joystick wired up](#hardware-setup--heltec-v3--v4) before the solo UI can be driven.
+The Wio Tracker L1s, GAT562 and the Cardputer ADV work out of the box. Heltec V3/V4 have no joystick and no keyboard of their own, so they need [a keyboard or a joystick wired up](#hardware-setup--heltec-v3--v4) before the solo UI can be driven. The Cardputer ADV has a built-in QWERTY keyboard; the T-Echo Lite needs the KeyShield add-on (its own T9 keypad) to be usable standalone — see [External Keyboard & Joystick](./docs/solo_features/external_keyboard.md).
 
 <!-- **Enclosures (Wio Tracker L1)**
 - [E-ink case](https://www.printables.com/model/1420534-seeed-wio-tracker-l1-e-ink-enclosure)
@@ -87,13 +89,13 @@ The e-ink variant targets the Wio Tracker L1 fitted with a 2.13″ GxEPD2 panel
 >
 > Updating from an earlier Solo release does not need this, unless the release notes say otherwise.
 
-### nRF52840 boards — Wio Tracker L1, GAT562
+### nRF52840 boards — Wio Tracker L1, GAT562, T-Echo Lite + KeyShield
 
 1. Download the `.uf2` file for your device from the [releases page](https://github.com/MarekZegare4/MeshCore-Solo/releases)
 2. Press reset twice quickly to enter bootloader mode — the device should appear as a mass storage drive on your computer
 3. Copy the `.uf2` file to the drive to flash the firmware
 
-### ESP32-S3 boards — Heltec V3, V4
+### ESP32-S3 boards — Heltec V3, V4, Cardputer ADV
 
 ESP32-S3 has no UF2 bootloader and no mass-storage mode. Releases ship a single **`-merged.bin`** per board — bootloader, partition table and app in one image — which goes to offset `0x0`:
 
diff --git a/docs/solo_features/external_keyboard.md b/docs/solo_features/external_keyboard.md
index 2eb7e8b2..0ee34047 100644
--- a/docs/solo_features/external_keyboard.md
+++ b/docs/solo_features/external_keyboard.md
@@ -3,7 +3,9 @@
 [Go back](../../README.md)
 
 Two optional hardware add-ons, both auto-detected and both entirely optional — a
-build with them enabled runs exactly the same with nothing plugged in.
+build with them enabled runs exactly the same with nothing plugged in. Two of
+the newer boards also ship with their own **built-in** keypad instead —
+see [Built-in keyboards](#built-in-keyboards-cardputer-adv-t-echo-lite--keyshield).
 
 - **CardKB** — an M5Stack I2C QWERTY keyboard (address `0x5F`), for typing
   messages, names and labels without walking the on-screen letter grid.
@@ -17,8 +19,10 @@ build with them enabled runs exactly the same with nothing plugged in.
 | Seeed Wio Tracker L1 (OLED) | ✅ Grove connector | onboard |
 | Seeed Wio Tracker L1 (E-ink) | ✅ Grove connector | onboard |
 | GAT562 30S Mesh Kit | — | onboard |
-| Heltec V3 | ✅ solder to free GPIOs | ✅ solder to free GPIOs |
-| Heltec V4 | ✅ solder to free GPIOs | ✅ solder to free GPIOs |
+| Heltec V3 *(experimental)* | ✅ solder to free GPIOs | ✅ solder to free GPIOs |
+| Heltec V4 *(experimental)* | ✅ solder to free GPIOs | ✅ solder to free GPIOs |
+| M5Stack Cardputer ADV *(experimental)* | — | built-in keyboard instead, see below |
+| LilyGO T-Echo Lite + KeyShield *(experimental)* | — | built-in keypad instead, see below |
 
 ---
 
@@ -114,3 +118,19 @@ Everything above lives in the `[env:Heltec_v3_companion_solo_dual]` /
 and [`variants/heltec_v4/platformio.ini`](../../variants/heltec_v4/platformio.ini),
 with comments explaining which pins are safe to reuse. To build a CardKB-only
 device, comment out the joystick block and set Ext. KB to Compact.
+
+---
+
+## Built-in keyboards (Cardputer ADV, T-Echo Lite + KeyShield)
+
+*Experimental* — newly-added board support, not the CardKB/joystick add-ons
+above. Both keypads are TCA8418-based and share one polling path, entirely
+independent of the CardKB code — a board can have either, or neither.
+
+- **M5Stack Cardputer ADV** — built-in QWERTY, no CardKB or joystick needed.
+- **LilyGO T-Echo Lite + KeyShield** — the KeyShield add-on gives the T-Echo
+  Lite a T9 keypad; without it the board has no usable input for the solo UI.
+
+Neither keypad follows CardKB's exact Fn-shortcut table (Fn+Enter,
+Fn+letter accent popups, Tab, Fn+Esc lock) — see each board's own
+`platformio.ini` / keyboard driver under `variants/` for its current keymap.
diff --git a/docs/solo_features/settings_screen/settings_screen.md b/docs/solo_features/settings_screen/settings_screen.md
index 1296a668..c4926ed3 100644
--- a/docs/solo_features/settings_screen/settings_screen.md
+++ b/docs/solo_features/settings_screen/settings_screen.md
@@ -90,7 +90,7 @@ The **repeater** mode and its flood filters live on their own screen — see **T
 | Name        | keyboard entry (up to 31 chars)                     | This device's node name, shown to others and in every advert. **Enter** opens the keyboard pre-filled with the current name; applied and saved on submit |
 | Timezone    | −12 h … +14 h                                       | UTC offset in whole hours                                                              |
 | Low battery | off / 3.0 V / 3.1 V / 3.2 V / 3.3 V / 3.4 V / 3.5 V | Auto-shutdown threshold; also sets the 0 % anchor for the battery percentage indicator |
-| GPS pwr _(if GPS detected)_ | off / 1 min / 5 min / 15 min / 30 min / 1 h | **Battery saver.** Cycles GPS off between fixes instead of running it continuously; each wake waits for a fix (up to 60 s) before sleeping again for the chosen interval. Automatically stays continuously on regardless of this setting whenever something needs a live position — an active Trail recording, Map › Live share, an armed Locator, or the Compass / Nearby navigate view. `off` (default) matches earlier releases: GPS runs continuously whenever enabled. The GPS status icon blinks while napping between fixes. |
+| GPS pwr _(if GPS detected)_ | off / 1 min / 5 min / 15 min / 30 min / 1 h | **Battery saver.** Cycles GPS off between fixes instead of running it continuously; each wake waits for a fix (up to 60 s) before sleeping again for the chosen interval. Automatically stays continuously on regardless of this setting whenever something needs a live position — an active Trail recording, Map › Live share, an armed Locator, the Compass / Nearby navigate view, or an in-flight `!gps fix` bot request. `off` (default) matches earlier releases: GPS runs continuously whenever enabled. The GPS status icon blinks while napping between fixes. |
 | Units       | Metric / Imperial                                   | Global unit system for every distance/speed shown in Tools (Nearby Nodes, Trail, navigate-to-point). Metric: m / km, km/h, min/km. Imperial: ft / mi, mph, min/mi |
 | Reboot      | action (**Enter**)                                  | Restarts this device. Pending setting changes are saved first. Last row, so it isn't the default-selected one |