Reference
slowhub reference
The slowhub.toml keys, the hub's files and sockets, its service, its commands and its HTTP endpoints.
How the hub behaves is explained on slowhub, and how it is built on Hub internals. In configuration keys, paths and commands, a slowapp is called an app.
Configuration file (slowhub.toml)
/etc/slowhub/slowhub.toml. Every key has a default; this is a Slowboard 1085’s file, without its apps. Restart slowhub after editing it.
state_dir = "/var/lib/slowhub"
# run_dir defaults to /run/user/<uid>/sb (runs/, ctl/, <app>/ui.sock, admin.sock).
device_socket = "/run/slowhub/device.sock"
device_user = "slowd" # the user allowed on the local screen socket
listen_web = "0.0.0.0:8080"
# listen_device_tcp = "0.0.0.0:8090" # screens on other machines (tokens: slowhub device add)
host_allow = ["slowboard", "slowboard.local", "192.168.1.50"]
web_url = "http://192.168.1.50:8080/"
[probe]
target = "1.1.1.1:443"
[budget]
spike_reserve_mb = 64
os_reserve_mb = 48
ui_reserve_mb = 25
[planner]
overlap = false
| Key | Meaning |
|---|---|
state_dir | The database, card files and app data |
run_dir | Run output, app page sockets and the admin socket |
device_socket, device_user | The socket for a slowd on the same machine, and the user allowed on it |
listen_web | The hub’s web address |
listen_device_tcp | Optional: the address screens on other machines connect to, with a token |
host_allow | Host names allowed in requests to any TCP listener: exact names, any case. IP addresses and localhost always pass |
web_url | The address a Slowboard shows in its “connected” QR code |
[probe] target | The host and port used to check that the internet is reachable |
[budget] | Memory kept back from apps: spike_reserve_mb, os_reserve_mb, ui_reserve_mb |
[planner] overlap | Allow two jobs at once when both fit in memory |
[[app]] | One per installed app; see below |
[[app]]
[[app]]
id = "reminders"
runner = "podman"
manifest = "/opt/slowboard/apps/reminders/slowapp.toml"
image = "ghcr.io/mike-anderson/slowapp-reminders@sha256:…"
| Key | Meaning |
|---|---|
id | The app’s id, matching its manifest |
runner | podman for a slowapp image |
manifest | Path to the app’s slowapp.toml |
image | The image, pinned by digest |
Install a slowapp walks through adding one.
Files and sockets
| Path | Contents |
|---|---|
/var/lib/slowhub/hub.db | SQLite: screens, configs, apps, runs, feeds, bundles, events |
/var/lib/slowhub/blobs/ | Card pictures, each written once |
/var/lib/slowhub/apps/<id>/data | Each app’s /data |
/run/slowhub/device.sock | The protocol, for a slowd on the same machine (directory 2750 epaper:slowd, socket 0660) |
/run/user/<uid>/sb/admin.sock | The admin socket, used by the slowhub commands |
/run/user/<uid>/sb/<id>/ui.sock | An app’s web page |
/run/user/<uid>/sb/runs/<run>/out | A run’s output, deleted after it is stored |
Service
slowhub.service is a systemd user unit, installed in /etc/systemd/user/ and enabled for the hub’s user (epaper on a Slowboard 1085), who has linger so the service runs without anyone logged in.
- It needs
dbus-user-session, so Podman’s memory limits really apply to containers. - It runs
/opt/slowboard/bin/slowhub --config /etc/slowhub/slowhub.toml serve. Restart=always,StartLimitIntervalSec=300,StartLimitBurst=10.MemoryHigh=96M,MemoryMax=128M. The unit also holds the Podman commands it runs, which is why the limit is well above the hub’s own use.
CLI
The commands talk to the admin socket, so run them as the hub’s user:
runuser -u epaper -- env XDG_RUNTIME_DIR=/run/user/$(id -u epaper) \
/opt/slowboard/bin/slowhub --config /etc/slowhub/slowhub.toml COMMAND
XDG_RUNTIME_DIR lets the command find admin.sock.
| Command | What it does |
|---|---|
serve | Run the hub (the default) |
status | The hub, its screens, feeds and apps |
update | Render every placed feed now, then refresh the screen |
runs [N] | The last N runs (default 20) and their outcomes |
run APP JOB [--fixture] | Run one job now and wait for it; --fixture runs it as a test render |
key red|yellow|black|white [tap|hold] | Press a key on the screen from the hub |
want KIND [DEVICE] | Send a command to a screen: refresh, heal, clear, wifi_setup and others |
events APP | An app’s answers that haven’t been delivered yet |
device add NAME [--hub] | Register a screen (or, with --hub, a downstream hub) on another machine; prints its token once |
device list, device revoke ID | List or remove those screens |
TODO(owner): the earlier docs listed
slowhub passcode,slowhub app secret set,slowhub backupandslowhub restore. The hub doesn’t have them yet. Confirm they are planned under these names, so the docs can mention them as coming.
Admin API
Served on the admin socket, to the hub’s own user and root only.
| Endpoint | What it does |
|---|---|
GET /admin/v1/status | Hub status |
GET, PUT /admin/v1/config[?device=ID] | Read or change a screen’s layout and prefs (Layout and preferences) |
POST /admin/v1/run | Run a job ({"app", "job", "fixture"}) or update now ({"action": "update"}) |
POST /admin/v1/key | Press a key |
POST /admin/v1/wants/{kind} | Send a command to a screen |
GET /admin/v1/runs?limit=N | Recent runs |
GET, POST /admin/v1/devices, DELETE /admin/v1/devices/{id} | Screens on other machines |
POST /admin/v1/apps/{id}/settings | Set an app’s settings |
GET /admin/v1/preview.png | The frame the screen last reported |
Protocol
The hub serves the protocol, /sb/v1, on device_socket and, when enabled, on listen_device_tcp. See the protocol reference.