7  コマンドを受け取って応答する

Step 4(firmware/step4_command)では、2 つ目のキャラクタリスティック Command を追加し、スマホから書き込まれたコマンドに応じて 応答を Notify で返す ようにします。

7.1 構成

flowchart TB
  S["サービス c0a60001-…"] --> CNT["Counter c0a60002-…<br/>Read / Notify<br/>1 秒ごとにカウンタ"]
  S --> CMD["Command c0a60003-…<br/>Write / Notify<br/>コマンドを受け、応答を返す"]

コマンドを書き込むキャラクタリスティックと、応答を返すキャラクタリスティックを 同じものにする か 分ける かは設計次第です。

方式 長所 短所
同じキャラクタリスティック(このサンプル) どの応答がどのコマンドに対するものか追いやすい Write と Notify の両方のプロパティを持つ
分ける(RX / TX) Nordic UART Service と同じ形。ストリーム的に使える 応答を区別する仕組み(先頭バイトなど)が必要

どちらの場合も、応答の先頭にコマンド番号を入れて、受け手がどのコマンドへの応答かを判別できるようにしておくと便利です。

7.2 プロトコル

コマンド(Write) 意味 応答(Notify)
00 PING 00 50 4F 4E 47(00 + ASCII の PONG)
01 STATUS 01 + カウンタ(u32 LE)+ 起動からの秒数(u32 LE)の 9 バイト
それ以外 未定義 <コマンド> FF

例えばカウンタが 300(0x12C)、起動から 305 秒(0x131)なら、STATUS の応答は

01  2C 01 00 00  31 01 00 00
│   └ counter    └ uptime
└ コマンド番号

になります。

7.3 全体のコード

/*
 * Step 4: コマンドを受け取って応答する
 *
 * Service : c0a60001-18ff-4cd1-afce-4832ee44bcb7
 *   Counter (Read / Notify)  : c0a60002-...  uint32 リトルエンディアン
 *   Command (Write / Notify) : c0a60003-...  コマンドを書き込み、応答は Notify
 *
 * コマンド:
 *   0x00 -> PING   : 応答 [0x00, 'P','O','N','G']
 *   0x01 -> STATUS : 応答 [0x01, counter(u32 LE), uptime_sec(u32 LE)]
 *   その他          : 応答 [cmd, 0xFF]
 */
#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.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"
#include "services/gatt/ble_svc_gatt.h"

#define TAG "STEP4"

#define CMD_PING   0x00
#define CMD_STATUS 0x01

/* c0a60001-18ff-4cd1-afce-4832ee44bcb7(バイト列は逆順=リトルエンディアンで書く) */
static const ble_uuid128_t svc_uuid =
    BLE_UUID128_INIT(0xb7, 0xbc, 0x44, 0xee, 0x32, 0x48, 0xce, 0xaf,
                     0xd1, 0x4c, 0xff, 0x18, 0x01, 0x00, 0xa6, 0xc0);
static const ble_uuid128_t counter_chr_uuid =
    BLE_UUID128_INIT(0xb7, 0xbc, 0x44, 0xee, 0x32, 0x48, 0xce, 0xaf,
                     0xd1, 0x4c, 0xff, 0x18, 0x02, 0x00, 0xa6, 0xc0);
static const ble_uuid128_t cmd_chr_uuid =
    BLE_UUID128_INIT(0xb7, 0xbc, 0x44, 0xee, 0x32, 0x48, 0xce, 0xaf,
                     0xd1, 0x4c, 0xff, 0x18, 0x03, 0x00, 0xa6, 0xc0);

static uint8_t own_addr_type;
static char device_name[20];
static uint16_t conn_handle = BLE_HS_CONN_HANDLE_NONE;
static uint16_t counter_val_handle;
static uint16_t cmd_val_handle;
static bool counter_notify_enabled;
static bool cmd_notify_enabled;
static uint32_t counter;

static void start_advertising(void);

/* ---------------- GATT ---------------- */

