ESP32 BLE GATT服务与特性深度解析：UUID、注册流程与数据交互

最新推荐文章于 2026-06-05 16:34:29 发布

原创最新推荐文章于 2026-06-05 16:34:29 发布 · 1k 阅读

23 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#GATT服务 #蓝牙特性 #ESP32 BLE

1. 蓝牙服务与特性的工程本质：从协议栈抽象到嵌入式实现

在嵌入式蓝牙开发中，“服务（Service）”与“特性（Characteristic）”并非抽象概念，而是BLE协议栈中定义明确、具有严格内存布局和运行时行为的实体。它们共同构成GATT（Generic Attribute Profile）层的核心数据模型，是应用层与底层协议栈交互的唯一合法接口。理解其本质，关键在于跳出“类比HTTP API”的思维定式，回归BLE协议栈的分层设计逻辑——服务是逻辑功能模块的容器，特性是该模块内可被访问的数据单元，而访问权限（Read/Write/Notify/Indicate）则由协议栈在连接建立后通过属性协议（ATT）动态协商并强制执行。

GATT层位于BLE协议栈的应用层，其下是ATT层（负责属性读写操作）、L2CAP层（逻辑链路控制与适配协议）以及底层的HCI（Host Controller Interface）。对于ESP32这类集成完整协议栈的SoC，开发者无需触碰HCI以下层级；芯片原厂（Espressif）已将控制器（Controller）固件固化于ROM中，而主机（Host）部分——包括L2CAP、ATT、GATT及上层Profile——则由ESP-IDF中的 bluedroid 组件实现。这意味着，所有服务与特性的注册、发现、读写操作，最终都转化为对 bluedroid 内部状态机和属性数据库的操作。因此，任何关于“直接操作寄存器”或“绕过协议栈”的设想，在标准BLE开发中均不成立。服务与特性的生命周期完全由 bluedroid 管理：注册即写入其全局属性表，注销即从表中移除，而所有客户端访问请求，均由 bluedroid 的ATT服务器线程统一调度、校验权限并触发用户注册的回调函数。

这种架构决定了一个根本事实：服务与特性不是代码中静态定义的变量，而是运行时动态注入协议栈的“可执行对象”。它们的UUID、权限、值句柄（Handle）共同构成一个属性条目（Attribute），被存储在 bluedroid 维护的GATT数据库中。当手机APP（GATT Client）发起服务发现（Service Discovery）请求时， bluedroid 会遍历此数据库，将匹配的服务UUID返回给客户端；当客户端尝试读取某特性值时， bluedroid 根据该特性的句柄查找到对应条目，验证客户端是否拥有Read权限，若通过，则调用开发者注册的 read_cb 回调函数，将当前值填充至响应缓冲区。整个过程对开发者透明，开发者只需关注“注册什么”和“如何响应”，而非“如何传输”。

2. UUID：128位全局唯一标识符的工程实践

UUID（Universally Unique Identifier）是BLE服务与特性的“身份证号”，其128位长度（16字节）的设计初衷是确保在全球范围内绝对不重复。在ESP32的 bluedroid 实现中，每个服务或特性的UUID都以 esp_bt_uuid_t 结构体形式存在，该结构体包含一个 len 字段（标识UUID长度为16、32或128位）和一个 uuid 联合体（用于存储不同长度的UUID值）。 必须强调，UUID的长度选择直接影响协议栈的行为与兼容性，绝非仅关乎书写便利。

2.1 标准UUID与自定义UUID的物理区别

蓝牙技术联盟（Bluetooth SIG）为常用功能预定义了大量16位UUID（如 0x2A37 代表Heart Rate Measurement），这些UUID被硬编码在 bluedroid 的 gatt_api.h 头文件中，并映射到一个固定的128位基地址（Base UUID）： 00000000-0000-1000-8000-00805F9B34FB 。当开发者使用16位UUID（如 0x2A37 ）注册服务时， bluedroid 在内部会自动将其扩展为完整的128位UUID： 00002A37-0000-1000-8000-00805F9B34FB 。这一过程由 esp_bt_uuid_t 结构体的 len 字段驱动——当 len == ESP_BT_UUID_LEN_16 时，协议栈自动拼接基地址。

然而， 16位UUID仅适用于SIG官方已注册的标准服务与特性 。一旦开发者需要实现自定义功能（如“智能灯开关状态”、“温湿度传感器读数”），就必须使用128位UUID。原因在于：手机端GATT客户端（如nRF Connect、古语蓝牙）在解析服务列表时，会优先检查UUID长度。若收到一个16位UUID但不在SIG官方列表中，客户端通常会显示为 Unknown Service 或 Unknown Characteristic ，导致调试困难。更重要的是，某些Android版本的BLE栈对非标准16位UUID的支持存在兼容性问题，可能导致服务发现失败。

