1. 简介

        低功耗蓝牙中最为核心的部分当属 GATT（Generic Attribute Profile），全称通用属性配置文件。而 GATT 又是建立在 ATT 协议（属性协议）的基础之上，为 ATT 协议传输和存储的数据建立了通用操作和框架。GATT 和 ATT 并不针对特定的传输协议，可在经典蓝牙和低功耗蓝牙中使用。不过，它们是必须在低功耗蓝牙中实施的，因为低功耗蓝牙用于发现服务。

        GATT 定义了两种角色： 服务器（Server）和客户端（Client）。GATT 服务器存储通过ATT 协议传输的数据，并接受来自 GATT 客户端的 ATT 协议请求、命令和确认。GATT 服务器发送对请求的响应，并在 GATT 服务器发生指定事件时，根据配置向 GATT 客户端异步发送指示和通知。

1.1 ATT协议

        低功耗蓝牙里面的数据以属性 (Attribute) 的方式存在，每条属性由四个元素组成——属性句柄（Attribute Handle）、属性类型（Attribute UUID）、属性值（Attribute Value）和属性许可（Attribute Permissions）。

• 属性句柄：可以通俗理解为属性的序号，例如第⼀个属性的句柄是0x0001，第二个属性的句柄是 0x0002，以此类推，最大可以到 0xFFFF；
• 属性类型：每个数据有自己需要代表的意思，例如温度、发射功率、电池等等。这个类型是以UUID的形式来表示的，有16bit和128bit两种长度，蓝牙组织（Bluetooth SIG）负责对常用的一些数据类型进行归类；
• 属性值：这个部分就是数据本身，长度可以是固定的，也可以是可变的；
• 属性许可：每个属性对各自的属性值有相应的访问限制，比如有些属性是可读的、有些是可写的、有些是可读又可写的等等。拥有数据的一方可以通过属性许可，控制本地数据的可读写属性。

1.2 GATT规范

        ATT 属性协议规定了在低功耗蓝牙中的最小数据存储单位，而 GATT 规范则定义了如何用特性值和描述符表示一个数据，如何把相似的数据聚合成服务（Service），以及如何发现对端设备拥有哪些服务和数据。

        GATT 规范引进了特性（Charateristic）的概念。这是由于在某些时候，一个数据可能并不只是单纯的数值，还会带有一些额外的信息。比如，这个数据的单位、这个数值的名称等等。

        一个特性包含特性声明（Characteristic Declaration）、特性数值（Characteristic Value）和描述符（Descriptor）。

• 特性声明：用于告诉对方此声明后面跟的内容为特性数值。
• 特征数值：用于承载特性的真正内容。
• 描述符：对特性进行进⼀步的描述，每个特性可以有多个描述符，也可以没有描述符。

2. 例程

        这个例程会建立一个标准的 GATT 和 ATT 通信环境，然后注册一个电池电量服务。使能ESP32作为服务器，启动后不断广播让周围的设备连接自己；然后我们使用手机上的测试APP连接ESP32，并读取电池电量服务中的数据。

2.1 menuconfig

        ESP32是默认不使能蓝牙功能的，因此要配置menuconfig来使能。首先，使能蓝牙控制器为仅低功耗蓝牙。

        然后，使能协议栈为NimBLE。

        保存配置后建议清除原有的CMake缓存，重新配置，不然静态语言检查可能会不生效。 

2.2 代码

#include <stdint.h>
#include <string.h>
#include <inttypes.h>
#include <stdbool.h>

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"

#include "nvs.h"
#include "nvs_flash.h"
#include "esp_system.h"
#include "esp_log.h"

#include "host/ble_gap.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"
#include "services/bas/ble_svc_bas.h"
#include "nimble/nimble_port.h"
#include "nimble/nimble_port_freertos.h"

#define TAG "app"
#define OWN_NAME "ESP32"

#define BDASTR "%02X:%02X:%02X:%02X:%02X:%02X"
#define BDA2STR(x) (x)[0], (x)[1], (x)[2], (x)[3], (x)[4], (x)[5]

static uint8_t ble_addr_type;
static TaskHandle_t bas_task_handle;
static uint8_t device_name[] = OWN_NAME;

static void ble_advertise(void);
static int ble_gap_event(struct ble_gap_event *event, void *arg);
static void ble_on_reset(int reason);
static void ble_on_sync(void);
static void ble_host_task(void *param);
static void bas_task(void* args);


