Skip to content
KinetixUI

IoT

KinetixUI IoT is a set of controls, telemetry, pairing and automation patterns for connected products whose hardware answers asynchronously.

@kinetixui/iot is a separate module, not part of @kinetixui/ui. It adds a domain vocabulary — devices, commands, telemetry, alerts, automation rules, pairing, places — on top of the same token contract every other KinetixUI platform is built from, and it is organised around one principle: the interface tells the truth about device state. See State honesty.

Experimental, and React only. The API may change without a major version while this finds its shape. It is not part of the 109 cross-platform component surface, and there is no SwiftUI, Jetpack Compose or Flutter port of it. It ships no transport, no automation engine and no video, and every demo on the website is simulation.

This page is the reference. For the tour — three reference environments, the command lifecycle and each pattern working — see the IoT overview.

Contents of the module#

LayerWhat it isImport
State modelTypes and pure functions. No React, no DOM@kinetixui/iot/functions
PrimitivesOne fact, rendered@kinetixui/iot/react
ControlsOne thing a user can change@kinetixui/iot/react
PatternsA composition with a rule or two@kinetixui/iot/react
CompositionsWhole screens, published as source to copykinetixui.com/iot

Install#

npm install @kinetixui/iot

The module is versioned on its own line, apart from @kinetixui/ui, so the site-wide changelog does not list it. What changed in each version is in its own changelog.

Three entry points, because the useful half of this module has nothing to do with rendering:

importcontains
@kinetixui/ioteverything
@kinetixui/iot/functionsmodels and pure functions — no React
@kinetixui/iot/reactprimitives, controls and patterns

The functions subpath imports neither React nor the DOM, so it runs in a server route, a worker, a queue consumer or a test with no renderer. That is asserted twice rather than promised: against the source import graph, and against the built dist that npm ships.

Peer dependencies#

react is an optional peer (>=18). The react subpath needs it, and so does the root @kinetixui/iot import because it re-exports the primitives; @kinetixui/iot/functions needs nothing at all. There is no react-dom peer — no primitive renders a portal — and no @kinetixui/ui peer, since nothing here imports a component from it.

Functions only, with no React required:

npm install @kinetixui/iot

Or, to use the primitives:

npm install @kinetixui/iot react

Styling prerequisite#

This package has no runtime dependencies, and deliberately does not depend on @kinetixui/tokens or @kinetixui/ui — not even as a peer. The primitives style themselves with Tailwind utilities on the token contract, which are class names rather than imports. So an app needs the token stylesheet loaded and this package inside its Tailwind content:

// tailwind.config.js
content: ["./src/**/*.{ts,tsx}", "./node_modules/@kinetixui/iot/dist/**/*.js"],

The functions subpath needs none of that.

Scope#

Available now

  • a state model — device, health, command lifecycle, telemetry, alert, activity, automation rule, pairing flow, space hierarchy and energy types — with pure functions for each
  • monitoring and feedback that keep "we do not know" visible: battery, connection, data freshness, telemetry, command feedback, per-device activity and energy (see Monitoring truth model)
  • 10 React primitives, 7 device controls and 29 patterns
  • a device taxonomy and a metric registry, so a category and a metric mean the same thing everywhere
  • control-state resolution: resolveControlState turns a device status and a command lifecycle into one answer about whether a control is operable, and whether what you are looking at is confirmed
  • a deterministic simulation and three reference environments, on the website only, as source to copy

