4  ESP-IDF の BLE スタック NimBLE

4.1 Bluedroid と NimBLE

ESP-IDF には、BLE のホスト(第 2 章の GAP・GATT・ATT・SM・L2CAP)の実装が 2 つ入っています。

Bluedroid NimBLE
由来 Android の Bluetooth スタック Apache Mynewt の BLE スタック
対応 Bluetooth Classic + BLE BLE のみ
サイズ 大きい 小さい(Flash・RAM とも少ない)
API esp_ble_gap_*、esp_ble_gatts_*(Espressif 独自のラッパー) ble_gap_*、ble_gatts_*(仕様の用語に近い)

ESP32-C3 は Bluetooth Classic を持たないので、Bluedroid を選ぶ理由はほとんどありません。このハンズオンでは NimBLE を使います。

4.2 sdkconfig で BLE を有効にする

ESP-IDF の Bluetooth は 既定で無効 です。sdkconfig.defaults に次を書きます(Step 2〜4)。

CONFIG_IDF_TARGET="esp32c3"

# Bluetooth (NimBLE, BLE only)
CONFIG_BT_ENABLED=y
CONFIG_BT_NIMBLE_ENABLED=y
CONFIG_BT_NIMBLE_MAX_CONNECTIONS=1
設定 意味
CONFIG_BT_ENABLED Bluetooth コンポーネントを有効にする
CONFIG_BT_NIMBLE_ENABLED ホストに NimBLE を使う(Bluedroid ではなく)
CONFIG_BT_NIMBLE_MAX_CONNECTIONS 同時接続数。1 台だけ受けるなら 1 にしてメモリを節約

idf.py menuconfig では Component config → Bluetooth の下で同じ設定ができます。ほかにも、

  • Component config → Bluetooth → NimBLE Options → Preferred MTU size(既定 256)
  • … → NimBLE Options → NimBLE Host task stack size(既定 4096 バイト)
  • … → NimBLE Options → Maximum number of bonds to save across reboots(既定 3)

などが並んでいます。

警告sdkconfig.defaults を書き換えても反映されないことがある

sdkconfig.defaults は、sdkconfig にまだ書かれていない項目 の初期値にしか使われません。Step 1 のように BLE なしで一度ビルドすると、sdkconfig に # CONFIG_BT_ENABLED is not set(=無効)が 書き込まれた状態 になります。そのあと sdkconfig.defaults に CONFIG_BT_ENABLED=y を足しても、sdkconfig の値が優先されて BLE は有効になりません。

対処: sdkconfig を削除してからビルドし直す(sdkconfig.defaults から作り直される)か、idf.py menuconfig で直接有効にします。サンプルの各ステップは sdkconfig を含めていないので、最初のビルドで正しく作られます。

4.3 NimBLE の動き方

4.3.1 ホストタスク

NimBLE のホストは、専用の FreeRTOS タスク(ホストタスク) の中で動きます。コントローラから届いたイベント(接続された、データが届いた…)は、すべてこのタスクで処理され、アプリのコールバック(GAP イベント、GATT アクセス)もこのタスクの中で呼ばれます。

flowchart LR
  subgraph C["コントローラ"]
    LL["Link Layer"]
  end
  subgraph HT["ホストタスク (nimble_port_run)"]
    Q[("イベントキュー")]
    H["NimBLE ホスト<br/>GAP / GATT / ATT / SM"]
    CB["アプリのコールバック<br/>gap_event_cb()<br/>gatt_access_cb()"]
    Q --> H --> CB
  end
  subgraph APP["アプリのタスク"]
    M["app_main / notify_task"]
  end
  LL -->|"HCI イベント"| Q
  M -->|"ble_gatts_notify_custom() など<br/>(内部でロックを取る)"| H

重要コールバックの中で待たない

gap_event_cb() や gatt_access_cb() は ホストタスクの中 で呼ばれます。ここで vTaskDelay() したり、重い処理をしたりすると、その間 BLE の処理全体が止まります(次のパケットが処理されない、ペアリングがタイムアウトする…)。コールバックでは 状態を記録する・データをコピーする・イベントを積む ぐらいにとどめ、重い処理は別のタスクで行います(第 10 章)。

一方、ble_gatts_notify_custom() などのホスト API は、内部で ロックを取ってから 処理するので、別のタスクから呼んでも構いません。ESP-IDF のサンプル blehr(心拍計)も、FreeRTOS のソフトウェアタイマーのコールバックから Notify を送っています。

4.3.2 初期化の順番

NimBLE を使うアプリの app_main() は、ほぼ次の形になります。

