HTTPS provisioning
The device calls POST {IOTMER_PROVISION_API_URL}/provision/device and stores the JSON response in NVS as iotmer_creds_t.
Console setup (workspaces, API keys): docs.iotmer.com
When HTTPS runs
| Condition | Result |
|---|---|
IOTMER_PROVISION_AUTH_CODE set | HTTPS provision runs (requires IOTMER_WORKSPACE_ID) |
| Auth code empty + complete NVS session | HTTPS skipped — field firmware path |
Complete NVS session: device_id, device_key, workspace_slug, mqtt_host, mqtt_username, mqtt_password.
device_http_token (NVS key dht) is not required for MQTT. It is required for iotmer_device_auth_bind_claim(). If HTTPS was skipped and NVS has no dht, run a one-off provision with auth code, or set lab-only IOTMER_DEVICE_HTTP_TOKEN.
Request
POST /api/v1/provision/device · Header: iotmer-auth-code
| Field | Required | Source |
|---|---|---|
workspace_id | Yes | Kconfig IOTMER_WORKSPACE_ID |
device_key | First registration | creds->device_key before call |
template_id | No | Kconfig IOTMER_TEMPLATE_ID |
device_id | No | NVS (re-provision) |
First registration:
{"workspace_id":"ws_...","device_key":"IoTmer-GW-3B7C"}
Re-provision:
{"workspace_id":"ws_...","device_key":"IoTmer-GW-3B7C","device_id":"dev_..."}
Response (parsed fields)
| Field | Use |
|---|---|
device_id, device_key | Identity |
workspace_slug | MQTT topic prefix → NVS |
mqtt_host, mqtt_port, mqtt_tls, mqtt_username, mqtt_password | Broker session |
device_http_token | Bearer for POST …/devices/auth/* → NVS dht. Never log. |
firmware_url, firmware_checksum_sha256, firmware_size_bytes | HTTP(S) auto-OTA (OTA) |
Responses may nest fields under data — the SDK handles both layouts.
Bind-claim
Deliver claim_code out-of-band (often over BLE JSON). Device calls:
POST …/devices/auth/bind-claim with Authorization: Bearer {device_http_token}
| HTTP | SDK result |
|---|---|
200 + ok: true | ESP_OK |
| 401 | ESP_ERR_INVALID_ARG |
| 409 / 410 | ESP_ERR_INVALID_STATE (used/expired claim) |
See BLE JSON provisioning and examples/05_ble_json.
Logging
After successful parse, the SDK logs host, port, TLS, username, password length, and whether the password changed. Password and token values are never logged.
OTA flag
On HTTPS success, the SDK sets an internal https_performed flag so OTA can run even when SHA matches NVS. See OTA.