Not in this module

  • MQTT, BLE, WebSocket or HTTP polling — no transport of any kind
  • vendor adapters (Matter, Zigbee, LoRaWAN, Modbus, or any product's own API)
  • native SwiftUI, Jetpack Compose or Flutter components
  • a device-discovery or provisioning implementation — pairing here is screen state
  • charting infrastructure — a series is data, and TelemetryTrend is a plain accessible plot
  • an automation engine — AutomationBuilder edits a rule and RoutineCard renders one; nothing evaluates a trigger or schedules a run
  • video — nothing in this module streams, decodes or displays a camera feed

Nothing in this module opens a connection, holds a credential, or parses or executes a device payload. It models what a device is, so that the layer which talks to one has something honest to render into.

Generic on purpose#

The models are shaped to be equally true for smart homes, agriculture, industrial operations, medical devices and fleet tracking. A field earns a place in KinetixDevice only if a soil probe, an infusion pump, a thermostat and a delivery van tracker would all populate it with the same meaning. Anything narrower goes in metadata, and there are no transport or protocol fields at all.

The same reasoning keeps vocabulary out of the library. Mode labels, group nouns ("room", "zone", "line") and unit strings come from your product; the module supplies the state model they hang on.

Architecture#

Five layers, and the boundary that matters is the second one:

  1. Your application and provider layer — wherever device state actually comes from: MQTT, BLE, Matter, a REST API, a WebSocket, a vendor SDK, a cloud service. These are examples of what an application might use. None of them is in this package.
  2. Your application adapter — your code turns whatever a provider sends into the module's shapes, and turns a callback from a control back into a request to the provider.
  3. KinetixUI IoT state (@kinetixui/iot/functions) — the state model as pure functions.
  4. KinetixUI IoT components (@kinetixui/iot/react) — primitives, controls and patterns that draw that state and report intent through callbacks.
  5. Compositions — whole screens, published as source on kinetixui.com/iot for you to copy.

The overview page draws this as a diagram.

Transport boundary#

KinetixUI does not own the transport. The module starts above it. Your application receives device state through an API, a gateway, a device SDK, a broker or something else entirely; the module begins after that and turns the result into consistent product semantics and UI.

In practice the boundary is one function you write. It takes what your provider sends and returns a KinetixDevice, and nothing about the provider leaks past it:

import { normalizeDeviceStatus, type KinetixDevice } from "@kinetixui/iot/functions";
 
// Your provider's shape. This type is yours; the module never sees it.
type ProviderMessage = { id: string; label: string; kind: string; link: string; batteryPct?: number; seen?: string };
 
function toDevice(message: ProviderMessage): KinetixDevice {
  return {
    id: message.id,
    name: message.label,
    type: message.kind,
    status: normalizeDeviceStatus(message.link), // "CONNECTED" -> "online"; anything unrecognised -> "offline"
    battery: message.batteryPct,
    lastSeenAt: message.seen,
  };
}

status is a badge, and a badge has no "unknown", so an unrecognised spelling falls back to offline there. Decide connectivity from the provider's own value instead, before that fallback, so "we could not read it" stays unknown (see Status, connectivity and health):

import { normalizeConnectivityState, type KinetixConnectivityState } from "@kinetixui/iot/functions";
 
function toConnectivity(link: string | undefined): KinetixConnectivityState {
  if (link === "CONNECTED") return "online";      // your provider's spellings, mapped by you
  if (link === "DISCONNECTED") return "offline";
  return normalizeConnectivityState(link);         // a known state passes through; anything else is "unknown"
}

Going the other way, a control reports intent and your code does whatever your transport requires. The control never assumes it worked:

import { DevicePowerControl } from "@kinetixui/iot/react";
 
// confirmedPower, requestedPower and sendToDevice are yours.
<DevicePowerControl
  label="Pump 01 power"
  state={confirmedPower}          // what the device last reported
  requested={requestedPower}      // what the user asked for, until the device agrees
  onToggle={(next) => sendToDevice(next)} // yours
/>

State honesty#

This is the principle the rest of the module is built on, so it is stated once, plainly.

A request is not a state. What the user asked for is drawn differently from what the device has confirmed — in the picture and in assistive technology.

Almost every device UI fills the gap between asked and confirmed with an optimistic update. The switch slides, the icon lights, and the screen asserts a state the device has not reported. On a lamp that is harmless. On a door lock, an irrigation valve or a pump it is a lie the user discovers later.

The module holds this line in four places:

  • Controls take state (confirmed) and requested (asked) as separate props, and never treat a press as a result. aria-checked on the power switch reports the confirmed state while a request is open.
  • The command lifecycle is a state machine in which only a confirmed event changes what the device is said to be. acknowledged is not confirmed.
  • Telemetry separates a reading from how much to trust it: stale, missing and errored are states with words, and a gap in a series is drawn as a gap.
  • Unknown is a result. No battery, no signal, no timestamp and no reading are each rendered as “unknown”, never as zero.

Optimistic presentation is not forbidden: every control except the lock accepts strategy="optimistic", which moves at once and says so in words if the device refuses (see Controls). What no strategy changes is the model underneath: requested and state stay two values, and only the device's report moves state.

The command lifecycle#

One user-initiated change, from asked to confirmed or to an honest failure. KinetixCommandLifecycle is a small state machine with nine stages: idle, requested, acknowledged, confirmed, failed, timed-out, unreachable, retrying and cancelled. It holds two values side by side — requestedValue and confirmedValue — and only a confirm event moves confirmedValue. Everything else, including acknowledged, leaves it alone, so “the device heard me” can never be drawn as “the device did it”.

Here is the whole story of a switch that does not get its answer — off, turning on, timeout, unreachable, retry:

import {
  advanceCommandLifecycle,
  canRetryLifecycle,
  describeCommandLifecycle,
  startCommandLifecycle,
} from "@kinetixui/iot/functions";
 
const say = (value: unknown) => String(value);
 
// OFF — the device last confirmed "off". You ask for "on".
let cmd = startCommandLifecycle<"on" | "off">({ confirmed: "off", requested: "on" });
describeCommandLifecycle(cmd, { formatValue: say });
// "No change requested. The device reports off."
 
// TURNING ON — sent, and not yet confirmed. The switch must not say "on".
cmd = advanceCommandLifecycle(cmd, { type: "sent" });
describeCommandLifecycle(cmd, { formatValue: say });
// "Requested on. Waiting for the device; not yet confirmed. It last reported off."
 
// TIMEOUT — no confirmation inside your window. You decide the window; the machine records the outcome.
cmd = advanceCommandLifecycle(cmd, { type: "timeout" });
describeCommandLifecycle(cmd, { formatValue: say });
// "No confirmation for on: the request timed out. The device last reported off."
 
// UNREACHABLE — the device did not answer at all. A different sentence, because the next step differs.
cmd = advanceCommandLifecycle(cmd, { type: "deviceUnreachable", reason: "No reply from the gateway." });
describeCommandLifecycle(cmd, { formatValue: say });
// "The device is unreachable, so on was not confirmed. No reply from the gateway. It last reported off."
 
// RETRY — a new attempt, counted and bounded (three by default).
canRetryLifecycle(cmd);                        // true
cmd = advanceCommandLifecycle(cmd, { type: "retry" });
describeCommandLifecycle(cmd, { formatValue: say });
// "Retrying, attempt 2 of 3. on is still not confirmed; the device last reported off."
 
// Only now does the device's state change.
cmd = advanceCommandLifecycle(cmd, { type: "confirm" });
describeCommandLifecycle(cmd, { formatValue: say });
// "Confirmed: the device reports on."

Three properties are worth relying on:

  • Every unconfirmed sentence names both values — the one requested and the one last reported — and none of them says the device is the requested value before confirmed. A screen-reader user has no colour or spinner to correct an over-claim.
  • The machine never throws and never mutates. transitionCommandLifecycle returns ok: false with the same state and a reason (illegal-transition, or max-attempts past the limit), so a caller fed by duplicate or late deliveries can ignore a rejection and keep rendering.
  • Late truth is accepted. A confirm after timed-out or unreachable is legal: a device that answers late has told you the truth, and refusing it would leave the screen insisting on a state the device has left. confirmed and cancelled are terminal; a new change is a new lifecycle.

The machine has no clock and no timer. Your code decides when to send timeout — isLifecycleTimedOut answers whether a window has passed when you pass it now and a limit — and what to do about it. CommandLifecycle renders a lifecycle as a stepper (requested → acknowledged → confirmed, or a failure branch with a Retry when the machine allows one) with one polite role="status" sentence, the same one describeCommandLifecycle returns.

A request can still be open when the device goes offline. resolveControlState lets the link decide a control's availability over a command in flight, because a request to an offline device is going nowhere, and describeControlState follows it. This wording lands on the next @kinetixui/iot release:

CommandLinkControl description
requested or acknowledgedonline, or not reportedChange requested, not yet confirmed by the device
requestedconnectingConnecting to the device. The requested change is not yet confirmed. Showing the last known setting
requestedstaleChange requested, not yet confirmed by the device. Device data is out of date
requestedofflineDevice offline. The requested change is not confirmed. Showing the last known setting
requestedunreachableDevice unreachable. The requested change is not confirmed. Showing the last known setting
confirmedonlineReady
failed or timed outonlineThe last change was not confirmed. Showing the setting the device reports

Offline and unreachable drop the "not yet", which would promise progress, the request chip stops pulsing there too, and the control's status region announces "Device offline. The requested change is not confirmed." A link that is not reported is unknown, never offline. A timeout is the application giving up waiting, so it is announced as "No confirmation for on: the device did not confirm in time, so the change may still apply", not as a failure.

CommandStatus is different on purpose. It shows a command record (queued, sent, acknowledged…) and knows nothing about the device's link, because a record can legitimately stay queued while a device is offline: many backends hold commands until the device reconnects. Show the link beside it with DeviceConnection, and settle the record (expired, failed) in your application when your transport gives up. The component does not guess from the device's state.

The device model#

import type { KinetixDevice, KinetixDeviceStatus } from "@kinetixui/iot/functions";
 
type KinetixDeviceStatus =
  | "online" | "offline" | "stale" | "syncing" | "pairing"
  | "updating" | "warning" | "error" | "disabled";
 
type KinetixDevice = {
  id: string;
  name: string;
  type: string;            // product-defined: "thermostat", "soil-probe", "gateway"
  status: KinetixDeviceStatus;
  battery?: number;        // 0–100
  signal?: number;         // normalised 0–100, not dBm
  firmwareVersion?: string;
  lastSeenAt?: string | Date;
  locationName?: string;
  metadata?: Record<string, unknown>;
};

stale is the one worth pointing at: it means "there is a connection story, but the data behind it is old", which is the state device UIs most often render as a confident online.

Status, connectivity and health are different questions#

status is what a device row shows as one badge. Beneath it the module keeps two more precise answers:

  • Connectivity — can the device be reached (online, stale, connecting, offline, unreachable, unknown)? A missing or unreadable status is unknown, never offline.
  • Health — is it working (healthy, degraded, warning, critical, unknown), with the reasons listed?

deriveDeviceHealth returns both a level and the reasons behind it, so a screen can say why:

import { deriveDeviceHealth, summarizeFleetHealth } from "@kinetixui/iot/functions";
 
deriveDeviceHealth({ status: "offline" });
// { level: "warning", reasons: [{ code: "offline", level: "warning", message: "The device is offline" }], faults: [] }
 
const fleet = summarizeFleetHealth([
  { id: "valve-03", name: "Valve 03", type: "valve", status: "online" },
  { id: "soil-04", name: "Soil sensor 04", type: "soil-sensor", status: "offline" },
]);
fleet.description; // "1 of 2 healthy, 1 warning, 1 offline."

Read that description carefully: it is one offline device, counted once as a warning and once as offline. summarizeFleetHealth reports offline beside the health counts because an offline device also has a health level, so the raw numbers overlap. DeviceHealthSummary therefore gives every device exactly one bucket (offline or unreachable is its own bucket, taken out of warning) so the visible counts sum to the fleet size. If you draw your own summary from byHealth and offline, do the same.

Device categories and the domain registry#

KinetixDevice.type is free text, because your product's vocabulary is yours. resolveDeviceCategory maps it onto a small set of categories, and the taxonomy says everything the module knows about each one:

import {
  KINETIX_DEVICE_TAXONOMY,
  categoryAffordances,
  resolveDeviceCategory,
  resolveDeviceDomain,
} from "@kinetixui/iot/functions";
 
resolveDeviceCategory({ type: "Soil Probe" });   // "soil-sensor"
resolveDeviceCategory("mystery");                // "unknown" — rendered neutrally, never guessed
resolveDeviceDomain("thermostat");               // "climate"
categoryAffordances("thermostat");               // ["setpoint", "mode"]
 
KINETIX_DEVICE_TAXONOMY.valve;
// { domain: "water", label: "Valve", affordances: ["power", "level"], defaultMetrics: ["flow"], groupKey: "valves" }

The 16 categories keep their interaction shape (a light, a lock, a pump, a motor), which decides which controls a device is offered. A separate domain registry (lighting, climate, security, irrigation, pump, industrial, and so on) groups devices for filtering and roll-ups without changing what a device can do. Both live in one table, so adding a category is one entry there and one union member, and nothing else switches on a category to find out its label or affordances. Domain and category values are lowercase strings by design, matching the rest of the module's unions.

Metrics and telemetry#

The telemetry model#

type KinetixTelemetryQuality = "good" | "estimated" | "missing" | "error";
 
type KinetixTelemetryPoint = {
  timestamp: string | Date;
  metric: string;          // product-defined: "temperature", "soil-moisture", "flow"
  value: number;
  unit?: string;           // "°C", "%", "L/min" — printed, never converted
  quality?: KinetixTelemetryQuality;
};
 
type KinetixTelemetrySeries = {
  deviceId: string;
  metric: string;
  points: KinetixTelemetryPoint[];
};

quality exists so that missingness survives the trip to the UI. It is why formatTelemetryValue can refuse to print a number.

The metric registry#

KINETIX_METRIC_REGISTRY says what a metric is called, its usual unit and how many decimals it deserves, so a tile, a plot axis and an accessible summary agree. It holds 13 metrics, from temperature and soil-moisture to flow, energy and battery. Everything in it is a default your product can override per call.

Thresholds are given only where they are not domain-specific: battery, signal-strength and air-quality have widely shared bands. Temperature, humidity and soil moisture deliberately have none — 30 °C is fine in a greenhouse and an emergency in a cold store, and a wrong default is worse than none. You supply the threshold that is true for your product:

import { getMetricDefinition, resolveMetricThresholds } from "@kinetixui/iot/functions";
 
getMetricDefinition("soil-moisture");                        // { id: "soil-moisture", label: "Soil moisture", unit: "%", decimals: 0 }
resolveMetricThresholds("soil-moisture", { warningLow: 28 }); // { warningLow: 28 }

Readings, thresholds, stale and missing#

evaluateReading judges one reading and returns a state with a word and a glyph: normal, warning, critical, stale or unavailable. The precedence is fixed: no usable value beats an old value beats the threshold result. A stale reading is never called normal, however in-range it is, because an old number is not evidence of a current condition.

import { evaluateReading } from "@kinetixui/iot/functions";
 
const now = "2026-01-01T12:00:00Z";
 
evaluateReading({ metric: "air-quality", value: 130, timestamp: "2026-01-01T11:59:00Z", now, staleAfterMs: 300_000 });
// { state: "warning", level: "warning", word: "Warning", glyph: "triangle", side: "high" }
 
evaluateReading({ metric: "air-quality", value: 130, timestamp: "2026-01-01T10:00:00Z", now, staleAfterMs: 300_000 });
// { state: "stale", level: "warning", word: "Stale", glyph: "clock", side: "high" } — what the number alone would have been
 
evaluateReading({ metric: "temperature", value: null, quality: "missing" });
// { state: "unavailable", level: null, word: "Unavailable", glyph: "dash" }

Every state is a different glyph silhouette and a word, so no state is carried by colour alone.

Monitoring truth model#

Monitoring is where an interface most often turns "we do not know" into a value. Five dimensions are kept apart, each with its own evidence and its own unknown, and none is derived from another:

DimensionQuestionValues
ConnectivityCan the device be reached?online, offline, unreachable, stale, connecting, unknown
FreshnessHow old is this piece of data?fresh, stale, unknown — from a timestamp and a policy you supply
AvailabilityIs there a value at all?a value, unknown (nothing reported), unavailable (the source cannot give one now), unsupported (the device does not do this)
ValueWhat is it?a number you format; never invented, never 0 for "no value"
Command lifecycleWhat happened to the request?the nine stages below
import { resolveFreshness } from "@kinetixui/iot/functions";
 
resolveFreshness({ observedAt: "2026-01-01T09:00:00Z", staleAfterMs: 30 * 60_000, now: "2026-01-01T12:00:00Z" }); // "stale"
resolveFreshness({ observedAt: "2026-01-01T09:00:00Z", now: "2026-01-01T12:00:00Z" });                            // "unknown" — no policy, no default

There is no default timeout: a soil probe reporting twice a day is not stale at noon, and an infusion pump's rate from ten minutes ago may be. Undated data is unknown, not stale and not fresh.

SituationWhat is shown
Online + stale telemetry"Online" beside a reading marked "Last known value" and "Stale" — a green dot does not make a number current
Unknown connection + known stale battery"Connection unknown" and "Battery 18 percent, low, stale reading" — neither becomes "offline"
Offline + last known telemetry"Offline, last seen 7 minutes ago" and the reading with its own freshness
Requested command + reported state unchangedThe control at the reported value; CommandFeedback "Requested, not yet confirmed … It last reported 20%"
Unsupported vs supported but no data"Battery not supported by this device" vs "Battery level unknown"

The components that present it:

ComponentTruth rules
DeviceBatteryUnknown is "—", never 0 %; charging only when reported, and 100 % implies no charger; stale never says offline; unsupported is "No battery"; thresholds are yours
DeviceConnectionSix states, six shapes, six words; connecting never looks online; unknown never says offline; no animation; transport text is yours
TelemetryMetricmetric optional; unknown, unavailable and unsupported are three words; a delta only with a real previous; a reference range is printed, never judged; formatValue and unitLabel are yours
CommandFeedbackOne line or panel over an existing lifecycle: acknowledged is not confirmed, a timeout "may still apply", unreachable is not "failed", cancel claims no rollback; announces only with announce
DeviceActivityA required order; an explicit origin (user, device, automation, system), and "Source unknown" when none was recorded — never guessed
EnergySummaryWithout summary: TelemetryMetrics for power, energy, cost and more over a period you name; no kWh, currency or "today" assumed
import { CommandFeedback, DeviceBattery, DeviceConnection, TelemetryMetric } from "@kinetixui/iot/react";
 
<DeviceConnection state="online" transportLabel="Wi-Fi via Barn gateway" />
<TelemetryMetric label="Soil moisture" value={31} unit="%" timestamp={readAt} staleAfterMs={30 * 60_000} />
<DeviceBattery value={18} updatedAt={batteryAt} staleAfterMs={6 * 3_600_000} />
<CommandFeedback lifecycle={valve} label="Zone 3 valve" formatValue={(v) => (v ? "open" : "closed")} onRetry={retry} />

TelemetryMetric reports two separate answers on its root. data-value-state is whether there is a value — known, unknown (nothing was reported), unavailable (quality missing or error, or the unavailable prop) or unsupported — and it is the one to style or test on for whether a value is there. data-reading-state is evaluateReading's judgement of the reading (normal, warning, critical, stale or unavailable), and it is the one for severity and freshness: every usable reading has data-value-state="known", so warning, critical and stale exist only here. Every missing value is unavailable in this attribute; that is why the visible word for an empty reading with no quality is "Unknown" while its reading state is still unavailable.

None of the monitoring components is a live region or offers a control; CommandFeedback adds one polite role="status" only when you pass announce (a control given the same lifecycle already announces it). No capability kind was added: a battery is telemetry with role battery.

Series, gaps and accessible summaries#

A series is analysed without interpolating over what is missing. summarizeSeries reports min, max, average and trend over the measured points and counts the rest as missing; detectSeriesGaps finds where readings were due and did not arrive; thresholdCrossings lists each time a series changed level, including recovery.

describeSeriesForAssistiveTech writes the sentence a screen reader gets for a plot, from the same functions, so the text is covered by the same tests as the classification:

import { describeSeriesForAssistiveTech, summarizeSeries } from "@kinetixui/iot/functions";
 
const series = {
  deviceId: "soil-04",
  metric: "soil-moisture",
  points: [
    { timestamp: "2026-01-01T09:00:00Z", metric: "soil-moisture", value: 41, unit: "%" },
    { timestamp: "2026-01-01T10:00:00Z", metric: "soil-moisture", value: 37, unit: "%" },
    { timestamp: "2026-01-01T11:00:00Z", metric: "soil-moisture", value: 0, quality: "missing" as const },
    { timestamp: "2026-01-01T12:00:00Z", metric: "soil-moisture", value: 29, unit: "%" },
  ],
};
 
summarizeSeries(series).trend;            // "falling"
summarizeSeries(series).missingCount;     // 1 — the point marked missing is not averaged in
describeSeriesForAssistiveTech(series);
// "Soil moisture: 3 readings from 2026-01-01 09:00 UTC to 2026-01-01 12:00 UTC. Latest 29 %. Lowest 29 %,
//  highest 41 %, average 36 %. Overall falling. 1 point has no usable reading."

TelemetryMetric renders one reading with its state, TelemetryGrid lays several out, and TelemetryTrend draws the series with a broken line at every dropout, optional threshold bands, a summary row and a "View data" table as the plot's textual equivalent.

Pairing is UI state, not a transport#

This is worth being blunt about, because the module's positioning says "pair" and that could be read as a promise it does not make. Nothing here discovers, connects to, or authenticates a device. There is no Bluetooth, no Wi-Fi provisioning and no network call anywhere in this package.

What it gives you is the vocabulary and the local logic for a pairing screen, so the screen can be built, tested and reviewed before any transport exists — and so that whichever transport you use does not invent its own word for "connecting".

Stages, methods and events#

A pairing flow has seven stages (discover, identify, authenticate, configure, assign, verify, complete) and five methods — how a person is being asked to connect: bluetooth, network, qr, manual-code and cloud. The methods are labels so a screen can choose its copy; your transport decides what actually happens and tells the flow with events.

import {
  advancePairing,
  getPairingFailure,
  pairingFlowSteps,
  startPairingFlow,
  transitionPairing,
} from "@kinetixui/iot/functions";
 
let flow = startPairingFlow();                             // { status: "idle", stage: "discover", ... }
flow = advancePairing(flow, { type: "start", method: "qr" });
flow = advancePairing(flow, { type: "next" });             // your transport reported the device was found
pairingFlowSteps(flow).map((step) => `${step.id}:${step.status}`);
// ["discover:complete", "identify:active", "authenticate:pending", ...]
 
const failed = transitionPairing(flow, { type: "fail", code: "weak-signal" });
failed.ok;                                                 // true
failed.state.status;                                       // "failed" — and the stage it failed at is kept

transitionPairing never throws: an event that is not legal for the current state comes back as ok: false with the same state and a reason, so a screen fed by an unreliable source can ignore it and keep rendering.

The failure registry#

Thirteen failures are described once, each with what to say, where it happens, whether a retry makes sense, whether a half-finished setup needs cleaning up, and the recovery actions to offer:

import { getPairingFailure } from "@kinetixui/iot/functions";
 
getPairingFailure("weak-signal");
// {
//   code: "weak-signal", title: "Signal too weak",
//   description: "The connection to the device was too weak to continue.",
//   recovery: [{ id: "retry", label: "Try again", kind: "retry" }, { id: "cancel", label: "Cancel setup", kind: "cancel" }],
//   retryable: true, stage: "identify", needsCleanup: false
// }

PairingMethodPicker, PairingStepper and PairingFailure render these. PairingFailure is a role="alert", and its recovery actions report through onAction — they change nothing on their own.

Code entry#

import { normalizePairingCode, validatePairingCode } from "@kinetixui/iot/functions";
 
normalizePairingCode("a1b-2c3");   // "A1B2C3"
validatePairingCode("A1B2C3");     // true — shape only, never correctness

validatePairingCode checks a code's shape so a form can enable its submit button. It does not transmit the code, store it, or judge whether it is the right one — only the device can do that.

Alerts and activity#

An alert is a fact a person has to own: a severity, a message, when it was raised, and optionally what raised it (source), a machine-readable kind, and one suggested action. It has three moments a screen must keep apart — raised, acknowledged (someone has seen it) and resolved (the cause is gone). Acknowledging does not resolve, and an acknowledged alert stays visible as acknowledged rather than disappearing.

import { acknowledgeAlert, sortAlerts, summarizeAlerts } from "@kinetixui/iot/functions";
 
const alerts = [
  { id: "a1", deviceId: "d1", severity: "warning" as const, message: "Low battery", raisedAt: "2026-01-01T09:00:00Z" },
  { id: "a2", deviceId: "d2", severity: "critical" as const, message: "Pressure high", raisedAt: "2026-01-01T08:00:00Z" },
];
 
sortAlerts(alerts).map((a) => a.id);   // ["a2", "a1"] — unresolved first, then loudest, then unacknowledged
summarizeAlerts(alerts).description;
// "2 open alerts on 2 devices: 1 critical, 1 warning. 2 not yet acknowledged."
acknowledgeAlert(alerts[1]!, "2026-01-01T12:00:00Z"); // a copy with acknowledgedAt set; nothing is mutated

AlertList renders a triaged, optionally per-device list with a summary line; AlertCard renders one, with kind, source, action and an acknowledged or resolved state. Severity is a glyph and a word. The callbacks (onAcknowledge, onAction) report intent — your application decides what acknowledging does. ActivityTimeline renders what happened, grouped by day: commands (with their lifecycle status, so a requested entry reads “Requested, not yet confirmed” and cannot be mistaken for a result), state changes, alerts, automation and firmware. Live-region announcements are rare on purpose; a list is not announced when it changes. DeviceActivity is one device's history in an order you choose, with each event's origin — user, device, automation or system — and "Source unknown" when your log did not record one.

Automation#

An automation is a rule: one trigger, any number of conditions joined by and / or, and one or more actions. The module models the rule and edits it. It does not run it. There is no engine, no scheduler and no trigger evaluation in this package; your application owns execution.

import {
  summarizeAutomationRule,
  validateAutomationRule,
  type KinetixAutomationRule,
} from "@kinetixui/iot/functions";
 
const rule: KinetixAutomationRule = {
  id: "irrigate-zone-3",
  name: "Irrigate when dry",
  enabled: true,
  trigger: { type: "sensor", subject: "soil-moisture", scope: "zone-3", operator: "lt", value: 28, unit: "%" },
  conditions: [],
  actions: [{ id: "open-valve", target: "valve-03", command: "open", durationMinutes: 20 }],
};
 
validateAutomationRule(rule);   // [] — no issues
summarizeAutomationRule(rule);  // "When soil moisture falls below 28% in zone 3, open valve 03 for 20 minutes."
validateAutomationRule({ ...rule, name: "", actions: [] });
// [{ path: "name", code: "missing-name", ... }, { path: "actions", code: "missing-action", ... }]

Validation returns issues with a path and a code, never an exception, so a form can point at the field. summarizeAutomationRule reads a rule back as a sentence and takes a label callback so subjects and targets read as your product names them. AutomationRuleView shows a rule read-only. AutomationBuilder is a keyboard-operable form over the same structure: you pass the subjects and targets your product offers, and it reports a new rule through onChange and onSubmit. It runs its own validation, shows the issues inline and keeps one polite status region.

RoutineCard and the older KinetixAutomation type describe a scene, routine or schedule that your engine already populates — a name, a status, a last and next run. That is presentation of state, not a scheduler.

Grouping and hierarchy#

A connected product organises devices into places, and every product names the levels differently. So the levels are not modelled. There is one node type, a kind string your product fills in, and a parentId; depth is whatever the data says it is. The module's tests build all four of the shapes below, and none of the level names is built in:

ProductLevels
Smart spaceHome → Floor → Room
AgritechFarm → Field → Irrigation zone
OperationsOrganization → Site → Line → Machine
Commercial propertyPortfolio → Site → Building → Zone
import { buildSpaceTree, describeSpaceRollup, rollupSpaceHealth, spacePath } from "@kinetixui/iot/functions";
 
const tree = buildSpaceTree([
  { id: "farm", name: "Demo Farm", kind: "farm" },
  { id: "gh-a", name: "Greenhouse A", kind: "field", parentId: "farm" },
  { id: "zone-3", name: "Irrigation Zone 3", kind: "irrigation-zone", parentId: "gh-a", deviceIds: ["valve-03", "soil-04"] },
]);
 
spacePath(tree, "zone-3").map((p) => p.name);  // ["Demo Farm", "Greenhouse A", "Irrigation Zone 3"]
 
const rollups = rollupSpaceHealth(tree, [
  { id: "valve-03", name: "Valve 03", type: "valve", status: "online" },
  { id: "soil-04", name: "Soil sensor 04", type: "soil-sensor", status: "offline" },
]);
describeSpaceRollup(rollups.get("farm")!); // "1 of 2 healthy, 1 warning, 1 offline."

buildSpaceTree never throws on bad input: a duplicate id, an orphan or a cycle is worked around and reported in tree.issues. A rollup exists at every level and follows the exclusive-bucket rule above. SpaceBreadcrumb renders a path, SpaceRollup a rollup, and DeviceGroupCard takes path and rollup slots. The tree is a description to render and roll up. It is not a permissions model, a device registry or a schema.

Energy#

summarizeEnergy takes the per-device figures your application already has and returns a total, each item's share and rank, and an optional comparison with a baseline. energyTrend reads a list of daily totals as rising, falling, steady or unknown.

import { energyTrend, summarizeEnergy } from "@kinetixui/iot/functions";
 
const energy = summarizeEnergy([{ id: "heater", label: "Heater", value: 6 }, { id: "fridge", label: "Fridge", value: 2 }], { unit: "kWh" });
energy.total;                        // 8
energy.top[0]?.share;                // 0.75
energyTrend([3, 4, 5, 6]).direction; // "rising"

EnergySummary displays these. It is display only: it computes no billing, cost, carbon estimate or forecast, and every number comes from your application. Without a summary it is a set of TelemetryMetrics — power, energy, a cost you computed and formatted, and anything else — over a period you name; see Monitoring truth model.

Camera pattern#

CameraDeviceCard is a device card for a camera, and it never shows or implies a live feed. There is no <video>, no stream, no player and no request. The picture is a poster slot your product fills (or a placeholder that says “no live feed”), the privacy and recording states are plain words, and lastEvent says what happened and when. It is the camera's state, not the camera's output.

Known limitations of the model#

  • status is one field, so a device has one state. A device that is reachable and reporting a fault is error or online, not both. That is deliberate — a single field is what a list row can sort and render — but it means product-level nuance belongs elsewhere: alerts carry severity independently, and needsAttention exists so a fleet view can emphasise without collapsing.
  • Statuses mix concerns on purpose. online/offline is a link fact, stale is about the data, syncing/updating/pairing are activities and disabled is configuration. They share one union because a device row shows one badge. If you need two axes, keep the second one yourself.

Utilities#

Every function is pure and deterministic, and every time-dependent one takes an injectable now.

import {
  classifyBatteryLevel,
  classifySignalStrength,
  compareFirmwareVersions,
  detectStaleReading,
  formatLastSeen,
  formatTelemetryValue,
  normalizeDeviceStatus,
} from "@kinetixui/iot/functions";
 
normalizeDeviceStatus("CONNECTED");        // "online"
normalizeDeviceStatus("ota");              // "updating"
normalizeDeviceStatus("something else");   // "offline"  (and isKnownDeviceStatus() is false)
 
classifyBatteryLevel(72);                  // "high"
classifyBatteryLevel(null);                // "unknown"  — not "critical"
 
classifySignalStrength(0);                 // "none"     — reported, and zero
classifySignalStrength(undefined);         // "unknown"  — not reported
 
formatLastSeen(fiveMinutesAgo, { now });   // "5m ago"
formatLastSeen(null);                      // "Never"
 
detectStaleReading(undefined, 60_000);     // true       — freshness is a claim
formatTelemetryValue({ value: 0, quality: "missing" }); // "Unknown" — never "0"
 
compareFirmwareVersions("1.9.9", "1.10.0"); // -1        — numeric, not lexical
compareFirmwareVersions("R3.2", "1.0.0");   // null      — not 0

"We do not know" survives#

That is the rule running through all of it. A device that does not report a battery is not a device with a flat one. An undated reading is not a fresh one. A firmware pair that cannot be compared is not up to date. Each of those is a place where a convenient default becomes a lie the interface tells about someone's hardware, so unknown is a first-class result rather than a fallback — and isKnownDeviceStatus exists so that the information normalizeDeviceStatus discards stays reachable.

Documented limitations#

  • Signal is a normalised 0–100 quality, not dBm. dBm ranges differ per radio — Wi-Fi, LTE, LoRa and BLE do not share a usable scale — so banding dBm would mean guessing the radio. That conversion belongs in the product, next to the radio it knows about.
  • Firmware comparison ignores prerelease tags. 1.4.0-rc.2 and 1.4.0 compare equal. Device firmware strings are rarely semver (1.04, 2.1.3.7, R3.2 all occur), so a strict parser would reject more real versions than the loose comparison gets wrong, and no semver dependency is added.
  • formatLastSeen stops at days. A year-old reading reads 400d ago, not 1y ago. Month arithmetic needs the locale rules this deliberately avoids.
  • buildDeviceCommand requires an id. Generating one would make the function non-deterministic, and products almost always have an id they need to correlate with.

React primitives#

import {
  BatteryIndicator,
  DeviceStatusBadge,
  LastSync,
  SensorReading,
  SignalStrength,
} from "@kinetixui/iot/react";
 
<DeviceStatusBadge status="online" />
<BatteryIndicator value={72} />
<SignalStrength value={84} />
<LastSync value={device.lastSeenAt} />
<SensorReading metric="Temperature" value={23.4} unit="°C" />

Ten primitives in all: those five, plus DeviceIcon and DeviceIdentity (a device's category, drawn with its state carried on the icon tile), MetricStatus (a reading's state as a glyph and a word), DeviceBattery and DeviceConnection (see Monitoring truth model). Each accepts className and forwards the rest of its props, and each emits a data- attribute for the value it resolved — data-status, data-level, data-quality — so a product can restyle per state without this module growing a variant API.

There is no size-variant prop. These are single-line readings that inherit their type scale from the surrounding text, and a variant matrix would be eight APIs to maintain for a choice CSS already makes.

Four levels, and when each is the right one#

The React surface has three layers, and the website carries a fourth. Knowing which one you are reaching for saves rebuilding something that already exists — or importing something larger than the job.

LevelWhat it isWhere it livesReach for it when
PrimitivesOne fact, rendered@kinetixui/iot/reactYou are laying out your own card and need the status, battery, signal, timestamp, reading or identity inside it
ControlsOne thing a user can change@kinetixui/iot/reactThe user needs to operate the device, not just read it
PatternsA composition of the above, plus a rule or two@kinetixui/iot/reactYou are building the arrangement every device product builds and would otherwise rewrite it
ExamplesA whole screen, assembled from patternskinetixui.com/iot — copy, do not installYou want a starting layout for a fleet view, a detail panel or an alert list

Primitives, controls and patterns are all published API. Examples are not: they are source on the website, meant to be read and copied into your own codebase, because a screen layout is where your product's decisions live and importing someone else's is rarely the shortcut it looks like.

Controls#

A control is the part that makes this a connected-device system rather than a dashboard. All seven share one rule, and it is the rule most device UIs get wrong:

What the user asked for is drawn differently from what the device has confirmed.

A switch that slides over and fills in the instant you touch it is telling you the device is on. It does not know that. On a lamp the lie is harmless; on a door lock or an irrigation valve it is not, and the user finds out minutes later. So a requested state and a confirmed state never look the same:

ControlConfirmedRequested, not yet confirmed
DevicePowerControlTrack filled, knob solidSwitch stays at the reported state, track outlined dashed, label says “Turning on”
DeviceLevelControlSolid fill to the valueHatched fill to the requested value, solid fill left at the confirmed one
DeviceSetpointControlTarget shown plainlyTarget tinted, with the current reading still visible beneath it
DeviceModeControlMode filledMode outlined and dashed, never filled
DeviceColorControlPreview and checked swatch are the reported colourRequested swatch dashed and named "requested, not yet confirmed"
DeviceLockControl"Locked" and a closed padlock — only when the device reports lockedThe reported state, with "Locking, not yet confirmed" beside it. optimistic is not accepted
DeviceMediaControlPlayback, position and volume as the device reports them"Starting playback, not yet confirmed"; a requested seek or volume drawn apart from the reported one

DeviceMediaControl carries no media: every action — play, pause, seek, volume, mute, previous, next — is a callback to your code, and there is no <audio>, <video>, stream or player in the package.

That is the default, strategy="confirmed". Every control also accepts strategy="hybrid", where the control moves to the request but stays marked as unconfirmed (the power knob hollow, the confirmed mark withheld), and strategy="optimistic", which moves without the mark and rolls back in words if the request fails.

The same distinction reaches assistive technology rather than being a visual flourish: aria-checked on the power switch reports the confirmed state while a request is open, and the slider's aria-valuetext names both numbers.

resolveControlState#

Controls do not each decide what "offline" or "pending" means. resolveControlState takes a device status and an optional command status and returns one answer:

import { resolveControlState } from "@kinetixui/iot/functions";
 
const control = resolveControlState({
  deviceStatus: device.status,
  commandStatus: pendingCommand?.status,
});
 
<DevicePowerControl state={device.power} requested={requested} control={control} label={device.name} />;

Its precedence is fixed so that five controls on one screen cannot disagree:

  1. An explicit disabled wins over everything.
  2. Device status outranks command status — a command cannot be meaningfully pending on a device that is offline.
  3. A command in flight is pending, and pending is not interactive: a second press while the first is unresolved is how users end up toggling a device twice.
  4. stale stays interactive. Sending a command is exactly how you find out whether a quiet device is still there, so stale must not lock the control the way offline does.

An unreported or unreadable status resolves to unknown — "Device status unknown", never "Device offline" — and an unknown control still does not accept input. unreachable and connecting keep their own words, and an optional connectivity input lets the link's own state decide.

Composition over configuration#

DeviceControlCard takes slots — primaryControl, statusLine, meta, expanded — rather than a prop per control. The alternative is onToggle, level, onLevelChange, mode, modes, onModeChange, setpoint… and it would still not fit the fourth product that arrives with a control nobody predicted.

<DeviceControlCard
  device={device}
  active={device.power === "on"}
  control={control}
  statusLine="Warming to 21°"
  primaryControl={<DevicePowerControl state={device.power} control={control} label={device.name} />}
  expanded={<DeviceLevelControl value={device.level} control={control} label="Brightness" />}
/>

Expanded content is unmounted while collapsed, so a grid of twenty cards does not carry twenty sliders it is not showing.

The library owns no vocabulary#

Mode labels come from you. There is no built-in "heat" | "cool" | "auto", because the same control serves a thermostat, an irrigation valve and a conveyor, and a library that ships one domain's words is wrong for the other two. The same applies to groups: DeviceGroupCard takes a kind string, so a home calls it a room, a farm calls it a zone and an operator calls it a site.

Unavailable modes stay visible and aria-disabled rather than disappearing — a mode that vanishes cannot explain why it is gone.

Commands are sent on release#

DeviceLevelControl composes a real input[type="range"] rather than reimplementing a slider, so keyboard, pointer and assistive technology behave exactly as the platform does. It reports a live value through onPreview and commits through onCommit on release — one command per drag rather than one per animation frame, which on a real gateway is a real cost.

Patterns#

29 compositions, each built from the primitives and controls above rather than re-deriving their semantics — so what "stale" means is decided once and every one of them agrees.

import {
  AlertList,
  CommandLifecycle,
  DeviceCard,
  DeviceHealthSummary,
  TelemetryGrid,
  TelemetryTrend,
} from "@kinetixui/iot/react";
MomentPatternsAnswers
A deviceDeviceCard, DeviceListItem, DeviceControlCard, DeviceStateSummaryWhat is this device doing, and what can I do about it?
Connection and firmwareConnectionHealth, FirmwareStatusWhy can I not reach it, and what version is it on?
A change settlingCommandLifecycle, CommandStatus, CommandFeedbackWhere did the command I sent get to?
A readingTelemetryMetric, TelemetryGrid, TelemetryCard, TelemetryTrendWhat is it, how much should I trust it, and what has it been doing, including where it stopped?
Alerts and historyAlertList, AlertCard, ActivityTimeline, DeviceActivityWhat is wrong, has anyone looked, and what happened, caused by whom or what?
Places and healthDeviceGroupCard, DeviceHealthSummary, SpaceBreadcrumb, SpaceRollupHow is this room, zone, line or site doing?
AutomationAutomationRuleView, AutomationBuilder, RoutineCardWhat will happen, and when? (The rule is edited here and run by you.)
Adding a devicePairingMethodPicker, PairingStepper, PairingFailureHow is setup going, and what next if it fails?
Two device familiesCameraDeviceCard, EnergySummaryA camera that is never a feed; energy that is never a bill.

Two rules the patterns add#

A device in transition does not show its last value. DeviceCard and DeviceListItem suppress the reading while a device is syncing, pairing or updating, showing the state where the number would be. A value rendered beside "Updating" is read as the current value, and it is not.

A dropout is drawn as a dropout. TelemetryTrend breaks the line at any point whose quality is missing or error and never interpolates across it. A straight line between two readings an hour apart is a claim that the sensor was answering in between, which is the claim quality exists to prevent. The bounds are printed as text beneath the plot, so the chart's textual equivalent is what everyone reads rather than a hidden description that can drift out of step.

Composition, not configuration#

DeviceCard takes an action node and decides where it goes; it has no onToggle, onPower or onRun. What a control does implies a transport, and this module has none — so the card owns the position and your product owns the behaviour.

Two candidates were evaluated and deliberately left out. A QuickAction would duplicate @kinetixui/ui's Button in a package that cannot depend on it. A DeviceDetailHeader is a layout arrangement rather than a semantic one, which makes it an example rather than an API.

Motion#

The patterns transition colour on state change, and an in-flight command carries a pulse. Both use Tailwind's own motion-reduce: variant, so a reader who asks for reduced motion gets the static version with no stylesheet to copy and no page-level rule to remember. Nothing loops, nothing moves a layout, and no animation carries information that is not also written down.

Accessibility#

Every primitive renders its fact as text, so the reading survives greyscale, forced-colors mode and a screen reader. Colour is always a second encoding of something already written down.

Where a visual shorthand is used — a battery bar, a signal meter, 5m ago — the visuals are hidden from assistive technology and the full sentence is supplied as the accessible name. Nothing is announced twice, and nothing is announced only as an abbreviation.

Online
Battery 72%, high
Signal 84%, excellent
Last seen 5 minutes ago
Temperature 23.4 °C

Those sentences come from the pure half — describeDeviceStatus, describeBattery, describeSignal, describeLastSeen — so the text a screen reader receives is covered by the same unit tests as the classification, and a non-React consumer can render it.

Missing values are stated rather than implied: Battery level unknown, Signal strength unknown, Never seen, No reading. LastSync renders a <time> whose dateTime is omitted rather than left blank when there is no instant to state.

No primitive animates, so there is nothing for prefers-reduced-motion to suppress — asserted in the test suite, not assumed. See Accessibility for how the rest of the library is verified.

State is never colour alone#

Status, severity and reading state are each a glyph with its own silhouette and a word, and offline is a dashed edge as well as a muted one. A requested value and a confirmed one differ by shape and text, not by hue.

Live regions are rare#

CommandLifecycle and AutomationBuilder each have one polite role="status"; PairingFailure is a role="alert"; a device control given a lifecycle has one polite role="status", and CommandFeedback has one only when given announce. Nothing else announces, and a live region announces changes, so nothing is spoken on first render.

Charts and scroll regions#

TelemetryTrend prints its bounds and a summary as text and offers a "View data" table, so the plot is never the only way to reach a number. Any region that scrolls horizontally must be focusable and named; the website's examples use role="region", an accessible name and tabindex="0".

Right-to-left#

The components use logical properties (ms-, ps-, text-start) rather than left and right, so a right-to-left page mirrors without a second stylesheet, and DevicePowerControl reverses its knob travel with Tailwind's rtl: variant. Two deliberate exceptions keep their direction: the time axis of TelemetryTrend stays left-to-right, because time is drawn one way on a plot in every reading direction, and identifiers, code and units should be wrapped in dir="ltr" inside right-to-left text. If you set dir on a Radix-based wrapper of your own, pass it through so arrow keys follow the reading order.

Simulation#

The website's demos are driven by a small deterministic simulation that lives in the website's source, not in @kinetixui/iot. It exists so that a demo can show a command settling, a sensor drifting past a threshold or a device going quiet without a device. It is demo state, and every page that renders it says so with the same disclosure sentence:

Simulated — no device is contacted. Readings, commands and delays are scripted in your browser; nothing is sent over a network.

What it is, and is not:

  • Deterministic. A scenario is data (devices, spaces, sensors, latencies, scripted events). Readings are a pure function of a seed, a sensor and elapsed time, from a seeded generator, so a given scenario and seed produce the same numbers every time.
  • An injected clock. The simulation never reads the time itself. Its state advances when a caller passes it a time, which is how the tests run it without waiting and how the React hook drives it from performance.now. The first render is at the scenario's fixed start time, so server and client agree, and time only advances after mount.
  • It models the honest lifecycle. A command runs through the real @kinetixui/iot lifecycle machine — requested, acknowledged, confirmed — with per-device latency, and a device can be flaky (fail its first commands), slow, or unreachable, in which case the command times out.
  • Not an automation engine. Where a scenario shows an automation firing, the event is a scripted entry that says “Scripted demo event — KinetixUI has no automation engine, so no rule was evaluated.”
  • Not a transport, and not a test double for one. It is not exported, not published and not something to build a product on. Your application supplies the real thing.
  • Reduced motion. Under prefers-reduced-motion ambient drift stops; a command you issued still settles.

Reference environments#

Three environments are published on the overview page as source to copy. Each is a fabricated scenario — nothing was measured and no device exists — and each carries the simulation disclosure.

EnvironmentLevelsWhat it exercises
Smart spaceHome → Floor → RoomLight, thermostat, plug and lock controls; air quality; a sample camera frame with no feed; energy; alerts; scenes
AgritechFarm → Field → Irrigation zoneSoil and climate readings; a soil-moisture trend against its threshold; valve and pump controls with a flaky valve; an irrigation rule
OperationsOrganization → Site → Line → MachineFleet and equipment health with a rollup at every level; energy; faults; command history

They are compositions, not components: read them, copy what fits, and replace the scenario with your own adapter. Alongside them the site publishes compositions for the moments above — a state-honesty demo, telemetry history, an alert centre, the automation builder, a pairing flow and a pump-station device detail — and the earlier fleet, dashboard, connected-space, telemetry-board, alert-inbox and connection-troubleshooting layouts.

Maturity#

The maturity programme so far, each step in this repository with its tests and browser gates (the audit):

  • M1 ✅ the device interaction contract: requested vs reported, correlation, report ordering, strategies.
  • M2A ✅ the four original controls on that contract, with confirmed, optimistic (with rollback) and hybrid.
  • M2B ✅ colour, lock and media controls; a missing status is unknown, not offline.
  • M3 ✅ monitoring and feedback: battery, connection, telemetry, command feedback, activity, energy, freshness.

Roadmap#

Nothing here is scheduled, and none of it is in the module today.

  • M4 Device Integration: lifecycle hardening (M4A), device ledger (M4B), and application-side provider validation (M4C). Live-provider and physical-device proof remain pending.
  • M5 native parity and an Angular reassessment; no native or Angular IoT code exists yet.
  • M6 reference experiences.
  • M7 Camera, Security & Spatial presentation, with no video engine.
  • A grouped or scheduled command queue — genuinely useful and genuinely a product concern. Modelling it here risks becoming the engine this module refuses to be, so it waits for a real product's requirements.

Transports, an automation engine and video are not roadmap items: they are outside what this module is.