PureLife Device Messaging Protocol

Part of: PureLife Device Protocol Version: 1.0 (Draft 0.1, 2026-09-17)

This document specifies how a provisioned Device communicates with its Server during normal operation. It has two transports:

The PureLife Device Protocol Reference (OpenAPI and AsyncAPI) is the reference for message formats. This document holds the normative text that does not fit into them: the trust model, certificate requirements, the assertion format, and the behaviour rules for the Device.

Contents

1. Base URL and versioning
2. Trust model
3. Manufacturer CA
4. Device certificate
5. Device key
6. Authentication
7. Access token
8. Bootstrap
9. Firmware update
10. Pairing token
11. Device behaviour
12. Requirements for the Manufacturer
13. MQTT: topics and session
14. MQTT: status and Last Will
15. MQTT: configuration
16. MQTT: logging
17. MQTT: commands
18. MQTT: telemetry
19. MQTT: room configuration
20. MQTT: events

1. Base URL and versioning

All HTTP operations are relative to the Server URL the Device received during provisioning (field server_url of endpoint pld-config of the Device Provisioning Protocol). The Server URL is an origin with an optional path prefix and without trailing slash, for example https://cloud.smart-altern.de. In URL templates below it is written {serverUrl}. Neither the Device nor the Server normalises the Server URL: the Device uses it byte for byte as provisioned (the Provisioner already rejects a trailing slash), and the Server compares the aud claim byte for byte with the URL it is configured with.

Every path of this protocol starts with /pld/v1. The v1 is the MAJOR version of the Device Messaging Protocol. A new MAJOR version gets a new path prefix. MINOR versions add fields and operations without changing the prefix.

POST {serverUrl}/pld/v1/auth
PUT  {serverUrl}/pld/v1/firmware
GET  {serverUrl}/pld/v1/bootstrap
POST {serverUrl}/pld/v1/pairing-token

1.1 Transport security

Both transports work with and without TLS. The scheme of the provisioned Server URL (https or http) and of mqtt.url from the bootstrap response (mqtts or mqtt) decides. The Device MUST support both.

• With TLS the Device validates the Server or broker certificate against its store of public CA certificates and MUST NOT skip that validation.
• Without TLS all traffic, including credentials, tokens and measurement data, is unencrypted and the Device cannot verify the identity of the Server or broker. The operator of the Server chooses this mode and is responsible for the security of the network. Typical use: an isolated internal network or a development environment.

2. Trust model

Three parties hold key material:

The chain of trust:

1. The Manufacturer creates a self-signed Manufacturer CA certificate and hands the certificate (not the key) to PureSec. PureSec embeds it in the Server.
2. During production the Device generates its key pair. The Manufacturer issues a Device certificate for the Device public key, signed with the CA key. The certificate binds the public key to the Device ID and the Manufacturer identifier.
3. When the Device authenticates, it presents the Device certificate and a JWT signed with its private key. The Server validates the certificate against the Manufacturer CA, validates the JWT with the public key from the certificate, and issues an access token.

The PoP of the Device Provisioning Protocol plays no role here.

3. Manufacturer CA

A Manufacturer MAY use an intermediate CA. In that case the intermediate certificate is part of the chain the Device presents (see section 6.2), and only the root is embedded in the Server.

A Manufacturer MAY have several CA certificates at the same time, for example during a key rotation. The Server accepts a Device certificate if it chains to any CA certificate registered for that Manufacturer.

4. Device certificate

The Server does not use CRLs or OCSP. A Device is revoked by blocking it on the Server.

5. Device key

• The Device key pair MUST be generated on the Device. The private key MUST never leave the Device. Only the public key is exported for certificate issuance.
• The private key MUST survive a Factory Reset and firmware updates. It is part of the Device identity, not of the provisioned data.
• The private key MUST be protected at rest. Where the platform offers a hardware key store, it SHOULD be used (for example the ECDSA peripheral with the key in eFuse on ESP32-H2, C5, C6 and P4). Otherwise the key MUST be stored encrypted (on ESP32: flash encryption together with NVS encryption; on Linux-based Devices: a secure element or TPM, and at the very least file permissions that restrict the key to the Device software).
• One key pair per Device. A Device MUST NOT share its key with another Device.

