5  アドバタイズして接続を待つ

Step 2(firmware/step2_advertise)では、NimBLE を起動してアドバタイズし、スマホから接続できるところまで作ります。まだ独自のサービスはありません。

5.1 全体のコード

/*
 * Step 2: アドバタイズして接続を待つ
 *
 * - NimBLE を初期化し、ホストタスクを起動する
 * - ホストとコントローラの同期 (sync) が取れたらアドバタイズを開始する
 * - 接続・切断などの GAP イベントをログに出す
 */
#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "nvs_flash.h"

#include "nimble/nimble_port.h"
#include "nimble/nimble_port_freertos.h"
#include "host/ble_hs.h"
#include "host/util/util.h"
#include "services/gap/ble_svc_gap.h"

#define TAG "STEP2"

static uint8_t own_addr_type;
static char device_name[20];

static void start_advertising(void);

/* ---------------- GAP イベント ---------------- */

static int gap_event_cb(struct ble_gap_event *event, void *arg)
{
    switch (event->type) {
    case BLE_GAP_EVENT_CONNECT:
        ESP_LOGI(TAG, "connect %s status=%d conn_handle=%d",
                 event->connect.status == 0 ? "ok" : "failed",
                 event->connect.status, event->connect.conn_handle);
        if (event->connect.status != 0) {
            start_advertising(); // 接続に失敗したらアドバタイズを再開
        }
        return 0;

    case BLE_GAP_EVENT_DISCONNECT:
        ESP_LOGI(TAG, "disconnect reason=0x%x", event->disconnect.reason);
        start_advertising(); // 切断されたらアドバタイズを再開
        return 0;

    case BLE_GAP_EVENT_CONN_UPDATE:
        ESP_LOGI(TAG, "connection parameters updated status=%d", event->conn_update.status);
        return 0;

    case BLE_GAP_EVENT_ADV_COMPLETE:
        ESP_LOGI(TAG, "advertising complete reason=%d", event->adv_complete.reason);
        start_advertising();
        return 0;

    case BLE_GAP_EVENT_MTU:
        ESP_LOGI(TAG, "mtu=%d", event->mtu.value);
        return 0;

    default:
        return 0;
    }
}

/* ---------------- アドバタイズ ---------------- */

static void start_advertising(void)
{
    struct ble_hs_adv_fields fields = { 0 };
    struct ble_gap_adv_params adv_params = { 0 };
    const char *name = ble_svc_gap_device_name();

    // アドバタイズパケット (最大 31 バイト) に載せる内容
    fields.flags = BLE_HS_ADV_F_DISC_GEN | BLE_HS_ADV_F_BREDR_UNSUP;
    fields.tx_pwr_lvl_is_present = 1;
    fields.tx_pwr_lvl = BLE_HS_ADV_TX_PWR_LVL_AUTO;
    fields.name = (uint8_t *)name;
    fields.name_len = strlen(name);
    fields.name_is_complete = 1;

    int rc = ble_gap_adv_set_fields(&fields);
    if (rc != 0) {
        ESP_LOGE(TAG, "ble_gap_adv_set_fields rc=%d", rc);
        return;
    }

    adv_params.conn_mode = BLE_GAP_CONN_MODE_UND; // 誰からでも接続を受ける
    adv_params.disc_mode = BLE_GAP_DISC_MODE_GEN; // 一般発見可能
    adv_params.itvl_min = BLE_GAP_ADV_ITVL_MS(100);
    adv_params.itvl_max = BLE_GAP_ADV_ITVL_MS(150);

    rc = ble_gap_adv_start(own_addr_type, NULL, BLE_HS_FOREVER,
                           &adv_params, gap_event_cb, NULL);
    if (rc != 0) {
        ESP_LOGE(TAG, "ble_gap_adv_start rc=%d", rc);
        return;
    }
    ESP_LOGI(TAG, "advertising as \"%s\"", name);
}

/* ---------------- ホストのコールバック ---------------- */

// ホストとコントローラの同期が取れた(BLE が使えるようになった)
static void on_sync(void)
{
    uint8_t addr[6];

    ble_hs_util_ensure_addr(0);
    ble_hs_id_infer_auto(0, &own_addr_type);
    ble_hs_id_copy_addr(own_addr_type, addr, NULL);

    // 同じ部屋に何台あっても区別できるよう、アドレスの下位 2 バイトを名前に付ける
    snprintf(device_name, sizeof(device_name), "HANDSON-C3-%02X%02X", addr[1], addr[0]);
    ble_svc_gap_device_name_set(device_name);
    ESP_LOGI(TAG, "address %02X:%02X:%02X:%02X:%02X:%02X",
             addr[5], addr[4], addr[3], addr[2], addr[1], addr[0]);

    start_advertising();
}

