SOLOreference

Two documents, one truth. SOLO-STATE.md in the repo is the operational log and the authority when anything here disagrees with it. Above that sits one rule: the firmware wins. The hub and console were regenerated after a lost session; the sketch is the genuine original, so where a contract is disputed, read solo-firmware/solo-firmware.ino.

01The shape of the system

One number, one screen. A metric is pushed (or pulled) into a slot on the hub; a device is a round panel bound to one slot, and it asks the hub every few seconds what to draw. Nothing is configured on the device itself, which is why swapping a board is just a re-claim.

02The device

Hardware

A classic ESP32 driving a GC9A01 240×240 round SPI panel over Arduino_GFX. It is the same physical board and panel as the first Desk Radar build, so the pin table below is empirical, not inferred — a wrong SCK/MOSI/DC/CS/RST presents as a black or garbled screen.

Firmware build

Libraries: Arduino_GFX, WiFiManager (tzapu), ArduinoJson, ArduinoOTA, Preferences.

arduino-cli compile --fqbn esp32:esp32:esp32:PartitionScheme=min_spiffs solo-firmware

Current image: 1,256,447 bytes — 63% of the 1,966,080-byte app partition; globals 55,192 (16%).

Lifecycle

1. Boot. Paints SOLO / hello / starting up, reads the persisted hub URL from Preferences (namespace solo, key hub).
2. WiFi. Paints wifi setup / SOLO-setup once, then blocks in WiFiManager's autoConnect("SOLO-setup"). The captive portal carries an extra field for the hub URL. Portal timeout is 300 s, after which it shows wifi / failed / restarting… and reboots.
3. Identity. Polls hubUrl + "/d/" + WiFi.macAddress() — uppercase, with colons. The hub normalises to lowercase hex with separators stripped, so 24:0A:C4:C6:03:00 and 240ac4c60300 are the same device.
4. OTA. Hostname "solo-" + last 6 of the MAC, password from the gitignored solo-secrets.h. Serviced by ArduinoOTA.handle() every loop, with an upload-progress arc drawn on the ring.
5. Loop. Fetch /d/{mac}, parse into a StaticJsonDocument<768>, redraw only when the frame signature changed, reconnect WiFi if dropped, sleep p seconds.

Anti-flicker

One lastSig string covers layout, the formatted value, its colour, the stale flag, w, and the ring bucketed to a whole percent — 1% is 3.6°, finer than drawArc's 4° dot spacing, so float jitter from the hub cannot make the panel twitch.

Staleness is decided on the device

The firmware computes stale = a > max(300, 5 × p) and ignores the slot's stale_seconds entirely. At p = 10 that is a flat 300 s. See the device contract for how the hub now steers that verdict with a synthesised a.

Claiming

On first check-in the hub mints a 6-character code from a 32-character ambiguity-free alphabet (no O/0, no I/1) and returns {"claim":true,"code":"…"}. The panel renders it and a human types it into the console. The code is stable across polls until claimed, then nulled.

03The drawing spec

Text metrics

The Adafruit GFX default font advances 6 px per character and stands 8 px tall, both multiplied by size. Everything is centred on x = 120. fitSize(s, maxW, cap) = clamp(floor(maxW / (6 × len)), 1, cap) picks the largest size that fits. centerText sets setTextWrap(false) on the device — GFX defaults wrapping on and it affects getTextBounds() too, so without it long text folds onto a second line instead of clipping like the canvas.

Colours (RGB565 → hex)

• text 0xFFFF #FFFFFF — value with no thresholds
• good 0x2E8B #29D35A — below warm
• warn 0xFD20 #FFA600 — at or above warm, and the "stale" word
• hot 0xF800 #FF0000 — at or above hot, and the ring sweep
• muted 0x5AEB #5A5D5A — labels, and the value when stale
• accent 0xFB00 #FF6100 — claim code, OTA arc
• track 0x18E3 #181C18 — the ring's unfilled track

Threshold colouring assumes higher is worse: v >= th[1] red, v >= th[0] amber, else green. th is dropped entirely unless both warm and hot are set, so the firmware can test th.isNull().

Layout geometry

Non-metric frames: claim draws a muted 1 px ring at r 114, "claim code" y 78 size 1, the code y 120 size 3 in accent, "enter in web console" y 162 size 1. Waiting draws "assigned" y 96, -- y 128 size 4, "waiting for data" y 168. Stale adds the word "stale" at y 208 size 1 in warn.