static void ble_advertise(void)
{    
    int rc;

    struct ble_hs_adv_fields fields;
    memset(&fields, 0, sizeof(fields));
    /* 标志位 */
    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 = device_name;
    fields.name_len = strlen(OWN_NAME);
    fields.name_is_complete = 1;
    /* UUID */
    fields.uuids16 = (ble_uuid16_t[]) {
        BLE_UUID16_INIT(BLE_SVC_BAS_UUID16)
    };
    fields.num_uuids16 = 1;
    fields.uuids16_is_complete = 1;

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

    /* 开始广播 */
    struct ble_gap_adv_params adv_params;
    memset(&adv_params, 0, sizeof(adv_params));

    adv_params.conn_mode = BLE_GAP_CONN_MODE_UND;
    adv_params.disc_mode = BLE_GAP_DISC_MODE_GEN;
    rc = ble_gap_adv_start(ble_addr_type, NULL, BLE_HS_FOREVER, &adv_params, ble_gap_event, NULL);
    if (rc != 0) {
        ESP_LOGE(TAG, "error enabling advertisement, rc=%d", rc);
        return;
    }
}

static int ble_gap_event(struct ble_gap_event *event, void *arg)
{
    int rc = 0;

    switch (event->type) {
        /* 连接建立事件 */
        case BLE_GAP_EVENT_LINK_ESTAB:
            ESP_LOGI(TAG, "connection %s, status=%d",
                     event->connect.status == 0 ? "established" : "failed",
                     event->connect.status);

            if (event->connect.status != 0) {
                ble_advertise();
            } else {
                xTaskCreate(bas_task, "bas_task", 2048, NULL, 5, &bas_task_handle);
            }
            break;

        /* 连接断开事件 */
        case BLE_GAP_EVENT_DISCONNECT:
            ESP_LOGI(TAG, "disconnect, reason=%d", event->disconnect.reason);
            if (bas_task_handle != NULL) {
                vTaskDelete(bas_task_handle);
            }
            ble_advertise();
            break;

        /* 广播完成事件 */
        case BLE_GAP_EVENT_ADV_COMPLETE:
            ESP_LOGI(TAG, "advertise complete");
            ble_advertise();
            break;

        /* 订阅事件 */
        case BLE_GAP_EVENT_SUBSCRIBE:
            ESP_LOGI(TAG, "subscribe event, cur_notify=%d, val_handle=%d",
                     event->subscribe.cur_notify,
                     event->subscribe.attr_handle);
            break;

        /* MTU更新事件 */
        case BLE_GAP_EVENT_MTU:
            ESP_LOGI(TAG, "mtu updated, conn_handle=%d mtu=%d",
                     event->mtu.conn_handle,
                     event->mtu.value);
            break;

        default:
            break;
    }

    return rc;
}

static void ble_on_reset(int reason)
{
    ESP_LOGE(TAG, "Resetting state; reason=%d", reason);
}

static void ble_on_sync(void)
{
    int ret;

    /* 获取最佳地址类型 */
    ret = ble_hs_id_infer_auto(0, &ble_addr_type);
    if (ret) {
        ESP_LOGE(TAG, "ble_hs_id_infer_auto failed, err: %d", ret);
        return;
    }

    /* 获取地址 */
    uint8_t addr_val[6] = {0};
    ret = ble_hs_id_copy_addr(ble_addr_type, addr_val, NULL);
    if (ret) {
        ESP_LOGE(TAG, "ble_hs_id_copy_addr failed, err: %d", ret);
        return;
    }
    ESP_LOGI(TAG, "Device address: " BDASTR, BDA2STR(addr_val));

    /* 使能广播 */
    ble_advertise();
}

static void ble_host_task(void *param)
{
    nimble_port_run();
    nimble_port_freertos_deinit();
}

static void bas_task(void* args)
{
    while (1) {
        for (uint8_t i = 0; i <= 10; i++) {
            ble_svc_bas_battery_level_set(i * 10);
            ESP_LOGI(TAG, "set battery level to %d", i * 10);
            vTaskDelay(2000 / portTICK_PERIOD_MS);
        }
    }
}

int app_main()
{
    /* 初始化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());
        ESP_ERROR_CHECK(nvs_flash_init());
    }

    /* 初始化控制器和NimBLE协议栈 */
    ret = nimble_port_init();
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to init nimble %d ", ret);
        return -1;
    }

    /* 使能电池电量服务 */
    ble_svc_bas_init();

    /* 配置主机 */
    ble_hs_cfg.reset_cb = ble_on_reset;
    ble_hs_cfg.sync_cb = ble_on_sync;
    ble_hs_cfg.store_status_cb = ble_store_util_status_rr;

    /* 使能绑定 */
    ble_hs_cfg.sm_bonding = 1;
    ble_hs_cfg.sm_our_key_dist |= BLE_SM_PAIR_KEY_DIST_ENC | BLE_SM_PAIR_KEY_DIST_ID;
    ble_hs_cfg.sm_their_key_dist |= BLE_SM_PAIR_KEY_DIST_ENC | BLE_SM_PAIR_KEY_DIST_ID;
    ble_hs_cfg.sm_sc = 1;
    ble_hs_cfg.sm_mitm = 1;

    /* 设置设备名 */
    if (ble_svc_gap_device_name_set(OWN_NAME) != 0) {
        ESP_LOGE(TAG, "set device name failed");
        return -1;
    }

    /* 使能NimBLE协议栈 */
    nimble_port_freertos_init(ble_host_task);

    return 0;
}