static int notify(uint16_t attr_handle, const void *data, uint16_t len)
{
    if (conn_handle == BLE_HS_CONN_HANDLE_NONE) {
        return BLE_HS_ENOTCONN;
    }
    struct os_mbuf *om = ble_hs_mbuf_from_flat(data, len);
    if (om == NULL) {
        return BLE_HS_ENOMEM;
    }
    return ble_gatts_notify_custom(conn_handle, attr_handle, om);
}

static void handle_command(const uint8_t *buf, uint16_t len)
{
    uint8_t rsp[9];
    uint16_t rsp_len;
    uint8_t cmd = buf[0];

    switch (cmd) {
    case CMD_PING:
        rsp[0] = CMD_PING;
        memcpy(&rsp[1], "PONG", 4);
        rsp_len = 5;
        break;
    case CMD_STATUS: {
        uint32_t uptime = (uint32_t)(esp_timer_get_time() / 1000000);
        rsp[0] = CMD_STATUS;
        memcpy(&rsp[1], &counter, 4); // ESP32-C3 (RISC-V) はリトルエンディアン
        memcpy(&rsp[5], &uptime, 4);
        rsp_len = 9;
        break;
    }
    default:
        rsp[0] = cmd;
        rsp[1] = 0xFF; // 未定義コマンド
        rsp_len = 2;
        break;
    }

    ESP_LOGI(TAG, "cmd 0x%02x (len=%d) -> rsp len=%d", cmd, len, rsp_len);
    if (cmd_notify_enabled) {
        notify(cmd_val_handle, rsp, rsp_len);
    } else {
        ESP_LOGW(TAG, "command notify not enabled, response dropped");
    }
}

static int gatt_access_cb(uint16_t conn, uint16_t attr_handle,
                          struct ble_gatt_access_ctxt *ctxt, void *arg)
{
    switch (ctxt->op) {
    case BLE_GATT_ACCESS_OP_READ_CHR:
        if (attr_handle == counter_val_handle) {
            int rc = os_mbuf_append(ctxt->om, &counter, sizeof(counter));
            return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES;
        }
        return BLE_ATT_ERR_UNLIKELY;

    case BLE_GATT_ACCESS_OP_WRITE_CHR:
        if (attr_handle == cmd_val_handle) {
            uint8_t buf[20];
            uint16_t len = OS_MBUF_PKTLEN(ctxt->om);
            if (len == 0 || len > sizeof(buf)) {
                return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN;
            }
            // mbuf (チェーンになっていることがある) を平らな配列にコピー
            ble_hs_mbuf_to_flat(ctxt->om, buf, sizeof(buf), &len);
            handle_command(buf, len);
            return 0; // 0 を返すと Write Response が成功で返る
        }
        return BLE_ATT_ERR_UNLIKELY;

    default:
        return BLE_ATT_ERR_UNLIKELY;
    }
}

static const struct ble_gatt_svc_def gatt_svcs[] = {
    {
        .type = BLE_GATT_SVC_TYPE_PRIMARY,
        .uuid = &svc_uuid.u,
        .characteristics = (struct ble_gatt_chr_def[]) {
            {
                .uuid = &counter_chr_uuid.u,
                .access_cb = gatt_access_cb,
                .val_handle = &counter_val_handle,
                .flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_NOTIFY,
            },
            {
                .uuid = &cmd_chr_uuid.u,
                .access_cb = gatt_access_cb,
                .val_handle = &cmd_val_handle,
                .flags = BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_NOTIFY,
            },
            { 0 },
        },
    },
    { 0 },
};

