# Clawdmeter v2 — roadmap

v2 turns Clawdmeter from a single-purpose usage indicator into a small
multi-app wrist companion for the Waveshare AMOLED-2.06 watch.

- **Classic line** — the stable 2.06 port + working Windows BLE daemon. Frozen on
  `main`, tagged `v1.0-classic`. Bugfix-only.
- **v2 development** — this branch (`v2-dev`). When it's ready it merges to `main`
  and is tagged `v2.0.0`.

## Architecture decisions (locked)

- **Navigation:** tap the Claude logo (top-left) → app launcher. Each feature is an
  "app" screen registered in a registry (`{id, icon, label, show/hide}`), mirroring
  the board-HAL pattern: a new app = one registry entry + one screen module, no
  edits to shared navigation code.
- **Home Assistant:** routed **through the desktop daemon** (watch → BLE → daemon →
  HA REST API). The watch stays dumb; the HA URL/token live on the PC. No WiFi
  provisioning or secrets on the watch.
- **Desktop companion:** a **local web UI** (FastAPI, opened from the tray) for
  config, firmware flashing, and per-app setup (soundpad labels, HA entity map,
  Now Playing).
- **Soundpad:** on-screen buttons emit **F13–F18** over the existing BLE HID
  keyboard. Requires raising the HID report map's keycode ceiling (currently 101 /
  0x65; F13–F24 are 0x68–0x73).

## Phases

| # | Phase | Depends on | Daemon work |
|---|-------|-----------|-------------|
| 0 | Version split — freeze classic, branch `v2-dev`, version constant | — | no |
| 1 | Touch foundation — verify FT3168 coordinate accuracy, calibrate swap/mirror, logo hit-area | — | no |
| 2 | Menu / launcher — app registry, launcher screen, nav stack, back affordance | 1 | no |
| 3 | Soundpad — raise HID ceiling to F24, 6-button screen → F13–F18 | 2 | no |
| 4 | Session / tokens — daemon computes today's tokens/$; extend payload + parser + screen | 2 | data |
| 5 | Now Playing — daemon reads Windows media session; new screen | 2 | media |
| 6 | Home Assistant — watch→daemon command characteristic, HA bridge, control screen | 2 | HA bridge |
| 7 | Desktop companion — local web UI: config + one-click firmware flash (esptool, bins from Gitea Releases) | — | big upgrade |
| 8 | Release v2.0 — docs, icons, Gitea release with firmware binaries | all | — |

Each UI phase is verified on hardware via the `screenshot` serial command before
moving on.

## BLE data channel (current + planned)

Custom GATT service `4c41555a-…0001`:

| Char | Dir | Now | v2 plan |
|------|-----|-----|---------|
| `…0002` RX | PC→watch | JSON usage payload | + session/tokens, now-playing fields |
| `…0003` TX | watch→PC | ack/nack | (unchanged) |
| `…0004` REQ | watch→PC | refresh request (0x01) | (unchanged) |
| `…0005` CMD | watch→PC | — | **new:** app commands (HA toggle, etc.) |

Plus the standard BLE HID keyboard (0x1812) for Space / Shift+Tab / soundpad keys.