Dashboards and devices¶

A dashboard is a grid of widgets bound to message names. It can show values and send controls across several flows. A device is a paired screen, such as a wall tablet or a knob, and shows an ordered set of published dashboards.

Building one¶

1. Open Dashboards → New dashboard.
2. Enter edit mode, choose Add widget and select a type.
3. Bind the widget to a message in its settings. On desktop, drag and resize tiles on the grid.
4. Publish when the dashboard is ready.

Edits stay in a draft; paired screens show the published version. On phones, tiles stack in one column over the dashboard's ground (its background image, or the Glass look's drifting colours) and dragging is disabled, but settings remain editable. In edit mode, ⌘Z / Ctrl-Z undoes an edit and ⌘⇧Z / Ctrl-Shift-Z redoes it.

Copy widget in a widget's settings, or ⌘C / Ctrl-C with it selected, keeps a copy in the browser until the next copy replaces it. Paste it on this or any other dashboard with the paste button in the bar or ⌘V / Ctrl-V. It lands below the other widgets with the same title, bindings and size.

A widget can end up below the canvas, for example after the canvas was made smaller. In edit mode the canvas then grows to reach it, under a dashed line where the panel ends. Scroll down and drag it back, or use Reflow.

Controls can publish real values while you edit, so choose their targets with care. Your new Switch may already be flipping something!

The widgets¶

Display¶

Every widget has a title. Show title controls its visibility; the title still names the widget for accessibility and published values.

Input¶

Colour defaults to [h, s, v]: hue 0–360°, saturation and brightness 0–100%. Sends can select RGB ([r, g, b], 0–255) or hex ("#rrggbb"). HSV and RGB bind to list; hex binds to str.

Controls publish to their bound messages. The flow canvas shows them as endpoints feeding the nodes that consume those messages.

Bindings are checked in the editor and on the server. See Payload types.

A slider's reading¶

A Slider can also show what it sets against, such as the room's temperature beside a setpoint: Beside it binds reading: {message, dtype, label} to a float or int. The reading is only shown, never published. It is written in the slider's unit and to its step's decimals (a step of 0.5 writes 21 as 21.0), as the slider writes its own value, so the two always match; — stands in for the value until one arrives. On a round face it takes the middle (see Round dashboards); in a tile it is a line under the slider's value.

It is also marked where it sits on the slider's scale, as a thermostat marks the room's temperature: the handle is what is set, the dot what is. The dot is at the reading's fraction of the scale, (reading − min) / (max − min) held to 0–1, so a reading outside the range sits at that end. It takes no pointer, and there is none until a value arrives. See Dots on the track.

Sizes are CSS pixels of the canvas, as in the round geometry below. The slider's own value is at the tile's text size (14; 16 on a touch-friendly panel), centred on a line as tall as the control (32; 48 touch-friendly).

Dots on the track¶

A slider's ticks, a selector's options on a round face and a slider's reading are dots inside the track, on its midline — on a round face the ring's centre line, radius c − 20. Each is drawn in the colour that reads on what covers it: the track, the value's fill, or the handle.

The reading is a filled circle like the handle, smaller and in the text colour rather than the handle's paint, so it reads as what the room is beside what it is set to. It is larger than a stop and stronger in colour, and it is the one dot that shows on the handle, so a reading at the setpoint is still visible.

A counter¶

A Counter sets one whole number with up to three linked counters. They are the digits of that number, counted in the unit of the finest, and the widget publishes the number on its one message: hours and minutes publish 07:30 as 450, and 07:55 plus five minutes is 08:00.

A new counter is a time of day: [{label: "h", step: 1, min: 0, max: 23}, {label: "min", step: 5, size: 60}], wrapping.

For counters 0 to n − 1, coarsest first, and the number v (ui/core/counter.ts, which the firmware ports as it stands):

Written, the digits are joined by :, each counter's label under its own. Every digit but the coarsest is zero-padded to the width of size − 1 (05); the coarsest to the width of max when it has one (07), and a negative one keeps its sign in front of the padding. The number shown is the message's, held as sent until it comes back, as a slider's is, and lo until one arrives.

In a tile each counter is a column: a press up, its digits, a press down and its label, at the control sizes, so touch-friendly where the panel is. A press moves the number at once and one publish follows 300 ms after the last press, as a ring's does; holding a press does not repeat it. On a round face see Round dashboards.

Charts¶

Choose the chart's data source:

• Live: recent numeric message history, updated as values arrive.
• Query: publishes a record request containing range_s and interval_s, then draws a flow's series response. Include those fields in the answer so the chart can reject responses for a different window.
• Runs: compares a numeric metric from named runs, a sweep or the latest runs of a flow. See Runs.

