12  トラブルシューティング

ハンズオンや実際の開発でよく出会う症状と、原因・対処をまとめます。

12.1 ビルド・書き込み

症状 原因 対処
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 を読めていない 一度ビルドしてから、言語サーバーを再起動する

12.2 見つからない・つながらない

症状 原因 対処
スキャンに出てこない アドバタイズが始まっていない ログに 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 を使う

12.3 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)を確認する

12.4 ペアリング

症状 原因 対処
毎回パスキーを聞かれる ボンディングしていない、またはボンド情報が保存されていない 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 の「このデバイスの登録を解除」
  • 両方そろえて消す のが基本です

12.5 動作が不安定

症状 原因 対処
task_wdt: Task watchdog got triggered ループの中で待っていない、コールバックで長い処理をしている vTaskDelay() を入れる。重い処理はイベントにして別タスクへ
Stack overflow in task … でリセット タスクのスタック不足 xTaskCreate() のスタックサイズを増やす。大きな配列は static に
BLE の応答が急に遅くなる ホストタスクのコールバックで待っている コールバックは 積むだけ(第 10 章)
queue full, drop … が出る ハンドラの処理がイベントの発生に追いつかない ハンドラを速くする。キューを長くするのは対症療法

12.6 ログの読み方

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 のようなスニファで、アドバタイズ・接続・ペアリングのパケットを観察できます(暗号化後の中身は、鍵がないと読めません)。