在上一篇文章中已经介绍了低功耗蓝牙 GAP 协议相关的代码编写，所以下面就不再赘述。

        在初始化蓝牙控制器和NimBLE协议栈后，调用 ble_svc_bas_init 函数即可初始化电池电量服务，NimBLE协议栈封装了大部分常用的服务接口，基本上可以即用。

        接着配置相关的回调函数，一个是 reset_cb ，这个是在设备复位时会调用，这里就是简单打印一个log；另一个是 sync_cb ，这个是协议栈刚启动和复位时会调用的，这里面首先会调用 ble_hs_id_infer_auto 函数去获取当前设备的最佳地址类型，然后调用 ble_advertise 去使能广播。

        使能广播前需要配置一个结构体，定义如下：

struct ble_hs_adv_fields {
    /*** 0x01 - Flags. */
    uint8_t flags;

    /*** 0x02,0x03 - 16-bit service class UUIDs. */
    const ble_uuid16_t *uuids16;
    uint8_t num_uuids16;
    unsigned uuids16_is_complete:1;

    /*** 0x04,0x05 - 32-bit service class UUIDs. */
    const ble_uuid32_t *uuids32;
    uint8_t num_uuids32;
    unsigned uuids32_is_complete:1;

    /*** 0x06,0x07 - 128-bit service class UUIDs. */
    const ble_uuid128_t *uuids128;
    uint8_t num_uuids128;
    unsigned uuids128_is_complete:1;

    /*** 0x08,0x09 - Local name. */
    const uint8_t *name;
    uint8_t name_len;
    unsigned name_is_complete:1;

    /*** 0x0a - Tx power level. */
    int8_t tx_pwr_lvl;
    unsigned tx_pwr_lvl_is_present:1;

    /*** 0x0d - Slave connection interval range. */
    const uint8_t *slave_itvl_range;

    /*** 0x10 - Security Manager TK value */
    const uint8_t *sm_tk_value;
    unsigned sm_tk_value_is_present:1;

    /*** 0x11 - Security Manager OOB flag */
    uint8_t sm_oob_flag;
    unsigned sm_oob_flag_is_present:1;

    /*** 0x14 - 16-bit service soliciation list. */
    const ble_uuid16_t *sol_uuids16;
    uint8_t sol_num_uuids16;

    /*** 0x15 - 128-bit service solicitation UUIDs. */
    const ble_uuid128_t *sol_uuids128;
    uint8_t sol_num_uuids128;

    /*** 0x16 - Service data - 16-bit UUID. */
    const uint8_t *svc_data_uuid16;
    uint8_t svc_data_uuid16_len;

    /*** 0x17 - Public target address. */
    const uint8_t *public_tgt_addr;
    uint8_t num_public_tgt_addrs;

    /*** 0x18 - Random target address. */
    const uint8_t *random_tgt_addr;
    uint8_t num_random_tgt_addrs;

    /*** 0x19 - Appearance. */
    uint16_t appearance;
    unsigned appearance_is_present:1;

    /*** 0x1a - Advertising interval. */
    uint16_t adv_itvl;
    unsigned adv_itvl_is_present:1;

    /*** 0x1b - LE Bluetooth device address */
    const uint8_t *device_addr;
    unsigned device_addr_type;
    unsigned device_addr_is_present:1;

    /*** 0xF1 - 32-bit service solicitation UUIDs */
    const ble_uuid32_t *sol_uuids32;
    uint8_t sol_num_uuids32;

    /*** 0x1c - LE Role */
    uint8_t le_role;
    unsigned le_role_is_present:1;

    /*** 0x20 - Service data - 32-bit UUID. */
    const uint8_t *svc_data_uuid32;
    uint8_t svc_data_uuid32_len;

    /*** 0x21 - Service data - 128-bit UUID. */
    const uint8_t *svc_data_uuid128;
    uint8_t svc_data_uuid128_len;

    /*** 0x24 - URI. */
    const uint8_t *uri;
    uint8_t uri_len;

    /*** 0xff - Manufacturer specific data. */
    const uint8_t *mfg_data;
    uint8_t mfg_data_len;
};

        这个结构体非常长，这个例程里面我们只需关注标志位（Flags）、UUID、本地名称（Local Name）和发射功率这几个部分。

        标志位目前支持以下几个：