static void on_reset(int reason)
{
    ESP_LOGE(TAG, "nimble reset reason=%d", reason);
}

static void host_task(void *param)
{
    nimble_port_run(); // nimble_port_stop() が呼ばれるまで戻らない
    nimble_port_freertos_deinit();
}

void app_main(void)
{
    // NimBLE は PHY のキャリブレーションデータ等に NVS を使う
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        ret = nvs_flash_init();
    }
    ESP_ERROR_CHECK(ret);

    ESP_ERROR_CHECK(nimble_port_init()); // コントローラ + ホストの初期化

    ble_hs_cfg.reset_cb = on_reset;
    ble_hs_cfg.sync_cb = on_sync;

    ble_svc_gap_init(); // GAP サービス (デバイス名など) を登録

    nimble_port_freertos_init(host_task); // ホストタスクを起動
}

上から順に見ていきます。

5.2 app_main:初期化

ESP_ERROR_CHECK(nimble_port_init());
ble_hs_cfg.reset_cb = on_reset;
ble_hs_cfg.sync_cb = on_sync;
ble_svc_gap_init();
nimble_port_freertos_init(host_task);

第 4 章の初期化の順番どおりです。app_main() はこのあと すぐに戻ります が、ホストタスクが動き続けるので BLE は止まりません。

ESP_ERROR_CHECK() は、戻り値が ESP_OK でなければエラーを表示してリセットするマクロです。初期化の失敗は、続けても意味がないのでこれで止めます。

5.3 on_sync:アドレスと名前

ble_hs_util_ensure_addr(0);
ble_hs_id_infer_auto(0, &own_addr_type);
ble_hs_id_copy_addr(own_addr_type, addr, NULL);
関数 内容
ble_hs_util_ensure_addr(0) 使えるアドレスがあることを確認する(引数 0 = プライバシー用のランダムアドレスは使わない)
ble_hs_id_infer_auto(0, &type) 使うアドレスの種類を自動で選ぶ。ESP32-C3 は Public アドレスを持っているので Public になる
ble_hs_id_copy_addr(type, addr, NULL) アドレスの 6 バイトを取得する。addr[0] が最下位バイト(リトルエンディアン)

ログに表示するときは addr[5] から順に出すと、ふだん見かける AA:BB:CC:DD:EE:FF の形になります。

snprintf(device_name, sizeof(device_name), "HANDSON-C3-%02X%02X", addr[1], addr[0]);
ble_svc_gap_device_name_set(device_name);

デバイス名は、GAP サービスの Device Name キャラクタリスティック(0x2A00) の値です。アドバタイズにもこの名前を載せます。ハンズオンでは全員が同じファームを書き込むので、アドレスの下位 2 バイトを名前に付けて 自分のボードを見分けられるようにしています。

5.4 start_advertising:何を、どう発信するか

5.4.1 アドバタイズデータ

fields.flags = BLE_HS_ADV_F_DISC_GEN | BLE_HS_ADV_F_BREDR_UNSUP;
fields.tx_pwr_lvl_is_present = 1;
fields.tx_pwr_lvl = BLE_HS_ADV_TX_PWR_LVL_AUTO;
fields.name = (uint8_t *)name;
fields.name_len = strlen(name);
fields.name_is_complete = 1;
ble_gap_adv_set_fields(&fields);

struct ble_hs_adv_fields に載せたい項目を書くと、ble_gap_adv_set_fields() が第 2 章の AD 構造のバイト列 に組み立ててくれます。

フィールド AD タイプ バイト数
flags 0x01 Flags 3
tx_pwr_lvl 0x0A TX Power Level(AUTO = 現在の送信電力を自動で入れる) 3
name(name_is_complete = 1) 0x09 Complete Local Name 2 + 15 = 17
合計 23 / 31

31 バイトを超えると ble_gap_adv_set_fields() が BLE_HS_EMSGSIZE を返します。

5.4.2 アドバタイズのパラメータ