/* ---------------- 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",
                 event->connect.status == 0 ? "ok" : "failed", event->connect.status);
        if (event->connect.status == 0) {
            conn_handle = event->connect.conn_handle;
        } else {
            start_advertising();
        }
        return 0;

    case BLE_GAP_EVENT_DISCONNECT:
        ESP_LOGI(TAG, "disconnect reason=0x%x", event->disconnect.reason);
        conn_handle = BLE_HS_CONN_HANDLE_NONE;
        counter_notify_enabled = false;
        cmd_notify_enabled = false;
        start_advertising();
        return 0;

    case BLE_GAP_EVENT_ADV_COMPLETE:
        start_advertising();
        return 0;

    case BLE_GAP_EVENT_SUBSCRIBE:
        ESP_LOGI(TAG, "subscribe attr_handle=%d notify=%d",
                 event->subscribe.attr_handle, event->subscribe.cur_notify);
        if (event->subscribe.attr_handle == counter_val_handle) {
            counter_notify_enabled = event->subscribe.cur_notify;
        } else if (event->subscribe.attr_handle == cmd_val_handle) {
            cmd_notify_enabled = event->subscribe.cur_notify;
        }
        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_hs_adv_fields rsp_fields = { 0 };
    struct ble_gap_adv_params adv_params = { 0 };
    const char *name = ble_svc_gap_device_name();

    fields.flags = BLE_HS_ADV_F_DISC_GEN | BLE_HS_ADV_F_BREDR_UNSUP;
    fields.uuids128 = &svc_uuid;
    fields.num_uuids128 = 1;
    fields.uuids128_is_complete = 1;
    ble_gap_adv_set_fields(&fields);

    rsp_fields.name = (uint8_t *)name;
    rsp_fields.name_len = strlen(name);
    rsp_fields.name_is_complete = 1;
    ble_gap_adv_rsp_set_fields(&rsp_fields);

    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);
    int 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);
}

/* ---------------- ホスト ---------------- */

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);
    snprintf(device_name, sizeof(device_name), "HANDSON-C3-%02X%02X", addr[1], addr[0]);
    ble_svc_gap_device_name_set(device_name);
    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_freertos_deinit();
}

/* ---------------- 1 秒ごとの Notify ---------------- */

static void notify_task(void *param)
{
    while (1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
        counter++;
        if (counter_notify_enabled) {
            notify(counter_val_handle, &counter, sizeof(counter));
        }
    }
}

void app_main(void)
{
    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();
    ble_svc_gatt_init();
    ESP_ERROR_CHECK(ble_gatts_count_cfg(gatt_svcs));
    ESP_ERROR_CHECK(ble_gatts_add_svcs(gatt_svcs));

    nimble_port_freertos_init(host_task);
    xTaskCreate(notify_task, "notify", 3072, NULL, 5, NULL);
}

7.4 Write を受け取る

case BLE_GATT_ACCESS_OP_WRITE_CHR:
    if (attr_handle == cmd_val_handle) {
        uint8_t buf[20];
        uint16_t len = OS_MBUF_PKTLEN(ctxt->om);
        if (len == 0 || len > sizeof(buf)) {
            return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN;
        }
        ble_hs_mbuf_to_flat(ctxt->om, buf, sizeof(buf), &len);
        handle_command(buf, len);
        return 0;
    }
  1. OS_MBUF_PKTLEN() で 書き込まれたデータの長さ を調べる
  2. 長さが 0、または想定より長ければ BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN(ATT エラー 0x0D)を返して拒否する。Client にはエラーとして伝わる
  3. ble_hs_mbuf_to_flat() で mbuf を 普通の配列にコピー する。mbuf はチェーンになっていることがあるので、ctxt->om->om_data を直接読むのは避ける
  4. 処理して 0 を返すと、Write Response(成功) が返る
警告受信データは信用しない

BLE で受け取るデータは、誰がどんな内容を送ってくるかわからない 外部入力です。長さのチェックをせずに memcpy() すると、バッファオーバーフローの原因になります。長さ・値の範囲を必ず確認 しましょう。

7.4.1 Write Request と Write Command

BLE_GATT_CHR_F_WRITE は Write Request(応答あり)、BLE_GATT_CHR_F_WRITE_NO_RSP は Write Command(応答なし)を受け付けます。どちらで書き込まれても、アクセスコールバックは同じ BLE_GATT_ACCESS_OP_WRITE_CHR で呼ばれます。

Write Request Write Command
応答 Write Response が返る なし
エラーの通知 できる(戻り値の ATT エラーが返る) できない(戻り値は無視される)
速さ 1 往復待つ 速い(連続して送れる)

コマンドのように「届いたか・受理されたか」を知りたい用途では、Write Request を使います。

7.5 応答を返す