Multi-line charts show a legend as well as different colours.

Media tiles¶

Media messages contain artifact references; the widget loads the bytes they name. Crop or fit controls image sizing. Play as it arrives enables autoplay, subject to the browser's rules for sound.

For local streams, volatile=True artifacts can be pushed over the websocket with their message. Stored artifacts are fetched individually, as are frames viewed through a portal. Use occasional snapshots for remote screens.

A tile asks for frames only while it is on screen in a tab that is being looked at, and stops when it scrolls away, the tab is hidden or the tile closes. A clip keeps playing either way. One page is pushed frames for at most 8 messages at once. A ninth tile fetches its frames one by one and does not turn a camera on. A device's camera sends only while a tile like this wants it.

For continuous video, set Live stream to a browser-compatible camera URL. The browser must be able to reach that URL; enrollment does not expose the camera itself. See Media payloads.

Player tiles¶

A Player reads a status record and publishes commands to a separate str message.

Controls send toggle, next, prev and seek:<seconds>. Your receiving node translates those into device actions. The position advances in the browser between readings and resets to each fresh reading.

Website tiles¶

Set Address to a page to embed, or choose Image for a snapshot or MJPEG URL. A website may refuse embedding.

Embedded pages run in a sandbox without cookies or storage by default. Trusted site permits the site's own origin, cookies and storage. Use it only for a trusted destination. The app blocks trusted embeds of its own origin, including the portal origin, to protect your session.

Dashboard settings¶

Open Dashboard settings from the dock. Each setting can hold a fixed value or follow a message chosen in Driven by. The fixed value is the fallback when no usable message value is available.

To change one on a schedule, have a scheduled node publish its bound message.

Look and theme¶

Fluksio is the default look. Material uses flat tonal cards; Glass uses translucent tiles. Widgets work the same in all three.

Theme follows the chosen preference unless a palette sets the background colour.

Palette¶

Paste a colour list or a Coolors palette link. Colours have roles by position:

Missing roles are derived, so three colours are enough to get started. Rotate shifts their order. Text contrast is corrected automatically; failure and success indicators keep their status colours.

Background and lock¶

Background draws an image beneath the widgets. Lock disables publishing from controls and shows Read-only when viewing the dashboard. It does not restrict API permissions and does not disable controls in edit mode.

Round dashboards¶

For a round screen such as a rotary knob, set the canvas to Round in the dashboard settings, or pick the Knob preset (360×360). A round canvas is square (shape: "round" forces canvas_height to canvas_width), and nothing outside its circle is drawn. It fills the screen at any width: a phone neither stacks nor pads it.

A round dashboard has no grid. It shows one widget at a time, each drawn as the whole face, in the order of widgets; layout is not read. In the editor, the faces are a row above the dock: press one to show it and open its settings, drag it along the row (or Alt+←/→) to move it, and add more with Add widget.

A Slider, Selector, Colour, Counter or Gauge draws on the ring along the edge, which a knob's own ring turns. In a browser, drag along the ring or use the mouse wheel (or the arrow keys once it has focus): one notch is one step, one option (no wrap), one hue step (hue_step, default 5°, wrapping) or one step of the counter selected. The value moves at once and is published once, 300 ms after the last notch or when the pointer is released. A Gauge only shows. On any other face, turning a knob only wakes the screen.

A Counter's ring turns one of its counters, with carry: the finest, until a press on another's digits selects that one instead. The selection holds while the face is shown and is the finest again once the face is left. Dragging along its ring counts notches rather than picking a place: one per step's share of the sweep, 300° × step / its turn (size, or max − min + 1 for the coarsest), so the arc stays under the finger, and one per 15° for a coarsest without max. The angle is counted from the last move the shorter way round, so a drag carries on through the gap. The face has no up or down presses.

A Slider's reading (Beside it) is written large in the middle, under its label; the slider's own title and value move to the line in the ring's gap.

Value, Bar, Switch, Button, Clock, Icon, Notification and Text have faces of their own. Every other type is drawn as its rectangular body in the middle of the face, and the editor marks it Poor fit for round.

Moving between faces¶

A swipe carries the page with the finger (Swiping); a drag that starts on the ring turns the ring instead. A dashboard reopens on the face it was last left on in this session, otherwise on its first. Landing on another dashboard shows its title and icon in the middle of the face for one second; a round panel has no rail.

Geometry¶

