Stats docs

How Stats works

Stats is organised in a few pieces, from the data to the people who see it.

Workspace

Your things, screens and links, kept apart from your other workspaces.

Thing

Something real you keep an eye on: a machine, a freezer, a room, a computer. It has properties, a history and a Card.

Property

One live value of a thing, like temp or door, created the first time a device sends it.

Device

Whatever reports for a thing: a Raspberry Pi, a gateway, a PLC, a script.

Screen

Widgets showing the live values and history of a workspace's things.

Live link

A screen or a Card for anyone with its address, read-only.

Display

Screens from any of your workspaces, in turn, on one or more TVs.

Get started

1. 1 Create an account with a password or with Google, confirm your email and accept the terms.
2. 2 Wait for approval: an admin reviews every new account, and you get an email once it's done.
3. 3 Create a workspace on the Workspaces page: a place of its own for things, screens and links.
4. 4 Add a thing to the workspace, then a device on the thing's page, and connect it as below.

Connect a device

A device asks Stats for a token, then reports straight to Stats' live service. It needs HTTPS and JSON, nothing else: no agent, no SDK, no open port.

1. Claim the device

Adding a device on its thing's page shows a claim code, once. It works one time, for 24 hours; case and dashes don't matter. The device trades it for its secret, which is also shown only once: keep it on the device.

curl -X POST https://stats.thuum.dev/device/claim \
  -H 'content-type: application/json' \
  -d '{"code": "ABCD-EFGH"}'

# 201 {"secret": "<80 hex characters>", "token_url": "https://stats.thuum.dev/device/token"}

2. Get a token

Trade the secret for a token whenever you need one. It lasts an hour and reaches only this device's own thing: it may write its live values and add to its history, nothing else.

curl -X POST https://stats.thuum.dev/device/token \
  -H 'authorization: Bearer <secret>' \
  -H 'content-type: application/json' -d '{}'

# 200 {"api_url": "…", "domain": "…", "token": "…", "expires_in": 3600,
#      "state_topic": "thing:…", "history_topic": "history:…"}

3. Report

Set each property's live value, then add the whole report to the thing's history as one reading event. Screens update at once; charts and timelines read the history.

# From the token's answer
API=<api_url> DOMAIN=<domain> TOKEN=<token>
STATE=<state_topic> HISTORY=<history_topic>

# Each property's live value
curl -X PUT "$API/api/$DOMAIN/state/data/$STATE/temp" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"value": 4.2}'

# Then the whole report, on the thing's history
curl -X POST "$API/api/$DOMAIN/event/data/$HISTORY" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"type": "reading", "data": {"temp": 4.2, "door": "closed"}}'

Ready-made recipes

Two scripts do all of the above. The device's box on the thing's page shows them with its claim code filled in.

curl -fsSO https://stats.thuum.dev/recipes/stats-report.py
STATS_URL=https://stats.thuum.dev STATS_CLAIM_CODE=ABCD-EFGH python3 stats-report.py

curl -fsSO https://stats.thuum.dev/recipes/stats-report.sh
STATS_URL=https://stats.thuum.dev sh stats-report.sh claim ABCD-EFGH
sh stats-report.sh report temp=4.2 door=closed

Properties and ranges

A property appears the first time a device reports it. On the thing's page, give it a label and a unit, and if you like, its ranges. Each side of a range is optional.

• Normal range: outside it, widgets show a warning, in amber with ▲ or ▼.
• Specification: outside it, an error, in red.
• Target: a fixed number, or another property's live value, drawn as a neutral mark.
• Deadband: once outside a limit, a value counts as back only when it's that far inside again, so a noisy value stops flickering between colours.

Every value shows its age. Past a widget's "Old after" (5 minutes unless you change it) it turns amber with ⚠, and an old value never raises an alarm.

Screens and widgets

A screen is a grid of widgets over up to 10 things of a workspace. It's what live links, embeds, kiosks, badges and displays show.

Open a screen, then Edit: add, change, move and remove widgets, with a live preview below. Each widget takes 1 to 4 columns and may have its own title.

Each widget below is the real one, live over simulated readings: a press, a cold room, a freezer running warm and a sensor gone quiet. See them on example screens, and in your own brand, in the showcase →

Live links

On a screen's page, Live links creates an address anyone can open: read-only, no account, no cookie. Give it a label and an expiry: one hour, one day, 7 or 30 days, or never.

The address is shown once, with its QR code and snippets ready to copy. Stats keeps only a fingerprint of it: if it's lost, create another.

<iframe src="https://stats.thuum.dev/l/<token>/embed" width="800" height="450" style="border:0" title="Thuum Stats"></iframe>

Turn a link off or delete it, and new viewers get nothing at once. A page already open keeps showing until it reloads.

Cards and stickers

Every thing has a Card: the page people see when they scan its sticker, made for phones. Open it with the Card button on the thing's page; a live preview shows it as viewers will.

• Nameplate: the thing's name and kind, up to 20 "Label: value" lines, a note, and the next due date with what is due. It turns amber 30 days before and red once overdue.
• Live strip: every property of the thing, with its age, as on a screen.
• Journal: notes, inspections (passed or failed) and maintenance, recorded from your account. Viewers see it as recorded by the owner, never a name.
• Files: photos and documents in JPEG, PNG, WebP or PDF, up to 5 MB each and 20 per thing. The first photo opens the Card.

Create a card link and Stats shows a sticker ready to print: the QR code, the thing's name and a line inviting people to scan it.

Displays

A display shows your screens on a TV, one at a time, fitted to the screen, with a status strip of every screen's worst state and since when. The TV needs a browser and nothing else.

• Create it on the Displays page, add up to 20 screens from any of your workspaces in order, and choose how long each one stays.
• Each TV gets its own address, shown once. Replace one without cutting off the others; turned off or expired, a TV says so within 30 seconds.
• On the TV: → or PageDown for next, ← or PageUp for previous, Space to stay or resume. Every manual change ends by itself.
• Control it from a desk or a phone: previous, next, stay, or show a screen for a while or until a time. The wall answers within seconds.

Your brand

On the Your brand page (from Workspaces), set a name, a logo, a main and an accent colour, light, dark or the viewer's choice, and whether to hide the Thuum Stats mark. A live preview shows the result as viewers will see it.

Logo: PNG, JPEG or WebP, up to 1 MB.

Your brand applies to everything you share: live links, embeds, kiosks, Cards and their stickers. Your own pages keep Stats' look.

Limits

Limits keep Stats quick for everyone during early access. They guard against mistakes and abuse; they are not price tiers.