因此，在工程实践中， 强烈建议所有自定义服务与特性一律采用128位UUID 。生成方式有两种：
- 在线工具生成 ：使用 uuidgen 命令行工具或在线UUID生成器，确保其符合RFC 4122标准。
- 代码内硬编码 ：在ESP-IDF项目中，将128位UUID声明为 const uint8_t 数组，例如：
c static const uint8_t service_uuid128[ESP_BLE_UUID_LEN_128] = { /* 0x12345678-90AB-CDEF-1234-567890ABCDEF */ 0xEF, 0xCD, 0xAB, 0x90, 0x78, 0x56, 0x34, 0x12, 0xEF, 0xCD, 0xAB, 0x90, 0x78, 0x56, 0x34, 0x12 };
注意字节序：BLE协议规定UUID按小端序（Little-Endian）存储，因此上述数组的排列顺序与人类阅读的字符串格式相反。 bluedroid 的API（如 esp_ble_gatts_create_service ）接收的正是这种小端序字节数组。

2.2 UUID在GATT数据库中的存储与索引

在 bluedroid 的GATT数据库中，UUID是服务与特性条目的核心索引键。当GATT Client发起服务发现请求时，协议栈会遍历数据库中所有服务条目，将其UUID与客户端请求的UUID进行逐字节比对。这一过程发生在 gatt_sr_srvr.c 的 gatts_find_service_by_uuid 函数中。因此，UUID的唯一性不仅关乎逻辑正确性，更直接影响查询性能。在资源受限的嵌入式系统中，避免UUID重复是基本工程素养。

一个常见误区是认为“只要UUID字符串不同即可”。实际上，由于 esp_bt_uuid_t 结构体的 len 字段参与哈希计算， {len=16, uuid=0x2A37} 与 {len=128, uuid=...2A37...} 在数据库中被视为两个完全不同的条目。这解释了为何在古语蓝牙小程序中看到的UUID显示为短格式（16位）或长格式（128位）——客户端根据接收到的 len 字段决定显示策略，而非协议栈做了“简化”。

3. GATT服务与特性的构建流程：从代码到协议栈

在ESP-IDF中，构建一个可被外部设备发现和访问的BLE服务，是一个严格的、分步注册的流程。该流程并非简单的“创建对象并赋值”，而是与 bluedroid 的GATT服务器（GATT Server）状态机深度耦合。任何步骤的遗漏或顺序错误，都将导致服务无法被发现或特性无法被访问。以下以构建一个包含两个特性的自定义服务为例，详解每一步的工程目的与底层机制。

3.1 初始化与配置：开启GATT服务器引擎

一切始于 esp_bluedroid_init() 与 esp_bluedroid_enable() 。前者初始化 bluedroid 的全局上下文（包括GATT数据库的内存池），后者启动GATT Server任务。此步骤不可省略，且必须在任何GATT API调用前完成。 bluedroid 的GATT Server是一个FreeRTOS任务，其优先级在 menuconfig 中默认为 CONFIG_BLUEDROID_TASK_PRIORITY （通常为5），它负责处理所有来自HCI的ATT事件（如读请求、写请求、通知触发）。

esp_err_t ret = nvs_flash_init();
ESP_ERROR_CHECK(ret);
esp_bt_controller_config_t bt_cfg = BT_CONTROLLER_INIT_CONFIG_DEFAULT();
ret = esp_bt_controller_init(&bt_cfg);
ESP_ERROR_CHECK(ret);
ret = esp_bt_controller_enable(ESP_BT_MODE_BLE);
ESP_ERROR_CHECK(ret);
ret = esp_bluedroid_init();
ESP_ERROR_CHECK(ret);
ret = esp_bluedroid_enable();
ESP_ERROR_CHECK(ret);

这段初始化代码的本质，是为GATT Server任务分配堆栈空间、创建消息队列，并注册HCI事件回调。若跳过此步直接调用 esp_ble_gatts_create_service ，将返回 ESP_ERR_INVALID_STATE 错误。

3.2 定义UUID：为服务与特性赋予唯一身份

如前所述，UUID必须精确指定长度。对于自定义服务，我们定义一个128位UUID；对于其下的特性，同样采用128位UUID以保证一致性：

// 服务UUID: 12345678-90AB-CDEF-1234-567890ABCDEF
static const uint8_t service_uuid[ESP_BLE_UUID_LEN_128] = {
    0xEF, 0xCD, 0xAB, 0x90, 0x78, 0x56, 0x34, 0x12,
    0xEF, 0xCD, 0xAB, 0x90, 0x78, 0x56, 0x34, 0x12
};

