Troubleshooting

MQTT: Connection refused, not authorized

• Cause: mqtt_password (or username) in NVS does not match what the broker expects — e.g. after Reset credentials in the console while the device still uses an old NVS password.
• Fix: Run HTTPS provisioning once with IOTMER_PROVISION_AUTH_CODE set (factory image or temporary build), or erase NVS and provision again.

MQTT: connected then immediate disconnect / EOF

• Cause (historical): Topic or subscription filters did not match console ACL ({workspace_slug}/{device_key}/…, cmd/# not commands).
• Fix: Use an SDK build whose iotmer_topics matches the ACL in the published docs (this repository’s current implementation).

Many failed auth attempts → broker flapping / ban

• The SDK backs off reconnect delay after CONNACK codes 4 (bad user/password) or 5 (not authorized) to reduce load on the broker.

provision skipped

• Expected when auth code is empty and NVS already holds a complete session. Not an error.

OTA skipped (same SHA)

• Expected when firmware metadata matches NVS, except when IOTMER_OTA_APPLY_EVEN_IF_SAME_SHA is enabled or HTTPS provision completed successfully on the same boot (forced re-download path).

ESP_ERR_NVS_KEY_TOO_LONG

• Use a component version that stores applied SHA under compliant key names (ota_sha, etc.).

Secrets in Git

• Exclude examples/*/sdkconfig from version control when it contains production Wi‑Fi or API keys. Use sdkconfig.defaults with empty placeholders for public repositories.

BLE Wi‑Fi provisioning (iotmer_ble_wifi_prov)

Symptom	Action
host/ble_gap.h: No such file or directory / IDF says bt missing from requirements	Use a component / IDF version where iotmer_ble_wifi_prov CMakeLists.txt declares REQUIRES bt. Clean rebuild after pulling.
adv_set_fields / BLE_HS_EMSGSIZE on start	Advertising + name + 128-bit UUID exceeded 31 B; use current firmware that splits UUID (adv) vs name (scan response).
Phone / PC shows UUID 2480 instead of 8024	Old NimBLE init byte order; flash firmware with corrected BLE_UUID128_INIT clock octets (0x80, 0x24).
macOS Bleak / nRF Connect: “characteristic not found” for RFC UUID strings	Core Bluetooth may print a different string for the same 128-bit value — compare canonical 128-bit values, or use the reference prov_client.py (canonicalises UUIDs). Remove the device from System Settings → Bluetooth after UUID firmware changes.
CONFIG_IOTMER_BLE_* missing from sdkconfig	Run idf.py fullclean or regenerate sdkconfig so defaults merge; ensure iotmer_ble_wifi_prov is in EXTRA_COMPONENT_DIRS so its Kconfig.projbuild is sourced.

Full protocol: BLE Wi‑Fi provisioning.