adv_params.conn_mode = BLE_GAP_CONN_MODE_UND;
adv_params.disc_mode = BLE_GAP_DISC_MODE_GEN;
adv_params.itvl_min = BLE_GAP_ADV_ITVL_MS(100);
adv_params.itvl_max = BLE_GAP_ADV_ITVL_MS(150);
設定 値 意味
conn_mode BLE_GAP_CONN_MODE_UND Undirected:誰からでも 接続を受ける(NON にすると接続不可、DIR は特定の相手だけ)
disc_mode BLE_GAP_DISC_MODE_GEN General:いつでも発見可能(LTD は限定時間だけ)
itvl_min / itvl_max 100〜150 ms アドバタイズ間隔。BLE_GAP_ADV_ITVL_MS() が 0.625 ms 単位に変換する

itvl_min / itvl_max を 0 のままにすると、NimBLE の既定値(30〜60 ms)が使われます。

5.4.3 開始

ble_gap_adv_start(own_addr_type, NULL, BLE_HS_FOREVER, &adv_params, gap_event_cb, NULL);
引数 値 意味
own_addr_type Public 自分のアドレスの種類
direct_addr NULL 特定の相手向けのアドバタイズではない
duration_ms BLE_HS_FOREVER 時間制限なし(時間を決めると、終了時に BLE_GAP_EVENT_ADV_COMPLETE)
cb gap_event_cb この広告から生まれた接続の GAP イベント を受け取る関数

5.5 gap_event_cb:接続と切断

case BLE_GAP_EVENT_DISCONNECT:
    ESP_LOGI(TAG, "disconnect reason=0x%x", event->disconnect.reason);
    start_advertising(); // 切断されたらアドバタイズを再開

BLE のペリフェラルは、接続すると自動でアドバタイズを止めます(同時接続数が 1 のとき)。切断されても 自動では再開しない ので、BLE_GAP_EVENT_DISCONNECT でもう一度 start_advertising() を呼びます。これを忘れると、「一度切断したら二度と見つからない」デバイスになります。

5.6 動かしてみる

cd firmware/step2_advertise
idf.py set-target esp32c3
idf.py build
idf.py -p PORT flash monitor

起動すると、次のようなログが出ます(アドレスはボードごとに違います)。

I (xxx) STEP2: address 34:85:18:XX:12:34
I (xxx) STEP2: advertising as "HANDSON-C3-1234"

5.6.1 nRF Connect でスキャンする

  1. スマホで nRF Connect を開き、SCANNER タブで SCAN を押す
  2. HANDSON-C3-XXXX を見つけてタップすると、アドバタイズの中身が見える
    • Flags: GeneralDiscoverable, BrEdrNotSupported
    • Tx Power Level
    • Complete Local Name: HANDSON-C3-XXXX
    • RSSI(受信強度)。ボードに近づける・離すと変わる
  3. 右の三本線(または RAW)を押すと、AD 構造の生のバイト列 が見える。第 2 章の表と見比べよう
  4. CONNECT を押すと接続し、シリアルモニタに connect ok が出る。GAP(0x1800)と GATT(0x1801)の 2 つのサービスだけが見える
  5. DISCONNECT を押すと、disconnect reason=0x213(相手が切断)が出て、またアドバタイズが始まる
ヒントやってみよう
  1. RAW のバイト列を 1 つずつ区切り、「長さ・タイプ・データ」に分解してみよう
  2. fields.name に 25 文字の名前を入れるとどうなるか? ble_gap_adv_set_fields() の戻り値をログに出して確かめよう
  3. itvl_min / itvl_max を 1000 ms にすると、nRF Connect のスキャン一覧での見つかりやすさ・RSSI の更新頻度はどう変わるか?
  4. 接続したまま、ボードを遠ざけたり、アンテナを外したりして、どの reason で切断されるか見てみよう
  1. Flags (3) + TX Power (3) + 名前 (2 + 25) = 33 バイトで 31 バイトを超えるので、BLE_HS_EMSGSIZE(4)が返り、アドバタイズは開始されません。名前を短くするか、スキャン応答に移します(Step 3 でそうしています)。
  2. アドバタイズの頻度が下がるので、見つかるまでに時間がかかり、RSSI の更新も遅くなります。そのかわり消費電力は下がります。
  3. 電波が届かなくなって Supervision Timeout が過ぎると、reason=0x208(Connection Timeout)になります。
重要キーポイント
  • アドバタイズの開始は sync_cb の中 から
  • ble_hs_adv_fields に書いた項目が AD 構造 になる。31 バイト以内
  • 切断されたら 自分でアドバタイズを再開 する