diff --git a/Ecosystem.md b/Ecosystem.md new file mode 100644 index 0000000..216b382 --- /dev/null +++ b/Ecosystem.md @@ -0,0 +1,209 @@ +# Ecosystem + +Survey of prior art relevant to claude-gauge, captured during initial +research in April 2026. Establishes what exists, what to borrow, and +where claude-gauge can uniquely contribute. + +## Direct cousins + +Projects that do essentially the same thing claude-gauge does: a +software metric driving a physical analog needle cluster. + +### Liam Jackson — CI Test Tachometer Dashboard + +The closest cousin. Three universal motorcycle tachometers wired to +an Arduino, displaying continuous-integration test failure counts in +real time. OLED in the center for context numbers. + +* Hardware: sub-$10 motorcycle tachs, Arduino, 3D-printed housing +* Signal: frequency-based PWM (1000 RPM = 16.66 Hz), "Slow PWM" + library +* Power: several hundred mA at high deflection +* Source: Printables STL for the housing, code inline in the + Hackaday writeup +* Reference: [Putting Cheap Motorcycle Tachometers To Work](https://hackaday.com/2025/01/18/putting-cheap-motorcycle-tachometers-to-work/) + +### John McLear — AstraDash (Astra GTE -> Home Assistant) + +Repurposed Astra GTE car dashboard driven by ESP32 showing Home +Assistant sensor data. Every 5 s, MQTT pushes a JSON payload +(`{oilTemp, battery, coolantTemp, fuelLevel, rpm, speedo}`) that gets +mapped arbitrarily to home metrics. EV charge becomes fuel level, +task count becomes speedometer, solar output becomes RPM. + +* Hardware: Astra GTE cluster, ESP32 NodeMCU-32S, bit-banged SPI +* Integration: MQTT via Home Assistant +* Source: [DNThomas/AstraDash](https://github.com/DNThomas/AstraDash) +* Article: [A Dashboard Outside The Car](https://hackaday.com/2024/01/11/a-dashboard-outside-the-car/) + +Lesson: the `/usage` JSON shape we designed for the firmware is the +same abstraction McLear uses. Validates the architecture. + +### Evan — Kegerator Gauge Cluster + +Salvaged Chevy cluster driving analog meters that show beer temp and +"fuel" (keg volume). Pressure sensors on a scale beneath the keg, +plus a flow sensor on the tap line. LEDs for drama during pour +events. + +* Pattern: automotive cluster as purpose-built hobby display +* Reference: listed on Hackaday under the gauge-cluster tag + +### Steampunk voltmeter projects + +Widespread Home Assistant community pattern: repurpose vintage +voltmeters as ambient displays via ESPHome. PWM driven through an RC +low-pass filter to smooth the needle. Used for tank levels, battery +state, network load, etc. + +* Pattern: ESPHome + vintage meter body = instant Home Assistant + integration +* Reference: Home Assistant community threads on MQTT DC voltmeters, + analog gauge dashboards + +## Adjacent projects + +Same hardware pattern (ESP32 + display + metric), different data or +display choice. + +### Ecasti — PrometheusClient + +Probably the most interesting adjacency. ESP32 pulls from Prometheus +via HTTP and renders time-series graphs, gauge displays, and stat +panels on integrated LCDs (M5Stack Tab5 / AtomS3 / CoreS3). Supports +HTTPS and Grafana Cloud. Apache-2.0. + +Studying the HTTP query loop and caching patterns saves real +daemon-design time. The digital cousin of claude-gauge; swap the +displays for steppers and you're at claude-gauge. + +Source: [ecasti-gmail-com/PrometheusClient](https://github.com/ecasti-gmail-com/PrometheusClient) +Article: [Prometheus Dashboards on ESP32](https://www.hackster.io/ecasti/prometheus-dasboards-on-esp32-d590db) + +### r00li — CarCluster + +Drives real automotive instrument clusters from a PC via ESP32. +Primary use case: driving simulators (Assetto, Forza). Bit-bangs SPI +to the target cluster. + +Source: [r00li/CarCluster](https://github.com/r00li/CarCluster) + +### YouTube / Twitch subscriber counters + +Pattern well-represented but exclusively digital: MAX7219 matrices, +OLEDs, 7-segment. No physical-needle variants found. Example: +[joeybab3/Live-Subscriber-Counter](https://github.com/joeybab3/Live-Subscriber-Counter). + +### Bitcoin / crypto tickers + +Similarly digital-only. OLED + API fetch every N seconds. A GitHub +project [sandman72/ESP32_BitcoinMeter](https://github.com/sandman72/ESP32_BitcoinMeter) +hints at a meter variant but isn't widely built. + +### Classic-car instrument restorations (Triumph GT6, Alfa Giuletta) + +Replace mechanical gauges with LCD. Different problem shape; not +applicable. + +## Hardware building blocks + +### SwitecX25 driver library + +The canonical Arduino library for X25, X27.168, VID28, VID29, +BKA30D-R5 steppers. Direct GPIO, no external driver IC strictly +required (though ULN2003A recommended for cleaner current). + +Source: [clearwater/SwitecX25](https://github.com/clearwater/SwitecX25) + +### Reference Arduino X27 build + +Full working Arduino code and wiring for X27 stepper + OLED overlay. + +Source: [nsocwx/Digital-Speedometer](https://github.com/nsocwx/Digital-Speedometer) + +### TheRengineer Analog Gauge Stepper Motor PCB + +Pre-made driver board for X27.168 / VID28 with JST connectors. +Skips the breadboard stage. + +Source: [Tindie listing](https://www.tindie.com/products/TheRengineer/analog-gauge-stepper-motor-pcb-only/) + +### Universal motorcycle tachometers + +$5-10 on overseas retailers. 12 V nominal but respond to 5 V logic. +Frequency-driven (1000 RPM = 16.66 Hz). Larger and more visually +readable at desk distance than X27.168. Good V1 prototype path. + +### Vintage analog voltmeters + +Etsy listings for Bakelite-body industrial voltmeters, steampunk +aesthetic ready. Typical $10-30. Drill for wiring, repurpose the +movement, done. + +## Middleware and framework options + +### ESPHome + +Home-Assistant-native framework for driving PWM-controlled analog +meters. If the claude-gauge daemon exposes a Home Assistant sensor, +ESPHome handles the firmware layer automatically. + +Trade-off: less firmware control, faster path to a moving needle. +Worth prototyping on. + +### Grafana Labs dashboard 25052 + +Pre-built Claude Code metrics dashboard. Free deep-stats surface for +architecture A. Import against Prometheus; done. + +### Anthropic `claude-code-monitoring-guide` + +Official reference Docker Compose stack: OTEL collector + Prometheus ++ Grafana. Borrow wholesale for architecture A. + +Source: [anthropics/claude-code-monitoring-guide](https://github.com/anthropics/claude-code-monitoring-guide) + +## Aesthetic references + +* **Retro-futuristic automobile control panel** (Hackaday.io project 10579): 1960s dashboard with modern guts. +* **Daniel Lazo's Retro Digital Dashboards** (Behance): art direction for cluster visuals. +* **Dieselpunk cellphone** (Make Magazine): aesthetic coherence lesson. +* **Bakelite industrial voltmeters** (Etsy): housing reuse options. + +## Curated lists checked + +* [obazoud/awesome-dashboard](https://github.com/obazoud/awesome-dashboard) — software dashboards +* [pfalcon/awesome-smarthome](https://github.com/pfalcon/awesome-smarthome) — smart home ecosystem +* [GitHub ambient-display topic](https://github.com/topics/ambient-display) — mostly e-ink + +Physical-gauge variants are under-represented in curated lists, +which itself is a signal. + +## Where claude-gauge uniquely contributes + +| Axis | State of the world | claude-gauge angle | +|---|---|---| +| Data source | HA, CI, kegerator, car sim, crypto | LLM telemetry (first) | +| Gauge metric | RPM, temp, fuel, voltage, follower count | Thinking-to-output ratio (novel) | +| Cluster semantics | Repurposed car cluster w/ mental legend | Purpose-built for token flow (new) | +| Model indicator | n/a | Discrete annunciator for active model (new) | +| Data path portability | Locked to one source | Dual-architecture (OTEL or ccusage) | +| Enclosure | One-off bespoke | Open, printable, replicable | +| Character metrics | n/a | Em-dash violator counter, phrase extractor | +| Physical observability framing | Implicit | Explicit "make AI work tangible" | + +## What to borrow + +1. **Motorcycle tachometers** as the V1 prototype hardware. Ship a + working needle in a weekend before committing to X27.168. +2. **McLear's JSON-over-MQTT payload abstraction**. Confirms the + firmware contract is right. +3. **Ecasti's PrometheusClient** HTTP query loop and caching patterns. + Lift directly for the daemon. +4. **TheRengineer's driver PCB** to skip X27.168 breadboarding. +5. **ESPHome firmware** as a shortcut path; fall back to hand-rolled + Arduino only if needed. +6. **Vintage Bakelite voltmeter case** from Etsy: one industrial box + housing all four needles, drilled ports. Instant aesthetic win. +7. **Grafana dashboard 25052** verbatim for architecture A's deep + stats. diff --git a/Home.md b/Home.md index 699e52e..0ca914b 100644 --- a/Home.md +++ b/Home.md @@ -22,9 +22,11 @@ the ambient summary. `ccusage` integration for B, Claude Code env vars * [Hardware](Hardware) — cluster layout, X27.168 steppers, ESP32 wiring, firmware structure, enclosure +* [Ecosystem](Ecosystem) — prior-art survey, what to borrow, where + claude-gauge uniquely contributes * [Roadmap](Roadmap) — phases, shipped, deferred -* [Ideas](Ideas) — exotic variants, metrics brainstorm, parked - thoughts +* [Ideas](Ideas) — exotic enclosure variants, unique-angle + shortlist, metrics brainstorm ## At a glance diff --git a/Ideas.md b/Ideas.md index ea1eff4..fd07280 100644 --- a/Ideas.md +++ b/Ideas.md @@ -149,22 +149,69 @@ lands on Grafana panels or a custom web page later. * Fitbit / health data: Claude usage vs heart rate (do you actually stress out when Claude is slow?) -## Hardware wild ideas +## Unique-angle shortlist -* **Audio feedback**: a quiet relay-click when the tach crosses - redline; a chime when a 5h block resets. Could be annoying; - prototype with speaker off first. -* **Tactile feedback**: a small vibration motor in the bezel that - pulses when STALL lights (useful if the cluster is out of your - peripheral vision). -* **Per-project LEDs**: a strip beside the cluster where the lit - LED indicates which project is currently active. Fun for homelab - archaeology. -* **Second cluster on the other monitor** showing a 24-hour sparkline - rather than live gauges. Historical companion. -* **Cluster-to-cluster sync**: if claude-gauge becomes popular enough - to build for friends, a single OTEL collector could drive multiple - clusters in multiple homes. Niche but fun. +Directions other projects haven't taken. Each plays on the dual +nature of a cluster: always-on display AND potential input surface. + +### Physical model-selector knob + +Rotary encoder mounted on the bezel that forces the model for the +next prompt. Turn clockwise through Haiku, Sonnet, Opus; click to +lock. The MODEL annunciator LED preview-lights while turning, +solid-lights once the next prompt lands. + +Turns the cluster into an input device, not just a display. No +prior art. + +### Swappable faces per mode + +Gauge faces are magnetic and swap in under a minute. "Scientific" +mode has numbered scales; "Brand" mode has model logos; "Mood" mode +is colour-coded emotional labels; "Seasonal" mode is themed. Same +needles, different semantics. Conference demo catnip. + +### Daily reset chime + +Real brass bell or solenoid click when a 5h block resets. Pavlov +for token management. Off by default; opt in per-user. + +### Tactile feedback + +Small vibration motor in the bezel that pulses when STALL lights. +Covers the "is Claude alive" question when the cluster is out of +peripheral view. + +### Per-project LED strip + +RGB strip beside the cluster; the lit section indicates which +project is currently active. Turns the desk into an ambient +work-location indicator for ADHD self-awareness. + +### Cluster-to-cluster sync over LAN + +If claude-gauge ships to friends, multiple clusters around the +country sync to a shared OTEL collector showing aggregate usage. +"Claude Code Live" art piece. + +### Physical commit button + +Satisfying mechanical clicky on the cluster bezel that triggers a +pre-composed `git commit` in the current project. Cluster as input +AND output. Dangerous, fun, on-brand. Requires daemon-side +permission gating. + +### Audio feedback (optional) + +Quiet relay click when the tach crosses redline; chime when a 5h +block resets. Off by default. Some users will love it, some will +throw the cluster out a window. Make it a toggle. + +### Second cluster as historical companion + +A second, smaller cluster on the other monitor rendering a 24-hour +sparkline rather than live gauges. Paired-instrument aesthetic. +Overkill for one user, charming for an office. ## Software wild ideas