wadamesh/CONSOLE_MODE.md

# Console mode

A boot mode where the device runs with **no LVGL**: a text console driven by
typed commands, with core mesh functionality and Lua apps. For boards that
struggle under the UI, and for people who would rather type than tap.

Regular mode is unaffected and you can go back at any time.

---

## Short answer

**Possible: yes, and considerably more of it already exists than you would
expect.** Four of the five pieces are built and shipping today.

**A lot of work: no, not for a usable console.** The work is not the console
itself, it is everything that currently assumes the UI is there. Realistic
shape: a useful console in a few days of work, a polished one that runs Lua
apps in a couple of weeks.

**Saves resources: yes, but not the resource you might think.** See
[What it actually saves](#what-it-actually-saves) below, because this changes
how the feature should be sold and to whom.

---

## What already exists

This is the reason the estimate is not larger.

| Piece | Where | State |
|---|---|---|
| **Command surface** | `CommonCLI::handleCommand` (MeshCore core) | Done. The full command set the node already answers over serial and over the mesh. |
| **Run a command locally, capture its output** | `MyMesh::runLocalCli()` + `MyMesh::setTerminalSink()` | Done. Feed it a line, get reply lines back through a callback. |
| **Text rendering with no LVGL** | `DisplayDriver` (core): `startFrame`, `setCursor`, `print`, `printWordWrap`, `getTextWidth`, `fillRect`, `drawTextEllipsized`, `endFrame`, UTF-8 to blocks | Done, and linked into the touch build already. |
| **A mode where LVGL does not drive the panel** | Remote mode (`s_remote_mode` in `UITask.cpp`) | Done and shipping. It paints the physical screen with `display.drawTextCentered(...)` directly while LVGL renders elsewhere. This is the exact precedent. |
| **An on-device terminal** | `homeTerminalCb` / `s_term_log_box` in `UITask.cpp` | Done, but built out of LVGL widgets. The *behaviour* is the model; the widgets are what console mode replaces. |

So the console does not need a new command language, a new renderer, or a new
way of talking to the mesh. It needs a different **front end** over machinery
that is already there and already tested.

---

## What it actually saves

Worth being precise, because the obvious assumption is wrong in one direction
and right in another.

### PSRAM: a real saving, and it is the object tree, not the draw buffer

Everything LVGL allocates is PSRAM: `include/lv_conf.h` sets `LV_MEM_CUSTOM 1`
with `LV_MEM_CUSTOM_ALLOC lvglPsramAlloc`, so every object, style and font cache
entry is a PSRAM allocation, and the draw buffer is `MALLOC_CAP_SPIRAM` too.

**The draw buffer is not the prize.** `LV_DRAW_BUF_LINES` is 24, so it is
37.5 KB on the 800 px panels and **11.2 KB on the V4**. Worth having back, not
worth building a mode for.

The saving is the **object tree**: every screen, tab, list row, label, style and
cached glyph, all of it live for the life of the session. That is the number
Phase 0 exists to measure, because it is the one nobody here can quote from
memory.

For scale on the V4, its PSRAM is also carrying up to four 128 KB map tiles, so
whatever LVGL is holding sits alongside that. Console mode frees the LVGL half
outright.

**This matters most exactly where you said it hurts.** The Heltec V4 has 2 MB of
PSRAM, and PSRAM pressure there is a recurring source of real bugs: map tiles
fragmenting the heap, the tile pool needing a cull and a cap, the extended Lua
SDK gated off the board entirely for want of memory. Console mode gives that
board its PSRAM back.

### Internal DRAM: a smaller saving than it looks

The scarce resource on these boards is internal DRAM, and LVGL is largely not
in it. What *is* in it is UITask's static data: the contact cache, message
rings, layout tables. Most of that is data the console still needs to do the
same job, so it does not simply disappear.

Two caveats worth keeping honest:

- There is a fallback at boot: if the PSRAM draw-buffer allocation fails,
  `malloc()` puts it in internal DRAM instead. On a board already under
  pressure that is exactly when it happens, so for the worst-off devices the
  DRAM saving is real after all.
- A meaningful DRAM number needs measuring, not guessing. See Phase 0.

### CPU: a real saving, and probably the one users feel

`lv_timer_handler()` runs on every pass of the main loop, alongside input-device
polling and any animation or scroll in flight, and a redraw blits through SPI.
A console redraws only when a line is added.

This is also the mechanism behind several bugs we have already fixed: the loop
being stalled by the UI is what starved the GPS UART ring, and what made SPIFFS
garbage collection visible as a freeze. Less time in the UI is less exposure to
that whole class of problem.

**How to describe the feature honestly:** it buys back PSRAM and CPU. On the
V4 that is the difference between comfortable and not. It is not a fix for
internal-DRAM exhaustion on its own.

---

## The hard parts

Not the console. These three.

### 1. Everything that assumes the UI exists

`src/main.cpp` calls `ui_task.showAlert(...)` in roughly twenty places to report
Wi-Fi and Bluetooth outcomes, and `ui_task.loop()` unconditionally. UITask is
also the owner of things the console still wants: the storage root, the Lua app
host, the update check.

The wrong fix is `#if` sprinkled through main. The right one is that UITask
keeps its role as the front end and gains a **headless personality**: the same
entry points, LVGL never initialised, `showAlert` becoming a console line.

### 2. Lua apps: the `wada.ui` translator

Decided: `wada.ui` gets a **console backend** behind the same names, so an app
keeps working without knowing which mode it is in.

This turns out to be far more achievable than "no UI" suggests, because console
mode is **not a text-only terminal**. It still owns a real pixel panel. The
thing being removed is LVGL's object tree, not the ability to draw.

The enabler is a raw framebuffer blit that already exists outside LVGL:

```
ST7789LCDDisplay::writePixelsRGB565(x, y, w, h, const uint16_t* pixels)
```

Present today on `ST7789LCDDisplay` (V4 TFT, T-Deck), `TanmatsuDisplay`,
`RM69A10Display` and `HI8561Display`. Missing only on `LGFXDisplay` (V4-R8) and
`ST7796LCDDisplay` (the pagers), and LovyanGFX has `pushImage` underneath, so
those are a wrapper method rather than new work.

That changes the answer on the two APIs that looked impossible:

| API | Console backend | Why it works |
|---|---|---|
| `label` | Text at a cursor. | `print` / `printWordWrap` / `drawTextEllipsized`. |
| `button` | A highlighted line with a selection index; activated by key or tap. | Text plus `fillRect` for the highlight. |
| `list` | Numbered lines, one selected. | Same. |
| `input` | A prompt, using the console's own keypad. | Phase 1 already builds it. |
| `text_w` / `text_lines` | `getTextWidth`, honestly measured. | Already the right shape. |
| `chart` | Drawn directly. | It is bars and lines; `fillRect` does it. |
| **`canvas`** | **Works.** The app already gets an RGB565 buffer and draws into it; console mode blits that buffer instead of handing it to LVGL. | `writePixelsRGB565`. |
| **`map`** | **Works.** Tiles are already decoded to RGB565 buffers (`MapTile.rgb565`); the projection and cache are ours and have no LVGL in them. | Same blit, plus markers as `fillRect`. |
| Everything non-UI | Unchanged. | `mesh`, `fs`, `net`, `crypto`, `geo`, `sys`, `timer`, `store` never touched LVGL. |

**What is genuinely lost is interaction, not drawing.** LVGL supplies scrolling
containers, a focus group, flex layout and event bubbling. The console backend
has to provide its own much simpler version: a line cursor, a selection index,
a scroll offset. That is the real work in this phase, and it is bounded.

So the honest expectation is that **most apps work**, including the graphical
ones, and a few that lean on LVGL behaviour we do not reimplement will not.
Apps already feature-detect through `wada.sys.caps()`, so anything that cannot
be supported is reported rather than broken, and `caps().console` lets an app
adapt its layout deliberately.

### 3. Getting back out

A boot flag that lands you in a console with no way back is a device that feels
bricked, and it will happen to somebody. This needs to be designed, not bolted
on. See [Safety](#safety).

---

## Plan

Each phase is shippable and useful on its own. Stop after any of them and
nothing is half-built.

### Phase 0: measure first

Before building anything, get the numbers the feature is being justified by.

- Free internal DRAM and free PSRAM at the home screen, on a V4 and a T-Deck.
- The same with `lv_timer_handler()` stubbed out and nothing built.
- Loop iterations per second, both ways.

Cheap, and it either confirms the case or changes what to build. If the DRAM
saving turns out to be negligible on the V4 and the PSRAM saving large, that is
worth knowing before the docs promise anything.

**Output:** real numbers in this file.

### Phase 1: the console front end

A `ConsoleUI` that owns the panel through `DisplayDriver`, with no LVGL.

- Scrollback ring in PSRAM, N lines, prune oldest.
- Prompt line, cursor, word wrap via `printWordWrap`.
- Input from the hardware keyboard where there is one.
- **An on-screen keypad on touch boards.** Decided: the V4 is the board that
  most needs its resources back, so console mode has to be usable there without
  a keyboard. The existing on-screen keyboard is LVGL and cannot be reused, so
  the console draws its own: `fillRect` + `drawRect` + `print` for the keys, and
  touch read straight from the board driver (`heltecV4CapTouchCheck()` and its
  equivalents), which is already independent of LVGL. `lvglTouchRead` is only an
  adapter feeding LVGL, so nothing needs to be untangled first.
- Commands go straight to `the_mesh.runLocalCli()`; output arrives through
  `setTerminalSink`. This part is close to free.
- One touch affordance, as you said: a back/exit target.

At the end of this phase the device is usable over the mesh from a console.

### Phase 2: boot into it, and back out

- A pref, `touchPrefsGetBootMode()`, read early in `setup()`.
- In console mode: never call `lv_init()`, never allocate the draw buffer, never
  build the UI. This is where the saving comes from, so it has to be a genuine
  skip and not a hidden LVGL instance.
- `ui_task.showAlert()` and friends route to the console.
- Commands to switch: `ui` reboots into the graphical mode, `console` reboots
  into this one. Also a Settings toggle in normal mode.

### Phase 3: the things the CLI does not cover

`CommonCLI` is a node CLI, not a messenger. Console mode needs conversational
commands, some of which the existing on-device terminal already has (`to <name>`
sets a recipient):

- `msg`, `to`, `reply`, unread counts, reading a thread's scrollback
- `contacts`, `chans`, `discover` with the results table
- `apps`, `run <id>`

Most of this is a thin layer over calls that already exist for the UI.

### Phase 4: Lua apps in the console

- A `WADA_UI_CONSOLE` backend behind the same `wada.ui` names, per the table
  above.
- `caps()` gains `console`, `canvas`, `map` so apps can adapt, and the docs say
  which apps work.
- Store apps audited; those that cannot work say so on launch rather than
  failing oddly.

### Phase 5: polish

- Command history and tab completion.
- Colour, where the panel has it.
- A `help` that is actually good, since there is no discoverable UI.
- Docs page, and a section in the user guide.

---

## Safety

The failure that matters is a device that boots to a console the owner cannot
leave. Three independent ways out, because one is not enough:

1. **A command.** `ui` then reboot.
2. **A key held at boot.** Any boot with the key down forces graphical mode
   regardless of the pref, the same shape as the existing recovery paths.
3. **The web flasher and the serial CLI** can always clear the pref.

And the pref should be stored so that a corrupt or unreadable value means
*graphical*, never console. Fail toward the mode everyone can use.

---

## Risks

| Risk | Containment |
|---|---|
| Console mode rots because nobody builds it | It compiles into every build from Phase 1, and SDK Test runs in it. A broken console fails the build, not a user. |
| Two front ends drift apart | The console consumes the same `runLocalCli` and the same MyMesh accessors the UI does. Do not let it grow a private copy of anything. |
| Touch-only boards get a console they cannot type into | Decide in Phase 1. Requiring a keyboard is a legitimate answer. |
| It quietly degrades normal mode | Everything new is behind the boot pref, and the graphical path keeps its current code path unchanged. Phase 0's numbers are the regression check. |
| Lua apps half-work and look broken | `caps()` first, refuse to launch second, document third. Less likely now that canvas and map can actually be drawn. |
| Two display drivers lack a raw blit | `LGFXDisplay` and `ST7796LCDDisplay` need a `writePixelsRGB565`; LovyanGFX's `pushImage` does the work. Until then `caps().canvas` is false on those boards and apps adapt. |

---

## Effort

Honest, assuming no surprises:

| Phase | Effort |
|---|---|
| 0 measure | Half a day |
| 1 console front end (incl. the drawn keypad) | 3 to 4 days |
| 2 boot mode and back out | 1 to 2 days |
| 3 messaging commands | 2 to 3 days |
| 4 `wada.ui` console backend | 4 to 6 days |
| 5 polish and docs | 2 days |

**A console you can actually use on the mesh: Phases 0 to 3, about a week.**
Phase 4 is the one that can grow, because it is the one with a design question
in it rather than just code.

---

## Open decisions

Worth settling before Phase 1 rather than during it.

1. ~~Keyboard required?~~ **Decided: no.** Touch boards get a drawn on-screen
   keypad, because the V4 is exactly the board this feature is for.
2. **Do Lua apps matter in v1?** Phases 0 to 3 are worth shipping without them.
   The translator is now a known quantity rather than a question mark, so it can
   follow safely.
3. **Does this replace the Terminal app** in graphical mode eventually, or do
   both stay?

---

## Audit: every UI surface, and its console equivalent

Done by enumerating the real thing rather than from memory: the tab list, the
app-drawer action enum (`APPACT_*`), the 19 settings categories, and the node
CLI's own command table in `CommonCLI.cpp`.

**The single most useful finding: the node CLI already covers far more than
expected.** `advert`, `board`, `clock`, `clock sync`, `erase`, `get`/`set`,
`gps` (on/off/sync/setloc/advert), `log`, `neighbors`, `ota url`, `password`,
`poweroff`, `powersaving`, `reboot`, `region`, `sensor list/get/set`,
`shutdown`, `start ota`, `tempradio`, `time`, `ver`. All of that arrives free,
which is why the console needed far fewer new commands than the UI has screens.

### Tabs and apps

| UI surface | Console | State |
|---|---|---|
| Chats: read a thread | `chat <name>` | **done** |
| Chats: send | `to <name>` + `msg <text>` | **done** |
| Chats: unread badges | `unread`, `read <name>` | **done**, and the monitor never clears them |
| Live incoming messages | the monitor, `monitor on\|off` | **done** |
| Contacts list | `contacts` | **done** |
| Contacts: favourite / block / delete | none | gap |
| Channels list | `chans` | **done** |
| Discover | `discover`, `discovered` | **done**, with both link directions |
| Advertise | CLI `advert` | free |
| Signal / traffic | `stat` | **done** |
| Map | none | needs the `wada.map` blit path; not console-shaped yet |
| Terminal | this *is* the console | n/a |
| Files | none | gap |
| Spectrum | none | gap, and heavy |
| Store / Lua apps | none | Phase 4 |
| Web reader | none | gap |
| VNC / Remote | none | deliberate: another front end, not a console feature |
| Power menu | CLI `poweroff` / `reboot` | free |
| Mentions | `unread` shows counts | partial |

### Settings, all 19 categories

| Category | Console | State |
|---|---|---|
| Radio & Mesh | CLI `get`/`set`, `region`, `tempradio` | free |
| GPS | CLI `gps *` | free |
| Clock & time | CLI `clock`, `time` | free |
| Sensors | CLI `sensor *` | free |
| About | CLI `ver`, `board`; `mem` | free |
| Battery | `batt` | **done** |
| Wi-Fi | `wifi` (state only) | partial |
| Bluetooth | none | gap |
| Auto-add | none | gap |
| Display / Keyboard / Sound / Lock screen | none | not meaningful without the UI |
| Quick replies | none | gap |
| Backups | none | gap |
| Language | none | gap |
| MQTT bridge | `mqtt status` | **done** (diagnostics only) |
| App permissions | none | with Phase 4 |
| General | `console`/`ui` toggle | partial |

### What the gaps have in common

Almost everything still missing is either **Phase 4** (anything Lua), **not
console-shaped** (Display, Keyboard, Lock screen: settings for a UI that is not
running), or **a list-and-act flow** (files, backups, quick replies, contact
actions) that all wants the same small pattern: number the list, act on the
number. That pattern is worth building once rather than six times.

The two genuinely interesting gaps are **Files** and **contact actions**
(favourite, block, delete), because both are things people do reach for.