// 特性A UUID: FEDCBA98-7654-3210-FEDC-BA9876543210
static const uint8_t chara_uuid[ESP_BLE_UUID_LEN_128] = {
    0x10, 0x32, 0x54, 0x76, 0x98, 0xBA, 0xDC, 0xFE,
    0x10, 0x32, 0x54, 0x76, 0x98, 0xBA, 0xDC, 0xFE
};

// 特性B UUID: 01234567-89AB-CDEF-0123-456789ABCDEF
static const uint8_t charb_uuid[ESP_BLE_UUID_LEN_128] = {
    0xEF, 0xCD, 0xAB, 0x89, 0x67, 0x45, 0x23, 0x01,
    0xEF, 0xCD, 0xAB, 0x89, 0x67, 0x45, 0x23, 0x01
};

3.3 创建服务：在GATT数据库中开辟逻辑空间

调用 esp_ble_gatts_create_service 是构建服务的第一步。此API的参数 service_id 是一个 esp_gatt_id_t 结构体，它不仅包含UUID，还包含一个 inst_id （实例ID）。 inst_id 的作用是允许同一UUID的服务存在多个实例。例如，一个设备可能同时提供两个独立的“电池服务”（Battery Service），分别监控主电池和备用电池，此时两个服务的UUID相同（ 0x180F ），但 inst_id 不同（如0和1）。 bluedroid 会为每个实例分配独立的句柄范围。

esp_gatt_id_t service_id = {
    .uuid = {
        .len = ESP_BLE_UUID_LEN_128,
        .uuid.uuid128 = (uint8_t*)service_uuid
    },
    .inst_id = 0x00 // 实例ID，通常为0
};
esp_ble_gatts_create_service(&service_id, 4); // 4: 预估该服务下属性总数

esp_ble_gatts_create_service 的第二个参数 num_handle 至关重要。它并非“精确数量”，而是 bluedroid 为该服务预分配的属性句柄（Handle）槽位数。每个服务、特性、描述符（Descriptor）都占用一个句柄。句柄是GATT协议中定位属性的16位整数索引，从服务起始句柄开始递增。若预估过小（如设为2，但实际有3个特性），后续 esp_ble_gatts_add_char 将失败；若过大，则浪费宝贵的句柄空间（ESP32的GATT句柄池默认有限）。经验法则是： num_handle = 1（服务本身）+ N（特性数）+ Σ（每个特性的描述符数） 。本例中，两个特性均无额外描述符，故设为4（1+2+1，其中+1为服务结束句柄）。

此调用成功后， bluedroid 在GATT数据库中创建一个新服务条目，并返回一个 service_handle 。该句柄是后续向此服务添加特性的唯一凭证。

3.4 添加特性：注入可访问的数据单元

特性是服务的子元素，通过 esp_ble_gatts_add_char 添加。此API要求指定特性UUID、值的属性（Properties）以及权限（Permissions）。 Properties与Permissions是两个常被混淆的概念，其工程含义截然不同：

Properties（属性） ：定义该特性支持哪些GATT操作，是客户端可见的“能力声明”。例如， ESP_GATT_CHAR_PROP_BIT_READ | ESP_GATT_CHAR_PROP_BIT_NOTIFY 表示客户端可以读取其值，并能订阅通知（Notification）。 bluedroid 在服务发现阶段将此信息通过 0x2803 （Characteristic Declaration）属性返回给客户端。
Permissions（权限） ：定义协议栈在运行时对访问请求的校验规则，是服务端的“安全策略”。例如， ESP_GATT_PERM_READ 表示只有拥有Read权限的客户端才能发起读请求； ESP_GATT_PERM_WRITE 同理。权限校验发生在ATT层，由 gatt_sr_srvr.c 中的 gatts_check_perm 函数执行。

esp_ble_gatts_add_char(service_handle, &chara_uuid, ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE,
                        ESP_GATT_CHAR_PROP_BIT_READ | ESP_GATT_CHAR_PROP_BIT_NOTIFY,
                        NULL, NULL);

此处， chara_uuid 是前面定义的128位UUID； ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE 是权限，允许读写； ESP_GATT_CHAR_PROP_BIT_READ | ESP_GATT_CHAR_PROP_BIT_NOTIFY 是属性，告知客户端“可读、可通知”。 NULL, NULL 分别指向初始值和描述符。若需设置初始值，可传入一个 esp_attr_value_t 结构体指针。

