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
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 にまだ書かれていない項目 の初期値にしか使われません。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 アクセス)もこのタスクの中で呼ばれます。
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 が呼ばれる |
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 の受信に使う) |
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 が解放する