Skip to main content

HTTPS provisioning

Provisioning means: the device calls the POST …/provision/device endpoint and receives JSON with device identity, MQTT credentials, optional firmware metadata, etc. The SDK parses that JSON into iotmer_creds_t and saves it to NVS.

API keys, workspaces, and device lifecycle are covered in documentation; this page is the HTTPS + NVS behaviour of this SDK only.

When HTTPS runs​

ConditionBehaviour
IOTMER_PROVISION_AUTH_CODE is non-emptySDK performs HTTPS provisioning (also needs IOTMER_WORKSPACE_ID).
Auth code is empty and NVS already has device_id, device_key, workspace_slug, mqtt_host, mqtt_username, mqtt_passwordHTTPS is skipped — “telemetry-only” path so field firmware does not embed the factory key.

Request body (simplified)​

The SDK builds JSON including:

  • workspace_id (from Kconfig)
  • optional template_id
  • device_id when the device is already known (repeat registration)

Response (subset)​

Typical fields parsed into RAM / NVS:

  • device_id, device_key
  • workspace_slug (returned in the provision JSON, then stored in NVS for MQTT topics)
  • mqtt_host, mqtt_port, mqtt_tls, mqtt_username, mqtt_password
  • optional firmware_url, firmware_checksum_sha256, firmware_size_bytes

Some responses nest metadata under a data object — the SDK supports both layouts.

Debug logging (no password leak)​

After a successful HTTPS parse, the SDK logs an MQTT summary:

  • host, port, TLS flag, username
  • password_len (character count)
  • whether the password string changed vs the NVS snapshot taken before this request (changed_or_new / same_as_before)

The plaintext password is never printed.

Internal flag: “HTTPS ran this boot”​

On success, the SDK sets an internal https_performed flag. That is used so OTA can optionally run even when the firmware SHA matches the last applied image (see OTA).