6. Authentication

POST {serverUrl}/pld/v1/auth exchanges a signed assertion for an access token. The operation is unauthenticated at the HTTP level; the assertion carries the authentication. Request and response formats are defined in Reference, HTTP part.

6.1 Request

{ "assertion": "<compact JWS>" }

The body MUST NOT exceed 8192 bytes; a larger body is answered with 413.

6.2 Assertion

The assertion is a JWT (RFC 7519) in compact JWS serialisation (RFC 7515), modelled on the client assertion of RFC 7523. It is signed with the Device private key and carries the Device certificate chain in its header. Header parameters, claims and their constraints are defined in the Reference, HTTP part, operation Authenticate a Device.

Rules:

• The assertion proves two things at once: that the Manufacturer vouches for the key (certificate chain in x5c) and that the Device holds the private key (signature). The device claim carries the identity data of pld-info, so that it is signed as well.
• iat and exp are in seconds, as required by RFC 7519. All other timestamps in the PureLife Device Protocol are milliseconds.
• An assertion is valid for at most 5 minutes and is used once; the Server rejects replays by jti.
• The Device MUST have synchronised its clock (NTP) before it creates an assertion. An assertion with a wrong clock fails with assertion_expired or assertion_not_yet_valid.

6.3 Server verification

The Server performs these checks in order and rejects at the first failure with the listed error code:

On success:

• If the Device was unknown, the Server creates it in state unpaired and stores its public key.
• The Server stores the Device information from the device claim.
• The Server issues an access token.

A Device that fails check 11 stays usable with its stored key. An administrator can accept the new key on the Server.

6.4 Response

{ "access_token": "<opaque>", "token_type": "Bearer", "expires_in": 3600 }

expires_in is the lifetime in seconds from the moment of issue. The value is a Server setting; the default is 3600. The Device MUST NOT assume a fixed lifetime.

7. Access token

• The access token is opaque to the Device. It is at most 4096 bytes.
• The Device sends it on every other HTTP request of this protocol as Authorization: Bearer <access_token>.
• The Device holds the token in memory. It MAY persist it. It MUST request a new one when expires_in has elapsed or when any request answers
• There is no refresh token. Renewal is a new authentication.

8. Bootstrap

GET {serverUrl}/pld/v1/bootstrap returns everything the Device needs to start operating: the Server time, the pairing state and the MQTT connection data. Fields: Reference, HTTP part.

The request carries no data about the Device. The Server identifies the Device by the access token and already holds its identity, public key and the values of the device claim from the authentication (section 6.2). The device object in the response is an echo of that identity for the Device to verify.

Rules:

• Every bootstrap rotates the MQTT password. The credentials returned by the latest bootstrap are the only valid ones.
• The Device MUST persist the mqtt object immediately after receiving it and MUST use the most recently persisted values, unchanged, for every MQTT connection: client identifier, credentials, keep-alive, will delay and session expiry.
• The Device has exactly one MQTT session at a time. A new connection with the same client identifier replaces the old one on the broker.
• The Device MUST run a bootstrap before it connects to the broker. It MUST NOT run a bootstrap while an MQTT session is up: that would rotate the credentials of the running session and write to persistent storage for nothing.
• device.paired is informational. The Device behaves the same whether it is paired or not.

9. Firmware update

Every Device supports firmware updates over HTTP. The update check runs in the start-up sequence before the bootstrap, so a Device only connects to the broker with the firmware the Server expects. It also runs on the command firmware-check and at least once every 24 hours while the Device is operating (authenticating first if the access token has expired; a bootstrap is not part of that periodic check).

9.1 Check

PUT {serverUrl}/pld/v1/firmware, with the access token. The Device reports its installed components, the Server answers with the updates to install. Fields: Reference, HTTP part, operation Report firmware and get updates.

Rules:

