Troubleshooting
MQTT: Connection refused / not authorized
Cause: NVS mqtt_password does not match the broker — e.g. after Reset credentials in the console.
Fix: Re-provision with IOTMER_PROVISION_AUTH_CODE set, or erase NVS and provision again.
MQTT: Connect then immediate disconnect
Cause: Topic filters do not match console ACL ({workspace_slug}/{device_key}/cmd, config/#).
Fix: Use current SDK iotmer_topics helpers.
MQTT: Auth failure loop
SDK backs off reconnect after CONNACK rc 4 (bad credentials) or 5 (not authorized).
Wi‑Fi: Drops and never recovers
SDK ≥ 0.2.0: persistent reconnect with 15–60 s backoff after fast retries. iotmer_wifi_connect() may return ESP_FAIL without blocking boot, but the link keeps retrying in the background.
Upgrade from older versions — no application "Wi‑Fi guardian" task needed.
Stack overflow during iotmer_init()
iotmer_init() runs Wi‑Fi (blocking ~30 s) and HTTPS provision (TLS) on the calling task. Use ≥ 8 KB stack.
Broken or truncated config JSON
SDK ≥ 0.2.0: reassembles messages larger than CONFIG_MQTT_BUFFER_SIZE (cap: IOTMER_MQTT_RX_ASSEMBLY_MAX, default 8 KB). Above the cap, messages are dropped with a warning.
Raise CONFIG_MQTT_BUFFER_SIZE or IOTMER_MQTT_RX_ASSEMBLY_MAX for large payloads.
provision skipped
Expected when auth code is empty and NVS holds a complete session. Not an error.
OTA skipped (same SHA)
HTTP(S) auto-OTA: expected when provision SHA matches NVS, unless IOTMER_OTA_APPLY_EVEN_IF_SAME_SHA=y or HTTPS provision ran on the same boot.
MQTT OTA: message=already_applied with "force": false. Use "force": true to rewrite the same image.
MQTT OTA: silence after starting
Expected. The worker disconnects MQTT for the HTTP(S) download. Wait for applied_rebooting or an error after reconnect — do not treat queued as success.
MQTT OTA: ota_busy
A previous OTA is still queued or running. Wait for reboot or an error ack.
See OTA.
Secrets in Git
Exclude examples/*/sdkconfig with production credentials. Use sdkconfig.defaults with empty placeholders.
BLE (iotmer_ble)
| Symptom | Fix |
|---|---|
Missing ble_gap.h | REQUIRES iotmer_ble in app CMakeLists; idf.py fullclean |
BLE_HS_EMSGSIZE on advertise | UUID in advertising PDU, name in scan response (31-byte limit) |
| macOS: characteristic not found | Compare 128-bit UUID values; remove peripheral from Bluetooth settings |
CONFIG_IOTMER_BLE missing | Enable in menuconfig; add component to EXTRA_COMPONENT_DIRS |
| macOS CBError 14 (pairing) | Forget device in Bluetooth settings; re-pair |
bind-claim fails | Ensure device_http_token in NVS. HTTP 410 = expired claim code |