SOLOguide

Written for everyone. The main text assumes no technical background; anything needing a terminal is folded into a for engineers block you can skip entirely. If you are changing how SOLO works rather than using it, read the technical reference instead — contracts, schema, geometry and traps.

01The four pieces

Everything lives in the cloud except the display itself. There is no server to maintain and no machine that has to stay switched on at home.

02Quick start — a number on a screen

1. Create a slot. In Console, fill in "Add or update a slot". A slot is one metric: give it a short name like signups and a label like "signups today".
2. Give it a number. Either pick a source in Panel and let the hub fetch it for you — GitHub review queues work out of the box — or push the value in from a scheduled job or workflow tool. See Getting data in.
3. Link a display. Power on a module (or open the simulator). It shows a six-character code. Type that code into the Console's Devices section and pick the slot.
4. Choose how it looks. Open Panel to pick a layout, turn the progress ring on, and set the text around the number.

The display updates on its own from then on. To show something else, change it in the console — you never touch the device.

03Slots — deciding what to show

A slot is one metric. It holds the current value plus everything that describes the data. Anything describing one screen lives on the device instead, in Panel.

curl -X POST https://solo-hub.joachim-609.workers.dev/admin/slots \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"signups","label":"signups today","units":"",
       "decimals":0,"source":"webhook","warm":null,"hot":null,
       "stale_seconds":7200,"ring_max":null}'

04Getting data in

Let the hub fetch it — the simplest option

Open Panel. The Source row shows where the number comes from today — a vendor mark, and whether it is pulled by the hub or pushed in from outside. Click Change, pick a source, fill in its fields, choose how often to check, and save. That is the whole setup: nothing to install, no workflow file, no key to hand out. Check now fetches immediately so you know it works before you walk away.

If a source needs credentials the hub does not have yet, the picker says so instead of failing quietly five minutes later. When a check fails, Panel shows the reason the source gave — "no such repo, or the token cannot see it" — and the display keeps its last good number and goes stale rather than dropping to zero.

Push — for anything not in that list

Anything that can make a web request on a schedule can feed a slot: a GitHub Action, a hosted automation tool like n8n Cloud or Zapier, or a script on a server you already have. It sends one number; the hub stores it. Leave the source picker on "pushed in from outside".

You'll need the ingest key — a password that only lets a service write values, so you can hand it to an automation without giving away control of the console.

By hand

Panel can push a value straight into the slot, which is the quickest way to prove the chain works. It can also switch one display to debug and drive it with a slider without touching the real data at all.

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

05Connecting a display

A new display knows nothing about you. The first time it reaches the hub it is given a six-character code, which it shows on screen. Typing that code into the console is what links the two.

1. Power on the module. After it joins wifi it shows claim code and six characters.
2. In Console → Devices, enter the code and the slot name.
3. Press Claim device. Within a few seconds the display switches to your metric.

Codes avoid easily-confused characters — no letter O or digit 0, no letter I or digit 1.

06Reading the panel

The display has four states. Knowing them makes most problems self-diagnosing.

The colour of the number

• Green — below your warm threshold
• Amber — at or above warm
• Red — at or above hot
• White — no thresholds set
• Grey — the value is stale

The ring around the edge

The ring is a progress ring: it sweeps clockwise from twelve o'clock in proportion to value ÷ ring max, so a half circle means half way. Turn it on per display in Panel and set the ring max on the slot. No ring max, no ring.

"stale"

The word stale appears, and the number turns grey, when the value is older than expected. The display is fine — something upstream has stopped sending.

07Layouts, art and debug

Everything in this section is set per display in Panel, so two panels can show the same slot completely differently.

Debug mode stops one display listening to its source and lets you drive it by hand with a number box and a slider. It writes nothing to the slot and nothing to history, so it cannot corrupt the real series — switching back to Live needs no cleanup.

08Troubleshooting

09Known limits

An honest list, so nobody loses an afternoon to it.

• One number per screen (two, stacked, with frac). That is the design, not an oversight.
• Colour thresholds only work one way — bigger is worse. Higher-is-better metrics should leave them blank.
• The progress ring is red at every percentage, and it has no colour bands of its own.
• The 24-hour comparison is unreliable near zero, because it is a percentage of yesterday.
• History is 48 hours. Older readings are deleted automatically. SOLO is a right-now display, not an analytics tool.
• Text must be short. Around 17 characters fit across the glass, and long text also eats into the device's payload budget.