Devices that draw dashboards natively use these numbers. They are canvas pixels, scaled with the canvas; S is the canvas width and c = S/2. Angles are degrees clockwise from three o'clock. Text sizes are font sizes; muted is the look's muted text colour.

Paint follows the look: Fluksio draws a muted track, a primary value and a handle of the ground colour ringed in primary; Material a tonal track and a primary handle; Glass a translucent track, a glowing value and a white handle. A Switch or Button face wears the look's own button.

Motion¶

How a dashboard moves, for devices that draw it natively. Distances are canvas pixels. Each look moves at its own spring; a device without springs runs the spring's closed form for the duration given and then sets the end value, or uses the cubic-bezier that stands in for it.

From rest, a spring's progress is p(t) = 1 − e^(−ζω₀t)·(cos ω_d t + (ζω₀/ω_d)·sin ω_d t), with ω_d = ω₀·√(1 − ζ²). "Spring" below is the dashboard's look's.

With reduced motion asked for, nothing travels on its own: a page under the finger still follows it, but every turn, return and value lands at once. The dot and the name pill, which only change colour or opacity, keep their timing.

A device may simplify where its hardware is slow, keeping the direction and the end state: a turn a key or a dot asked for may cut; a retarget may restart the curve from where it is without carrying the speed; a counting number may switch; and the value arc may be redrawn each frame as an arc to the eased angle, which is what the browser's reveal amounts to.

Swiping¶

Faces are swiped sideways and a device's dashboards up and down, with the page under the finger, as a tile view moves.

Showing one¶

Open /view/{name} for a dashboard-only view with your normal session. For a dedicated screen, pair a device.

Devices: hanging a screen on a wall¶

As a superuser:

1. Open Devices → Add device and name it after where it hangs. The name sets its address, /panel/{id}, and a later change of title keeps it.
2. Under Dashboards, add the ones it shows. The first is what it opens with, and the arrows set the order of its rail.
3. Enable Touch friendly for larger controls.
4. Open the pairing link on the device. It shows a six-character code.
5. Enter that code under Pairing, check the device description, then press Pair. A device asking from your own network also appears in the list below, with what it says about itself and a two-character check. The device shows the same check beside its code. When the two match, Pair this one adopts it without the code.

The screen collects its credential and shows the assigned published dashboards. Several dashboards get a navigation rail. The page says whether the device is online, which it is while its live socket is open, and when it was last seen since the instance started.

Each save carries the version it was read at. When someone else saved the device first, the save is refused and the page shows their version.

On your network one address may ask for five codes a minute, and the portal limits the requests that come through it. At most 50 requests wait from each, and a new one pushes out the oldest that came the same way.

A device credential reads its assigned dashboards, their bound messages and the artifacts they show. It writes only the targets of their controls and query charts, and the messages of its own in ports. A message its tiles only draw, or a dashboard setting is bound to, stays read only. On a locked dashboard only the query charts may still publish.

A device acts as itself and not as the superuser who paired it, so deleting or deactivating that account leaves the device paired.

Unpair screen revokes the device's credential and keeps the device and its dashboards. Deleting the device removes the assignment, its access and its report, and a device added again under the same name does not bring the old credential back.

The device definitions are stored in the flow repository (_devices/<id>.json), so their history is in git with the flows. The credential generation lives in DEVICES_FILE outside it, so reverting the repository never undoes an unpair. An instance from before devices moves its panels.json there on its first start and renames the file panels.json.migrated.

A screen without a browser¶