调用成功后， bluedroid 为该特性分配一个句柄（ char_handle ），并在数据库中创建两个条目：一个是 0x2803 （特性声明），另一个是 0x2800 （特性值本身）。客户端读取服务时，首先看到声明条目，从中获知特性的UUID和Properties；然后，客户端可使用该特性的值句柄去读取或写入实际数据。

3.5 启动服务：将逻辑模型激活为运行实体

所有服务与特性注册完毕后，必须调用 esp_ble_gatts_start_service 来“激活”该服务。此步骤将服务的状态从 ESP_GATT_SERVICE_INDEX_INVALID 置为 ESP_GATT_SERVICE_INDEX_ACTIVE ，并为其分配连续的句柄范围。 这是服务对外可见的关键一步。 若未调用此函数，即使注册成功，GATT Client在服务发现时也看不到该服务。

esp_ble_gatts_start_service(service_handle);

至此，一个完整的GATT服务已在 bluedroid 中就绪。手机APP连接后，通过标准的GATT服务发现流程，即可枚举出该服务及其下的所有特性。

4. 特性值的读写与通知：数据流的双向通道

服务与特性注册成功，仅完成了“广告牌”的搭建。真正的价值在于数据交换——客户端读取设备状态、写入控制指令、或接收设备主动推送的通知。在ESP-IDF中，这一切都通过注册回调函数（Callback）实现，体现了事件驱动的编程范式。

4.1 注册GATT事件回调：建立事件分发中枢

bluedroid 通过一个统一的GATT事件回调函数 gatts_event_handler 来分发所有GATT相关事件。开发者必须在此函数中，根据 esp_gatts_cb_event_t 事件类型，路由到具体的业务逻辑。最关键的事件是 ESP_GATTS_READ_EVT （读请求）、 ESP_GATTS_WRITE_EVT （写请求）和 ESP_GATTS_EXEC_WRITE_EVT （执行写，用于长写操作）。

static void gatts_event_handler(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t* param) {
    switch (event) {
        case ESP_GATTS_REG_EVT:
            // 服务注册完成事件，可在此处创建服务
            break;
        case ESP_GATTS_READ_EVT:
            // 处理读请求
            break;
        case ESP_GATTS_WRITE_EVT:
            // 处理写请求
            break;
        default:
            break;
    }
}

此回调函数在 app_main 中通过 esp_ble_gatts_register_callback(gatts_event_handler) 注册。它是整个GATT交互的入口点，所有客户端的访问请求，最终都汇聚于此。

4.2 响应读请求：按需生成数据

当GATT Client发起读请求时， bluedroid 触发 ESP_GATTS_READ_EVT 事件，并在 param->read 结构体中提供 handle （被读取的特性句柄）和 conn_id （连接ID）。开发者需根据 handle 判断是哪个特性被读取，然后将数据填充至 param->read.value 缓冲区，并设置 param->read.value_len 。

case ESP_GATTS_READ_EVT: {
    if (param->read.handle == chara_handle) {
        // 读取特性A：返回当前LED状态
        uint8_t led_state = gpio_get_level(GPIO_NUM_2);
        param->read.value[0] = led_state;
        param->read.value_len = 1;
    } else if (param->read.handle == charb_handle) {
        // 读取特性B：返回ADC采样值
        uint32_t adc_val = adc1_get_raw(ADC1_CHANNEL_0);
        param->read.value[0] = adc_val & 0xFF;
        param->read.value[1] = (adc_val >> 8) & 0xFF;
        param->read.value_len = 2;
    }
    break;
}

关键点在于： bluedroid 不会缓存特性值。 每次读请求都触发一次回调，开发者必须在回调中实时计算或读取最新数据。这保证了数据的时效性，但也意味着回调函数必须高效，避免阻塞GATT Server任务。

4.3 处理写请求：接收并解析控制指令

写请求的处理逻辑类似，但方向相反。 ESP_GATTS_WRITE_EVT 事件的 param->write 结构体提供了 handle 、 value （指向写入数据的指针）、 len （数据长度）和 is_prep （是否为准备写，即长写的一部分）。

case ESP_GATTS_WRITE_EVT: {
    if (param->write.handle == charb_handle && param->write.len == 1) {
        // 写入特性B：控制LED开关
        uint8_t cmd = param->write.value[0];
        if (cmd == 0x01) {
            gpio_set_level(GPIO_NUM_2, 1);
        } else if (cmd == 0x00) {
            gpio_set_level(GPIO_NUM_2, 0);
        }
    }
    break;
}

4.4 主动发送通知：打破请求-响应模式

