PureLife Device Provisioning Protocol

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

This document specifies how a Device is provisioned: how it receives its network configuration and the address of its Server, how the Provisioner verifies that the Device can reach the Server, and how the Device is paired with a Customer.

The protocol builds on the Unified Provisioning framework of Espressif (protocomm and network_provisioning). Everything that framework already defines (session establishment, security schemes, Wi-Fi configuration, Bluetooth LE transport) is used unchanged and is only referenced here. This document specifies what is added on top of it.

Contents

1. Normative references
2. Overview
3. Transport
4. Security
5. Protocol version and capabilities
6. Device states
7. LED
8. Provisioning flow
9. Endpoints
10. Server check
11. Pairing
12. Device label and QR code
13. Message size limits
14. Related specifications
15. Protocol Buffers files

1. Normative references

The Espressif components are licensed under Apache-2.0. Their protobuf definitions are not reproduced in this specification. Implementers take them from the component sources.

A Device does not have to be built with ESP-IDF. Any implementation that behaves as specified by the references above and by this document is compliant.

2. Overview

Provisioning happens over Bluetooth LE between the Provisioner and the Device. The Provisioner also talks to the Server over HTTPS to finish the pairing. The Device talks to the Server during the Server check and the pairing step.

flowchart LR
    P["Provisioner<br/>(app or tool)"]
    D["Device"]
    S["Server<br/>(PureLife Cloud)"]
    P <-->|"Bluetooth LE (protocomm)<br/>this specification"| D
    P -->|"HTTPS<br/>PureLife Cloud API (pairing)"| S
    D -->|"HTTP(S)<br/>Device Messaging Protocol"| S

The Espressif framework contributes these endpoints:

This specification adds the following endpoints. All of them are custom endpoints in the sense of the Espressif framework and are only reachable inside the secure session.

3. Transport

• The Device MUST provide the provisioning service over Bluetooth LE (GATT), as implemented by the protocomm BLE transport.
• SoftAP (Wi-Fi + HTTP) MUST NOT be offered.
• The Device MUST advertise the device name PLD_<Device ID> (see section 9.1 for the Device ID format). The name is at most 28 bytes; the protocomm BLE transport allows 29.
• The Device MUST include the 128-bit UUID of the provisioning service in the advertisement, as protocomm does. The Provisioner takes the service UUID from the advertisement and discovers the endpoints through the Characteristic User Description descriptor of each characteristic. The Provisioner MUST NOT rely on a fixed service UUID.
• The Provisioner MUST use the endpoint names to address endpoints. The 16-bit characteristic UUIDs assigned by the framework are an implementation detail.

4. Security

The security scheme is the protocomm security scheme announced in proto-ver (prov.sec_ver).

Rules:

• The Device MUST NOT offer Security 1 without PoP (the no_pop capability MUST NOT be present in proto-ver).
• A Device offering Security 0 announces this through the no_sec capability in proto-ver. With Security 0 all provisioning data, including the Wi-Fi passphrase, is transmitted unencrypted, and anyone in Bluetooth range can provision the Device while it is in Provisioning. A Provisioner SHOULD inform the user before it continues with an unsecured session.
• Note for ESP-IDF 6.0 and later: Security 0 and 1 are disabled by default and have to be enabled explicitly (CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0 / ..._VERSION_1).

4.1 Proof of Possession

• The PoP is generated per Device by the Manufacturer during production, stored in the Device and printed on the Device label (see section 12).
• The PoP MUST be random and MUST consist of at least 8 characters from the set A-Z, a-z, 0-9. 12 characters are RECOMMENDED.
• The PoP MUST NOT be derivable from the Device ID, the MAC address or any other public property of the Device.
• The PoP is never transmitted to the Server.

5. Protocol version and capabilities

The proto-ver endpoint returns a JSON document. The framework fills the prov object. The Device MUST add an object with the key pld:

{
  "prov": { "ver": "...", "sec_ver": 1, "sec_patch_ver": 0, "cap": ["wifi_scan"] },
  "pld":  { "ver": "1.0", "cap": ["ipv6"] }
}

The values inside prov are set by the Espressif component and are not specified here.

Defined capabilities:

The key pld and the contents of the pld object are fixed by this specification. A Device MUST NOT add other keys to the pld object or other capabilities than the ones listed. The prov object is defined by the Espressif component; the Provisioner does not depend on any other top-level key.

The Provisioner MUST refuse to continue if pld is missing or if pld.ver has a MAJOR version it does not support.

6. Device states

stateDiagram-v2
    direction LR
    [*] --> Provisioning : power on<br/>(delivery state)
    Provisioning --> Operating : Finish, or<br/>timer expiry after Commit
    Provisioning --> Off : timer expiry<br/>without Commit
    Off --> Provisioning : power cycle
    Operating --> Provisioning : Factory Reset<br/>(button 20 s)

