This chapter summarizes symptoms you often run into in the hands-on and in real development, with causes and fixes.
Build and flash
nimble/nimble_port.h: No such file or directory |
bt is missing from PRIV_REQUIRES in main/CMakeLists.txt, or BLE is disabled in sdkconfig |
Write PRIV_REQUIRES bt. Delete sdkconfig and regenerate it (Chapter 4) |
Changes to sdkconfig.defaults don’t take effect |
A value is already written in sdkconfig |
Delete sdkconfig before building, or use idf.py menuconfig |
ble_store_config_init not found (implicit declaration) |
Not declared in a public header |
Declare void ble_store_config_init(void); yourself |
Flashing stops with Failed to connect |
Cannot enter download mode, or another app is using the port |
Close the serial monitor. Hold BOOT and press RESET (Chapter 1) |
idf.py not found |
The environment is not activated |
source ~/.espressif/tools/activate_idf_v6.0.1.sh (adjust the path to your environment) |
| Lots of red squiggles in the VS Code editor, but the build passes |
Code completion (clangd / IntelliSense) can’t read build/compile_commands.json |
Build once, then restart the language server |
Not found / can’t connect
| Doesn’t appear in scans |
Advertising hasn’t started |
Does advertising as … appear in the log? Check the return value of ble_gap_adv_set_fields() (BLE_HS_EMSGSIZE if over 31 bytes) |
| Never found again once disconnected |
Advertising is not restarted on disconnect |
start_advertising() on BLE_GAP_EVENT_DISCONNECT |
| Disconnects / can’t be found as soon as you move a little away |
The antenna is not attached to the XIAO ESP32C3 |
Attach the supplied antenna to the U.FL connector |
| An old name keeps being shown |
The phone/PC is caching the name |
Turn Bluetooth off and on. In nRF Connect, rescan |
| Doesn’t appear in the Web Bluetooth list |
No service UUID in the advertisement (Step 2), or the browser is unsupported |
Flash Step 3 or later. Use Chrome / Edge |
Notify doesn’t arrive
| No Notify |
The client has not subscribed to the CCCD |
Press ↓↓↓ in nRF Connect. Does subscribe … notify=1 appear in the log? |
| Only command responses don’t arrive |
Not subscribed to the Command CCCD |
Also enable Notify on the characteristic that returns responses |
rc=6 (BLE_HS_ENOMEM) appears |
Sending too fast; out of mbufs |
Lengthen the send period, bundle data (Chapter 6) |
rc=7 (BLE_HS_ENOTCONN) |
Tried to send after disconnecting |
Check the connection handle before sending |
| Data longer than 20 bytes gets cut off |
MTU is still 23 |
Split it, or check the result of MTU negotiation (BLE_GAP_EVENT_MTU) |
Pairing
| Asked for the passkey every time |
Not bonding, or bond information is not saved |
sm_bonding = 1, ble_store_config_init(), CONFIG_BT_NIMBLE_NVS_PERSIST=y |
Disconnects right after connecting / encryption fails (enc change status≠0) |
Only one side has the bond information (e.g. the ESP32-C3 was erase-flashed) |
Also forget the device on the phone/PC, then reconnect |
| Can’t access even after entering the passkey (Insufficient Authentication) |
With this peer combination it became Just Works, giving an unauthenticated key |
Check authenticated=0 in the log. Check the peer’s IO Capability |
| No pairing dialog appears |
No protected characteristics, or no Security Request sent |
*_ENC / *_AUTHEN flags, ble_gap_security_initiate() |
| Notify arrives even though not paired |
The CCCD is not protected |
Add BLE_GATT_CHR_F_NOTIFY_INDICATE_ENC / _AUTHEN |
| Bonds are not saved from the 4th device on |
Storage is full (3 entries by default) |
store_status_cb = ble_store_util_status_rr, or increase CONFIG_BT_NIMBLE_MAX_BONDS |
- ESP32-C3 side:
idf.py -p PORT erase-flash (this erases the whole flash, including the app; flash again). From a program, ble_store_clear() also works
- Phone side: in the OS’s Bluetooth settings, “Forget this device” for
HANDSON-C3-XXXX
- The basic rule is to delete on both sides together
Unstable behaviour
task_wdt: Task watchdog got triggered |
Not waiting inside a loop, or doing long processing in a callback |
Add vTaskDelay(). Turn heavy processing into an event for another task |
Resets with Stack overflow in task … |
Task stack too small |
Increase the stack size in xTaskCreate(). Make large arrays static |
| BLE responses suddenly become slow |
Waiting in a host task callback |
Callbacks only post (Chapter 10) |
queue full, drop … appears |
Handler processing can’t keep up with event generation |
Make handlers faster. Lengthening the queue only treats the symptom |
Reading logs
To see NimBLE’s own logs in detail, set idf.py menuconfig → Component config → Bluetooth → NimBLE Options → NimBLE Host log verbosity to Debug. It produces a large amount of ATT and SM traffic, so use it only when investigating a problem.
To see the BLE communication itself, a sniffer such as nRF52840 Dongle + nRF Sniffer for Bluetooth LE + Wireshark lets you observe advertising, connection and pairing packets (contents after encryption cannot be read without the keys).