• Firmware is organised in components with a Manufacturer-defined id, for example mcu, radar or ble. The component mcu is mandatory: it is the main controller firmware, and its version is the firmware version of the Device. Which other components exist is up to the Manufacturer.
• Versions are opaque strings. Only the Server decides whether an update is due; the Device MUST NOT compare versions. It installs what the Server returns.
• For every component the Device reports the outcome of its last installation attempt (lastUpdate), so that the Server can react to failures instead of offering the same update again and again.
• The Server answers with updates, in installation order, or with an empty list when the Device is up to date. Every entry carries a signed download URL with its expiry, the size and the SHA-256 of the file.
• A check that fails with an HTTP or network error is retried like any other request (section 11.3). The Device does not continue with the bootstrap until a check has succeeded.

9.2 Installation

• The Device MUST install every update the Server returned before it continues with the bootstrap. It MUST NOT connect to the broker while updates are pending.
• A Device that can install several components in one go installs them in the given order. A Device that cannot installs the first entry it can, restarts, and repeats the start-up sequence (authentication and check) until the Server returns no updates.
• Download: GET of the signed URL, without any Authorization header, before expiresAt. The scheme follows section 1.1. The Server supports HTTP Range requests; the Device MAY resume an interrupted download.
• Before installing, the Device MUST verify the SHA-256 of the downloaded file. It SHOULD additionally verify a Manufacturer signature of the firmware (secure boot); the format of that signature is up to the Manufacturer.
• A failed update MUST be rolled back to the previous firmware and reported in the next check as lastUpdate with result failed and a reason. An update has failed when the download, the verification or the writing fails, when the new firmware does not boot (crash, watchdog, or the start-up sequence cannot be started), or when the new firmware has not completed one successful authentication within 30 minutes after the restart despite repeated attempts. A Server that is unreachable for that long causes a rollback as well; the Server then offers the update again at the next check, which is harmless.
• After a successful installation the Device restarts where necessary and runs the start-up sequence from the beginning. It does not report success explicitly; the next check shows the new versions.
• While an update is downloaded or installed, the Device shows the LED state Firmware update in progress (section 11.4).

An update can also be triggered from the Server at any time with the command firmware-check (section 17.7).

10. Pairing token

POST {serverUrl}/pld/v1/pairing-token creates a pairing token. The Device requests it when the Provisioner sends StartPairingCommand (Device Provisioning Protocol, section 11). The operation requires an access token and has no request body. Response format: Reference, HTTP part.

{ "token": "<43 characters base64url>", "expiresAt": 1758096600000 }

Rules:

• The token consists of 32 random bytes, encoded as base64url without padding (43 characters). The Server stores only a hash of it, bound to the Device ID.
• The token expires 10 minutes after issue. expiresAt (Unix milliseconds) is authoritative; the lifetime is a Server setting.
• A new request invalidates the previous token of the Device. Redeeming a token consumes it. Blocking the Device deletes its token.
• The request is allowed whether or not the Device is paired, because pairing a paired Device moves it to the new Customer.
• The Server accepts at most one request per Device every 10 seconds and answers 429 otherwise.
• The Device passes token and expiresAt to the Provisioner unchanged. It MUST NOT log the token and MUST discard it when the provisioning session ends.

Redeeming the token is not part of this protocol. The Provisioner sends the token and the Device ID to the PureLife Cloud API (operation Pair a sensor), authenticated as a user; the Server pairs the Device with that user's Customer. A Device that is paired with another Customer is moved without further confirmation. The Device is not informed actively; it sees the result in device.paired on its next bootstrap.

11. Device behaviour

11.1 Start-up sequence

1. Connect to Wi-Fi.
2. Synchronise the clock with an NTP server (configured, from DHCP, or Manufacturer default; Device Provisioning Protocol, section 9.2).
3. POST /pld/v1/auth.
4. PUT /pld/v1/firmware. If the Server returns updates: install them, restart, start again at step 1 (section 9).
5. GET /pld/v1/bootstrap, persist the MQTT credentials.
6. Connect to the broker (MQTT part of this protocol).

11.2 When to authenticate again

The Device authenticates only when it needs an access token. An expired token by itself is no reason to authenticate, and a running MQTT session is never touched by an authentication.

The Device MUST NOT authenticate more often than necessary. In particular it MUST NOT authenticate before every request.

11.3 Error handling

Every non-2xx response carries an error body in the form of the Google JSON Style Guide: error.code repeats the HTTP status, error.message is human readable, and error.errors[0].reason is the machine-readable reason. The reasons are listed in section 6.3 and in the OpenAPI document.