Rules:

• A Device in delivery state, or after a Factory Reset, MUST enter Provisioning automatically when powered on.
• On entering Provisioning the Device starts a provisioning timer of 15 minutes. The timer is restarted whenever a secure session is established and whenever the Device receives a request on any endpoint in that session, so an active Provisioner is never cut off.
• When the timer expires:
  • if a Commit has happened in this Provisioning period, the Device MUST enter Operating;
  • otherwise the Device MUST enter Off.
• Holding the button for 20 seconds triggers a Factory Reset in any state. The Device erases all provisioned data (Wi-Fi credentials, PLD configuration, Server credentials obtained later) and enters Provisioning. The PoP is not part of the provisioned data and survives the reset.
• After the button has been held for 3 seconds the Device shows the LED pattern Factory Reset pending until the button is released or the 20 seconds are reached. Releasing the button earlier cancels the Factory Reset; the Device keeps its state and the LED returns to the pattern of that state.
• A Device counts as provisioned once a Commit has been performed. Wi-Fi credentials alone do not make a Device provisioned, even though the Espressif framework persists them as soon as they are applied.
• The Device MUST disable the auto-stop behaviour of the Espressif provisioning manager (disable_auto_stop) and MUST stop the provisioning service only on a Finish command or on timer expiry.

7. LED

The status LED shows the following states.

"Connection to Server established" applies whenever the Device establishes its connection to the Server, both during the Server check and in Operating after every reconnect.

8. Provisioning flow

The Provisioner performs the following steps in order. Steps marked (framework) use Espressif endpoints unchanged.

Deviations:

• If Wi-Fi fails in step 8, the Provisioner MAY reset the Wi-Fi state machine with prov-ctrl (CtrlReset) and repeat step 8 with different credentials, or it MAY commit anyway (step 10) and leave the Device to retry. Committing with failing Wi-Fi is explicitly allowed so that an installer can finish work when the network is not yet available.
• Steps 11 and 12 require a Commit and a working Server connection. If they are skipped, the Device is provisioned but not paired. Because the Device leaves Provisioning on Finish or on timer expiry, and re-entering requires a Factory Reset, an unpaired Device can only be paired by provisioning it again from scratch. Provisioners MUST therefore call Finish only after pairing succeeded, or make the user confirm that the Device will stay unpaired.
• The Provisioner MAY disconnect at any time. Without a Commit nothing is persisted except the Wi-Fi credentials, and the Device switches off when the provisioning timer expires.

9. Endpoints

All PLD endpoints follow the same pattern as the Espressif endpoints: each endpoint has one payload message with a msg type field and a oneof containing the command or response. Each response carries a Status.

Every response message contains Status status = 1 and string detail = 2 (human readable, English, at most 64 bytes). detail MUST be empty when status is STATUS_OK and SHOULD name the cause otherwise. It is meant for logs and support, not for display to end users.

The .proto files are the reference for field names, numbers, enum values and the conventions used (see the header of pld_constants.proto). The tables in this document use the short forms of enum values where the prefix is obvious.

9.1 pld-info

Reads the identity of the Device. Read-only.

The Provisioner MUST compare device_id with the Device ID from the label and abort if they differ.

9.2 pld-config

Sets and reads the pending PLD configuration. Values sent here are held in memory only. They are persisted by Commit (pld-ctrl).

Semantics of SetConfigCommand:

• Fields that are not present leave the pending value unchanged. This allows the Provisioner to split the configuration over several commands to stay within the message size limit.
• A present list replaces the pending list completely. An empty present list clears it, so that the Device falls back to DHCP.
• The Device validates each present field and rejects the whole command with STATUS_INVALID_ARGUMENT if any field is invalid. In that case no pending value is changed.

Only server_url is required for a Commit. The lists are empty until the Provisioner sets them.

• DNS: With a non-empty list the Device uses these servers instead of the ones offered by DHCP. With an empty list it uses the DNS servers offered by DHCP.
• NTP: With a non-empty list the Device tries these servers in order. With an empty list it uses the NTP servers offered by DHCP (option 42); if DHCP offers none, it uses NTP servers defined by the Manufacturer.

9.3 pld-ctrl

Commit

• Validates that the pending configuration is complete (STATUS_INVALID_ARGUMENT otherwise, detail names the missing field).
• Persists the pending configuration atomically. Either the complete new configuration is stored, or the previous state is kept.
• MUST succeed regardless of the Wi-Fi connection state and regardless of the result of the Server check.
• After the first successful Commit the Device counts as provisioned.
• A second Commit in the same session replaces the stored configuration.

Finish

