Przejdź do głównej zawartości
Dokumentacja

Dashboards and the device API

Ta treść nie jest jeszcze dostępna w Twoim języku.

A dashboard can call the device API of a PIN endpoint’s MC252 or MC261L directly, without parameters in Setup. Calls run as the viewer: their workspace role decides which operations they get, and every call is checked, rate limited, metered as API usage, and recorded in activity history like any other device API call. Only the operations of the device’s built-in manifest can be called, by their id. For the steps to build such a dashboard, see Show device state from the device API.

The hooks below share one call between components, stop polling while the page is hidden, wait out rate limits, and hide what the viewer may not do. A direct trpc.device.api.invoke call does none of this.

Hooks

Section titled “Hooks”

All hooks take the endpoint id, usually from the dashboard configuration. With no endpoint id they call nothing.

ExportWhat it does
useDeviceApi(endpointId)The operations the viewer may call: status, model, operations, canCall(id).
useDeviceApiRead(options)Reads an operation whose effect is read, once or every refreshMs.
useDeviceApiAction(options)Calls an operation, typically a write: available, canCall, call, isPending.
deviceApiErrorText(error)Localized error text, with the role a refused call needs and when to try again.
DEVICE_API_MIN_REFRESH_MS15 000: the shortest refreshMs. Shorter values are raised to it.

useDeviceApi reports status:

  • loading until the list arrives.
  • unsupported when the endpoint is not an enabled PIN endpoint of a device with built-in operations.
  • error when the list could not be read, for example when the viewer has no access.
  • ready with the operations the viewer’s role allows. Viewers get none. canCall(id, input) also checks input keys that need a stronger role, such as admin-only settings.

useDeviceApiRead({ endpointId, operation, input, refreshMs, select, enabled }) returns status (loading, unavailable, error, ready), data, error, isFetching, updatedAt, and refresh(). It is unavailable when the device has no such operation, the operation is a write, or the viewer’s role cannot call it with this input. data keeps the last answer while a refresh runs and after a failed one. select shapes the device’s JSON answer; without it data is unknown. Components that read the same operation with the same input share one call. Each distinct input is its own read, so returning to an earlier input, such as an earlier page of a journal, shows its answer without another call while it is fresh.

Each read reaches the device and counts toward the operation’s rate limit, which is shared by every viewer of the endpoint (for MC252 operations, 60 calls a minute unless the operation sets its own). Without refreshMs the value is read once and again when the viewer returns to a stale page.

useDeviceApiAction({ endpointId, operation }) returns available (the viewer’s role allows the operation), canCall(input), call(input), isPending, error, and reset(). call resolves with the device’s answer and rejects with the API error. After a successful call, reads of the same endpoint are read again. call asks for no confirmation.

The assistant’s dashboard preview may call read operations only. A write there fails with push_agent_key; it works in the published dashboard.

Section titled “Related”