PureLife Device Protocol (PLD)

Status: Draft 0.1 (2026-09-17)

Warning

This specification is currently in draft status. The definitions, procedures and data structures described herein are subject to change without notice.

The interfaces documented here are not yet implemented and are provided for design and planning purposes only.

The PureLife Device Protocol (PLD) defines how a sensor (the Device) is set up and how it communicates with a PureLife Cloud instance (the Server). The protocol is independent of the sensing technology and of the Manufacturer; any Device that follows this specification can work with the Server.

PureSec provides the protocol specification. The Device firmware is provided by the manufacturer of the Device.

Documents

The protocol has two parts, each published as its own specification. The message formats of the Device Messaging Protocol are additionally provided as the PureLife Device Protocol Reference.

Device Provisioning Protocol
Initial setup of a Device over Bluetooth LE: network, Server address, Server check, pairing with a Customer. The message definitions are available as Protocol Buffers files.
Device Messaging Protocol
Communication between Device and Server during normal operation: authentication, bootstrap and pairing token over HTTP; status, configuration, room, logging, telemetry, commands and events over MQTT.
Reference, HTTP part
Message formats of the HTTP operations of the Device Messaging Protocol (OpenAPI).
Reference, MQTT part
Message formats of the MQTT topics of the Device Messaging Protocol (AsyncAPI).

The glossary, conventions and versioning rules below apply to both parts.

Glossary

The following terms are used consistently across all parts of the protocol.

Term	Meaning
Device	The sensor hardware together with the manufacturer's firmware that implements this protocol.
Server	The PureLife Cloud instance the Device talks to. There is exactly one Server per Device.
Provisioner	The app or tool that provisions a Device (for example a smartphone app or a command-line tool). It talks to the Device over Bluetooth LE and to the Server over HTTPS.
Manufacturer	The company that builds the Device and its firmware. Identified by a manufacturer identifier agreed with PureSec.
Customer	A tenant on the Server. Devices are paired to exactly one Customer.
Device ID	Identifier of a Device, unique per Manufacturer. See the provisioning specification for the format.
PoP	Proof of Possession. A per-Device secret printed on the Device that proves the Provisioner has physical access to the Device.
Provisioning Mode	Device state in which it accepts provisioning over Bluetooth LE.
Commit	The moment the Device persists the provisioned configuration. A Device counts as provisioned after the first Commit.
Pairing	Linking a Device to a Customer on the Server.
Manufacturer CA	Certificate authority operated by the Manufacturer. Its private key signs Device certificates; its certificate is embedded in the Server.
Device certificate	X.509 certificate issued by the Manufacturer CA that binds the Device public key to the Device ID and the Manufacturer.
Assertion	JWT signed with the Device private key that the Device presents to authenticate.
Access token	Opaque token issued by the Server after authentication, used for all other HTTP requests.
Bootstrap	The HTTP request after authentication that returns the MQTT connection data.
Factory Reset	Erases all provisioned data and returns the Device to its delivery state.

Bluetooth and HTTP have their own notion of client and server. To avoid confusion these words are not used for protocol roles in this specification. The roles are always Device, Provisioner and Server.

Conventions

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119.
Timestamps are Unix time in milliseconds, UTC.
Strings are UTF-8 unless stated otherwise.
Message definitions of the provisioning part are written in Protocol Buffers (proto3 syntax); field names follow the protobuf style (snake_case).
JSON payloads follow the Google JSON Style Guide: property names in camelCase, arrays with plural names, enum values as strings, empty or null properties omitted, errors as an error object with code, message and errors[]. Deliberate deviations: timestamps are Unix milliseconds instead of RFC 3339 strings, durations are seconds instead of ISO 8601, and names fixed by RFCs keep their spelling (access_token, token_type, expires_in of RFC 6749, JWT claims).

Versioning

Each part of the protocol carries its own version in the form MAJOR.MINOR.

A MINOR increment only adds optional fields, messages, endpoints or capabilities. Implementations of the same MAJOR version stay compatible.
A MAJOR increment may change or remove existing behaviour.
Every receiver of a JSON document (Device and Server alike) MUST ignore properties it does not know. This is what makes MINOR additions safe. The schemas in the Reference therefore do not forbid additional properties; they describe the properties of the version they belong to.

How a Device announces the version it implements is defined in each part.