2026-09-24 22:22:37 +02:00
# UI Core + frontends — design
Status: 📋 draft for review (2026-09-24). Branch: `wio-tracker-l2` .
## Why
The Wio Tracker L2 (320×
interface. Rather than a second, parallel copy of everything Solo does, the
application logic moves out of `ui-new` into a hardware-independent **UI Core**
that every frontend shares:
| Frontend | Devices | Toolkit | Input |
|---|---|---|---|
| `ui-lvgl` (rich) | Wio Tracker L2 first; later other ESP32-S3 colour boards | LVGL 9 | pointer (touch) + focus (buttons, CardKB) |
| `ui-new` (lite) | OLED / e-ink / nRF52 (Wio L1, T-Echo Lite, Heltec, …) | `DisplayDriver` | focus (joystick, buttons, CardKB) |
A feature written once in the Core (live share, locator, unread tracking, a new
setting) then shows up on both. `ui-new` is not rewritten: it is re-pointed at
the Core and stays the lite frontend.
Non-goals: changing the mesh protocol, `MyMesh` , persistence formats
(`NodePrefs` layout, `/scopes1` , trail files), or the companion app protocol.
## Current state
`ui-new` is 18.5k lines. `UITask` implements `AbstractUITask` (the interface
`MyMesh` calls into) *and* hosts the screens, so logic and drawing are
interleaved. Classified:
**Models — already UI-free, move as-is**
2026-09-24 23:00:46 +02:00
- `MessageHistory.h` — channel (48) / DM (32) rings, unread counters + overflow flags. ✅ moved to `ui-core/` .
2026-09-24 22:22:37 +02:00
- `Trail.h` / `TrailStore` , waypoints (`WaypointsView` storage half), `ScopeList.h` .
**Engines — logic living inside `UITask.cpp` / `UITask.h`**
2026-09-24 23:00:46 +02:00
- Unread tracking — DM unread table ✅ (`ui-core/DmUnreadTable.h` ), room unread (still in `UITask` ).
2026-09-24 23:28:58 +02:00
- Notifications ✅ split: the Core decides *what* happened (`MessageArrived` with kind / DM sender / channel slot, `AdvertHeard` ); the frontend decides *how* to show it (`showAlert` , `SoundNotifier` , vibration, LED, wake-on-message) — those are platform services.
2026-09-24 23:09:26 +02:00
- Live share ✅ `ui-core/LiveShareEngine.h` — session timer, movement/heartbeat gate, send + scope guard, peers' `LiveTrackStore` + expiry.
2026-09-24 23:15:18 +02:00
- Locator ✅ `ui-core/LocatorEngine.h` — active target, geofence state machine, proximity beeper.
2026-09-24 23:17:03 +02:00
- Trail ✅ `ui-core/TrailEngine.h` — store, sampling, auto-pause, low-battery auto-save.
2026-09-24 23:07:32 +02:00
- Course over ground + current position ✅ `ui-core/CourseEngine.h` .
2026-09-24 23:03:57 +02:00
- Clock tools — alarm / countdown / ring ✅ `ui-core/ClockEngine.h` .
2026-09-24 23:05:39 +02:00
- Ping ✅ `ui-core/PingEngine.h` (timeout still decided by `NearbyScreen` ).
2026-09-24 22:22:37 +02:00
- Device controls — GPS on/off, GPIO (`setGpioMode` , bot GPIO), buzzer mode/volume, brightness, radio apply (`applyTxPower` , `applyApc` , `applyRadioParams` , …).
- Bot hooks — `botSetGPS` , `botBuzz` , `botSetGPIO` , …
**Screen-embedded logic (harder to extract)**
- `SettingsScreen.h` (1.3k lines) — ~40 items, each with inline get/format/step/apply code.
- `NearbyScreen.h` — contact discovery/sorting; `AdminScreen.h` — repeater admin session; `BotScreen.h` ; `RepeaterScreen.h` ; `MessagesScreen.h` (2.6k lines) — list ordering, favourites, context-menu actions mixed with rendering.
**Pure view / widgets — stay in `ui-new`**
- Rendering of every screen, `KeyboardWidget` , `PopupMenu` , `AccordionList` , `TabBar` , `icons.h` , `GfxUtils.h` , marquee, badges.
## Architecture
```
MyMesh ──(AbstractUITask callbacks)──► UiCore ──events──► Frontend (ui-new | ui-lvgl)
▲ │ ▲ │
└──────────── mesh actions ────────────┘ └──── actions ─────┘
engines, models, settings schema
Platform services (per board): Sound, DisplayPower, Input sources, Led
```
### 1. `UiCore` owns the mesh-facing interface
2026-09-24 22:54:40 +02:00
`MyMesh` talks to the UI only through `MyMesh::Listener` (set with
`setListener()` ), ported from upstream's "Abstract UI overhaul" (PR #3431 and
follow-ups `3caf033d` , `5c3d9281` , `30dd723c` , `b3b17025` , `64434c53` ) with
identical names/signatures. A second block in the same interface holds this
fork's extensions (own-send mirroring, relay echoes, room login/admin replies,
`[LOC]` shares, contact/channel removal, bot device actions,
`requestShutdown` ), each defaulting to a no-op.
2026-09-24 23:28:58 +02:00
For `ui-new` , `UiCore` is the Listener (`UITaskBase::meshListener()` hands it
to `MyMesh::setListener()` ): it applies the display filter, labels room posts,
files history, keeps unread counters, runs the engines and emits events. The
frontend implements `UiCoreHost` (`ui-core/UiCoreHost.h` ) for what the Core
still asks of it synchronously: "is this conversation on screen", "keep the
selection after an insert", and forwarding for not-yet-extracted parts (room
login / admin sessions, bot device actions, prefs cleanup on contact/channel
removal, shutdown). `ui-orig` / `ui-tiny` keep `AbstractUITask` , which is
`UITaskBase` + the Listener glue, unchanged. This is the single point that
makes both frontends receive identical behaviour.
2026-09-24 22:22:37 +02:00
### 2. Engines
One class per engine from the inventory above, each with `begin(prefs, …)` ,
`loop(now_ms)` and a small public API. No drawing, no `DisplayDriver` , no
screen pointers. Engines that need to show something emit an event
(`AlertRequested{text, ms}` , `LocShareEnded` , `AlarmFired` , …) instead of
calling `showAlert()` directly.
Constraints (the lite frontend runs on nRF52 with ~215 KB flash / ~65 KB RAM
free): no heap allocation, no RTTI/exceptions, no STL containers, fixed-size
buffers — the same rules `ui-new` follows today. Extraction must be roughly
size-neutral on `WioTrackerL1_companion_solo_dual` .
### 3. Events: Core → frontend
A small fixed-size queue of tagged events plus coarse dirty flags
(`DIRTY_MESSAGES` , `DIRTY_CONTACTS` , `DIRTY_STATUS` , …). The frontend drains
the queue in its `loop()` and redraws what is dirty. No callbacks into the
frontend from inside mesh processing — which also keeps the e-ink busy-wait
pump rule ("never re-enter UI code from the radio path") trivially true.
### 4. Actions: frontend → Core
Plain methods on the Core facade: `sendDM` , `sendChannelMsg` , `markRead` ,
`setLiveShare` , `setLocatorTarget` , `toggleGps` , `startPing` , … Both frontends
call the same ones, so e.g. "marking a channel read" has one implementation.
### 5. Declarative settings schema
Replaces the per-item code in `SettingsScreen` :
```cpp
struct SettingDef {
const char * id ; // stable key, also used for search / CLI
const char * label ;
uint8_t section ; // Radio / System / Display / …
SettingType type ; // Bool, Enum, Int, Text, Action
// accessors over NodePrefs; enum labels; min/max/step
int ( * get )( const NodePrefs & );
void ( * set )( NodePrefs & , int );
const char * ( * label_for )( int v ); // Enum/Int formatting
bool ( * visible )( const NodePrefs & ); // build- or state-dependent rows
bool ( * locked )( const NodePrefs & , const char ** why ); // "Off while repeating"
void ( * apply )( UiCore & ); // side effect after set (radio, display…)
};
```
`ui-new` renders it as today's accordion list; `ui-lvgl` as switches, dropdowns
and sliders. Build-time gating (`FEAT_*` ) stays in the table via `#if` , so a
hidden row costs no flash.
### 6. Platform services
Per-board implementations behind small interfaces: `Sound` (buzzer PWM today;
I2S ES8311 tone generator on L2), `DisplayPower` (auto-off, brightness), `Led` ,
and input sources. Input reaches frontends in two forms: **focus keys** (the
existing `KEY_*` codes — joystick, buttons, CardKB) and **pointer events**
(`down/move/up` with coordinates — touch). LVGL consumes both natively; `ui-new`
consumes keys only.
## `ui-lvgl` specifics
- LVGL 9 (pinned), memory in a PSRAM pool; partial-render buffers in internal RAM, flush over QSPI via LovyanGFX.
- Theme tokens (colours, spacing, typography) in one place — the first chance to realise the "Amber Trace" direction in colour.
- Fonts with full Latin/Polish/Cyrillic coverage.
- Runs in the WASM sim at 320×
- PR #3381 's LVGL UI is a reference for platform glue (flush, GT911, PSRAM pool) only; its screens are not adopted.
## Migration plan
Each step keeps `WioTrackerL1_companion_solo_dual` behaviour identical and is
checked in the sim plus on L1 hardware before the next one.
2026-09-24 22:54:40 +02:00
0. **Listener boundary** ✅ (upstream `MyMesh::Listener` ported; `MyMesh` has no UI calls left).
2026-09-24 23:00:46 +02:00
1. **Skeleton** ✅. `examples/companion_radio/ui-core/` with `UiCore.h` (facade), `MessageHistory.h` , `DmUnreadTable.h` . Header-only for now, reached from `ui-new/UITask.cpp` by relative include, so none of the 66 variant `platformio.ini` files that build `ui-new` change. `UITask` heap-allocates one `UiCore` in `begin()` (before the screens, as `MessagesScreen` used to own the history on the heap); `MessagesScreen` binds to `core().history` by reference. When the Core grows real `.cpp` files, compile them through a unity `.cpp` inside each frontend directory.
2026-09-24 23:28:58 +02:00
2. **Engines, one per commit.** Clock tools ✅ (also introduced `ui-core/UiEvents.h` , the Core → frontend event queue; `UITask::tickCore()` runs `UiCore::loop()` and drains it) → ping ✅ → course-over-ground ✅ → live share ✅ → locator ✅ → trail ✅ → notifications ✅ (with step 3). `UITask` shrinks to screen management + drawing.
3. **Flip the interface** ✅. `UiCore` is `MyMesh::Listener` ; `ui-new` 's `UITask` derives `UITaskBase` + `UiCoreHost` and is fed by events, drained at the start (mesh-originated) and end (engines) of its `loop()` . Mesh callbacks no longer touch the display or buzzer directly.
2026-09-24 22:22:37 +02:00
4. **Settings schema.** Convert `SettingsScreen` section by section.
2026-09-24 23:49:42 +02:00
5. ** `ui-lvgl` skeleton** ✅ on L2 hardware (env `Wio_Tracker_L2_companion_solo_lvgl` , LVGL 9.2.2): status bar, home, conversation list, contact picker, conversation with keyboard, toasts, display sleep/wake. The Core gained the first actions (`sendDirectText` , `sendChannelText` ) and runs DM resends itself. Still to do: sim target at 320×
2026-09-24 22:22:37 +02:00
6. Contacts/Nearby, Admin, Bot logic extraction as the LVGL screens for them are built.
## Decisions
- **Upstream merge cost accepted** (2026-09-24). Moving code out of `ui-new`
will conflict with upstream edits to the same files; this fork's `ui-new` is
already heavily diverged, and upstream is itself working toward a larger UI
abstraction — revisit alignment when that lands.
- **Scope is UI only** (2026-09-24). The settings schema and event queue serve
the on-device frontends; CLI and companion-app settings/push paths are
untouched for now.