The openpanel firmware, kept in its own repository, draws dashboards as native widgets on an ESP32-P4 wall panel (Waveshare ESP32-P4-WIFI6-Touch-LCD-7B, 1024×600). Once its config page points it at this instance (the device's link works too, the device keeps only its address), it shows the pairing code itself; enter it as in step 5. It reads the same published dashboards and live values and draws every widget type with two exceptions, both shown as a placeholder: a website tile that embeds a page (image tiles work), and a chart of runs, which a device credential may not read. Media tiles play MJPEG streams, pushed frames, images, and H.264 Baseline or MJPEG clips up to 640×360. Re-encode other clips with the clip recipe.

The device decides what its port names mean. openpanel reports the ones it serves, such as gpio.<n>, backlight, touch, mic and speaker, with the settings each one reads, and ignores any other name. A browser screen serves none of them. The speech recipe turns mic into text and text into speaker.

The device's own ports¶

A device can also act as a node, with a button on its GPIO, its backlight or its microphone. Its ports are wired in a flow with a Device node: pick the device, then add each port under Publishes (in, the device sends to the message) or Follows (out, the device reads it). Use in flow on the device's page puts its node in a flow you pick, and Capabilities lists the ports it reports and what the published flows wire, each linked to its node.

Only enabled published flows count, so stopping a flow takes its ports out of the device's io and its credential's reach. A port wired in two of them, or a device node naming a device that does not exist, is an error on the canvas. Until it is fixed the device follows the first binding of the port, by message name. Until a device reports what it has, a port name is free text; once it has, a port it does not list is a warning and one wired the wrong way round, or to another type, an error. int and float pass for each other.

The device reads its ports as io on GET /devices/{id}, in a fixed order, and is told to read them again when publishing or deleting a flow changes them. The credential may publish to its in messages even when a dashboard is locked, and may upload an artifact named after one (PUT /artifacts?name=<message>), which is how a microphone sends a recording. A value it publishes there is credited to its device node, so the node's edge lights up on the canvas. out messages are read only. The node is shown degraded, Offline, in amber while the device is not connected: a warning on Home, not a fault, since a panel switched off or asleep breaks nothing.

What a device reports¶

A paired device says what it has with PUT /devices/{id}/report, from its own credential only. openpanel sends it after pairing and once per boot. The report replaces the one before and is at most 16 KB. It is read leniently, so a newer firmware still reports to an older instance:

• keys this version does not know are dropped
• a value it does not know for a display shape or a port direction reads as unknown, and a features value that is not true or false is left out
• a port it cannot read, such as one with an unknown dtype, is left out on its own and named in the server log

Only a report that is not schema 1, or not an object at all, is refused with 422.

{
  "schema": 1,
  "platform": "esp32p4",
  "board": "p4",
  "firmware": "0.1.2",
  "display": {"w": 1024, "h": 600, "shape": "rect", "touch": true},
  "ports": [
    {"port": "backlight", "direction": "out", "dtype": "int",
     "config": {"type": "object", "properties": {"wake_s": {"type": "integer", "default": 30}}}},
    {"port": "gpio.4", "direction": "in", "modes": ["in", "out"], "dtype": "bool"}
  ],
  "camera": {"sensor": "IMX415", "w": 1920, "h": 1080, "fps": 15},
  "features": {"display": true}
}

config is a JSON schema of the settings the device reads for that port, which the Device node turns into a form. It may instead name an entry of a top-level config_schemas object, so pins that share a schema send it once: "config_schemas": {"pin": {...}} and "config": "pin" on each port. The schema is put in place when the report is read. modes lists the directions a port may be wired in when it may be either, as a GPIO pin. on_demand marks a port that sends only while somebody wants it.

The device's page shows the report under Capabilities, with each port's binding or Use in flow for it. A reported screen becomes a canvas preset in the dashboard settings, named after the device, and the first report of a touch screen turns Touch friendly on. A device paired before this version keeps the switch as it was set.

A device's camera¶

A camera device (openpanel on a NANO) reports four ports:

camera sends only while it has demand: while a page wants its frames (a dashboard tile, the preview on the device's page, a screen through the portal), or a node of a running flow reads its message. Once its flow wires camera, the device's page shows a Camera preview. A flow that reads camera keeps it sending all the time, about 300 GB a month through a cloud instance, so the Device node warns when a node in its flow reads a port that sends on demand. Have flows read snapshot or person instead. To keep the picture of whoever came by, a node reading snapshot can hand it on to a message of its own, which a media tile shows until the next one:

def process(snapshot):
    return {"visitor": snapshot}

The device is told which of its ports have demand on its live socket, and sends its frames there too, as described under Live events. Through the portal the socket carries text only, so a device paired there uploads each frame over HTTP instead.

A device may fetch the last 8 artifacts each of its messages pointed at, not only the current one, so a screen fetching a camera frame by frame through the portal is not refused a frame the camera has just replaced.

Before device nodes¶

Before device nodes a device carried its ports itself. On its first start an instance moves each one into the flow that declares its message, one device node per device and flow, in the published flow and its draft. A port whose message no flow declares is left out and named in the startup log, so wire it again by hand.

A screen somewhere you cannot reach¶

An enrolled instance also shows a portal pairing link. Use that link on the remote screen, then approve its code on the device's page. The device description says via portal. Anyone can ask the portal for a code, so a request that came through it, or from outside your network, is adopted by its code only and never from the list.

The instance enforces the same dashboard and message limits. Remote credentials are issued by the portal with the device's credential generation in them, so Unpair screen and deleting the device revoke them as they do a local one. A credential from a portal older than this carries none and keeps working only while the device was never unpaired or deleted. Pair such a screen again once the portal is updated.

See also¶

• Payload types
• Flows, nodes and messages
• Accounts and the portal