static void handle_command(const uint8_t *buf, uint16_t len)
{
    ...
    if (cmd_notify_enabled) {
        notify(cmd_val_handle, rsp, rsp_len);
    }
}

コマンドごとに応答のバイト列を組み立て、Command キャラクタリスティックの Notify で返します。応答を受け取るには、Client が Command の CCCD も購読 しておく必要があります。購読していなければ、ログに response dropped と出ます。

ノートWrite のコールバックの中で Notify してよいか

handle_command() は gatt_access_cb() から呼ばれるので、ホストタスクの中 で Notify を送っています。NimBLE は、アクセスコールバックを ホストのロックを解放した状態で 呼ぶ作りになっている(ソースの中で、ロックを持っていないことを確認するアサートがある)ので、コールバックの中から Notify などのホスト API を呼んでも構いません。ESP-IDF のサンプル bleprph も、Write のコールバックの中から ble_gatts_chr_updated() で通知を送っています。

ただし、応答を作る処理が重くなる場合は、第 10 章のようにイベントキューに回して、ホストタスクをすぐ返すほうが安全です。

7.5.1 エンディアンと memcpy

memcpy(&rsp[1], &counter, 4); // ESP32-C3 (RISC-V) はリトルエンディアン

CPU がリトルエンディアンなので、uint32_t をそのまま memcpy() するとリトルエンディアンのバイト列になります。ビッグエンディアンの CPU に移植する可能性 がある場合や、意図を明確にしたい場合は、

rsp[1] = (uint8_t)(counter >> 0);
rsp[2] = (uint8_t)(counter >> 8);
rsp[3] = (uint8_t)(counter >> 16);
rsp[4] = (uint8_t)(counter >> 24);

のようにシフトで書くか、NimBLE の put_le32(&rsp[1], counter) を使います。

7.6 動かしてみる

  1. nRF Connect で接続し、C0A60003-…(Command)の Notify を有効 にする
  2. ↑(Write) を押し、型を BYTE ARRAY にして 00 を送る → Command に (0x) 00-50-4F-4E-47 が届く。表示を UTF-8 にすると PONG が読める
  3. 01 を送る → 01 で始まる 9 バイトが届く。カウンタと秒数を読み取ってみよう
  4. 05 を送る → 05-FF が届く
  5. Command の Notify を 無効にしてから 00 を送ると、シリアルモニタに response dropped が出る
ヒントやってみよう
  1. 21 バイト以上のデータを書き込むとどうなるか?(nRF Connect でも長いデータを送れる)
  2. 0x02 で カウンタを 0 に戻す コマンドを追加しよう。応答は 02 00(成功)にする
  3. 0x03 xx で Notify の周期を xx 秒に変える コマンドを追加しよう。xx が 0 や 61 以上なら 03 FF を返す
static uint32_t notify_period_s = 1;   // notify_task は vTaskDelay(pdMS_TO_TICKS(notify_period_s * 1000)) にする

    case 0x02:
        counter = 0;
        rsp[0] = 0x02;
        rsp[1] = 0x00;
        rsp_len = 2;
        break;
    case 0x03:
        rsp[0] = 0x03;
        if (len >= 2 && buf[1] >= 1 && buf[1] <= 60) {
            notify_period_s = buf[1];
            rsp[1] = 0x00;
        } else {
            rsp[1] = 0xFF;
        }
        rsp_len = 2;
        break;

1 は、MTU が 23 のままなら 1 回の Write で送れるのは 20 バイトまでで、nRF Connect が自動で Long Write(Prepare Write + Execute Write)に切り替えることがあります。どちらにしても、長さチェックにより BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN が返り、nRF Connect にエラーが表示されます。

重要キーポイント
  • Write は BLE_GATT_ACCESS_OP_WRITE_CHR で届く。長さを確認 してから配列にコピー
  • 戻り値の ATT エラーは、Write Request なら Client に伝わる
  • 応答は Notify で返す。応答の先頭にコマンド番号 を入れると受け手が楽
  • 応答を受け取るには、Client がそのキャラクタリスティックの CCCD を購読 している必要がある