Skip to main content

Reference examples

Reference applications live under examples/ in this repository. Additional examples will be added as the SDK grows; this page documents the ones available today and the roles they illustrate.

01_provisioning — factory / bring-up​

Purpose: Register or refresh the device against the provision API and persist credentials in NVS.

  • Configure IOTMER_PROVISION_AUTH_CODE and IOTMER_WORKSPACE_ID in menuconfig (and Wi‑Fi).
  • Successful boots log an HTTPS POST to {IOTMER_PROVISION_API_URL}/provision/device.
  • Auto-OTA may run after a successful response.
  • The example defaults may set IOTMER_OTA_APPLY_EVEN_IF_SAME_SHA so a matching server SHA still triggers a re-download (forced re-flash workflows).

Usage: One factory programming cycle per device, or whenever server-issued credentials must be refreshed.

02_telemetry — field firmware​

Purpose: Operational firmware: Wi‑Fi, reuse NVS session, MQTT telemetry.

  • Leave IOTMER_PROVISION_AUTH_CODE empty after at least one full provision has populated NVS (including workspace_slug from the API response for MQTT topic prefix {workspace_slug}/{device_key}/…).
  • Logs show provision skipped (no auth code; using stored session) when the stored session is complete.
  • Application flow: iotmer_connect, subscribe, publish.

Deployment: Ship this binary (or an application built on the same component) over USB or OTA without embedding the factory API key.

03_lwt_presence — retained presence (ONLINE/OFFLINE)​

Purpose: Demonstrate MQTT retained presence plus broker last-will (LWT):

  • On connect, the device publishes retained "ONLINE" to …/presence/.
  • If the client disconnects unexpectedly, the broker publishes retained "OFFLINE" to the same topic via LWT.

This is useful for fleet dashboards and simple health checks.

04_config — MQTT Config Protocol v1​

Purpose: Demonstrate the config pull flow over MQTT:

config/meta (retained) → config/get → config/resp (identity or gzip+base64 chunks) → config/status.

Start here for the full protocol contract: MQTT Config Protocol v1.

05_ble_wifi_prov — BLE Wi‑Fi credential transfer (optional)​

Purpose: Demonstrate IOTMER-owned BLE GATT protocol v1 for delivering STA SSID and password to the chip, then calling iotmer_wifi_set_credentials() (same NVS keys as the rest of the SDK). This is not compatible with Espressif wifi_prov_mgr phone apps.

  • Component: iotmer_ble_wifi_prov (NimBLE); enable CONFIG_IOTMER_BLE_WIFI_PROV and NimBLE in sdkconfig.
  • Protocol & GATT UUIDs: BLE Wi‑Fi provisioning.
  • Reference app: examples/05_ble_wifi_prov — after a successful COMMIT, the sample calls iotmer_wifi_reconnect() and stops BLE advertising.
  • Desktop test client: examples/05_ble_wifi_prov/pc_ble_client (Python Bleak), useful on macOS / Linux / Windows for scripted tests.

Build & flash (any example)​

cd examples/02_telemetry
idf.py set-target esp32c3    # select the target SoC
idf.py menuconfig             # Component config → IOTMER
idf.py build flash monitor

Use sdkconfig.defaults in CI. Store secrets only in local sdkconfig; do not commit production API keys or Wi‑Fi credentials to public repositories.