The ring

drawArc(start, sweep, r, colour, dotR) steps every 4° and stamps filled circles — it is a dotted arc, not a stroked path. The progress ring draws a 2 px track over the full 360° at r 114, then a 3 px red sweep from twelve o'clock for r / 100 × 360, skipped below 2° so a rounding artefact cannot leave a lone dot. It is red at every percentage; that is a known rough edge, not a bug.

04The hub

A single Cloudflare Worker, solo-hub, over a D1 database named solo, with a cron trigger every minute. No framework, no dependencies — the GA4 service-account JWT is signed with WebCrypto by hand. Currently rev Q (GET /health reports it, along with how many slots pull their own data).

The minute trigger is a resolution, not a cadence: since rev L each slot carries its own pull_interval and the tick only fetches what is due. A coarser trigger rounded every slot's cadence up to a multiple of itself — the old 3-minute tick delivered a 5-minute interval every 6 minutes.

Auth

Two secrets: ADMIN_KEY for everything under /admin, and INGEST_KEY for writes. The admin key also satisfies ingest, which is why the console can push a test value with the key you already gave it. Both are Bearer tokens. Comparison fails closed when either side is falsy, so an empty secret matches nothing — including an empty token.

CORS is wide open (Access-Control-Allow-Origin: *, methods GET POST PATCH PUT DELETE OPTIONS, headers Authorization Content-Type) because the console is a static page on a different origin. PATCH had to be added explicitly — without it the browser preflight fails and every device edit silently dies.

Routes

PATCH /admin/devices/:id accepts slot (name or null), layout, ring, poll_seconds (5–600), label, top_text, bottom_text, mode, dbg_value and dbg_value2. It validates the layout enum, the poll range, the mode enum strictly ("DEBUG" and true are both rejected) and that the slot exists. It exists because /admin/claim looks devices up by claim_code, which is NULL after claiming — so re-pointing a claimed panel was impossible before it.

Debug mode

Mode is per device, and so are the debug numbers. In debug the hub changes exactly four things, all read-side: v ← dbg_value ?? slot.value, w ← dbg_value2 ?? slot.value2, a ← 0, and r computed from the debug value. Nothing is written to slots or history, so a debugging session cannot corrupt the real series or skew the 24 h delta, and flipping back to live needs no cleanup. Per-column fallback is deliberate: it lets you override only the numerator of a frac. dbg_value: 0 is a real zero, not a clear — send null to clear.

The /d/ key set is byte-for-byte the same shape in both modes, which is precisely why debug mode needed no firmware change.

05The device contract — /d/{mac}

Single-letter keys, because the firmware parses into a fixed StaticJsonDocument<768>. Overrun it and deserializeJson returns NoMemory, the parse branch fails, and nothing is drawn at all — a silent freeze on the last frame rather than an error. A real claimed payload measures around 100 bytes; Panel meters every poll against 768.

The ar key (art_rev) was removed with pixel art in rev K — the Worker no longer sends it.

The split layout (firmware rev D)

Two labelled numbers side by side, divided by a vertical rule — built for an A/B pair, which frac cannot express because it draws no text at all. It needed no new wire keys: v and w are the two numbers, and t / b become the left and right labels rather than top and bottom.

Geometry: halves centred on x = 60 and x = 180 with 96 px of drawing width each, numbers at y = 104 capped at text size 5 (a 3-char number is 90 px, which just clears the rule), labels at y = 148 at size 2. The rule runs y = 66..174 rather than full height — the glass is a circle and has no corners. Thresholds colour the left number only, the same convention frac uses for its numerator.

Rotation — several faces on one panel (rev N)

A device with a rotation list cycles through it, and this is entirely hub-side: the firmware re-reads every key on every poll, so a different slot's numbers arriving is indistinguishable, to it, from that slot having changed. The /d/ key set is identical. The face is picked by wall clock (floor(now / rotate_seconds) % faces), so two panels showing the same list stay in step and a reboot resumes mid-cycle.

Three things that are easy to get wrong here:

