fix serial monitor loop issue

- Bond clearing on firmware version change (lines 38-67) — stores the firmware version string in SPIFFS at /ble_ver. On boot, if it doesn't match, all stored bonds are wiped. This fixes the forget/re-pair issue after flashing. Normal reboots keep pairing intact.
- TX power -3 dBm (line 73).
Connection parameter negotiation (lines 137-147) — latency=4 for power saving when connected.
- Advertising intervals 300ms/600ms (three places) — compromise between discovery speed and power.
- No controller power-down — the header file is unchanged from stock.

Audiobook Player Guide.md

@@ -0,0 +1,78 @@
+## Audiobook Player (Audio variant only)
+
+Press **P** from the home screen to open the audiobook player.
+Place `.mp3`, `.m4b`, `.m4a`, or `.wav` files in `/audiobooks/` on the SD card.
+Files can be organised into subfolders (e.g. by author) — use **Enter** to
+browse into folders and **.. (up)** to go back.
+
+| Key | Action |
+|-----|--------|
+| W / S | Scroll file list / Volume up-down |
+| Enter | Select book or folder / Play-Pause |
+| A | Seek back 30 seconds |
+| D | Seek forward 30 seconds |
+| [ | Previous chapter (M4B only) |
+| ] | Next chapter (M4B only) |
+| Q | Leave player (audio continues) / Close book (when paused) / Exit (from file list) |
+
+### Recommended Format
+
+**MP3 is the recommended format.** M4B/M4A files are supported but currently
+have playback issues with the ESP32-audioI2S library — some files may fail to
+decode or produce silence. MP3 files play reliably and are the safest choice.
+
+MP3 files should be encoded at a **44100 Hz sample rate**. Lower sample rates
+(e.g. 22050 Hz) can cause distortion or playback failure due to ESP32-S3 I2S
+hardware limitations.
+
+**Bookmarks** are saved automatically every 30 seconds during playback and when
+you stop or exit. Reopening a book resumes from your last position.
+
+**Cover art** from M4B files is displayed as dithered monochrome on the e-ink
+screen, along with title, author, and chapter information.
+
+**Metadata caching** — the first time you open the audiobook player, it reads
+title and author tags from each file (which can take a few seconds with many
+files). This metadata is cached to the SD card so subsequent visits load
+near-instantly. If you add or remove files the cache updates automatically.
+
+### Background Playback
+
+Audio continues playing when you leave the audiobook player screen. Press **Q**
+while audio is playing to return to the home screen — a **>>** indicator will
+appear in the status bar next to the battery icon to show that audio is active
+in the background. Press **P** at any time to return to the player screen and
+resume control.
+
+If you pause or stop playback first and then press **Q**, the book is closed
+and you're returned to the file list instead.
+
+### Audio Hardware
+
+The audiobook player uses the PCM5102A I2S DAC on the audio variant of the
+T-Deck Pro (I2S pins: BCLK=7, DOUT=8, LRC=9). Audio is output via the 3.5mm
+headphone jack.
+
+> **Note:** The audiobook player is not available on the 4G modem variant
+> due to I2S pin conflicts.
+
+### SD Card Folder Structure
+
+```
+SD Card
+├── audiobooks/
+│   ├── .bookmarks/          (auto-created, stores resume positions)
+│   │   ├── mybook.bmk
+│   │   └── another.bmk
+│   ├── .metacache            (auto-created, speeds up file list loading)
+│   ├── Ann Leckie/
+│   │   ├── Ancillary Justice.mp3
+│   │   └── Ancillary Sword.mp3
+│   ├── Iain M. Banks/
+│   │   └── The Algebraist.mp3
+│   ├── mybook.mp3
+│   └── podcast.mp3
+├── books/                   (existing — text reader)
+│   └── ...
+└── ...
+```

README.md

@@ -1,7 +1,36 @@
 ## Meshcore + Fork = Meck 
 This fork was created specifically to focus on enabling BLE companion firmware for the LilyGo T-Deck Pro. Created with the assistance of Claude AI using Meshcore v1.11 code. 
 
-⭐ ***Please note as of 1 Feb 2026, the T-Deck Pro repeater & usb firmware has not been finalised nor confirmed as functioning.*** ⭐
+<img src="https://github.com/user-attachments/assets/b30ce6bd-79af-44d3-93c4-f5e7e21e5621" alt="IMG_1453" width="300" height="650">
+
+### Contents
+- [T-Deck Pro Keyboard Controls](#t-deck-pro-keyboard-controls)
+  - [Navigation (Home Screen)](#navigation-home-screen)
+  - [Bluetooth (BLE)](#bluetooth-ble)
+  - [Clock & Timezone](#clock--timezone)
+  - [Channel Message Screen](#channel-message-screen)
+  - [Contacts Screen](#contacts-screen)
+  - [Sending a Direct Message](#sending-a-direct-message)
+  - [Repeater Admin Screen](#repeater-admin-screen)
+  - [Settings Screen](#settings-screen)
+  - [Compose Mode](#compose-mode)
+  - [Symbol Entry (Sym Key)](#symbol-entry-sym-key)
+  - [Emoji Picker](#emoji-picker)
+  - [SMS & Phone App (4G only)](#sms--phone-app-4g-only)
+  - [Web Browser & IRC](#web-browser--irc)
+- [About MeshCore](#about-meshcore)
+- [What is MeshCore?](#what-is-meshcore)
+- [Key Features](#key-features)
+- [What Can You Use MeshCore For?](#what-can-you-use-meshcore-for)
+- [How to Get Started](#how-to-get-started)
+- [MeshCore Flasher](#meshcore-flasher)
+- [MeshCore Clients](#meshcore-clients)
+- [Hardware Compatibility](#-hardware-compatibility)
+- [Contributing](#contributing)
+- [Road-Map / To-Do](#road-map--to-do)
+- [Get Support](#-get-support)
+- [License](#-license)
+  - [Third-Party Libraries](#third-party-libraries)
 
 ## T-Deck Pro Keyboard Controls
 
@@ -12,37 +41,75 @@ The T-Deck Pro BLE companion firmware includes full keyboard support for standal
 | Key | Action |
 |-----|--------|
 | W / A | Previous page |
-| S / D | Next page |
+| D | Next page |
 | Enter | Select / Confirm |
 | M | Open channel messages |
-| N | Open contacts list |
-| R | Open e-book reader |
+| C | Open contacts list |
+| E | Open e-book reader |
+| N | Open notes |
+| S | Open settings |
+| B | Open web browser (BLE and 4G variants only) |
+| T | Open SMS & Phone app (4G variant only) |
+| P | Open audiobook player (audio variant only) |
 | Q | Back to home screen |
 
+### Bluetooth (BLE)
+
+BLE is **disabled by default** at boot to support standalone-first operation. The device is fully functional without a phone — you can send and receive messages, browse contacts, read e-books, and set your timezone directly from the keyboard.
+
+To connect to the MeshCore companion app, navigate to the **Bluetooth** home page (use D to page through) and press **Enter** to toggle BLE on. The BLE PIN will be displayed on screen. Toggle it off again the same way when you're done.
+
+### Clock & Timezone
+
+The T-Deck Pro does not include a dedicated RTC chip, so after each reboot the device clock starts unset. The clock will appear in the nav bar (between node name and battery) once the time has been synced by one of two methods:
+
+1. **GPS fix** (standalone) — Once the GPS acquires a satellite fix, the time is automatically synced from the NMEA data. No phone or BLE connection required. Typical time to first fix is 30–90 seconds outdoors with clear sky.
+2. **BLE companion app** — If BLE is enabled and connected to the MeshCore companion app, the app will push the current time to the device.
+
+**Setting your timezone:**
+
+The UTC offset can be set from the **Settings** screen (press **S** from the home screen), or from the **GPS** home page by pressing **U** to open the UTC offset editor.
+
+| Key | Action |
+|-----|--------|
+| W | Increase offset (+1 hour) |
+| S | Decrease offset (-1 hour) |
+| Enter | Save and exit |
+| Q | Cancel and exit |
+
+The UTC offset is persisted to flash and survives reboots — you only need to set it once. The valid range is UTC-12 to UTC+14. For example, AEST is UTC+10 and AEDT is UTC+11.
+
+The GPS page also shows the current time, satellite count, position, altitude, and your configured UTC offset for reference.
+
 ### Channel Message Screen
 
 | Key | Action |
 |-----|--------|
 | W / S | Scroll messages up/down |
 | A / D | Switch between channels |
-| C | Compose new message |
+| Enter | Compose new message |
+| R | Reply to a message — enter reply select mode, scroll to a message with W/S, then press Enter to compose a reply with an @mention |
+| V | View relay path of the last received message (scrollable, up to 20 hops) |
 | Q | Back to home screen |
 
 ### Contacts Screen
 
-Press **N** from the home screen to open the contacts list. All known mesh contacts are shown sorted by most recently seen, with their type (Chat, Repeater, Room, Sensor), hop count, and time since last advert.
+Press **C** from the home screen to open the contacts list. All known mesh contacts are shown sorted by most recently seen, with their type (Chat, Repeater, Room, Sensor), hop count, and time since last advert.
 
 | Key | Action |
 |-----|--------|
 | W / S | Scroll up / down through contacts |
-| A / D | Cycle filter: All → Chat → Repeater → Room → Sensor |
+| A / D | Cycle filter: All → Chat → Repeater → Room → Sensor → Favourites |
 | Enter | Open DM compose (Chat contact) or repeater admin (Repeater contact) |
-| C | Open DM compose to selected chat contact |
+| X | Export contacts to SD card (wait 5–10 seconds for confirmation popup) |
+| R | Import contacts from SD card (wait 5–10 seconds for confirmation popup) |
 | Q | Back to home screen |
 
+**Contact limits:** Standalone variants support up to 1,500 contacts (stored in PSRAM). BLE variants (both Audio-BLE and 4G-BLE) are limited to 500 contacts due to BLE protocol constraints.
+
 ### Sending a Direct Message
 
-Select a **Chat** contact in the contacts list and press **Enter** or **C** to start composing a direct message. The compose screen will show `DM: ContactName` in the header. Type your message and press **Enter** to send. The DM is sent encrypted directly to that contact (or flooded if no direct path is known). After sending or cancelling, you're returned to the contacts list.
+Select a **Chat** contact in the contacts list and press **Enter** to start composing a direct message. The compose screen will show `DM: ContactName` in the header. Type your message and press **Enter** to send. The DM is sent encrypted directly to that contact (or flooded if no direct path is known). After sending or cancelling, you're returned to the contacts list.
 
 ### Repeater Admin Screen
 
@@ -63,11 +130,41 @@ After a successful login, you'll see a menu with the following remote administra
 |-----|--------|
 | W / S | Navigate menu items |
 | Enter | Execute selected command |
-| C | Enter compose mode (send raw CLI command) |
 | Q | Back to contacts (from menu) or cancel login |
 
 Command responses are displayed in a scrollable view. Use **W / S** to scroll long responses and **Q** to return to the menu.
 
+### Settings Screen
+
+Press **S** from the home screen to open settings. On first boot (when the device name is still the default hex ID), the settings screen launches automatically as an onboarding wizard to set your device name and radio preset.
+
+| Key | Action |
+|-----|--------|
+| W / S | Navigate up / down through settings |
+| Enter | Edit selected setting |
+| Q | Back to home screen |
+
+**Available settings:**
+
+| Setting | Edit Method |
+|---------|-------------|
+| Device Name | Text entry — type a name, Enter to confirm |
+| Radio Preset | A / D to cycle presets (MeshCore Default, Long Range, Fast/Short, EU Default), Enter to apply |
+| Frequency | W / S to adjust, Enter to confirm |
+| Bandwidth | W / S to cycle standard values (31.25 / 62.5 / 125 / 250 / 500 kHz), Enter to confirm |
+| Spreading Factor | W / S to adjust (5–12), Enter to confirm |
+| Coding Rate | W / S to adjust (5–8), Enter to confirm |
+| TX Power | W / S to adjust (1–20 dBm), Enter to confirm |
+| UTC Offset | W / S to adjust (-12 to +14), Enter to confirm |
+| Channels | View existing channels, add hashtag channels, or delete non-primary channels (X) |
+| Device Info | Public key and firmware version (read-only) |
+
+The bottom of the settings screen also displays your node ID and firmware version. On the 4G variant, IMEI, carrier name, and APN details are shown here as well.
+
+When adding a hashtag channel, type the channel name and press Enter. The channel secret is automatically derived from the name via SHA-256, matching the standard MeshCore hashtag convention.
+
+If you've changed radio parameters, pressing Q will prompt you to apply changes before exiting.
+
 ### Compose Mode
 
 | Key | Action |
@@ -113,6 +210,22 @@ While in compose mode, press the **$** key to open the emoji picker. A scrollabl
 | Enter | Insert selected emoji |
 | $ / Q / Backspace | Cancel and return to compose |
 
+### SMS & Phone App (4G only)
+
+Press **T** from the home screen to open the SMS & Phone app. The app opens to a menu screen where you can choose between the **Phone** dialer (for calling any number) or the **SMS Inbox** (for messaging and calling saved contacts).
+
+For full documentation including key mappings, dialpad usage, contacts management, and troubleshooting, see the [SMS & Phone App Guide](SMS%20%26%20Phone%20App%20Guide.md).
+
+### Web Browser & IRC
+
+Press **B** from the home screen to open the web reader. This is available on the BLE and 4G variants (not the standalone audio variant, which excludes WiFi to preserve lowest-battery-usage design).
+
+The web reader home screen provides access to the **IRC client**, the **URL bar**, and your **bookmarks** and **history**. Select IRC Chat and press Enter to configure and connect to an IRC server. Select the URL bar to enter a web address, or scroll down to open a bookmark or history entry.
+
+The browser is a text-centric reader best suited to text-heavy websites. It also includes basic web search via DuckDuckGo Lite, and can download EPUB files — follow a link to an `.epub` and it will be saved to the books folder on your SD card for reading later in the e-book reader.
+
+For full documentation including key mappings, WiFi setup, bookmarks, IRC configuration, and SD card structure, see the [Web App Guide](Web%20App%20Guide.md).
+
 ## About MeshCore
 
 MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.
@@ -169,7 +282,9 @@ Download a copy of the Meck firmware bin from https://github.com/pelgraine/Meck/
 
 **Companion Firmware**
 
-The companion firmware can be connected to via BLE. USB is planned for a future update.
+The companion firmware can be connected to via BLE.
+
+> **Note:** On the T-Deck Pro, BLE is disabled by default at boot. Navigate to the Bluetooth home page and press Enter to enable BLE before connecting with a companion app.
 
 - Web: https://app.meshcore.nz
 - Android: https://play.google.com/store/apps/details?id=com.liamcottle.meshcore.android
@@ -181,10 +296,6 @@ The companion firmware can be connected to via BLE. USB is planned for a future
 
 MeshCore is designed for devices listed in the [MeshCore Flasher](https://flasher.meshcore.co.uk)
 
-## 📜 License
-
-MeshCore is open-source software released under the MIT License. You are free to use, modify, and distribute it for personal and commercial projects.
-
 ## Contributing
 
 Please submit PR's using 'dev' as the base branch!
@@ -204,11 +315,38 @@ There are a number of fairly major features in the pipeline, with no particular
 - [X] Standalone DM functionality for Companion BLE firmware
 - [X] Contacts list with filtering for Companion BLE firmware
 - [X] Standalone repeater admin access for Companion BLE firmware
-- [ ] Companion radio: USB
-- [ ] Simple Repeater firmware for the T-Deck Pro
-- [ ] Get pin 45 with the screen backlight functioning for the T-Deck Pro v1.1
-- [ ] Canned messages function for Companion BLE firmware
+- [X] GPS time sync with on-device timezone setting
+- [X] Settings screen with radio presets, channel management, and first-boot onboarding
+- [X] Expand SMS app to enable phone calls
+- [X] Basic web reader app for text-centric websites
+- [ ] Fix M4B rendering to enable chaptered audiobook playback
+- [ ] Better JPEG and PNG decoding
+- [ ] Improve EPUB rendering and EPUB format handling
+- [ ] Map support with GPS
+- [ ] WiFi companion environment
 
 ## 📞 Get Support
 
-- Join [MeshCore Discord](https://discord.gg/BMwCtwHj5V) to chat with the developers and get help from the community.
+- Join [MeshCore Discord](https://discord.gg/BMwCtwHj5V) to chat with the developers and get help from the community.
+
+## 📜 License
+
+The upstream [MeshCore](https://github.com/meshcore-dev/MeshCore) library is released under the **MIT License** (Copyright © 2025 Scott Powell / rippleradios.com). Meck-specific code (UI screens, display helpers, device integration) is also provided under the MIT License.
+
+However, this firmware links against libraries with different license terms. Because two dependencies use the **GPL-3.0** copyleft license, the combined firmware binary is effectively subject to GPL-3.0 obligations when distributed. Please review the individual licenses below if you intend to redistribute or modify this firmware.
+
+### Third-Party Libraries
+
+| Library | License | Author / Source |
+|---------|---------|-----------------|
+| [MeshCore](https://github.com/meshcore-dev/MeshCore) | MIT | Scott Powell / rippleradios.com |
+| [GxEPD2](https://github.com/ZinggJM/GxEPD2) | GPL-3.0 | Jean-Marc Zingg |
+| [ESP32-audioI2S](https://github.com/schreibfaul1/ESP32-audioI2S) | GPL-3.0 | schreibfaul1 (Wolle) |
+| [Adafruit GFX Library](https://github.com/adafruit/Adafruit-GFX-Library) | BSD | Adafruit |
+| [RadioLib](https://github.com/jgromes/RadioLib) | MIT | Jan Gromeš |
+| [JPEGDEC](https://github.com/bitbank2/JPEGDEC) | Apache-2.0 | Larry Bank (bitbank2) |
+| [CRC32](https://github.com/bakercp/CRC32) | MIT | Christopher Baker |
+| [base64](https://github.com/Densaugeo/base64_arduino) | MIT | densaugeo |
+| [Arduino Crypto](https://github.com/rweather/arduinolibs) | MIT | Rhys Weatherley |
+
+Full license texts for each dependency are available in their respective repositories linked above.

SMS & Phone App Guide.md

@@ -0,0 +1,206 @@
+## SMS & Phone App (4G variant only) - Meck v0.9.5
+
+Press **T** from the home screen to open the SMS & Phone app.
+Requires a nano SIM card inserted in the T-Deck Pro V1.1 4G modem slot and an
+SD card formatted as FAT32. The modem registers on the cellular network
+automatically at boot — the red LED on the board indicates the modem is
+powered. The modem (and its red LED) can be switched off and on from the
+settings screen. After each modem startup, the system clock syncs from the
+cellular network, which takes roughly 15 seconds.
+
+### App Menu
+
+The SMS & Phone app opens to a landing screen with two options:
+
+| Option | Description |
+|--------|-------------|
+| **Phone** | Open the phone dialer to call any number |
+| **SMS Inbox** | Open the SMS inbox for messaging and calling saved contacts |
+
+Use **W / S** to select an option and **Enter** to confirm. Press **Q** to
+return to the home screen.
+
+### Key Mapping
+
+| Context | Key | Action |
+|---------|-----|--------|
+| Home screen | T | Open SMS & Phone app |
+| App menu | W / S | Select Phone or SMS Inbox |
+| App menu | Enter | Open selected option |
+| App menu | Q | Back to home screen |
+| Inbox | W / S | Scroll conversations |
+| Inbox | Enter | Open conversation |
+| Inbox | C | Compose new SMS (enter phone number) |
+| Inbox | D | Open contacts directory |
+| Inbox | Q | Back to app menu |
+| Conversation | W / S | Scroll messages |
+| Conversation | C | Reply to this conversation |
+| Conversation | F | Call this number |
+| Conversation | A | Add or edit contact name for this number |
+| Conversation | Q | Back to inbox |
+| Compose | Enter | Send SMS (from body) / Confirm phone number (from phone input) |
+| Compose | Shift+Del | Cancel and return |
+| Contacts | W / S | Scroll contact list |
+| Contacts | Enter | Compose SMS to selected contact |
+| Contacts | F | Call selected contact |
+| Contacts | Q | Back to inbox |
+| Edit Contact | Enter | Save contact name |
+| Edit Contact | Shift+Del | Cancel without saving |
+| Phone Dialer | 0–9, *, +, # | Enter phone number (see input methods below) |
+| Phone Dialer | Enter | Place call |
+| Phone Dialer | Backspace | Delete last digit |
+| Phone Dialer | Q | Back to app menu |
+| Dialing | Enter or Q | Cancel / hang up |
+| Incoming Call | Enter | Answer call |
+| Incoming Call | Q | Reject call |
+| In Call | Enter or Q | Hang up |
+| In Call | W / S | Volume up / down (0–5) |
+| In Call | 0–9, *, # | Send DTMF tone |
+
+### Sending an SMS
+
+There are three ways to start a new message:
+
+1. **From inbox** — press **C**, type the destination phone number, press
+   **Enter**, then type your message and press **Enter** to send.
+2. **From a conversation** — press **C** to reply. The recipient is
+   pre-filled so you go straight to typing the message body.
+3. **From the contacts directory** — press **D** from the inbox, scroll to a
+   contact, and press **Enter**. The compose screen opens with the number
+   pre-filled.
+
+Messages are limited to 160 characters (standard SMS). A character counter is
+shown in the footer while composing.
+
+### Making a Phone Call
+
+There are three ways to start a call:
+
+1. **From the phone dialer** — select **Phone** from the app menu to open the
+   dialer. Enter a phone number and press **Enter** to call. This is the
+   easiest way to call a number you haven't messaged before.
+2. **From a conversation** — open a conversation and press **F**. You can call
+   any number you have previously exchanged messages with, whether or not it is
+   saved as a named contact.
+3. **From the contacts directory** — press **D** from the inbox, scroll to a
+   contact, and press **F**.
+
+The display switches to a dialing screen showing the contact name (or phone
+number) and an animated progress indicator. Once the remote party answers, the
+screen transitions to the in-call view with a live call timer.
+
+During an active call, **W** and **S** adjust the speaker volume (0–5). The
+number keys **0–9**, **\***, and **#** send DTMF tones for navigating phone
+menus and voicemail systems. Press **Enter** or **Q** to hang up.
+
+Audio is routed through the A7682E modem's internal codec to the board speaker
+and microphone — no headphones or external audio hardware are required.
+
+### Phone Dialer Input Methods
+
+The phone dialer supports three ways to enter digits:
+
+1. **Direct key press** — press the keyboard letter that corresponds to each
+   number using the silk-screened labels on the T-Deck Pro keys:
+
+   | Key | Digit | | Key | Digit | | Key | Digit |
+   |-----|-------|-|-----|-------|-|-----|-------|
+   | W | 1 | | S | 4 | | Z | 7 |
+   | E | 2 | | D | 5 | | X | 8 |
+   | R | 3 | | F | 6 | | C | 9 |
+   | A | * | | O | + | | Mic | 0 |
+
+2. **Touchscreen tap** — tap the on-screen number buttons directly. Note: this
+   currently requires fairly precise taps on the numbers themselves.
+
+3. **Sym+key** — the standard symbol entry method (e.g. Sym+W for 1, Sym+S for
+   4, etc.)
+
+### Receiving a Phone Call
+
+When an incoming call arrives, the app automatically switches to the incoming
+call screen regardless of which view is active. A short alert and buzzer
+notification are triggered. The caller's name is shown if saved in contacts,
+otherwise the raw phone number is displayed.
+
+Press **Enter** to answer or **Q** to reject the call. If the call is not
+answered it is logged as a missed call and a "Missed: ..." alert is shown
+briefly.
+
+### Contacts
+
+The contacts directory lets you assign display names to phone numbers.
+Names appear in the inbox list, conversation headers, call screens, and
+compose screen instead of raw numbers.
+
+To add or edit a contact, open a conversation with that number and press **A**.
+Type the display name and press **Enter** to save. Names can be up to 23
+characters long.
+
+Contacts are stored as a plain text file at `/sms/contacts.txt` on the SD card
+in `phone=Display Name` format — one per line, human-editable. Up to 30
+contacts are supported.
+
+### Conversation History
+
+Messages are saved to the SD card automatically and persist across reboots.
+Each phone number gets its own file under `/sms/` on the SD card. The inbox
+shows the most recent 20 conversations sorted by last activity. Within a
+conversation, the most recent 30 messages are loaded with the newest at the
+bottom (chat-style). Sent messages are shown with `>>>` and received messages
+with `<<<`.
+
+Message timestamps use the cellular network clock (synced via NITZ roughly 15
+seconds after each modem startup) and display as relative times (e.g. 5m, 2h,
+1d). If the modem is toggled off and back on, the clock re-syncs automatically.
+
+### Modem Power Control
+
+The 4G modem can be toggled on or off from the settings screen. Scroll to
+**4G Modem: ON/OFF** and press **Enter** to toggle. Switching the modem off
+kills its red status LED and stops all cellular activity. The setting persists
+to SD card and is respected on subsequent boots — if disabled, the modem and
+LED stay off until re-enabled. The SMS & Phone app remains accessible when the
+modem is off but will not be able to send or receive messages or calls.
+
+### Signal Indicator
+
+A signal strength indicator is shown in the top-right corner of all SMS and
+call screens. Bars are derived from the modem's CSQ (signal quality) reading,
+updated every 30 seconds. The modem state (REG, READY, OFF, etc.) is shown
+when not yet connected. During a call, the signal indicator remains visible.
+
+### IMEI, Carrier & APN
+
+The 4G modem's IMEI, current carrier name, and APN are displayed at the bottom
+of the settings screen (press **S** from the home screen), alongside your node
+ID and firmware version.
+
+### SD Card Structure
+
+```
+SD Card
+├── sms/
+│   ├── contacts.txt           (plain text, phone=Name format)
+│   ├── modem.cfg              (0 or 1, modem enable state)
+│   ├── 0412345678.sms         (binary message log per phone number)
+│   └── 0498765432.sms
+├── books/                     (text reader)
+├── audiobooks/                (audio variant only)
+└── ...
+```
+
+### Troubleshooting
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| Modem icon stays at REG / never reaches READY | SIM not inserted, no signal, or SIM requires PIN unlock (not currently supported) |
+| Timestamps show `---` | Modem clock hasn't synced yet (wait ~15 seconds after modem startup), or messages were saved before clock sync was available |
+| Red LED stays on after disabling modem | Toggle the setting off, then reboot — the boot sequence ensures power is cut when disabled |
+| SMS sends but no delivery | Check signal strength; below 5 bars is marginal. Move to better coverage |
+| Call drops immediately after dialing | Check signal strength and ensure the SIM plan supports voice calls |
+| No audio during call | The A7682E routes audio through its own codec; ensure the board speaker is not obstructed. Try adjusting volume with W/S |
+
+> **Note:** The SMS & Phone app is only available on the 4G modem variant of
+> the T-Deck Pro. It is not present on the audio or standalone BLE builds due
+> to shared GPIO pin conflicts between the A7682E modem and PCM5102A DAC.

Serial Settings Guide.md

@@ -0,0 +1,315 @@
+# Meck Serial Settings Guide
+
+Configure your T-Deck Pro's Meck firmware over USB serial — no companion app needed. Plug in a USB-C cable, open a serial terminal, and you have full access to every setting on the device.
+
+## Getting Started
+
+### What You Need
+
+- T-Deck Pro running Meck firmware
+- USB-C cable
+- A serial terminal application:
+  - **Windows:** PuTTY, TeraTerm, or the Arduino IDE Serial Monitor
+  - **macOS:** `screen`, CoolTerm, or the Arduino IDE Serial Monitor
+  - **Linux:** `screen`, `minicom`, `picocom`, or the Arduino IDE Serial Monitor
+
+### Connection Settings
+
+| Parameter | Value |
+|-----------|-------|
+| Baud rate | 115200 |
+| Data bits | 8 |
+| Parity | None |
+| Stop bits | 1 |
+| Line ending | CR (carriage return) or CR+LF |
+
+### Quick Start (macOS / Linux)
+
+```
+screen /dev/ttyACM0 115200
+```
+
+On macOS the port is typically `/dev/cu.usbmodem*`. On Linux it is usually `/dev/ttyACM0` or `/dev/ttyUSB0`.
+
+### Quick Start (Arduino IDE)
+
+Open **Tools → Serial Monitor**, set baud to **115200** and line ending to **Carriage Return** or **Both NL & CR**.
+
+Once connected, type `help` and press Enter to confirm everything is working.
+
+---
+
+## Command Reference
+
+All commands follow a simple pattern: `get` to read, `set` to write.
+
+### Viewing Settings
+
+| Command | Description |
+|---------|-------------|
+| `get all` | Dump every setting at once |
+| `get name` | Device name |
+| `get freq` | Radio frequency (MHz) |
+| `get bw` | Bandwidth (kHz) |
+| `get sf` | Spreading factor |
+| `get cr` | Coding rate |
+| `get tx` | TX power (dBm) |
+| `get radio` | All radio params in one line |
+| `get utc` | UTC offset (hours) |
+| `get notify` | Keyboard flash notification (on/off) |
+| `get gps` | GPS status and interval |
+| `get pin` | BLE pairing PIN |
+| `get channels` | List all channels with index numbers |
+| `get presets` | List all radio presets with parameters |
+| `get pubkey` | Device public key (hex) |
+| `get firmware` | Firmware version string |
+
+**4G variant only:**
+
+| Command | Description |
+|---------|-------------|
+| `get modem` | Modem enabled/disabled |
+| `get apn` | Current APN |
+| `get imei` | Device IMEI |
+
+### Changing Settings
+
+#### Device Name
+
+```
+set name MyNode
+```
+
+Names cannot contain these characters: `[ ] / \ : , ? *`
+
+#### Radio Parameters (Individual)
+
+Each of these applies immediately — no reboot required.
+
+```
+set freq 910.525
+set bw 62.5
+set sf 7
+set cr 5
+set tx 22
+```
+
+Valid ranges:
+
+| Parameter | Min | Max |
+|-----------|-----|-----|
+| freq | 400.0 | 928.0 |
+| bw | 7.8 | 500.0 |
+| sf | 5 | 12 |
+| cr | 5 | 8 |
+| tx | 1 | Board max (typically 22) |
+
+#### Radio Parameters (All at Once)
+
+Set frequency, bandwidth, spreading factor, and coding rate in a single command:
+
+```
+set radio 910.525 62.5 7 5
+```
+
+#### Radio Presets
+
+The easiest way to configure your radio. First, list the available presets:
+
+```
+get presets
+```
+
+This prints a numbered list like:
+
+```
+  Available radio presets:
+     0  Australia                       915.800 MHz  BW250.0  SF10  CR5  TX22
+     1  Australia (Narrow)              916.575 MHz  BW62.5   SF7   CR8  TX22
+    ...
+    14  USA/Canada (Recommended)        910.525 MHz  BW62.5   SF7   CR5  TX22
+    15  Vietnam                         920.250 MHz  BW250.0  SF11  CR5  TX22
+```
+
+Apply a preset by name or number:
+
+```
+set preset USA/Canada (Recommended)
+set preset 14
+```
+
+Preset names are case-insensitive, so `set preset australia` works too. The preset applies all five radio parameters (freq, bw, sf, cr, tx) and takes effect immediately.
+
+#### UTC Offset
+
+```
+set utc 10
+```
+
+Range: -12 to +14.
+
+#### Keyboard Notification Flash
+
+Toggle whether the keyboard backlight flashes when a new message arrives:
+
+```
+set notify on
+set notify off
+```
+
+#### BLE PIN
+
+```
+set pin 123456
+```
+
+### Channel Management
+
+#### List Channels
+
+```
+get channels
+```
+
+Output:
+
+```
+  [0] #public
+  [1] #meck-test
+  [2] #local-group
+```
+
+#### Add a Hashtag Channel
+
+```
+set channel.add meck-test
+```
+
+The `#` prefix is added automatically if you omit it. The channel's encryption key is derived from the name (SHA-256), matching the same method used by the on-device Settings screen and companion apps.
+
+#### Delete a Channel
+
+```
+set channel.del 2
+```
+
+Channels are referenced by their index number (shown in `get channels`). Channel 0 (public) cannot be deleted. Remaining channels are automatically compacted after deletion.
+
+### 4G Modem (4G Variant Only)
+
+#### Enable / Disable Modem
+
+```
+set modem on
+set modem off
+```
+
+#### Set APN
+
+```
+set apn telstra.internet
+```
+
+To clear a custom APN and revert to auto-detection on next boot:
+
+```
+set apn
+```
+
+### System Commands
+
+| Command | Description |
+|---------|-------------|
+| `reboot` | Restart the device |
+| `rebuild` | Erase filesystem, re-save identity + prefs + contacts + channels |
+| `erase` | Format the filesystem (caution: loses everything) |
+| `ls UserData/` | List files on internal filesystem |
+| `ls ExtraFS/` | List files on secondary filesystem |
+| `cat UserData/<path>` | Dump file contents as hex |
+| `rm UserData/<path>` | Delete a file |
+| `help` | Show command summary |
+
+---
+
+## Common Workflows
+
+### First-Time Setup
+
+Plug in your new T-Deck Pro and run through these commands to get on the air:
+
+```
+set name YourCallsign
+set preset Australia
+set utc 10
+set channel.add local-group
+get all
+```
+
+### Switching to a New Region
+
+Moving from Australia to the US? One command:
+
+```
+set preset USA/Canada (Recommended)
+```
+
+Verify with:
+
+```
+get radio
+```
+
+### Custom Radio Configuration
+
+If none of the presets match your local group or you need specific parameters, set them directly. You can do it all in one command:
+
+```
+set radio 916.575 62.5 8 8
+set tx 20
+```
+
+Or one parameter at a time if you're only adjusting part of your config:
+
+```
+set freq 916.575
+set bw 62.5
+set sf 8
+set cr 8
+set tx 20
+```
+
+Both approaches apply immediately. Confirm with `get radio` to double-check everything took:
+
+```
+get radio
+  > freq=916.575 bw=62.5 sf=8 cr=8 tx=20
+```
+
+### Troubleshooting Radio Settings
+
+If you're not sure what went wrong, dump everything:
+
+```
+get all
+```
+
+Compare the radio section against what others in your area are using. If you need to match exact parameters from another node:
+
+```
+set radio 916.575 62.5 7 8
+set tx 22
+```
+
+### Backing Up Your Settings
+
+Use `get all` to capture a snapshot of your configuration. Copy the serial output and save it — you can manually re-enter the settings after a firmware update or device reset if your SD card backup isn't available.
+
+---
+
+## Tips
+
+- **All radio changes apply live.** There is no need to reboot after changing frequency, bandwidth, spreading factor, coding rate, or TX power. The radio reconfigures on the fly.
+- **Preset selection by number is faster.** Once you've seen `get presets`, use the index number instead of typing the full name.
+- **Settings are persisted immediately.** Every `set` command writes to flash. If power is lost, your settings are safe.
+- **SD card backup is automatic.** If your T-Deck Pro has an SD card inserted, settings are backed up after every change. On a fresh flash, settings restore automatically from the SD card.
+- **The `get all` command is your friend.** When in doubt, dump everything and check.

TXT & EPUB Reader Guide.md

@@ -12,12 +12,11 @@ This adds a text reader accessible via the **R** key from the home screen.
 - Automatic reading position resume (persisted to SD card)
 - Index files cached to SD for instant re-opens
 - Bookmark indicator (`*`) on files with saved positions
-- Compose mode (`C`) still accessible from within reader
 
 **Key Mapping:**
 | Context | Key | Action |
 |---------|-----|--------|
-| Home screen | R | Open text reader |
+| Home screen | E | Open text reader |
 | File list | W/S | Navigate up/down |
 | File list | Enter | Open selected file |
 | File list | Q | Back to home screen |
@@ -114,4 +113,4 @@ The conversion is handled by three components:
 - Page content is pre-read from SD into a memory buffer during `handleInput()`, then rendered from buffer during `render()` — this avoids SPI bus conflicts during display refresh
 - Layout metrics (chars per line, lines per page) are calculated dynamically from the display driver's font metrics on first entry
 - EPUB conversion runs synchronously in `openBook()` — the e-ink splash screen keeps the user informed while the ESP32 processes the archive
-- ZIP extraction uses the ESP32-S3's hardware-optimised ROM `tinfl` inflate, avoiding external compression library dependencies and the linker conflicts they cause
+- ZIP extraction uses the ESP32-S3's hardware-optimised ROM `tinfl` inflate, avoiding external compression library dependencies and the linker conflicts they cause

Web App Guide.md

@@ -0,0 +1,181 @@
+# Web Reader & IRC - Meck v0.9.5
+
+Press **B** from the home screen to open the web reader. The web reader is
+available on the BLE and 4G variants. It is excluded from the standalone audio
+variant to preserve zero-radio-power design.
+
+The web reader home screen provides access to the **IRC client**, the **URL
+bar**, your **bookmarks**, and browsing **history**. Use **W / S** to navigate
+the list and **Enter** to select an item.
+
+## Web Browser
+
+A text-centric web browser ("reader mode") that fetches pages over WiFi,
+strips HTML to readable text, extracts links as numbered references, and
+paginates content for the e-ink display. Still very much in development, but
+already useful for text-heavy websites.
+
+Includes basic web search via **DuckDuckGo Lite** — type a search query into
+the URL bar and it will be sent to DuckDuckGo.
+
+### EPUB Downloads
+
+If you follow a link to an `.epub` file, it will be saved directly to the
+`/books/` folder on your SD card. You can then read it in the e-book reader
+(press **E** from the home screen).
+
+### Bookmarks
+
+Press **K** while on a page to save a bookmark. Bookmarks appear on the web
+reader home screen below the URL bar. To delete a bookmark, open the browser
+home screen, scroll down to the bookmark, and press **Delete**.
+
+### Cookies & History
+
+Press **X** to clear cookies and browsing history.
+
+---
+
+## IRC Client
+
+The IRC client lets you connect to IRC networks directly from the device. It
+is accessed from the web reader home screen — select **IRC Chat** (the first
+item) and press **Enter**.
+
+If you are not currently connected, the IRC setup screen opens where you can
+configure the server, port, nickname, and channel. If you are already
+connected, you go straight to the chat view.
+
+### IRC Setup
+
+The setup screen has five fields. Use **W / S** to navigate between them and
+press **Enter** to edit a field (type the value, then **Enter** to confirm).
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| Host | IRC server hostname (e.g. `irc.libera.chat`) | — |
+| Port | Server port. Use `6697` for TLS or `6667` for plain | 6697 |
+| Nick | Your IRC nickname (max 16 characters) | — |
+| Channel | Channel to join, including the `#` (e.g. `#meshcore`) | — |
+| Connect | Select and press Enter to connect | — |
+
+TLS is used automatically when the port is 6697. Other ports connect without
+encryption.
+
+Configuration is saved to the SD card at `/web/irc.cfg` and restored on next
+launch, so you only need to enter server details once.
+
+If WiFi is not connected when you press Connect, you'll be taken to the WiFi
+setup screen first.
+
+### IRC Chat View
+
+Once connected and joined to the channel, you'll see messages in a scrollable
+chat view. The channel name and connection status are shown at the top.
+
+| Key | Action |
+|-----|--------|
+| Enter | Start composing a message (type, then Enter to send) |
+| Backspace | Delete last character while composing; exit compose if empty |
+| W / S | Scroll up (older) / down (newer) through messages |
+| X | Disconnect from IRC and return to web reader home |
+| Q | Return to web reader home (connection stays alive in background) |
+
+The IRC connection remains active when you press **Q** to go back to the web
+reader home screen. You'll see the connection status and channel name displayed
+on the IRC Chat line. Select it and press Enter to return to the chat. Press
+**X** from the chat view to disconnect.
+
+The client automatically reconnects if the connection drops (10-second delay
+between attempts) and detects dead connections after 5 minutes of inactivity
+via ping timeout.
+
+Messages are stored in a circular buffer of 64 messages. Older messages are
+discarded as new ones arrive.
+
+---
+
+## Key Bindings
+
+### From Home Screen
+| Key | Action |
+|-----|--------|
+| `b` | Open web reader |
+
+### Web Reader - Home View
+| Key | Action |
+|-----|--------|
+| `w` / `s` | Navigate up/down in IRC / URL bar / bookmarks / history |
+| `Enter` | Select IRC Chat, activate URL bar, or open bookmark/history item |
+| Type | Enter URL (when URL bar is active) |
+| `q` | Exit to firmware home |
+
+### Web Reader - Reading View
+| Key | Action |
+|-----|--------|
+| `w` / `a` | Previous page |
+| `s` / `d` / `Space` | Next page |
+| `l` or `Enter` | Enter link selection (type link number) |
+| `g` | Go to new URL (return to web reader home) |
+| `k` | Bookmark current page |
+| `x` | Clear cookies and history |
+| `q` | Back to web reader home |
+
+### Web Reader - WiFi Setup
+| Key | Action |
+|-----|--------|
+| `w` / `s` | Navigate SSID list |
+| `Enter` | Select SSID / submit password / retry |
+| Type | Enter WiFi password |
+| `q` | Back |
+
+### IRC - Setup View
+| Key | Action |
+|-----|--------|
+| `w` / `s` | Navigate fields (Host / Port / Nick / Channel / Connect) |
+| `Enter` | Edit selected field, or connect (when on Connect button) |
+| Type | Enter field value (when editing) |
+| `Backspace` | Delete last character (when editing) |
+| `q` | Back to web reader home |
+
+### IRC - Chat View
+| Key | Action |
+|-----|--------|
+| `Enter` | Start composing / send message |
+| `Backspace` | Delete character / exit compose if empty |
+| `w` / `s` | Scroll older / newer messages |
+| `x` | Disconnect and return to web reader home |
+| `q` | Back to web reader home (stays connected) |
+
+---
+
+## WiFi
+
+The web reader and IRC client both use WiFi for network access. On first use,
+you'll be taken to the WiFi setup screen to scan for networks and enter a
+password. Credentials are saved to `/web/wifi.cfg` on the SD card and used for
+auto-reconnect on subsequent launches.
+
+On the 4G variant, the web reader currently uses WiFi. A future update will add
+PPP support via the A7682E cellular modem, allowing the browser and IRC to work
+over cellular data without WiFi.
+
+---
+
+## SD Card Structure
+```
+/web/
+  wifi.cfg         - Saved WiFi credentials (auto-reconnect)
+  bookmarks.txt    - One URL per line
+  history.txt      - Recent URLs, newest first
+  irc.cfg          - IRC server/port/nick/channel config
+```
+
+---
+
+## Conditional Compilation
+All web reader code is wrapped in `#ifdef MECK_WEB_READER` guards. The flag is set:
+- **meck_audio_ble**: Yes (`-D MECK_WEB_READER=1`) — WiFi available via BLE radio stack
+- **meck_4g_ble**: Yes (`-D MECK_WEB_READER=1`) — WiFi now, PPP via A7682E in future
+- **meck_4g_standalone**: Yes (`-D MECK_WEB_READER=1`) — WiFi works better without BLE (no teardown needed, more free heap)
+- **meck_audio_standalone**: No — excluded to preserve zero-radio-power design

examples/companion_radio/AbstractUITask.h

@@ -40,14 +40,19 @@ public:
   void enableSerial() { _serial->enable(); }
   void disableSerial() { _serial->disable(); }
   virtual void msgRead(int msgcount) = 0;
-  virtual void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount) = 0;
+  virtual void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount,
+                      const uint8_t* path = nullptr) = 0;
   virtual void notify(UIEventType t = UIEventType::none) = 0;
   virtual void loop() = 0;
   virtual void showAlert(const char* text, int duration_millis) {}
   virtual void forceRefresh() {}
   virtual void addSentChannelMessage(uint8_t channel_idx, const char* sender, const char* text) {}
 
+  // Mark a channel as read when BLE companion app syncs a message
+  virtual void markChannelReadFromBLE(uint8_t channel_idx) {}
+
   // Repeater admin callbacks (from MyMesh)
   virtual void onAdminLoginResult(bool success, uint8_t permissions, uint32_t server_time) {}
   virtual void onAdminCliResponse(const char* from_name, const char* text) {}
+  virtual void onAdminTelemetryResult(const uint8_t* data, uint8_t len) {}
 };

examples/companion_radio/DataStore.cpp

@@ -228,6 +228,19 @@ void DataStore::loadPrefsInt(const char *filename, NodePrefs& _prefs, double& no
     file.read((uint8_t *)&_prefs.gps_enabled, sizeof(_prefs.gps_enabled));                 // 85
     file.read((uint8_t *)&_prefs.gps_interval, sizeof(_prefs.gps_interval));               // 86
     file.read((uint8_t *)&_prefs.autoadd_config, sizeof(_prefs.autoadd_config));           // 87
+    file.read((uint8_t *)&_prefs.utc_offset_hours, sizeof(_prefs.utc_offset_hours));       // 88
+
+    // Fields added later — may not exist in older prefs files
+    if (file.read((uint8_t *)&_prefs.kb_flash_notify, sizeof(_prefs.kb_flash_notify)) != sizeof(_prefs.kb_flash_notify)) {
+      _prefs.kb_flash_notify = 0;  // default OFF for old files
+    }
+    if (file.read((uint8_t *)&_prefs.ringtone_enabled, sizeof(_prefs.ringtone_enabled)) != sizeof(_prefs.ringtone_enabled)) {
+      _prefs.ringtone_enabled = 0;  // default OFF for old files
+    }
+
+    // Clamp booleans to 0/1 in case of garbage
+    if (_prefs.kb_flash_notify > 1) _prefs.kb_flash_notify = 0;
+    if (_prefs.ringtone_enabled > 1) _prefs.ringtone_enabled = 0;
 
     file.close();
   }
@@ -263,14 +276,65 @@ void DataStore::savePrefs(const NodePrefs& _prefs, double node_lat, double node_
     file.write((uint8_t *)&_prefs.gps_enabled, sizeof(_prefs.gps_enabled));                 // 85
     file.write((uint8_t *)&_prefs.gps_interval, sizeof(_prefs.gps_interval));               // 86
     file.write((uint8_t *)&_prefs.autoadd_config, sizeof(_prefs.autoadd_config));           // 87
+    file.write((uint8_t *)&_prefs.utc_offset_hours, sizeof(_prefs.utc_offset_hours));     // 88
+    file.write((uint8_t *)&_prefs.kb_flash_notify, sizeof(_prefs.kb_flash_notify));      // 89
+    file.write((uint8_t *)&_prefs.ringtone_enabled, sizeof(_prefs.ringtone_enabled));    // 90
 
     file.close();
   }
 }
 
 void DataStore::loadContacts(DataStoreHost* host) {
-File file = openRead(_getContactsChannelsFS(), "/contacts3");
+  FILESYSTEM* fs = _getContactsChannelsFS();
+
+  // --- Crash recovery ---
+  // If /contacts3 is missing but /contacts3.tmp exists, a crash occurred
+  // after removing the original but before the rename completed.
+  // The .tmp file has the valid data — promote it.
+  if (!fs->exists("/contacts3") && fs->exists("/contacts3.tmp")) {
+    Serial.println("DataStore: recovering contacts from .tmp file");
+    fs->rename("/contacts3.tmp", "/contacts3");
+  }
+  // If both exist, a crash occurred before the old file was removed.
+  // The original /contacts3 is still valid — just clean up the orphan.
+  if (fs->exists("/contacts3.tmp")) {
+    fs->remove("/contacts3.tmp");
+  }
+
+  File file = openRead(fs, "/contacts3");
     if (file) {
+      // --- Truncation guard ---
+      // If the file is smaller than one full contact record (152 bytes),
+      // it was truncated by a crash/brown-out. Discard it and try the
+      // .tmp backup if available.
+      size_t fsize = file.size();
+      if (fsize > 0 && fsize < 152) {
+        Serial.printf("DataStore: contacts3 truncated (%d bytes < 152), discarding\n", (int)fsize);
+        file.close();
+        fs->remove("/contacts3");
+        if (fs->exists("/contacts3.tmp")) {
+          File tmp = openRead(fs, "/contacts3.tmp");
+          if (tmp && tmp.size() >= 152) {
+            Serial.println("DataStore: recovering from .tmp after truncation");
+            tmp.close();
+            fs->rename("/contacts3.tmp", "/contacts3");
+            file = openRead(fs, "/contacts3");
+            if (!file) return;  // give up
+          } else {
+            if (tmp) tmp.close();
+            Serial.println("DataStore: no valid contacts backup — starting fresh");
+            return;
+          }
+        } else {
+          Serial.println("DataStore: no .tmp backup — starting fresh");
+          return;
+        }
+      } else if (fsize == 0) {
+        // Empty file — nothing to load
+        file.close();
+        return;
+      }
+
       bool full = false;
       while (!full) {
         ContactInfo c;
@@ -300,36 +364,86 @@ File file = openRead(_getContactsChannelsFS(), "/contacts3");
 }
 
 void DataStore::saveContacts(DataStoreHost* host) {
-  File file = openWrite(_getContactsChannelsFS(), "/contacts3");
-  if (file) {
-    uint32_t idx = 0;
-    ContactInfo c;
-    uint8_t unused = 0;
+  FILESYSTEM* fs = _getContactsChannelsFS();
+  const char* finalPath = "/contacts3";
+  const char* tmpPath   = "/contacts3.tmp";
 
-    while (host->getContactForSave(idx, c)) {
-      bool success = (file.write(c.id.pub_key, 32) == 32);
-      success = success && (file.write((uint8_t *)&c.name, 32) == 32);
-      success = success && (file.write(&c.type, 1) == 1);
-      success = success && (file.write(&c.flags, 1) == 1);
-      success = success && (file.write(&unused, 1) == 1);
-      success = success && (file.write((uint8_t *)&c.sync_since, 4) == 4);
-      success = success && (file.write((uint8_t *)&c.out_path_len, 1) == 1);
-      success = success && (file.write((uint8_t *)&c.last_advert_timestamp, 4) == 4);
-      success = success && (file.write(c.out_path, 64) == 64);
-      success = success && (file.write((uint8_t *)&c.lastmod, 4) == 4);
-      success = success && (file.write((uint8_t *)&c.gps_lat, 4) == 4);
-      success = success && (file.write((uint8_t *)&c.gps_lon, 4) == 4);
+  // --- Step 1: Write all contacts to a temporary file ---
+  File file = openWrite(fs, tmpPath);
+  if (!file) {
+    Serial.println("DataStore: saveContacts FAILED — cannot open tmp file");
+    return;
+  }
 
-      if (!success) break; // write failed
+  uint32_t idx = 0;
+  ContactInfo c;
+  uint8_t unused = 0;
+  uint32_t recordsWritten = 0;
+  bool writeOk = true;
 
-      idx++;  // advance to next contact
+  while (host->getContactForSave(idx, c)) {
+    bool success = (file.write(c.id.pub_key, 32) == 32);
+    success = success && (file.write((uint8_t *)&c.name, 32) == 32);
+    success = success && (file.write(&c.type, 1) == 1);
+    success = success && (file.write(&c.flags, 1) == 1);
+    success = success && (file.write(&unused, 1) == 1);
+    success = success && (file.write((uint8_t *)&c.sync_since, 4) == 4);
+    success = success && (file.write((uint8_t *)&c.out_path_len, 1) == 1);
+    success = success && (file.write((uint8_t *)&c.last_advert_timestamp, 4) == 4);
+    success = success && (file.write(c.out_path, 64) == 64);
+    success = success && (file.write((uint8_t *)&c.lastmod, 4) == 4);
+    success = success && (file.write((uint8_t *)&c.gps_lat, 4) == 4);
+    success = success && (file.write((uint8_t *)&c.gps_lon, 4) == 4);
+
+    if (!success) {
+      writeOk = false;
+      Serial.printf("DataStore: saveContacts write error at record %d\n", idx);
+      break;
     }
-    file.close();
+
+    recordsWritten++;
+    idx++;
+  }
+
+  file.close();
+
+  // --- Step 2: Verify the write completed ---
+  // Reopen read-only to get true on-disk size (SPIFFS file.size() is unreliable before close)
+  size_t expectedBytes = recordsWritten * 152;  // 152 bytes per contact record
+  File verify = openRead(fs, tmpPath);
+  size_t bytesWritten = verify ? verify.size() : 0;
+  if (verify) verify.close();
+
+  if (!writeOk || bytesWritten != expectedBytes) {
+    Serial.printf("DataStore: saveContacts ABORTED — wrote %d bytes, expected %d (%d records)\n",
+                  (int)bytesWritten, (int)expectedBytes, recordsWritten);
+    fs->remove(tmpPath);  // Clean up failed tmp file
+    return;  // Original /contacts3 is untouched
+  }
+
+  // --- Step 3: Replace original with verified temp file ---
+  fs->remove(finalPath);
+  if (fs->rename(tmpPath, finalPath)) {
+    Serial.printf("DataStore: saved %d contacts (%d bytes)\n", recordsWritten, (int)bytesWritten);
+  } else {
+    // Rename failed — tmp file still has the good data
+    Serial.println("DataStore: rename failed, tmp file preserved");
   }
 }
 
 void DataStore::loadChannels(DataStoreHost* host) {
-    File file = openRead(_getContactsChannelsFS(), "/channels2");
+    FILESYSTEM* fs = _getContactsChannelsFS();
+
+    // Crash recovery (same pattern as contacts)
+    if (!fs->exists("/channels2") && fs->exists("/channels2.tmp")) {
+      Serial.println("DataStore: recovering channels from .tmp file");
+      fs->rename("/channels2.tmp", "/channels2");
+    }
+    if (fs->exists("/channels2.tmp")) {
+      fs->remove("/channels2.tmp");
+    }
+
+    File file = openRead(fs, "/channels2");
     if (file) {
       bool full = false;
       uint8_t channel_idx = 0;
@@ -354,22 +468,54 @@ void DataStore::loadChannels(DataStoreHost* host) {
 }
 
 void DataStore::saveChannels(DataStoreHost* host) {
-  File file = openWrite(_getContactsChannelsFS(), "/channels2");
-  if (file) {
-    uint8_t channel_idx = 0;
-    ChannelDetails ch;
-    uint8_t unused[4];
-    memset(unused, 0, 4);
+  FILESYSTEM* fs = _getContactsChannelsFS();
+  const char* finalPath = "/channels2";
+  const char* tmpPath   = "/channels2.tmp";
 
-    while (host->getChannelForSave(channel_idx, ch)) {
-      bool success = (file.write(unused, 4) == 4);
-      success = success && (file.write((uint8_t *)ch.name, 32) == 32);
-      success = success && (file.write((uint8_t *)ch.channel.secret, 32) == 32);
+  File file = openWrite(fs, tmpPath);
+  if (!file) {
+    Serial.println("DataStore: saveChannels FAILED — cannot open tmp file");
+    return;
+  }
 
-      if (!success) break; // write failed
-      channel_idx++;
+  uint8_t channel_idx = 0;
+  ChannelDetails ch;
+  uint8_t unused[4];
+  memset(unused, 0, 4);
+  bool writeOk = true;
+
+  while (host->getChannelForSave(channel_idx, ch)) {
+    bool success = (file.write(unused, 4) == 4);
+    success = success && (file.write((uint8_t *)ch.name, 32) == 32);
+    success = success && (file.write((uint8_t *)ch.channel.secret, 32) == 32);
+
+    if (!success) {
+      writeOk = false;
+      Serial.printf("DataStore: saveChannels write error at channel %d\n", channel_idx);
+      break;
     }
-    file.close();
+    channel_idx++;
+  }
+
+  file.close();
+
+  // Reopen read-only to get true on-disk size (SPIFFS file.size() is unreliable before close)
+  size_t expectedBytes = channel_idx * 68;  // 4 + 32 + 32 = 68 bytes per channel
+  File verify = openRead(fs, tmpPath);
+  size_t bytesWritten = verify ? verify.size() : 0;
+  if (verify) verify.close();
+  if (!writeOk || bytesWritten != expectedBytes) {
+    Serial.printf("DataStore: saveChannels ABORTED — wrote %d bytes, expected %d\n",
+                  (int)bytesWritten, (int)expectedBytes);
+    fs->remove(tmpPath);
+    return;
+  }
+
+  fs->remove(finalPath);
+  if (fs->rename(tmpPath, finalPath)) {
+    Serial.printf("DataStore: saved %d channels (%d bytes)\n", channel_idx, (int)bytesWritten);
+  } else {
+    Serial.println("DataStore: channels rename failed, tmp file preserved");
   }
 }
 
@@ -598,4 +744,4 @@ bool DataStore::putBlobByKey(const uint8_t key[], int key_len, const uint8_t src
   }
   return false; // error
 }
-#endif
+#endif

examples/companion_radio/MyMesh.cpp

@@ -2,6 +2,11 @@
 
 #include <Arduino.h> // needed for PlatformIO
 #include <Mesh.h>
+#include "RadioPresets.h"        // Shared radio presets (serial CLI + settings screen)
+
+#ifdef HAS_4G_MODEM
+  #include "ModemManager.h"      // Serial CLI modem commands
+#endif
 
 #define CMD_APP_START                 1
 #define CMD_SEND_TXT_MSG              2
@@ -53,6 +58,10 @@
 #define CMD_SET_FLOOD_SCOPE           54   // v8+
 #define CMD_SEND_CONTROL_DATA         55   // v8+
 #define CMD_GET_STATS                 56   // v8+, second byte is stats type
+
+// Control data sub-types for active node discovery
+#define CTL_TYPE_NODE_DISCOVER_REQ    0x80
+#define CTL_TYPE_NODE_DISCOVER_RESP   0x90
 #define CMD_SEND_ANON_REQ             57
 #define CMD_SET_AUTOADD_CONFIG        58
 #define CMD_GET_AUTOADD_CONFIG        59
@@ -357,6 +366,32 @@ void MyMesh::onDiscoveredContact(ContactInfo &contact, bool is_new, uint8_t path
     memcpy(p->path, path, p->path_len);
   }
 
+  // Buffer for on-device discovery UI
+  if (_discoveryActive && _discoveredCount < MAX_DISCOVERED_NODES) {
+    bool dup = false;
+    for (int i = 0; i < _discoveredCount; i++) {
+      if (contact.id.matches(_discovered[i].contact.id)) {
+        // Update existing entry with fresher data
+        _discovered[i].contact = contact;
+        _discovered[i].path_len = path_len;
+        _discovered[i].already_in_contacts = !is_new;
+        // Preserve snr if already set by active discovery response
+        dup = true;
+        Serial.printf("[Discovery] Updated: %s (hops=%d)\n", contact.name, path_len);
+        break;
+      }
+    }
+    if (!dup) {
+      _discovered[_discoveredCount].contact = contact;
+      _discovered[_discoveredCount].path_len = path_len;
+      _discovered[_discoveredCount].snr = 0;  // no SNR from passive advert
+      _discovered[_discoveredCount].already_in_contacts = !is_new;
+      _discoveredCount++;
+      Serial.printf("[Discovery] Found: %s (hops=%d, is_new=%d, total=%d)\n",
+                    contact.name, path_len, is_new, _discoveredCount);
+    }
+  }
+
   if (!is_new) dirty_contacts_expiry = futureMillis(LAZY_CONTACTS_WRITE_DELAY); // only schedule lazy write for contacts that are in contacts[]
 }
 
@@ -439,7 +474,8 @@ void MyMesh::queueMessage(const ContactInfo &from, uint8_t txt_type, mesh::Packe
   // we only want to show text messages on display, not cli data
   bool should_display = txt_type == TXT_TYPE_PLAIN || txt_type == TXT_TYPE_SIGNED_PLAIN;
   if (should_display && _ui) {
-    _ui->newMsg(path_len, from.name, text, offline_queue_len);
+    const uint8_t* msg_path = (pkt->isRouteFlood() && pkt->path_len > 0) ? pkt->path : nullptr;
+    _ui->newMsg(path_len, from.name, text, offline_queue_len, msg_path);
     if (!_prefs.buzzer_quiet) _ui->notify(UIEventType::contactMessage); //buzz if enabled
   }
 #endif
@@ -524,9 +560,9 @@ void MyMesh::onCommandDataRecv(const ContactInfo &from, mesh::Packet *pkt, uint3
   markConnectionActive(from); // in case this is from a server, and we have a connection
   queueMessage(from, TXT_TYPE_CLI_DATA, pkt, sender_timestamp, NULL, 0, text);
 
+  // Forward CLI response to UI admin screen if admin session is active
 #ifdef DISPLAY_CLASS
-  // Route CLI responses to admin UI if active
-  if (_ui && _admin_contact_idx >= 0) {
+  if (_admin_contact_idx >= 0 && _ui) {
     _ui->onAdminCliResponse(from.name, text);
   }
 #endif
@@ -581,7 +617,8 @@ void MyMesh::onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packe
     channel_name = channel_details.name;
   }
   if (_ui) {
-    _ui->newMsg(path_len, channel_name, text, offline_queue_len);
+    const uint8_t* msg_path = (pkt->isRouteFlood() && pkt->path_len > 0) ? pkt->path : nullptr;
+    _ui->newMsg(path_len, channel_name, text, offline_queue_len, msg_path);
     if (!_prefs.buzzer_quiet) _ui->notify(UIEventType::channelMessage); //buzz if enabled
   }
 #endif
@@ -666,7 +703,6 @@ bool MyMesh::uiLoginToRepeater(uint32_t contact_idx, const char* password) {
 
   uint32_t est_timeout;
   int result = sendLogin(*recipient, password, est_timeout);
-
   if (result == MSG_SEND_FAILED) {
     MESH_DEBUG_PRINTLN("UI: Admin login send failed to %s", recipient->name);
     return false;
@@ -692,7 +728,6 @@ bool MyMesh::uiSendCliCommand(uint32_t contact_idx, const char* command) {
   uint32_t timestamp = getRTCClock()->getCurrentTimeUnique();
   uint32_t est_timeout;
   int result = sendCommandData(*recipient, timestamp, 0, command, est_timeout);
-
   if (result == MSG_SEND_FAILED) {
     MESH_DEBUG_PRINTLN("UI: CLI command send failed to %s: %s", recipient->name, command);
     return false;
@@ -706,6 +741,29 @@ bool MyMesh::uiSendCliCommand(uint32_t contact_idx, const char* command) {
   return true;
 }
 
+bool MyMesh::uiSendTelemetryRequest(uint32_t contact_idx) {
+  ContactInfo contact;
+  if (!getContactByIdx(contact_idx, contact)) return false;
+
+  ContactInfo* recipient = lookupContactByPubKey(contact.id.pub_key, PUB_KEY_SIZE);
+  if (!recipient) return false;
+
+  uint32_t tag, est_timeout;
+  int result = sendRequest(*recipient, REQ_TYPE_GET_TELEMETRY_DATA, tag, est_timeout);
+  if (result == MSG_SEND_FAILED) {
+    MESH_DEBUG_PRINTLN("UI: Telemetry request send failed to %s", recipient->name);
+    return false;
+  }
+
+  clearPendingReqs();
+  pending_telemetry = tag;
+
+  MESH_DEBUG_PRINTLN("UI: Telemetry request sent to %s (%s), timeout=%dms",
+                     recipient->name, result == MSG_SEND_SENT_FLOOD ? "flood" : "direct",
+                     est_timeout);
+  return true;
+}
+
 uint8_t MyMesh::onContactRequest(const ContactInfo &contact, uint32_t sender_timestamp, const uint8_t *data,
                                  uint8_t len, uint8_t *reply) {
   if (data[0] == REQ_TYPE_GET_TELEMETRY_DATA) {
@@ -765,10 +823,10 @@ void MyMesh::onContactResponse(const ContactInfo &contact, const uint8_t *data,
       memcpy(&out_frame[i], contact.id.pub_key, 6);
       i += 6;                                     // pub_key_prefix
 
-#ifdef DISPLAY_CLASS
+      #ifdef DISPLAY_CLASS
       // Notify UI of successful legacy login
       if (_ui) _ui->onAdminLoginResult(true, 0, tag);
-#endif
+      #endif
     } else if (data[4] == RESP_SERVER_LOGIN_OK) { // new login response
       uint16_t keep_alive_secs = ((uint16_t)data[5]) * 16;
       if (keep_alive_secs > 0) {
@@ -783,20 +841,20 @@ void MyMesh::onContactResponse(const ContactInfo &contact, const uint8_t *data,
       out_frame[i++] = data[7]; // NEW (v7): ACL permissions
       out_frame[i++] = data[12]; // FIRMWARE_VER_LEVEL
 
-#ifdef DISPLAY_CLASS
+      #ifdef DISPLAY_CLASS
       // Notify UI of successful login
       if (_ui) _ui->onAdminLoginResult(true, data[6], tag);
-#endif
+      #endif
     } else {
       out_frame[i++] = PUSH_CODE_LOGIN_FAIL;
       out_frame[i++] = 0; // reserved
       memcpy(&out_frame[i], contact.id.pub_key, 6);
       i += 6; // pub_key_prefix
 
-#ifdef DISPLAY_CLASS
+      #ifdef DISPLAY_CLASS
       // Notify UI of login failure
       if (_ui) _ui->onAdminLoginResult(false, 0, 0);
-#endif
+      #endif
     }
     _serial->writeFrame(out_frame, i);
   } else if (len > 4 && // check for status response
@@ -816,6 +874,7 @@ void MyMesh::onContactResponse(const ContactInfo &contact, const uint8_t *data,
     _serial->writeFrame(out_frame, i);
   } else if (len > 4 && tag == pending_telemetry) {  // check for matching response tag
     pending_telemetry = 0;
+    MESH_DEBUG_PRINTLN("Telemetry response received from %s, len=%d", contact.name, len);
 
     int i = 0;
     out_frame[i++] = PUSH_CODE_TELEMETRY_RESPONSE;
@@ -825,6 +884,11 @@ void MyMesh::onContactResponse(const ContactInfo &contact, const uint8_t *data,
     memcpy(&out_frame[i], &data[4], len - 4);
     i += (len - 4);
     _serial->writeFrame(out_frame, i);
+
+    #ifdef DISPLAY_CLASS
+    // Route telemetry data to UI (LPP buffer after the 4-byte tag)
+    if (_ui) _ui->onAdminTelemetryResult(&data[4], len - 4);
+    #endif
   } else if (len > 4 && tag == pending_req) {  // check for matching response tag
     pending_req = 0;
 
@@ -873,6 +937,62 @@ bool MyMesh::onContactPathRecv(ContactInfo& contact, uint8_t* in_path, uint8_t i
 }
 
 void MyMesh::onControlDataRecv(mesh::Packet *packet) {
+  // --- Active discovery response interception ---
+  if (_discoveryActive && packet->payload_len >= 6) {
+    uint8_t resp_type = packet->payload[0] & 0xF0;
+    if (resp_type == CTL_TYPE_NODE_DISCOVER_RESP) {
+      uint8_t node_type = packet->payload[0] & 0x0F;
+      int8_t snr_scaled = (int8_t)packet->payload[1];   // SNR × 4 (how well repeater heard us)
+      uint32_t tag;
+      memcpy(&tag, &packet->payload[2], 4);
+
+      // Validate: tag must match ours AND payload must include full 32-byte pubkey
+      if (tag == _discoveryTag && packet->payload_len >= 6 + PUB_KEY_SIZE) {
+        const uint8_t* pubkey = &packet->payload[6];
+
+        // Dedup check against existing buffer entries (pre-seeded or earlier responses)
+        for (int i = 0; i < _discoveredCount; i++) {
+          if (_discovered[i].contact.id.matches(pubkey)) {
+            // Already in buffer — update SNR (active discovery data is fresher)
+            _discovered[i].snr = snr_scaled;
+            Serial.printf("[Discovery] Updated SNR for %s: %d\n",
+                          _discovered[i].contact.name, snr_scaled);
+            return;
+          }
+        }
+
+        // New node — add if room
+        if (_discoveredCount < MAX_DISCOVERED_NODES) {
+          DiscoveredNode& node = _discovered[_discoveredCount];
+          memset(&node.contact, 0, sizeof(ContactInfo));
+          memcpy(node.contact.id.pub_key, pubkey, PUB_KEY_SIZE);
+          node.contact.type = node_type;
+          node.snr = snr_scaled;
+          node.path_len = packet->path_len;
+
+          // Try to resolve name from contacts table
+          ContactInfo* existing = lookupContactByPubKey(pubkey, PUB_KEY_SIZE);
+          if (existing) {
+            strncpy(node.contact.name, existing->name, sizeof(node.contact.name) - 1);
+            node.already_in_contacts = true;
+          } else {
+            // Show hex prefix as placeholder name
+            snprintf(node.contact.name, sizeof(node.contact.name),
+                     "%02X%02X%02X%02X",
+                     pubkey[0], pubkey[1], pubkey[2], pubkey[3]);
+            node.already_in_contacts = false;
+          }
+
+          _discoveredCount++;
+          Serial.printf("[Discovery] Active response: %s type=%d snr=%d hops=%d (total=%d)\n",
+                        node.contact.name, node_type, snr_scaled, packet->path_len, _discoveredCount);
+        }
+      }
+      return;  // consumed — don't forward discovery responses to BLE
+    }
+  }
+
+  // --- Original BLE forwarding for non-discovery control data ---
   if (packet->payload_len + 4 > sizeof(out_frame)) {
     MESH_DEBUG_PRINTLN("onControlDataRecv(), payload_len too long: %d", packet->payload_len);
     return;
@@ -969,6 +1089,10 @@ MyMesh::MyMesh(mesh::Radio &radio, mesh::RNG &rng, mesh::RTCClock &rtc, SimpleMe
   memset(_sent_track, 0, sizeof(_sent_track));
   _sent_track_idx = 0;
   _admin_contact_idx = -1;
+  _discoveredCount = 0;
+  _discoveryActive = false;
+  _discoveryTimeout = 0;
+  _discoveryTag = 0;
 
   // defaults
   memset(&_prefs, 0, sizeof(_prefs));
@@ -1022,6 +1146,7 @@ void MyMesh::begin(bool has_display) {
   _prefs.buzzer_quiet = constrain(_prefs.buzzer_quiet, 0, 1);  // Ensure boolean 0 or 1
   _prefs.gps_enabled = constrain(_prefs.gps_enabled, 0, 1);  // Ensure boolean 0 or 1
   _prefs.gps_interval = constrain(_prefs.gps_interval, 0, 86400);  // Max 24 hours
+  _prefs.utc_offset_hours = constrain(_prefs.utc_offset_hours, -12, 14);  // Valid timezone range
 
 #ifdef BLE_PIN_CODE // 123456 by default
   if (_prefs.ble_pin == 0) {
@@ -1042,6 +1167,7 @@ void MyMesh::begin(bool has_display) {
   _active_ble_pin = 0;
 #endif
 
+  initContacts();    // allocate contacts array from PSRAM (deferred from constructor)
   resetContacts();
   _store->loadContacts(this);
   bootstrapRTCfromContacts();
@@ -1182,6 +1308,8 @@ void MyMesh::handleCmdFrame(size_t len) {
     memcpy(&msg_timestamp, &cmd_frame[i], 4);
     i += 4;
     const char *text = (char *)&cmd_frame[i];
+    int text_len = len - i;
+    cmd_frame[len] = '\0';  // Null-terminate for C string use
 
     if (txt_type != TXT_TYPE_PLAIN) {
       writeErrFrame(ERR_CODE_UNSUPPORTED_CMD);
@@ -1190,6 +1318,11 @@ void MyMesh::handleCmdFrame(size_t len) {
       bool success = getChannel(channel_idx, channel);
       if (success && sendGroupMessage(msg_timestamp, channel.channel, _prefs.node_name, text, len - i)) {
         writeOKFrame();
+        #ifdef DISPLAY_CLASS
+        if (_ui) {
+          _ui->addSentChannelMessage(channel_idx, _prefs.node_name, text);
+        }
+#endif
       } else {
         writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx
       }
@@ -1363,6 +1496,7 @@ void MyMesh::handleCmdFrame(size_t len) {
     }
   } else if (cmd_frame[0] == CMD_IMPORT_CONTACT && len > 2 + 32 + 64) {
     if (importContact(&cmd_frame[1], len - 1)) {
+      dirty_contacts_expiry = futureMillis(LAZY_CONTACTS_WRITE_DELAY);
       writeOKFrame();
     } else {
       writeErrFrame(ERR_CODE_ILLEGAL_ARG);
@@ -1372,7 +1506,19 @@ void MyMesh::handleCmdFrame(size_t len) {
     if ((out_len = getFromOfflineQueue(out_frame)) > 0) {
       _serial->writeFrame(out_frame, out_len);
 #ifdef DISPLAY_CLASS
-      if (_ui) _ui->msgRead(offline_queue_len);
+      if (_ui) {
+        _ui->msgRead(offline_queue_len);
+
+        // Mark channel as read when BLE companion app syncs the message.
+        // Frame layout V3: [resp_code][snr][res1][res2][channel_idx][path_len]...
+        // Frame layout V1: [resp_code][channel_idx][path_len]...
+        bool is_v3_ch = (out_frame[0] == RESP_CODE_CHANNEL_MSG_RECV_V3);
+        bool is_old_ch = (out_frame[0] == RESP_CODE_CHANNEL_MSG_RECV);
+        if (is_v3_ch || is_old_ch) {
+          uint8_t ch_idx = is_v3_ch ? out_frame[4] : out_frame[1];
+          _ui->markChannelReadFromBLE(ch_idx);
+        }
+      }
 #endif
     } else {
       out_frame[0] = RESP_CODE_NO_MORE_MESSAGES;
@@ -1805,6 +1951,12 @@ void MyMesh::handleCmdFrame(size_t len) {
           savePrefs();
         }
         #endif
+        // UTC offset for local clock display (works regardless of GPS)
+        if (strcmp(sp, "utc_offset") == 0) {
+          int offset = atoi(np);
+          _prefs.utc_offset_hours = constrain(offset, -12, 14);
+          savePrefs();
+        }
         writeOKFrame();
       } else {
         writeErrFrame(ERR_CODE_ILLEGAL_ARG);
@@ -1947,15 +2099,447 @@ void MyMesh::checkCLIRescueCmd() {
   if (len > 0 && cli_command[len - 1] == '\r') {  // received complete line
     cli_command[len - 1] = 0;  // replace newline with C string null terminator
 
-    if (memcmp(cli_command, "set ", 4) == 0) {
+    // =====================================================================
+    // GET commands — read settings
+    // =====================================================================
+    if (memcmp(cli_command, "get ", 4) == 0) {
+      const char* key = &cli_command[4];
+
+      if (strcmp(key, "name") == 0) {
+        Serial.printf("  > %s\n", _prefs.node_name);
+      } else if (strcmp(key, "freq") == 0) {
+        Serial.printf("  > %.3f\n", _prefs.freq);
+      } else if (strcmp(key, "bw") == 0) {
+        Serial.printf("  > %.1f\n", _prefs.bw);
+      } else if (strcmp(key, "sf") == 0) {
+        Serial.printf("  > %d\n", _prefs.sf);
+      } else if (strcmp(key, "cr") == 0) {
+        Serial.printf("  > %d\n", _prefs.cr);
+      } else if (strcmp(key, "tx") == 0) {
+        Serial.printf("  > %d\n", _prefs.tx_power_dbm);
+      } else if (strcmp(key, "utc") == 0) {
+        Serial.printf("  > %d\n", _prefs.utc_offset_hours);
+      } else if (strcmp(key, "notify") == 0) {
+        Serial.printf("  > %s\n", _prefs.kb_flash_notify ? "on" : "off");
+      } else if (strcmp(key, "gps") == 0) {
+        Serial.printf("  > %s (interval: %ds)\n",
+            _prefs.gps_enabled ? "on" : "off", _prefs.gps_interval);
+      } else if (strcmp(key, "pin") == 0) {
+        Serial.printf("  > %06d\n", _prefs.ble_pin);
+      } else if (strcmp(key, "radio") == 0) {
+        Serial.printf("  > freq=%.3f bw=%.1f sf=%d cr=%d tx=%d\n",
+            _prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr, _prefs.tx_power_dbm);
+      } else if (strcmp(key, "pubkey") == 0) {
+        char hex[PUB_KEY_SIZE * 2 + 1];
+        mesh::Utils::toHex(hex, self_id.pub_key, PUB_KEY_SIZE);
+        Serial.printf("  > %s\n", hex);
+      } else if (strcmp(key, "firmware") == 0) {
+        Serial.printf("  > %s\n", FIRMWARE_VERSION);
+      } else if (strcmp(key, "channels") == 0) {
+        bool found = false;
+        for (uint8_t i = 0; i < MAX_GROUP_CHANNELS; i++) {
+          ChannelDetails ch;
+          if (getChannel(i, ch) && ch.name[0] != '\0') {
+            Serial.printf("  [%d] %s\n", i, ch.name);
+            found = true;
+          } else {
+            break;
+          }
+        }
+        if (!found) Serial.println("  (no channels)");
+      } else if (strcmp(key, "presets") == 0) {
+        Serial.println("  Available radio presets:");
+        for (int i = 0; i < (int)NUM_RADIO_PRESETS; i++) {
+          Serial.printf("    %2d  %-30s  %.3f MHz  BW%.1f  SF%d  CR%d  TX%d\n",
+              i, RADIO_PRESETS[i].name, RADIO_PRESETS[i].freq,
+              RADIO_PRESETS[i].bw, RADIO_PRESETS[i].sf,
+              RADIO_PRESETS[i].cr, RADIO_PRESETS[i].tx_power);
+        }
+#ifdef HAS_4G_MODEM
+      } else if (strcmp(key, "modem") == 0) {
+        Serial.printf("  > %s\n", ModemManager::loadEnabledConfig() ? "on" : "off");
+      } else if (strcmp(key, "apn") == 0) {
+        Serial.printf("  > %s\n", modemManager.getAPN());
+      } else if (strcmp(key, "imei") == 0) {
+        Serial.printf("  > %s\n", modemManager.getIMEI());
+#endif
+      } else if (strcmp(key, "all") == 0) {
+        Serial.println("  === Meck Device Settings ===");
+        Serial.printf("  name:       %s\n", _prefs.node_name);
+        Serial.printf("  freq:       %.3f\n", _prefs.freq);
+        Serial.printf("  bw:         %.1f\n", _prefs.bw);
+        Serial.printf("  sf:         %d\n", _prefs.sf);
+        Serial.printf("  cr:         %d\n", _prefs.cr);
+        Serial.printf("  tx:         %d\n", _prefs.tx_power_dbm);
+        Serial.printf("  utc:        %d\n", _prefs.utc_offset_hours);
+        Serial.printf("  notify:     %s\n", _prefs.kb_flash_notify ? "on" : "off");
+        Serial.printf("  gps:        %s (interval: %ds)\n",
+            _prefs.gps_enabled ? "on" : "off", _prefs.gps_interval);
+        Serial.printf("  pin:        %06d\n", _prefs.ble_pin);
+#ifdef HAS_4G_MODEM
+        Serial.printf("  modem:      %s\n", ModemManager::loadEnabledConfig() ? "on" : "off");
+        Serial.printf("  apn:        %s\n", modemManager.getAPN());
+        Serial.printf("  imei:       %s\n", modemManager.getIMEI());
+#endif
+        // Detect current preset
+        bool presetFound = false;
+        for (int i = 0; i < (int)NUM_RADIO_PRESETS; i++) {
+          if (_prefs.freq == RADIO_PRESETS[i].freq && _prefs.bw == RADIO_PRESETS[i].bw &&
+              _prefs.sf == RADIO_PRESETS[i].sf && _prefs.cr == RADIO_PRESETS[i].cr) {
+            Serial.printf("  preset:     %s\n", RADIO_PRESETS[i].name);
+            presetFound = true;
+            break;
+          }
+        }
+        if (!presetFound) Serial.println("  preset:     (custom)");
+        Serial.printf("  firmware:   %s\n", FIRMWARE_VERSION);
+        char hex[PUB_KEY_SIZE * 2 + 1];
+        mesh::Utils::toHex(hex, self_id.pub_key, PUB_KEY_SIZE);
+        Serial.printf("  pubkey:     %s\n", hex);
+        // List channels
+        Serial.println("  channels:");
+        bool chFound = false;
+        for (uint8_t i = 0; i < MAX_GROUP_CHANNELS; i++) {
+          ChannelDetails ch;
+          if (getChannel(i, ch) && ch.name[0] != '\0') {
+            Serial.printf("    [%d] %s\n", i, ch.name);
+            chFound = true;
+          } else {
+            break;
+          }
+        }
+        if (!chFound) Serial.println("    (none)");
+      } else {
+        Serial.printf("  Error: unknown key '%s' (try 'help')\n", key);
+      }
+
+    // =====================================================================
+    // SET commands — write settings
+    // =====================================================================
+    } else if (memcmp(cli_command, "set ", 4) == 0) {
       const char* config = &cli_command[4];
-      if (memcmp(config, "pin ", 4) == 0) {
+
+      if (memcmp(config, "name ", 5) == 0) {
+        const char* val = &config[5];
+        // Validate name (same rules as CommonCLI)
+        bool valid = true;
+        const char* p = val;
+        while (*p) {
+          if (*p == '[' || *p == ']' || *p == '/' || *p == '\\' ||
+              *p == ':' || *p == ',' || *p == '?' || *p == '*') {
+            valid = false;
+            break;
+          }
+          p++;
+        }
+        if (valid && strlen(val) > 0) {
+          strncpy(_prefs.node_name, val, sizeof(_prefs.node_name) - 1);
+          _prefs.node_name[sizeof(_prefs.node_name) - 1] = '\0';
+          savePrefs();
+          Serial.printf("  > name = %s\n", _prefs.node_name);
+        } else {
+          Serial.println("  Error: invalid name (no []/:,?* chars)");
+        }
+
+      } else if (memcmp(config, "freq ", 5) == 0) {
+        float f = atof(&config[5]);
+        if (f >= 400.0f && f <= 928.0f) {
+          _prefs.freq = f;
+          savePrefs();
+          radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+          Serial.printf("  > freq = %.3f (applied)\n", _prefs.freq);
+        } else {
+          Serial.println("  Error: freq out of range (400-928)");
+        }
+
+      } else if (memcmp(config, "bw ", 3) == 0) {
+        float bw = atof(&config[3]);
+        if (bw >= 7.8f && bw <= 500.0f) {
+          _prefs.bw = bw;
+          savePrefs();
+          radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+          Serial.printf("  > bw = %.1f (applied)\n", _prefs.bw);
+        } else {
+          Serial.println("  Error: bw out of range (7.8-500)");
+        }
+
+      } else if (memcmp(config, "sf ", 3) == 0) {
+        int sf = atoi(&config[3]);
+        if (sf >= 5 && sf <= 12) {
+          _prefs.sf = (uint8_t)sf;
+          savePrefs();
+          radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+          Serial.printf("  > sf = %d (applied)\n", _prefs.sf);
+        } else {
+          Serial.println("  Error: sf out of range (5-12)");
+        }
+
+      } else if (memcmp(config, "cr ", 3) == 0) {
+        int cr = atoi(&config[3]);
+        if (cr >= 5 && cr <= 8) {
+          _prefs.cr = (uint8_t)cr;
+          savePrefs();
+          radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+          Serial.printf("  > cr = %d (applied)\n", _prefs.cr);
+        } else {
+          Serial.println("  Error: cr out of range (5-8)");
+        }
+
+      } else if (memcmp(config, "tx ", 3) == 0) {
+        int tx = atoi(&config[3]);
+        if (tx >= 1 && tx <= MAX_LORA_TX_POWER) {
+          _prefs.tx_power_dbm = (uint8_t)tx;
+          savePrefs();
+          radio_set_tx_power(_prefs.tx_power_dbm);
+          Serial.printf("  > tx = %d (applied)\n", _prefs.tx_power_dbm);
+        } else {
+          Serial.printf("  Error: tx out of range (1-%d)\n", MAX_LORA_TX_POWER);
+        }
+
+      } else if (memcmp(config, "utc ", 4) == 0) {
+        int utc = atoi(&config[4]);
+        if (utc >= -12 && utc <= 14) {
+          _prefs.utc_offset_hours = (int8_t)utc;
+          savePrefs();
+          Serial.printf("  > utc = %d\n", _prefs.utc_offset_hours);
+        } else {
+          Serial.println("  Error: utc out of range (-12 to 14)");
+        }
+
+      } else if (memcmp(config, "notify ", 7) == 0) {
+        if (strcmp(&config[7], "on") == 0) {
+          _prefs.kb_flash_notify = 1;
+        } else if (strcmp(&config[7], "off") == 0) {
+          _prefs.kb_flash_notify = 0;
+        } else {
+          Serial.println("  Error: use 'on' or 'off'");
+          cli_command[0] = 0;
+          return;
+        }
+        savePrefs();
+        Serial.printf("  > notify = %s\n", _prefs.kb_flash_notify ? "on" : "off");
+
+      } else if (memcmp(config, "pin ", 4) == 0) {
         _prefs.ble_pin = atoi(&config[4]);
         savePrefs();
         Serial.printf("  > pin is now %06d\n", _prefs.ble_pin);
+
+      } else if (memcmp(config, "radio ", 6) == 0) {
+        // Composite: "set radio <freq> <bw> <sf> <cr>"
+        char tmp[64];
+        strncpy(tmp, &config[6], sizeof(tmp) - 1);
+        tmp[sizeof(tmp) - 1] = '\0';
+        const char* parts[4];
+        int num = mesh::Utils::parseTextParts(tmp, parts, 4);
+        if (num == 4) {
+          float freq = strtof(parts[0], nullptr);
+          float bw   = strtof(parts[1], nullptr);
+          int sf     = atoi(parts[2]);
+          int cr     = atoi(parts[3]);
+          if (freq >= 400.0f && freq <= 928.0f && bw >= 7.8f && bw <= 500.0f
+              && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8) {
+            _prefs.freq = freq;
+            _prefs.bw = bw;
+            _prefs.sf = (uint8_t)sf;
+            _prefs.cr = (uint8_t)cr;
+            savePrefs();
+            radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+            radio_set_tx_power(_prefs.tx_power_dbm);
+            Serial.printf("  > radio = %.3f/%.1f/SF%d/CR%d TX:%d (applied)\n",
+                _prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr, _prefs.tx_power_dbm);
+          } else {
+            Serial.println("  Error: invalid radio params");
+          }
+        } else {
+          Serial.println("  Usage: set radio <freq> <bw> <sf> <cr>");
+        }
+
+      } else if (memcmp(config, "preset ", 7) == 0) {
+        const char* name = &config[7];
+        // Try exact match first (case-insensitive)
+        bool found = false;
+        for (int i = 0; i < (int)NUM_RADIO_PRESETS; i++) {
+          if (strcasecmp(RADIO_PRESETS[i].name, name) == 0) {
+            _prefs.freq = RADIO_PRESETS[i].freq;
+            _prefs.bw = RADIO_PRESETS[i].bw;
+            _prefs.sf = RADIO_PRESETS[i].sf;
+            _prefs.cr = RADIO_PRESETS[i].cr;
+            _prefs.tx_power_dbm = RADIO_PRESETS[i].tx_power;
+            savePrefs();
+            radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+            radio_set_tx_power(_prefs.tx_power_dbm);
+            Serial.printf("  > Applied preset '%s' (%.3f/%.1f/SF%d/CR%d TX:%d)\n",
+                RADIO_PRESETS[i].name, _prefs.freq, _prefs.bw,
+                _prefs.sf, _prefs.cr, _prefs.tx_power_dbm);
+            found = true;
+            break;
+          }
+        }
+        // Try by index number if name didn't match
+        if (!found) {
+          char* endp;
+          long idx = strtol(name, &endp, 10);
+          if (endp != name && *endp == '\0' && idx >= 0 && idx < (int)NUM_RADIO_PRESETS) {
+            _prefs.freq = RADIO_PRESETS[idx].freq;
+            _prefs.bw = RADIO_PRESETS[idx].bw;
+            _prefs.sf = RADIO_PRESETS[idx].sf;
+            _prefs.cr = RADIO_PRESETS[idx].cr;
+            _prefs.tx_power_dbm = RADIO_PRESETS[idx].tx_power;
+            savePrefs();
+            radio_set_params(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
+            radio_set_tx_power(_prefs.tx_power_dbm);
+            Serial.printf("  > Applied preset '%s' (%.3f/%.1f/SF%d/CR%d TX:%d)\n",
+                RADIO_PRESETS[idx].name, _prefs.freq, _prefs.bw,
+                _prefs.sf, _prefs.cr, _prefs.tx_power_dbm);
+            found = true;
+          }
+        }
+        if (!found) {
+          Serial.printf("  Error: unknown preset '%s' (try 'get presets')\n", name);
+        }
+
+      } else if (memcmp(config, "channel.add ", 12) == 0) {
+        const char* name = &config[12];
+        if (strlen(name) == 0) {
+          Serial.println("  Error: channel name required");
+          cli_command[0] = 0;
+          return;
+        }
+        // Build channel name with # prefix if not present
+        char chanName[32];
+        if (name[0] == '#') {
+          strncpy(chanName, name, sizeof(chanName));
+        } else {
+          chanName[0] = '#';
+          strncpy(&chanName[1], name, sizeof(chanName) - 1);
+        }
+        chanName[31] = '\0';
+
+        // Generate 128-bit PSK from SHA-256 of channel name
+        ChannelDetails newCh;
+        memset(&newCh, 0, sizeof(newCh));
+        strncpy(newCh.name, chanName, sizeof(newCh.name));
+        newCh.name[31] = '\0';
+
+        uint8_t hash[32];
+        mesh::Utils::sha256(hash, 32, (const uint8_t*)chanName, strlen(chanName));
+        memcpy(newCh.channel.secret, hash, 16);
+
+        // Find next empty slot
+        bool added = false;
+        for (uint8_t i = 0; i < MAX_GROUP_CHANNELS; i++) {
+          ChannelDetails existing;
+          if (!getChannel(i, existing) || existing.name[0] == '\0') {
+            if (setChannel(i, newCh)) {
+              saveChannels();
+              Serial.printf("  > Added channel '%s' at slot %d\n", chanName, i);
+              added = true;
+            }
+            break;
+          }
+        }
+        if (!added) Serial.println("  Error: no empty channel slots");
+
+      } else if (memcmp(config, "channel.del ", 12) == 0) {
+        int idx = atoi(&config[12]);
+        if (idx <= 0) {
+          Serial.println("  Error: cannot delete channel 0 (public)");
+        } else if (idx >= MAX_GROUP_CHANNELS) {
+          Serial.printf("  Error: index out of range (1-%d)\n", MAX_GROUP_CHANNELS - 1);
+        } else {
+          // Verify channel exists
+          ChannelDetails ch;
+          if (!getChannel(idx, ch) || ch.name[0] == '\0') {
+            Serial.printf("  Error: no channel at index %d\n", idx);
+          } else {
+            // Compact: shift channels down
+            int total = 0;
+            for (uint8_t i = 0; i < MAX_GROUP_CHANNELS; i++) {
+              ChannelDetails tmp;
+              if (getChannel(i, tmp) && tmp.name[0] != '\0') {
+                total = i + 1;
+              } else {
+                break;
+              }
+            }
+            for (int i = idx; i < total - 1; i++) {
+              ChannelDetails next;
+              if (getChannel(i + 1, next)) {
+                setChannel(i, next);
+              }
+            }
+            ChannelDetails empty;
+            memset(&empty, 0, sizeof(empty));
+            setChannel(total - 1, empty);
+            saveChannels();
+            Serial.printf("  > Deleted channel %d ('%s'), compacted %d channels\n",
+                idx, ch.name, total);
+          }
+        }
+
+#ifdef HAS_4G_MODEM
+      } else if (memcmp(config, "apn ", 4) == 0) {
+        const char* apn = &config[4];
+        if (strlen(apn) > 0) {
+          modemManager.setAPN(apn);
+          Serial.printf("  > apn = %s\n", apn);
+        } else {
+          ModemManager::saveAPNConfig("");
+          Serial.println("  > apn cleared (will auto-detect on next boot)");
+        }
+
+      } else if (strcmp(config, "modem on") == 0) {
+        ModemManager::saveEnabledConfig(true);
+        modemManager.begin();
+        Serial.println("  > modem enabled");
+
+      } else if (strcmp(config, "modem off") == 0) {
+        ModemManager::saveEnabledConfig(false);
+        modemManager.shutdown();
+        Serial.println("  > modem disabled");
+#endif
+
       } else {
-        Serial.printf("  Error: unknown config: %s\n", config);
+        Serial.printf("  Error: unknown setting '%s' (try 'help')\n", config);
       }
+
+    // =====================================================================
+    // HELP command
+    // =====================================================================
+    } else if (strcmp(cli_command, "help") == 0) {
+      Serial.println("=== Meck Serial CLI ===");
+      Serial.println("  get <key>                Read a setting");
+      Serial.println("  set <key> <value>        Write a setting");
+      Serial.println("");
+      Serial.println("  Settings keys:");
+      Serial.println("    name, freq, bw, sf, cr, tx, utc, notify, pin");
+      Serial.println("");
+      Serial.println("  Compound commands:");
+      Serial.println("    get all                Dump all settings");
+      Serial.println("    get radio              Show all radio params");
+      Serial.println("    get channels           List channels");
+      Serial.println("    get presets            List radio presets");
+      Serial.println("    get pubkey             Show public key");
+      Serial.println("    get firmware           Show firmware version");
+      Serial.println("    set radio <f> <bw> <sf> <cr>   Set all radio params");
+      Serial.println("    set preset <name|num>  Apply radio preset");
+      Serial.println("    set channel.add <name> Add hashtag channel");
+      Serial.println("    set channel.del <idx>  Delete channel by index");
+#ifdef HAS_4G_MODEM
+      Serial.println("");
+      Serial.println("  4G modem:");
+      Serial.println("    get/set apn, get imei, set modem on/off");
+#endif
+      Serial.println("");
+      Serial.println("  System:");
+      Serial.println("    rebuild   Erase & rebuild filesystem");
+      Serial.println("    erase     Format filesystem");
+      Serial.println("    reboot    Restart device");
+      Serial.println("    ls / cat / rm   File operations");
+
+    // =====================================================================
+    // Existing system commands (unchanged)
+    // =====================================================================
     } else if (strcmp(cli_command, "rebuild") == 0) {
       bool success = _store->formatFileSystem();
       if (success) {
@@ -2095,7 +2679,7 @@ void MyMesh::checkCLIRescueCmd() {
     } else if (strcmp(cli_command, "reboot") == 0) {
       board.reboot();  // doesn't return
     } else {
-      Serial.println("  Error: unknown command");
+      Serial.println("  Error: unknown command (try 'help')");
     }
 
     cli_command[0] = 0;  // reset command buffer
@@ -2132,9 +2716,11 @@ void MyMesh::checkSerialInterface() {
 void MyMesh::loop() {
   BaseChatMesh::loop();
 
-  if (_cli_rescue) {
-    checkCLIRescueCmd();
-  } else {
+  // Always check USB serial for text CLI commands (independent of BLE)
+  checkCLIRescueCmd();
+
+  // Process BLE/WiFi companion app binary frames
+  if (!_cli_rescue) {
     checkSerialInterface();
   }
 
@@ -2144,6 +2730,12 @@ void MyMesh::loop() {
     dirty_contacts_expiry = 0;
   }
 
+  // Discovery scan timeout
+  if (_discoveryActive && millisHasNowPassed(_discoveryTimeout)) {
+    _discoveryActive = false;
+    Serial.printf("[Discovery] Scan complete: %d nodes found\n", _discoveredCount);
+  }
+
 #ifdef DISPLAY_CLASS
   if (_ui) _ui->setHasConnection(_serial->isConnected());
 #endif
@@ -2162,4 +2754,71 @@ bool MyMesh::advert() {
   } else {
     return false;
   }
+}
+
+void MyMesh::startDiscovery(uint32_t duration_ms) {
+  _discoveredCount = 0;
+  _discoveryActive = true;
+  _discoveryTimeout = futureMillis(duration_ms);
+  _discoveryTag = getRNG()->nextInt(1, 0xFFFFFFFF);
+
+  Serial.printf("[Discovery] Active scan started (%lu ms, tag=%08X)\n",
+                duration_ms, _discoveryTag);
+
+  // --- Pre-seed from advert_paths cache (shows known nodes immediately) ---
+  for (int i = 0; i < ADVERT_PATH_TABLE_SIZE && _discoveredCount < MAX_DISCOVERED_NODES; i++) {
+    if (advert_paths[i].recv_timestamp == 0) continue;  // empty slot
+
+    ContactInfo* c = lookupContactByPubKey(advert_paths[i].pubkey_prefix, sizeof(advert_paths[i].pubkey_prefix));
+    if (c) {
+      _discovered[_discoveredCount].contact = *c;
+      _discovered[_discoveredCount].path_len = advert_paths[i].path_len;
+      _discovered[_discoveredCount].snr = 0;  // no SNR from cache
+      _discovered[_discoveredCount].already_in_contacts = true;
+      _discoveredCount++;
+    }
+  }
+  Serial.printf("[Discovery] Pre-seeded %d nodes from cache\n", _discoveredCount);
+
+  // --- Send active discovery request (CTL_TYPE_NODE_DISCOVER_REQ) ---
+  // Repeaters with firmware v1.11+ will respond with their pubkey + SNR
+  uint8_t ctl_payload[10];
+  ctl_payload[0] = CTL_TYPE_NODE_DISCOVER_REQ;  // 0x80, prefix_only=0 (full 32-byte pubkeys)
+  ctl_payload[1] = (1 << ADV_TYPE_REPEATER)     // repeaters
+                 | (1 << ADV_TYPE_ROOM);         // rooms (repeaters with chat)
+  memcpy(&ctl_payload[2], &_discoveryTag, 4);    // random correlation tag
+  uint32_t since = 0;                            // accept all firmware versions
+  memcpy(&ctl_payload[6], &since, 4);
+
+  auto pkt = createControlData(ctl_payload, sizeof(ctl_payload));
+  if (pkt) {
+    sendZeroHop(pkt);
+    Serial.println("[Discovery] Sent CTL_TYPE_NODE_DISCOVER_REQ (zero-hop)");
+  } else {
+    Serial.println("[Discovery] ERROR: createControlData returned NULL (packet pool full?)");
+  }
+}
+
+void MyMesh::stopDiscovery() {
+  _discoveryActive = false;
+}
+
+bool MyMesh::addDiscoveredToContacts(int idx) {
+  if (idx < 0 || idx >= _discoveredCount) return false;
+  if (_discovered[idx].already_in_contacts) return true;  // already there
+
+  // Retrieve cached raw advert packet and import it
+  uint8_t buf[256];
+  int plen = getBlobByKey(_discovered[idx].contact.id.pub_key, PUB_KEY_SIZE, buf);
+  if (plen > 0) {
+    bool ok = importContact(buf, (uint8_t)plen);
+    if (ok) {
+      _discovered[idx].already_in_contacts = true;
+      dirty_contacts_expiry = futureMillis(LAZY_CONTACTS_WRITE_DELAY);
+      MESH_DEBUG_PRINTLN("Discovery: added contact '%s'", _discovered[idx].contact.name);
+    }
+    return ok;
+  }
+  MESH_DEBUG_PRINTLN("Discovery: no cached advert blob for contact '%s'", _discovered[idx].contact.name);
+  return false;
 }

examples/companion_radio/MyMesh.h

@@ -8,11 +8,11 @@
 #define FIRMWARE_VER_CODE 8
 
 #ifndef FIRMWARE_BUILD_DATE
-#define FIRMWARE_BUILD_DATE "10 Feb 2026"
+#define FIRMWARE_BUILD_DATE "4 March 2026"
 #endif
 
 #ifndef FIRMWARE_VERSION
-#define FIRMWARE_VERSION "Meck v0.8.1"
+#define FIRMWARE_VERSION "Meck v0.9.8"
 #endif
 
 #if defined(NRF52_PLATFORM) || defined(STM32_PLATFORM)
@@ -84,6 +84,16 @@ struct AdvertPath {
   uint8_t path[MAX_PATH_SIZE];
 };
 
+// Discovery scan — transient buffer for on-device node discovery
+#define MAX_DISCOVERED_NODES 20
+
+struct DiscoveredNode {
+  ContactInfo contact;
+  uint8_t path_len;
+  int8_t snr;                 // SNR × 4 from active discovery response (0 if pre-seeded)
+  bool already_in_contacts;   // true if contact was auto-added or already known
+};
+
 class MyMesh : public BaseChatMesh, public DataStoreHost {
 public:
   MyMesh(mesh::Radio &radio, mesh::RNG &rng, mesh::RTCClock &rtc, SimpleMeshTables &tables, DataStore& store, AbstractUITask* ui=NULL);
@@ -101,6 +111,14 @@ public:
   void enterCLIRescue();
 
   int  getRecentlyHeard(AdvertPath dest[], int max_num);
+
+  // Discovery scan — on-device node discovery
+  void startDiscovery(uint32_t duration_ms = 30000);
+  void stopDiscovery();
+  bool isDiscoveryActive() const { return _discoveryActive; }
+  int  getDiscoveredCount() const { return _discoveredCount; }
+  const DiscoveredNode& getDiscovered(int idx) const { return _discovered[idx]; }
+  bool addDiscoveredToContacts(int idx);  // promote a discovered node into contacts
   
   // Queue a sent channel message for BLE app sync
   void queueSentChannelMessage(uint8_t channel_idx, uint32_t timestamp, const char* sender, const char* text);
@@ -111,6 +129,7 @@ public:
   // Repeater admin - UI-initiated operations
   bool uiLoginToRepeater(uint32_t contact_idx, const char* password);
   bool uiSendCliCommand(uint32_t contact_idx, const char* command);
+  bool uiSendTelemetryRequest(uint32_t contact_idx);
   int  getAdminContactIdx() const { return _admin_contact_idx; }
 
 
@@ -170,6 +189,12 @@ protected:
 
 public:
   void savePrefs() { _store->savePrefs(_prefs, sensors.node_lat, sensors.node_lon); }
+  void saveChannels() {
+    _store->saveChannels(this);
+  }
+  void saveContacts() {
+    _store->saveContacts(this);
+  }
 
 private:
   void writeOKFrame();
@@ -189,10 +214,6 @@ private:
   void checkCLIRescueCmd();
   void checkSerialInterface();
 
-  // helpers, short-cuts
-  void saveChannels() { _store->saveChannels(this); }
-  void saveContacts() { _store->saveContacts(this); }
-
   DataStore* _store;
   NodePrefs _prefs;
   uint32_t pending_login;
@@ -254,6 +275,13 @@ private:
   SentMsgTrack _sent_track[SENT_TRACK_SIZE];
   int _sent_track_idx;  // next slot in circular buffer
   int _admin_contact_idx;  // contact index for active admin session (-1 if none)
+
+  // Discovery scan state
+  DiscoveredNode _discovered[MAX_DISCOVERED_NODES];
+  int _discoveredCount;
+  bool _discoveryActive;
+  unsigned long _discoveryTimeout;
+  uint32_t _discoveryTag;      // random correlation tag for active discovery
 };
 
 extern MyMesh the_mesh;

examples/companion_radio/NodePrefs.h

@@ -28,4 +28,7 @@ struct NodePrefs {  // persisted to file
   uint8_t  gps_enabled;      // GPS enabled flag (0=disabled, 1=enabled)
   uint32_t gps_interval;     // GPS read interval in seconds
   uint8_t autoadd_config;    // bitmask for auto-add contacts config
+  int8_t  utc_offset_hours;  // UTC offset in hours (-12 to +14), default 0
+  uint8_t kb_flash_notify;   // Keyboard backlight flash on new message (0=off, 1=on)
+  uint8_t ringtone_enabled;  // Ringtone on incoming call (0=off, 1=on) — 4G only
 };

examples/companion_radio/ui-new/ApnDatabase.h

@@ -0,0 +1,372 @@
+#pragma once
+
+// =============================================================================
+// ApnDatabase.h - Embedded APN Lookup Table
+//
+// Maps MCC/MNC (Mobile Country Code / Mobile Network Code) to default APN
+// settings for common carriers worldwide. Compiled directly into flash (~3KB)
+// so users never need to manually install a lookup file.
+//
+// The modem queries IMSI via AT+CIMI to extract MCC (3 digits) + MNC (2-3
+// digits), then looks up the APN here. If not found, falls back to the
+// modem's existing PDP context (AT+CGDCONT?) or user-configured APN.
+//
+// To add a carrier: append to APN_DATABASE[] with the MCC+MNC as a single
+// integer.  MNC can be 2 or 3 digits:
+//   MCC=310, MNC=260  → mccmnc = 310260
+//   MCC=505, MNC=01   → mccmnc = 50501
+//
+// Guard: HAS_4G_MODEM
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef APN_DATABASE_H
+#define APN_DATABASE_H
+
+struct ApnEntry {
+  uint32_t mccmnc;        // MCC+MNC as integer (e.g. 310260 for T-Mobile US)
+  const char* apn;        // APN string
+  const char* carrier;    // Human-readable carrier name (for debug/display)
+};
+
+// ---------------------------------------------------------------------------
+// APN Database — sorted by MCC for binary search potential (not required)
+//
+// Sources: carrier documentation, GSMA databases, community wikis.
+// This covers ~120 major carriers across key regions. Users with less
+// common carriers can set APN manually in Settings.
+// ---------------------------------------------------------------------------
+
+static const ApnEntry APN_DATABASE[] = {
+  // =========================================================================
+  // Australia (MCC 505)
+  // =========================================================================
+  { 50501,  "telstra.internet",    "Telstra" },
+  { 50502,  "yesinternet",         "Optus" },
+  { 50503,  "vfinternet.au",       "Vodafone AU" },
+  { 50506,  "3netaccess",          "Three AU" },
+  { 50507,  "telstra.internet",    "Vodafone AU (MVNO)" },  // Many MVNOs on Telstra
+  { 50510,  "telstra.internet",    "Norfolk Tel" },
+  { 50512,  "3netaccess",          "Amaysim" },              // Optus MVNO
+  { 50514,  "yesinternet",         "Aussie Broadband" },     // Optus MVNO
+  { 50590,  "yesinternet",         "Optus MVNO" },
+
+  // =========================================================================
+  // New Zealand (MCC 530)
+  // =========================================================================
+  { 53001,  "internet",            "Vodafone NZ" },
+  { 53005,  "internet",            "Spark NZ" },
+  { 53024,  "internet",            "2degrees" },
+
+  // =========================================================================
+  // United States (MCC 310, 311, 312, 313, 316)
+  // =========================================================================
+  { 310012, "fast.t-mobile.com",   "Verizon (old)" },
+  { 310026, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310030, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310032, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310060, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310160, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310200, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310210, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310220, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310230, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310240, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310250, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310260, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310270, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310310, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310490, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310530, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310580, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310660, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310800, "fast.t-mobile.com",   "T-Mobile US" },
+  { 311480, "vzwinternet",         "Verizon" },
+  { 311481, "vzwinternet",         "Verizon" },
+  { 311482, "vzwinternet",         "Verizon" },
+  { 311483, "vzwinternet",         "Verizon" },
+  { 311484, "vzwinternet",         "Verizon" },
+  { 311489, "vzwinternet",         "Verizon" },
+  { 310410, "fast.t-mobile.com",   "AT&T (migrated)" },
+  { 310120, "att.mvno",            "AT&T (Sprint)" },
+  { 312530, "iot.1nce.net",        "1NCE IoT" },
+  { 310120, "tfdata",              "Tracfone" },
+
+  // =========================================================================
+  // Canada (MCC 302)
+  // =========================================================================
+  { 30220,  "internet.com",        "Rogers" },
+  { 30221,  "internet.com",        "Rogers" },
+  { 30237,  "internet.com",        "Rogers" },
+  { 30272,  "internet.com",        "Rogers" },
+  { 30234,  "sp.telus.com",        "Telus" },
+  { 30286,  "sp.telus.com",        "Telus" },
+  { 30236,  "sp.telus.com",        "Telus" },
+  { 30261,  "sp.bell.ca",          "Bell" },
+  { 30263,  "sp.bell.ca",          "Bell" },
+  { 30267,  "sp.bell.ca",          "Bell" },
+  { 30268,  "fido-core-appl1.apn", "Fido" },
+  { 30278,  "internet.com",        "SaskTel" },
+  { 30266,  "sp.mb.com",           "MTS" },
+
+  // =========================================================================
+  // United Kingdom (MCC 234, 235)
+  // =========================================================================
+  { 23410,  "o2-internet",         "O2 UK" },
+  { 23415,  "three.co.uk",         "Vodafone UK" },
+  { 23420,  "three.co.uk",         "Three UK" },
+  { 23430,  "everywhere",          "EE" },
+  { 23431,  "everywhere",          "EE" },
+  { 23432,  "everywhere",          "EE" },
+  { 23433,  "everywhere",          "EE" },
+  { 23450,  "data.lycamobile.co.uk","Lycamobile UK" },
+  { 23486,  "three.co.uk",         "Three UK" },
+
+  // =========================================================================
+  // Germany (MCC 262)
+  // =========================================================================
+  { 26201,  "internet.t-mobile",   "Telekom DE" },
+  { 26202,  "web.vodafone.de",     "Vodafone DE" },
+  { 26203,  "internet",            "O2 DE" },
+  { 26207,  "internet",            "O2 DE" },
+
+  // =========================================================================
+  // France (MCC 208)
+  // =========================================================================
+  { 20801,  "orange",              "Orange FR" },
+  { 20810,  "sl2sfr",              "SFR" },
+  { 20815,  "free",                "Free Mobile" },
+  { 20820,  "ofnew.fr",            "Bouygues" },
+
+  // =========================================================================
+  // Italy (MCC 222)
+  // =========================================================================
+  { 22201,  "mobile.vodafone.it",  "TIM" },
+  { 22210,  "mobile.vodafone.it",  "Vodafone IT" },
+  { 22250,  "internet.it",         "Iliad IT" },
+  { 22288,  "internet.wind",       "WindTre" },
+  { 22299,  "internet.wind",       "WindTre" },
+
+  // =========================================================================
+  // Spain (MCC 214)
+  // =========================================================================
+  { 21401,  "internet",            "Vodafone ES" },
+  { 21403,  "internet",            "Orange ES" },
+  { 21404,  "internet",            "Yoigo" },
+  { 21407,  "internet",            "Movistar" },
+
+  // =========================================================================
+  // Netherlands (MCC 204)
+  // =========================================================================
+  { 20404,  "internet",            "Vodafone NL" },
+  { 20408,  "internet",            "KPN" },
+  { 20412,  "internet",            "Telfort" },
+  { 20416,  "internet",            "T-Mobile NL" },
+  { 20420,  "internet",            "T-Mobile NL" },
+
+  // =========================================================================
+  // Sweden (MCC 240)
+  // =========================================================================
+  { 24001,  "internet.telia.se",   "Telia SE" },
+  { 24002,  "tre.se",              "Three SE" },
+  { 24007,  "internet.telenor.se", "Telenor SE" },
+
+  // =========================================================================
+  // Norway (MCC 242)
+  // =========================================================================
+  { 24201,  "internet.telenor.no", "Telenor NO" },
+  { 24202,  "internet.netcom.no",  "Telia NO" },
+
+  // =========================================================================
+  // Denmark (MCC 238)
+  // =========================================================================
+  { 23801,  "internet",            "TDC" },
+  { 23802,  "internet",            "Telenor DK" },
+  { 23806,  "internet",            "Three DK" },
+  { 23820,  "internet",            "Telia DK" },
+
+  // =========================================================================
+  // Switzerland (MCC 228)
+  // =========================================================================
+  { 22801,  "gprs.swisscom.ch",    "Swisscom" },
+  { 22802,  "internet",            "Sunrise" },
+  { 22803,  "internet",            "Salt" },
+
+  // =========================================================================
+  // Austria (MCC 232)
+  // =========================================================================
+  { 23201,  "a1.net",              "A1" },
+  { 23203,  "web.one.at",          "Three AT" },
+  { 23205,  "web",                 "T-Mobile AT" },
+
+  // =========================================================================
+  // Japan (MCC 440, 441)
+  // =========================================================================
+  { 44010,  "spmode.ne.jp",        "NTT Docomo" },
+  { 44020,  "plus.4g",             "SoftBank" },
+  { 44051,  "au.au-net.ne.jp",     "KDDI au" },
+
+  // =========================================================================
+  // South Korea (MCC 450)
+  // =========================================================================
+  { 45005,  "lte.sktelecom.com",   "SK Telecom" },
+  { 45006,  "lte.ktfwing.com",     "KT" },
+  { 45008,  "lte.lguplus.co.kr",   "LG U+" },
+
+  // =========================================================================
+  // India (MCC 404, 405)
+  // =========================================================================
+  { 40445,  "airtelgprs.com",      "Airtel" },
+  { 40410,  "airtelgprs.com",      "Airtel" },
+  { 40411,  "www",                 "Vodafone IN (Vi)" },
+  { 40413,  "www",                 "Vodafone IN (Vi)" },
+  { 40486,  "www",                 "Vodafone IN (Vi)" },
+  { 40553,  "jionet",              "Jio" },
+  { 40554,  "jionet",              "Jio" },
+  { 40512,  "bsnlnet",             "BSNL" },
+
+  // =========================================================================
+  // Singapore (MCC 525)
+  // =========================================================================
+  { 52501,  "internet",            "Singtel" },
+  { 52503,  "internet",            "M1" },
+  { 52505,  "internet",            "StarHub" },
+
+  // =========================================================================
+  // Hong Kong (MCC 454)
+  // =========================================================================
+  { 45400,  "internet",            "CSL" },
+  { 45406,  "internet",            "SmarTone" },
+  { 45412,  "internet",            "CMHK" },
+
+  // =========================================================================
+  // Brazil (MCC 724)
+  // =========================================================================
+  { 72405,  "claro.com.br",        "Claro BR" },
+  { 72406,  "wap.oi.com.br",       "Vivo" },
+  { 72410,  "wap.oi.com.br",       "Vivo" },
+  { 72411,  "wap.oi.com.br",       "Vivo" },
+  { 72415,  "internet.tim.br",     "TIM BR" },
+  { 72431,  "gprs.oi.com.br",      "Oi" },
+
+  // =========================================================================
+  // Mexico (MCC 334)
+  // =========================================================================
+  { 33402,  "internet.itelcel.com","Telcel" },
+  { 33403,  "internet.movistar.mx","Movistar MX" },
+  { 33404,  "internet.att.net.mx", "AT&T MX" },
+
+  // =========================================================================
+  // South Africa (MCC 655)
+  // =========================================================================
+  { 65501,  "internet",            "Vodacom" },
+  { 65502,  "internet",            "Telkom ZA" },
+  { 65507,  "internet",            "Cell C" },
+  { 65510,  "internet",            "MTN ZA" },
+
+  // =========================================================================
+  // Philippines (MCC 515)
+  // =========================================================================
+  { 51502,  "internet.globe.com.ph","Globe" },
+  { 51503,  "internet",            "Smart" },
+  { 51505,  "internet",            "Sun Cellular" },
+
+  // =========================================================================
+  // Thailand (MCC 520)
+  // =========================================================================
+  { 52001,  "internet",            "AIS" },
+  { 52004,  "internet",            "TrueMove" },
+  { 52005,  "internet",            "dtac" },
+
+  // =========================================================================
+  // Indonesia (MCC 510)
+  // =========================================================================
+  { 51001,  "internet",            "Telkomsel" },
+  { 51010,  "internet",            "Telkomsel" },
+  { 51011,  "3gprs",               "XL Axiata" },
+  { 51028,  "3gprs",               "XL Axiata (Axis)" },
+
+  // =========================================================================
+  // Malaysia (MCC 502)
+  // =========================================================================
+  { 50212,  "celcom3g",            "Celcom" },
+  { 50213,  "celcom3g",            "Celcom" },
+  { 50216,  "internet",            "Digi" },
+  { 50219,  "celcom3g",            "Celcom" },
+
+  // =========================================================================
+  // Czech Republic (MCC 230)
+  // =========================================================================
+  { 23001,  "internet.t-mobile.cz","T-Mobile CZ" },
+  { 23002,  "internet",            "O2 CZ" },
+  { 23003,  "internet.vodafone.cz","Vodafone CZ" },
+
+  // =========================================================================
+  // Poland (MCC 260)
+  // =========================================================================
+  { 26001,  "internet",            "Plus PL" },
+  { 26002,  "internet",            "T-Mobile PL" },
+  { 26003,  "internet",            "Orange PL" },
+  { 26006,  "internet",            "Play" },
+
+  // =========================================================================
+  // Portugal (MCC 268)
+  // =========================================================================
+  { 26801,  "internet",            "Vodafone PT" },
+  { 26803,  "internet",            "NOS" },
+  { 26806,  "internet",            "MEO" },
+
+  // =========================================================================
+  // Ireland (MCC 272)
+  // =========================================================================
+  { 27201,  "internet",            "Vodafone IE" },
+  { 27202,  "open.internet",       "Three IE" },
+  { 27205,  "three.ie",            "Three IE" },
+
+  // =========================================================================
+  // IoT / Global SIMs
+  // =========================================================================
+  { 901028, "iot.1nce.net",        "1NCE (IoT)" },
+  { 90143,  "hologram",            "Hologram" },
+};
+
+#define APN_DATABASE_SIZE (sizeof(APN_DATABASE) / sizeof(APN_DATABASE[0]))
+
+// ---------------------------------------------------------------------------
+// Lookup function — returns nullptr if not found
+// ---------------------------------------------------------------------------
+
+inline const ApnEntry* apnLookup(uint32_t mccmnc) {
+  for (int i = 0; i < (int)APN_DATABASE_SIZE; i++) {
+    if (APN_DATABASE[i].mccmnc == mccmnc) {
+      return &APN_DATABASE[i];
+    }
+  }
+  return nullptr;
+}
+
+// Parse IMSI string into MCC+MNC.  Tries 3-digit MNC first (6-digit mccmnc),
+// falls back to 2-digit MNC (5-digit mccmnc) if not found.
+inline const ApnEntry* apnLookupFromIMSI(const char* imsi) {
+  if (!imsi || strlen(imsi) < 5) return nullptr;
+
+  // Extract MCC (always 3 digits)
+  uint32_t mcc = (imsi[0] - '0') * 100 + (imsi[1] - '0') * 10 + (imsi[2] - '0');
+
+  // Try 3-digit MNC first (more specific)
+  if (strlen(imsi) >= 6) {
+    uint32_t mnc3 = (imsi[3] - '0') * 100 + (imsi[4] - '0') * 10 + (imsi[5] - '0');
+    uint32_t mccmnc6 = mcc * 1000 + mnc3;
+    const ApnEntry* entry = apnLookup(mccmnc6);
+    if (entry) return entry;
+  }
+
+  // Fall back to 2-digit MNC
+  uint32_t mnc2 = (imsi[3] - '0') * 10 + (imsi[4] - '0');
+  uint32_t mccmnc5 = mcc * 100 + mnc2;
+  return apnLookup(mccmnc5);
+}
+
+#endif // APN_DATABASE_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/ChannelScreen.h

@@ -6,14 +6,47 @@
 #include <MeshCore.h>
 #include "EmojiSprites.h"
 
+// SD card message persistence
+#if defined(HAS_SDCARD) && defined(ESP32)
+  #include <SD.h>
+#endif
+
 // Maximum messages to store in history
-#define CHANNEL_MSG_HISTORY_SIZE 20
+#define CHANNEL_MSG_HISTORY_SIZE 300
 #define CHANNEL_MSG_TEXT_LEN 160
+#define MSG_PATH_MAX 20  // Max repeater hops stored per message
 
 #ifndef MAX_GROUP_CHANNELS
   #define MAX_GROUP_CHANNELS 20
 #endif
 
+// ---------------------------------------------------------------------------
+// On-disk format for message persistence (SD card)
+// ---------------------------------------------------------------------------
+#define MSG_FILE_MAGIC   0x4D434853  // "MCHS" - MeshCore History Store
+#define MSG_FILE_VERSION 3           // v3: MSG_PATH_MAX increased to 20
+#define MSG_FILE_PATH    "/meshcore/messages.bin"
+
+struct __attribute__((packed)) MsgFileHeader {
+  uint32_t magic;
+  uint16_t version;
+  uint16_t capacity;
+  uint16_t count;
+  int16_t  newestIdx;
+  // 12 bytes total
+};
+
+struct __attribute__((packed)) MsgFileRecord {
+  uint32_t timestamp;
+  uint8_t  path_len;
+  uint8_t  channel_idx;
+  uint8_t  valid;
+  uint8_t  reserved;
+  uint8_t  path[MSG_PATH_MAX];  // Repeater hop hashes (first byte of pub key)
+  char     text[CHANNEL_MSG_TEXT_LEN];
+  // 188 bytes total
+};
+
 class UITask;  // Forward declaration
 class MyMesh;  // Forward declaration
 extern MyMesh the_mesh;
@@ -24,6 +57,7 @@ public:
     uint32_t timestamp;
     uint8_t path_len;
     uint8_t channel_idx;  // Which channel this message belongs to
+    uint8_t path[MSG_PATH_MAX];  // Repeater hop hashes
     char text[CHANNEL_MSG_TEXT_LEN];
     bool valid;
   };
@@ -38,19 +72,40 @@ private:
   int _scrollPos;     // Current scroll position (0 = newest)
   int _msgsPerPage;   // Messages that fit on screen
   uint8_t _viewChannelIdx;  // Which channel we're currently viewing
+  bool _sdReady;      // SD card is available for persistence
+  bool _showPathOverlay;  // Show path detail overlay for last received msg
+  int _pathScrollPos;     // Scroll offset within path overlay hop list
+  int _pathHopsVisible;   // Hops that fit on screen (set during render)
+
+  // Reply select mode — press R to pick a message and reply with @mention
+  bool _replySelectMode;       // True when user is picking a message to reply to
+  int  _replySelectPos;        // Index into chronological channelMsgs[] (0=oldest)
+  int  _replyChannelMsgCount;  // Cached count from last render (for input bounds)
+
+  // Per-channel unread message counts (standalone mode)
+  // Index 0..MAX_GROUP_CHANNELS-1 for channel messages
+  // Index MAX_GROUP_CHANNELS for DMs (channel_idx == 0xFF)
+  int _unread[MAX_GROUP_CHANNELS + 1];
   
 public:
   ChannelScreen(UITask* task, mesh::RTCClock* rtc) 
     : _task(task), _rtc(rtc), _msgCount(0), _newestIdx(-1), _scrollPos(0), 
-      _msgsPerPage(3), _viewChannelIdx(0) {
+      _msgsPerPage(6), _viewChannelIdx(0), _sdReady(false), _showPathOverlay(false), _pathScrollPos(0), _pathHopsVisible(20),
+      _replySelectMode(false), _replySelectPos(-1), _replyChannelMsgCount(0) {
     // Initialize all messages as invalid
     for (int i = 0; i < CHANNEL_MSG_HISTORY_SIZE; i++) {
       _messages[i].valid = false;
+      memset(_messages[i].path, 0, MSG_PATH_MAX);
     }
+    // Initialize unread counts
+    memset(_unread, 0, sizeof(_unread));
   }
 
+  void setSDReady(bool ready) { _sdReady = ready; }
+
   // Add a new message to the history
-  void addMessage(uint8_t channel_idx, uint8_t path_len, const char* sender, const char* text) {
+  void addMessage(uint8_t channel_idx, uint8_t path_len, const char* sender, const char* text,
+                  const uint8_t* path_bytes = nullptr) {
     // Move to next slot in circular buffer
     _newestIdx = (_newestIdx + 1) % CHANNEL_MSG_HISTORY_SIZE;
     
@@ -60,6 +115,13 @@ public:
     msg->channel_idx = channel_idx;
     msg->valid = true;
     
+    // Store path hop hashes
+    memset(msg->path, 0, MSG_PATH_MAX);
+    if (path_bytes && path_len > 0 && path_len != 0xFF) {
+      int n = path_len < MSG_PATH_MAX ? path_len : MSG_PATH_MAX;
+      memcpy(msg->path, path_bytes, n);
+    }
+    
     // Sanitize emoji: replace UTF-8 emoji sequences with single-byte escape codes
     // The text already contains "Sender: message" format
     emojiSanitize(text, msg->text, CHANNEL_MSG_TEXT_LEN);
@@ -70,6 +132,22 @@ public:
     
     // Reset scroll to show newest message
     _scrollPos = 0;
+    _showPathOverlay = false;  // Dismiss overlay on new message
+    _pathScrollPos = 0;
+    _replySelectMode = false;  // Dismiss reply select on new message
+    _replySelectPos = -1;
+
+    // Track unread count for this channel (only for received messages, not sent)
+    // path_len == 0 means locally sent
+    if (path_len != 0) {
+      int unreadSlot = (channel_idx == 0xFF) ? MAX_GROUP_CHANNELS : channel_idx;
+      if (unreadSlot >= 0 && unreadSlot <= MAX_GROUP_CHANNELS) {
+        _unread[unreadSlot]++;
+      }
+    }
+
+    // Persist to SD card
+    saveToSD();
   }
 
   // Get count of messages for the currently viewed channel
@@ -86,7 +164,271 @@ public:
   int getMessageCount() const { return _msgCount; }
   
   uint8_t getViewChannelIdx() const { return _viewChannelIdx; }
-  void setViewChannelIdx(uint8_t idx) { _viewChannelIdx = idx; _scrollPos = 0; }
+  void setViewChannelIdx(uint8_t idx) {
+    _viewChannelIdx = idx;
+    _scrollPos = 0;
+    _showPathOverlay = false;
+    _pathScrollPos = 0;
+    markChannelRead(idx);
+  }
+  bool isShowingPathOverlay() const { return _showPathOverlay; }
+  void dismissPathOverlay() { _showPathOverlay = false; _pathScrollPos = 0; }
+
+  // --- Reply select mode (R key → pick a message → Enter to @mention reply) ---
+  bool isReplySelectMode() const { return _replySelectMode; }
+  void exitReplySelect() { _replySelectMode = false; _replySelectPos = -1; }
+
+  // Extract sender name from a "Sender: message" formatted text.
+  // Returns true if a sender was found, fills senderBuf (null-terminated).
+  static bool extractSenderName(const char* msgText, char* senderBuf, int bufLen) {
+    const char* colon = strstr(msgText, ": ");
+    if (!colon || colon == msgText) return false;
+    int nameLen = colon - msgText;
+    if (nameLen >= bufLen) nameLen = bufLen - 1;
+    memcpy(senderBuf, msgText, nameLen);
+    senderBuf[nameLen] = '\0';
+    return true;
+  }
+
+  // Get the sender name of the currently selected message in reply select mode.
+  // Returns true and fills senderBuf if valid selection exists.
+  bool getReplySelectSender(char* senderBuf, int bufLen) {
+    if (!_replySelectMode || _replySelectPos < 0) return false;
+
+    // Rebuild the channel message list (same logic as render)
+    static int rsMsgs[CHANNEL_MSG_HISTORY_SIZE];
+    int count = 0;
+    for (int i = 0; i < _msgCount && count < CHANNEL_MSG_HISTORY_SIZE; i++) {
+      int idx = _newestIdx - i;
+      while (idx < 0) idx += CHANNEL_MSG_HISTORY_SIZE;
+      idx = idx % CHANNEL_MSG_HISTORY_SIZE;
+      if (_messages[idx].valid && _messages[idx].channel_idx == _viewChannelIdx) {
+        rsMsgs[count++] = idx;
+      }
+    }
+    // Reverse to chronological (oldest first)
+    for (int l = 0, r = count - 1; l < r; l++, r--) {
+      int t = rsMsgs[l]; rsMsgs[l] = rsMsgs[r]; rsMsgs[r] = t;
+    }
+
+    if (_replySelectPos >= count) return false;
+    int idx = rsMsgs[_replySelectPos];
+    return extractSenderName(_messages[idx].text, senderBuf, bufLen);
+  }
+
+  // Get the ChannelMessage pointer for the currently selected reply message.
+  ChannelMessage* getReplySelectMsg() {
+    if (!_replySelectMode || _replySelectPos < 0) return nullptr;
+
+    static int rsMsgs[CHANNEL_MSG_HISTORY_SIZE];
+    int count = 0;
+    for (int i = 0; i < _msgCount && count < CHANNEL_MSG_HISTORY_SIZE; i++) {
+      int idx = _newestIdx - i;
+      while (idx < 0) idx += CHANNEL_MSG_HISTORY_SIZE;
+      idx = idx % CHANNEL_MSG_HISTORY_SIZE;
+      if (_messages[idx].valid && _messages[idx].channel_idx == _viewChannelIdx) {
+        rsMsgs[count++] = idx;
+      }
+    }
+    for (int l = 0, r = count - 1; l < r; l++, r--) {
+      int t = rsMsgs[l]; rsMsgs[l] = rsMsgs[r]; rsMsgs[r] = t;
+    }
+
+    if (_replySelectPos >= count) return nullptr;
+    return &_messages[rsMsgs[_replySelectPos]];
+  }
+
+  // --- Unread message tracking (standalone mode) ---
+
+  // Mark all messages for a channel as read
+  void markChannelRead(uint8_t channel_idx) {
+    int slot = (channel_idx == 0xFF) ? MAX_GROUP_CHANNELS : channel_idx;
+    if (slot >= 0 && slot <= MAX_GROUP_CHANNELS) {
+      _unread[slot] = 0;
+    }
+  }
+
+  // Get unread count for a specific channel
+  int getUnreadForChannel(uint8_t channel_idx) const {
+    int slot = (channel_idx == 0xFF) ? MAX_GROUP_CHANNELS : channel_idx;
+    if (slot >= 0 && slot <= MAX_GROUP_CHANNELS) {
+      return _unread[slot];
+    }
+    return 0;
+  }
+
+  // Get total unread across all channels
+  int getTotalUnread() const {
+    int total = 0;
+    for (int i = 0; i <= MAX_GROUP_CHANNELS; i++) {
+      total += _unread[i];
+    }
+    return total;
+  }
+
+  // Find the newest RECEIVED message for the current channel
+  // (path_len != 0 means received, path_len 0 = locally sent)
+  ChannelMessage* getNewestReceivedMsg() {
+    for (int i = 0; i < _msgCount; i++) {
+      int idx = _newestIdx - i;
+      while (idx < 0) idx += CHANNEL_MSG_HISTORY_SIZE;
+      idx = idx % CHANNEL_MSG_HISTORY_SIZE;
+      if (_messages[idx].valid && _messages[idx].channel_idx == _viewChannelIdx
+          && _messages[idx].path_len != 0) {
+        return &_messages[idx];
+      }
+    }
+    return nullptr;
+  }
+
+  // Format the path of the newest received message as paste-ready text
+  // Output: comma-separated hex prefixes e.g. "30, 3b, 9b, 05, e8, 36"
+  // Returns length written (0 if no path available)
+  int formatPathAsText(char* buf, int bufLen) {
+    ChannelMessage* msg = getNewestReceivedMsg();
+    if (!msg || msg->path_len == 0 || msg->path_len == 0xFF) return 0;
+    
+    int pos = 0;
+    int plen = msg->path_len < MSG_PATH_MAX ? msg->path_len : MSG_PATH_MAX;
+    
+    for (int h = 0; h < plen && pos < bufLen - 1; h++) {
+      if (h > 0) pos += snprintf(buf + pos, bufLen - pos, ", ");
+      pos += snprintf(buf + pos, bufLen - pos, "%02x", msg->path[h]);
+    }
+    
+    return pos;
+  }
+
+  // -----------------------------------------------------------------------
+  // SD card persistence
+  // -----------------------------------------------------------------------
+
+  // Save the entire message buffer to SD card.
+  // File: /meshcore/messages.bin  (~50 KB for 300 messages)
+  void saveToSD() {
+#if defined(HAS_SDCARD) && defined(ESP32)
+    if (!_sdReady) return;
+
+    // Ensure directory exists
+    if (!SD.exists("/meshcore")) {
+      SD.mkdir("/meshcore");
+    }
+
+    File f = SD.open(MSG_FILE_PATH, "w", true);
+    if (!f) {
+      Serial.println("ChannelScreen: SD save failed - can't open file");
+      return;
+    }
+
+    // Write header
+    MsgFileHeader hdr;
+    hdr.magic    = MSG_FILE_MAGIC;
+    hdr.version  = MSG_FILE_VERSION;
+    hdr.capacity = CHANNEL_MSG_HISTORY_SIZE;
+    hdr.count    = (uint16_t)_msgCount;
+    hdr.newestIdx = (int16_t)_newestIdx;
+    f.write((uint8_t*)&hdr, sizeof(hdr));
+
+    // Write all message slots (including invalid ones - preserves circular buffer layout)
+    for (int i = 0; i < CHANNEL_MSG_HISTORY_SIZE; i++) {
+      MsgFileRecord rec;
+      rec.timestamp   = _messages[i].timestamp;
+      rec.path_len    = _messages[i].path_len;
+      rec.channel_idx = _messages[i].channel_idx;
+      rec.valid       = _messages[i].valid ? 1 : 0;
+      rec.reserved    = 0;
+      memcpy(rec.path, _messages[i].path, MSG_PATH_MAX);
+      memcpy(rec.text, _messages[i].text, CHANNEL_MSG_TEXT_LEN);
+      f.write((uint8_t*)&rec, sizeof(rec));
+    }
+
+    f.close();
+    digitalWrite(SDCARD_CS, HIGH);  // Release SD CS
+#endif
+  }
+
+  // Load message buffer from SD card.  Returns true if messages were loaded.
+  bool loadFromSD() {
+#if defined(HAS_SDCARD) && defined(ESP32)
+    if (!_sdReady) return false;
+
+    if (!SD.exists(MSG_FILE_PATH)) {
+      Serial.println("ChannelScreen: No saved messages on SD");
+      return false;
+    }
+
+    File f = SD.open(MSG_FILE_PATH, "r");
+    if (!f) {
+      Serial.println("ChannelScreen: SD load failed - can't open file");
+      return false;
+    }
+
+    // Read and validate header
+    MsgFileHeader hdr;
+    if (f.read((uint8_t*)&hdr, sizeof(hdr)) != sizeof(hdr)) {
+      Serial.println("ChannelScreen: SD load failed - short header");
+      f.close();
+      return false;
+    }
+
+    if (hdr.magic != MSG_FILE_MAGIC) {
+      Serial.printf("ChannelScreen: SD load failed - bad magic 0x%08X\n", hdr.magic);
+      f.close();
+      return false;
+    }
+
+    if (hdr.version != MSG_FILE_VERSION) {
+      Serial.printf("ChannelScreen: SD load failed - version %d (expected %d)\n",
+                    hdr.version, MSG_FILE_VERSION);
+      f.close();
+      return false;
+    }
+
+    if (hdr.capacity != CHANNEL_MSG_HISTORY_SIZE) {
+      Serial.printf("ChannelScreen: SD load failed - capacity %d (expected %d)\n",
+                    hdr.capacity, CHANNEL_MSG_HISTORY_SIZE);
+      f.close();
+      return false;
+    }
+
+    // Read message records
+    int loaded = 0;
+    for (int i = 0; i < CHANNEL_MSG_HISTORY_SIZE; i++) {
+      MsgFileRecord rec;
+      if (f.read((uint8_t*)&rec, sizeof(rec)) != sizeof(rec)) {
+        Serial.printf("ChannelScreen: SD load - short read at record %d\n", i);
+        break;
+      }
+      _messages[i].timestamp   = rec.timestamp;
+      _messages[i].path_len    = rec.path_len;
+      _messages[i].channel_idx = rec.channel_idx;
+      _messages[i].valid       = (rec.valid != 0);
+      memcpy(_messages[i].path, rec.path, MSG_PATH_MAX);
+      memcpy(_messages[i].text, rec.text, CHANNEL_MSG_TEXT_LEN);
+      if (_messages[i].valid) loaded++;
+    }
+
+    _msgCount   = (int)hdr.count;
+    _newestIdx  = (int)hdr.newestIdx;
+    _scrollPos  = 0;
+
+    // Sanity-check restored state
+    if (_newestIdx < -1 || _newestIdx >= CHANNEL_MSG_HISTORY_SIZE) _newestIdx = -1;
+    if (_msgCount < 0 || _msgCount > CHANNEL_MSG_HISTORY_SIZE) _msgCount = loaded;
+
+    f.close();
+    digitalWrite(SDCARD_CS, HIGH);  // Release SD CS
+    Serial.printf("ChannelScreen: Loaded %d messages from SD (count=%d, newest=%d)\n",
+                  loaded, _msgCount, _newestIdx);
+    return loaded > 0;
+#else
+    return false;
+#endif
+  }
+
+  // -----------------------------------------------------------------------
+  // Rendering
+  // -----------------------------------------------------------------------
 
   int render(DisplayDriver& display) override {
     char tmp[40];
@@ -114,6 +456,175 @@ public:
     // Divider line
     display.drawRect(0, 11, display.width(), 1);
     
+    // --- Path detail overlay ---
+    if (_showPathOverlay) {
+      display.setTextSize(0);
+      int lineH = 9;
+      int y = 14;
+      
+      ChannelMessage* msg = getNewestReceivedMsg();
+      if (!msg) {
+        display.setCursor(0, y);
+        display.setColor(DisplayDriver::LIGHT);
+        display.print("No received messages");
+      } else {
+        // Message preview (first ~30 chars)
+        display.setCursor(0, y);
+        display.setColor(DisplayDriver::LIGHT);
+        char preview[32];
+        strncpy(preview, msg->text, 31);
+        preview[31] = '\0';
+        display.print(preview);
+        y += lineH;
+        
+        // Age
+        uint32_t age = _rtc->getCurrentTime() - msg->timestamp;
+        display.setCursor(0, y);
+        display.setColor(DisplayDriver::YELLOW);
+        if (age < 60) sprintf(tmp, "Age: %ds", age);
+        else if (age < 3600) sprintf(tmp, "Age: %dm", age / 60);
+        else if (age < 86400) sprintf(tmp, "Age: %dh", age / 3600);
+        else sprintf(tmp, "Age: %dd", age / 86400);
+        display.print(tmp);
+        y += lineH;
+        
+        // Route type
+        display.setCursor(0, y);
+        uint8_t plen = msg->path_len;
+        if (plen == 0xFF) {
+          display.setColor(DisplayDriver::LIGHT);
+          display.print("Route: Direct");
+        } else if (plen == 0) {
+          display.setColor(DisplayDriver::LIGHT);
+          display.print("Route: Local/Sent");
+        } else {
+          display.setColor(DisplayDriver::GREEN);
+          sprintf(tmp, "Route: %d hop%s", plen, plen == 1 ? "" : "s");
+          display.print(tmp);
+        }
+        y += lineH + 2;
+        
+        // Show each hop resolved against contacts (scrollable)
+        if (plen > 0 && plen != 0xFF) {
+          int displayHops = plen < MSG_PATH_MAX ? plen : MSG_PATH_MAX;
+          int footerReserve = 26;  // footer + divider
+          int scrollBarW = 4;
+          int maxY = display.height() - footerReserve;
+          int hopAreaTop = y;
+          
+          // Calculate how many hops fit in the visible area
+          int hopsVisible = (maxY - hopAreaTop) / lineH;
+          if (hopsVisible < 1) hopsVisible = 1;
+          _pathHopsVisible = hopsVisible;  // Cache for input handler
+          bool needsScroll = displayHops > hopsVisible;
+          
+          // Clamp scroll position
+          int maxScroll = displayHops - hopsVisible;
+          if (maxScroll < 0) maxScroll = 0;
+          if (_pathScrollPos > maxScroll) _pathScrollPos = maxScroll;
+          
+          // Available text width (narrower if scroll bar present)
+          int textRight = needsScroll ? display.width() - scrollBarW - 2 : display.width();
+          (void)textRight;  // reserved for future truncation
+          
+          int startHop = _pathScrollPos;
+          int endHop = startHop + hopsVisible;
+          if (endHop > displayHops) endHop = displayHops;
+          
+          for (int h = startHop; h < endHop && y + lineH <= maxY; h++) {
+            uint8_t hopHash = msg->path[h];
+            display.setCursor(0, y);
+            display.setColor(DisplayDriver::LIGHT);
+            sprintf(tmp, " %d: ", h + 1);
+            display.print(tmp);
+            
+            // Always show hex prefix first
+            display.setColor(DisplayDriver::LIGHT);
+            sprintf(tmp, "%02X ", hopHash);
+            display.print(tmp);
+            
+            // Try to resolve name: prefer repeaters, then any contact
+            bool resolved = false;
+            int numContacts = the_mesh.getNumContacts();
+            ContactInfo contact;
+            
+            // First pass: repeaters only
+            for (uint32_t ci = 0; ci < numContacts && !resolved; ci++) {
+              if (the_mesh.getContactByIdx(ci, contact)) {
+                if (contact.id.pub_key[0] == hopHash && contact.type == ADV_TYPE_REPEATER) {
+                  display.setColor(DisplayDriver::GREEN);
+                  display.print(contact.name);
+                  resolved = true;
+                }
+              }
+            }
+            // Second pass: any contact type
+            if (!resolved) {
+              for (uint32_t ci = 0; ci < numContacts; ci++) {
+                if (the_mesh.getContactByIdx(ci, contact)) {
+                  if (contact.id.pub_key[0] == hopHash) {
+                    display.setColor(DisplayDriver::YELLOW);
+                    display.print(contact.name);
+                    resolved = true;
+                    break;
+                  }
+                }
+              }
+            }
+            // No name resolved - hex prefix already shown, add "?" marker
+            if (!resolved) {
+              display.setColor(DisplayDriver::LIGHT);
+              display.print("?");
+            }
+            y += lineH;
+          }
+          
+          // Scroll bar (right edge) when hops exceed visible area
+          if (needsScroll) {
+            int sbX = display.width() - scrollBarW;
+            int sbTop = hopAreaTop;
+            int sbHeight = maxY - hopAreaTop;
+            
+            // Outline
+            display.setColor(DisplayDriver::LIGHT);
+            display.drawRect(sbX, sbTop, scrollBarW, sbHeight);
+            
+            // Proportional thumb
+            int thumbH = (hopsVisible * sbHeight) / displayHops;
+            if (thumbH < 4) thumbH = 4;
+            int thumbY = sbTop + (_pathScrollPos * (sbHeight - thumbH)) / maxScroll;
+            display.setColor(DisplayDriver::GREEN);
+            for (int ty = thumbY + 1; ty < thumbY + thumbH - 1; ty++)
+              display.drawRect(sbX + 1, ty, scrollBarW - 2, 1);
+          }
+        }
+      }
+      
+      // Overlay footer
+      display.setTextSize(1);
+      int footerY = display.height() - 12;
+      display.drawRect(0, footerY - 2, display.width(), 1);
+      display.setCursor(0, footerY);
+      display.setColor(DisplayDriver::YELLOW);
+      display.print("Q:Back");
+      // Show scroll hint if path is scrollable
+      if (msg && msg->path_len > _pathHopsVisible && msg->path_len != 0xFF) {
+        const char* scrollHint = "W/S:Scrl";
+        int scrollW = display.getTextWidth(scrollHint);
+        display.setCursor((display.width() - scrollW) / 2, footerY);
+        display.print(scrollHint);
+      }
+      const char* copyHint = "Ent:Copy";
+      display.setCursor(display.width() - display.getTextWidth(copyHint) - 2, footerY);
+      display.print(copyHint);
+
+#if AUTO_OFF_MILLIS == 0
+      return 5000;
+#else
+      return 1000;
+#endif
+    }
+    
     if (channelMsgCount == 0) {
       display.setTextSize(0);  // Tiny font for body text
       display.setCursor(0, 20);
@@ -129,6 +640,7 @@ public:
       int lineHeight = 9;   // 8px font + 1px spacing
       int headerHeight = 14;
       int footerHeight = 14;
+      int scrollBarW = 4;   // Width of scroll indicator on right edge
       // Hard cutoff: no text may START at or beyond this y value
       // This ensures rendered glyphs (which extend lineHeight below y) stay above the footer
       int maxY = display.height() - footerHeight;
@@ -136,7 +648,8 @@ public:
       int y = headerHeight;
       
       // Build list of messages for this channel (newest first)
-      int channelMsgs[CHANNEL_MSG_HISTORY_SIZE];
+      // Static to avoid 1200-byte stack allocation every render cycle
+      static int channelMsgs[CHANNEL_MSG_HISTORY_SIZE];
       int numChannelMsgs = 0;
       
       for (int i = 0; i < _msgCount && numChannelMsgs < CHANNEL_MSG_HISTORY_SIZE; i++) {
@@ -154,6 +667,13 @@ public:
         int tmp = channelMsgs[l]; channelMsgs[l] = channelMsgs[r]; channelMsgs[r] = tmp;
       }
       
+      // Cache for reply select input bounds
+      _replyChannelMsgCount = numChannelMsgs;
+      
+      // Clamp scroll position to valid range
+      int maxScroll = numChannelMsgs > _msgsPerPage ? numChannelMsgs - _msgsPerPage : 0;
+      if (_scrollPos > maxScroll) _scrollPos = maxScroll;
+      
       // Calculate start index so newest messages appear at the bottom
       // scrollPos=0 shows the most recent messages, scrollPos++ scrolls up to older
       int startIdx = numChannelMsgs - _msgsPerPage - _scrollPos;
@@ -161,40 +681,72 @@ public:
       
       // Display messages oldest-to-newest (top to bottom)
       int msgsDrawn = 0;
+      bool screenFull = false;
+      bool lastMsgTruncated = false;  // Did the last message get clipped by footer?
       for (int i = startIdx; i < numChannelMsgs && y + lineHeight <= maxY; i++) {
         int idx = channelMsgs[i];
         ChannelMessage* msg = &_messages[idx];
         
+        // Reply select: is this the currently selected message?
+        bool isSelected = (_replySelectMode && i == _replySelectPos);
+        
+        // Highlight: single fillRect for the entire message area, then
+        // draw DARK text on top (same pattern as web reader bookmarks).
+        // Because message height depends on word-wrap, we fill a generous
+        // area up-front and erase the excess after rendering.
+        int yStart = y;
+        int contentW = display.width();
+        int maxLinesPerMsg = 8;
+        if (isSelected) {
+          int maxFillH = (maxLinesPerMsg + 1) * lineHeight + 2;
+          int availH = maxY - y;
+          if (maxFillH > availH) maxFillH = availH;
+          display.setColor(DisplayDriver::LIGHT);
+          display.fillRect(0, y + 5, contentW, maxFillH);
+        }
+        
         // Time indicator with hop count - inline on same line as message start
         display.setCursor(0, y);
-        display.setColor(DisplayDriver::YELLOW);
+        display.setColor(isSelected ? DisplayDriver::DARK : DisplayDriver::YELLOW);
         
         uint32_t age = _rtc->getCurrentTime() - msg->timestamp;
-        if (age < 60) {
-          sprintf(tmp, "(%d) %ds ", msg->path_len == 0xFF ? 0 : msg->path_len, age);
-        } else if (age < 3600) {
-          sprintf(tmp, "(%d) %dm ", msg->path_len == 0xFF ? 0 : msg->path_len, age / 60);
-        } else if (age < 86400) {
-          sprintf(tmp, "(%d) %dh ", msg->path_len == 0xFF ? 0 : msg->path_len, age / 3600);
+        if (isSelected) {
+          // Show > marker for selected message, replacing the hop count
+          if (age < 60) {
+            sprintf(tmp, ">%ds ", age);
+          } else if (age < 3600) {
+            sprintf(tmp, ">%dm ", age / 60);
+          } else if (age < 86400) {
+            sprintf(tmp, ">%dh ", age / 3600);
+          } else {
+            sprintf(tmp, ">%dd ", age / 86400);
+          }
         } else {
-          sprintf(tmp, "(%d) %dd ", msg->path_len == 0xFF ? 0 : msg->path_len, age / 86400);
+          if (age < 60) {
+            sprintf(tmp, "(%d) %ds ", msg->path_len == 0xFF ? 0 : msg->path_len, age);
+          } else if (age < 3600) {
+            sprintf(tmp, "(%d) %dm ", msg->path_len == 0xFF ? 0 : msg->path_len, age / 60);
+          } else if (age < 86400) {
+            sprintf(tmp, "(%d) %dh ", msg->path_len == 0xFF ? 0 : msg->path_len, age / 3600);
+          } else {
+            sprintf(tmp, "(%d) %dd ", msg->path_len == 0xFF ? 0 : msg->path_len, age / 86400);
+          }
         }
         display.print(tmp);
         // DO NOT advance y - message text continues on the same line
         
         // Message text with character wrapping and inline emoji support
         // (continues after timestamp on first line)
-        display.setColor(DisplayDriver::LIGHT);
+        display.setColor(isSelected ? DisplayDriver::DARK : DisplayDriver::LIGHT);
         
         int textLen = strlen(msg->text);
         int pos = 0;
         int linesForThisMsg = 0;
-        int maxLinesPerMsg = 8;
         char charStr[2] = {0, 0};
         
         // Track position in pixels for emoji placement
         // Uses advance width (cursor movement) not bounding box for px tracking
-        int lineW = display.width();
+        int lineW = display.width() - scrollBarW - 1;  // Reserve space for scroll bar
         int px = display.getTextWidth(tmp);  // Pixel X after timestamp
         char dblStr[3] = {0, 0, 0};
         
@@ -283,14 +835,70 @@ public:
           }
         }
         
+        // Check if this message was clipped (not all text rendered)
+        lastMsgTruncated = (pos < textLen);
+        
         // If we didn't end on a full line, still count it
         if (px > 0) {
           y += lineHeight;
         }
         
         y += 2;  // Small gap between messages
+        
+        // Erase excess highlight below the actual message.
+        // The upfront fillRect covered a max area; restore the unused
+        // portion back to background so subsequent messages render cleanly.
+        if (isSelected) {
+          int usedH = y - yStart;
+          int maxFillH = (maxLinesPerMsg + 1) * lineHeight + 2;
+          int availH = maxY - yStart;
+          if (maxFillH > availH) maxFillH = availH;
+          if (usedH < maxFillH) {
+            display.setColor(DisplayDriver::DARK);
+            display.fillRect(0, y + 5, contentW, maxFillH - usedH);
+          }
+        }
+        
         msgsDrawn++;
-        _msgsPerPage = msgsDrawn;
+        if (y + lineHeight > maxY) screenFull = true;
+      }
+      
+      // Only update _msgsPerPage when at the bottom (scrollPos==0) and the
+      // screen actually filled up.  While scrolled, freezing _msgsPerPage
+      // prevents a feedback loop where variable-height messages cause
+      // msgsPerPage to oscillate, shifting startIdx every render (flicker).
+      if (screenFull && msgsDrawn > 0 && _scrollPos == 0) {
+        // If the last message was truncated (text clipped by footer), exclude it
+        // from the page count so next render starts one message later and the
+        // bottom message fits completely.
+        int effectiveDrawn = lastMsgTruncated ? msgsDrawn - 1 : msgsDrawn;
+        if (effectiveDrawn < 1) effectiveDrawn = 1;
+        _msgsPerPage = effectiveDrawn;
+      }
+      
+      // --- Scroll bar (emoji picker style) ---
+      int sbX = display.width() - scrollBarW;
+      int sbTop = headerHeight;
+      int sbHeight = maxY - headerHeight;
+      
+      // Draw track outline
+      display.setColor(DisplayDriver::LIGHT);
+      display.drawRect(sbX, sbTop, scrollBarW, sbHeight);
+      
+      if (channelMsgCount > _msgsPerPage) {
+        // Scrollable: draw proportional thumb
+        int maxScroll = channelMsgCount - _msgsPerPage;
+        if (maxScroll < 1) maxScroll = 1;
+        int thumbH = (_msgsPerPage * sbHeight) / channelMsgCount;
+        if (thumbH < 4) thumbH = 4;
+        // _scrollPos=0 is newest (bottom), so invert for thumb position
+        int thumbY = sbTop + ((maxScroll - _scrollPos) * (sbHeight - thumbH)) / maxScroll;
+        for (int ty = thumbY + 1; ty < thumbY + thumbH - 1; ty++)
+          display.drawRect(sbX + 1, ty, scrollBarW - 2, 1);
+      } else {
+        // All messages fit: fill entire track
+        for (int ty = sbTop + 1; ty < sbTop + sbHeight - 1; ty++)
+          display.drawRect(sbX + 1, ty, scrollBarW - 2, 1);
       }
       
       display.setTextSize(1);  // Restore for footer
@@ -302,13 +910,18 @@ public:
     display.setCursor(0, footerY);
     display.setColor(DisplayDriver::YELLOW);
     
-    // Left side: Q:Back A/D:Ch
-    display.print("Q:Back A/D:Ch");
-    
-    // Right side: C:New
-    const char* rightText = "C:New";
-    display.setCursor(display.width() - display.getTextWidth(rightText) - 2, footerY);
-    display.print(rightText);
+    // Left side: abbreviated controls
+    if (_replySelectMode) {
+      display.print("W/S:Sel V:Pth Q:X");
+      const char* rightText = "Ent:Reply";
+      display.setCursor(display.width() - display.getTextWidth(rightText) - 2, footerY);
+      display.print(rightText);
+    } else {
+      display.print("Q:Bck A/D:Ch R:Rply");
+      const char* rightText = "Ent:New";
+      display.setCursor(display.width() - display.getTextWidth(rightText) - 2, footerY);
+      display.print(rightText);
+    }
 
 #if AUTO_OFF_MILLIS == 0  // e-ink
     return 5000;
@@ -318,7 +931,111 @@ public:
   }
 
   bool handleInput(char c) override {
+    // If overlay is showing, handle scroll and dismiss
+    if (_showPathOverlay) {
+      if (c == 'q' || c == 'Q' || c == '\b' || c == 'v' || c == 'V') {
+        _showPathOverlay = false;
+        _pathScrollPos = 0;
+        return true;
+      }
+      if (c == '\r' || c == 13) {
+        return false;  // Let main.cpp handle Enter for copy-to-compose
+      }
+      // W - scroll up in hop list
+      if (c == 'w' || c == 'W' || c == 0xF2) {
+        if (_pathScrollPos > 0) {
+          _pathScrollPos--;
+        }
+        return true;
+      }
+      // S - scroll down in hop list
+      if (c == 's' || c == 'S' || c == 0xF1) {
+        ChannelMessage* msg = getNewestReceivedMsg();
+        if (msg && msg->path_len > 0 && msg->path_len != 0xFF) {
+          int totalHops = msg->path_len < MSG_PATH_MAX ? msg->path_len : MSG_PATH_MAX;
+          if (_pathScrollPos < totalHops - _pathHopsVisible) {
+            _pathScrollPos++;
+          }
+        }
+        return true;
+      }
+      return true;  // Consume all other keys while overlay is up
+    }
+
+    // --- Reply select mode ---
+    if (_replySelectMode) {
+      // Q - exit reply select
+      if (c == 'q' || c == 'Q' || c == '\b') {
+        _replySelectMode = false;
+        _replySelectPos = -1;
+        return true;
+      }
+      // W - select older message (lower index in chronological order)
+      if (c == 'w' || c == 'W' || c == 0xF2) {
+        if (_replySelectPos > 0) {
+          _replySelectPos--;
+          // Auto-scroll to keep selection visible
+          int startIdx = _replyChannelMsgCount - _msgsPerPage - _scrollPos;
+          if (startIdx < 0) startIdx = 0;
+          if (_replySelectPos < startIdx) {
+            _scrollPos++;
+          }
+        }
+        return true;
+      }
+      // S - select newer message (higher index in chronological order)
+      if (c == 's' || c == 'S' || c == 0xF1) {
+        if (_replySelectPos < _replyChannelMsgCount - 1) {
+          _replySelectPos++;
+          // Auto-scroll to keep selection visible
+          int endIdx = _replyChannelMsgCount - _scrollPos;
+          if (_replySelectPos >= endIdx) {
+            if (_scrollPos > 0) _scrollPos--;
+          }
+        }
+        return true;
+      }
+      // V - view path for the SELECTED message (not just newest received)
+      if (c == 'v' || c == 'V') {
+        // Path overlay will use getNewestReceivedMsg() — for v1 this is fine.
+        // The user can see the selected message's hop count in the > marker.
+        ChannelMessage* selMsg = getReplySelectMsg();
+        if (selMsg && selMsg->path_len != 0) {
+          _showPathOverlay = true;
+          _pathScrollPos = 0;
+        }
+        return true;
+      }
+      // Enter - let main.cpp handle (enters compose with @mention)
+      if (c == '\r' || c == 13) {
+        return false;
+      }
+      return true;  // Consume all other keys in reply select
+    }
+
     int channelMsgCount = getMessageCountForChannel();
+
+    // R - enter reply select mode
+    if (c == 'r' || c == 'R') {
+      if (channelMsgCount > 0) {
+        _replySelectMode = true;
+        // Start with newest message selected
+        _replySelectPos = _replyChannelMsgCount > 0
+                            ? _replyChannelMsgCount - 1 : channelMsgCount - 1;
+        return true;
+      }
+      return false;
+    }
+    
+    // V - show path detail for last received message
+    if (c == 'v' || c == 'V') {
+      if (getNewestReceivedMsg() != nullptr) {
+        _showPathOverlay = true;
+        _pathScrollPos = 0;
+        return true;
+      }
+      return false;  // No received messages to show
+    }
     
     // W or KEY_PREV - scroll up (older messages)
     if (c == 0xF2 || c == 'w' || c == 'W') {
@@ -338,6 +1055,8 @@ public:
     
     // A - previous channel
     if (c == 'a' || c == 'A') {
+      _replySelectMode = false;
+      _replySelectPos = -1;
       if (_viewChannelIdx > 0) {
         _viewChannelIdx--;
       } else {
@@ -351,11 +1070,14 @@ public:
         }
       }
       _scrollPos = 0;
+      markChannelRead(_viewChannelIdx);
       return true;
     }
     
     // D - next channel
     if (c == 'd' || c == 'D') {
+      _replySelectMode = false;
+      _replySelectPos = -1;
       ChannelDetails ch;
       uint8_t nextIdx = _viewChannelIdx + 1;
       if (the_mesh.getChannel(nextIdx, ch) && ch.name[0] != '\0') {
@@ -364,6 +1086,7 @@ public:
         _viewChannelIdx = 0;
       }
       _scrollPos = 0;
+      markChannelRead(_viewChannelIdx);
       return true;
     }
     

examples/companion_radio/ui-new/Contactsscreen.h

@@ -18,6 +18,7 @@ public:
     FILTER_REPEATER,
     FILTER_ROOM,       // Room servers
     FILTER_SENSOR,
+    FILTER_FAVOURITE,  // Contacts marked as favourite (any type)
     FILTER_COUNT       // keep last
   };
 
@@ -30,9 +31,9 @@ private:
 
   // Cached filtered contact indices for efficient scrolling
   // We rebuild this on filter change or when entering the screen
-  static const int MAX_VISIBLE = 400;  // matches MAX_CONTACTS build flag
-  uint16_t _filteredIdx[MAX_VISIBLE];  // indices into contact table
-  uint32_t _filteredTs[MAX_VISIBLE];   // cached last_advert_timestamp for sorting
+  // Arrays allocated in PSRAM when available (supports 1000+ contacts)
+  uint16_t* _filteredIdx;    // indices into contact table
+  uint32_t* _filteredTs;     // cached last_advert_timestamp for sorting
   int _filteredCount;                  // how many contacts match current filter
   bool _cacheValid;
 
@@ -48,6 +49,7 @@ private:
       case FILTER_REPEATER:  return "Rptr";
       case FILTER_ROOM:      return "Room";
       case FILTER_SENSOR:    return "Sens";
+      case FILTER_FAVOURITE: return "Fav";
       default:               return "?";
     }
   }
@@ -61,7 +63,7 @@ private:
     }
   }
 
-  bool matchesFilter(uint8_t adv_type) const {
+  bool matchesFilter(uint8_t adv_type, uint8_t flags = 0) const {
     switch (_filter) {
       case FILTER_ALL:       return true;
       case FILTER_CHAT:      return adv_type == ADV_TYPE_CHAT;
@@ -70,6 +72,7 @@ private:
       case FILTER_SENSOR:    return (adv_type != ADV_TYPE_CHAT &&
                                      adv_type != ADV_TYPE_REPEATER &&
                                      adv_type != ADV_TYPE_ROOM);
+      case FILTER_FAVOURITE: return (flags & 0x01) != 0;
       default:               return true;
     }
   }
@@ -78,9 +81,9 @@ private:
     _filteredCount = 0;
     uint32_t numContacts = the_mesh.getNumContacts();
     ContactInfo contact;
-    for (uint32_t i = 0; i < numContacts && _filteredCount < MAX_VISIBLE; i++) {
+    for (uint32_t i = 0; i < numContacts && _filteredCount < MAX_CONTACTS; i++) {
       if (the_mesh.getContactByIdx(i, contact)) {
-        if (matchesFilter(contact.type)) {
+        if (matchesFilter(contact.type, contact.flags)) {
           _filteredIdx[_filteredCount] = (uint16_t)i;
           _filteredTs[_filteredCount] = contact.last_advert_timestamp;
           _filteredCount++;
@@ -88,7 +91,7 @@ private:
       }
     }
     // Sort by last_advert_timestamp descending (most recently seen first)
-    // Simple insertion sort — fine for up to 400 entries on ESP32
+    // Insertion sort — fine for up to ~1000 entries on ESP32
     for (int i = 1; i < _filteredCount; i++) {
       uint16_t tmpIdx = _filteredIdx[i];
       uint32_t tmpTs  = _filteredTs[i];
@@ -130,7 +133,15 @@ private:
 public:
   ContactsScreen(UITask* task, mesh::RTCClock* rtc)
     : _task(task), _rtc(rtc), _scrollPos(0), _filter(FILTER_ALL),
-      _filteredCount(0), _cacheValid(false), _rowsPerPage(5) {}
+      _filteredCount(0), _cacheValid(false), _rowsPerPage(5) {
+  #if defined(ESP32) && defined(BOARD_HAS_PSRAM)
+    _filteredIdx = (uint16_t*)ps_calloc(MAX_CONTACTS, sizeof(uint16_t));
+    _filteredTs = (uint32_t*)ps_calloc(MAX_CONTACTS, sizeof(uint32_t));
+  #else
+    _filteredIdx = new uint16_t[MAX_CONTACTS]();
+    _filteredTs = new uint32_t[MAX_CONTACTS]();
+  #endif
+  }
 
   void invalidateCache() { _cacheValid = false; }
 
@@ -180,8 +191,12 @@ public:
     snprintf(tmp, sizeof(tmp), "Contacts [%s]", filterLabel(_filter));
     display.print(tmp);
 
-    // Count on right
-    snprintf(tmp, sizeof(tmp), "%d/%d", _filteredCount, (int)the_mesh.getNumContacts());
+    // Count on right: All → total/max, filtered → matched/total
+    if (_filter == FILTER_ALL) {
+      snprintf(tmp, sizeof(tmp), "%d/%d", (int)the_mesh.getNumContacts(), MAX_CONTACTS);
+    } else {
+      snprintf(tmp, sizeof(tmp), "%d/%d", _filteredCount, (int)the_mesh.getNumContacts());
+    }
     display.setCursor(display.width() - display.getTextWidth(tmp) - 2, 0);
     display.print(tmp);
 
@@ -282,17 +297,17 @@ public:
     display.drawRect(0, footerY - 2, display.width(), 1);
     display.setColor(DisplayDriver::YELLOW);
 
-    // Left: Q:Back
+    // Left: Q:Bk
     display.setCursor(0, footerY);
-    display.print("Q:Back");
+    display.print("Q:Bk");
 
     // Center: A/D:Filter
     const char* mid = "A/D:Filtr";
     display.setCursor((display.width() - display.getTextWidth(mid)) / 2, footerY);
     display.print(mid);
 
-    // Right: W/S:Scroll
-    const char* right = "W/S:Scrll";
+    // Right: F:Dscvr
+    const char* right = "F:Dscvr";
     display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
     display.print(right);
 

examples/companion_radio/ui-new/Discoveryscreen.h

@@ -0,0 +1,205 @@
+#pragma once
+
+#include <helpers/ui/UIScreen.h>
+#include <helpers/ui/DisplayDriver.h>
+#include <helpers/AdvertDataHelpers.h>
+#include <MeshCore.h>
+
+// Forward declarations
+class UITask;
+class MyMesh;
+extern MyMesh the_mesh;
+
+class DiscoveryScreen : public UIScreen {
+  UITask* _task;
+  mesh::RTCClock* _rtc;
+  int _scrollPos;
+  int _rowsPerPage;
+
+  static char typeChar(uint8_t adv_type) {
+    switch (adv_type) {
+      case ADV_TYPE_CHAT:     return 'C';
+      case ADV_TYPE_REPEATER: return 'R';
+      case ADV_TYPE_ROOM:     return 'S';
+      case ADV_TYPE_SENSOR:   return 'N';
+      default:                return '?';
+    }
+  }
+
+  static const char* typeLabel(uint8_t adv_type) {
+    switch (adv_type) {
+      case ADV_TYPE_CHAT:     return "Chat";
+      case ADV_TYPE_REPEATER: return "Rptr";
+      case ADV_TYPE_ROOM:     return "Room";
+      case ADV_TYPE_SENSOR:   return "Sens";
+      default:                return "?";
+    }
+  }
+
+public:
+  DiscoveryScreen(UITask* task, mesh::RTCClock* rtc)
+    : _task(task), _rtc(rtc), _scrollPos(0), _rowsPerPage(5) {}
+
+  void resetScroll() { _scrollPos = 0; }
+
+  int getSelectedIdx() const { return _scrollPos; }
+
+  int render(DisplayDriver& display) override {
+    int count = the_mesh.getDiscoveredCount();
+    bool active = the_mesh.isDiscoveryActive();
+
+    // === Header ===
+    display.setTextSize(1);
+    display.setColor(DisplayDriver::GREEN);
+    display.setCursor(0, 0);
+
+    char hdr[32];
+    if (active) {
+      snprintf(hdr, sizeof(hdr), "Scanning... %d found", count);
+    } else {
+      snprintf(hdr, sizeof(hdr), "Scan done: %d found", count);
+    }
+    display.print(hdr);
+
+    // Divider
+    display.drawRect(0, 11, display.width(), 1);
+
+    // === Body — discovered node rows ===
+    display.setTextSize(0);  // tiny font for compact rows
+    int lineHeight = 9;
+    int headerHeight = 14;
+    int footerHeight = 14;
+    int maxY = display.height() - footerHeight;
+    int y = headerHeight;
+    int rowsDrawn = 0;
+
+    if (count == 0) {
+      display.setColor(DisplayDriver::LIGHT);
+      display.setCursor(4, 28);
+      display.print(active ? "Listening for adverts..." : "No nodes found");
+      if (!active) {
+        display.setCursor(4, 38);
+        display.print("F: Scan again  Q: Back");
+      }
+    } else {
+      // Center visible window around selected item
+      int maxVisible = (maxY - headerHeight) / lineHeight;
+      if (maxVisible < 3) maxVisible = 3;
+      int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                                count - maxVisible));
+      int endIdx = min(count, startIdx + maxVisible);
+
+      for (int i = startIdx; i < endIdx && y + lineHeight <= maxY; i++) {
+        const DiscoveredNode& node = the_mesh.getDiscovered(i);
+        bool selected = (i == _scrollPos);
+
+        // Highlight selected row
+        if (selected) {
+          display.setColor(DisplayDriver::LIGHT);
+          display.fillRect(0, y + 5, display.width(), lineHeight);
+          display.setColor(DisplayDriver::DARK);
+        } else {
+          display.setColor(DisplayDriver::LIGHT);
+        }
+
+        display.setCursor(0, y);
+
+        // Prefix: cursor + type
+        char prefix[4];
+        if (selected) {
+          snprintf(prefix, sizeof(prefix), ">%c", typeChar(node.contact.type));
+        } else {
+          snprintf(prefix, sizeof(prefix), " %c", typeChar(node.contact.type));
+        }
+        display.print(prefix);
+
+        // Build right-side info: SNR or hop count + status
+        char rightStr[16];
+        if (node.snr != 0) {
+          // Active discovery result — show SNR in dB (value is ×4 scaled)
+          int snr_db = node.snr / 4;
+          if (node.already_in_contacts) {
+            snprintf(rightStr, sizeof(rightStr), "%ddB [+]", snr_db);
+          } else {
+            snprintf(rightStr, sizeof(rightStr), "%ddB", snr_db);
+          }
+        } else {
+          // Pre-seeded from cache — show hop count
+          if (node.already_in_contacts) {
+            snprintf(rightStr, sizeof(rightStr), "%dh [+]", node.path_len);
+          } else {
+            snprintf(rightStr, sizeof(rightStr), "%dh", node.path_len);
+          }
+        }
+        int rightWidth = display.getTextWidth(rightStr) + 2;
+
+        // Name (truncated with ellipsis)
+        char filteredName[32];
+        display.translateUTF8ToBlocks(filteredName, node.contact.name, sizeof(filteredName));
+        int nameX = display.getTextWidth(prefix) + 2;
+        int nameMaxW = display.width() - nameX - rightWidth - 2;
+        display.drawTextEllipsized(nameX, y, nameMaxW, filteredName);
+
+        // Right-aligned info
+        display.setCursor(display.width() - rightWidth, y);
+        display.print(rightStr);
+
+        y += lineHeight;
+        rowsDrawn++;
+      }
+      _rowsPerPage = (rowsDrawn > 0) ? rowsDrawn : 1;
+    }
+
+    display.setTextSize(1);  // restore for footer
+
+    // === Footer ===
+    int footerY = display.height() - 12;
+    display.drawRect(0, footerY - 2, display.width(), 1);
+    display.setColor(DisplayDriver::YELLOW);
+
+    display.setCursor(0, footerY);
+    display.print("Q:Back");
+
+    const char* mid = "Ent:Add";
+    display.setCursor((display.width() - display.getTextWidth(mid)) / 2, footerY);
+    display.print(mid);
+
+    const char* right = "F:Rescan";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+
+    // Faster refresh while actively scanning
+    return active ? 1000 : 5000;
+  }
+
+  bool handleInput(char c) override {
+    int count = the_mesh.getDiscoveredCount();
+
+    // W - scroll up
+    if (c == 'w' || c == 'W' || c == 0xF2) {
+      if (_scrollPos > 0) {
+        _scrollPos--;
+        return true;
+      }
+    }
+
+    // S - scroll down
+    if (c == 's' || c == 'S' || c == 0xF1) {
+      if (_scrollPos < count - 1) {
+        _scrollPos++;
+        return true;
+      }
+    }
+
+    // F - rescan (handled here as well as in main.cpp for consistency)
+    if (c == 'f') {
+      the_mesh.startDiscovery();
+      _scrollPos = 0;
+      return true;
+    }
+
+    // Enter - handled by main.cpp for alert feedback
+
+    return false;  // Q/back and Enter handled by main.cpp
+  }
+};

examples/companion_radio/ui-new/Emojisprites.h

@@ -3,7 +3,7 @@
 // Emoji sprites for e-ink display - dual size
 // Large (12x12) for compose/picker, Small (10x10) for channel view
 // MSB-first, 2 bytes per row
-// 46 total emoji: joy/thumbsup/frown first, then 43 original (telephone removed)
+// 65 total emoji: joy/thumbsup/frown first, then 43 original, then 19 new
 
 #include <stdint.h>
 #ifdef ESP32
@@ -15,11 +15,11 @@
 #define EMOJI_SM_W 10
 #define EMOJI_SM_H 10
 
-#define EMOJI_COUNT 46
+#define EMOJI_COUNT 65
 
 // Escape codes in 0x80+ range - safe from keyboard ASCII (32-126)
 #define EMOJI_ESCAPE_START 0x80
-#define EMOJI_ESCAPE_END   0xAD   // 0x80 + 45
+#define EMOJI_ESCAPE_END   0xC0   // 0x80 + 64
 #define EMOJI_PAD_BYTE     0x7F   // DEL, not typeable (key < 127 guard)
 
 // ======== LARGE 12x12 SPRITES ========
@@ -208,6 +208,82 @@ static const uint8_t emoji_lg_peach[] PROGMEM = {
 static const uint8_t emoji_lg_racing_car[] PROGMEM = {
   0x00,0x00, 0x00,0x00, 0x00,0x00, 0x07,0x80, 0x0F,0xC0, 0x7F,0xE0, 0xFF,0xF0, 0xFF,0xF0, 0x6F,0x60, 0x49,0x20, 0x00,0x00, 0x00,0x00,
 };
+// [46] mouse 🐭
+static const uint8_t emoji_lg_mouse[] PROGMEM = {
+  0x30,0xC0, 0x79,0xE0, 0x79,0xE0, 0x3F,0xC0, 0x49,0x20, 0x80,0x10, 0x86,0x10, 0x89,0x10, 0x40,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [47] mushroom 🍄
+static const uint8_t emoji_lg_mushroom[] PROGMEM = {
+  0x1F,0x80, 0x3F,0xC0, 0x7F,0xE0, 0xE6,0x70, 0xE6,0x70, 0x7F,0xE0, 0x3F,0xC0, 0x0F,0x00, 0x0F,0x00, 0x0F,0x00, 0x1F,0x80, 0x00,0x00,
+};
+// [48] biohazard ☣️
+static const uint8_t emoji_lg_biohazard[] PROGMEM = {
+  0x0F,0x00, 0x1F,0x80, 0x3F,0xC0, 0x1F,0x80, 0x0F,0x00, 0x66,0x60, 0x76,0xE0, 0x70,0xE0, 0x79,0xE0, 0x39,0xC0, 0x19,0x80, 0x00,0x00,
+};
+// [49] panda 🐼
+static const uint8_t emoji_lg_panda[] PROGMEM = {
+  0x00,0x00, 0x60,0x60, 0xF0,0xF0, 0xF0,0xF0, 0x7F,0xE0, 0x59,0xA0, 0x59,0xA0, 0x40,0x20, 0x46,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [50] anger 💢
+static const uint8_t emoji_lg_anger[] PROGMEM = {
+  0x00,0x00, 0x3C,0xC0, 0x3C,0xC0, 0x30,0xC0, 0x30,0x00, 0x00,0x00, 0x00,0x00, 0x00,0xC0, 0x30,0xC0, 0x33,0xC0, 0x33,0xC0, 0x00,0x00,
+};
+// [51] dragon_face 🐲
+static const uint8_t emoji_lg_dragon_face[] PROGMEM = {
+  0xC0,0x30, 0xE0,0x70, 0x76,0xE0, 0x3F,0xC0, 0x69,0x60, 0x40,0x20, 0x4F,0x20, 0x29,0x40, 0x30,0xC0, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [52] pager 📟
+static const uint8_t emoji_lg_pager[] PROGMEM = {
+  0x00,0x00, 0x7F,0xE0, 0x40,0x20, 0x5F,0xA0, 0x5F,0xA0, 0x40,0x20, 0x5B,0x20, 0x5B,0x20, 0x40,0x20, 0x7F,0xE0, 0x00,0x00, 0x00,0x00,
+};
+// [53] bee 🐝
+static const uint8_t emoji_lg_bee[] PROGMEM = {
+  0x00,0x00, 0x19,0x80, 0x19,0x80, 0x3F,0x80, 0x7F,0xC0, 0x7F,0xE0, 0x7F,0xE0, 0x7F,0xC0, 0x3F,0x80, 0x1F,0x40, 0x0A,0x00, 0x00,0x00,
+};
+// [54] bulb 💡
+static const uint8_t emoji_lg_bulb[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x40,0x20, 0x40,0x20, 0x40,0x20, 0x20,0x40, 0x30,0xC0, 0x1F,0x80, 0x16,0x80, 0x1F,0x80, 0x0F,0x00, 0x00,0x00,
+};
+// [55] cat 🐱
+static const uint8_t emoji_lg_cat[] PROGMEM = {
+  0x40,0x20, 0x60,0x60, 0x70,0xE0, 0x3F,0xC0, 0x59,0xA0, 0x40,0x20, 0x40,0x20, 0x46,0x20, 0x29,0x40, 0x30,0xC0, 0x1F,0x80, 0x00,0x00,
+};
+// [56] fleur ⚜️
+static const uint8_t emoji_lg_fleur[] PROGMEM = {
+  0x06,0x00, 0x06,0x00, 0x0F,0x00, 0x6F,0x60, 0xF6,0xF0, 0xF6,0xF0, 0x76,0xE0, 0x3F,0xC0, 0x1F,0x80, 0x0F,0x00, 0x19,0x80, 0x00,0x00,
+};
+// [57] moon 🌔
+static const uint8_t emoji_lg_moon[] PROGMEM = {
+  0x1F,0x80, 0x3F,0xC0, 0x7F,0xE0, 0x7F,0x80, 0xFF,0x80, 0xFF,0x00, 0xFF,0x00, 0xFF,0x80, 0x7F,0x80, 0x7F,0xE0, 0x3F,0xC0, 0x1F,0x80,
+};
+// [58] coffee ☕
+static const uint8_t emoji_lg_coffee[] PROGMEM = {
+  0x24,0x80, 0x12,0x40, 0x00,0x00, 0x7F,0xC0, 0x40,0x70, 0x40,0x50, 0x40,0x50, 0x40,0x70, 0x7F,0xC0, 0x00,0x00, 0xFF,0xC0, 0x00,0x00,
+};
+// [59] tooth 🦷
+static const uint8_t emoji_lg_tooth[] PROGMEM = {
+  0x3F,0xC0, 0x7F,0xE0, 0xFF,0xF0, 0xFF,0xF0, 0xFF,0xF0, 0x7F,0xE0, 0x3F,0xC0, 0x3F,0xC0, 0x39,0xC0, 0x39,0xC0, 0x30,0xC0, 0x20,0x40,
+};
+// [60] pretzel 🥨
+static const uint8_t emoji_lg_pretzel[] PROGMEM = {
+  0x39,0xC0, 0x46,0x20, 0x80,0x20, 0x86,0x10, 0x49,0x20, 0x30,0xC0, 0x30,0xC0, 0x49,0x20, 0x86,0x10, 0x80,0x10, 0x46,0x20, 0x39,0xC0,
+};
+// [61] abacus 🧮
+static const uint8_t emoji_lg_abacus[] PROGMEM = {
+  0xFF,0xF0, 0x80,0x10, 0xB6,0x50, 0x80,0x10, 0xA6,0x90, 0x80,0x10, 0x94,0xD0, 0x80,0x10, 0xB2,0x50, 0x80,0x10, 0xFF,0xF0, 0x00,0x00,
+};
+// [62] moai 🗿
+static const uint8_t emoji_lg_moai[] PROGMEM = {
+  0x3F,0xC0, 0x7F,0xC0, 0x7F,0xC0, 0x39,0xC0, 0x39,0xC0, 0x3F,0xC0, 0x27,0x40, 0x3F,0x80, 0x2F,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00,
+};
+// [63] tipping 💁
+static const uint8_t emoji_lg_tipping[] PROGMEM = {
+  0x1E,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00, 0x0C,0x00, 0x1E,0x00, 0x3F,0x00, 0x7F,0x80, 0x0C,0xE0, 0x0D,0xE0, 0x12,0xE0, 0x33,0x00,
+};
+// [64] hedgehog 🦔
+static const uint8_t emoji_lg_hedgehog[] PROGMEM = {
+  0x00,0x00, 0x0A,0x80, 0x15,0x40, 0x2A,0xA0, 0x55,0x60, 0x7E,0xF0, 0xDB,0x90, 0xFF,0xD0, 0x7F,0xE0, 0x3F,0xC0, 0x24,0x80, 0x00,0x00,
+};
 
 static const uint8_t* const EMOJI_SPRITES_LG[] PROGMEM = {
   emoji_lg_joy, emoji_lg_thumbsup, emoji_lg_frown,
@@ -220,6 +296,11 @@ static const uint8_t* const EMOJI_SPRITES_LG[] PROGMEM = {
   emoji_lg_kangaroo, emoji_lg_feather, emoji_lg_bright, emoji_lg_part_alt, emoji_lg_motorboat,
   emoji_lg_domino, emoji_lg_satellite, emoji_lg_customs, emoji_lg_cowboy, emoji_lg_wheel,
   emoji_lg_koala, emoji_lg_control_knobs, emoji_lg_peach, emoji_lg_racing_car,
+  emoji_lg_mouse, emoji_lg_mushroom, emoji_lg_biohazard, emoji_lg_panda,
+  emoji_lg_anger, emoji_lg_dragon_face, emoji_lg_pager, emoji_lg_bee,
+  emoji_lg_bulb, emoji_lg_cat, emoji_lg_fleur, emoji_lg_moon,
+  emoji_lg_coffee, emoji_lg_tooth, emoji_lg_pretzel, emoji_lg_abacus,
+  emoji_lg_moai, emoji_lg_tipping, emoji_lg_hedgehog,
 };
 
 // ======== SMALL 10x10 SPRITES ========
@@ -362,6 +443,82 @@ static const uint8_t emoji_sm_peach[] PROGMEM = {
 static const uint8_t emoji_sm_racing_car[] PROGMEM = {
   0x00,0x00, 0x00,0x00, 0x0E,0x00, 0x1F,0x00, 0x7F,0x80, 0xFF,0xC0, 0xFF,0xC0, 0x5E,0x80, 0x00,0x00, 0x00,0x00,
 };
+// [46] mouse 🐭
+static const uint8_t emoji_sm_mouse[] PROGMEM = {
+  0x61,0x80, 0xF3,0xC0, 0x7F,0x80, 0x92,0x40, 0x80,0x40, 0x8C,0x40, 0x52,0x80, 0x40,0x80, 0x3F,0x00, 0x00,0x00,
+};
+// [47] mushroom 🍄
+static const uint8_t emoji_sm_mushroom[] PROGMEM = {
+  0x3F,0x00, 0x7F,0x80, 0xED,0xC0, 0xED,0xC0, 0x7F,0x80, 0x3F,0x00, 0x1E,0x00, 0x1E,0x00, 0x3F,0x00, 0x00,0x00,
+};
+// [48] biohazard ☣️
+static const uint8_t emoji_sm_biohazard[] PROGMEM = {
+  0x1E,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00, 0x6D,0x80, 0x73,0x80, 0x73,0x80, 0x7B,0x80, 0x33,0x00, 0x00,0x00,
+};
+// [49] panda 🐼
+static const uint8_t emoji_sm_panda[] PROGMEM = {
+  0xC0,0xC0, 0xF3,0xC0, 0x7F,0x80, 0xB3,0x40, 0xB3,0x40, 0x80,0x40, 0x4C,0x80, 0x21,0x00, 0x3F,0x00, 0x00,0x00,
+};
+// [50] anger 💢
+static const uint8_t emoji_sm_anger[] PROGMEM = {
+  0x00,0x00, 0x73,0x00, 0x73,0x00, 0x63,0x00, 0x60,0x00, 0x01,0x80, 0x63,0x00, 0x67,0x00, 0x67,0x00, 0x00,0x00,
+};
+// [51] dragon_face 🐲
+static const uint8_t emoji_sm_dragon_face[] PROGMEM = {
+  0xC0,0xC0, 0xED,0xC0, 0x7F,0x80, 0x52,0x80, 0x40,0x80, 0x4C,0x80, 0x33,0x00, 0x2D,0x00, 0x1E,0x00, 0x00,0x00,
+};
+// [52] pager 📟
+static const uint8_t emoji_sm_pager[] PROGMEM = {
+  0x00,0x00, 0x7F,0x80, 0x40,0x80, 0x5E,0x80, 0x40,0x80, 0x5A,0x80, 0x5A,0x80, 0x40,0x80, 0x7F,0x80, 0x00,0x00,
+};
+// [53] bee 🐝
+static const uint8_t emoji_sm_bee[] PROGMEM = {
+  0x33,0x00, 0x33,0x00, 0x7F,0x00, 0xFF,0x80, 0xFF,0xC0, 0xFF,0x80, 0x7F,0x00, 0x3E,0x80, 0x14,0x00, 0x00,0x00,
+};
+// [54] bulb 💡
+static const uint8_t emoji_sm_bulb[] PROGMEM = {
+  0x3F,0x00, 0x40,0x80, 0x80,0x40, 0x80,0x40, 0x40,0x80, 0x33,0x00, 0x3F,0x00, 0x1E,0x00, 0x1E,0x00, 0x00,0x00,
+};
+// [55] cat 🐱
+static const uint8_t emoji_sm_cat[] PROGMEM = {
+  0x80,0x40, 0xC0,0xC0, 0x7F,0x80, 0xB3,0x40, 0x80,0x40, 0x8C,0x40, 0x52,0x80, 0x61,0x80, 0x3F,0x00, 0x00,0x00,
+};
+// [56] fleur ⚜️
+static const uint8_t emoji_sm_fleur[] PROGMEM = {
+  0x0C,0x00, 0x0C,0x00, 0x6D,0x80, 0xED,0xC0, 0xED,0xC0, 0x6D,0x80, 0x3F,0x00, 0x1E,0x00, 0x33,0x00, 0x00,0x00,
+};
+// [57] moon 🌔
+static const uint8_t emoji_sm_moon[] PROGMEM = {
+  0x3F,0x00, 0x7F,0x80, 0xFF,0x80, 0xFE,0x00, 0xFE,0x00, 0xFE,0x00, 0xFE,0x00, 0xFF,0x80, 0x7F,0x80, 0x3F,0x00,
+};
+// [58] coffee ☕
+static const uint8_t emoji_sm_coffee[] PROGMEM = {
+  0x49,0x00, 0x24,0x80, 0x00,0x00, 0xFF,0x00, 0x81,0xC0, 0x81,0x40, 0x81,0xC0, 0xFF,0x00, 0x00,0x00, 0xFE,0x00,
+};
+// [59] tooth 🦷
+static const uint8_t emoji_sm_tooth[] PROGMEM = {
+  0x7F,0x80, 0xFF,0xC0, 0xFF,0xC0, 0xFF,0xC0, 0x7F,0x80, 0x3F,0x00, 0x3B,0x80, 0x31,0x80, 0x20,0x80, 0x00,0x00,
+};
+// [60] pretzel 🥨
+static const uint8_t emoji_sm_pretzel[] PROGMEM = {
+  0x73,0x80, 0x9E,0x40, 0x8C,0x40, 0x52,0x80, 0x33,0x00, 0x33,0x00, 0x52,0x80, 0x8C,0x40, 0x9E,0x40, 0x73,0x80,
+};
+// [61] abacus 🧮
+static const uint8_t emoji_sm_abacus[] PROGMEM = {
+  0xFF,0xC0, 0x80,0x40, 0xB5,0x40, 0x80,0x40, 0xAD,0x40, 0x80,0x40, 0xAB,0x40, 0x80,0x40, 0xFF,0xC0, 0x00,0x00,
+};
+// [62] moai 🗿
+static const uint8_t emoji_sm_moai[] PROGMEM = {
+  0x7F,0x00, 0x7F,0x00, 0x33,0x00, 0x33,0x00, 0x3F,0x00, 0x2E,0x00, 0x3E,0x00, 0x3E,0x00, 0x3E,0x00, 0x1C,0x00,
+};
+// [63] tipping 💁
+static const uint8_t emoji_sm_tipping[] PROGMEM = {
+  0x3C,0x00, 0x7E,0x00, 0x7E,0x00, 0x3C,0x00, 0x18,0x00, 0x3C,0x00, 0x7E,0x00, 0x1B,0x80, 0x1B,0x80, 0x36,0x00,
+};
+// [64] hedgehog 🦔
+static const uint8_t emoji_sm_hedgehog[] PROGMEM = {
+  0x15,0x00, 0x2A,0x80, 0x55,0x40, 0xFF,0xC0, 0xDB,0x40, 0xFF,0x80, 0x7F,0x80, 0x3F,0x00, 0x24,0x00, 0x00,0x00,
+};
 
 static const uint8_t* const EMOJI_SPRITES_SM[] PROGMEM = {
   emoji_sm_joy, emoji_sm_thumbsup, emoji_sm_frown,
@@ -374,6 +531,11 @@ static const uint8_t* const EMOJI_SPRITES_SM[] PROGMEM = {
   emoji_sm_kangaroo, emoji_sm_feather, emoji_sm_bright, emoji_sm_part_alt, emoji_sm_motorboat,
   emoji_sm_domino, emoji_sm_satellite, emoji_sm_customs, emoji_sm_cowboy, emoji_sm_wheel,
   emoji_sm_koala, emoji_sm_control_knobs, emoji_sm_peach, emoji_sm_racing_car,
+  emoji_sm_mouse, emoji_sm_mushroom, emoji_sm_biohazard, emoji_sm_panda,
+  emoji_sm_anger, emoji_sm_dragon_face, emoji_sm_pager, emoji_sm_bee,
+  emoji_sm_bulb, emoji_sm_cat, emoji_sm_fleur, emoji_sm_moon,
+  emoji_sm_coffee, emoji_sm_tooth, emoji_sm_pretzel, emoji_sm_abacus,
+  emoji_sm_moai, emoji_sm_tipping, emoji_sm_hedgehog,
 };
 
 // ---- Codepoint lookup for UTF-8 conversion ----
@@ -417,7 +579,7 @@ static const EmojiCodepoint EMOJI_CODEPOINTS[EMOJI_COUNT] = {
   { 0x1F506, 0x0000, 0xA2 }, // bright
   { 0x303D,  0x0000, 0xA3 }, // part_alt
   { 0x1F6E5, 0x0000, 0xA4 }, // motorboat
-  { 0x1F0CE, 0x0000, 0xA5 }, // domino
+  { 0x1F030, 0x0000, 0xA5 }, // domino
   { 0x1F4E1, 0x0000, 0xA6 }, // satellite
   { 0x1F6C3, 0x0000, 0xA7 }, // customs
   { 0x1F920, 0x0000, 0xA8 }, // cowboy
@@ -426,10 +588,37 @@ static const EmojiCodepoint EMOJI_CODEPOINTS[EMOJI_COUNT] = {
   { 0x1F39B, 0x0000, 0xAB }, // control_knobs
   { 0x1F351, 0x0000, 0xAC }, // peach
   { 0x1F3CE, 0x0000, 0xAD }, // racing_car
+  { 0x1F42D, 0x0000, 0xAE }, // mouse
+  { 0x1F344, 0x0000, 0xAF }, // mushroom
+  { 0x2623,  0x0000, 0xB0 }, // biohazard
+  { 0x1F43C, 0x0000, 0xB1 }, // panda
+  { 0x1F4A2, 0x0000, 0xB2 }, // anger
+  { 0x1F432, 0x0000, 0xB3 }, // dragon_face
+  { 0x1F4DF, 0x0000, 0xB4 }, // pager
+  { 0x1F41D, 0x0000, 0xB5 }, // bee
+  { 0x1F4A1, 0x0000, 0xB6 }, // bulb
+  { 0x1F431, 0x0000, 0xB7 }, // cat
+  { 0x269C,  0x0000, 0xB8 }, // fleur
+  { 0x1F314, 0x0000, 0xB9 }, // moon
+  { 0x2615,  0x0000, 0xBA }, // coffee
+  { 0x1F9B7, 0x0000, 0xBB }, // tooth
+  { 0x1F968, 0x0000, 0xBC }, // pretzel
+  { 0x1F9EE, 0x0000, 0xBD }, // abacus
+  { 0x1F5FF, 0x0000, 0xBE }, // moai
+  { 0x1F481, 0x0000, 0xBF }, // tipping
+  { 0x1F994, 0x0000, 0xC0 }, // hedgehog
 };
 
 // ---- Helper functions ----
 
+// Alias table: extra codepoints that map to existing emoji escape bytes.
+// Used for variant codepoints (e.g. MWD node identifier 🂎 U+1F08E -> domino sprite)
+struct EmojiAlias { uint32_t cp; uint8_t escape; };
+#define EMOJI_ALIAS_COUNT 1
+static const EmojiAlias EMOJI_ALIASES[EMOJI_ALIAS_COUNT] = {
+  { 0x1F08E, 0xA5 }, // domino tile (MWD node signifier) -> domino sprite
+};
+
 static uint32_t emojiDecodeUtf8(const uint8_t* s, int remaining, int* bytes_consumed) {
   uint8_t b0 = s[0];
   if (b0 < 0x80) { *bytes_consumed = 1; return b0; }
@@ -483,6 +672,18 @@ static void emojiSanitize(const char* src, char* dst, int dstLen) {
           found = true; break;
         }
       }
+      if (!found) {
+        // Check alias table for variant codepoints
+        for (int a = 0; a < EMOJI_ALIAS_COUNT; a++) {
+          if (EMOJI_ALIASES[a].cp == cp) {
+            dst[di++] = EMOJI_ALIASES[a].escape;
+            si += consumed;
+            // Skip trailing variation selector U+FE0F
+            if (si + 2 < srcLen && s[si] == 0xEF && s[si+1] == 0xB8 && s[si+2] == 0x8F) si += 3;
+            found = true; break;
+          }
+        }
+      }
       if (!found) si += consumed;  // Skip unknown multi-byte chars
     } else {
       dst[di++] = (char)b;

examples/companion_radio/ui-new/Epubprocessor.h

@@ -2,8 +2,8 @@
 // =============================================================================
 // EpubProcessor.h - Convert EPUB files to plain text for TextReaderScreen
 //
-// Pipeline: EPUB (ZIP) → container.xml → OPF spine → extract chapters →
-//           strip XHTML tags → concatenated plain text → cached .txt on SD
+// Pipeline: EPUB (ZIP) → container.xml → OPF spine → extract chapters →
+//           strip XHTML tags → concatenated plain text → cached .txt on SD
 //
 // The resulting .txt file is placed in /books/ and picked up automatically
 // by TextReaderScreen's existing pagination, indexing, and bookmarking.
@@ -14,6 +14,7 @@
 #include <SD.h>
 #include <FS.h>
 #include "EpubZipReader.h"
+#include "Utf8CP437.h"
 
 // Maximum chapters in spine (most novels have 20-80)
 #define EPUB_MAX_CHAPTERS 200
@@ -426,7 +427,7 @@ private:
   //
   // Handles:
   //   - Tag removal (everything between < and >)
-  //   - <p>, <br>, <div>, <h1>-<h6> → newlines
+  //   - <p>, <br>, <div>, <h1>-<h6> → newlines
   //   - HTML entity decoding (&amp; &lt; &gt; &quot; &apos; &#NNN; &#xHH;)
   //   - Collapse multiple whitespace/newlines
   //   - Skip <head>, <style>, <script> content entirely
@@ -547,9 +548,9 @@ private:
         }
       }
 
-      // Handle UTF-8 multi-byte sequences (smart quotes, em dashes, etc.)
-      // These appear as raw bytes in XHTML and must be mapped to ASCII
-      // since the e-ink font only supports ASCII characters.
+      // Handle UTF-8 multi-byte sequences (smart quotes, em dashes, accented chars, etc.)
+      // These appear as raw bytes in XHTML. Typographic chars are mapped to ASCII;
+      // accented Latin chars are preserved as UTF-8 for CP437 rendering on e-ink.
       if ((uint8_t)c >= 0xC0) {
         uint32_t codepoint = 0;
         int extraBytes = 0;
@@ -579,7 +580,8 @@ private:
         if (valid && extraBytes > 0) {
           p += extraBytes;  // Skip continuation bytes (loop increments past lead byte)
 
-          // Map Unicode codepoints to ASCII equivalents
+          // Map Unicode codepoints to displayable equivalents
+          // Typographic chars → ASCII, accented chars → preserved as UTF-8
           char mapped = 0;
           switch (codepoint) {
             case 0x2018: case 0x2019: mapped = '\''; break;  // Smart single quotes
@@ -598,6 +600,21 @@ private:
             default:
               if (codepoint >= 0x20 && codepoint < 0x7F) {
                 mapped = (char)codepoint;  // Basic ASCII range
+              } else if (unicodeToCP437(codepoint)) {
+                // Accented character that the e-ink font can render via CP437.
+                // Preserve as UTF-8 in the output; the text reader will decode
+                // and map to CP437 at render time.
+                if (codepoint <= 0x7FF) {
+                  output[outPos++] = 0xC0 | (codepoint >> 6);
+                  output[outPos++] = 0x80 | (codepoint & 0x3F);
+                } else if (codepoint <= 0xFFFF) {
+                  output[outPos++] = 0xE0 | (codepoint >> 12);
+                  output[outPos++] = 0x80 | ((codepoint >> 6) & 0x3F);
+                  output[outPos++] = 0x80 | (codepoint & 0x3F);
+                }
+                lastWasNewline = false;
+                lastWasSpace = false;
+                continue;  // Already wrote to output
               } else {
                 continue;  // Skip unmappable characters
               }
@@ -608,7 +625,7 @@ private:
           continue;  // Skip malformed UTF-8
         }
       } else if ((uint8_t)c >= 0x80) {
-        // Stray continuation byte (0x80-0xBF) — skip
+        // Stray continuation byte (0x80-0xBF) — skip
         continue;
       }
 
@@ -683,6 +700,37 @@ private:
     if (entityLen == 5 && strncmp(entity, "ldquo", 5) == 0) return '"';
     if (entityLen == 5 && strncmp(entity, "rdquo", 5) == 0) return '"';
 
+    // Common accented character entities → CP437 bytes for built-in font
+    if (entityLen == 6 && strncmp(entity, "eacute", 6) == 0) return (char)0x82;  // é
+    if (entityLen == 6 && strncmp(entity, "egrave", 6) == 0) return (char)0x8A;  // è
+    if (entityLen == 5 && strncmp(entity, "ecirc", 5) == 0) return (char)0x88;   // ê
+    if (entityLen == 4 && strncmp(entity, "euml", 4) == 0) return (char)0x89;    // ë
+    if (entityLen == 6 && strncmp(entity, "agrave", 6) == 0) return (char)0x85;  // à
+    if (entityLen == 6 && strncmp(entity, "aacute", 6) == 0) return (char)0xA0;  // á
+    if (entityLen == 5 && strncmp(entity, "acirc", 5) == 0) return (char)0x83;   // â
+    if (entityLen == 4 && strncmp(entity, "auml", 4) == 0) return (char)0x84;    // ä
+    if (entityLen == 6 && strncmp(entity, "ccedil", 6) == 0) return (char)0x87;  // ç
+    if (entityLen == 6 && strncmp(entity, "iacute", 6) == 0) return (char)0xA1;  // í
+    if (entityLen == 5 && strncmp(entity, "icirc", 5) == 0) return (char)0x8C;   // î
+    if (entityLen == 4 && strncmp(entity, "iuml", 4) == 0) return (char)0x8B;    // ï
+    if (entityLen == 6 && strncmp(entity, "igrave", 6) == 0) return (char)0x8D;  // ì
+    if (entityLen == 6 && strncmp(entity, "oacute", 6) == 0) return (char)0xA2;  // ó
+    if (entityLen == 5 && strncmp(entity, "ocirc", 5) == 0) return (char)0x93;   // ô
+    if (entityLen == 4 && strncmp(entity, "ouml", 4) == 0) return (char)0x94;    // ö
+    if (entityLen == 6 && strncmp(entity, "ograve", 6) == 0) return (char)0x95;  // ò
+    if (entityLen == 6 && strncmp(entity, "uacute", 6) == 0) return (char)0xA3;  // ú
+    if (entityLen == 5 && strncmp(entity, "ucirc", 5) == 0) return (char)0x96;   // û
+    if (entityLen == 4 && strncmp(entity, "uuml", 4) == 0) return (char)0x81;    // ü
+    if (entityLen == 6 && strncmp(entity, "ugrave", 6) == 0) return (char)0x97;  // ù
+    if (entityLen == 6 && strncmp(entity, "ntilde", 6) == 0) return (char)0xA4;  // ñ
+    if (entityLen == 6 && strncmp(entity, "Eacute", 6) == 0) return (char)0x90;  // É
+    if (entityLen == 6 && strncmp(entity, "Ccedil", 6) == 0) return (char)0x80;  // Ç
+    if (entityLen == 6 && strncmp(entity, "Ntilde", 6) == 0) return (char)0xA5;  // Ñ
+    if (entityLen == 4 && strncmp(entity, "Auml", 4) == 0) return (char)0x8E;    // Ä
+    if (entityLen == 4 && strncmp(entity, "Ouml", 4) == 0) return (char)0x99;    // Ö
+    if (entityLen == 4 && strncmp(entity, "Uuml", 4) == 0) return (char)0x9A;    // Ü
+    if (entityLen == 5 && strncmp(entity, "szlig", 5) == 0) return (char)0xE1;   // ß
+
     // Numeric entities: &#NNN; or &#xHH;
     if (entityLen >= 2 && entity[0] == '#') {
       int codepoint = 0;
@@ -701,14 +749,13 @@ private:
           if (ch >= '0' && ch <= '9') codepoint = codepoint * 10 + (ch - '0');
         }
       }
-      // Map to ASCII (best effort - e-ink font is ASCII only)
+      // Map to displayable character (best effort)
       if (codepoint >= 32 && codepoint < 127) return (char)codepoint;
       if (codepoint == 160) return ' ';   // non-breaking space
-      if (codepoint == 8211 || codepoint == 8212) return '-';  // en/em dash
-      if (codepoint == 8216 || codepoint == 8217) return '\''; // smart quotes
-      if (codepoint == 8220 || codepoint == 8221) return '"';  // smart quotes
-      if (codepoint == 8230) return '.';   // ellipsis
-      if (codepoint == 8226) return '*';   // bullet
+      // Try CP437 mapping for accented characters.
+      // The byte value will be passed through to the built-in font.
+      uint8_t cp437 = unicodeToCP437(codepoint);
+      if (cp437) return (char)cp437;
       // Unknown codepoint > 127: skip it
       return ' ';
     }

examples/companion_radio/ui-new/M4BMetadata.h

@@ -0,0 +1,651 @@
+#pragma once
+
+// =============================================================================
+// M4BMetadata.h - Lightweight MP4/M4B atom parser for metadata extraction
+//
+// Walks the MP4 atom (box) tree to extract:
+//   - Title     (moov/udta/meta/ilst/©nam)
+//   - Author    (moov/udta/meta/ilst/©ART)
+//   - Cover art (moov/udta/meta/ilst/covr) - JPEG offset+size within file
+//   - Duration  (moov/mvhd timescale + duration)
+//   - Chapter markers (moov/udta/chpl) - Nero-style chapter list
+//
+// Designed for embedded use: no dynamic allocation, reads directly from SD
+// via Arduino File API, uses a small stack buffer for atom headers.
+//
+// Usage:
+//   M4BMetadata meta;
+//   File f = SD.open("/audiobooks/mybook.m4b");
+//   if (meta.parse(f)) {
+//     Serial.printf("Title: %s\n", meta.title);
+//     Serial.printf("Author: %s\n", meta.author);
+//     if (meta.hasCoverArt) {
+//       // JPEG data is at meta.coverOffset, meta.coverSize bytes
+//     }
+//   }
+//   f.close();
+// =============================================================================
+
+#include <SD.h>
+
+// Maximum metadata string lengths (including null terminator)
+#define M4B_MAX_TITLE    128
+#define M4B_MAX_AUTHOR   64
+#define M4B_MAX_CHAPTERS 100
+
+struct M4BChapter {
+  uint32_t startMs;    // Chapter start time in milliseconds
+  char     name[48];   // Chapter title (truncated to fit)
+};
+
+class M4BMetadata {
+public:
+  // Extracted metadata
+  char     title[M4B_MAX_TITLE];
+  char     author[M4B_MAX_AUTHOR];
+  bool     hasCoverArt;
+  uint32_t coverOffset;   // Byte offset of JPEG/PNG data within file
+  uint32_t coverSize;     // Size of cover image data in bytes
+  uint8_t  coverFormat;   // 13=JPEG, 14=PNG (from MP4 well-known type)
+  uint32_t durationMs;    // Total duration in milliseconds
+  uint32_t sampleRate;    // Audio sample rate (from audio stsd)
+  uint32_t bitrate;       // Approximate bitrate in bps
+
+  // Chapter data
+  M4BChapter chapters[M4B_MAX_CHAPTERS];
+  int        chapterCount;
+
+  M4BMetadata() { clear(); }
+
+  void clear() {
+    title[0] = '\0';
+    author[0] = '\0';
+    hasCoverArt = false;
+    coverOffset = 0;
+    coverSize = 0;
+    coverFormat = 0;
+    durationMs = 0;
+    sampleRate = 44100;
+    bitrate = 0;
+    chapterCount = 0;
+  }
+
+  // Parse an open file. Returns true if at least title or duration was found.
+  // File position is NOT preserved — caller should seek as needed afterward.
+  bool parse(File& file) {
+    clear();
+    if (!file || file.size() < 8) return false;
+
+    _fileSize = file.size();
+
+    // Walk top-level atoms looking for 'moov'
+    uint32_t pos = 0;
+    while (pos < _fileSize) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_MOOV) {
+        parseMoov(file, hdr.dataOffset, hdr.dataOffset + hdr.dataSize);
+        break;  // moov found and parsed, we're done
+      }
+
+      // Skip to next top-level atom
+      pos += hdr.size;
+      if (hdr.size == 0) break;  // size=0 means "extends to EOF"
+    }
+
+    return (title[0] != '\0' || durationMs > 0);
+  }
+
+  // Get chapter index for a given playback position (milliseconds).
+  // Returns -1 if no chapters or position is before first chapter.
+  int getChapterForPosition(uint32_t positionMs) const {
+    if (chapterCount == 0) return -1;
+    int ch = 0;
+    for (int i = 1; i < chapterCount; i++) {
+      if (chapters[i].startMs > positionMs) break;
+      ch = i;
+    }
+    return ch;
+  }
+
+  // Get the start position of the next chapter after the given position.
+  // Returns 0 if no next chapter.
+  uint32_t getNextChapterMs(uint32_t positionMs) const {
+    for (int i = 0; i < chapterCount; i++) {
+      if (chapters[i].startMs > positionMs) return chapters[i].startMs;
+    }
+    return 0;
+  }
+
+  // Get the start position of the current or previous chapter.
+  uint32_t getPrevChapterMs(uint32_t positionMs) const {
+    uint32_t prev = 0;
+    for (int i = 0; i < chapterCount; i++) {
+      if (chapters[i].startMs >= positionMs) break;
+      prev = chapters[i].startMs;
+    }
+    return prev;
+  }
+
+private:
+  uint32_t _fileSize;
+
+  // MP4 atom type codes (big-endian FourCC)
+  static constexpr uint32_t ATOM_MOOV = 0x6D6F6F76;  // 'moov'
+  static constexpr uint32_t ATOM_MVHD = 0x6D766864;  // 'mvhd'
+  static constexpr uint32_t ATOM_UDTA = 0x75647461;  // 'udta'
+  static constexpr uint32_t ATOM_META = 0x6D657461;  // 'meta'
+  static constexpr uint32_t ATOM_ILST = 0x696C7374;  // 'ilst'
+  static constexpr uint32_t ATOM_NAM  = 0xA96E616D;  // '©nam'
+  static constexpr uint32_t ATOM_ART  = 0xA9415254;  // '©ART'
+  static constexpr uint32_t ATOM_COVR = 0x636F7672;  // 'covr'
+  static constexpr uint32_t ATOM_DATA = 0x64617461;  // 'data'
+  static constexpr uint32_t ATOM_CHPL = 0x6368706C;  // 'chpl' (Nero chapters)
+  static constexpr uint32_t ATOM_TRAK = 0x7472616B;  // 'trak'
+  static constexpr uint32_t ATOM_MDIA = 0x6D646961;  // 'mdia'
+  static constexpr uint32_t ATOM_MDHD = 0x6D646864;  // 'mdhd'
+  static constexpr uint32_t ATOM_HDLR = 0x68646C72;  // 'hdlr'
+
+  struct AtomHeader {
+    uint32_t type;
+    uint64_t size;        // Total atom size including header
+    uint32_t dataOffset;  // File offset where data begins (after header)
+    uint64_t dataSize;    // size - header_length
+  };
+
+  // Read a 32-bit big-endian value from file at current position
+  static uint32_t readU32BE(File& file) {
+    uint8_t buf[4];
+    file.read(buf, 4);
+    return ((uint32_t)buf[0] << 24) | ((uint32_t)buf[1] << 16) |
+           ((uint32_t)buf[2] << 8)  | buf[3];
+  }
+
+  // Read a 64-bit big-endian value
+  static uint64_t readU64BE(File& file) {
+    uint32_t hi = readU32BE(file);
+    uint32_t lo = readU32BE(file);
+    return ((uint64_t)hi << 32) | lo;
+  }
+
+  // Read a 16-bit big-endian value
+  static uint16_t readU16BE(File& file) {
+    uint8_t buf[2];
+    file.read(buf, 2);
+    return ((uint16_t)buf[0] << 8) | buf[1];
+  }
+
+  // Read atom header at given file offset
+  bool readAtomHeader(File& file, uint32_t offset, AtomHeader& hdr) {
+    if (offset + 8 > _fileSize) return false;
+
+    file.seek(offset);
+    uint32_t size32 = readU32BE(file);
+    hdr.type = readU32BE(file);
+
+    if (size32 == 1) {
+      // 64-bit extended size
+      if (offset + 16 > _fileSize) return false;
+      hdr.size = readU64BE(file);
+      hdr.dataOffset = offset + 16;
+      hdr.dataSize = (hdr.size > 16) ? hdr.size - 16 : 0;
+    } else if (size32 == 0) {
+      // Atom extends to end of file
+      hdr.size = _fileSize - offset;
+      hdr.dataOffset = offset + 8;
+      hdr.dataSize = hdr.size - 8;
+    } else {
+      hdr.size = size32;
+      hdr.dataOffset = offset + 8;
+      hdr.dataSize = (size32 > 8) ? size32 - 8 : 0;
+    }
+
+    return true;
+  }
+
+  // Parse the moov container atom
+  void parseMoov(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      switch (hdr.type) {
+        case ATOM_MVHD:
+          parseMvhd(file, hdr.dataOffset, (uint32_t)hdr.dataSize);
+          break;
+        case ATOM_UDTA:
+          parseUdta(file, hdr.dataOffset, hdr.dataOffset + (uint32_t)hdr.dataSize);
+          break;
+        case ATOM_TRAK:
+          break;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Parse mvhd (movie header) for duration
+  void parseMvhd(File& file, uint32_t offset, uint32_t size) {
+    file.seek(offset);
+    uint8_t version = file.read();
+
+    if (version == 0) {
+      file.seek(offset + 4);   // skip version(1) + flags(3)
+      /* create_time */ readU32BE(file);
+      /* modify_time */ readU32BE(file);
+      uint32_t timescale = readU32BE(file);
+      uint32_t duration = readU32BE(file);
+      if (timescale > 0) {
+        durationMs = (uint32_t)((uint64_t)duration * 1000 / timescale);
+      }
+    } else if (version == 1) {
+      file.seek(offset + 4);
+      /* create_time */ readU64BE(file);
+      /* modify_time */ readU64BE(file);
+      uint32_t timescale = readU32BE(file);
+      uint64_t duration = readU64BE(file);
+      if (timescale > 0) {
+        durationMs = (uint32_t)(duration * 1000 / timescale);
+      }
+    }
+  }
+
+  // Parse udta container — contains meta and/or chpl
+  void parseUdta(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_META) {
+        parseMeta(file, hdr.dataOffset + 4,
+                  hdr.dataOffset + (uint32_t)hdr.dataSize);
+      } else if (hdr.type == ATOM_CHPL) {
+        parseChpl(file, hdr.dataOffset, (uint32_t)hdr.dataSize);
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Parse meta container — contains hdlr + ilst
+  void parseMeta(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_ILST) {
+        parseIlst(file, hdr.dataOffset, hdr.dataOffset + (uint32_t)hdr.dataSize);
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Parse ilst (iTunes metadata list) — contains ©nam, ©ART, covr etc.
+  void parseIlst(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      switch (hdr.type) {
+        case ATOM_NAM:
+          extractTextData(file, hdr.dataOffset,
+                          hdr.dataOffset + (uint32_t)hdr.dataSize,
+                          title, M4B_MAX_TITLE);
+          break;
+        case ATOM_ART:
+          extractTextData(file, hdr.dataOffset,
+                          hdr.dataOffset + (uint32_t)hdr.dataSize,
+                          author, M4B_MAX_AUTHOR);
+          break;
+        case ATOM_COVR:
+          extractCoverData(file, hdr.dataOffset,
+                           hdr.dataOffset + (uint32_t)hdr.dataSize);
+          break;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Extract text from a 'data' sub-atom within an ilst entry.
+  void extractTextData(File& file, uint32_t start, uint32_t end,
+                       char* dest, int maxLen) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_DATA && hdr.dataSize > 8) {
+        uint32_t textOffset = hdr.dataOffset + 8;
+        uint32_t textLen = (uint32_t)hdr.dataSize - 8;
+        if (textLen > (uint32_t)(maxLen - 1)) textLen = maxLen - 1;
+
+        file.seek(textOffset);
+        file.read((uint8_t*)dest, textLen);
+        dest[textLen] = '\0';
+        return;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Extract cover art location from 'data' sub-atom within covr.
+  void extractCoverData(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_DATA && hdr.dataSize > 8) {
+        file.seek(hdr.dataOffset);
+        uint32_t typeIndicator = readU32BE(file);
+        uint8_t wellKnownType = typeIndicator & 0xFF;
+
+        coverOffset = hdr.dataOffset + 8;
+        coverSize = (uint32_t)hdr.dataSize - 8;
+        coverFormat = wellKnownType;  // 13=JPEG, 14=PNG
+        hasCoverArt = (coverSize > 0);
+
+        Serial.printf("M4B: Cover art found - %s, %u bytes at offset %u\n",
+                      wellKnownType == 13 ? "JPEG" :
+                      wellKnownType == 14 ? "PNG" : "unknown",
+                      coverSize, coverOffset);
+        return;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // =====================================================================
+  // ID3v2 Parser for MP3 files
+  // =====================================================================
+public:
+  // Parse ID3v2 tags from an MP3 file. Extracts title (TIT2), artist
+  // (TPE1), and cover art (APIC). Fills the same metadata fields as
+  // the M4B parser so decodeCoverArt() works unchanged.
+  bool parseID3v2(File& file) {
+    clear();
+    if (!file || file.size() < 10) return false;
+
+    file.seek(0);
+    uint8_t hdr[10];
+    if (file.read(hdr, 10) != 10) return false;
+
+    // Verify "ID3" magic
+    if (hdr[0] != 'I' || hdr[1] != 'D' || hdr[2] != '3') {
+      Serial.println("ID3: No ID3v2 header found");
+      return false;
+    }
+
+    uint8_t versionMajor = hdr[3];  // 3 = ID3v2.3, 4 = ID3v2.4
+    bool v24 = (versionMajor == 4);
+    bool hasExtHeader = (hdr[5] & 0x40) != 0;
+
+    // Tag size is syncsafe integer (4 x 7-bit bytes)
+    uint32_t tagSize = ((uint32_t)(hdr[6] & 0x7F) << 21) |
+                       ((uint32_t)(hdr[7] & 0x7F) << 14) |
+                       ((uint32_t)(hdr[8] & 0x7F) << 7)  |
+                       (hdr[9] & 0x7F);
+
+    uint32_t tagEnd = 10 + tagSize;
+    if (tagEnd > file.size()) tagEnd = file.size();
+
+    Serial.printf("ID3: v2.%d, %u bytes\n", versionMajor, tagSize);
+
+    // Skip extended header if present
+    uint32_t pos = 10;
+    if (hasExtHeader && pos + 4 < tagEnd) {
+      file.seek(pos);
+      uint32_t extSize;
+      if (v24) {
+        uint8_t eb[4];
+        file.read(eb, 4);
+        extSize = ((uint32_t)(eb[0] & 0x7F) << 21) |
+                  ((uint32_t)(eb[1] & 0x7F) << 14) |
+                  ((uint32_t)(eb[2] & 0x7F) << 7)  |
+                  (eb[3] & 0x7F);
+      } else {
+        extSize = readU32BE(file) + 4;
+      }
+      pos += extSize;
+    }
+
+    // Walk ID3v2 frames
+    bool foundTitle = false, foundArtist = false, foundCover = false;
+
+    while (pos + 10 < tagEnd) {
+      file.seek(pos);
+      uint8_t fhdr[10];
+      if (file.read(fhdr, 10) != 10) break;
+
+      if (fhdr[0] == 0) break;
+
+      char frameId[5] = { (char)fhdr[0], (char)fhdr[1],
+                          (char)fhdr[2], (char)fhdr[3], '\0' };
+
+      uint32_t frameSize;
+      if (v24) {
+        frameSize = ((uint32_t)(fhdr[4] & 0x7F) << 21) |
+                    ((uint32_t)(fhdr[5] & 0x7F) << 14) |
+                    ((uint32_t)(fhdr[6] & 0x7F) << 7)  |
+                    (fhdr[7] & 0x7F);
+      } else {
+        frameSize = ((uint32_t)fhdr[4] << 24) | ((uint32_t)fhdr[5] << 16) |
+                    ((uint32_t)fhdr[6] << 8)  | fhdr[7];
+      }
+
+      if (frameSize == 0 || pos + 10 + frameSize > tagEnd) break;
+
+      uint32_t dataStart = pos + 10;
+
+      // --- TIT2 (Title) ---
+      if (!foundTitle && strcmp(frameId, "TIT2") == 0 && frameSize > 1) {
+        id3ExtractText(file, dataStart, frameSize, title, M4B_MAX_TITLE);
+        foundTitle = (title[0] != '\0');
+      }
+      // --- TPE1 (Artist/Author) ---
+      if (!foundArtist && strcmp(frameId, "TPE1") == 0 && frameSize > 1) {
+        id3ExtractText(file, dataStart, frameSize, author, M4B_MAX_AUTHOR);
+        foundArtist = (author[0] != '\0');
+      }
+      // --- APIC (Attached Picture) ---
+      if (!foundCover && strcmp(frameId, "APIC") == 0 && frameSize > 20) {
+        id3ExtractAPIC(file, dataStart, frameSize);
+        foundCover = hasCoverArt;
+      }
+
+      pos = dataStart + frameSize;
+
+      // Early exit once we have everything
+      if (foundTitle && foundArtist && foundCover) break;
+    }
+
+    if (foundTitle) Serial.printf("ID3: Title: %s\n", title);
+    if (foundArtist) Serial.printf("ID3: Author: %s\n", author);
+    return (foundTitle || foundCover);
+  }
+
+private:
+  // Extract text from a TIT2/TPE1 frame.
+  // Format: encoding(1) + text data
+  void id3ExtractText(File& file, uint32_t offset, uint32_t size,
+                      char* dest, int maxLen) {
+    file.seek(offset);
+    uint8_t encoding = file.read();
+    uint32_t textLen = size - 1;
+    if (textLen == 0) return;
+
+    if (encoding == 0 || encoding == 3) {
+      // ISO-8859-1 or UTF-8 — read directly
+      uint32_t readLen = (textLen < (uint32_t)(maxLen - 1))
+                         ? textLen : (uint32_t)(maxLen - 1);
+      file.read((uint8_t*)dest, readLen);
+      dest[readLen] = '\0';
+      // Strip trailing nulls
+      while (readLen > 0 && dest[readLen - 1] == '\0') readLen--;
+      dest[readLen] = '\0';
+    }
+    else if (encoding == 1 || encoding == 2) {
+      // UTF-16 (with or without BOM) — crude ASCII extraction
+      // Static buffer to avoid stack overflow (loopTask has limited stack)
+      static uint8_t u16buf[128];
+      uint32_t readLen = (textLen > sizeof(u16buf)) ? sizeof(u16buf) : textLen;
+      file.read(u16buf, readLen);
+
+      uint32_t srcStart = 0;
+      // Skip BOM if present
+      if (readLen >= 2 && ((u16buf[0] == 0xFF && u16buf[1] == 0xFE) ||
+                           (u16buf[0] == 0xFE && u16buf[1] == 0xFF))) {
+        srcStart = 2;
+      }
+      bool littleEndian = (srcStart >= 2 && u16buf[0] == 0xFF);
+
+      int dstIdx = 0;
+      for (uint32_t i = srcStart; i + 1 < readLen && dstIdx < maxLen - 1; i += 2) {
+        uint8_t lo = littleEndian ? u16buf[i] : u16buf[i + 1];
+        uint8_t hi = littleEndian ? u16buf[i + 1] : u16buf[i];
+        if (lo == 0 && hi == 0) break;  // null terminator
+        if (hi == 0 && lo >= 0x20 && lo < 0x7F) {
+          dest[dstIdx++] = (char)lo;
+        } else {
+          dest[dstIdx++] = '?';
+        }
+      }
+      dest[dstIdx] = '\0';
+    }
+  }
+
+  // Extract APIC (cover art) frame.
+  // Format: encoding(1) + MIME(null-term) + picType(1) + desc(null-term) + imageData
+  void id3ExtractAPIC(File& file, uint32_t offset, uint32_t frameSize) {
+    file.seek(offset);
+    uint8_t encoding = file.read();
+
+    // Read MIME type (null-terminated ASCII)
+    char mime[32] = {0};
+    int mimeLen = 0;
+    while (mimeLen < 31) {
+      int b = file.read();
+      if (b < 0) return;   // Read error
+      if (b == 0) break;   // Null terminator = end of MIME string
+      mime[mimeLen++] = (char)b;
+    }
+    mime[mimeLen] = '\0';
+
+    // Picture type (1 byte)
+    uint8_t picType = file.read();
+    (void)picType;
+
+    // Skip description (null-terminated, encoding-dependent)
+    if (encoding == 0 || encoding == 3) {
+      // Single-byte null terminator
+      while (true) {
+        int b = file.read();
+        if (b < 0) return;   // Read error
+        if (b == 0) break;   // Null terminator
+      }
+    } else {
+      // UTF-16: double-null terminator
+      while (true) {
+        int b1 = file.read();
+        int b2 = file.read();
+        if (b1 < 0 || b2 < 0) return;  // Read error
+        if (b1 == 0 && b2 == 0) break;  // Double-null terminator
+      }
+    }
+
+    // Everything from here to end of frame is image data
+    uint32_t imgOffset = file.position();
+    uint32_t imgEnd = offset + frameSize;
+    if (imgOffset >= imgEnd) return;
+
+    uint32_t imgSize = imgEnd - imgOffset;
+
+    // Determine format from MIME type
+    bool isJpeg = (strstr(mime, "jpeg") || strstr(mime, "jpg"));
+    bool isPng  = (strstr(mime, "png") != nullptr);
+
+    // Also detect by magic bytes if MIME is generic
+    if (!isJpeg && !isPng && imgSize > 4) {
+      file.seek(imgOffset);
+      uint8_t magic[4];
+      file.read(magic, 4);
+      if (magic[0] == 0xFF && magic[1] == 0xD8) isJpeg = true;
+      else if (magic[0] == 0x89 && magic[1] == 'P' &&
+               magic[2] == 'N'  && magic[3] == 'G') isPng = true;
+    }
+
+    coverOffset = imgOffset;
+    coverSize = imgSize;
+    coverFormat = isJpeg ? 13 : (isPng ? 14 : 0);
+    hasCoverArt = (imgSize > 100 && (isJpeg || isPng));
+
+    if (hasCoverArt) {
+      Serial.printf("ID3: Cover %s, %u bytes\n",
+                    isJpeg ? "JPEG" : "PNG", imgSize);
+    }
+  }
+
+  // Parse Nero-style chapter list (chpl atom).
+  void parseChpl(File& file, uint32_t offset, uint32_t size) {
+    if (size < 9) return;
+
+    file.seek(offset);
+    uint8_t version = file.read();
+    file.read();  // flags byte 1
+    file.read();  // flags byte 2
+    file.read();  // flags byte 3
+
+    file.read();  // reserved
+
+    uint32_t count;
+    if (version == 1) {
+      count = readU32BE(file);
+    } else {
+      count = file.read();
+    }
+
+    if (count > M4B_MAX_CHAPTERS) count = M4B_MAX_CHAPTERS;
+
+    chapterCount = 0;
+    for (uint32_t i = 0; i < count; i++) {
+      if (!file.available()) break;
+
+      uint64_t timestamp = readU64BE(file);
+      uint32_t startMs = (uint32_t)(timestamp / 10000);  // 100ns -> ms
+
+      uint8_t nameLen = file.read();
+      if (nameLen == 0 || !file.available()) break;
+
+      M4BChapter& ch = chapters[chapterCount];
+      ch.startMs = startMs;
+
+      uint8_t readLen = (nameLen < sizeof(ch.name) - 1) ? nameLen : sizeof(ch.name) - 1;
+      file.read((uint8_t*)ch.name, readLen);
+      ch.name[readLen] = '\0';
+
+      if (nameLen > readLen) {
+        file.seek(file.position() + (nameLen - readLen));
+      }
+
+      chapterCount++;
+    }
+
+    Serial.printf("M4B: Found %d chapters\n", chapterCount);
+  }
+};

examples/companion_radio/ui-new/Mapscreen.h

@@ -0,0 +1,886 @@
+#pragma once
+
+// =============================================================================
+// MapScreen — OSM Tile Map for T-Deck Pro E-Ink Display
+// =============================================================================
+//
+// Renders standard OSM "slippy map" PNG tiles from SD card onto the e-ink
+// display at native 240×320 resolution (bypassing the 128×128 logical grid).
+//
+// Tiles are B&W PNGs stored at /tiles/{zoom}/{x}/{y}.png — the same format
+// used by Ripple, tdeck-maps, and MTD-Script tile downloaders.
+//
+// REQUIREMENTS:
+//   1. Add PNGdec library to platformio.ini:
+//        lib_deps = ... bitbank2/PNGdec@^1.0.1
+//
+//   2. Add raw display access to GxEPDDisplay.h (public section):
+//        // --- Raw pixel access for MapScreen (bypasses scaling) ---
+//        void drawPixelRaw(int16_t x, int16_t y, uint16_t color) {
+//          display.drawPixel(x, y, color);
+//        }
+//        int16_t rawWidth()  { return display.width(); }
+//        int16_t rawHeight() { return display.height(); }
+//        // Force endFrame() to push to display even if CRC unchanged
+//        // (needed because drawPixelRaw bypasses CRC tracking)
+//        void invalidateFrameCRC() { last_display_crc_value = 0; }
+//
+//   3. Add to UITask.h:
+//        #include "MapScreen.h"
+//        UIScreen* map_screen;
+//        void gotoMapScreen();
+//        bool isOnMapScreen() const { return curr == map_screen; }
+//        UIScreen* getMapScreen() const { return map_screen; }
+//
+//   4. Initialise in UITask::begin():
+//        map_screen = new MapScreen(this);
+//
+//   5. Implement UITask::gotoMapScreen() following gotoTextReader() pattern.
+//
+//   6. Hook 'g' key in main.cpp for GPS/Map access:
+//        case 'g':
+//          if (ui_task.isOnMapScreen()) {
+//            // Already on map — 'g' re-centers on GPS
+//            ui_task.injectKey('g');
+//          } else {
+//            Serial.println("Opening map");
+//            {
+//              MapScreen* ms = (MapScreen*)ui_task.getMapScreen();
+//              if (ms) {
+//                ms->setSDReady(sdCardReady);
+//                ms->setGPSPosition(sensors.node_lat,
+//                                   sensors.node_lon);
+//                // Populate contact markers via iterator
+//                ms->clearMarkers();
+//                ContactsIterator it = the_mesh.startContactsIterator();
+//                ContactInfo ci;
+//                while (it.hasNext(&the_mesh, ci)) {
+//                  double lat = ((double)ci.gps_lat) / 1000000.0;
+//                  double lon = ((double)ci.gps_lon) / 1000000.0;
+//                  ms->addMarker(lat, lon, ci.name, ci.type);
+//                }
+//              }
+//            }
+//            ui_task.gotoMapScreen();
+//          }
+//          break;
+//
+//   7. Route WASD/zoom keys to map screen in main.cpp (in existing handlers):
+//        For 'w', 's', 'a', 'd' cases, add:
+//          if (ui_task.isOnMapScreen()) { ui_task.injectKey(key); break; }
+//        For the default case, add map screen passthrough:
+//          if (ui_task.isOnMapScreen()) { ui_task.injectKey(key); break; }
+//        This covers +, -, i, o, g (re-center) keys too.
+//
+// TILE SOURCES (B&W recommended for e-ink):
+//   - MTD-Script:    github.com/fistulareffigy/MTD-Script
+//   - tdeck-maps:    github.com/JustDr00py/tdeck-maps
+//   - Stamen Toner style gives best e-ink contrast
+// =============================================================================
+
+#include <Arduino.h>
+#include <SD.h>
+#include <PNGdec.h>
+#undef local  // PNGdec's zutil.h defines 'local' as 'static' — breaks any variable named 'local'
+#include <helpers/ui/UIScreen.h>
+#include <helpers/ui/DisplayDriver.h>
+#include <helpers/ui/GxEPDDisplay.h>
+
+// ---------------------------------------------------------------------------
+// Layout constants (physical pixel coordinates, 240×320 display)
+// ---------------------------------------------------------------------------
+#define MAP_DISPLAY_W       240
+#define MAP_DISPLAY_H       320
+
+// Footer bar occupies the bottom — matches other screens' setTextSize(1) footer
+#define MAP_FOOTER_H        24      // ~24px at bottom for nav hints
+#define MAP_VIEWPORT_Y      0       // Map starts at top
+#define MAP_VIEWPORT_H      (MAP_DISPLAY_H - MAP_FOOTER_H)  // 296px for map
+
+#define MAP_TILE_SIZE       256     // Standard OSM tile size in pixels
+#define MAP_DEFAULT_ZOOM    13
+#define MAP_MIN_ZOOM        1
+#define MAP_MAX_ZOOM        17
+
+// PNG decode buffer size — 256×256 RGB = 196KB, but PNGdec streams row-by-row
+// We only need a line buffer. Allocate in PSRAM for safety.
+#define MAP_PNG_BUF_SIZE    (65536)  // 64KB for PNG file read buffer
+
+// Tile path on SD card
+#define MAP_TILE_ROOT       "/tiles"
+
+// Contact type (for label display — matches AdvertDataHelpers.h)
+#ifndef ADV_TYPE_REPEATER
+  #define ADV_TYPE_REPEATER   2
+#endif
+
+// Pan step: fraction of viewport to move per keypress
+#define MAP_PAN_FRACTION    4       // 1/4 of viewport per press
+
+// Max contact markers (PSRAM-allocated, ~37 bytes each)
+#define MAP_MAX_MARKERS     500
+
+
+class MapScreen : public UIScreen {
+public:
+  MapScreen(UITask* task)
+    : _task(task),
+      _einkDisplay(nullptr),
+      _sdReady(false),
+      _needsRedraw(true),
+      _hasFix(false),
+      _centerLat(-33.8688),   // Default: Sydney (most Ripple users)
+      _centerLon(151.2093),
+      _gpsLat(0.0),
+      _gpsLon(0.0),
+      _zoom(MAP_DEFAULT_ZOOM),
+      _zoomMin(MAP_MIN_ZOOM),
+      _zoomMax(MAP_MAX_ZOOM),
+      _pngBuf(nullptr),
+      _tileFound(false)
+  {
+    // Allocate marker array in PSRAM at construction (~20KB)
+    // so addMarker() works before enter() is called
+    _markers = (MapMarker*)ps_calloc(MAP_MAX_MARKERS, sizeof(MapMarker));
+    if (_markers) {
+      Serial.printf("MapScreen: markers allocated (%d × %d = %d bytes PSRAM)\n",
+                     MAP_MAX_MARKERS, (int)sizeof(MapMarker),
+                     MAP_MAX_MARKERS * (int)sizeof(MapMarker));
+    } else {
+      Serial.println("MapScreen: marker PSRAM alloc FAILED");
+    }
+  }
+
+  ~MapScreen() {
+    if (_pngBuf) { free(_pngBuf); _pngBuf = nullptr; }
+    if (_markers) { free(_markers); _markers = nullptr; }
+  }
+
+  void setSDReady(bool ready) { _sdReady = ready; }
+
+  // Set initial GPS position (called when opening map — centers viewport)
+  void setGPSPosition(double lat, double lon) {
+    if (lat != 0.0 || lon != 0.0) {
+      _gpsLat = lat;
+      _gpsLon = lon;
+      _centerLat = lat;
+      _centerLon = lon;
+      _hasFix = true;
+      _needsRedraw = true;
+    }
+  }
+
+  // Update own GPS position without moving viewport (called periodically)
+  void updateGPSPosition(double lat, double lon) {
+    if (lat == 0.0 && lon == 0.0) return;
+    if (lat != _gpsLat || lon != _gpsLon) {
+      _gpsLat = lat;
+      _gpsLon = lon;
+      _hasFix = true;
+      _needsRedraw = true;  // Redraw to move own-position marker
+    }
+  }
+
+  // Add a location marker (call once per contact before entering map)
+  void clearMarkers() { _numMarkers = 0; }
+  void addMarker(double lat, double lon, const char* name = "", uint8_t type = 0) {
+    if (!_markers || _numMarkers >= MAP_MAX_MARKERS) return;
+    if (lat == 0.0 && lon == 0.0) return;  // Skip no-location contacts
+    _markers[_numMarkers].lat = lat;
+    _markers[_numMarkers].lon = lon;
+    _markers[_numMarkers].type = type;
+    strncpy(_markers[_numMarkers].name, name, sizeof(_markers[0].name) - 1);
+    _markers[_numMarkers].name[sizeof(_markers[0].name) - 1] = '\0';
+    _numMarkers++;
+  }
+
+  // Refresh contact markers (called periodically from main loop)
+  // Clears and rebuilds — caller iterates contacts and calls addMarker()
+  int getNumMarkers() const { return _numMarkers; }
+
+  // Called when navigating to map screen
+  void enter(DisplayDriver& display) {
+    _einkDisplay = static_cast<GxEPDDisplay*>(&display);
+    _needsRedraw = true;
+
+    // Allocate PNG read buffer in PSRAM on first use
+    if (!_pngBuf) {
+      _pngBuf = (uint8_t*)ps_malloc(MAP_PNG_BUF_SIZE);
+      if (!_pngBuf) {
+        Serial.println("MapScreen: PSRAM alloc failed, trying heap");
+        _pngBuf = (uint8_t*)malloc(MAP_PNG_BUF_SIZE);
+      }
+      if (_pngBuf) {
+        Serial.printf("MapScreen: PNG buffer allocated (%d bytes)\n", MAP_PNG_BUF_SIZE);
+      } else {
+        Serial.println("MapScreen: PNG buffer alloc FAILED");
+      }
+    }
+
+    // Detect available zoom levels from SD card directories
+    detectZoomRange();
+  }
+
+  // ---- UIScreen interface ----
+
+  int render(DisplayDriver& display) override {
+    if (!_einkDisplay) {
+      _einkDisplay = static_cast<GxEPDDisplay*>(&display);
+    }
+
+    if (!_sdReady) {
+      display.setTextSize(1);
+      display.setColor(DisplayDriver::LIGHT);
+      display.setCursor(10, 20);
+      display.print("SD card not found");
+      display.setCursor(10, 35);
+      display.print("Insert SD with");
+      display.setCursor(10, 48);
+      display.print("/tiles/{z}/{x}/{y}.png");
+      return 5000;
+    }
+
+    // Always render tiles — UITask clears the buffer via startFrame() before
+    // calling us, so we must redraw every time (e.g. after alert overlays)
+    bool wasRedraw = _needsRedraw;
+    _needsRedraw = false;
+
+    // Render map tiles into the viewport
+    renderMapViewport();
+
+    // Overlay contact markers
+    renderContactMarkers();
+
+    // Crosshair at viewport center
+    renderCrosshair();
+
+    // Footer bar (uses normal display API with scaling)
+    renderFooter(display);
+
+    // Raw pixel writes bypass CRC tracking — force refresh
+    _einkDisplay->invalidateFrameCRC();
+
+    // If user panned/zoomed, allow quick re-render; otherwise idle longer
+    return wasRedraw ? 1000 : 30000;
+  }
+
+  bool handleInput(char c) override {
+    // Pan distances in degrees — adaptive to zoom level
+    // At zoom Z, one tile covers 360/2^Z degrees of longitude
+    double tileLonSpan = 360.0 / (1 << _zoom);
+    double tileLatSpan = tileLonSpan * cos(_centerLat * PI / 180.0);  // Rough approx
+
+    // Pan by 1/MAP_PAN_FRACTION of viewport (viewport ≈ 1 tile)
+    double panLon = tileLonSpan / MAP_PAN_FRACTION;
+    double panLat = tileLatSpan / MAP_PAN_FRACTION;
+
+    switch (c) {
+      // ---- WASD panning ----
+      case 'w':
+      case 'W':
+        _centerLat += panLat;
+        if (_centerLat > 85.05) _centerLat = 85.05;  // Web Mercator limit
+        _needsRedraw = true;
+        return true;
+
+      case 's':
+      case 'S':
+        _centerLat -= panLat;
+        if (_centerLat < -85.05) _centerLat = -85.05;
+        _needsRedraw = true;
+        return true;
+
+      case 'a':
+      case 'A':
+        _centerLon -= panLon;
+        if (_centerLon < -180.0) _centerLon += 360.0;
+        _needsRedraw = true;
+        return true;
+
+      case 'd':
+      case 'D':
+        _centerLon += panLon;
+        if (_centerLon > 180.0) _centerLon -= 360.0;
+        _needsRedraw = true;
+        return true;
+
+      // ---- Zoom controls ----
+      case 'z':
+      case 'Z':
+        if (_zoom < _zoomMax) {
+          _zoom++;
+          _needsRedraw = true;
+          Serial.printf("MapScreen: zoom in -> %d\n", _zoom);
+        }
+        return true;
+
+      case 'x':
+      case 'X':
+        if (_zoom > _zoomMin) {
+          _zoom--;
+          _needsRedraw = true;
+          Serial.printf("MapScreen: zoom out -> %d\n", _zoom);
+        }
+        return true;
+
+      // ---- Re-center on GPS fix ----
+      case 'g':
+        if (_hasFix) {
+          _centerLat = _gpsLat;
+          _centerLon = _gpsLon;
+          _needsRedraw = true;
+          Serial.println("MapScreen: re-center on GPS");
+        }
+        return true;
+
+      default:
+        return false;
+    }
+  }
+
+private:
+  UITask* _task;
+  GxEPDDisplay* _einkDisplay;
+  bool _sdReady;
+  bool _needsRedraw;
+  bool _hasFix;
+
+  // Map state
+  double _centerLat;
+  double _centerLon;
+  double _gpsLat;       // Own GPS position (separate from viewport center)
+  double _gpsLon;
+  int _zoom;
+  int _zoomMin;     // Detected from SD card
+  int _zoomMax;     // Detected from SD card
+
+  // PNG decode buffer (PSRAM)
+  uint8_t* _pngBuf;
+  bool _tileFound;      // Did last tile load succeed?
+
+  // PNGdec instance
+  PNG _png;
+
+  // Contacts for marker overlay
+  struct MapMarker {
+    double lat;
+    double lon;
+    char name[20];    // Truncated display name
+    uint8_t type;     // ADV_TYPE_CHAT, ADV_TYPE_REPEATER, etc.
+  };
+  MapMarker* _markers = nullptr;  // PSRAM-allocated
+  int _numMarkers = 0;
+
+  // ---- Rendering state passed to PNG callback ----
+  // PNGdec calls our callback per scanline — we need to know where to draw.
+  // Also carries a PNG* so the static callback can call getLineAsRGB565().
+  struct DrawContext {
+    GxEPDDisplay* display;
+    PNG* png;         // Pointer to the decoder (for getLineAsRGB565)
+    int offsetX;      // Screen X offset for this tile
+    int offsetY;      // Screen Y offset for this tile
+    int viewportY;    // Top of viewport (MAP_VIEWPORT_Y)
+    int viewportH;    // Height of viewport (MAP_VIEWPORT_H)
+  };
+  DrawContext _drawCtx;
+
+  // ==========================================================================
+  // Detect available zoom levels from /tiles/{z}/ directories on SD
+  // ==========================================================================
+
+  void detectZoomRange() {
+    if (!_sdReady) return;
+
+    _zoomMin = MAP_MAX_ZOOM;
+    _zoomMax = MAP_MIN_ZOOM;
+
+    char path[32];
+    for (int z = MAP_MIN_ZOOM; z <= MAP_MAX_ZOOM; z++) {
+      snprintf(path, sizeof(path), MAP_TILE_ROOT "/%d", z);
+      if (SD.exists(path)) {
+        if (z < _zoomMin) _zoomMin = z;
+        if (z > _zoomMax) _zoomMax = z;
+      }
+    }
+
+    // If no tiles found, reset to defaults
+    if (_zoomMin > _zoomMax) {
+      _zoomMin = MAP_MIN_ZOOM;
+      _zoomMax = MAP_MAX_ZOOM;
+      Serial.println("MapScreen: no tile directories found");
+    } else {
+      Serial.printf("MapScreen: detected zoom range %d-%d\n", _zoomMin, _zoomMax);
+    }
+
+    // Clamp current zoom to available range
+    if (_zoom > _zoomMax) _zoom = _zoomMax;
+    if (_zoom < _zoomMin) _zoom = _zoomMin;
+  }
+
+  // ==========================================================================
+  // Tile coordinate math (Web Mercator / Slippy Map convention)
+  // ==========================================================================
+
+  // Convert lat/lon to tile X,Y and sub-tile pixel offset at given zoom
+  static void latLonToTileXY(double lat, double lon, int zoom,
+                              int& tileX, int& tileY,
+                              int& pixelX, int& pixelY)
+  {
+    int n = 1 << zoom;
+
+    // Tile X (longitude is linear)
+    double x = (lon + 180.0) / 360.0 * n;
+    tileX = (int)floor(x);
+    pixelX = (int)((x - tileX) * MAP_TILE_SIZE);
+
+    // Tile Y (latitude uses Mercator projection)
+    double latRad = lat * PI / 180.0;
+    double y = (1.0 - log(tan(latRad) + 1.0 / cos(latRad)) / PI) / 2.0 * n;
+    tileY = (int)floor(y);
+    pixelY = (int)((y - tileY) * MAP_TILE_SIZE);
+  }
+
+  // Convert tile X,Y + pixel offset back to lat/lon
+  static void tileXYToLatLon(int tileX, int tileY, int pixelX, int pixelY,
+                              int zoom, double& lat, double& lon)
+  {
+    int n = 1 << zoom;
+    double x = tileX + (double)pixelX / MAP_TILE_SIZE;
+    double y = tileY + (double)pixelY / MAP_TILE_SIZE;
+
+    lon = x / n * 360.0 - 180.0;
+    double latRad = atan(sinh(PI * (1.0 - 2.0 * y / n)));
+    lat = latRad * 180.0 / PI;
+  }
+
+  // Convert a lat/lon to pixel position within the current viewport
+  // Returns false if off-screen
+  bool latLonToScreen(double lat, double lon, int& screenX, int& screenY) {
+    int centerTileX, centerTileY, centerPixelX, centerPixelY;
+    latLonToTileXY(_centerLat, _centerLon, _zoom,
+                   centerTileX, centerTileY, centerPixelX, centerPixelY);
+
+    int targetTileX, targetTileY, targetPixelX, targetPixelY;
+    latLonToTileXY(lat, lon, _zoom,
+                   targetTileX, targetTileY, targetPixelX, targetPixelY);
+
+    // Calculate pixel delta from center
+    int dx = (targetTileX - centerTileX) * MAP_TILE_SIZE + (targetPixelX - centerPixelX);
+    int dy = (targetTileY - centerTileY) * MAP_TILE_SIZE + (targetPixelY - centerPixelY);
+
+    screenX = MAP_DISPLAY_W / 2 + dx;
+    screenY = MAP_VIEWPORT_Y + MAP_VIEWPORT_H / 2 + dy;
+
+    return (screenX >= 0 && screenX < MAP_DISPLAY_W &&
+            screenY >= MAP_VIEWPORT_Y && screenY < MAP_VIEWPORT_Y + MAP_VIEWPORT_H);
+  }
+
+  // ==========================================================================
+  // Tile loading and rendering
+  // ==========================================================================
+
+  // Build tile file path: /tiles/{zoom}/{x}/{y}.png
+  static void buildTilePath(char* buf, int bufSize, int zoom, int x, int y) {
+    snprintf(buf, bufSize, MAP_TILE_ROOT "/%d/%d/%d.png", zoom, x, y);
+  }
+
+  // Load a PNG tile from SD and decode it directly to the display
+  // screenX, screenY = top-left corner on display where this tile goes
+  bool loadAndRenderTile(int tileX, int tileY, int screenX, int screenY) {
+    if (!_pngBuf || !_einkDisplay) return false;
+
+    char path[64];
+    buildTilePath(path, sizeof(path), _zoom, tileX, tileY);
+
+    // Check existence first to avoid noisy ESP32 VFS error logs
+    if (!SD.exists(path)) return false;
+
+    File f = SD.open(path, FILE_READ);
+    if (!f) return false;
+
+    // Read entire PNG into buffer
+    int fileSize = f.size();
+    if (fileSize > MAP_PNG_BUF_SIZE) {
+      Serial.printf("MapScreen: tile too large: %s (%d bytes)\n", path, fileSize);
+      f.close();
+      return false;
+    }
+
+    int bytesRead = f.read(_pngBuf, fileSize);
+    f.close();
+
+    if (bytesRead != fileSize) {
+      Serial.printf("MapScreen: short read: %s (%d/%d)\n", path, bytesRead, fileSize);
+      return false;
+    }
+
+    // Set up draw context for the PNG callback
+    _drawCtx.display   = _einkDisplay;
+    _drawCtx.png       = &_png;
+    _drawCtx.offsetX   = screenX;
+    _drawCtx.offsetY   = screenY;
+    _drawCtx.viewportY = MAP_VIEWPORT_Y;
+    _drawCtx.viewportH = MAP_VIEWPORT_H;
+
+    // Open PNG from memory buffer
+    int rc = _png.openRAM(_pngBuf, fileSize, pngDrawCallback);
+    if (rc != PNG_SUCCESS) {
+      Serial.printf("MapScreen: PNG open failed: %s (rc=%d)\n", path, rc);
+      return false;
+    }
+
+    // Decode — triggers pngDrawCallback for each scanline.
+    // First arg is user pointer, passed as pDraw->pUser in callback.
+    rc = _png.decode(&_drawCtx, 0);
+    _png.close();
+
+    if (rc != PNG_SUCCESS) {
+      Serial.printf("MapScreen: PNG decode failed: %s (rc=%d)\n", path, rc);
+      return false;
+    }
+
+    return true;
+  }
+
+  // PNGdec scanline callback — called once per row of the decoded image.
+  // Draws directly to the e-ink display at raw pixel coordinates.
+  // Uses getLineAsRGB565 with correct (little) endianness for ESP32.
+  static int pngDrawCallback(PNGDRAW* pDraw) {
+    DrawContext* ctx = (DrawContext*)pDraw->pUser;
+    if (!ctx || !ctx->display || !ctx->png) return 0;
+
+    int screenY = ctx->offsetY + pDraw->y;
+
+    // Clip to viewport vertically
+    if (screenY < ctx->viewportY || screenY >= ctx->viewportY + ctx->viewportH) return 1;
+
+    // Debug: log format on first row of first tile only
+    if (pDraw->y == 0 && ctx->offsetX >= 0 && ctx->offsetY >= 0) {
+      static bool logged = false;
+      if (!logged) {
+        Serial.printf("MapScreen: PNG iBpp=%d iWidth=%d\n", pDraw->iBpp, pDraw->iWidth);
+        logged = true;
+      }
+    }
+
+    uint16_t lineWidth = pDraw->iWidth;
+    uint16_t lineBuf[MAP_TILE_SIZE];
+    if (lineWidth > MAP_TILE_SIZE) lineWidth = MAP_TILE_SIZE;
+    ctx->png->getLineAsRGB565(pDraw, lineBuf, PNG_RGB565_LITTLE_ENDIAN, 0xFFFFFFFF);
+
+    for (int x = 0; x < lineWidth; x++) {
+      int screenX = ctx->offsetX + x;
+      if (screenX < 0 || screenX >= MAP_DISPLAY_W) continue;
+
+      // RGB565 little-endian on ESP32: standard bit layout
+      // R[15:11] G[10:5] B[4:0]
+      uint16_t pixel = lineBuf[x];
+
+      // For B&W tiles this is 0x0000 (black) or 0xFFFF (white)
+      // Simple threshold on full 16-bit value handles both cleanly
+      uint16_t color = (pixel > 0x7FFF) ? GxEPD_WHITE : GxEPD_BLACK;
+      ctx->display->drawPixelRaw(screenX, screenY, color);
+    }
+    return 1;
+  }
+
+  // ==========================================================================
+  // Viewport rendering — stitch tiles to fill the screen
+  // ==========================================================================
+
+  void renderMapViewport() {
+    if (!_einkDisplay) return;
+
+    // Find which tile the center point falls in
+    int centerTileX, centerTileY, centerPixelX, centerPixelY;
+    latLonToTileXY(_centerLat, _centerLon, _zoom,
+                   centerTileX, centerTileY, centerPixelX, centerPixelY);
+
+    Serial.printf("MapScreen: center tile %d/%d/%d  px(%d,%d)\n",
+                  _zoom, centerTileX, centerTileY, centerPixelX, centerPixelY);
+
+    // Screen position where the center tile's (0,0) corner should be placed
+    // such that the GPS point ends up at viewport center
+    int viewCenterX = MAP_DISPLAY_W / 2;
+    int viewCenterY = MAP_VIEWPORT_Y + MAP_VIEWPORT_H / 2;
+
+    int baseTileScreenX = viewCenterX - centerPixelX;
+    int baseTileScreenY = viewCenterY - centerPixelY;
+
+    // Determine tile grid range needed to cover the entire viewport
+    int startDX = 0, startDY = 0;
+    int endDX = 0, endDY = 0;
+
+    while (baseTileScreenX + startDX * MAP_TILE_SIZE > 0) startDX--;
+    while (baseTileScreenY + startDY * MAP_TILE_SIZE > MAP_VIEWPORT_Y) startDY--;
+    while (baseTileScreenX + (endDX + 1) * MAP_TILE_SIZE < MAP_DISPLAY_W) endDX++;
+    while (baseTileScreenY + (endDY + 1) * MAP_TILE_SIZE < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) endDY++;
+
+    int maxTile = (1 << _zoom) - 1;
+    int loaded = 0, missing = 0;
+
+    for (int dy = startDY; dy <= endDY; dy++) {
+      for (int dx = startDX; dx <= endDX; dx++) {
+        int tx = centerTileX + dx;
+        int ty = centerTileY + dy;
+
+        // Longitude wraps
+        if (tx < 0) tx += (1 << _zoom);
+        if (tx > maxTile) tx -= (1 << _zoom);
+
+        // Latitude doesn't wrap — skip out-of-range
+        if (ty < 0 || ty > maxTile) continue;
+
+        int screenX = baseTileScreenX + dx * MAP_TILE_SIZE;
+        int screenY = baseTileScreenY + dy * MAP_TILE_SIZE;
+
+        if (loadAndRenderTile(tx, ty, screenX, screenY)) {
+          loaded++;
+        } else {
+          missing++;
+        }
+      }
+    }
+
+    Serial.printf("MapScreen: rendered %d tiles, %d missing\n", loaded, missing);
+    _tileFound = (loaded > 0);
+  }
+
+  // ==========================================================================
+  // Contact marker overlay
+  // ==========================================================================
+
+  void renderContactMarkers() {
+    if (!_einkDisplay || !_markers) return;
+
+    int visible = 0;
+    for (int i = 0; i < _numMarkers; i++) {
+      int sx, sy;
+      if (latLonToScreen(_markers[i].lat, _markers[i].lon, sx, sy)) {
+        int r = markerRadius();
+        drawDiamond(sx, sy, r);
+
+        // Draw name label for repeaters (and at higher zoom for all contacts)
+        if (_markers[i].name[0] != '\0' &&
+            (_markers[i].type == ADV_TYPE_REPEATER || _zoom >= 14)) {
+          drawLabel(sx, sy - r - 2, _markers[i].name);
+        }
+        visible++;
+      }
+    }
+
+    // Render own GPS position as a distinct marker (circle)
+    if (_hasFix) {
+      int sx, sy;
+      if (latLonToScreen(_gpsLat, _gpsLon, sx, sy)) {
+        drawOwnPosition(sx, sy);
+        visible++;
+      }
+    }
+  }
+
+  // Marker radius scaled by zoom level
+  // z10→3px, z11→4, z12→5, z13→6, z14→7, z15→8, z16→9, z17→10
+  int markerRadius() {
+    int r = _zoom - 7;
+    if (r < 3) r = 3;
+    if (r > 10) r = 10;
+    return r;
+  }
+
+  // Draw a filled diamond marker at screen coordinates with given radius
+  void drawDiamond(int cx, int cy, int r) {
+    // White outline first (1px larger than fill)
+    for (int dy = -(r + 1); dy <= (r + 1); dy++) {
+      int span = (r + 1) - abs(dy);
+      int innerSpan = r - abs(dy);
+      for (int dx = -span; dx <= span; dx++) {
+        if (abs(dy) <= r && abs(dx) <= innerSpan) continue;
+        int px = cx + dx, py = cy + dy;
+        if (px >= 0 && px < MAP_DISPLAY_W &&
+            py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+          _einkDisplay->drawPixelRaw(px, py, GxEPD_WHITE);
+        }
+      }
+    }
+
+    // Filled black diamond
+    for (int dy = -r; dy <= r; dy++) {
+      int span = r - abs(dy);
+      for (int dx = -span; dx <= span; dx++) {
+        int px = cx + dx, py = cy + dy;
+        if (px >= 0 && px < MAP_DISPLAY_W &&
+            py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+          _einkDisplay->drawPixelRaw(px, py, GxEPD_BLACK);
+        }
+      }
+    }
+  }
+
+  // Strip non-ASCII characters (emoji, flags, symbols) from label text.
+  // Copies only printable ASCII (0x20-0x7E) into dest buffer.
+  // Skips leading whitespace after stripping. Returns length.
+  static int extractAsciiLabel(const char* src, char* dest, int destSize) {
+    int j = 0;
+    for (int i = 0; src[i] != '\0' && j < destSize - 1; i++) {
+      uint8_t ch = (uint8_t)src[i];
+      if (ch >= 0x20 && ch <= 0x7E) {
+        dest[j++] = src[i];
+      }
+      // Skip continuation bytes of multi-byte UTF-8 sequences
+    }
+    dest[j] = '\0';
+
+    // Trim leading spaces (left after stripping emoji prefix)
+    int start = 0;
+    while (dest[start] == ' ') start++;
+    if (start > 0) {
+      memmove(dest, dest + start, j - start + 1);
+      j -= start;
+    }
+    return j;
+  }
+
+  // Draw a text label above a marker with white background for readability
+  // Built-in font is 5×7 pixels per character
+  void drawLabel(int cx, int topY, const char* text) {
+    // Clean emoji/non-ASCII from label
+    char clean[24];
+    int len = extractAsciiLabel(text, clean, sizeof(clean));
+    if (len == 0) return;  // Nothing printable
+    if (len > 14) len = 14;  // Truncate long names
+    clean[len] = '\0';
+
+    int textW = len * 6;     // 5px char + 1px spacing
+    int textH = 8;           // 7px + 1px padding
+
+    int lx = cx - textW / 2;
+    int ly = topY - textH;
+
+    // Clamp to viewport
+    if (lx < 1) lx = 1;
+    if (lx + textW >= MAP_DISPLAY_W - 1) lx = MAP_DISPLAY_W - textW - 1;
+    if (ly < MAP_VIEWPORT_Y) ly = MAP_VIEWPORT_Y;
+    if (ly + textH >= MAP_VIEWPORT_Y + MAP_VIEWPORT_H) return;
+
+    // White background rectangle
+    for (int y = ly - 1; y <= ly + textH; y++) {
+      for (int x = lx - 1; x <= lx + textW; x++) {
+        if (x >= 0 && x < MAP_DISPLAY_W &&
+            y >= MAP_VIEWPORT_Y && y < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+          _einkDisplay->drawPixelRaw(x, y, GxEPD_WHITE);
+        }
+      }
+    }
+
+    // Draw text using raw font rendering
+    _einkDisplay->drawTextRaw(lx, ly, clean, GxEPD_BLACK);
+  }
+
+  // Draw own-position marker: bold circle with filled center dot
+  // Fixed size (doesn't scale with zoom) so it's always clearly visible
+  void drawOwnPosition(int cx, int cy) {
+    int r = 8;  // Outer radius — always prominent
+
+    // White halo (clears map underneath)
+    for (int dy = -(r + 2); dy <= (r + 2); dy++) {
+      for (int dx = -(r + 2); dx <= (r + 2); dx++) {
+        if (dx * dx + dy * dy <= (r + 2) * (r + 2)) {
+          int px = cx + dx, py = cy + dy;
+          if (px >= 0 && px < MAP_DISPLAY_W &&
+              py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+            _einkDisplay->drawPixelRaw(px, py, GxEPD_WHITE);
+          }
+        }
+      }
+    }
+
+    // Thick black circle outline (2px wide ring)
+    for (int dy = -r; dy <= r; dy++) {
+      for (int dx = -r; dx <= r; dx++) {
+        int d2 = dx * dx + dy * dy;
+        if (d2 >= (r - 2) * (r - 2) && d2 <= r * r) {
+          int px = cx + dx, py = cy + dy;
+          if (px >= 0 && px < MAP_DISPLAY_W &&
+              py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+            _einkDisplay->drawPixelRaw(px, py, GxEPD_BLACK);
+          }
+        }
+      }
+    }
+
+    // Filled black center dot (radius 3)
+    for (int dy = -3; dy <= 3; dy++) {
+      for (int dx = -3; dx <= 3; dx++) {
+        if (dx * dx + dy * dy <= 9) {
+          int px = cx + dx, py = cy + dy;
+          if (px >= 0 && px < MAP_DISPLAY_W &&
+              py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+            _einkDisplay->drawPixelRaw(px, py, GxEPD_BLACK);
+          }
+        }
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Crosshair at viewport center
+  // ==========================================================================
+
+  void renderCrosshair() {
+    if (!_einkDisplay) return;
+
+    int cx = MAP_DISPLAY_W / 2;
+    int cy = MAP_VIEWPORT_Y + MAP_VIEWPORT_H / 2;
+    int len = markerRadius() + 2;  // Scales with zoom
+
+    // Draw thin crosshair: black line with white border for contrast
+    // Horizontal arm
+    for (int x = cx - len; x <= cx + len; x++) {
+      if (x >= 0 && x < MAP_DISPLAY_W) {
+        if (cy - 1 >= MAP_VIEWPORT_Y)
+          _einkDisplay->drawPixelRaw(x, cy - 1, GxEPD_WHITE);
+        if (cy + 1 < MAP_VIEWPORT_Y + MAP_VIEWPORT_H)
+          _einkDisplay->drawPixelRaw(x, cy + 1, GxEPD_WHITE);
+        _einkDisplay->drawPixelRaw(x, cy, GxEPD_BLACK);
+      }
+    }
+
+    // Vertical arm
+    for (int y = cy - len; y <= cy + len; y++) {
+      if (y >= MAP_VIEWPORT_Y && y < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+        if (cx - 1 >= 0)
+          _einkDisplay->drawPixelRaw(cx - 1, y, GxEPD_WHITE);
+        if (cx + 1 < MAP_DISPLAY_W)
+          _einkDisplay->drawPixelRaw(cx + 1, y, GxEPD_WHITE);
+        _einkDisplay->drawPixelRaw(cx, y, GxEPD_BLACK);
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Footer bar — zoom level, GPS status, navigation hints
+  // ==========================================================================
+
+  void renderFooter(DisplayDriver& display) {
+    // Use the standard footer pattern: setTextSize(1) at height()-12
+    display.setTextSize(1);
+    display.setColor(DisplayDriver::LIGHT);
+
+    int footerY = display.height() - 12;
+
+    // Separator line
+    display.drawRect(0, footerY - 2, display.width(), 1);
+
+    // Left: zoom level
+    char left[8];
+    snprintf(left, sizeof(left), "Z%d", _zoom);
+    display.setCursor(0, footerY);
+    display.print(left);
+
+    // Right: navigation hint
+    const char* right = "WASD:pan Z/X:zoom";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+  }
+};

examples/companion_radio/ui-new/ModemManager.h

@@ -0,0 +1,266 @@
+#pragma once
+
+// =============================================================================
+// ModemManager - A7682E 4G Modem Driver for T-Deck Pro (V1.1 4G variant)
+//
+// Runs AT commands on a dedicated FreeRTOS task (Core 0, priority 1) to never
+// block the mesh radio loop.  Communicates with main loop via lock-free queues.
+//
+// Supports: SMS send/receive, voice call dial/answer/hangup/DTMF
+//
+// Guard: HAS_4G_MODEM (defined only for the 4G build environment)
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef MODEM_MANAGER_H
+#define MODEM_MANAGER_H
+
+#include <Arduino.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/task.h>
+#include <freertos/queue.h>
+#include <freertos/semphr.h>
+#include "variant.h"
+#include "ApnDatabase.h"
+
+// ---------------------------------------------------------------------------
+// Modem pins (from variant.h, always defined for reference)
+//   MODEM_POWER_EN  41   Board 6609 enable
+//   MODEM_PWRKEY    40   Power key toggle
+//   MODEM_RST        9   Reset (shared with I2S BCLK on audio board)
+//   MODEM_RI         7   Ring indicator (shared with I2S DOUT on audio)
+//   MODEM_DTR        8   Data terminal ready (shared with I2S LRC on audio)
+//   MODEM_RX        10   UART RX (shared with PIN_PERF_POWERON)
+//   MODEM_TX        11   UART TX
+// ---------------------------------------------------------------------------
+
+// SMS field limits
+#define SMS_PHONE_LEN    20
+#define SMS_BODY_LEN    161   // 160 chars + null
+
+// Task configuration
+#define MODEM_TASK_PRIORITY   1       // Below mesh (default loop = priority 1 on core 1)
+#define MODEM_TASK_STACK_SIZE 6144    // Increased for call handling
+#define MODEM_TASK_CORE       0       // Run on core 0 (mesh runs on core 1)
+
+// Queue sizes
+#define MODEM_SEND_QUEUE_SIZE  4
+#define MODEM_RECV_QUEUE_SIZE  8
+#define MODEM_CALL_CMD_QUEUE_SIZE  4
+#define MODEM_CALL_EVT_QUEUE_SIZE  4
+
+// ---------------------------------------------------------------------------
+// Modem state machine
+// ---------------------------------------------------------------------------
+enum class ModemState {
+  OFF,
+  POWERING_ON,
+  INITIALIZING,
+  REGISTERING,
+  READY,
+  ERROR,
+  SENDING_SMS,
+  // Voice call states
+  DIALING,        // ATD sent, waiting for connect/carrier
+  RINGING_IN,     // Incoming call detected (RING URC)
+  IN_CALL         // Voice call active
+};
+
+// ---------------------------------------------------------------------------
+// SMS structures (unchanged)
+// ---------------------------------------------------------------------------
+
+// Outgoing SMS (queued from main loop to modem task)
+struct SMSOutgoing {
+  char phone[SMS_PHONE_LEN];
+  char body[SMS_BODY_LEN];
+};
+
+// Incoming SMS (queued from modem task to main loop)
+struct SMSIncoming {
+  char phone[SMS_PHONE_LEN];
+  char body[SMS_BODY_LEN];
+  uint32_t timestamp;   // epoch seconds (from modem RTC or millis-based)
+};
+
+// ---------------------------------------------------------------------------
+// Voice call structures
+// ---------------------------------------------------------------------------
+
+// Commands from main loop → modem task
+enum class CallCmd : uint8_t {
+  DIAL,           // Initiate outgoing call
+  ANSWER,         // Answer incoming call
+  HANGUP,         // End active call or reject incoming
+  DTMF,           // Send DTMF tone during call
+  SET_VOLUME      // Set speaker volume
+};
+
+struct CallCommand {
+  CallCmd cmd;
+  char phone[SMS_PHONE_LEN];   // Used by DIAL
+  char dtmf;                    // Used by DTMF (single digit: 0-9, *, #)
+  uint8_t volume;               // Used by SET_VOLUME (0-5)
+};
+
+// Events from modem task → main loop
+enum class CallEventType : uint8_t {
+  INCOMING,       // Incoming call ringing (+CLIP parsed)
+  CONNECTED,      // Call answered / outgoing connected
+  ENDED,          // Call ended (local hangup, remote hangup, or no carrier)
+  MISSED,         // Incoming call ended before answer
+  BUSY,           // Outgoing call got busy signal
+  NO_ANSWER,      // Outgoing call not answered
+  DIAL_FAILED     // ATD command failed
+};
+
+struct CallEvent {
+  CallEventType type;
+  char phone[SMS_PHONE_LEN];   // Caller/callee number (from +CLIP or dial)
+  uint32_t duration;            // Call duration in seconds (for ENDED)
+};
+
+// ---------------------------------------------------------------------------
+// ModemManager class
+// ---------------------------------------------------------------------------
+
+class ModemManager {
+public:
+  void begin();
+  void shutdown();
+
+  // --- SMS API (unchanged) ---
+  bool sendSMS(const char* phone, const char* body);
+  bool recvSMS(SMSIncoming& out);
+
+  // --- Voice Call API ---
+  bool dialCall(const char* phone);          // Queue outgoing call
+  bool answerCall();                          // Answer incoming call
+  bool hangupCall();                          // End active / reject incoming
+  bool sendDTMF(char digit);                  // Send DTMF during call
+  bool setCallVolume(uint8_t level);          // Set volume 0-5
+  bool pollCallEvent(CallEvent& out);         // Poll from main loop
+
+  // Ringtone control — called from main loop
+  void setRingtoneEnabled(bool en) { _ringtoneEnabled = en; }
+  bool isRingtoneEnabled() const { return _ringtoneEnabled; }
+
+  // --- State queries (lock-free reads) ---
+  ModemState getState() const { return _state; }
+  int  getSignalBars() const;       // 0-5
+  int  getCSQ() const { return _csq; }
+  bool isReady() const { return _state == ModemState::READY; }
+  bool isInCall() const { return _state == ModemState::IN_CALL; }
+  bool isRinging() const { return _state == ModemState::RINGING_IN; }
+  bool isDialing() const { return _state == ModemState::DIALING; }
+  bool isCallActive() const {
+    return _state == ModemState::IN_CALL ||
+           _state == ModemState::DIALING ||
+           _state == ModemState::RINGING_IN;
+  }
+  const char* getOperator() const { return _operator; }
+  const char* getCallPhone() const { return _callPhone; }
+  uint32_t getCallStartTime() const { return _callStartTime; }
+
+  // --- Device info (populated during init) ---
+  const char* getIMEI() const { return _imei; }
+  const char* getIMSI() const { return _imsi; }
+  const char* getAPN() const { return _apn; }
+  const char* getAPNSource() const { return _apnSource; }  // "auto", "network", "user", "none"
+
+  // --- APN configuration ---
+  // Set APN manually (overrides auto-detection). Persists to SD.
+  void setAPN(const char* apn);
+  // Load user-configured APN from SD card. Returns true if found.
+  static bool loadAPNConfig(char* apnOut, int maxLen);
+  // Save user-configured APN to SD card.
+  static void saveAPNConfig(const char* apn);
+
+  // Pause/resume polling — used by web reader to avoid Core 0 contention
+  // during WiFi TLS handshakes.  While paused, the task skips AT commands
+  // (SMS poll, CSQ poll) but still drains URCs and handles call commands
+  // so incoming calls aren't missed.
+  void pausePolling()  { _paused = true; }
+  void resumePolling() { _paused = false; }
+  bool isPaused() const { return _paused; }
+
+  static const char* stateToString(ModemState s);
+
+  // Persistent enable/disable config (SD file /sms/modem.cfg)
+  static bool loadEnabledConfig();
+  static void saveEnabledConfig(bool enabled);
+
+private:
+  volatile ModemState _state = ModemState::OFF;
+  volatile int _csq = 99;    // 99 = unknown
+  volatile bool _paused = false;  // Suppresses AT polling when true
+  char _operator[24] = {0};
+
+  // Device identity (populated during Phase 2 init)
+  char _imei[20] = {0};      // IMEI from AT+GSN
+  char _imsi[20] = {0};      // IMSI from AT+CIMI (for APN lookup)
+  char _apn[64] = {0};       // Active APN
+  char _apnSource[8] = {0};  // "auto", "network", "user", "none"
+
+  // Call state (written by modem task, read by main loop)
+  char _callPhone[SMS_PHONE_LEN] = {0};  // Current call number
+  volatile uint32_t _callStartTime = 0;    // millis() when call connected
+
+  // Ringtone state
+  volatile bool _ringtoneEnabled = false;
+  bool _ringing = false;              // Shadow of RINGING_IN for tone logic
+  unsigned long _nextRingTone = 0;    // Next tone burst timestamp (modem task)
+  bool _toneActive = false;           // Is a tone currently sounding
+
+  TaskHandle_t _taskHandle = nullptr;
+
+  // SMS queues
+  QueueHandle_t _sendQueue = nullptr;
+  QueueHandle_t _recvQueue = nullptr;
+
+  // Call queues
+  QueueHandle_t _callCmdQueue = nullptr;   // main loop → modem task
+  QueueHandle_t _callEvtQueue = nullptr;   // modem task → main loop
+
+  SemaphoreHandle_t _uartMutex = nullptr;
+
+  // URC line buffer (accumulated between AT commands)
+  static const int URC_BUF_SIZE = 256;
+  char _urcBuf[URC_BUF_SIZE];
+  int  _urcPos = 0;
+
+  // UART AT command helpers (called only from modem task)
+  bool modemPowerOn();
+  bool sendAT(const char* cmd, const char* expect, uint32_t timeout_ms = 2000);
+  bool waitResponse(const char* expect, uint32_t timeout_ms, char* buf = nullptr, size_t bufLen = 0);
+  void pollCSQ();
+  void pollIncomingSMS();
+  bool doSendSMS(const char* phone, const char* body);
+
+  // URC (unsolicited result code) handling
+  void drainURCs();                // Read available UART data, process complete lines
+  void processURCLine(const char* line);  // Handle a single URC line
+
+  // APN resolution (called from modem task during init)
+  void resolveAPN();              // Auto-detect APN from network/IMSI/user config
+
+  // Call control (called from modem task)
+  bool doDialCall(const char* phone);
+  bool doAnswerCall();
+  bool doHangup();
+  bool doSendDTMF(char digit);
+  bool doSetVolume(uint8_t level);
+  void queueCallEvent(CallEventType type, const char* phone = nullptr, uint32_t duration = 0);
+  void handleRingtone();  // Play tone bursts while incoming call rings
+
+  // FreeRTOS task
+  static void taskEntry(void* param);
+  void taskLoop();
+};
+
+// Global singleton
+extern ModemManager modemManager;
+
+#endif // MODEM_MANAGER_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/Radiopresets.h

@@ -0,0 +1,34 @@
+#pragma once
+
+// ---------------------------------------------------------------------------
+// Radio presets — shared between SettingsScreen (UI) and MyMesh (Serial CLI)
+// ---------------------------------------------------------------------------
+
+struct RadioPreset {
+  const char* name;
+  float freq;
+  float bw;
+  uint8_t sf;
+  uint8_t cr;
+  uint8_t tx_power;
+};
+
+static const RadioPreset RADIO_PRESETS[] = {
+  { "Australia",              915.800f, 250.0f,  10, 5, 22 },
+  { "Australia (Narrow)",     916.575f,  62.5f,   7, 8, 22 },
+  { "Australia: SA, WA",      923.125f,  62.5f,   8, 8, 22 },
+  { "Australia: QLD",         923.125f,  62.5f,   8, 5, 22 },
+  { "EU/UK (Narrow)",         869.618f,  62.5f,   8, 8, 14 },
+  { "EU/UK (Long Range)",     869.525f, 250.0f,  11, 5, 14 },
+  { "EU/UK (Medium Range)",   869.525f, 250.0f,  10, 5, 14 },
+  { "Czech Republic (Narrow)",869.432f,  62.5f,   7, 5, 14 },
+  { "EU 433 (Long Range)",    433.650f, 250.0f,  11, 5, 14 },
+  { "New Zealand",            917.375f, 250.0f,  11, 5, 22 },
+  { "New Zealand (Narrow)",   917.375f,  62.5f,   7, 5, 22 },
+  { "Portugal 433",           433.375f,  62.5f,   9, 6, 14 },
+  { "Portugal 868",           869.618f,  62.5f,   7, 6, 14 },
+  { "Switzerland",            869.618f,  62.5f,   8, 8, 14 },
+  { "USA/Canada (Recommended)",910.525f, 62.5f,   7, 5, 22 },
+  { "Vietnam",                920.250f, 250.0f,  11, 5, 22 },
+};
+#define NUM_RADIO_PRESETS (sizeof(RADIO_PRESETS) / sizeof(RADIO_PRESETS[0]))

examples/companion_radio/ui-new/SMSContacts.cpp

@@ -0,0 +1,8 @@
+#ifdef HAS_4G_MODEM
+
+#include "SMSContacts.h"
+
+// Global singleton
+SMSContactStore smsContacts;
+
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/SMSContacts.h

@@ -0,0 +1,176 @@
+#pragma once
+
+// =============================================================================
+// SMSContacts - Phone-to-name lookup for SMS contacts (4G variant)
+//
+// Stores contacts in /sms/contacts.txt on SD card.
+// Format: one contact per line as "phone=Display Name"
+//
+// Completely separate from mesh ContactInfo / IdentityStore.
+//
+// Guard: HAS_4G_MODEM
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef SMS_CONTACTS_H
+#define SMS_CONTACTS_H
+
+#include <Arduino.h>
+#include <SD.h>
+
+#define SMS_CONTACT_NAME_LEN   24
+#define SMS_CONTACT_MAX        30
+#define SMS_CONTACTS_FILE      "/sms/contacts.txt"
+
+struct SMSContact {
+  char phone[20];   // matches SMS_PHONE_LEN
+  char name[SMS_CONTACT_NAME_LEN];
+  bool valid;
+};
+
+class SMSContactStore {
+public:
+  void begin() {
+    _count = 0;
+    memset(_contacts, 0, sizeof(_contacts));
+    load();
+  }
+
+  // Look up a name by phone number. Returns nullptr if not found.
+  const char* lookup(const char* phone) const {
+    for (int i = 0; i < _count; i++) {
+      if (_contacts[i].valid && strcmp(_contacts[i].phone, phone) == 0) {
+        return _contacts[i].name;
+      }
+    }
+    return nullptr;
+  }
+
+  // Fill buf with display name if found, otherwise copy phone number.
+  // Returns true if a name was found.
+  bool displayName(const char* phone, char* buf, size_t bufLen) const {
+    const char* name = lookup(phone);
+    if (name && name[0]) {
+      strncpy(buf, name, bufLen - 1);
+      buf[bufLen - 1] = '\0';
+      return true;
+    }
+    strncpy(buf, phone, bufLen - 1);
+    buf[bufLen - 1] = '\0';
+    return false;
+  }
+
+  // Add or update a contact. Returns true on success.
+  bool set(const char* phone, const char* name) {
+    // Update existing
+    for (int i = 0; i < _count; i++) {
+      if (_contacts[i].valid && strcmp(_contacts[i].phone, phone) == 0) {
+        strncpy(_contacts[i].name, name, SMS_CONTACT_NAME_LEN - 1);
+        _contacts[i].name[SMS_CONTACT_NAME_LEN - 1] = '\0';
+        save();
+        return true;
+      }
+    }
+    // Add new
+    if (_count >= SMS_CONTACT_MAX) return false;
+    strncpy(_contacts[_count].phone, phone, sizeof(_contacts[_count].phone) - 1);
+    _contacts[_count].phone[sizeof(_contacts[_count].phone) - 1] = '\0';
+    strncpy(_contacts[_count].name, name, SMS_CONTACT_NAME_LEN - 1);
+    _contacts[_count].name[SMS_CONTACT_NAME_LEN - 1] = '\0';
+    _contacts[_count].valid = true;
+    _count++;
+    save();
+    return true;
+  }
+
+  // Remove a contact by phone number
+  bool remove(const char* phone) {
+    for (int i = 0; i < _count; i++) {
+      if (_contacts[i].valid && strcmp(_contacts[i].phone, phone) == 0) {
+        for (int j = i; j < _count - 1; j++) {
+          _contacts[j] = _contacts[j + 1];
+        }
+        _count--;
+        memset(&_contacts[_count], 0, sizeof(SMSContact));
+        save();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Accessors for list browsing
+  int count() const { return _count; }
+  const SMSContact& get(int index) const { return _contacts[index]; }
+
+  // Check if a contact exists
+  bool exists(const char* phone) const { return lookup(phone) != nullptr; }
+
+private:
+  SMSContact _contacts[SMS_CONTACT_MAX];
+  int _count = 0;
+
+  void load() {
+    File f = SD.open(SMS_CONTACTS_FILE, FILE_READ);
+    if (!f) {
+      Serial.println("[SMSContacts] No contacts file, starting fresh");
+      return;
+    }
+
+    char line[64];
+    while (f.available() && _count < SMS_CONTACT_MAX) {
+      int pos = 0;
+      while (f.available() && pos < (int)sizeof(line) - 1) {
+        char c = f.read();
+        if (c == '\n' || c == '\r') break;
+        line[pos++] = c;
+      }
+      line[pos] = '\0';
+      if (pos == 0) continue;
+      // Consume trailing CR/LF
+      while (f.available()) {
+        int pk = f.peek();
+        if (pk == '\n' || pk == '\r') { f.read(); continue; }
+        break;
+      }
+
+      // Parse "phone=name"
+      char* eq = strchr(line, '=');
+      if (!eq) continue;
+      *eq = '\0';
+      const char* phone = line;
+      const char* name = eq + 1;
+      if (strlen(phone) == 0 || strlen(name) == 0) continue;
+
+      strncpy(_contacts[_count].phone, phone, sizeof(_contacts[_count].phone) - 1);
+      strncpy(_contacts[_count].name, name, SMS_CONTACT_NAME_LEN - 1);
+      _contacts[_count].valid = true;
+      _count++;
+    }
+    f.close();
+    Serial.printf("[SMSContacts] Loaded %d contacts\n", _count);
+  }
+
+  void save() {
+    if (!SD.exists("/sms")) SD.mkdir("/sms");
+    File f = SD.open(SMS_CONTACTS_FILE, FILE_WRITE);
+    if (!f) {
+      Serial.println("[SMSContacts] Failed to write contacts file");
+      return;
+    }
+    for (int i = 0; i < _count; i++) {
+      if (!_contacts[i].valid) continue;
+      f.print(_contacts[i].phone);
+      f.print('=');
+      f.println(_contacts[i].name);
+    }
+    f.close();
+  }
+};
+
+// Global singleton
+extern SMSContactStore smsContacts;
+
+#endif // SMS_CONTACTS_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/SMSStore.cpp

@@ -0,0 +1,196 @@
+#ifdef HAS_4G_MODEM
+
+#include "SMSStore.h"
+#include <Mesh.h>   // For MESH_DEBUG_PRINTLN
+#include "target.h" // For SDCARD_CS macro
+
+// Global singleton
+SMSStore smsStore;
+
+void SMSStore::begin() {
+  // Ensure SMS directory exists
+  if (!SD.exists(SMS_DIR)) {
+    SD.mkdir(SMS_DIR);
+    MESH_DEBUG_PRINTLN("[SMSStore] created %s", SMS_DIR);
+  }
+  _ready = true;
+  MESH_DEBUG_PRINTLN("[SMSStore] ready");
+}
+
+void SMSStore::phoneToFilename(const char* phone, char* out, size_t outLen) {
+  // Convert phone number to safe filename: strip non-alphanumeric, prefix with dir
+  // e.g. "+1234567890" -> "/sms/p1234567890.sms"
+  char safe[SMS_PHONE_LEN];
+  int j = 0;
+  for (int i = 0; phone[i] && j < SMS_PHONE_LEN - 1; i++) {
+    char c = phone[i];
+    if ((c >= '0' && c <= '9') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) {
+      safe[j++] = c;
+    }
+  }
+  safe[j] = '\0';
+  snprintf(out, outLen, "%s/p%s.sms", SMS_DIR, safe);
+}
+
+bool SMSStore::saveMessage(const char* phone, const char* body, bool isSent, uint32_t timestamp) {
+  if (!_ready) return false;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  // Build record
+  SMSRecord rec;
+  memset(&rec, 0, sizeof(rec));
+  rec.timestamp = timestamp;
+  rec.isSent = isSent ? 1 : 0;
+  rec.bodyLen = strlen(body);
+  if (rec.bodyLen >= SMS_BODY_LEN) rec.bodyLen = SMS_BODY_LEN - 1;
+  strncpy(rec.phone, phone, SMS_PHONE_LEN - 1);
+  strncpy(rec.body, body, SMS_BODY_LEN - 1);
+
+  // Append to file
+  File f = SD.open(filepath, FILE_APPEND);
+  if (!f) {
+    // Try creating
+    f = SD.open(filepath, FILE_WRITE);
+    if (!f) {
+      MESH_DEBUG_PRINTLN("[SMSStore] can't open %s", filepath);
+      return false;
+    }
+  }
+
+  size_t written = f.write((uint8_t*)&rec, sizeof(rec));
+  f.close();
+
+  // Release SD CS
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return written == sizeof(rec);
+}
+
+int SMSStore::loadConversations(SMSConversation* out, int maxCount) {
+  if (!_ready) return 0;
+
+  File dir = SD.open(SMS_DIR);
+  if (!dir || !dir.isDirectory()) return 0;
+
+  int count = 0;
+  File entry;
+  while ((entry = dir.openNextFile()) && count < maxCount) {
+    const char* name = entry.name();
+    // Only process .sms files
+    if (!strstr(name, ".sms")) { entry.close(); continue; }
+
+    size_t fileSize = entry.size();
+    if (fileSize < sizeof(SMSRecord)) { entry.close(); continue; }
+
+    int numRecords = fileSize / sizeof(SMSRecord);
+
+    // Read the last record for preview
+    SMSRecord lastRec;
+    entry.seek(fileSize - sizeof(SMSRecord));
+    if (entry.read((uint8_t*)&lastRec, sizeof(SMSRecord)) != sizeof(SMSRecord)) {
+      entry.close();
+      continue;
+    }
+
+    SMSConversation& conv = out[count];
+    memset(&conv, 0, sizeof(SMSConversation));
+    strncpy(conv.phone, lastRec.phone, SMS_PHONE_LEN - 1);
+    strncpy(conv.preview, lastRec.body, 39);
+    conv.preview[39] = '\0';
+    conv.lastTimestamp = lastRec.timestamp;
+    conv.messageCount = numRecords;
+    conv.unreadCount = 0;  // TODO: track read state
+    conv.valid = true;
+
+    count++;
+    entry.close();
+  }
+  dir.close();
+
+  // Release SD CS
+  digitalWrite(SDCARD_CS, HIGH);
+
+  // Sort by most recent (simple bubble sort, small N)
+  for (int i = 0; i < count - 1; i++) {
+    for (int j = 0; j < count - 1 - i; j++) {
+      if (out[j].lastTimestamp < out[j + 1].lastTimestamp) {
+        SMSConversation tmp = out[j];
+        out[j] = out[j + 1];
+        out[j + 1] = tmp;
+      }
+    }
+  }
+
+  return count;
+}
+
+int SMSStore::loadMessages(const char* phone, SMSMessage* out, int maxCount) {
+  if (!_ready) return 0;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  File f = SD.open(filepath, FILE_READ);
+  if (!f) return 0;
+
+  size_t fileSize = f.size();
+  int numRecords = fileSize / sizeof(SMSRecord);
+
+  // Load from end of file (most recent N messages), in chronological order
+  int startIdx = numRecords > maxCount ? numRecords - maxCount : 0;
+
+  // Read chronologically (oldest first) for chat-style display
+  SMSRecord rec;
+  int outIdx = 0;
+  for (int i = startIdx; i < numRecords && outIdx < maxCount; i++) {
+    f.seek(i * sizeof(SMSRecord));
+    if (f.read((uint8_t*)&rec, sizeof(SMSRecord)) != sizeof(SMSRecord)) continue;
+
+    out[outIdx].timestamp = rec.timestamp;
+    out[outIdx].isSent = rec.isSent != 0;
+    out[outIdx].valid = true;
+    strncpy(out[outIdx].phone, rec.phone, SMS_PHONE_LEN - 1);
+    strncpy(out[outIdx].body, rec.body, SMS_BODY_LEN - 1);
+    outIdx++;
+  }
+
+  f.close();
+
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return outIdx;
+}
+
+bool SMSStore::deleteConversation(const char* phone) {
+  if (!_ready) return false;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  bool ok = SD.remove(filepath);
+
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return ok;
+}
+
+int SMSStore::getMessageCount(const char* phone) {
+  if (!_ready) return 0;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  File f = SD.open(filepath, FILE_READ);
+  if (!f) return 0;
+
+  int count = f.size() / sizeof(SMSRecord);
+  f.close();
+
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return count;
+}
+
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/SMSStore.h

@@ -0,0 +1,87 @@
+#pragma once
+
+// =============================================================================
+// SMSStore - SD card backed SMS message storage
+//
+// Stores sent and received messages in /sms/ on the SD card.
+// Each conversation is a separate file named by phone number (sanitised).
+// Messages are appended as fixed-size records for simple random access.
+//
+// Guard: HAS_4G_MODEM
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef SMS_STORE_H
+#define SMS_STORE_H
+
+#include <Arduino.h>
+#include <SD.h>
+
+#define SMS_PHONE_LEN    20
+#define SMS_BODY_LEN    161
+#define SMS_MAX_CONVERSATIONS 20
+#define SMS_DIR          "/sms"
+
+// Fixed-size on-disk record (256 bytes, easy alignment)
+struct SMSRecord {
+  uint32_t timestamp;           // epoch seconds
+  uint8_t  isSent;              // 1=sent, 0=received
+  uint8_t  reserved[2];
+  uint8_t  bodyLen;             // actual length of body
+  char     phone[SMS_PHONE_LEN]; // 20
+  char     body[SMS_BODY_LEN];   // 161
+  uint8_t  padding[256 - 4 - 3 - 1 - SMS_PHONE_LEN - SMS_BODY_LEN];
+};
+
+// In-memory message for UI
+struct SMSMessage {
+  uint32_t timestamp;
+  bool     isSent;
+  bool     valid;
+  char     phone[SMS_PHONE_LEN];
+  char     body[SMS_BODY_LEN];
+};
+
+// Conversation summary for inbox view
+struct SMSConversation {
+  char     phone[SMS_PHONE_LEN];
+  char     preview[40];         // last message preview
+  uint32_t lastTimestamp;
+  int      messageCount;
+  int      unreadCount;
+  bool     valid;
+};
+
+class SMSStore {
+public:
+  void begin();
+  bool isReady() const { return _ready; }
+
+  // Save a message (sent or received)
+  bool saveMessage(const char* phone, const char* body, bool isSent, uint32_t timestamp);
+
+  // Load conversation list (sorted by most recent)
+  int loadConversations(SMSConversation* out, int maxCount);
+
+  // Load messages for a specific phone number (chronological, oldest first)
+  int loadMessages(const char* phone, SMSMessage* out, int maxCount);
+
+  // Delete all messages for a phone number
+  bool deleteConversation(const char* phone);
+
+  // Get total message count for a phone number
+  int getMessageCount(const char* phone);
+
+private:
+  bool _ready = false;
+
+  // Convert phone number to safe filename
+  void phoneToFilename(const char* phone, char* out, size_t outLen);
+};
+
+// Global singleton
+extern SMSStore smsStore;
+
+#endif // SMS_STORE_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/Textreaderscreen.h

@@ -4,6 +4,7 @@
 #include <helpers/ui/DisplayDriver.h>
 #include <SD.h>
 #include <vector>
+#include "Utf8CP437.h"
 #include "EpubProcessor.h"
 
 // Forward declarations
@@ -14,7 +15,7 @@ class UITask;
 // ============================================================================
 #define BOOKS_FOLDER      "/books"
 #define INDEX_FOLDER      "/.indexes"
-#define INDEX_VERSION     4
+#define INDEX_VERSION     5  // v5: UTF-8 aware word wrap (accented char support)
 #define PREINDEX_PAGES    100
 #define READER_MAX_FILES  50
 #define READER_BUF_SIZE   4096
@@ -57,6 +58,10 @@ inline WrapResult findLineBreak(const char* buffer, int bufLen, int lineStart, i
     }
 
     if (c >= 32) {
+      // Skip UTF-8 continuation bytes (0x80-0xBF) - the lead byte already
+      // counted as one display character, so don't double-count these.
+      if ((uint8_t)c >= 0x80 && (uint8_t)c < 0xC0) continue;
+
       charCount++;
       if (c == ' ' || c == '\t') {
         if (inWord) {
@@ -177,8 +182,10 @@ private:
 
   // File list state
   std::vector<String> _fileList;
+  std::vector<String> _dirList;    // Subdirectories at current path
   std::vector<FileCache> _fileCache;
   int _selectedFile;
+  String _currentPath;             // Current browsed directory
 
   // Reading state
   File _file;
@@ -386,8 +393,8 @@ private:
     idxFile.read(&fullyFlag, 1);
     idxFile.read((uint8_t*)&lastRead, 4);
 
-    // Verify file hasn't changed - try BOOKS_FOLDER first, then epub cache
-    String fullPath = String(BOOKS_FOLDER) + "/" + filename;
+    // Verify file hasn't changed - try current path first, then epub cache
+    String fullPath = _currentPath + "/" + filename;
     File txtFile = SD.open(fullPath.c_str(), FILE_READ);
     if (!txtFile) {
       // Fallback: check epub cache directory
@@ -477,33 +484,94 @@ private:
 
   // ---- File Scanning ----
 
+  // ---- Folder Navigation Helpers ----
+
+  bool isAtBooksRoot() const {
+    return _currentPath == String(BOOKS_FOLDER);
+  }
+
+  // Number of non-file entries at the start of the visual list
+  int dirEntryCount() const {
+    int count = _dirList.size();
+    if (!isAtBooksRoot()) count++;  // ".." entry
+    return count;
+  }
+
+  // Total items in the visual list (parent + dirs + files)
+  int totalListItems() const {
+    return dirEntryCount() + (int)_fileList.size();
+  }
+
+  // What type of entry is at visual list index idx?
+  // Returns: 0 = ".." parent, 1 = directory, 2 = file
+  int itemTypeAt(int idx) const {
+    bool hasParent = !isAtBooksRoot();
+    if (hasParent && idx == 0) return 0;  // ".."
+    int dirStart = hasParent ? 1 : 0;
+    if (idx < dirStart + (int)_dirList.size()) return 1;  // directory
+    return 2;  // file
+  }
+
+  // Get directory name for visual index (only valid when itemTypeAt == 1)
+  const String& dirNameAt(int idx) const {
+    int dirStart = isAtBooksRoot() ? 0 : 1;
+    return _dirList[idx - dirStart];
+  }
+
+  // Get file list index for visual index (only valid when itemTypeAt == 2)
+  int fileIndexAt(int idx) const {
+    return idx - dirEntryCount();
+  }
+
+  void navigateToParent() {
+    int lastSlash = _currentPath.lastIndexOf('/');
+    if (lastSlash > 0) {
+      _currentPath = _currentPath.substring(0, lastSlash);
+    } else {
+      _currentPath = BOOKS_FOLDER;
+    }
+  }
+
+  void navigateToChild(const String& dirName) {
+    _currentPath = _currentPath + "/" + dirName;
+  }
+
+  // ---- File Scanning ----
+
   void scanFiles() {
     _fileList.clear();
+    _dirList.clear();
     if (!SD.exists(BOOKS_FOLDER)) {
       SD.mkdir(BOOKS_FOLDER);
       Serial.printf("TextReader: Created %s\n", BOOKS_FOLDER);
     }
 
-    File root = SD.open(BOOKS_FOLDER);
+    File root = SD.open(_currentPath.c_str());
     if (!root || !root.isDirectory()) return;
 
     File f = root.openNextFile();
-    while (f && _fileList.size() < READER_MAX_FILES) {
-      if (!f.isDirectory()) {
-        String name = String(f.name());
-        int slash = name.lastIndexOf('/');
-        if (slash >= 0) name = name.substring(slash + 1);
+    while (f && (_fileList.size() + _dirList.size()) < READER_MAX_FILES) {
+      String name = String(f.name());
+      int slash = name.lastIndexOf('/');
+      if (slash >= 0) name = name.substring(slash + 1);
 
-        if (!name.startsWith(".") &&
-            (name.endsWith(".txt") || name.endsWith(".TXT") ||
-             name.endsWith(".epub") || name.endsWith(".EPUB"))) {
-          _fileList.push_back(name);
-        }
+      // Skip hidden files/dirs
+      if (name.startsWith(".")) {
+        f = root.openNextFile();
+        continue;
+      }
+
+      if (f.isDirectory()) {
+        _dirList.push_back(name);
+      } else if (name.endsWith(".txt") || name.endsWith(".TXT") ||
+                 name.endsWith(".epub") || name.endsWith(".EPUB")) {
+        _fileList.push_back(name);
       }
       f = root.openNextFile();
     }
     root.close();
-    Serial.printf("TextReader: Found %d files\n", _fileList.size());
+    Serial.printf("TextReader: %s — %d dirs, %d files\n",
+                  _currentPath.c_str(), (int)_dirList.size(), (int)_fileList.size());
   }
 
   // ---- Book Open/Close ----
@@ -513,7 +581,7 @@ private:
 
     // ---- EPUB auto-conversion ----
     String actualFilename = filename;
-    String actualFullPath = String(BOOKS_FOLDER) + "/" + filename;
+    String actualFullPath = _currentPath + "/" + filename;
     bool isEpub = filename.endsWith(".epub") || filename.endsWith(".EPUB");
 
     if (isEpub) {
@@ -603,7 +671,7 @@ private:
         _currentPage = cache->lastReadPage;
       }
 
-      // Already fully indexed — open immediately
+      // Already fully indexed — open immediately
       if (cache->fullyIndexed) {
         _totalPages = _pagePositions.size();
         _mode = READING;
@@ -613,7 +681,7 @@ private:
         return;
       }
 
-      // Partially indexed — finish indexing with splash
+      // Partially indexed — finish indexing with splash
       Serial.printf("TextReader: Finishing index for %s (have %d pages so far)\n",
                     actualFilename.c_str(), (int)_pagePositions.size());
 
@@ -629,7 +697,7 @@ private:
       drawSplash("Indexing...", "Please wait", shortName);
 
       if (_pagePositions.empty()) {
-        // Cache had no pages (e.g. dummy entry) — full index from scratch
+        // Cache had no pages (e.g. dummy entry) — full index from scratch
         _pagePositions.push_back(0);
         indexPagesWordWrap(_file, 0, _pagePositions,
                            _linesPerPage, _charsPerLine, 0);
@@ -639,7 +707,7 @@ private:
                            _linesPerPage, _charsPerLine, 0);
       }
     } else {
-      // No cache — full index from scratch
+      // No cache — full index from scratch
       Serial.printf("TextReader: Full index for %s\n", actualFilename.c_str());
 
       char shortName[28];
@@ -750,15 +818,26 @@ private:
     display.setCursor(0, 0);
     display.setTextSize(1);
     display.setColor(DisplayDriver::GREEN);
-    display.print("Text Reader");
+    if (isAtBooksRoot()) {
+      display.print("Text Reader");
+    } else {
+      // Show current subfolder name
+      int lastSlash = _currentPath.lastIndexOf('/');
+      String folderName = (lastSlash >= 0) ? _currentPath.substring(lastSlash + 1) : _currentPath;
+      char hdrBuf[20];
+      strncpy(hdrBuf, folderName.c_str(), 17);
+      hdrBuf[17] = '\0';
+      display.print(hdrBuf);
+    }
 
-    sprintf(tmp, "[%d]", (int)_fileList.size());
+    int totalItems = totalListItems();
+    sprintf(tmp, "[%d]", totalItems);
     display.setCursor(display.width() - display.getTextWidth(tmp) - 2, 0);
     display.print(tmp);
 
     display.drawRect(0, 11, display.width(), 1);
 
-    if (_fileList.size() == 0) {
+    if (totalItems == 0) {
       display.setCursor(0, 18);
       display.setColor(DisplayDriver::LIGHT);
       display.print("No files found");
@@ -775,8 +854,8 @@ private:
       if (maxVisible > 15) maxVisible = 15;
 
       int startIdx = max(0, min(_selectedFile - maxVisible / 2,
-                                (int)_fileList.size() - maxVisible));
-      int endIdx = min((int)_fileList.size(), startIdx + maxVisible);
+                                totalItems - maxVisible));
+      int endIdx = min(totalItems, startIdx + maxVisible);
 
       int y = startY;
       for (int i = startIdx; i < endIdx; i++) {
@@ -795,27 +874,41 @@ private:
         // Set cursor AFTER fillRect so text draws on top of highlight
         display.setCursor(0, y);
 
-        // Build display string: "> filename.txt *" (asterisk if has bookmark)
+        int type = itemTypeAt(i);
         String line = selected ? "> " : "  ";
-        String name = _fileList[i];
 
-        // Check for resume indicator
-        String suffix = "";
-        for (int j = 0; j < (int)_fileCache.size(); j++) {
-          if (_fileCache[j].filename == name && _fileCache[j].lastReadPage > 0) {
-            suffix = " *";
-            break;
+        if (type == 0) {
+          // ".." parent directory
+          line += ".. (up)";
+        } else if (type == 1) {
+          // Subdirectory
+          line += "/" + dirNameAt(i);
+          // Truncate if needed
+          if ((int)line.length() > _charsPerLine) {
+            line = line.substring(0, _charsPerLine - 3) + "...";
           }
+        } else {
+          // File
+          int fi = fileIndexAt(i);
+          String name = _fileList[fi];
+
+          // Check for resume indicator
+          String suffix = "";
+          if (fi < (int)_fileCache.size()) {
+            if (_fileCache[fi].filename == name && _fileCache[fi].lastReadPage > 0) {
+              suffix = " *";
+            }
+          }
+
+          // Truncate if needed
+          int maxLen = _charsPerLine - 4 - suffix.length();
+          if ((int)name.length() > maxLen) {
+            name = name.substring(0, maxLen - 3) + "...";
+          }
+          line += name + suffix;
         }
 
-        // Truncate if needed
-        int maxLen = _charsPerLine - 4 - suffix.length();
-        if ((int)name.length() > maxLen) {
-          name = name.substring(0, maxLen - 3) + "...";
-        }
-        line += name + suffix;
         display.print(line.c_str());
-
         y += listLineH;
       }
       display.setTextSize(1);  // Restore
@@ -855,12 +948,40 @@ private:
       if (wrap.nextStart <= oldPos && wrap.lineEnd >= _pageBufLen) break;
 
       display.setCursor(0, y);
-      // Print line character by character (only printable)
+      // Print line with UTF-8 decoding: multi-byte sequences are decoded
+      // to Unicode codepoints, then mapped to CP437 for the built-in font.
       char charStr[2] = {0, 0};
-      for (int j = pos; j < wrap.lineEnd && j < _pageBufLen; j++) {
-        if (_pageBuf[j] >= 32) {
-          charStr[0] = _pageBuf[j];
+      int j = pos;
+      while (j < wrap.lineEnd && j < _pageBufLen) {
+        uint8_t b = (uint8_t)_pageBuf[j];
+
+        if (b < 32) {
+          // Control character — skip
+          j++;
+          continue;
+        }
+
+        if (b < 0x80) {
+          // Plain ASCII — print directly
+          charStr[0] = (char)b;
           display.print(charStr);
+          j++;
+        } else if (b >= 0xC0) {
+          // UTF-8 lead byte — decode full sequence and map to CP437
+          int savedJ = j;
+          uint32_t cp = decodeUtf8Char(_pageBuf, wrap.lineEnd, &j);
+          uint8_t glyph = unicodeToCP437(cp);
+          if (glyph) {
+            charStr[0] = (char)glyph;
+            display.print(charStr);
+          }
+          // If unmappable (glyph==0), just skip the character
+        } else {
+          // Standalone byte 0x80-0xBF: not a valid UTF-8 lead byte.
+          // Treat as CP437 pass-through (e.g. from EPUB numeric entity decoding).
+          charStr[0] = (char)b;
+          display.print(charStr);
+          j++;
         }
       }
 
@@ -895,7 +1016,8 @@ public:
       _bootIndexed(false), _display(nullptr),
       _charsPerLine(38), _linesPerPage(22), _lineHeight(5),
       _headerHeight(14), _footerHeight(14),
-      _selectedFile(0), _fileOpen(false), _currentPage(0), _totalPages(0),
+      _selectedFile(0), _currentPath(BOOKS_FOLDER),
+      _fileOpen(false), _currentPage(0), _totalPages(0),
       _pageBufLen(0), _contentDirty(true) {
   }
 
@@ -997,7 +1119,7 @@ public:
 
     // --- Pass 1: Fast cache load (no per-file splash screens) ---
     // Try to load existing .idx files from SD for every file.
-    // This is just SD reads — no indexing, no e-ink refreshes.
+    // This is just SD reads — no indexing, no e-ink refreshes.
     _fileCache.clear();
     _fileCache.resize(_fileList.size());  // Pre-allocate slots to maintain alignment with _fileList
 
@@ -1026,7 +1148,7 @@ public:
         // Skip files that loaded from cache
         if (_fileCache[i].filename.length() > 0) continue;
 
-        // Skip .epub files — they'll be converted on first open via openBook()
+        // Skip .epub files — they'll be converted on first open via openBook()
         if (_fileList[i].endsWith(".epub") || _fileList[i].endsWith(".EPUB")) {
           needsIndexCount--;  // Don't count epubs in progress display
           continue;
@@ -1035,8 +1157,8 @@ public:
         indexProgress++;
         drawBootSplash(indexProgress, needsIndexCount, _fileList[i]);
 
-        // Try BOOKS_FOLDER first, then epub cache fallback
-        String fullPath = String(BOOKS_FOLDER) + "/" + _fileList[i];
+        // Try current path first, then epub cache fallback
+        String fullPath = _currentPath + "/" + _fileList[i];
         File file = SD.open(fullPath.c_str(), FILE_READ);
         if (!file) {
           String cacheFallback = String("/books/.epub_cache/") + _fileList[i];
@@ -1133,6 +1255,8 @@ public:
   }
 
   bool handleFileListInput(char c) {
+    int total = totalListItems();
+
     // W - scroll up
     if (c == 'w' || c == 'W' || c == 0xF2) {
       if (_selectedFile > 0) {
@@ -1144,18 +1268,36 @@ public:
 
     // S - scroll down
     if (c == 's' || c == 'S' || c == 0xF1) {
-      if (_selectedFile < (int)_fileList.size() - 1) {
+      if (_selectedFile < total - 1) {
         _selectedFile++;
         return true;
       }
       return false;
     }
 
-    // Enter - open selected file
+    // Enter - open selected item (directory or file)
     if (c == '\r' || c == 13) {
-      if (_fileList.size() > 0 && _selectedFile < (int)_fileList.size()) {
-        openBook(_fileList[_selectedFile]);
+      if (total == 0 || _selectedFile >= total) return false;
+
+      int type = itemTypeAt(_selectedFile);
+
+      if (type == 0) {
+        // ".." — navigate to parent
+        navigateToParent();
+        rescanAndIndex();
         return true;
+      } else if (type == 1) {
+        // Subdirectory — navigate into it
+        navigateToChild(dirNameAt(_selectedFile));
+        rescanAndIndex();
+        return true;
+      } else {
+        // File — open it
+        int fi = fileIndexAt(_selectedFile);
+        if (fi >= 0 && fi < (int)_fileList.size()) {
+          openBook(_fileList[fi]);
+          return true;
+        }
       }
       return false;
     }
@@ -1163,6 +1305,53 @@ public:
     return false;
   }
 
+  // Rescan current directory and re-index its files.
+  // Called when navigating into or out of a subfolder.
+  void rescanAndIndex() {
+    scanFiles();
+    _selectedFile = 0;
+
+    // Rebuild file cache for the new directory's files
+    _fileCache.clear();
+    _fileCache.resize(_fileList.size());
+
+    for (int i = 0; i < (int)_fileList.size(); i++) {
+      if (!loadIndex(_fileList[i], _fileCache[i])) {
+        // Not cached — skip EPUB auto-indexing here (it happens on open)
+        // For .txt files, index now
+        if (!(_fileList[i].endsWith(".epub") || _fileList[i].endsWith(".EPUB"))) {
+          String fullPath = _currentPath + "/" + _fileList[i];
+          File file = SD.open(fullPath.c_str(), FILE_READ);
+          if (!file) {
+            // Try epub cache fallback
+            String cacheFallback = String("/books/.epub_cache/") + _fileList[i];
+            file = SD.open(cacheFallback.c_str(), FILE_READ);
+          }
+          if (file) {
+            FileCache& cache = _fileCache[i];
+            cache.filename = _fileList[i];
+            cache.fileSize = file.size();
+            cache.fullyIndexed = false;
+            cache.lastReadPage = 0;
+            cache.pagePositions.clear();
+            cache.pagePositions.push_back(0);
+            indexPagesWordWrap(file, 0, cache.pagePositions,
+                               _linesPerPage, _charsPerLine,
+                               PREINDEX_PAGES - 1);
+            cache.fullyIndexed = !file.available();
+            file.close();
+            saveIndex(cache.filename, cache.pagePositions, cache.fileSize,
+                      cache.fullyIndexed, 0);
+          }
+        } else {
+          _fileCache[i].filename = "";
+        }
+      }
+      yield();  // Feed WDT between files
+    }
+    digitalWrite(SDCARD_CS, HIGH);
+  }
+
   bool handleReadingInput(char c) {
     // W/A - previous page
     if (c == 'w' || c == 'W' || c == 'a' || c == 'A' || c == 0xF2) {

examples/companion_radio/ui-new/Touchinput.h

@@ -0,0 +1,128 @@
+#pragma once
+
+// =============================================================================
+// TouchInput - Minimal CST328/CST3530 touch driver for T-Deck Pro
+//
+// Uses raw I2C reads on the shared Wire bus. No external library needed.
+// Protocol confirmed via raw serial capture from actual hardware:
+//
+//   Register 0xD000, 7 bytes:
+//   buf[0]: event flags (0xAB = idle/no touch, other = active touch)
+//   buf[1]: X coordinate high data
+//   buf[2]: Y coordinate high data
+//   buf[3]: X low nibble (bits 7:4) | Y low nibble (bits 3:0)
+//   buf[4]: pressure
+//   buf[5]: touch count (& 0x7F), typically 0x01 for single touch
+//   buf[6]: 0xAB always (check byte, ignore)
+//
+//   Coordinate formula:
+//     x = (buf[1] << 4) | ((buf[3] >> 4) & 0x0F)   → 0..239
+//     y = (buf[2] << 4) | (buf[3] & 0x0F)           → 0..319
+//
+// Hardware: CST328 at 0x1A, INT=GPIO12, RST=GPIO38 (V1.1)
+//
+// Guard: HAS_TOUCHSCREEN
+// =============================================================================
+
+#ifdef HAS_TOUCHSCREEN
+
+#ifndef TOUCH_INPUT_H
+#define TOUCH_INPUT_H
+
+#include <Arduino.h>
+#include <Wire.h>
+
+class TouchInput {
+public:
+  static const uint8_t TOUCH_ADDR = 0x1A;
+
+  TouchInput(TwoWire* wire = &Wire)
+    : _wire(wire), _intPin(-1), _initialized(false), _debugCount(0), _lastPoll(0) {}
+
+  bool begin(int intPin) {
+    _intPin = intPin;
+    pinMode(_intPin, INPUT);
+
+    // Verify the touch controller is present on the bus
+    _wire->beginTransmission(TOUCH_ADDR);
+    uint8_t err = _wire->endTransmission();
+    if (err != 0) {
+      Serial.printf("[Touch] CST328 not found at 0x%02X (err=%d)\n", TOUCH_ADDR, err);
+      return false;
+    }
+
+    Serial.printf("[Touch] CST328 found at 0x%02X, INT=GPIO%d\n", TOUCH_ADDR, _intPin);
+    _initialized = true;
+    return true;
+  }
+
+  bool isReady() const { return _initialized; }
+
+  // Poll for touch. Returns true if a finger is down, fills x and y.
+  // Coordinates are in physical display space (0-239 X, 0-319 Y).
+  // NOTE: CST328 INT pin is pulse-based, not level. We cannot rely on
+  // digitalRead(INT) for touch state. Instead, always read and check buf[0].
+  bool getPoint(int16_t &x, int16_t &y) {
+    if (!_initialized) return false;
+
+    // Rate limit: poll at most every 20ms (50 Hz) to avoid I2C bus congestion
+    unsigned long now = millis();
+    if (now - _lastPoll < 20) return false;
+    _lastPoll = now;
+
+    uint8_t buf[7];
+    memset(buf, 0, sizeof(buf));
+
+    // Write register address 0xD000
+    _wire->beginTransmission(TOUCH_ADDR);
+    _wire->write(0xD0);
+    _wire->write(0x00);
+    if (_wire->endTransmission(false) != 0) return false;
+
+    // Read 7 bytes of touch data
+    uint8_t received = _wire->requestFrom(TOUCH_ADDR, (uint8_t)7);
+    if (received < 7) return false;
+    for (int i = 0; i < 7; i++) buf[i] = _wire->read();
+
+    // buf[0] == 0xAB means idle (no touch active)
+    if (buf[0] == 0xAB) return false;
+
+    // buf[0] == 0x00 can appear on finger-up transition — ignore
+    if (buf[0] == 0x00) return false;
+
+    // Touch count from buf[5]
+    uint8_t count = buf[5] & 0x7F;
+    if (count == 0 || count > 5) return false;
+
+    // Parse coordinates (CST226/CST328 format confirmed by hardware capture)
+    //   x = (buf[1] << 4) | high nibble of buf[3]
+    //   y = (buf[2] << 4) | low nibble of buf[3]
+    int16_t tx = ((int16_t)buf[1] << 4) | ((buf[3] >> 4) & 0x0F);
+    int16_t ty = ((int16_t)buf[2] << 4) | (buf[3] & 0x0F);
+
+    // Sanity check (panel is 240x320)
+    if (tx < 0 || tx > 260 || ty < 0 || ty > 340) return false;
+
+    // Debug: log first 20 touch events with parsed coordinates
+    if (_debugCount < 50) {
+      Serial.printf("[Touch] Raw: %02X %02X %02X %02X %02X %02X %02X → x=%d y=%d\n",
+                    buf[0], buf[1], buf[2], buf[3], buf[4], buf[5], buf[6],
+                    tx, ty);
+      _debugCount++;
+    }
+
+    x = tx;
+    y = ty;
+    return true;
+  }
+
+private:
+  TwoWire* _wire;
+  int _intPin;
+  bool _initialized;
+  int _debugCount;
+  unsigned long _lastPoll;
+};
+
+#endif // TOUCH_INPUT_H
+#endif // HAS_TOUCHSCREEN

examples/companion_radio/ui-new/UITask.h

@@ -22,6 +22,17 @@
 #include "../AbstractUITask.h"
 #include "../NodePrefs.h"
 
+#ifdef HAS_4G_MODEM
+  #include "SMSScreen.h"
+#endif
+
+#ifdef MECK_WEB_READER
+  #include "WebReaderScreen.h"
+#endif
+
+// MapScreen.h included in UITask.cpp and main.cpp only (PNGdec headers
+// conflict with BLE if pulled into the global include chain)
+
 class UITask : public AbstractUITask {
   DisplayDriver* _display;
   SensorManager* _sensors;
@@ -32,11 +43,18 @@ class UITask : public AbstractUITask {
   GenericVibration vibration;
 #endif
   unsigned long _next_refresh, _auto_off;
+  unsigned long _kb_flash_off_at;          // Keyboard flash turn-off timer
+#ifdef HAS_4G_MODEM
+  bool _incomingCallRinging;               // Currently ringing (incoming call)
+  unsigned long _nextCallFlash;            // Next LED toggle time
+  bool _callFlashState;                    // Current LED state during ring
+#endif
   NodePrefs* _node_prefs;
   char _alert[80];
   unsigned long _alert_expiry;
   int _msgcount;
   unsigned long ui_started_at, next_batt_chck;
+  uint8_t _low_batt_count = 0;  // Consecutive low-voltage readings for debounce
   int next_backlight_btn_check = 0;
 #ifdef PIN_STATUS_LED
   int led_state = 0;
@@ -54,7 +72,18 @@ class UITask : public AbstractUITask {
   UIScreen* channel_screen;  // Channel message history screen
   UIScreen* contacts_screen; // Contacts list screen
   UIScreen* text_reader;     // *** NEW: Text reader screen ***
-  UIScreen* repeater_admin;  // Repeater admin screen
+  UIScreen* notes_screen;    // Notes editor screen
+  UIScreen* settings_screen; // Settings/onboarding screen
+  UIScreen* audiobook_screen; // Audiobook player screen (null if not available)
+#ifdef HAS_4G_MODEM
+  UIScreen* sms_screen;      // SMS messaging screen (4G variant only)
+#endif
+  UIScreen* repeater_admin;   // Repeater admin screen
+  UIScreen* discovery_screen;  // Node discovery scan screen
+#ifdef MECK_WEB_READER
+  UIScreen* web_reader;       // Web reader screen (lazy-init, WiFi required)
+#endif
+  UIScreen* map_screen;       // Map tile screen (GPS + SD card tiles)
   UIScreen* curr;
 
   void userLedHandler();
@@ -71,6 +100,12 @@ public:
 
   UITask(mesh::MainBoard* board, BaseSerialInterface* serial) : AbstractUITask(board, serial), _display(NULL), _sensors(NULL) {
     next_batt_chck = _next_refresh = 0;
+    _kb_flash_off_at = 0;
+  #ifdef HAS_4G_MODEM
+    _incomingCallRinging = false;
+    _nextCallFlash = 0;
+    _callFlashState = false;
+  #endif
     ui_started_at = 0;
     curr = NULL;
   }
@@ -80,42 +115,95 @@ public:
   void gotoChannelScreen();  // Navigate to channel message screen
   void gotoContactsScreen(); // Navigate to contacts list
   void gotoTextReader();     // *** NEW: Navigate to text reader ***
+  void gotoNotesScreen();    // Navigate to notes editor
+  void gotoSettingsScreen(); // Navigate to settings
+  void gotoOnboarding();     // Navigate to settings in onboarding mode
+  void gotoAudiobookPlayer(); // Navigate to audiobook player
   void gotoRepeaterAdmin(int contactIdx);  // Navigate to repeater admin
+  void gotoDiscoveryScreen();              // Navigate to node discovery scan
+  void gotoMapScreen();         // Navigate to map tile screen
+#ifdef MECK_WEB_READER
+  void gotoWebReader();         // Navigate to web reader (browser)
+#endif
+#ifdef HAS_4G_MODEM
+  void gotoSMSScreen();
+  bool isOnSMSScreen() const { return curr == sms_screen; }
+  SMSScreen* getSMSScreen() const { return (SMSScreen*)sms_screen; }
+#endif
   void showAlert(const char* text, int duration_millis) override;
   void forceRefresh() override { _next_refresh = 100; }
+  // Wake display and extend auto-off timer. Call this when handling keys
+  // outside of injectKey() to prevent display auto-off during direct input.
+  void keepAlive() {
+    if (_display != NULL && !_display->isOn()) _display->turnOn();
+    _auto_off = millis() + 15000;  // matches AUTO_OFF_MILLIS default
+  }
   int  getMsgCount() const { return _msgcount; }
+  int  getUnreadMsgCount() const;  // Per-channel unread tracking (standalone)
   bool hasDisplay() const { return _display != NULL; }
   bool isButtonPressed() const;
   bool isOnChannelScreen() const { return curr == channel_screen; }
   bool isOnContactsScreen() const { return curr == contacts_screen; }
   bool isOnTextReader() const { return curr == text_reader; }  // *** NEW ***
+  bool isOnNotesScreen() const { return curr == notes_screen; }
+  bool isOnSettingsScreen() const { return curr == settings_screen; }
+  bool isOnAudiobookPlayer() const { return curr == audiobook_screen; }
   bool isOnRepeaterAdmin() const { return curr == repeater_admin; }
+  bool isOnDiscoveryScreen() const { return curr == discovery_screen; }
+  bool isOnMapScreen() const { return curr == map_screen; }
+#ifdef MECK_WEB_READER
+  bool isOnWebReader() const { return curr == web_reader; }
+#endif
+
+#ifdef MECK_AUDIO_VARIANT
+  // Check if audio is playing/paused in the background (for status indicators)
+  bool isAudioPlayingInBackground() const;
+  bool isAudioPausedInBackground() const;
+#endif
   uint8_t getChannelScreenViewIdx() const;
 
   void toggleBuzzer();
   bool getGPSState();
   void toggleGPS();
 
+  // Check if home screen is in an editing mode (e.g. UTC offset editor)
+  bool isEditingHomeScreen() const;
+
   // Inject a key press from external source (e.g., keyboard)
   void injectKey(char c);
   
   // Add a sent message to the channel screen history
   void addSentChannelMessage(uint8_t channel_idx, const char* sender, const char* text) override;
 
+  // Mark channel as read when BLE companion app syncs messages
+  void markChannelReadFromBLE(uint8_t channel_idx) override;
+
   // Repeater admin callbacks
   void onAdminLoginResult(bool success, uint8_t permissions, uint32_t server_time) override;
   void onAdminCliResponse(const char* from_name, const char* text) override;
+  void onAdminTelemetryResult(const uint8_t* data, uint8_t len) override;
   
   // Get current screen for checking state
   UIScreen* getCurrentScreen() const { return curr; }
   UIScreen* getMsgPreviewScreen() const { return msg_preview; }
   UIScreen* getTextReaderScreen() const { return text_reader; }  // *** NEW ***
+  UIScreen* getNotesScreen() const { return notes_screen; }
   UIScreen* getContactsScreen() const { return contacts_screen; }
+  UIScreen* getChannelScreen() const { return channel_screen; }
+  UIScreen* getSettingsScreen() const { return settings_screen; }
+  UIScreen* getAudiobookScreen() const { return audiobook_screen; }
+  void setAudiobookScreen(UIScreen* s) { audiobook_screen = s; }
   UIScreen* getRepeaterAdminScreen() const { return repeater_admin; }
+  UIScreen* getDiscoveryScreen() const { return discovery_screen; }
+  UIScreen* getMapScreen() const { return map_screen; }
+#ifdef MECK_WEB_READER
+  UIScreen* getWebReaderScreen() const { return web_reader; }
+#endif
 
   // from AbstractUITask
   void msgRead(int msgcount) override;
-  void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount) override;
+  void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount,
+             const uint8_t* path = nullptr) override;
   void notify(UIEventType t = UIEventType::none) override;
   void loop() override;
 

examples/companion_radio/ui-new/Utf8cp437.h

@@ -0,0 +1,152 @@
+#pragma once
+// =============================================================================
+// Utf8CP437.h - UTF-8 decoding and Unicode-to-CP437 mapping
+//
+// The Adafruit GFX built-in 6x8 font uses the CP437 character set for codes
+// 128-255. This header provides utilities to:
+//   1. Decode UTF-8 multi-byte sequences into Unicode codepoints
+//   2. Map Unicode codepoints to CP437 byte values for display
+//
+// Used by both EpubProcessor (at XHTML→text conversion time) and
+// TextReaderScreen (at render time for plain .txt files).
+// =============================================================================
+
+// Map a Unicode codepoint to its CP437 equivalent byte.
+// Returns the CP437 byte (0x80-0xFF) for supported accented characters,
+// the codepoint itself for ASCII (0x20-0x7E), or 0 if unmappable.
+inline uint8_t unicodeToCP437(uint32_t cp) {
+  // ASCII passthrough
+  if (cp >= 0x20 && cp < 0x7F) return (uint8_t)cp;
+
+  switch (cp) {
+    // Uppercase accented
+    case 0x00C7: return 0x80;  // Ç
+    case 0x00C9: return 0x90;  // É
+    case 0x00C4: return 0x8E;  // Ä
+    case 0x00C5: return 0x8F;  // Å
+    case 0x00C6: return 0x92;  // Æ
+    case 0x00D6: return 0x99;  // Ö
+    case 0x00DC: return 0x9A;  // Ü
+    case 0x00D1: return 0xA5;  // Ñ
+
+    // Lowercase accented
+    case 0x00E9: return 0x82;  // é
+    case 0x00E2: return 0x83;  // â
+    case 0x00E4: return 0x84;  // ä
+    case 0x00E0: return 0x85;  // à
+    case 0x00E5: return 0x86;  // å
+    case 0x00E7: return 0x87;  // ç
+    case 0x00EA: return 0x88;  // ê
+    case 0x00EB: return 0x89;  // ë
+    case 0x00E8: return 0x8A;  // è
+    case 0x00EF: return 0x8B;  // ï
+    case 0x00EE: return 0x8C;  // î
+    case 0x00EC: return 0x8D;  // ì
+    case 0x00E6: return 0x91;  // æ
+    case 0x00F4: return 0x93;  // ô
+    case 0x00F6: return 0x94;  // ö
+    case 0x00F2: return 0x95;  // ò
+    case 0x00FB: return 0x96;  // û
+    case 0x00F9: return 0x97;  // ù
+    case 0x00FF: return 0x98;  // ÿ
+    case 0x00FC: return 0x81;  // ü
+    case 0x00E1: return 0xA0;  // á
+    case 0x00ED: return 0xA1;  // í
+    case 0x00F3: return 0xA2;  // ó
+    case 0x00FA: return 0xA3;  // ú
+    case 0x00F1: return 0xA4;  // ñ
+
+    // Currency / symbols
+    case 0x00A2: return 0x9B;  // ¢
+    case 0x00A3: return 0x9C;  // £
+    case 0x00A5: return 0x9D;  // ¥
+    case 0x00BF: return 0xA8;  // ¿
+    case 0x00A1: return 0xAD;  // ¡
+    case 0x00AB: return 0xAE;  // «
+    case 0x00BB: return 0xAF;  // »
+    case 0x00B0: return 0xF8;  // °
+    case 0x00B1: return 0xF1;  // ±
+    case 0x00B5: return 0xE6;  // µ
+    case 0x00DF: return 0xE1;  // ß
+
+    // Typographic (smart quotes, dashes, etc.)
+    case 0x2018: case 0x2019: return '\'';  // Smart single quotes
+    case 0x201C: case 0x201D: return '"';   // Smart double quotes
+    case 0x2013: case 0x2014: return '-';   // En/em dash
+    case 0x2010: case 0x2011: case 0x2012: case 0x2015: return '-'; // Hyphens/bars
+    case 0x2026: return 0xFD;              // Ellipsis (CP437 has no …, use ²? no, skip)
+    case 0x2022: return 0x07;              // Bullet → CP437 bullet
+    case 0x00A0: return ' ';               // Non-breaking space
+    case 0x2039: case 0x203A: return '\''; // Single guillemets
+    case 0x2032: return '\'';              // Prime
+    case 0x2033: return '"';               // Double prime
+
+    default: return 0;  // Unmappable
+  }
+}
+
+// Decode a single UTF-8 character from a byte buffer.
+// Returns the Unicode codepoint and advances *pos past the full sequence.
+// If the sequence is invalid, returns 0xFFFD (replacement char) and advances by 1.
+//
+// buf:    input buffer
+// bufLen: total buffer length
+// pos:    pointer to current position (updated on return)
+inline uint32_t decodeUtf8Char(const char* buf, int bufLen, int* pos) {
+  int i = *pos;
+  if (i >= bufLen) return 0;
+
+  uint8_t c = (uint8_t)buf[i];
+
+  // ASCII (single byte)
+  if (c < 0x80) {
+    *pos = i + 1;
+    return c;
+  }
+
+  // Continuation byte without lead byte — skip
+  if (c < 0xC0) {
+    *pos = i + 1;
+    return 0xFFFD;
+  }
+
+  uint32_t codepoint;
+  int extraBytes;
+
+  if ((c & 0xE0) == 0xC0) {
+    codepoint = c & 0x1F;
+    extraBytes = 1;
+  } else if ((c & 0xF0) == 0xE0) {
+    codepoint = c & 0x0F;
+    extraBytes = 2;
+  } else if ((c & 0xF8) == 0xF0) {
+    codepoint = c & 0x07;
+    extraBytes = 3;
+  } else {
+    *pos = i + 1;
+    return 0xFFFD;
+  }
+
+  // Verify we have enough bytes and they're valid continuation bytes
+  if (i + extraBytes >= bufLen) {
+    *pos = i + 1;
+    return 0xFFFD;
+  }
+
+  for (int b = 1; b <= extraBytes; b++) {
+    uint8_t cb = (uint8_t)buf[i + b];
+    if ((cb & 0xC0) != 0x80) {
+      *pos = i + 1;
+      return 0xFFFD;
+    }
+    codepoint = (codepoint << 6) | (cb & 0x3F);
+  }
+
+  *pos = i + 1 + extraBytes;
+  return codepoint;
+}
+
+// Check if a byte is a UTF-8 continuation byte (10xxxxxx)
+inline bool isUtf8Continuation(uint8_t c) {
+  return (c & 0xC0) == 0x80;
+}

examples/companion_radio/ui-new/emojipicker.h

@@ -1,7 +1,7 @@
 #pragma once
 
 // Emoji Picker with scrolling grid and scroll bar
-// 5 columns, 4 visible rows, scrollable through all 46 emoji
+// 5 columns, 4 visible rows, scrollable through all 65 emoji
 // WASD navigation, Enter to select, $/Q/Backspace to cancel
 
 #include <helpers/ui/DisplayDriver.h>
@@ -58,6 +58,25 @@ static const char* EMOJI_LABELS[EMOJI_COUNT] = {
   "Knob",   // 43 control_knobs
   "Pch",    // 44 peach
   "Race",   // 45 racing_car
+  "Mous",   // 46 mouse
+  "Shrm",   // 47 mushroom
+  "Bio",    // 48 biohazard
+  "Pnda",   // 49 panda
+  "Bang",   // 50 anger
+  "DrgF",   // 51 dragon_face
+  "Pagr",   // 52 pager
+  "Bee",    // 53 bee
+  "Bulb",   // 54 bulb
+  "Cat",    // 55 cat
+  "Flur",   // 56 fleur
+  "Moon",   // 57 moon
+  "Cafe",   // 58 coffee
+  "Toth",   // 59 tooth
+  "Prtz",   // 60 pretzel
+  "Abac",   // 61 abacus
+  "Moai",   // 62 moai
+  "Hiii",   // 63 tipping
+  "Hedg",   // 64 hedgehog
 };
 
 struct EmojiPicker {

examples/companion_radio/ui-new/webreaderdeps.cpp

@@ -0,0 +1,16 @@
+// WebReaderDeps.cpp
+// -----------------------------------------------------------------------
+// PlatformIO library dependency finder (LDF) hint file.
+//
+// The web reader's WiFi/HTTP includes live in WebReaderScreen.h (header-only),
+// but PlatformIO's LDF can't always trace framework library dependencies
+// through conditional #include chains in headers. This .cpp file exposes
+// the includes at the top level where the scanner reliably finds them.
+//
+// No actual code here — just #include directives for the dependency finder.
+// -----------------------------------------------------------------------
+#ifdef MECK_WEB_READER
+  #include <WiFi.h>
+  #include <HTTPClient.h>
+  #include <WiFiClientSecure.h>
+#endif

platformio.ini

@@ -27,6 +27,7 @@ build_flags = -w -DNDEBUG -DRADIOLIB_STATIC_ONLY=1 -DRADIOLIB_GODMODE=1
   -D LORA_FREQ=869.525
   -D LORA_BW=250
   -D LORA_SF=11
+  -D ENABLE_ADVERT_ON_BOOT=1
   -D ENABLE_PRIVATE_KEY_IMPORT=1   ; NOTE: comment these out for more secure firmware
   -D ENABLE_PRIVATE_KEY_EXPORT=1
   -D RADIOLIB_EXCLUDE_CC1101=1
@@ -58,6 +59,7 @@ platform = platformio/espressif32@6.11.0
 monitor_filters = esp32_exception_decoder
 extra_scripts = merge-bin.py
 build_flags = ${arduino_base.build_flags}
+  -D ESP32_PLATFORM
 ;  -D ESP32_CPU_FREQ=80          ; change it to your need
 build_src_filter = ${arduino_base.build_src_filter}
 
@@ -67,10 +69,10 @@ lib_deps =
   file://arch/esp32/AsyncElegantOTA
 
 ; esp32c6 uses arduino framework 3.x
-; WARNING: experimental. pioarduino on esp32c6 needs work - it's not considered stable and has issues.
+; WARNING: experimental. May not work as stable as other platforms.
 [esp32c6_base]
 extends = esp32_base
-platform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.12/platform-espressif32.zip
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.13-1/platform-espressif32.zip
 
 ; ----------------- NRF52 ---------------------
 
@@ -79,7 +81,7 @@ extends = arduino_base
 platform = nordicnrf52
 platform_packages =
   framework-arduinoadafruitnrf52 @ 1.10700.0
-extra_scripts = 
+extra_scripts =
   create-uf2.py
   arch/nrf52/extra_scripts/patch_bluefruit.py
 build_flags = ${arduino_base.build_flags}
@@ -147,4 +149,4 @@ lib_deps =
   adafruit/Adafruit_VL53L0X @ ^1.2.4
   stevemarple/MicroNMEA @ ^2.0.6
   adafruit/Adafruit BME680 Library @ ^2.0.4
-  adafruit/Adafruit BMP085 Library @ ^1.2.4
+  adafruit/Adafruit BMP085 Library @ ^1.2.4

src/helpers/BaseChatMesh.h

@@ -58,9 +58,9 @@ class BaseChatMesh : public mesh::Mesh {
 
   friend class ContactsIterator;
 
-  ContactInfo contacts[MAX_CONTACTS];
+  ContactInfo* contacts;
   int num_contacts;
-  int sort_array[MAX_CONTACTS];
+  int* sort_array;
   int matching_peer_indexes[MAX_SEARCH_RESULTS];
   unsigned long txt_send_timeout;
 #ifdef MAX_GROUP_CHANNELS
@@ -78,6 +78,8 @@ protected:
   BaseChatMesh(mesh::Radio& radio, mesh::MillisecondClock& ms, mesh::RNG& rng, mesh::RTCClock& rtc, mesh::PacketManager& mgr, mesh::MeshTables& tables)
       : mesh::Mesh(radio, ms, rng, rtc, mgr, tables)
   { 
+    contacts = NULL;
+    sort_array = NULL;
     num_contacts = 0;
   #ifdef MAX_GROUP_CHANNELS
     memset(channels, 0, sizeof(channels));
@@ -90,6 +92,19 @@ protected:
 
   void bootstrapRTCfromContacts();
   void resetContacts() { num_contacts = 0; }
+
+  // Must be called from begin() before loadContacts/bootstrapRTCfromContacts.
+  // Deferred from constructor because PSRAM is not available during global init.
+  void initContacts() {
+    if (contacts != NULL) return;  // already initialized
+  #if defined(ESP32) && defined(BOARD_HAS_PSRAM)
+    contacts = (ContactInfo*)ps_calloc(MAX_CONTACTS, sizeof(ContactInfo));
+    sort_array = (int*)ps_calloc(MAX_CONTACTS, sizeof(int));
+  #else
+    contacts = new ContactInfo[MAX_CONTACTS]();
+    sort_array = new int[MAX_CONTACTS]();
+  #endif
+  }
   void populateContactFromAdvert(ContactInfo& ci, const mesh::Identity& id, const AdvertDataParser& parser, uint32_t timestamp);
   ContactInfo* allocateContactSlot(); // helper to find slot for new contact
 
@@ -169,4 +184,4 @@ public:
   int findChannelIdx(const mesh::GroupChannel& ch);
 
   void loop();
-};
+};

src/helpers/esp32/SerialBLEInterface.cpp

@@ -147,15 +147,21 @@ void SerialBLEInterface::enable() {
 }
 
 void SerialBLEInterface::disable() {
+  bool wasEnabled = _isEnabled;
   _isEnabled = false;
 
   BLE_DEBUG_PRINTLN("SerialBLEInterface::disable");
 
-  pServer->getAdvertising()->stop();
-  pServer->disconnect(last_conn_id);
-  pService->stop();
+  // Only try BLE operations if we were previously enabled
+  // (avoids accessing dead BLE objects after btStop/mem_release)
+  if (wasEnabled && pServer) {
+    pServer->getAdvertising()->stop();
+    pServer->disconnect(last_conn_id);
+    pService->stop();
+  }
   oldDeviceConnected = deviceConnected = false;
   adv_restart_time = 0;
+  clearBuffers();
 }
 
 size_t SerialBLEInterface::writeFrame(const uint8_t src[], size_t len) {
@@ -186,6 +192,8 @@ bool SerialBLEInterface::isWriteBusy() const {
 }
 
 size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
+  if (!_isEnabled) return 0;  // BLE disabled — skip all BLE operations
+
   if (send_queue_len > 0   // first, check send queue
     && millis() >= _last_write + BLE_WRITE_MIN_INTERVAL    // space the writes apart
   ) {
@@ -249,4 +257,4 @@ size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
 
 bool SerialBLEInterface::isConnected() const {
   return deviceConnected;  //pServer != NULL && pServer->getConnectedCount() > 0;
-}
+}

src/helpers/esp32/SerialBLEInterface.h

@@ -88,4 +88,4 @@ public:
 #else
   #define BLE_DEBUG_PRINT(...) {}
   #define BLE_DEBUG_PRINTLN(...) {}
-#endif
+#endif

src/helpers/ui/GxEPDDisplay.h

@@ -12,7 +12,31 @@
 #include <Fonts/FreeSans9pt7b.h>
 #include <Fonts/FreeSansBold12pt7b.h>
 #include <Fonts/FreeSans18pt7b.h>
-#include <CRC32.h>
+
+// Inline CRC32 for frame change detection (replaces bakercp/CRC32
+// to avoid naming collision with PNGdec's bundled CRC32.h)
+class FrameCRC32 {
+  uint32_t _crc = 0xFFFFFFFF;
+public:
+  void reset() { _crc = 0xFFFFFFFF; }
+  template<typename T> void update(T val) {
+    const uint8_t* p = (const uint8_t*)&val;
+    for (size_t i = 0; i < sizeof(T); i++) {
+      _crc ^= p[i];
+      for (int b = 0; b < 8; b++)
+        _crc = (_crc >> 1) ^ (0xEDB88320 & -(int32_t)(_crc & 1));
+    }
+  }
+  template<typename T> void update(const T* data, size_t len) {
+    const uint8_t* p = (const uint8_t*)data;
+    for (size_t i = 0; i < len * sizeof(T); i++) {
+      _crc ^= p[i];
+      for (int b = 0; b < 8; b++)
+        _crc = (_crc >> 1) ^ (0xEDB88320 & -(int32_t)(_crc & 1));
+    }
+  }
+  uint32_t finalize() { return _crc ^ 0xFFFFFFFF; }
+};
 
 #include "DisplayDriver.h"
 
@@ -34,7 +58,7 @@ class GxEPDDisplay : public DisplayDriver {
   bool _init = false;
   bool _isOn = false;
   uint16_t _curr_color;
-  CRC32 display_crc;
+  FrameCRC32 display_crc;
   int last_display_crc_value = 0;
 
 public:
@@ -60,4 +84,24 @@ public:
   void drawXbm(int x, int y, const uint8_t* bits, int w, int h) override;
   uint16_t getTextWidth(const char* str) override;
   void endFrame() override;
-};
+
+  // --- Raw pixel access for MapScreen (bypasses scaling) ---
+  void drawPixelRaw(int16_t x, int16_t y, uint16_t color) {
+    display.drawPixel(x, y, color);
+  }
+  int16_t rawWidth()  { return display.width(); }
+  int16_t rawHeight() { return display.height(); }
+
+  // Draw text at raw (unscaled) physical coordinates using built-in 5x7 font
+  void drawTextRaw(int16_t x, int16_t y, const char* text, uint16_t color) {
+    display.setFont(NULL);          // Built-in 5x7 font
+    display.setTextSize(1);
+    display.setTextColor(color);
+    display.setCursor(x, y);
+    display.print(text);
+  }
+
+  // Force endFrame() to push to display even if CRC unchanged
+  // (needed because drawPixelRaw bypasses CRC tracking)
+  void invalidateFrameCRC() { last_display_crc_value = 0; }
+};

variants/lilygo_tdeck_pro/CPUPowerManager.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <Arduino.h>
+
+// CPU Frequency Scaling for ESP32-S3
+//
+// Typical current draw (CPU only, rough):
+//   240 MHz  ~70-80 mA
+//   160 MHz  ~50-60 mA
+//    80 MHz  ~30-40 mA
+//
+// SPI peripherals and UART use their own clock dividers from the APB clock,
+// so LoRa, e-ink, and GPS serial all work fine at 80MHz.
+
+#ifdef ESP32
+
+#ifndef CPU_FREQ_IDLE
+#define CPU_FREQ_IDLE   80     // MHz — normal mesh listening
+#endif
+
+#ifndef CPU_FREQ_BOOST
+#define CPU_FREQ_BOOST  240    // MHz — heavy processing
+#endif
+
+#ifndef CPU_BOOST_TIMEOUT_MS
+#define CPU_BOOST_TIMEOUT_MS  10000  // 10 seconds
+#endif
+
+class CPUPowerManager {
+public:
+  CPUPowerManager() : _boosted(false), _boost_started(0) {}
+
+  void begin() {
+    setCpuFrequencyMhz(CPU_FREQ_IDLE);
+    _boosted = false;
+    MESH_DEBUG_PRINTLN("CPU power: idle at %d MHz", CPU_FREQ_IDLE);
+  }
+
+  void loop() {
+    if (_boosted && (millis() - _boost_started >= CPU_BOOST_TIMEOUT_MS)) {
+      setIdle();
+    }
+  }
+
+  void setBoost() {
+    if (!_boosted) {
+      setCpuFrequencyMhz(CPU_FREQ_BOOST);
+      _boosted = true;
+      MESH_DEBUG_PRINTLN("CPU power: boosted to %d MHz", CPU_FREQ_BOOST);
+    }
+    _boost_started = millis();
+  }
+
+  void setIdle() {
+    if (_boosted) {
+      setCpuFrequencyMhz(CPU_FREQ_IDLE);
+      _boosted = false;
+      MESH_DEBUG_PRINTLN("CPU power: idle at %d MHz", CPU_FREQ_IDLE);
+    }
+  }
+
+  bool isBoosted() const { return _boosted; }
+  uint32_t getFrequencyMHz() const { return getCpuFrequencyMhz(); }
+
+private:
+  bool _boosted;
+  unsigned long _boost_started;
+};
+
+#endif // ESP32

variants/lilygo_tdeck_pro/GPSStreamCounter.h

@@ -0,0 +1,72 @@
+#pragma once
+
+#include <Arduino.h>
+
+// Transparent Stream wrapper that counts NMEA sentences (newline-delimited)
+// flowing from the GPS serial port to the MicroNMEA parser.
+//
+// Usage:  Instead of  MicroNMEALocationProvider gps(Serial2, &rtc_clock);
+//         Use:        GPSStreamCounter gpsStream(Serial2);
+//                     MicroNMEALocationProvider gps(gpsStream, &rtc_clock);
+//
+// Every read() call passes through to the underlying stream; when a '\n'
+// is seen the sentence counter increments.  This lets the UI display a
+// live "nmea" count so users can confirm the baud rate is correct and
+// the GPS module is actually sending data.
+
+class GPSStreamCounter : public Stream {
+public:
+  GPSStreamCounter(Stream& inner)
+    : _inner(inner), _sentences(0), _sentences_snapshot(0),
+      _last_snapshot(0), _sentences_per_sec(0) {}
+
+  // --- Stream read interface (passes through) ---
+  int available() override { return _inner.available(); }
+  int peek()      override { return _inner.peek(); }
+
+  int read() override {
+    int c = _inner.read();
+    if (c == '\n') {
+      _sentences++;
+    }
+    return c;
+  }
+
+  // --- Stream write interface (pass through for NMEA commands if needed) ---
+  size_t write(uint8_t b) override { return _inner.write(b); }
+
+  // --- Sentence counting API ---
+
+  // Total sentences received since boot (or last reset)
+  uint32_t getSentenceCount() const { return _sentences; }
+
+  // Sentences received per second (updated each time you call it,
+  // with a 1-second rolling window)
+  uint16_t getSentencesPerSec() {
+    unsigned long now = millis();
+    unsigned long elapsed = now - _last_snapshot;
+    if (elapsed >= 1000) {
+      uint32_t delta = _sentences - _sentences_snapshot;
+      // Scale to per-second if interval wasn't exactly 1000ms
+      _sentences_per_sec = (uint16_t)((delta * 1000UL) / elapsed);
+      _sentences_snapshot = _sentences;
+      _last_snapshot = now;
+    }
+    return _sentences_per_sec;
+  }
+
+  // Reset all counters (e.g. when GPS hardware power cycles)
+  void resetCounters() {
+    _sentences = 0;
+    _sentences_snapshot = 0;
+    _sentences_per_sec = 0;
+    _last_snapshot = millis();
+  }
+
+private:
+  Stream& _inner;
+  volatile uint32_t _sentences;
+  uint32_t _sentences_snapshot;
+  unsigned long _last_snapshot;
+  uint16_t _sentences_per_sec;
+};

variants/lilygo_tdeck_pro/TDeckBoard.cpp

@@ -72,10 +72,30 @@ void TDeckBoard::begin() {
     rtc_gpio_deinit((gpio_num_t)P_LORA_DIO_1);
   }
   
-  // Test BQ27220 communication
+  // Test BQ27220 communication and configure design capacity
   #if HAS_BQ27220
     uint16_t voltage = getBattMilliVolts();
     MESH_DEBUG_PRINTLN("TDeckBoard::begin() - Battery voltage: %d mV", voltage);
+    configureFuelGauge();
+  #endif
+
+  // --- Early low-voltage protection ---
+  // If we boot below the shutdown threshold, go straight to deep sleep
+  // WITHOUT touching the filesystem. This breaks the brown-out reboot
+  // loop that corrupts contacts when battery is deeply depleted (~2.5V).
+  #if HAS_BQ27220 && defined(AUTO_SHUTDOWN_MILLIVOLTS)
+  {
+    uint16_t bootMv = getBattMilliVolts();
+    if (bootMv > 0 && bootMv < AUTO_SHUTDOWN_MILLIVOLTS) {
+      Serial.printf("CRITICAL: Boot voltage %dmV < %dmV — sleeping immediately\n",
+                    bootMv, AUTO_SHUTDOWN_MILLIVOLTS);
+      // Don't mount SD, don't load contacts, don't pass Go.
+      // Only wake on user button press (presumably after plugging in charger).
+      esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_ALL);
+      esp_sleep_enable_ext1_wakeup(1ULL << PIN_USER_BTN, ESP_EXT1_WAKEUP_ANY_HIGH);
+      esp_deep_sleep_start();  // CPU halts here
+    }
+  }
   #endif
   
   MESH_DEBUG_PRINTLN("TDeckBoard::begin() - complete");
@@ -123,4 +143,450 @@ uint8_t TDeckBoard::getBatteryPercent() {
   #else
     return 0;
   #endif
+}
+
+// ---- BQ27220 extended register helpers ----
+
+#if HAS_BQ27220
+// Read a 16-bit register from BQ27220. Returns 0 on I2C error.
+static uint16_t bq27220_read16(uint8_t reg) {
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(reg);
+  if (Wire.endTransmission(false) != 0) return 0;
+  if (Wire.requestFrom((uint8_t)BQ27220_I2C_ADDR, (uint8_t)2) != 2) return 0;
+  uint16_t val = Wire.read();
+  val |= (Wire.read() << 8);
+  return val;
+}
+
+// Read a single byte from BQ27220 register.
+static uint8_t bq27220_read8(uint8_t reg) {
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(reg);
+  if (Wire.endTransmission(false) != 0) return 0;
+  if (Wire.requestFrom((uint8_t)BQ27220_I2C_ADDR, (uint8_t)1) != 1) return 0;
+  return Wire.read();
+}
+
+// Write a 16-bit subcommand to BQ27220 Control register (0x00).
+// Subcommands control unsealing, config mode, sealing, etc.
+static bool bq27220_writeControl(uint16_t subcmd) {
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x00);                    // Control register
+  Wire.write(subcmd & 0xFF);           // LSB first
+  Wire.write((subcmd >> 8) & 0xFF);    // MSB
+  return Wire.endTransmission() == 0;
+}
+#endif
+
+// ---- BQ27220 Design Capacity configuration ----
+// The BQ27220 ships with a 3000 mAh default. The T-Deck Pro uses a 2000 mAh
+// cell. This function checks on boot and writes the correct value via the
+// MAC Data Memory interface if needed. The value persists in battery-backed
+// RAM, so this typically only writes once (or after a full battery disconnect).
+//
+// Procedure follows TI TRM SLUUBD4A Section 6.1:
+//   1. Unseal  →  2. Full Access  →  3. Enter CFG_UPDATE
+//   4. Write Design Capacity via MAC  →  5. Exit CFG_UPDATE  →  6. Seal
+
+bool TDeckBoard::configureFuelGauge(uint16_t designCapacity_mAh) {
+#if HAS_BQ27220
+  // Read current design capacity from standard command register
+  uint16_t currentDC = bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  Serial.printf("BQ27220: Design Capacity = %d mAh (target %d)\n", currentDC, designCapacity_mAh);
+
+  if (currentDC == designCapacity_mAh) {
+    // Design Capacity correct, but check if Full Charge Capacity is sane.
+    uint16_t fcc = bq27220_read16(BQ27220_REG_FULL_CAP);
+    Serial.printf("BQ27220: Design Capacity already correct, FCC=%d mAh\n", fcc);
+    if (fcc >= designCapacity_mAh * 3 / 2) {
+      // FCC is >=150% of design — stale from factory defaults (typically 3000 mAh).
+      uint16_t designEnergy = (uint16_t)((uint32_t)designCapacity_mAh * 37 / 10);
+      Serial.printf("BQ27220: FCC %d >> DC %d, checking Design Energy (target %d mWh)\n",
+                    fcc, designCapacity_mAh, designEnergy);
+
+      // Unseal to read data memory and issue RESET
+      bq27220_writeControl(0x0414); delay(2);
+      bq27220_writeControl(0x3672); delay(2);
+      // Full Access
+      bq27220_writeControl(0xFFFF); delay(2);
+      bq27220_writeControl(0xFFFF); delay(2);
+
+      // Read current Design Energy from data memory to check if it needs writing
+      // Enter CFG_UPDATE to access data memory
+      bq27220_writeControl(0x0090);
+      bool ready = false;
+      for (int i = 0; i < 50; i++) {
+        delay(20);
+        uint16_t opSt = bq27220_read16(BQ27220_REG_OP_STATUS);
+        if (opSt & 0x0400) { ready = true; break; }
+      }
+      if (ready) {
+        // Read Design Energy at data memory address 0x92A1
+        Wire.beginTransmission(BQ27220_I2C_ADDR);
+        Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+        Wire.endTransmission();
+        delay(10);
+        uint8_t oldMSB = bq27220_read8(0x40);
+        uint8_t oldLSB = bq27220_read8(0x41);
+        uint16_t currentDE = (oldMSB << 8) | oldLSB;
+
+        if (currentDE != designEnergy) {
+          // Design Energy actually needs updating — write it
+          uint8_t oldChk = bq27220_read8(0x60);
+          uint8_t dLen   = bq27220_read8(0x61);
+          uint8_t newMSB = (designEnergy >> 8) & 0xFF;
+          uint8_t newLSB = designEnergy & 0xFF;
+          uint8_t temp = (255 - oldChk - oldMSB - oldLSB);
+          uint8_t newChk = 255 - ((temp + newMSB + newLSB) & 0xFF);
+
+          Serial.printf("BQ27220: DE old=%d new=%d mWh, writing\n", currentDE, designEnergy);
+
+          Wire.beginTransmission(BQ27220_I2C_ADDR);
+          Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+          Wire.write(newMSB); Wire.write(newLSB);
+          Wire.endTransmission();
+          delay(5);
+          Wire.beginTransmission(BQ27220_I2C_ADDR);
+          Wire.write(0x60); Wire.write(newChk); Wire.write(dLen);
+          Wire.endTransmission();
+          delay(10);
+
+          // Exit with reinit since we actually changed data
+          bq27220_writeControl(0x0091);  // EXIT_CFG_UPDATE_REINIT
+          delay(200);
+          Serial.println("BQ27220: Design Energy written, exited CFG_UPDATE");
+        } else {
+          // DC=2000, DE=7400, Update Status=0x00, but FCC is stuck at 3000.
+          // Diagnostic scan found the culprits:
+          //   0x9106 = Qmax Cell 0 (IT Cfg class) — the raw capacity the
+          //            gauge uses for FCC calculation. Factory default 3000.
+          //   0x929D = Stored FCC reference (Gas Gauging class, 2 bytes
+          //            before Design Capacity). Also stuck at 3000.
+          //
+          // Fix: overwrite both with designCapacity_mAh (2000).
+          Serial.printf("BQ27220: DE correct (%d mWh) — fixing Qmax + stored FCC\n", currentDE);
+
+          // --- Helper lambda for MAC data memory 2-byte write ---
+          // Reads old value + checksum, computes differential checksum, writes new value.
+          auto writeDM16 = [](uint16_t addr, uint16_t newVal) -> bool {
+            // Select address
+            Wire.beginTransmission(BQ27220_I2C_ADDR);
+            Wire.write(0x3E);
+            Wire.write(addr & 0xFF);
+            Wire.write((addr >> 8) & 0xFF);
+            Wire.endTransmission();
+            delay(10);
+
+            uint8_t oldMSB = bq27220_read8(0x40);
+            uint8_t oldLSB = bq27220_read8(0x41);
+            uint8_t oldChk = bq27220_read8(0x60);
+            uint8_t dLen   = bq27220_read8(0x61);
+            uint16_t oldVal = (oldMSB << 8) | oldLSB;
+
+            if (oldVal == newVal) {
+              Serial.printf("BQ27220:   [0x%04X] already %d, skip\n", addr, newVal);
+              return true;  // already correct
+            }
+
+            uint8_t newMSB = (newVal >> 8) & 0xFF;
+            uint8_t newLSB = newVal & 0xFF;
+            uint8_t temp = (255 - oldChk - oldMSB - oldLSB);
+            uint8_t newChk = 255 - ((temp + newMSB + newLSB) & 0xFF);
+
+            Serial.printf("BQ27220:   [0x%04X] %d -> %d\n", addr, oldVal, newVal);
+
+            // Write new value
+            Wire.beginTransmission(BQ27220_I2C_ADDR);
+            Wire.write(0x3E);
+            Wire.write(addr & 0xFF);
+            Wire.write((addr >> 8) & 0xFF);
+            Wire.write(newMSB);
+            Wire.write(newLSB);
+            Wire.endTransmission();
+            delay(5);
+
+            // Write checksum
+            Wire.beginTransmission(BQ27220_I2C_ADDR);
+            Wire.write(0x60);
+            Wire.write(newChk);
+            Wire.write(dLen);
+            Wire.endTransmission();
+            delay(10);
+            return true;
+          };
+
+          // Overwrite Qmax Cell 0 (IT Cfg) — this is what FCC is derived from
+          writeDM16(0x9106, designCapacity_mAh);
+
+          // Overwrite stored FCC reference (Gas Gauging, 2 bytes before DC)
+          writeDM16(0x929D, designCapacity_mAh);
+
+          // Exit with reinit to apply the new values
+          bq27220_writeControl(0x0091);  // EXIT_CFG_UPDATE_REINIT
+          delay(200);
+          Serial.println("BQ27220: Qmax + stored FCC updated, exited CFG_UPDATE");
+        }
+      } else {
+        Serial.println("BQ27220: Failed to enter CFG_UPDATE for DE check");
+      }
+
+      // Seal first, then issue RESET.
+      // RESET forces the gauge to fully reinitialize its Impedance Track
+      // algorithm and recalculate FCC from the current DC/DE values.
+      // This is the actual fix when DC and DE are correct but FCC is stuck.
+      bq27220_writeControl(0x0030);  // SEAL
+      delay(5);
+      Serial.println("BQ27220: Issuing RESET to force FCC recalculation...");
+      bq27220_writeControl(0x0041);  // RESET
+      delay(2000);  // Full reset needs generous settle time
+
+      fcc = bq27220_read16(BQ27220_REG_FULL_CAP);
+      Serial.printf("BQ27220: FCC after RESET: %d mAh (target <= %d)\n", fcc, designCapacity_mAh);
+
+      if (fcc > designCapacity_mAh * 3 / 2) {
+        // RESET didn't fix FCC — the gauge IT algorithm is stubbornly
+        // retaining its learned value. This typically resolves after one
+        // full charge/discharge cycle. Software clamp in
+        // getFullChargeCapacity() ensures correct display regardless.
+        Serial.printf("BQ27220: FCC still stale at %d — software clamp active\n", fcc);
+      }
+    }
+    return true;
+  }
+
+  Serial.printf("BQ27220: Updating Design Capacity from %d to %d mAh\n", currentDC, designCapacity_mAh);
+
+  // Step 1: Unseal (default unseal keys)
+  bq27220_writeControl(0x0414);
+  delay(2);
+  bq27220_writeControl(0x3672);
+  delay(2);
+
+  // Step 2: Enter Full Access mode
+  bq27220_writeControl(0xFFFF);
+  delay(2);
+  bq27220_writeControl(0xFFFF);
+  delay(2);
+
+  // Step 3: Enter CFG_UPDATE mode
+  bq27220_writeControl(0x0090);
+
+  // Wait for CFGUPMODE bit (bit 10) in OperationStatus register
+  bool cfgReady = false;
+  for (int i = 0; i < 50; i++) {
+    delay(20);
+    uint16_t opStatus = bq27220_read16(BQ27220_REG_OP_STATUS);
+    Serial.printf("BQ27220: OperationStatus = 0x%04X (attempt %d)\n", opStatus, i);
+    if (opStatus & 0x0400) {  // CFGUPMODE is bit 10
+      cfgReady = true;
+      break;
+    }
+  }
+  if (!cfgReady) {
+    Serial.println("BQ27220: ERROR - Timeout waiting for CFGUPDATE mode");
+    bq27220_writeControl(0x0092);  // Try to exit cleanly
+    bq27220_writeControl(0x0030);  // Re-seal
+    return false;
+  }
+  Serial.println("BQ27220: Entered CFGUPDATE mode");
+
+  // Step 4: Write Design Capacity via MAC Data Memory interface
+  // Design Capacity mAh lives at data memory address 0x929F
+
+  // 4a. Select the data memory block by writing address to 0x3E-0x3F
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x3E);   // MACDataControl register
+  Wire.write(0x9F);   // Address low byte
+  Wire.write(0x92);   // Address high byte
+  Wire.endTransmission();
+  delay(10);
+
+  // 4b. Read old data (MSB, LSB) and checksum for differential update
+  uint8_t oldMSB     = bq27220_read8(0x40);
+  uint8_t oldLSB     = bq27220_read8(0x41);
+  uint8_t oldChksum  = bq27220_read8(0x60);
+  uint8_t dataLen    = bq27220_read8(0x61);
+
+  Serial.printf("BQ27220: Old DC bytes=0x%02X 0x%02X chk=0x%02X len=%d\n",
+                     oldMSB, oldLSB, oldChksum, dataLen);
+
+  // 4c. Compute new values (BQ27220 stores big-endian in data memory)
+  uint8_t newMSB = (designCapacity_mAh >> 8) & 0xFF;
+  uint8_t newLSB = designCapacity_mAh & 0xFF;
+
+  // Differential checksum: remove old bytes, add new bytes
+  uint8_t temp = (255 - oldChksum - oldMSB - oldLSB);
+  uint8_t newChksum = 255 - ((temp + newMSB + newLSB) & 0xFF);
+
+  Serial.printf("BQ27220: New DC bytes=0x%02X 0x%02X chk=0x%02X\n",
+                     newMSB, newLSB, newChksum);
+
+  // 4d. Write address + new data as a single block transaction
+  //     BQ27220 MAC requires: [0x3E] [addr_lo] [addr_hi] [data...]
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x3E);    // Start at MACDataControl
+  Wire.write(0x9F);    // Address low byte
+  Wire.write(0x92);    // Address high byte
+  Wire.write(newMSB);  // Data byte 0 (at 0x40)
+  Wire.write(newLSB);  // Data byte 1 (at 0x41)
+  uint8_t writeResult = Wire.endTransmission();
+  Serial.printf("BQ27220: Write block result = %d\n", writeResult);
+
+  // 4e. Write updated checksum and length
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x60);
+  Wire.write(newChksum);
+  Wire.write(dataLen);
+  writeResult = Wire.endTransmission();
+  Serial.printf("BQ27220: Write checksum result = %d\n", writeResult);
+  delay(10);
+
+  // 4f. Verify the write took effect before exiting config mode
+  //     Re-read the block to confirm
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x3E);
+  Wire.write(0x9F);
+  Wire.write(0x92);
+  Wire.endTransmission();
+  delay(10);
+  uint8_t verMSB = bq27220_read8(0x40);
+  uint8_t verLSB = bq27220_read8(0x41);
+  Serial.printf("BQ27220: Verify in CFGUPDATE: DC bytes=0x%02X 0x%02X (%d mAh)\n",
+                     verMSB, verLSB, (verMSB << 8) | verLSB);
+
+  // Step 4g: Also update Design Energy (address 0x92A1) while in CFG_UPDATE.
+  // Design Energy = capacity × 3.7V (nominal LiPo voltage).
+  // The gauge uses both DC and DE to compute Full Charge Capacity.
+  {
+    uint16_t designEnergy = (uint16_t)((uint32_t)designCapacity_mAh * 37 / 10);
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+    Wire.endTransmission();
+    delay(10);
+    uint8_t deOldMSB = bq27220_read8(0x40);
+    uint8_t deOldLSB = bq27220_read8(0x41);
+    uint8_t deOldChk = bq27220_read8(0x60);
+    uint8_t deLen    = bq27220_read8(0x61);
+
+    uint8_t deNewMSB = (designEnergy >> 8) & 0xFF;
+    uint8_t deNewLSB = designEnergy & 0xFF;
+    uint8_t deTemp = (255 - deOldChk - deOldMSB - deOldLSB);
+    uint8_t deNewChk = 255 - ((deTemp + deNewMSB + deNewLSB) & 0xFF);
+
+    Serial.printf("BQ27220: Design Energy: old=%d new=%d mWh\n",
+                  (deOldMSB << 8) | deOldLSB, designEnergy);
+
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+    Wire.write(deNewMSB); Wire.write(deNewLSB);
+    Wire.endTransmission();
+    delay(5);
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(0x60); Wire.write(deNewChk); Wire.write(deLen);
+    Wire.endTransmission();
+    delay(10);
+  }
+
+  // Step 5: Exit CFG_UPDATE (with reinit to apply changes immediately)
+  bq27220_writeControl(0x0091);  // EXIT_CFG_UPDATE_REINIT
+  Serial.println("BQ27220: Sent EXIT_CFG_UPDATE_REINIT, waiting...");
+  delay(200);  // Allow gauge to reinitialize
+
+  // Verify
+  uint16_t verifyDC = bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  Serial.printf("BQ27220: Design Capacity now reads %d mAh (expected %d)\n",
+                     verifyDC, designCapacity_mAh);
+
+  uint16_t newFCC = bq27220_read16(BQ27220_REG_FULL_CAP);
+  Serial.printf("BQ27220: Full Charge Capacity: %d mAh\n", newFCC);
+
+  if (verifyDC == designCapacity_mAh) {
+    Serial.println("BQ27220: Configuration SUCCESS");
+  } else {
+    Serial.println("BQ27220: Configuration FAILED");
+  }
+
+  // Step 6: Seal the device
+  bq27220_writeControl(0x0030);
+  delay(5);
+
+  // Step 7: Force full gauge RESET to reinitialize FCC from new DC/DE.
+  // Without this, the Impedance Track algorithm retains the old FCC
+  // (often 3000 mAh from factory) until a full charge/discharge cycle.
+  bq27220_writeControl(0x0041);  // RESET
+  delay(1000);  // Gauge needs time to fully reinitialize
+
+  // Re-verify after hard reset
+  verifyDC = bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  newFCC = bq27220_read16(BQ27220_REG_FULL_CAP);
+  Serial.printf("BQ27220: Post-RESET DC=%d FCC=%d mAh\n", verifyDC, newFCC);
+
+  return verifyDC == designCapacity_mAh;
+#else
+  return false;
+#endif
+}
+
+int16_t TDeckBoard::getAvgCurrent() {
+  #if HAS_BQ27220
+    return (int16_t)bq27220_read16(BQ27220_REG_AVG_CURRENT);
+  #else
+    return 0;
+  #endif
+}
+
+int16_t TDeckBoard::getAvgPower() {
+  #if HAS_BQ27220
+    return (int16_t)bq27220_read16(BQ27220_REG_AVG_POWER);
+  #else
+    return 0;
+  #endif
+}
+
+uint16_t TDeckBoard::getTimeToEmpty() {
+  #if HAS_BQ27220
+    return bq27220_read16(BQ27220_REG_TIME_TO_EMPTY);
+  #else
+    return 0xFFFF;
+  #endif
+}
+
+uint16_t TDeckBoard::getRemainingCapacity() {
+  #if HAS_BQ27220
+    return bq27220_read16(BQ27220_REG_REMAIN_CAP);
+  #else
+    return 0;
+  #endif
+}
+
+uint16_t TDeckBoard::getFullChargeCapacity() {
+  #if HAS_BQ27220
+    uint16_t fcc = bq27220_read16(BQ27220_REG_FULL_CAP);
+    // Clamp to design capacity — the gauge may report a stale factory FCC
+    // (e.g. 3000 mAh) until it completes a full learning cycle. Never let
+    // the reported FCC exceed what the actual cell can hold.
+    if (fcc > BQ27220_DESIGN_CAPACITY_MAH) fcc = BQ27220_DESIGN_CAPACITY_MAH;
+    return fcc;
+  #else
+    return 0;
+  #endif
+}
+
+uint16_t TDeckBoard::getDesignCapacity() {
+  #if HAS_BQ27220
+    return bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  #else
+    return 0;
+  #endif
+}
+
+int16_t TDeckBoard::getBattTemperature() {
+  #if HAS_BQ27220
+    uint16_t raw = bq27220_read16(BQ27220_REG_TEMPERATURE);
+    // BQ27220 returns 0.1°K, convert to 0.1°C (273.1K = 0°C)
+    return (int16_t)(raw - 2731);
+  #else
+    return 0;
+  #endif
 }

variants/lilygo_tdeck_pro/TDeckBoard.h

@@ -7,11 +7,24 @@
 #include <driver/rtc_io.h>
 
 // BQ27220 Fuel Gauge Registers
-#define BQ27220_REG_VOLTAGE 0x08
-#define BQ27220_REG_CURRENT 0x0C
-#define BQ27220_REG_SOC 0x2C
+#define BQ27220_REG_TEMPERATURE    0x06  // Temperature (0.1°K)
+#define BQ27220_REG_VOLTAGE        0x08
+#define BQ27220_REG_CURRENT        0x0C  // Instantaneous current (mA, signed)
+#define BQ27220_REG_SOC            0x2C
+#define BQ27220_REG_REMAIN_CAP     0x10  // Remaining capacity (mAh)
+#define BQ27220_REG_FULL_CAP       0x12  // Full charge capacity (mAh)
+#define BQ27220_REG_AVG_CURRENT    0x14  // Average current (mA, signed)
+#define BQ27220_REG_TIME_TO_EMPTY  0x16  // Minutes until empty
+#define BQ27220_REG_AVG_POWER      0x24  // Average power (mW, signed)
+#define BQ27220_REG_DESIGN_CAP     0x3C  // Design capacity (mAh, read-only standard cmd)
+#define BQ27220_REG_OP_STATUS      0x3A  // Operation status
 #define BQ27220_I2C_ADDR 0x55
 
+// T-Deck Pro battery capacity (all variants use 1400 mAh cell)
+#ifndef BQ27220_DESIGN_CAPACITY_MAH
+#define BQ27220_DESIGN_CAPACITY_MAH  1400
+#endif
+
 class TDeckBoard : public ESP32Board {
 public:
   void begin();
@@ -52,6 +65,30 @@ public:
   // Read state of charge percentage from BQ27220
   uint8_t getBatteryPercent();
 
+  // Read average current in mA (negative = discharging, positive = charging)
+  int16_t getAvgCurrent();
+
+  // Read average power in mW (negative = discharging, positive = charging)
+  int16_t getAvgPower();
+
+  // Read time-to-empty in minutes (0xFFFF if charging/unavailable)
+  uint16_t getTimeToEmpty();
+
+  // Read remaining capacity in mAh
+  uint16_t getRemainingCapacity();
+
+  // Read full charge capacity in mAh (learned value, may need cycling to update)
+  uint16_t getFullChargeCapacity();
+
+  // Read design capacity in mAh (the configured battery size)
+  uint16_t getDesignCapacity();
+
+  // Read battery temperature in 0.1°C units (e.g., 256 = 25.6°C)
+  int16_t getBattTemperature();
+
+  // Configure BQ27220 design capacity (checks on boot, writes only if wrong)
+  bool configureFuelGauge(uint16_t designCapacity_mAh = BQ27220_DESIGN_CAPACITY_MAH);
+
   const char* getManufacturerName() const {
     return "LilyGo T-Deck Pro";
   }

variants/lilygo_tdeck_pro/Tca8418keyboard.h

@@ -28,7 +28,10 @@ private:
   uint8_t _addr;
   TwoWire* _wire;
   bool _initialized;
-  bool _shiftActive;   // Sticky shift (one-shot)
+  bool _shiftActive;   // Sticky shift (one-shot or held)
+  bool _shiftConsumed; // Was shift active for the last returned key
+  bool _shiftHeld;     // Shift key physically held down
+  bool _shiftUsedWhileHeld; // Was shift consumed by any key while held
   bool _altActive;     // Sticky alt (one-shot)
   bool _symActive;     // Sticky sym (one-shot)
   unsigned long _lastShiftTime;  // For Shift+key combos
@@ -148,7 +151,7 @@ private:
 public:
   TCA8418Keyboard(uint8_t addr = 0x34, TwoWire* wire = &Wire) 
     : _addr(addr), _wire(wire), _initialized(false), 
-      _shiftActive(false), _altActive(false), _symActive(false), _lastShiftTime(0) {}
+      _shiftActive(false), _shiftConsumed(false), _shiftHeld(false), _shiftUsedWhileHeld(false), _altActive(false), _symActive(false), _lastShiftTime(0) {}
 
   bool begin() {
     // Check if device responds
@@ -203,6 +206,19 @@ public:
     Serial.printf("KB raw: event=0x%02X code=%d pressed=%d count=%d\n", 
                   keyEvent, keyCode, pressed, keyCount);
 
+    // Track shift release (before the general release-ignore)
+    if (!pressed && (keyCode == 35 || keyCode == 31)) {
+      _shiftHeld = false;
+      // If shift was used while held (e.g. cursor nav), clear it completely
+      // so the next bare keypress isn't treated as shifted.
+      // If shift was NOT used (tap-then-release), keep _shiftActive for one-shot.
+      if (_shiftUsedWhileHeld) {
+        _shiftActive = false;
+      }
+      _shiftUsedWhileHeld = false;
+      return 0;
+    }
+
     // Only act on key press, not release
     if (!pressed || keyCode == 0) {
       return 0;
@@ -211,6 +227,8 @@ public:
     // Handle modifier keys - set sticky state and return 0
     if (keyCode == 35 || keyCode == 31) {  // Shift keys
       _shiftActive = true;
+      _shiftHeld = true;
+      _shiftUsedWhileHeld = false;
       _lastShiftTime = millis();
       Serial.println("KB: Shift activated");
       return 0;
@@ -238,14 +256,12 @@ public:
       return KB_KEY_EMOJI;
     }
     
-    // Handle Mic key - produces 0 with Sym, otherwise ignore
+    // Handle Mic key - always produces '0' (silk-screened on key)
+    // Sym+Mic also produces '0' (consumes sym so it doesn't leak)
     if (keyCode == 34) {
-      if (_symActive) {
-        _symActive = false;
-        Serial.println("KB: Sym+Mic -> '0'");
-        return '0';
-      }
-      return 0;  // Ignore mic without Sym
+      _symActive = false;
+      Serial.println("KB: Mic -> '0'");
+      return '0';
     }
 
     // Get the character
@@ -276,7 +292,17 @@ public:
       if (c >= 'a' && c <= 'z') {
         c = c - 'a' + 'A';
       }
-      _shiftActive = false;  // Reset sticky shift
+      // Track that shift was used while physically held
+      if (_shiftHeld) {
+        _shiftUsedWhileHeld = true;
+      }
+      // Only clear shift if it's one-shot (tap), not held down
+      if (!_shiftHeld) {
+        _shiftActive = false;
+      }
+      _shiftConsumed = true; // Record that shift was active for this key
+    } else {
+      _shiftConsumed = false;
     }
     
     if (c != 0) {
@@ -294,4 +320,10 @@ public:
   bool wasShiftRecentlyPressed(unsigned long withinMs = 500) const {
     return (millis() - _lastShiftTime) < withinMs;
   }
+  
+  // Check if shift was active when the most recent key was produced
+  // (immune to e-ink refresh timing unlike wasShiftRecentlyPressed)
+  bool wasShiftConsumed() const {
+    return _shiftConsumed;
+  }
 };

variants/lilygo_tdeck_pro/platformio.ini

@@ -62,6 +62,8 @@ build_flags =
   -D EINK_MOSI=33
   -D EINK_BL=45
   -D EINK_NOT_HIBERNATE=1
+  -D HAS_BQ27220=1
+  -D AUTO_SHUTDOWN_MILLIVOLTS=2800
   -D EINK_LIMIT_FASTREFRESH=10
   -D EINK_LIMIT_GHOSTING_PX=2000
   -D DISPLAY_ROTATION=0
@@ -80,6 +82,7 @@ build_flags =
   -D PIN_DISPLAY_BL=45
   -D PIN_USER_BTN=0
   -D CST328_PIN_RST=38
+  -D ARDUINO_LOOP_STACK_SIZE=32768
 build_src_filter = ${esp32_base.build_src_filter}
   +<../variants/LilyGo_TDeck_Pro>
   +<helpers/sensors/*.cpp>
@@ -88,35 +91,108 @@ lib_deps =
   ${sensor_base.lib_deps}
   zinggjm/GxEPD2@^1.5.9
   adafruit/Adafruit GFX Library@^1.11.0
-  bakercp/CRC32@^2.0.0
+  bitbank2/PNGdec@^1.0.1
 
-[env:LilyGo_TDeck_Pro_companion_radio_usb]
+; ---------------------------------------------------------------------------
+; Meck unified builds — one codebase, six variants via build flags
+; ---------------------------------------------------------------------------
+
+; Audio + BLE companion (audio-player hardware with BLE phone bridging)
+; MAX_CONTACTS=500 is near BLE protocol ceiling (MAX_CONTACTS/2 sent as uint8_t, max 510)
+[env:meck_audio_ble]
 extends = LilyGo_TDeck_Pro
 build_flags =
   ${LilyGo_TDeck_Pro.build_flags}
   -I examples/companion_radio/ui-new
-  -D MAX_CONTACTS=350
-  -D MAX_GROUP_CHANNELS=40
-  -D OFFLINE_QUEUE_SIZE=256
-build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
-  +<helpers/esp32/*.cpp>
-  +<helpers/ui/MomentaryButton.cpp>
-  +<../examples/companion_radio/*.cpp>
-  +<../examples/companion_radio/ui-new/*.cpp>
-  +<helpers/ui/GxEPDDisplay.cpp>
-lib_deps =
-  ${LilyGo_TDeck_Pro.lib_deps}
-  densaugeo/base64 @ ~1.4.0
-
-[env:LilyGo_TDeck_Pro_companion_radio_ble]
-extends = LilyGo_TDeck_Pro
-build_flags =
-  ${LilyGo_TDeck_Pro.build_flags}
-  -I examples/companion_radio/ui-new
-  -D MAX_CONTACTS=400
+  -D MAX_CONTACTS=500
   -D MAX_GROUP_CHANNELS=20
   -D BLE_PIN_CODE=123456
   -D OFFLINE_QUEUE_SIZE=256
+  -D MECK_AUDIO_VARIANT
+  -D MECK_WEB_READER=1
+build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+  +<helpers/ui/GxEPDDisplay.cpp>
+lib_deps =
+  ${LilyGo_TDeck_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  https://github.com/schreibfaul1/ESP32-audioI2S.git#2.0.6
+  bitbank2/JPEGDEC
+
+; Audio + WiFi companion (audio-player hardware with WiFi app bridging)
+; No BLE — WiFi companion uses SerialWifiInterface (TCP socket on port 5000).
+; Connect via MeshCore web app, meshcore.js, or Python CLI over local network.
+; No BLE protocol ceiling on contacts; bumped to 1500 (PSRAM-backed).
+; WiFi always on from boot — web reader works without teardown, extra free heap.
+; WiFi credentials loaded from SD card at runtime (/web/wifi.cfg).
+; Configure via Settings > WiFi Setup, or through the web reader.
+[env:meck_audio_wifi]
+extends = LilyGo_TDeck_Pro
+build_flags =
+  ${LilyGo_TDeck_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=1500
+  -D MAX_GROUP_CHANNELS=20
+  -D MECK_WIFI_COMPANION=1
+  -D TCP_PORT=5000
+  -D WIFI_DEBUG_LOGGING=1
+  -D OFFLINE_QUEUE_SIZE=256
+  -D MECK_AUDIO_VARIANT
+  -D MECK_WEB_READER=1
+  -D FIRMWARE_VERSION='"Meck v0.9.8.WiFi"'
+build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+  +<helpers/ui/GxEPDDisplay.cpp>
+lib_deps =
+  ${LilyGo_TDeck_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  https://github.com/schreibfaul1/ESP32-audioI2S.git#2.0.6
+  bitbank2/JPEGDEC
+
+; Audio standalone (audio-player hardware, no BLE/WiFi — maximum battery life)
+; No MECK_WEB_READER: WiFi power draw conflicts with zero-radio-power design.
+; Contacts and sort arrays allocated in PSRAM — 1500 contacts uses ~290KB of 8MB.
+[env:meck_audio_standalone]
+extends = LilyGo_TDeck_Pro
+build_flags =
+  ${LilyGo_TDeck_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=1500
+  -D MAX_GROUP_CHANNELS=20
+  -D OFFLINE_QUEUE_SIZE=256
+  -D MECK_AUDIO_VARIANT
+build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+  +<helpers/ui/GxEPDDisplay.cpp>
+lib_deps =
+  ${LilyGo_TDeck_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  https://github.com/schreibfaul1/ESP32-audioI2S.git#2.0.6
+  bitbank2/JPEGDEC
+
+; 4G + BLE companion (4G modem hardware, no audio — GPIO conflict with PCM5102A)
+; MAX_CONTACTS=500 is near BLE protocol ceiling (MAX_CONTACTS/2 sent as uint8_t, max 510)
+[env:meck_4g_ble]
+extends = LilyGo_TDeck_Pro
+build_flags =
+  ${LilyGo_TDeck_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=500
+  -D MAX_GROUP_CHANNELS=20
+  -D BLE_PIN_CODE=123456
+  -D OFFLINE_QUEUE_SIZE=256
+  -D HAS_4G_MODEM=1
+  -D MECK_WEB_READER=1
+  -D FIRMWARE_VERSION='"Meck v0.9.8.4G"'
 build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
   +<helpers/esp32/*.cpp>
   +<helpers/ui/MomentaryButton.cpp>
@@ -127,20 +203,58 @@ lib_deps =
   ${LilyGo_TDeck_Pro.lib_deps}
   densaugeo/base64 @ ~1.4.0
 
-[env:LilyGo_TDeck_Pro_repeater]
+; 4G + WiFi companion (4G modem hardware with WiFi app bridging, no audio)
+; No BLE — WiFi companion uses SerialWifiInterface (TCP socket on port 5000).
+; Connect via MeshCore web app, meshcore.js, or Python CLI over local network.
+; WiFi credentials loaded from SD card at runtime (/web/wifi.cfg).
+; Configure via Settings > WiFi Setup, or through the web reader.
+; Contacts and sort arrays allocated in PSRAM — 1500 contacts uses ~290KB of 8MB.
+[env:meck_4g_wifi]
 extends = LilyGo_TDeck_Pro
 build_flags =
   ${LilyGo_TDeck_Pro.build_flags}
-  -D ADVERT_NAME='"TDeck Pro Repeater"'
-  -D ADVERT_LAT=0.0
-  -D ADVERT_LON=0.0
-  -D ADMIN_PASSWORD='"password"'
-  -D MAX_NEIGHBOURS=50
-  -D NO_OTA=1
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=1500
+  -D MAX_GROUP_CHANNELS=20
+  -D MECK_WIFI_COMPANION=1
+  -D TCP_PORT=5000
+  -D WIFI_DEBUG_LOGGING=1
+  -D OFFLINE_QUEUE_SIZE=256
+  -D HAS_4G_MODEM=1
+  -D MECK_WEB_READER=1
+  -D FIRMWARE_VERSION='"Meck v0.9.8.4G.WiFi"'
 build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
-  +<../examples/simple_repeater>
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
   +<helpers/ui/GxEPDDisplay.cpp>
 lib_deps =
   ${LilyGo_TDeck_Pro.lib_deps}
-  me-no-dev/AsyncTCP @ ^1.1.1
-  me-no-dev/ESPAsyncWebServer @ ^1.2.3
+  densaugeo/base64 @ ~1.4.0
+
+; 4G standalone (4G modem hardware, no BLE — maximum battery + cellular features)
+; No BLE_PIN_CODE: BLE never initializes, saving ~30KB heap + radio power.
+; MECK_WEB_READER enabled: works better without BLE (no teardown dance needed,
+; more free heap from boot). WiFi-first with cellular PPP fallback (future).
+; Contacts and sort arrays allocated in PSRAM — 1500 contacts uses ~290KB of 8MB.
+[env:meck_4g_standalone]
+extends = LilyGo_TDeck_Pro
+build_flags =
+  ${LilyGo_TDeck_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=1500
+  -D MAX_GROUP_CHANNELS=20
+  -D OFFLINE_QUEUE_SIZE=256
+  -D HAS_4G_MODEM=1
+  -D MECK_WEB_READER=1
+  -D FIRMWARE_VERSION='"Meck v0.9.8.4G.SA"'
+build_src_filter = ${LilyGo_TDeck_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+  +<helpers/ui/GxEPDDisplay.cpp>
+lib_deps =
+  ${LilyGo_TDeck_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0

variants/lilygo_tdeck_pro/target.cpp

@@ -17,7 +17,10 @@ ESP32RTCClock fallback_clock;
 AutoDiscoverRTCClock rtc_clock(fallback_clock);
 
 #if HAS_GPS
-  MicroNMEALocationProvider gps(Serial2, &rtc_clock);
+  // Wrap Serial2 with a sentence counter so the UI can show NMEA throughput.
+  // MicroNMEALocationProvider reads through this wrapper transparently.
+  GPSStreamCounter gpsStream(Serial2);
+  MicroNMEALocationProvider gps(gpsStream, &rtc_clock);
   EnvironmentSensorManager sensors(gps);
 #else
   SensorManager sensors;

variants/lilygo_tdeck_pro/target.h

@@ -18,6 +18,7 @@
 #if HAS_GPS
   #include "helpers/sensors/EnvironmentSensorManager.h"
   #include "helpers/sensors/MicroNMEALocationProvider.h"
+  #include "GPSStreamCounter.h"
 #else
   #include <helpers/SensorManager.h>
 #endif
@@ -27,6 +28,7 @@ extern WRAPPER_CLASS radio_driver;
 extern AutoDiscoverRTCClock rtc_clock;
 
 #if HAS_GPS
+  extern GPSStreamCounter gpsStream;
   extern EnvironmentSensorManager sensors;
 #else
   extern SensorManager sensors;