sequenceDiagram
  participant A as app_main
  participant N as NimBLE
  participant H as ホストタスク
  A->>A: nvs_flash_init()
  A->>N: nimble_port_init()<br/>(コントローラ + ホストを初期化)
  A->>N: ble_hs_cfg に sync_cb / reset_cb / sm_* を設定
  A->>N: ble_svc_gap_init() / ble_svc_gatt_init()
  A->>N: ble_gatts_count_cfg() / ble_gatts_add_svcs()<br/>(自分のサービスを登録)
  A->>H: nimble_port_freertos_init(host_task)<br/>(ホストタスクを起動)
  H->>H: nimble_port_run()
  H-->>H: コントローラと同期
  H->>A: sync_cb() — ここで初めて BLE が使える
  A->>N: ble_gap_adv_start()(アドバタイズ開始)

関数 役割
nvs_flash_init() 不揮発ストレージの初期化。無線(PHY)のキャリブレーションデータや、ボンディング情報(第 9 章)の保存に使う
nimble_port_init() コントローラとホストの初期化
ble_hs_cfg ホストの設定(コールバック、セキュリティ)を入れるグローバル変数。ホストタスクを起動する前に 設定する
ble_svc_gap_init() 標準の GAP サービス(0x1800:デバイス名など)を登録
ble_svc_gatt_init() 標準の GATT サービス(0x1801:Service Changed)を登録
ble_gatts_count_cfg() 自分のサービス定義を数えて、必要なメモリ量をホストに伝える
ble_gatts_add_svcs() 自分のサービス定義をキューに登録(実際に属性の表に載るのは同期後)
nimble_port_freertos_init() ホストタスクを作る。タスクの中で nimble_port_run() を呼ぶ
sync_cb ホストとコントローラの同期が取れたとき に呼ばれる。アドバタイズはここから始める
reset_cb コントローラとの不整合などでホストがリセットされたとき。リセット後、また sync_cb が呼ばれる
警告sync 前に BLE の API を呼ばない

app_main() の最後で ble_gap_adv_start() を呼ぶと、まだ同期していないので失敗します。アドバタイズの開始やアドレスの取得は sync_cb の中 で行います。

4.3.3 イベントで知らせる GAP

接続・切断・購読・ペアリングなど、GAP に関わる出来事は、すべて 1 つのコールバック に struct ble_gap_event として届きます。どのコールバックに届くかは、ble_gap_adv_start() に渡した関数で決まります(接続を受け入れたアドバタイズのコールバックが、その接続のイベントを受け取る)。

イベント いつ
BLE_GAP_EVENT_CONNECT 接続した(または接続に失敗した: status != 0)
BLE_GAP_EVENT_DISCONNECT 切断した(reason に理由)
BLE_GAP_EVENT_ADV_COMPLETE アドバタイズが終わった(時間切れなど)
BLE_GAP_EVENT_CONN_UPDATE 接続パラメータが変わった
BLE_GAP_EVENT_MTU MTU が決まった
BLE_GAP_EVENT_SUBSCRIBE CCCD が書き込まれた(Notify / Indicate の購読・解除)
BLE_GAP_EVENT_ENC_CHANGE 暗号化が始まった・失敗した
BLE_GAP_EVENT_PASSKEY_ACTION ペアリングでパスキーの表示・入力が必要になった
BLE_GAP_EVENT_REPEAT_PAIRING ボンド済みの相手が、ペアリングをやり直そうとしている

4.4 mbuf:NimBLE のパケットバッファ

NimBLE は、パケットのデータを struct os_mbuf(メモリバッファ)という単位で扱います。mbuf は固定サイズのブロックを チェーン でつないだもので、長いデータは複数のブロックにまたがります。

関数・マクロ 用途
ble_hs_mbuf_from_flat(data, len) 普通の配列から mbuf を作る(Notify の送信に使う)
os_mbuf_append(om, data, len) mbuf の末尾にデータを足す(Read の応答に使う)
OS_MBUF_PKTLEN(om) mbuf チェーン全体の長さ
ble_hs_mbuf_to_flat(om, buf, max, &len) mbuf を普通の配列にコピー(Write の受信に使う)
ノートmbuf の持ち主

ble_gatts_notify_custom(conn, handle, om) に渡した om は、成功しても失敗しても NimBLE が解放します。呼び出し側で os_mbuf_free_chain() してはいけません(二重解放になる)。逆に、Write で受け取った ctxt->om はホストの持ち物なので、コールバックを抜けたら使えません。必要なデータは配列にコピーします。

重要キーポイント
  • ESP32-C3 の BLE には NimBLE を使う。sdkconfig で有効にする
  • コールバックは ホストタスク の中で呼ばれる。待たない・重いことをしない
  • BLE の API は sync_cb のあと から使える
  • GAP の出来事は 1 つのコールバック に BLE_GAP_EVENT_* として届く
  • データは mbuf で受け渡す。送った mbuf は NimBLE が解放する