From 25b101d0867505496260f73a9af43b1800bb01ac Mon Sep 17 00:00:00 2001
From: wenil <x570@local>
Date: Sat, 20 Jun 2026 13:49:40 +0300
Subject: [PATCH] =?UTF-8?q?v2:=20kick=20off=20v2-dev=20=E2=80=94=20version?=
 =?UTF-8?q?=20constant=20+=20roadmap?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Freeze the classic line on main (tagged v1.0-classic) and open the v2
development branch. Add a firmware version constant (2.0.0-dev) reported in
the boot banner so the daemon can tell classic from v2, and document the
phased v2 plan in docs/v2-roadmap.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/v2-roadmap.md     | 55 ++++++++++++++++++++++++++++++++++++++++++
 firmware/src/main.cpp  |  3 ++-
 firmware/src/version.h | 10 ++++++++
 3 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 docs/v2-roadmap.md
 create mode 100644 firmware/src/version.h

diff --git a/docs/v2-roadmap.md b/docs/v2-roadmap.md
new file mode 100644
index 0000000..e52f3fc
--- /dev/null
+++ b/docs/v2-roadmap.md
@@ -0,0 +1,55 @@
+# 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.
diff --git a/firmware/src/main.cpp b/firmware/src/main.cpp
index 1207553..8822235 100644
--- a/firmware/src/main.cpp
+++ b/firmware/src/main.cpp
@@ -7,6 +7,7 @@
 #include "data.h"
 #include "ui.h"
 #include "ble.h"
+#include "version.h"
 #include "splash.h"
 #include "usage_rate.h"
 #include "idle.h"
@@ -180,7 +181,7 @@ extern "C" void board_init(void);
 void setup() {
     Serial.begin(115200);
     delay(300);
-    Serial.println("{\"ready\":true}");
+    Serial.printf("{\"ready\":true,\"fw\":\"%s\"}\n", CLAWDMETER_VERSION);
 
     board_init();
 
diff --git a/firmware/src/version.h b/firmware/src/version.h
new file mode 100644
index 0000000..de315bf
--- /dev/null
+++ b/firmware/src/version.h
@@ -0,0 +1,10 @@
+#pragma once
+
+// Clawdmeter firmware version.
+//
+// The "classic" line — the stable Waveshare AMOLED-2.06 port plus the working
+// Windows BLE daemon — is frozen on the `main` branch and tagged v1.0-classic.
+// Active development (multi-app launcher, on-screen soundpad, Now Playing,
+// Home Assistant control, richer desktop companion) lives on `v2-dev`.
+// See docs/v2-roadmap.md.
+#define CLAWDMETER_VERSION "2.0.0-dev"