{ "error": { "code": 401, "message": "signature verification failed", "errors": [ { "reason": "invalid_signature" } ] } }

Backoff: exponential, starting at 5 seconds, doubling, capped at 5 minutes, with a random jitter of ±20 % on every step.

11.4 LED

In addition to the LED states of the Device Provisioning Protocol:

system.ledEnabled = false switches the LED off in Operating altogether; the fall pattern is then not shown either.

11.5 Sound

The Device has a speaker for system sounds. Which sounds exist and how they sound is up to the Manufacturer, with one exception: a detected fall is signalled by a sound (capability fall). Two switches in the configuration control this:

12. Requirements for the Manufacturer

Production process, per Device:

1. Generate the EC P-256 key pair on the Device.
2. Export the public key (for example as a PKCS#10 certificate signing request with CN = Device ID and O = Manufacturer identifier).
3. Issue the Device certificate with the Manufacturer CA as specified in section 4.
4. Store the Device certificate on the Device next to the private key.
5. Print the label as specified in the Device Provisioning Protocol.

Once, per Manufacturer:

1. Create the Manufacturer CA as specified in section 3. Keep the CA private key offline or in an HSM.
2. Hand the CA certificate (PEM) and the Manufacturer identifier to PureSec.
3. Announce a new CA certificate to PureSec before Devices signed by it ship, so that the Server knows it in time.

Example with OpenSSL (Manufacturer CA, then one Device certificate from a CSR generated on the Device):

# Manufacturer CA, once
openssl ecparam -name prime256v1 -genkey -noout -out ca.key
openssl req -x509 -new -key ca.key -sha256 -days 7300 \
  -subj "/O=example-manufacturer/CN=Example Manufacturer Device CA" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -out ca.crt

# Device certificate, per Device, from the CSR the Device produced
openssl x509 -req -in device.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -sha256 -not_after 99991231235959Z \
  -extfile <(printf "basicConstraints=CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=clientAuth\n") \
  -out device.crt

13. MQTT: topics and session

Message formats are defined in Reference, MQTT part. The AsyncAPI document is written from the Device's point of view: send operations are published by the Device, receive operations are subscribed by the Device.

13.1 Topic scheme

All topics have the form

pld/v1/{clientId}/{category}[/{sub}]

Rules:

• Topics are lower-case ASCII. There is no leading slash.
• The Device MUST NOT publish to or subscribe to any topic outside pld/v1/{clientId}/. The broker enforces this with access control rules: the Device may publish to status, log, event/#, telemetry, config/reported, room/reported and ack/#, and may subscribe to config/desired, room/desired and cmd/#.
• The Device MUST NOT use wildcard subscriptions other than cmd/#.
• Every payload is a JSON object. The Device MUST set the MQTT 5 properties Payload Format Indicator = 1 and Content Type = application/json on every publish.

13.2 Session

• MQTT 5. With the scheme mqtts the Device validates the broker certificate against its store of public CA certificates; with mqtt the connection is unencrypted (see section 1.1).
• Client identifier, username, password, keep-alive, will delay and session expiry are taken from the bootstrap response (section 8). The Device MUST NOT choose its own values.
• Clean Start = false with the session expiry from the bootstrap, so that the broker keeps QoS 1 messages for the Device during short outages.
• Every CONNECT MUST carry the Last Will of section 14.
• After every successful connection the Device, in this order:
  1. subscribes to config/desired, room/desired (capability room) and cmd/#,
  2. publishes status (online),
  3. publishes config/reported and, with capability room, room/reported.
• On not authorized from the broker the Device follows section 11.2.

14. MQTT: status and Last Will

pld/v1/{clientId}/status holds the connection state of the Device as a retained message.

• The Device MUST register a Last Will in every CONNECT packet: topic pld/v1/{clientId}/status, QoS 1, retained, payload {"state":"offline"}, with the Will Delay Interval from the bootstrap response. A connection without this will is not compliant; the Server relies on it to detect a lost Device. The broker publishes the will when the connection is lost and the Device has not reconnected with the same client identifier within the delay. The will carries no timestamp; the Server uses its receive time.
• After every successful connection the Device publishes the online message (retained, QoS 1) with timestamp, protocolVersion, firmwareVersion, uptime, capabilities and, with capability room, the room limits object (section 19.2).
• On an orderly shutdown (for example before a reboot) the Device SHOULD publish {"state":"offline"} itself and then disconnect normally; the broker does not send the will after a normal disconnect.

A silent connection loss becomes visible on the Server after at most 1.5 × keep-alive plus the will delay. With the defaults that is 50 seconds. The broker MAY additionally track connections on its own; that is Server-internal and not part of this protocol.

14.1 Capabilities

capabilities in the online message declares what the Device does. The Server uses it to decide which events to expect, which configuration groups to send, and what to show in the user interface. Defined values:

This list is closed: a Device MUST NOT announce any other value. A Device without a capability MUST NOT send the corresponding events and MUST ignore the corresponding configuration group.

15. MQTT: configuration

Configuration follows the desired / reported pattern.

• The Server publishes the configuration it wants on config/desired, retained, QoS 1, always as a complete document with a revision that increases with every change.
• The Device receives the retained message immediately after subscribing, so it always has the current configuration after a reconnect or reboot, even if the change happened while it was offline.
• The Device applies the document, persists it, and publishes the configuration it actually uses on config/reported, retained, QoS 1, as a complete document with the same revision. Values it rejects keep their previous value and are listed in errors as objects with location (dotted path of the field) and message (short reason).
• The Device also publishes config/reported after every connection, so that the Server can detect a Device that lost its configuration (revision 0 means factory defaults).
• Reading the configuration on the Server means reading the latest config/reported. There is no read request.
• Both documents are at most 8192 bytes.

Capabilities and groups:

• The Server includes only the groups that always apply (system) and the groups whose capability the Device announced in its last online message. A Device without the fall capability never receives a fall group.
• The Device reports only the groups it supports and silently ignores groups it does not know in desired. It does not list them in errors.
• When a firmware update adds or removes capabilities, the Device announces the new list at its next connection. The Server then publishes a new desired with the groups adjusted (new groups with default values) and an increased revision.

15.1 Groups

Parameters, defaults and ranges of every group: Reference, MQTT part, schema ConfigDesired. A parameter that is absent keeps its default. The behaviour behind the parameters is specified where it applies: telemetry in section 18, LED and sound in sections 11.4 and 11.5, presence and fall reporting in section 20.

16. MQTT: logging

A Device with the capability log publishes log batches on pld/v1/{clientId}/log, QoS 0, not retained.

• Entries are batched: at most 50 entries or 8192 bytes per message, published at the latest 5 seconds after the first buffered entry. An entry with level error triggers an immediate publish of the batch.
• Levels, from most to least severe: error, warn, info, debug. Entries below system.logLevel are not sent. Default level info.
• Each entry carries its own timestamp (Unix milliseconds) and level, an optional tag naming the component, and message of at most 256 bytes.
• Loss is acceptable. The Device MUST NOT buffer log entries across reconnects beyond the 5-second window and MUST drop entries rather than stall other traffic.
• Log messages MUST NOT contain personal data: no names, no room or resident identifiers beyond the Device's own identity, no measurement values that describe a person. Logs are for the health of the Device, not for its function.

17. MQTT: commands

The Server sends commands on pld/v1/{clientId}/cmd/{command} (QoS 1, not retained). The Device answers on pld/v1/{clientId}/ack/{command} (QoS 1, not retained). Message formats: Reference, MQTT part.

17.1 Command envelope

{ "id": "3cb44b34-5421-4c7d-bb15-2f40422b3947", "issuedAt": 1758096000000, "expiresAt": 1758096300000, "params": { } }

Every command carries an id assigned by the Server, the times it was issued and expires, and a command-specific params object (empty if the command has no parameters). Fields: Reference, MQTT part, schema CommandEnvelope. The command name is the topic, not part of the payload.

The lifetime defaults to 5 minutes and is at most 1 hour. The Server also sets the MQTT 5 Message Expiry Interval to the remaining lifetime, so that the broker drops commands that expire while the Device is offline.

The Device:

• rejects a command whose expiresAt has passed (expired);
• ignores a command whose id it has already seen (it keeps at least the last 16 ids);
• executes at most one of wifi, server, reboot, wifi-scan and firmware-check at a time and rejects others with busy while one is running;
• answers an unknown command name with unknown_command.

17.2 Acknowledgement

Every command is acknowledged in two steps: first accepted or rejected, then, for accepted commands, done or failed.

{ "id": "3cb44b34-...", "timestamp": 1758096001000, "status": "accepted" }
{ "id": "3cb44b34-...", "timestamp": 1758096045000, "status": "done" }

Rules:

• The final acknowledgement follows within 10 minutes of accepted. If it does not arrive, the Server treats the command as failed with an unknown outcome.
• If a command requires the Device to disconnect (wifi, server, reboot), the Device sends the final acknowledgement after it has reconnected. It keeps the command id in memory for wifi and server and in persistent storage for reboot.
• Before it disconnects for a command, the Device publishes status offline (retained) and disconnects normally, so that the status topic stays accurate and no Last Will is triggered.

17.3 wifi

params: ssid (1 to 32 bytes), passphrase (empty for an open network, otherwise 8 to 63 bytes), optional bssid (AA:BB:CC:DD:EE:FF), optional channel (1 to 14).

1. accepted.
2. Publish status offline, disconnect normally.
3. Connect to the new network and run the stages WIFI, DNS, NTP, TLS, SERVER, MQTT of the Server check with the committed configuration (Server URL, DNS and NTP servers stay unchanged). SERVER includes authentication and bootstrap, so the MQTT credentials are rotated; MQTT is a test connection to the broker. Time budget: 60 seconds.
4. On success: persist the new network and run the start-up sequence from step 3 (authentication, firmware check, bootstrap, connect). Once the broker connection is established and status online is published, send done.
5. On failure: restore the previous network and run the start-up sequence from step 3 on the previous network. Once connected, send failed with stage and reason. If the previous network cannot be reached either, the Device stays in its normal reconnect behaviour on the previous network; the acknowledgement follows when it is back.

17.4 server

params: serverUrl, optional ntpServers, optional dnsServers, with the constraints and partial-update semantics of SetConfigCommand of the Device Provisioning Protocol.

1. accepted.
2. While still connected to the current broker, run the stages DNS, NTP, TLS, SERVER, MQTT of the Server check against the new values. Time budget: 60 seconds. SERVER includes authentication and bootstrap at the new Server; as a side effect the Device is registered there (unpaired) and receives that Server's MQTT connection data. MQTT is a test connection to the new broker with those data, opened next to the current session and closed again.
3. On success: persist the new configuration, send done to the current broker, publish status offline, disconnect normally, and run the start-up sequence from step 3 against the new Server (authentication, firmware check, bootstrap, connect).
4. On failure: failed with stage and reason. Nothing is changed and the Device stays connected to the current broker.

The previous Server marks the Device as inactive when it receives done.

17.5 reboot

params: optional delay in seconds (0 to 60, default 0).

1. accepted.
2. Publish status offline, disconnect normally, wait delay, restart.
3. After the restart and reconnect: status online, then done for the stored command id.

17.6 wifi-scan

params: none.

1. accepted.
2. Scan for at most 15 seconds. The current connection stays up.
3. done with result.networks: at most 20 entries, strongest first, each with ssid, bssid, rssi (dBm), channel and auth (open, psk, enterprise, other). Networks with hidden SSID are omitted.

17.7 firmware-check

params: none.

1. accepted.
2. PUT /pld/v1/firmware as in section 9.1.
3. done with result.updates: the components and target versions the Server returned, possibly empty. On an HTTP or network error failed with stage and reason as for wifi and server.
4. If there are updates: publish status offline, disconnect normally, install as in section 9.2, restart, and run the start-up sequence. The result becomes visible to the Server through the next firmware check.

18. MQTT: telemetry

Every Device publishes periodic health values on pld/v1/{clientId}/telemetry, QoS 0, not retained: uptime, Wi-Fi signal and access point, reconnect counters, clock state, free memory and, if the Device has a sensor, its temperature. Fields: Reference, MQTT part, schema Telemetry.

Telemetry describes the Device, not what it measures. Measurement data goes into events, occurrences into the log. Telemetry therefore carries no personal data.

Rules:

• Telemetry is sent only while system.telemetryEnabled is true.
• The first message is sent 10 seconds after the connection is established (after status and config/reported), then every system.telemetryInterval seconds. Each interval gets a random jitter of ±10 %, so that many Devices do not send in lockstep after a power outage.
• The counters (wifi.reconnects, mqtt.reconnects) start at zero on boot and are never reset otherwise. memory.minFree is the lowest free memory observed since boot.
• The message is at most 512 bytes.

clock.offset is calculated from the bootstrap: the Device notes its own time when sending the request (t0) and when receiving the response (t1) and computes offset = t1 − (serverTime + (t1 − t0) / 2). A positive value means the Device clock is ahead. The value is kept until the next bootstrap. It shows clock drift and failed NTP synchronisation before they break authentication (tolerance 300 s).

19. MQTT: room configuration

A Device with the capability room monitors a detection area around itself that can contain regions. The room configuration follows the same desired / reported pattern as section 15, on its own topics and with its own revision:

Message formats: Reference, MQTT part.

19.1 Coordinate system

All coordinates are integers in centimetres, relative to the Device:

• The Device is the origin.
• x runs to the right (positive) and to the left (negative).
• y runs to the front (positive) and to the back (negative).
• z runs upwards from the floor. The floor is z = 0, the Device is at z = sensorHeight.

What "front", "left" and "right" mean on the housing is defined by the Manufacturer in the documentation of the Device (for example by a marking or the position of the LED). The Server shows it to the installer.

19.2 Limits announced by the Device

With the capability room the online message (section 14) carries a room object that describes what the Device supports: the maximum number of regions, whether z is evaluated, the supported mountings with the largest extent per direction and the allowed mounting height, and the allowed range of the durations. Fields: Reference, MQTT part, schema RoomLimits. The Server uses it to validate and to render the room editor.

"room": {
  "maxRegions": 8,
  "zAxis": true,
  "mountings": {
    "wall":    { "left": 300, "right": 300, "front": 400, "back": 0,   "sensorHeight": { "min": 150, "max": 330 } },
    "ceiling": { "left": 300, "right": 300, "front": 200, "back": 200, "sensorHeight": { "min": 200, "max": 330 } }
  },
  "duration": { "min": 1, "max": 300 }
}

19.3 Room document

The room document consists of the mounting, the mounting height, the detection area, the durations of the area and the regions. Fields: Reference, MQTT part, schemas RoomDesired and RoomReported.

{
  "revision": 3,
  "mounting": "wall",
  "sensorHeight": 220,
  "area": { "x": { "min": -200, "max": 200 }, "y": { "min": 0, "max": 300 }, "z": { "min": 0, "max": 180 } },
  "enterDuration": 120,
  "exitDuration": 120,
  "regions": [
    {
      "id": "a7f07121-e084-45c8-a61f-4a5c80a13a24",
      "kind": "bed",
      "x": { "min": -120, "max": -20 },
      "y": { "min": 60, "max": 260 },
      "z": { "min": 0, "max": 80 },
      "presenceEnabled": true,
      "fallEnabled": false,
      "enterDuration": 60,
      "exitDuration": 120
    }
  ]
}

A room document is valid when all of the following hold:

• mounting is one of the mountings the Device announced, and sensorHeight lies within the range announced for it.
• The area extends at least 30 cm to every side that applies: x.min ≤ -30, x.max ≥ 30, y.max ≥ 30, and y.min ≤ -30 for ceiling. For wall, y.min is 0. No side exceeds the announced limit: -x.min ≤ left, x.max ≤ right, y.max ≤ front, -y.min ≤ back.
• z is present in the area and in every region exactly when the Device announced zAxis; then 0 ≤ z.min < z.max ≤ sensorHeight.
• Every region is an axis-aligned box with min < max on every axis and lies entirely inside the area. Regions do not overlap; overlap is judged on the x/y rectangle, independent of z. There are at most maxRegions regions.
• All durations lie within the announced duration range. A region without its own durations uses those of the area.

Region ids are assigned by the Server and referenced by the Device in events. The kind of a region has no effect the Server prescribes; what the Device makes of it is up to the Manufacturer.

19.4 Rules

• The Server publishes room/desired retained, always as a complete document, only to Devices with the capability room, and only with values inside the limits the Device announced.
• The Device validates the whole document. If any value is invalid, the Device rejects the whole document: it keeps the previous room configuration and publishes room/reported with the previous values, the revision of the rejected document and errors naming the fields (location such as regions[2].x.max, message such as outside area). A partially applied room configuration never exists.
• The Device MAY round coordinates and durations to its own grid. It reports the effective values in room/reported.
• The Device publishes room/reported after applying a desired document and after every connection. revision 0 means no room configuration has been received yet; the Device then monitors nothing beyond its default area, which the Manufacturer defines.
• Both documents are at most 8192 bytes.

20. MQTT: events

Events report what the Device detects. They are state reports, not transitions: the Device sends the current state, the Server derives "entered" or "left" by comparing consecutive reports. A lost report therefore costs no transition.

Message formats: Reference, MQTT part. Every event carries timestamp, the time of the observation on the Device in Unix milliseconds. Region identifiers refer to the room configuration in use (section 19); a Device without the capability room sends no region data.

Optional parts of the events are tied to capabilities and are then always present:

20.1 Presence

A presence event states whether anyone is in the detection area, which regions are occupied and, with the capability targets, the tracked targets with position, posture and confidence. Fields: Reference, MQTT part, schema PresenceEvent.

{
  "timestamp": 1758096300000,
  "present": true,
  "count": 1,
  "regions": [ { "id": "a7f07121-e084-45c8-a61f-4a5c80a13a24", "present": true } ],
  "targets": [ { "id": 3, "type": "person", "x": -40, "y": 120, "z": 90, "posture": "sitting", "confidence": 0.82 } ]
}

Rules:

• present and the region states are debounced: they change only after the enterDuration or exitDuration of the area or region has elapsed. regions lists every region with presenceEnabled.
• Postures are body postures only. Situations such as "in bed" or "sitting on the floor next to the bed" are derived by the Server from posture and region.
• The Device sends a presence event immediately when present changes, when the set of occupied regions changes, or when the posture of any target changes. Otherwise it sends one at the latest every presence.interval seconds. A change of position alone does not trigger an event.
• No presence events while presence.enabled is false.
• Presence events are not buffered. While the Device is disconnected they are dropped. The Device sets the MQTT 5 Message Expiry Interval to presence.interval seconds.
• At most 10 targets, at most 2048 bytes.

20.2 Fall

A fall event states the current state of one fall: when it started, how sure the Device is, where the person is and, once it is over, when and why it ended. Fields: Reference, MQTT part, schema FallEvent.

{
  "timestamp": 1758096310000,
  "id": "6f1c2a3b-9d4e-4f50-8a6b-7c8d9e0f1a2b",
  "state": "confirmed",
  "startedAt": 1758096300000,
  "confidence": 0.91,
  "position": { "x": 60, "y": 210, "z": 20 },
  "regionId": "0f4a2c9e-6b1d-4e0a-9c3f-2d7e8b5a1c44"
}

All events of one fall share id (assigned by the Device) and startedAt. endedAt is present only in the final states canceled and finished, reason only with finished.

States:

stateDiagram-v2
    direction LR
    [*] --> suspected
    suspected --> confirmed
    suspected --> canceled
    confirmed --> finished
    canceled --> [*]
    finished --> [*]

Rules:

• suspected is sent as soon as the Device suspects a fall. confirmed follows when the Device is sure, canceled when it is not. finished ends a confirmed fall.
• While a fall is suspected or confirmed, the Device repeats the event every 10 seconds with the current timestamp, confidence and position, so that the Server can tell an ongoing fall from a lost connection.
• No fall events while fall.enabled is false. A fall whose position lies in a region with fallEnabled false is not reported.
• Fall events are buffered: while the Device is disconnected it stores every state change (suspected, confirmed, canceled, finished) and publishes them after reconnecting, in order, with their original values. The 10-second repetitions are not buffered; they resume after reconnecting for a fall that is still ongoing. The buffer MUST hold at least 50 state changes. When it is full, the Device drops the oldest buffered events, but never an event of a fall that has not yet reached canceled or finished. Fall events carry no message expiry.
• At most 512 bytes.