• The served p is not poll_seconds while cycling. A device configured to poll every 180 s would sit on one face for three minutes of a 20 s rotation, so the hub serves rotate_seconds / 4 instead. Everything downstream — including the staleness encoding below — must use that value, because the firmware derives its own threshold from the p it was handed.
• It is a constant, not a countdown to the boundary. Serving "seconds until the next face" looks better and does not work: loop() sets nextPoll before it parses the response, so a new p only takes effect one cycle later and the timing would drift. A constant is immune to that lag.
• Two faces that are identical on the glass will not repaint. The redraw signature covers layout, formatted value, colour, staleness and the text each layout actually draws — so two big faces showing the same number look like rotation has stopped. Correct behaviour, surprising symptom.

A face whose slot has been deleted falls back to the device's own claimed slot rather than dropping to a claim screen, which would read as "this panel was forgotten".

Three states, not two (rev O). rotate_on = 0 draws the device's own columns and keeps the list; a face with enabled:false is kept but skipped; and if no face is active the panel falls back to its single face exactly as if cycling were off. One active face pins that face and is not "cycling", so it keeps the device's own poll rate rather than the faster rotation one.

a versus ta — read this before "fixing" either

Since rev I, a is not "the age of the value". It is "the age as the firmware must interpret it": a deliberately synthesised number whose only job is to make the firmware's own hardcoded rule stale = a > max(300, 5 × p) land on the verdict the hub has already reached from the slot's stale_seconds.

Why: the firmware's threshold is derived from its poll rate, so at p = 10 it is a flat 300 s — while a GitHub Actions cron on a five-minute schedule routinely runs several minutes late. The panel therefore read "stale" most of the day while working perfectly. Meanwhile the field that does describe the data's cadence, the slot's stale_seconds, was invisible to the panel. ta carries the truth for display.

Rev L removes the cause for pulled slots — the hub owns the schedule, so a 300 s interval is actually 300 s — but the encoding stays: a source can still fail, and the hub's verdict is still the only one that knows about stale_seconds.

The encoding, since a is thresholded and never rendered:

1. Recompute the firmware's own threshold, thr = max(300, 5 × poll_seconds).
2. Take the true age — for frac, the older of the two halves; null (never pushed) counts as stale.
3. Reach the verdict from the slot: stale = trueAge > stale_seconds.
4. Emit an a that produces that verdict — when fresh, the real age if it is already under thr, otherwise clamped safely below it; when stale, a value comfortably above thr, keeping the real age whenever that is already higher so the number stays as honest as it can.

ta is additive and REV B/C ignore unknown keys, so none of this needed a reflash.

The frac rule

For frac, /d/ reports the older of the two ages, so a half that stopped updating still shows stale. Skipped in debug, where a is pinned to 0 on purpose.

06Data model

Five tables in D1. meta is a key/value scratchpad — its only current use is caching the GA4 access token.

slots — one row per metric

devices — one row per panel

pull_log — one row per attempt (rev M)

(slot, ts, ok, value, value2, ms, err), WITHOUT ROWID, same rolling 48 h as history and pruned beside it. It exists because the two questions you actually have when a panel goes quiet were both unanswerable without it: history records only writes that succeeded and only the primary number, while slots.pull_err keeps only the most recent failure — one later success erases it, so an intermittent source left no trace at all.

Written in the same D1 batch as the slots.pull_ts/ok/err update, so the log and the current state cannot disagree. Deleting a slot deletes its log with it — there are no foreign keys, so that is explicit in the delete handler.

The console shows the last ten minutes under Source → Recent checks, fetched only while that fold is open. The gap column is computed client-side against the previous row and turns amber past 1.5x pull_interval — a missed tick is invisible any other way.

history

(slot, ts, value), WITHOUT ROWID, rolling 48 hours, pruned by the cron. It backs the 24-hour delta. Only the primary series is recorded — value2 has no history.

07Sources and history

A number reaches a slot one of two ways: it is pushed to /ingest/{slot} from outside, or the hub pulls it on a schedule. Both still work; a slot's pull_kind decides which one applies to it.

Pull — the hub fetches its own data (rev L)

Set pull_kind and pull_config on a slot and the cron fetches it every pull_interval seconds. Nothing outside Cloudflare is involved: no workflow in someone else's repo, no ingest key copied into a repo secret, and no dependence on GitHub's best-effort scheduler — which is what made the panel read stale most of the day and forced the a-as-verdict hack in rev I.

The Mixpanel fetcher re-runs the funnel rather than reading a cached number, so it gets a 45 s budget of its own where every other pull has 10 s — 2.5–5.6 s from a laptop but 16 s from the Worker, and the very first call blew through 10 s. An empty data object is treated as an error, not 0 %: it is equally what a wrong project id, the US host, or a dead window looks like. Queries go to eu.mixpanel.com; the US host answers 200 with nothing.