• Requires a previous Commit in this Provisioning period (STATUS_INVALID_STATE otherwise).
• The Device sends the response, stops the provisioning service and enters Operating.

9.4 pld-check

See section 10.

9.5 pld-pair

See section 11.

10. Server check

The Server check verifies from the Device's point of view that the Server is reachable with the pending configuration. It is asynchronous: the Provisioner starts it and polls the result.

Preconditions: the pending configuration MUST be complete and Wi-Fi MUST be connected. Otherwise StartCheckCommand answers STATUS_INVALID_STATE. A running check answers STATUS_BUSY.

The check runs the following stages in order and stops at the first failure. Later stages are reported as SKIPPED, as is a stage that does not apply.

The overall check MUST finish within 60 seconds. Each stage MUST fail with CHECK_ERROR_TIMEOUT if it exceeds its share.

The Server check does not check for or install firmware updates; that happens in the start-up sequence after Finish. The test connection of stage MQTT is not an operating connection.

GetCheckStatusResponse:

StageResult:

CheckError:

The Provisioner SHOULD present the failed stage and error to the user in plain language and SHOULD offer to commit anyway.

11. Pairing

Pairing links the Device to the Customer of the Provisioner's user. The Device proves to the Server that it is online, and the Provisioner proves to the Server that it has physical access to the Device (it holds the secure session that required the PoP).

sequenceDiagram
    participant P as Provisioner
    participant D as Device
    participant S as Server
    P->>D: StartPairingCommand
    D->>S: request pairing token (Device Messaging Protocol, HTTPS)
    S-->>D: token, expires_at
    P->>D: GetPairingStatusCommand (poll)
    D-->>P: DONE, token, expires_at
    P->>S: pair Device (PureLife Cloud API): device_id, token
    S-->>P: 200 OK
    P->>D: FinishCommand

Rules:

• StartPairingCommand requires a Commit (STATUS_INVALID_STATE otherwise) and answers STATUS_BUSY while a request is running.
• The Device requests the token from the Server as defined by the Device Messaging Protocol, section 10 (POST /pld/v1/pairing-token). The request MUST finish within 30 seconds. On 401 the Device authenticates again and retries the request once within that budget; on 429 or 503 it does not retry but reports PAIR_ERROR_SERVER_REJECTED with the status, and the Provisioner MAY start a new pairing after the Retry-After time.
• The token is opaque to the Device and to the Provisioner. It is a 43-character base64url string. expires_at is the expiry time as Unix milliseconds, set by the Server; the default lifetime is 10 minutes.
• A new StartPairingCommand requests a new token. The Server invalidates the previous one.
• The Provisioner redeems the token through the PureLife Cloud API (operation Pair a sensor), together with the Device ID. How that API is called is specified there, not here. The Device Provisioning Protocol is not affected by the outcome; the Provisioner reports it to the user.

GetPairingStatusResponse:

PairError:

12. Device label and QR code

Every Device carries a label with, in human readable form:

1. the Device ID,
2. for Security 1 the PoP, for Security 2 username and password. Devices with Security 0 have no secret on the label.

The label SHOULD additionally carry a QR code as specified below. The Provisioner MUST support both ways: scanning the QR code and entering the Device ID and the secret by hand. From the Device ID the Provisioner derives the advertised name (PLD_<Device ID>).

The QR code contains a JSON document in the format used by the Espressif provisioning libraries, so that those libraries can parse it directly:

{"ver":"v1","name":"PLD_9923003A4BE3","pop":"K7fT2pQ9xL4m","transport":"ble","security":1}

For Security 2 the keys username and password are used instead of pop, as defined by the Espressif provisioning libraries. For Security 0 the key pop is omitted.

The Device ID is not a separate key. It is name without the PLD_ prefix. After the session is established the Provisioner compares it with pld-info.

13. Message size limits

The protocomm BLE transport limits one transfer to 512 bytes, including the overhead of the security scheme (16 bytes for the AES-GCM tag of Security 2). Every PLD request and every PLD response MUST therefore be at most 450 bytes after protobuf serialisation and before encryption.

The field limits in this document are chosen so that every message stays within that limit even when all fields have their maximum length. The largest messages are SetConfigCommand and GetConfigResponse with a full configuration (about 410 bytes). This relies on the rule that detail is empty on success; a 64-byte detail in a GetConfigResponse with a full configuration would exceed the limit. The Provisioner MAY split SetConfigCommand over several commands.

14. Related specifications

Some steps of this protocol are specified elsewhere:

15. Protocol Buffers files

The messages of the PLD endpoints are defined in proto/:

The framework's own definitions (session.proto, sec0.proto, sec1.proto, sec2.proto, constants.proto, wifi_config.proto, wifi_scan.proto, wifi_ctrl.proto) are taken from the protocomm and network_provisioning sources.