ハンズオンや実際の開発でよく出会う症状と、原因・対処をまとめます。
ビルド・書き込み
nimble/nimble_port.h: No such file or directory |
main/CMakeLists.txt の PRIV_REQUIRES に bt がない、または sdkconfig で BLE が無効 |
PRIV_REQUIRES bt を書く。sdkconfig を削除して作り直す(第 4 章) |
sdkconfig.defaults を直したのに反映されない |
sdkconfig に既に値が書かれている |
sdkconfig を削除してからビルド、または idf.py menuconfig |
ble_store_config_init が見つからない(暗黙の宣言) |
公開ヘッダに宣言がない |
void ble_store_config_init(void); を自分で宣言する |
書き込みが Failed to connect で止まる |
ダウンロードモードに入れない、別のアプリがポートを使っている |
シリアルモニタを閉じる。BOOT を押したまま RESET(第 1 章) |
idf.py が見つからない |
環境を有効にしていない |
source ~/.espressif/tools/activate_idf_v6.0.1.sh(パスは環境に合わせる) |
| VS Code のエディタに赤い波線が大量に出るが、ビルドは通る |
補完(clangd / IntelliSense)が build/compile_commands.json を読めていない |
一度ビルドしてから、言語サーバーを再起動する |
見つからない・つながらない
| スキャンに出てこない |
アドバタイズが始まっていない |
ログに advertising as … が出ているか。ble_gap_adv_set_fields() の戻り値(31 バイト超過で BLE_HS_EMSGSIZE) |
| 一度切断すると二度と見つからない |
切断時にアドバタイズを再開していない |
BLE_GAP_EVENT_DISCONNECT で start_advertising() |
| 少し離れるとすぐ切れる / 見つからない |
XIAO ESP32C3 の アンテナが付いていない |
付属のアンテナを U.FL コネクタに付ける |
| 名前が古いまま表示される |
スマホ・PC が名前を キャッシュ している |
Bluetooth をオフ・オンする。nRF Connect ではスキャンし直す |
| Web Bluetooth の一覧に出ない |
アドバタイズにサービス UUID がない(Step 2)、ブラウザが非対応 |
Step 3 以降を書き込む。Chrome / Edge を使う |
Notify が届かない
| Notify が来ない |
Client が CCCD を購読していない |
nRF Connect で ↓↓↓ を押す。ログに subscribe … notify=1 が出るか |
| コマンドの応答だけ来ない |
Command 側の CCCD を購読していない |
応答を返すキャラクタリスティックの Notify も有効にする |
rc=6(BLE_HS_ENOMEM)が出る |
送信が速すぎて mbuf が足りない |
送信周期を延ばす、まとめて送る(第 6 章) |
rc=7(BLE_HS_ENOTCONN) |
切断後に送ろうとした |
接続ハンドルを確認してから送る |
| 20 バイトを超えるデータが途中で切れる |
MTU が 23 のまま |
分割して送る、MTU 交渉の結果(BLE_GAP_EVENT_MTU)を確認する |
ペアリング
| 毎回パスキーを聞かれる |
ボンディングしていない、またはボンド情報が保存されていない |
sm_bonding = 1、ble_store_config_init()、CONFIG_BT_NIMBLE_NVS_PERSIST=y |
接続直後に切断される・暗号化に失敗する(enc change status≠0) |
片方だけがボンド情報を持っている(ESP32-C3 を erase-flash した、など) |
スマホ・PC 側の登録も解除 してから接続し直す |
| パスキーを入れてもアクセスできない(Insufficient Authentication) |
相手との組み合わせで Just Works になり、認証されていない鍵になった |
ログの authenticated=0 を確認。相手の IO Capability を確認する |
| ペアリングのダイアログが出ない |
保護されたキャラクタリスティックがない、Security Request を送っていない |
*_ENC / *_AUTHEN フラグ、ble_gap_security_initiate() |
| 未ペアリングなのに Notify が届く |
CCCD が保護されていない |
BLE_GATT_CHR_F_NOTIFY_INDICATE_ENC / _AUTHEN を付ける |
| ボンドが 4 台目から保存されない |
保存領域が満杯(既定 3 件) |
store_status_cb = ble_store_util_status_rr、または CONFIG_BT_NIMBLE_MAX_BONDS を増やす |
- ESP32-C3 側:
idf.py -p PORT erase-flash(Flash 全体を消すのでアプリも消える。書き込み直す)。プログラムからは ble_store_clear() でも消せる
- スマホ側: OS の Bluetooth 設定で、
HANDSON-C3-XXXX の「このデバイスの登録を解除」
- 両方そろえて消す のが基本です
動作が不安定
task_wdt: Task watchdog got triggered |
ループの中で待っていない、コールバックで長い処理をしている |
vTaskDelay() を入れる。重い処理はイベントにして別タスクへ |
Stack overflow in task … でリセット |
タスクのスタック不足 |
xTaskCreate() のスタックサイズを増やす。大きな配列は static に |
| BLE の応答が急に遅くなる |
ホストタスクのコールバックで待っている |
コールバックは 積むだけ(第 10 章) |
queue full, drop … が出る |
ハンドラの処理がイベントの発生に追いつかない |
ハンドラを速くする。キューを長くするのは対症療法 |
ログの読み方
NimBLE 自身のログを詳しく見たいときは、idf.py menuconfig → Component config → Bluetooth → NimBLE Options → NimBLE Host log verbosity を Debug にします。ATT・SM のやりとりが大量に出るので、問題を調べるときだけにしましょう。
BLE の通信そのものを見たいときは、nRF52840 Dongle + nRF Sniffer for Bluetooth LE + Wireshark のようなスニファで、アドバタイズ・接続・ペアリングのパケットを観察できます(暗号化後の中身は、鍵がないと読めません)。