GET /admin/pullers is the authority on what exists — the console builds its form from it and holds no copy of the param specs, so a kind added to the Worker appears with its own fields and no console change. Adding a source means adding one entry to PULLERS.

Three deliberate refusals in the GitHub fetcher, each of which would otherwise put a plausible wrong number on the glass:

• The REST pulls list, not the search API. Search needs scopes a repo-scoped token may not have on a private repo, and answers 0 rather than failing — which reads as inbox zero.
• Past 5 pages of open PRs it throws instead of reporting a truncated count.
• A failed pull writes no value. The last good number and its ts stay put, the panel ages out through stale_seconds, and the reason lands in pull_err where the console shows it. A zero would look like real data.

Reviews requested via a team land in requested_teams and are not counted — the same limitation the Actions workflow had, kept so the two agree.

Push — /ingest/{slot}

curl -fsS -X POST https://solo-hub.joachim-609.workers.dev/ingest/prs \
  -H "Authorization: Bearer $INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": 3, "value2": 12}'

Use -f. Without it curl exits 0 on a 401 and you get a green build with a panel quietly going stale — the worst failure mode there is. An optional "ts" (unix seconds) backfills. Every write appends a history row.

A pull that fails is caught per slot, so one broken source never stops the others or the history prune. Before a source's secret exists its slot simply logs pull … failed: GITHUB_TOKEN is not set on the Worker every interval — expected, not a fault.

The prune (history and pull_log, batched) runs on the ten-minute marks only. At a minute-by-minute tick, running two whole-table deletes every time would be ten times the D1 writes for no benefit.

The 24-hour delta is a percentage of yesterday's value, so metrics that sit near zero produce wild figures. Expected, not a bug.

08Pixel art removed

32×32, one 4-bit palette index per pixel, two pixels per byte, first pixel in the HIGH nibble, row-major, rows byte-aligned at row × 16 → exactly 512 bytes. Drawn as 7×7 px cells at x = 8 + col×7, y = 8 + row×7 — 224 px centred on the 240 px panel.

The 512 bytes never travel through JSON. /d/ carries only ar (the art_rev) and only for art-layout devices; the device re-fetches GET /art/{mac} — raw bytes, no auth — whenever that number changes. The palette is the firmware's own 16 colours; the full table with RGB565 values and a golden test vector is in ART-CONTRACT.md.

The panel is circular: 100 of the 1024 cells are fully invisible and 68 are clipped. dims them and shows a live "off glass" count.

09The console

Static HTML on Cloudflare Pages — no build step, no CDN, no webfonts. One shared stylesheet, solo.css, linked relatively; the directory is served as-is.

Admin key handling. Panel and Art keep it in localStorage under solo_admin_key, so it is entered once per browser and re-enterable with the Key button. Console keeps it in the form only, for that tab. Nothing is ever put in a URL.

Dirty-state saves. Panel remembers each row exactly as the hub gave it, enables Save only on a real difference, marks changed fields, and sends only the changed keys. A 15-second background reconcile adopts hub-side changes when the form is clean and raises a conflict banner when it is not — because the alternative is a form left open for an hour writing a stale poll_seconds back over reality.

10Operating it

Always invoke wrangler through the local binary — a bare wrangler is not installed, and pnpm wrangler fails on a freshness check.

# hub
./node_modules/.bin/wrangler deploy

# console
./node_modules/.bin/wrangler pages deploy console \
  --project-name solo-console --branch main

# schema / migrations — --remote is load-bearing
./node_modules/.bin/wrangler d1 execute solo --remote --file=solo-hub-schema.sql

# firmware, over the air; the board only needs USB power
arduino-cli upload -p solo-c60300.local --protocol network \
  --fqbn esp32:esp32:esp32:PartitionScheme=min_spiffs solo-firmware

Secrets

Keys live outside the repo in ~/.solo-admin-key, ~/.solo-ingest-key and ~/.solo-ota-password (mode 600). The OTA password is inlined into the sketch at build time through solo-firmware/solo-secrets.h, which is gitignored — a fresh clone will not compile until you recreate it.

Repo layout

11Traps

Each of these cost real time at least once. They are worth reading before debugging anything that "should" work.