通知（Notification）是BLE中实现“服务器推送”的核心机制。它允许设备在无客户端请求的情况下，主动向已订阅的客户端发送数据更新。启用通知需两步：客户端订阅（通过写入 0x2902 客户端特征配置描述符CCC），设备端发送（调用 esp_ble_gatts_send_indicate 或 esp_ble_gatts_send_notify ）。

首先，客户端订阅会触发 ESP_GATTS_WRITE_EVT 事件，目标句柄为 0x2902 。开发者需在回调中解析写入值（ 0x0001 表示启用通知， 0x0000 表示禁用），并记录该连接的订阅状态。

case ESP_GATTS_WRITE_EVT: {
    if (param->write.handle == ccc_handle) { // ccc_handle 是0x2902描述符的句柄
        if (param->write.len == 2 && param->write.value[0] == 0x01 && param->write.value[1] == 0x00) {
            notify_enabled = true; // 记录订阅状态
        } else if (param->write.len == 2 && param->write.value[0] == 0x00 && param->write.value[1] == 0x00) {
            notify_enabled = false;
        }
    }
    break;
}

当需要推送数据时，调用 esp_ble_gatts_send_notify ：

if (notify_enabled) {
    uint8_t data[1] = {sensor_value};
    esp_ble_gatts_send_notify(gatts_if, conn_id, chara_handle, sizeof(data), data);
}

此函数将数据封装成ATT Notification PDU，并通过HCI发送给客户端。 通知是单向、无确认的。 若需确保送达，应使用Indication（指示），它要求客户端发送ACK，但会增加通信开销。

5. 调试与验证：从理论到现实的闭环

构建服务与特性后，必须通过真实设备进行验证。古语蓝牙微信小程序是优秀的调试工具，但其UI设计隐藏了协议细节，容易产生误解。一个严谨的工程师，应掌握以下调试方法：

5.1 使用nRF Connect进行底层验证

nRF Connect（Android/iOS）提供了比小程序更透明的GATT浏览器。连接设备后，它会完整列出所有服务、特性及其属性（Properties）和权限（Permissions）。重点观察：
- 服务UUID是否显示为完整的128位格式（验证是否正确注册）。
- 特性下方是否显示 Read , Notify , Write 等图标（验证Properties是否正确设置）。
- 点击特性后，右侧面板是否显示 Permission: Readable, Writable （验证Permissions）。
- 尝试手动读取/写入，观察设备是否正确响应（验证回调逻辑）。

5.2 分析HCI日志：窥探协议栈内部

当现象与预期不符时，最有力的证据是HCI日志。在ESP-IDF中，可通过 idf.py monitor 启动串口监视器，并在 menuconfig 中启用 Component config -> Bluetooth -> Bluedroid Options -> Enable Bluetooth controller debug log 。日志中会清晰打印出：
- GATT Server: add service （服务添加成功）
- GATT Server: start service （服务启动）
- GATT Server: read request from ... handle=0x0012 （读请求到达）
- GATT Server: write request to handle=0x0013 value=01 （写请求内容）

通过日志，可以精准定位问题是出在服务注册失败、回调未注册、还是权限配置错误。

5.3 作业解析：构建多服务复合设备

课程作业要求构建一个包含三个服务的设备：一个自定义服务（UUID 0x9011 ）含两个特性，一个标准电池服务（ 0x180F ），一个标准设备信息服务（ 0x180A ）。这在工程上意味着：
- 调用三次 esp_ble_gatts_create_service ，分别创建三个服务。
- 为电池服务和设备信息服务，必须使用 ESP_BLE_UUID_LEN_16 和对应的SIG标准UUID（ 0x180F , 0x180A ），因为 bluedroid 内置了这些标准服务的描述符（如电池电量Characteristic 0x2A19 ）。
- 所有服务的 inst_id 必须唯一，避免句柄冲突。
- 启动服务时，必须按注册顺序依次调用 esp_ble_gatts_start_service 。

这个作业的深层意义在于，它模拟了真实BLE设备的复杂性——现代智能设备（如智能手表）往往同时提供心率、步数、通知提醒、固件升级等多个服务。掌握多服务管理，是迈向专业BLE开发的必经之路。

我在实际项目中曾遇到一个典型问题：在添加第二个服务时， esp_ble_gatts_create_service 返回 ESP_ERR_INVALID_ARG 。排查日志发现， num_handle 参数被误设为一个极小的值（2），而该服务下特性加描述符总数远超此数。 bluedroid 的句柄分配器检测到溢出，直接拒绝了请求。将 num_handle 修正为合理值（10）后，问题解决。这个坑提醒我， num_handle 不是可有可无的参数，而是 bluedroid 内存管理的关键约束。