Core Concepts
The words the rest of the docs assume you know.
Identity & data model
A workspace grouping devices, datastreams, dashboards and members. Every device belongs to exactly one project.
One physical (or logical) piece of hardware, with its own credential, reporting one or more signals.
How a device connects: a username (the device short id, which must also be the MQTT clientid), a dvp_ password, and a short opaque topic_id that roots the device's topics. The password doubles as the key that HMAC-signs every payload - one secret, not two. Issued per device; regenerating invalidates the old password, and its signing key, immediately. The topic_id can be rotated on its own.
The older per-device credential (dvk_ prefix). It is still accepted as an MQTT password - and then as the signing key - for firmware that cannot be reconfigured. New devices should use the MQTT credential above instead. Regenerating invalidates the old key immediately.
A signal is one named value a device reports (temperature, door_open). A datastream is that signal's server-side metadata: type, unit, readable/writable/observable, bounds, stale threshold.
Protocol & data
A timestamped set of signal values sent in one message. A value may be a number, an integer, a boolean or a string, each with an optional unit and quality flag. Wire format: <a href="/docs/mqtt">MQTT protocol reference</a>.
The device transport: one TLS MQTT connection carrying many signals across many measurements, plus a command channel back. Authentication happens inside CONNECT, and every payload is HMAC-signed with the connection password. See the <a href="/docs/mqtt">MQTT protocol reference</a>.
A per-device integer that must strictly increase, forever - the replay defence. The server remembers the highest value it accepted, so anything less than or equal to it is silently dropped. Seed it from the wall clock, never from zero.
UTC, ISO-8601. A measurement carries when it was observed on the device; the server records when it was received - so buffered telemetry still lands at the right time.
Each value can carry a unit string (C, %). The datastream can define a canonical unit for consistent charting and export.
Quality flags
Every value carries a quality flag:
| valid | a normal, trustworthy reading (the default) |
| stale | older than expected for this signal; the sensor may not have refreshed recently |
| uncertain | the device itself isn't confident (warming up, out of calibrated range) |
| error | the device couldn't obtain a real reading; don't trust the value |
Control
Desired = what someone wants a writable datastream to become ("turn this relay on"). Reported = what the device says it actually did. Tracked separately: setting desired state doesn't mean the physical action happened.
A request to change a writable datastream's desired state. Acceptance means the request was stored - not that the device received or applied it.
cmd topic and answer on cmd/ack - see the <a href="/docs/mqtt#msg-cmd">MQTT protocol reference</a>. Do not assume a 201 from the commands endpoint means a relay actually flipped; wait for the command's result.