#define BLE_HS_ADV_F_DISC_LTD                   0x01  // 限制性发现模式
#define BLE_HS_ADV_F_DISC_GEN                   0x02  // 普通发现模式
#define BLE_HS_ADV_F_BREDR_UNSUP                0x04  // 禁用经典蓝牙

        UUID是跟使能的服务类型有关的，例程里面的电池电量服务使用的是16bit的UUID，UUID号可以在对应的头文件中找到。

        本地名称就是广播时附带的设备名，设置字符串数组和其长度即可。

        发射功率一般来说填BLE_HS_ADV_TX_PWR_LVL_AUTO，来让协议栈决定。

        配置完结构体后调用 ble_gap_adv_set_fields 写入配置。调用 ble_gap_adv_start 来使能广播；参数一为地址类型；参数二为直接地址，用于定向广播时使用；参数三为广播时长，填BLE_HS_FOREVER表示无限时间；参数四为配置参数，结构体定义如下：

struct ble_gap_adv_params {
    /** Advertising mode. Can be one of following constants:
     *  - BLE_GAP_CONN_MODE_NON (non-connectable; 3.C.9.3.2).
     *  - BLE_GAP_CONN_MODE_DIR (directed-connectable; 3.C.9.3.3).
     *  - BLE_GAP_CONN_MODE_UND (undirected-connectable; 3.C.9.3.4).
     */
    uint8_t conn_mode;
    /** Discoverable mode. Can be one of following constants:
     *  - BLE_GAP_DISC_MODE_NON  (non-discoverable; 3.C.9.2.2).
     *  - BLE_GAP_DISC_MODE_LTD (limited-discoverable; 3.C.9.2.3).
     *  - BLE_GAP_DISC_MODE_GEN (general-discoverable; 3.C.9.2.4).
     */
    uint8_t disc_mode;

    /** Minimum advertising interval, if 0 stack use sane defaults */
    uint16_t itvl_min;
    /** Maximum advertising interval, if 0 stack use sane defaults */
    uint16_t itvl_max;
    /** Advertising channel map , if 0 stack use sane defaults */
    uint8_t channel_map;

    /** Advertising  Filter policy */
    uint8_t filter_policy;

    /** If do High Duty cycle for Directed Advertising */
    uint8_t high_duty_cycle:1;
};

• conn_mode：连接模式，BLE_GAP_CONN_MODE_NON（不可连接）、BLE_GAP_CONN_MODE_DIR（直接连接）、BLE_GAP_CONN_MODE_UND（非直接连接）；
• disc_mode：发现模式，BLE_GAP_DISC_MODE_NON（不可发现）、BLE_GAP_DISC_MODE_LTD（限制性发现）、BLE_GAP_DISC_MODE_GEN（普通发现）；
• itvl_min：最小广播间隔，0为协议栈决定；
• itvl_max：最大广播间隔，0为协议栈决定；
• channel_map：通道遮罩，一共有3个通道，填BLE_GAP_ADV_DFLT_CHANNEL_MAP为全开；0为协议栈决定；
• filter_policy：过滤策略；
• high_duty_cycle：高占空比（仅直接广播）。

         参数五为回调函数，参数六为回调函数的用户参数。

        上面的回调函数是重点，主要处理以下几个GAP事件：

1. 广播完成事件（BLE_GAP_EVENT_ADV_COMPLETE）

        当广播程序执行完后触发，理论上我们这里是不会触发的，因为代码里面设置了永不超时的广播。

2. 连接建立事件（BLE_GAP_EVENT_LINK_ESTAB）

        当有子节点与广播者建立连接时触发，这里会创建一个电池电量的任务，任务主函数里面就是定时地调用 ble_svc_bas_battery_level_set 来设置电池电量百分比。

3. 连接断开事件（BLE_GAP_EVENT_DISCONNECT）

        当有子节点断开连接时触发，这里会删除电池电量任务，并重新使能广播。

4. 订阅事件（BLE_GAP_EVENT_SUBSCRIBE）

        当有子节点的订阅状态改变时触发，这里只是打印log。

5. MTU更新事件（BLE_GAP_EVENT_MTU）

        当L2CAP协议的某通道MTU长度改变时触发，这里只是打印log。

        回到 main 函数，下面继续设置一些安全配对相关的配置。sm_bonding，使能设备绑定功能；sm_our_key_dist，本地键值对遮罩；sm_their_key_dist，远程键值对遮罩；sm_mitm，使能MITM保护协议；sm_sc，使能安全连接。

        调用 ble_svc_gap_device_name_set 设置本机的设备名。最后调用 nimble_port_freertos_init 使能NimBLE协议栈。

2.3 运行

        下面是部分的运行log。

        打开手机的调试上位机，找到我们的ESP32。

         连接设备后，可以在“服务”这一栏看到电池电量服务的相关信息。

         点击该服务卡片，接收服务的数据，可以看到下面的就会显示ESP32发送过来的服务数据了。