How-to
Layout and preferences
Choose which app's cards appear where on a screen, and when the screen may update. Both live on the hub, one set per screen.
The hub keeps one config document for each screen. It has two parts:
- the layout: how the screen is divided into slots, and which feeds each slot shows;
- the preferences (prefs): when and how often the screen updates.
slowd keeps a copy, so a screen keeps working on its last layout while the hub is away. The hub and slowd both check every change, and slowd can only make limits stricter, never looser.
The layout
The Slowboard 1085 starts with three slots side by side, filled by Weather:
{"strip_h": 36, "spare_key": "white", "prompt_slot": "right",
"slots": [{"id": "left", "x0": 0, "x1": 451, "key": "red", "sources": ["weather/left"]},
{"id": "middle", "x0": 452, "x1": 907, "key": "yellow", "sources": ["weather/middle"]},
{"id": "right", "x0": 908, "x1": 1359, "key": "black", "sources": ["weather/right"]}],
"prompt_sources": ["reminders/prompts"]}
| Field | Meaning |
|---|---|
slots | The slots, left to right. Each covers columns x0 to x1 of the screen. |
slots[].id | A name for the slot. |
slots[].sources | The feeds whose cards make the slot’s deck, in order, as <app>/<feed>. |
slots[].key | The key that moves through this slot’s cards. slowd shows it in the slot’s strip. |
spare_key | The key not used by any slot’s key. |
strip_h | Height of the strip under the cards, in pixels. The card height is the screen’s height minus this. |
prompt_slot | The slot that shows a question when its app doesn’t ask for a particular slot. |
prompt_sources | The only feeds allowed to put questions on this screen. |
Any arrangement of slots works if it follows these rules:
- the slots cover the full width with no gaps or overlaps;
- on the Slowboard 1085, each slot starts at a column divisible by 4 and ends one column before the next multiple of 4 (
x0 % 4 == 0,x1 % 4 == 3), because of how the panel refreshes part of the screen; - slot ids are unique, and each key is used once;
prompt_slotnames one of the slots.
A slot’s width sets the size its apps draw for. An app whose feed has size = "slot" adapts to any slot.
TODO(owner): describe how keys are meant to be presented in the layout. The keys are generic, and the strip shows what each does; but the layout’s
keyandspare_keyfields assign keys to slots. Confirm the wording above, or say how it should change.
The preferences
| Field | Default | Meaning |
|---|---|---|
auto | true | Whether the screen updates on its own. |
every_min | 30 | Minutes between scheduled updates. Must divide a day (1440) and be at least 15. |
active_hours | "06:00-24:00" | When scheduled updates may happen. Key presses work at any time. |
quiet_hours | none | When nothing refreshes at all, key presses included. |
tz | "America/Vancouver" | The screen’s time zone. Apps get it as TZ. |
detail_keep_s | 600 | How long a detail card stays before the slot returns to its home card. |
stale_grace_min | 15 | How long past valid_until before a card gets an “as of” note. |
scheduled_waveform | "normal" | The refresh mode for scheduled updates. |
daily_ceiling | {"global": 120, "per_app": 48} | The most refreshes a day, in total and per app. Can only be lowered from the screen’s own limits. |
Change them
The hub’s command-line tool doesn’t edit the config yet. The hub’s admin socket accepts changes as JSON: send only the parts you want to change. Each top-level field you send replaces the current one, so send slots as a whole list.
For example, to update the screen every hour:
u=$(id -u epaper)
runuser -u epaper -- curl -s --unix-socket /run/user/$u/sb/admin.sock \
-X PUT -H 'Content-Type: application/json' http://hub/admin/v1/config \
-d '{"prefs": {"every_min": 60}}'
GET http://hub/admin/v1/config on the same socket returns the current document. Both act on the screen on the same machine; add ?device=<id> for another screen. An invalid change is refused with a message saying why, and nothing is changed.
TODO(owner): a layout editor is planned for the hub’s web interface. Confirm whether the docs should show the admin-socket method above, or wait for the editor, and add a worked layout change once there is a supported way to make one.