Device Provisioning Workflow¶

This page is the complete operational runbook for the zero-touch device provisioning flow.

Overview¶

Zero-touch provisioning means a device can be unboxed, powered on, and fully registered in the platform without any manual intervention. The process relies on:

• A pre-installed enroll.sh script (or rauc-hawkbit-updater equivalent) baked into the Yocto image.
• The device knowing only: the iot-bridge-api URL and the step-ca root CA fingerprint.
• No pre-shared passwords — only asymmetric cryptography.

Step-by-Step Flow¶

Phase 1 — Factory Enrollment (first boot)¶

sequenceDiagram
    participant D as Device
    participant I as Tenant IoT Bridge API
    participant S as Tenant step-ca (Sub-CA)

    D->>D: generate EC key pair
    D->>D: generate CSR (CN=device-id)
    D->>I: POST /devices/{id}/enroll { csr_pem }
    I->>I: validate device-id
    I->>I: build OTT JWT
    I->>S: POST /1.0/sign
    S-->>I: signed cert (chain: device → Sub-CA → ICA → Root CA)
    I->>I: allocate WG IP
    I->>I: generate WG config
    I-->>D: { cert, ca_chain, wg }
    D->>D: save /certs/device.crt
    D->>D: save /certs/ca-chain.crt
    D->>D: save /certs/wg0.conf
    D->>D: write /certs/enrolled (idempotency flag)

Phase 2 — First MQTT Connection¶

sequenceDiagram
    participant D as Device
    participant T as ThingsBoard (Tenant-Stack)
    participant I as Tenant IoT Bridge API

    D->>T: MQTT CONNECT (mTLS, cert CN=device-id)
    T->>T: verify cert chain against Sub-CA → Root CA
    T->>I: Rule Engine: POST_CONNECT event<br/>POST /webhooks/thingsboard
    I->>I: create hawkBit target
    I->>I: store WG IP in TB attributes
    T-->>D: CONNACK

Phase 3 — Device Registers with WireGuard¶

sequenceDiagram
    participant D as Device
    participant W as WireGuard Server

    D->>W: wg-quick up wg0 (uses /certs/wg0.conf)
    W->>W: add peer (public key + allowed IPs)
    W-->>D: tunnel established
    Note over D: now reachable at 10.8.0.x

Configuration Reference¶

iot-bridge-api Environment Variables¶

Re-Enrollment¶

If a device loses its certificate (e.g. storage failure), delete the idempotency flag and re-run enrollment:

rm /certs/enrolled
/opt/cdm/enroll.sh

The device_id is preserved; a new key pair and certificate are generated.

Decommissioning a Device¶

1. Revoke the device certificate in step-ca.
2. Delete the device from ThingsBoard.
3. Remove the device target from hawkBit.
4. Remove the WireGuard peer from the server config:

   wg set wg0 peer <device-public-key> remove
   wg-quick save wg0
   

5. Delete the device entry from cdm_peers.json (in the wg-data volume).

Troubleshooting¶