From 1f739d02671ba35f46848c5a007f4dd28a3cefeb Mon Sep 17 00:00:00 2001
From: wenil <i@wenil.ru>
Date: Sat, 20 Jun 2026 12:51:14 +0300
Subject: [PATCH] docs: document the Waveshare AMOLED-2.06 board port

Add docs/boards/waveshare-amoled-2.06.md (pins, CO5300 col offset 22,
Windows UTF-8 flashing gotcha, daemon name + address fixes) and list the
board in README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                            |  1 +
 docs/boards/waveshare-amoled-2.06.md | 70 ++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 docs/boards/waveshare-amoled-2.06.md

diff --git a/README.md b/README.md
index 749b957..b058989 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ Boards supported out of the box:
 - [Waveshare ESP32-S3-Touch-AMOLED-2.16](https://www.waveshare.com/esp32-s3-touch-amoled-2.16.htm?&aff_id=149786)
 - [Waveshare ESP32-C6-Touch-AMOLED-2.16](https://www.waveshare.com/esp32-c6-touch-amoled-2.16.htm?&aff_id=149786) 
 - [Waveshare ESP32-S3-Touch-AMOLED-1.8](https://www.waveshare.com/esp32-s3-touch-amoled-1.8.htm?&aff_id=149786)
+- [Waveshare ESP32-S3-Touch-AMOLED-2.06](https://www.waveshare.com/esp32-s3-touch-amoled-2.06.htm) (watch form factor, 410×502) — env `waveshare_amoled_206`, see [`docs/boards/waveshare-amoled-2.06.md`](docs/boards/waveshare-amoled-2.06.md)
 
 > Please check if a pull request exists for your alternative hardware port before opening a new one, providing QA feedback and testing on the same hardware is more valuable than duplicate pull requests.
 
diff --git a/docs/boards/waveshare-amoled-2.06.md b/docs/boards/waveshare-amoled-2.06.md
new file mode 100644
index 0000000..0b516a4
--- /dev/null
+++ b/docs/boards/waveshare-amoled-2.06.md
@@ -0,0 +1,70 @@
+# Waveshare ESP32-S3-Touch-AMOLED-2.06 (watch)
+
+Port of Clawdmeter to the [Waveshare ESP32-S3-Touch-AMOLED-2.06](https://www.waveshare.com/esp32-s3-touch-amoled-2.06.htm)
+smartwatch dev board. PlatformIO env: **`waveshare_amoled_206`**.
+
+This board shares its display controller (CO5300), PMU (AXP2101), IMU
+(QMI8658) and I²C bus with the existing 2.16 / 1.8 ports, so the port mostly
+combines drivers already in the tree: the CO5300 display path from the 2.16
+board and the FocalTech inline touch reader from the 1.8 board.
+
+## Hardware
+
+| Block | Part | Pins |
+|-------|------|------|
+| Display | CO5300 AMOLED, **410×502**, QSPI | CS=12, SCLK=11, D0–D3=4/5/6/7, RESET=8, TE=13 |
+| Touch | FT3168 (FocalTech), I²C @ 0x38 | INT=38, RST=9 |
+| PMU | AXP2101, I²C @ 0x34 | battery, USB VBUS |
+| IMU | QMI8658, I²C @ 0x6B | INT=21 (rotation disabled) |
+| RTC | PCF85063 | on I²C bus |
+| I²C bus | shared | SDA=15, SCL=14 |
+| Buttons | BOOT (Space/PTT) / PWR (screens, brightness, pairing) | BOOT=0, PWR=10 |
+
+Fixed orientation (non-square panel — IMU auto-rotation is off). Display power
+comes from the AXP2101 rail and needs no explicit enable (same as the 2.16
+board); if a future panel revision boots dark, see the commented AXP rail-enable
+block in `power.cpp`.
+
+### Display column offset
+
+The CO5300 GRAM is wider than the 410 px active area, so the image needs a
+horizontal start offset or a band of uninitialised memory shows on the right:
+
+```c
+#define CO5300_COL_OFFSET  22   // board.h — verified on this panel
+```
+
+## Build & flash
+
+```bash
+pio run -e waveshare_amoled_206
+pio run -e waveshare_amoled_206 -t upload --upload-port <PORT>   # COMx / /dev/ttyACM0 / /dev/cu.usbmodem*
+```
+
+### Windows flashing gotcha
+
+esptool's progress output crashes the upload on a non-UTF-8 Windows console
+(`UnicodeEncodeError`, cp1251). Force UTF-8 before running `pio`:
+
+```powershell
+$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"
+pio run -e waveshare_amoled_206 -t upload --upload-port COM7
+```
+
+## Host daemon notes
+
+The device advertises as **`Clawdmeter`** (matching `firmware/src/ble.cpp`).
+
+Two Windows-daemon fixes ship with this port:
+
+1. `daemon/claude_usage_daemon_windows.py` scans for `Clawdmeter` (the upstream
+   value `Claude Controller` never matched the firmware name).
+2. Once the device is bonded as a BLE HID keyboard, Windows keeps it connected
+   and it stops advertising, so a name scan can't find it. Set
+   `CLAWDMETER_ADDRESS` to its BLE address to connect directly:
+
+   ```powershell
+   setx CLAWDMETER_ADDRESS "<AA:BB:CC:DD:EE:FF>"
+   ```
+
+   The BLE address is the chip MAC (from `esptool ... flash_id`) **+1**.