Cherry-picks the macOS-specific pieces from PR #5: Python daemon using
bleak (CoreBluetooth backend), LaunchAgent template, flash-mac.sh, and
install-mac.sh. Token is read from the macOS Keychain ("Claude
Code-credentials" service); Linux behavior is unchanged. README split
into "macOS installation" and "Linux installation" sections with
parallel Flash / Pair / Install subsections.
Co-Authored-By: Chris Davidson <36679917+lorddavidson@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
GitHub's clickable-thumbnail trick worked but was awkward; a 500x500
12fps GIF renders inline everywhere. Drop the now-unused thumbnail.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
GitHub strips relative src on <video> tags, so swap to an image link
pointing at the raw mp4. Extracted a frame for the thumbnail so the
two demo cells aren't visually identical.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace the 480x320 Panlee-era usage/bluetooth/controller PNGs with
fresh 480x480 captures of the current UI (Usage, Bluetooth, Splash).
Drop the Controller screen column entirely — that screen was removed
when buttons took over its shortcuts.
README cleanup: daemon poll cadence corrected to 60s, splash mood-
group + auto-rotation behaviour documented, "tap the logo to cycle"
replaced with the actual middle-button gesture, Lucide section
rewritten to point at tools/png_to_lvgl.js instead of the dead inline
Python+inkscape recipe, and intro line drops "touch controller" since
touch only toggles splash now. demo.gif flagged as stale (recapture is
a hardware task).
The two panels in init_usage_screen() differed only in y-offset, pill
text, and which globals received the children — same widget tree, same
sizes, same positions. Fold into make_usage_panel() so the layout intent
shows up in two call sites instead of being duplicated by hand.
Verified by pixel-diff: pre- and post-refactor screenshots of the Usage
screen are byte-identical.
The detect-rotation/blank/redraw block and the brightness step-up block
were two stateful chunks in loop() glued by a brightness_ramp global.
Fold them into handle_rotation_change() with local static state — the
'on rotation change, flash to black then ramp back' invariant lives in
one place and the loop body shrinks.
touch_read() had two branches that both called getPoint() unconditionally
— the touch_data_ready flag served no purpose. Gate the I2C transaction
on the flag so the ISR finally pulls its weight: idle loops no longer
hit I2C, getPoint() runs only when the CST9220 actually raised the
TP_INT line.
Also scope touch_pressed/x/y to file-static (no cross-TU users) and
drop the stale 'permanent while we work on it' comment by the default
boot screen — splash-on-boot is documented in CLAUDE.md.
Six public API functions had no callers anywhere in the firmware:
splash_prev, splash_set_active, splash_current_name, splash_count,
ble_is_connected, imu_set_rotation, power_is_usb_connected,
power_usb_changed. Trimming them lets power.cpp drop the VBUS state
machine (cached_usb, usb_changed_flag, last_vbus_ms,
enableVbusVoltageMeasure). usage_rate_reset becomes file-static since
the only caller is in usage_rate.cpp itself. Montserrat font flags in
platformio.ini were enabled but never referenced.
Group splash animations into four moods (idle/normal/active/heavy) and pick
which group plays based on a 5-min sliding rate of session_pct. Thresholds
sit at 0.10/0.20/0.33 %/min so Heavy fires when usage matches or beats the
5-hour session reset pace. Splash auto-rotates within the current group
every 20s; group recomputes on every BLE poll and the splash re-picks
immediately if it changes mid-display. 4-min minimum window prevents
single-sample bumps after boot from falsely landing in Heavy.
- Extract design tokens to firmware/src/theme.h (THEME_BG, THEME_PANEL,
THEME_TEXT, etc.); ui.cpp aliases COL_* to the THEME_* tokens
- Splash container + canvas COL_EMPTY now use THEME_BG / 0x0000 instead
of the hardcoded 0x0f0f0f / 0x10A2 dark grey
- tools/convert_to_c.js maps "transparent" palette entries to 0x0000
(true black) so regenerated splash_animations.h matches the new bg
- Re-regenerate splash_animations.h
- Convert logo to RGB565A8 (alpha plane) so it composites against any
background — no more grey halo around the upper-left logo on screens
where the bg differs from the previous baked-in 0x18E3 color
UX overhaul:
- Drop the Controller screen entirely (touch zones, swipe gestures, HID
gesture engine, four icon arrays, hand icon)
- Two persistent screens (Usage, Bluetooth) cycled by the middle PWR
button; splash becomes a touch-toggled welcome animation
- Left button (GPIO 0): hold to send Space (Claude Code voice-mode PTT)
- Right button (GPIO 18): press to send Shift+Tab (mode toggle)
- Middle button on splash cycles animations instead of screens
- Remove USB plug/unplug auto-switch (Controller was the unplug target)
- Hide battery indicator on splash when in LOW state — it's noisy over
the pixel-art animations
Implementation:
- Delete firmware/src/hid.{cpp,h} and touch.{cpp,h}; their roles fold
into main.cpp button handlers and LVGL CLICKED events respectively
- splash_get_root() exposes the splash container so ui.cpp can attach
a click handler for the dismiss-on-tap behavior
- Tap detection uses LVGL's built-in LV_EVENT_CLICKED with event
bubbling on the inner panels — debouncing is handled by LVGL
- On Bluetooth screen, only the Reset Bluetooth zone is clickable;
taps elsewhere are no-ops (no conflict with splash toggle)
Docs:
- README: drop Controller from screens table, rewrite Physical buttons
table, remove Gesture controls section
- CLAUDE.md: update file map, button assignments, drop gesture refs
Each gesture hint now wraps its gesture in white (COL_TEXT) and the
action in dim gray (COL_DIM), stacked vertically. Replaces the prior
single-line "Gesture: action" format that wrapped at arbitrary points.
- Drop "of current session" trailing text from the percentage label so
it no longer overlaps the right-aligned reset countdown
- Shrink hint font from styrene_24 to styrene_20 and enable WRAP mode
with center alignment so each hint fits the narrow center zone
- Shift all three titles by +16 from screen mid so they center between
the logo (right edge ~100) and battery icon (left edge ~412)
- Bluetooth screen: increase Reset zone height 70 -> 110 for breathing
room around the trash icon + label
- Bluetooth screen: drop the "Bluetooth Low Energy" footer
- Drop "Claude" prefix from titles, center all three
- Replace verbose "Current Session" / "Current Week" labels with rounded
pills above the bar; reset countdown moves below the bar
- Extend bar to fill panel inner width (was 8px short)
- Symmetric vertical pill placement within panel
- Spinner: per-frame hold times + ping-pong indexing, modeled on
Claude Code's Cavalry triangle oscillator (turn-around frames hold
~2x longer)
- Bottom spinner re-centered between weekly panel and screen edge
- screenshot.sh: 480x320 -> 480x480 for the new panel
- CLAUDE.md: document screenshot.sh + temporary boot-screen swap as
the standard self-QA workflow for UI changes
- Cache invalidation: drop ~/.config/claude-usage-monitor/ble-address and remove
the dead MAC from bluez on connect failure, so swapping ESP boards no longer
pins the daemon to a stale factory MAC
- Scan robustness: pick first matching candidate (head -1), sanity-check cached
content for valid MAC format, handle multiple Claude Controllers in bluez
- 5s tick + 60s poll: inner loop wakes every 5s for fast disconnect detection
while keeping Anthropic API cadence at one minute
- Refresh-request channel: new GATT characteristic ...0004 NOTIFY, firmware
fires once in onSubscribe when has_received_data is false; daemon subscribes
via setsid'd dbus-monitor pipeline (process group cleanup avoids the
bash-wait-on-job hang we hit on disconnect)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Full hardware swap from Panlee SC01 Plus (480×320 IPS) to Waveshare 2.16"
square AMOLED (480×480, CO5300 + CST9220 + AXP2101 + QMI8658). Library
stack moves to Arduino_GFX, SensorLib, XPowersLib on the pioarduino
platform 55.03.38-1 (Arduino Core 3.x).
UI:
- 4 screens (splash, usage, controller, bluetooth) with 3-button physical
navigation: GPIO 0 = prev, AXP PKEY = cycle, GPIO 18 = next.
- IMU-driven 90° auto-rotation. CO5300 can't rotate via MADCTL, so flush
callback does CPU strip-rotation in PARTIAL render mode. Rotation
transitions use AMOLED brightness flash (instant black → redraw → ramp).
- Battery indicator (Lucide icons) in upper-right, RGB565A8 alpha so it
blends over the splash animations.
- USB plugged/unplugged auto-switches between Usage and Controller
screens (suppressed while on splash).
- Fonts and icons re-scaled ~1.9× for the higher-DPI panel; 20px margins
to clear rounded corners.
Splash:
- 13 × 20×20 pixel-art creature animations sourced from
claudepix.vercel.app via tools/scrape_claudepix.js (scraper handles
both PRESET creature-engine and standalone FRAMES+PAL formats).
tools/convert_to_c.js emits firmware/src/splash_animations.h.
Attribution preserved in README and the generated header.
Tooling:
- tools/png_to_lvgl.js converts alpha PNGs to LVGL RGB565A8 (planar
layout, with --tint to colorize Lucide black-on-transparent sources).
- tools/scrape_claudepix.js, tools/convert_to_c.js for the splash
pipeline.
Docs:
- New worktree CLAUDE.md with hardware pin map, file inventory, build
commands, and the 8 critical gotchas (CO5300 rotation, OPI PSRAM,
pioarduino requirement, LVGL 9 font patching, centralized touch read,
even-aligned flush regions, touch swap/mirror values, RGB565A8 layout).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Move all communication from USB to BLE. The device now advertises as
"Claude Controller" and acts as both a BLE HID keyboard (for touch
gestures) and a GATT data server (for usage updates from the daemon).
- Add NimBLE-Arduino BLE module with custom GATT service + HID keyboard
- Add third screen (Bluetooth) with connection status, MAC, reset button
- Rewrite daemon in bash using bluetoothctl/busctl for BLE GATT writes
- Add screenshot capture via LVGL snapshot over serial
- Remove TinyUSB mode — normal pio upload works again
- Update README with BLE architecture, screenshots, gesture docs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two screens switchable by tapping the Claude logo:
- Usage screen: session and weekly utilization with animation
- Controller screen: touch gesture HID keyboard controls
Controller screen features:
- Lucide icons for ESC, DEL, left/right arrow buttons
- Gestures panel with hand icon header and hint list
- Session usage bar with reset timer at bottom
- Hold anywhere for voice dictation (space key)
- Hidden Ctrl+Space on logo hold
Also fixes stuck modifier keys with releaseAll() after each keystroke.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The SC01 Plus now acts as a composite USB device (CDC serial + HID keyboard).
Touch gestures on the screen send keystrokes to the computer:
- Swipe up/down: arrow keys
- Swipe right: Enter
- Swipe left: Shift+Tab (change mode in Claude Code)
- Double-tap logo: Ctrl+Space (voice mode)
- Tap and hold: Space (held while touching)
Gesture-to-key mapping is defined as a simple config table in hid.cpp.
Touch detection uses a state machine with configurable thresholds in touch.cpp.
Switches to TinyUSB composite mode (ARDUINO_USB_MODE=0). Flashing now
requires flash.sh which handles the DTR/RTS bootloader reset.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Physical desk monitor that displays Claude Code usage limits (5-hour session
and 7-day weekly utilization) on an ESP32-S3 touchscreen via USB serial.
Firmware: LVGL 9 dashboard with LovyanGFX on SC01 Plus, Anthropic brand
colors and custom fonts (Tiempos, Styrene B, DejaVu Sans Mono), Claude
spinner animation with rotating status words.
Daemon: Pure bash script that reads the Claude Code OAuth token, makes a
minimal Haiku API call, extracts usage from rate-limit response headers,
and sends JSON to the ESP32 over serial. Uses inotifywait for instant
USB plug/unplug detection.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
