3.6 实现GATT/ATT模型中的通知(Notification)与指示(Indication)机制
在BLE协议栈中,通知(Notification)与指示(Indication)是服务端向客户端主动推送数据的核心机制,也是实现低功耗、事件驱动通信的关键。它们并非由协议栈自动触发的“魔法功能”,而是开发者必须显式实现的、基于属性表(Attribute Table)状态变化的主动行为。本节将从工程实践出发,完整剖析ESP32平台下基于ESP-IDF框架实现LED状态变更通知的全过程——包括服务端标志位管理、属性写入响应、通知触发时机、客户端注册流程、配置描述符(Client Characteristic Configuration Descriptor, CCCD)操作,以及通知与指示的本质区别与代码实现细节。
3.6.1 GATT/ATT模型中通知机制的本质:状态驱动而非事件自动分发
许多初学者误以为:只要客户端在GATT客户端上对某个特征值(Characteristic)调用
setNotify(true)
,服务端后续对该特征值的任何写入操作就会自动触发通知发送。这是一种根本性误解。BLE规范(Bluetooth Core Specification v5.4, Vol 3, Part F)明确指出:
通知与指示是服务端主动发起的行为,其触发条件完全由服务端应用逻辑定义,协议栈仅提供底层传输通道和配置描述符存储空间
。
这一设计源于BLE的资源约束本质。自动监听所有特征值变更并广播通知会极大增加服务端CPU负载与功耗,违背低功耗设计原则。因此,规范将“何时通知”、“通知什么”的决策权完全交予应用层。服务端必须:
- 维护一个本地标志位(Flag) :用于记录客户端是否已启用对该特征值的通知;
- 在特征值被修改后主动检查该标志位 :若已启用,则调用协议栈API显式发送通知;
- 在收到客户端对CCCD的写入请求后更新该标志位 :这是通知开关的唯一合法途径。
这种“状态-动作”分离的设计,要求开发者清晰区分两个独立事件流:
-
配置流(Configuration Flow)
:客户端写入CCCD → 服务端解析并更新本地通知标志位;
-
数据流(Data Flow)
:服务端应用逻辑修改特征值 → 检查本地标志位 → 决定是否调用
esp_ble_gatts_send_indicate()
或
esp_ble_gatts_send_notify()
。
理解这一点,是避免调试时陷入“为什么注册了却不收通知”陷阱的第一步。它不是协议栈的Bug,而是规范强制要求的、可预测的、节能的编程范式。
3.6.2 服务端核心实现:标志位、写入回调与通知触发三要素
在ESP32的GATT服务端实现中,通知功能的落地依赖于三个紧密耦合的组件:全局通知标志位、特征值写入回调函数(Write Callback)、以及通知触发任务。以下以LED状态特征值为例,展开详细分析。
全局通知标志位的声明与语义
服务端需定义一个全局变量,用于持久化存储客户端对LED特征值的通知使能状态。该变量通常声明为
uint8_t
类型,其取值具有严格语义:
// 服务端全局变量,定义在gatts_profile.h或对应.c文件顶部
static uint8_t led_notify_enabled = 0; // 0: 未启用通知;1: 启用通知(Notification);2: 启用指示(Indication)
此变量的生命周期贯穿整个GATT服务运行期,其值仅通过CCCD写入操作更新,绝不允许在其他任何地方被直接赋值。它的存在,是服务端判断“是否需要主动推送”的唯一依据。
特征值写入回调:解析CCCD并更新标志位
当客户端执行
setNotify(true)
时,GATT协议栈底层会将一个写入请求路由至服务端注册的
gatts_write_evt_cb
回调函数。该回调的核心任务是:
识别写入目标是否为CCCD,并据此更新
led_notify_enabled
标志位
。
在ESP-IDF中,CCCD的标准UUID为
0x2902
。服务端需在回调中比对写入请求的目标句柄(handle)与预定义的CCCD句柄(通常为特征值句柄+1),并检查写入的数据长度与内容:
// 在gatts_profile.c的write_event_handler函数中
case ESP_GATTS_WRITE_EVT: {
esp_gatt_status_t status = ESP_GATT_OK;
// 获取写入请求的句柄
uint16_t handle = param->write.handle;
// 判断是否为LED特征值的CCCD(假设CCCD句柄为LED_CHAR_VAL_HANDLE + 1)
if (handle == led_cccd_handle) {
// CCCD写入数据必须为2字节
if (param->write.len == 2) {
// 解析CCCD值:0x0001 = 启用通知;0x0002 = 启用指示;0x0000 = 禁用
uint16_t cccd_value = *(uint16_t*)param->write.value;
if (cccd_value == 0x0001) {
led_notify_enabled = 1; // 启用通知
ESP_LOGI(GATTS_TAG, "LED Notify Enabled");
} else if (cccd_value == 0x0002) {
led_notify_enabled = 2; // 启用指示
ESP_LOGI(GATTS_TAG, "LED Indicate Enabled");
} else if (cccd_value == 0x0000) {
led_notify_enabled = 0; // 禁用
ESP_LOGI(GATTS_TAG, "LED Notify/Indicate Disabled");
} else {
status = ESP_GATT_INVALID_VALUE_SIZE;
}
} else {
status = ESP_GATT_INVALID_VALUE_SIZE;
}
}
// ... 其他特征值写入处理(如LED状态本身)...
esp_ble_gatts_send_response(gatts_if, param->write.conn_id, param->write.trans_id, status, NULL);
break;
}
此段代码的关键在于:
-
精确的目标识别
:通过
handle == led_cccd_handle
确保只响应针对LED特征值CCCD的写入,避免误判。
-
严格的格式校验
:
param->write.len == 2
保证了写入的是标准的2字节CCCD值,防止非法数据破坏状态。
-
语义化的值映射
:
0x0001
与
0x0002
是BLE SIG官方定义的CCCD有效值,直接映射到
led_notify_enabled
的
1
和
2
,为后续通知/指示的区分奠定基础。
通知触发:在业务逻辑中主动调用发送API
标志位更新后,通知并不会自动发生。服务端必须在其业务逻辑中,于特征值实际变更之后,显式调用发送API。以周期性切换LED状态的任务为例:
// 在LED控制任务中(例如一个FreeRTOS任务)
void led_control_task(void *pvParameters) {
while(1) {
// 1. 执行业务逻辑:读取/计算新的LED状态
uint8_t new_led_state = get_next_led_state(); // 例如,取反当前状态
// 2. 更新GATT数据库中的LED特征值
esp_ble_gatts_set_attr_value(led_char_val_handle, sizeof(new_led_state), &new_led_state);
// 3. 关键步骤:检查通知标志位,决定是否发送
if (led_notify_enabled == 1) {
// 发送Notification:无需客户端确认
esp_ble_gatts_send_notify(gatts_if, conn_id, led_char_val_handle, sizeof(new_led_state), &new_led_state);
} else if (led_notify_enabled == 2) {
// 发送Indication:需要客户端确认
esp_ble_gatts_send_indicate(gatts_if, conn_id, led_char_val_handle, sizeof(new_led_state), &new_led_state);
}
vTaskDelay(LED_TOGGLE_PERIOD / portTICK_PERIOD_MS);
}
}
此处的
esp_ble_gatts_send_notify()
和
esp_ble_gatts_send_indicate()
是ESP-IDF提供的核心API。它们的参数列表清晰体现了设计意图:
-
gatts_if
: GATT服务接口ID;
-
conn_id
: 目标客户端的连接ID;
-
handle
: 被通知的特征值句柄(即
led_char_val_handle
);
-
length
与
value
: 待通知的数据内容。
必须强调
:
esp_ble_gatts_send_notify()
的调用,是通知机制得以生效的最终一环。缺少它,无论CCCD如何配置,客户端都将永远静默。
3.6.3 客户端核心实现:注册、CCCD写入与通知接收
客户端的角色相对被动,其工作重心在于: 正确注册通知、确保CCCD被成功写入、可靠地接收并解析通知数据 。这三步缺一不可。
注册通知:调用
setNotify(true)
的实质
在Android/iOS或nRF Connect等标准BLE客户端中,点击“Enable Notification”按钮,其背后执行的是一系列标准化的GATT操作:
1.
发现服务与特征值
:通过
discoverServices()
获取服务列表,再通过
discoverCharacteristics()
获取LED特征值及其关联的CCCD。
2.
写入CCCD
:构造一个2字节的
0x0001
数据包,向CCCD的句柄发起
writeDescriptor()
请求。
3.
等待写入结果
:监听
onDescriptorWrite()
回调,确认写入成功。
在ESP32作为GATT客户端的场景下(例如,一个ESP32设备连接另一个ESP32服务端),此过程由
esp_ble_gattc_write_char_descr()
API完成。关键点在于,
写入CCCD的操作必须在特征值读取/发现完成后进行,且必须等待
ESP_GATTC_WRITE_DESCR_EVT
事件返回成功状态,才能认为注册完成
。
CCCD写入的必要性与常见误区
一个高频错误是:开发者在客户端代码中调用了
setNotify(true)
,但服务端日志却显示
led_notify_enabled
始终为0。这几乎可以断定,CCCD写入操作失败或未被执行。
原因可能包括:
-
未等待服务端返回CCCD句柄
:在
ESP_GATTC_CFG_MTU_EVT
或
ESP_GATTC_SEARCH_CMPL_EVT
事件后,必须先通过
esp_ble_gattc_get_characteristic()
获取特征值信息,再通过
esp_ble_gattc_get_descriptor()
获取其CCCD句柄,最后才能调用
write_char_descr()
。
-
写入超时或连接不稳定
:
write_char_descr()
是异步操作,需在
ESP_GATTC_WRITE_DESCR_EVT
事件中检查
param->write.status
是否为
ESP_GATT_OK
。
-
服务端未正确处理CCCD写入
:如前所述,服务端
gatts_write_evt_cb
中未正确识别CCCD句柄或未校验数据长度。
一个经过验证的健壮写入流程如下:
// 在客户端的ESP_GATTC_SEARCH_CMPL_EVT事件处理中
case ESP_GATTC_SEARCH_CMPL_EVT: {
if (param->search_cmpl.status == ESP_GATT_OK) {
// 成功发现服务,现在获取LED特征值的CCCD句柄
esp_ble_gattc_get_descriptor(gattc_if, conn_id, led_char_handle,
(uint16_t)ESP_GATT_UUID_CHAR_CLIENT_CONFIG,
&led_cccd_handle);
}
break;
}
// 在ESP_GATTC_CFG_MTU_EVT事件后,尝试写入CCCD
case ESP_GATTC_CFG_MTU_EVT: {
if (param->cfg_mtu.status == ESP_GATT_OK) {
// 准备CCCD写入数据:0x0001
uint8_t cccd_value[2] = {0x01, 0x00};
esp_ble_gattc_write_char_descr(gattc_if, conn_id, led_cccd_handle,
sizeof(cccd_value), cccd_value,
ESP_GATT_WRITE_TYPE_NO_RSP,
ESP_GATT_AUTH_REQ_NONE);
}
break;
}
// 在ESP_GATTC_WRITE_DESCR_EVT事件中确认结果
case ESP_GATTC_WRITE_DESCR_EVT: {
if (param->write.status == ESP_GATT_OK &&
param->write.handle == led_cccd_handle) {
ESP_LOGI(GATTC_TAG, "CCCD write success. Notify registered.");
// 此刻,客户端已成功注册,可等待服务端通知
} else {
ESP_LOGE(GATTC_TAG, "CCCD write failed. Status: %d", param->write.status);
}
break;
}
通知接收:解析
ESP_GATTS_NOTIFY_EVT
事件
当服务端成功调用
esp_ble_gatts_send_notify()
后,客户端GATT层会收到
ESP_GATTC_NOTIFY_EVT
事件。客户端必须在此事件的处理函数中,提取并解析通知数据:
case ESP_GATTC_NOTIFY_EVT: {
// 1. 校验通知来源:是否来自LED特征值
if (param->notify.handle == led_char_val_handle) {
// 2. 校验数据长度(预期为1字节LED状态)
if (param->notify.value_len == 1) {
uint8_t led_state = param->notify.value[0];
ESP_LOGI(GATTC_TAG, "Received LED Notify: State = %d", led_state);
// 3. 执行业务逻辑:例如,控制本地LED
gpio_set_level(LED_GPIO, led_state ? 1 : 0);
} else {
ESP_LOGW(GATTC_TAG, "Unexpected notify length: %d", param->notify.value_len);
}
}
break;
}
此段代码体现了客户端接收通知的标准模式: 句柄匹配 → 长度校验 → 数据解析 → 业务处理 。其中,句柄匹配是防止不同特征值通知混淆的关键安全措施。
3.6.4 通知(Notification)与指示(Indication)的深度辨析
尽管二者在API调用上仅差一个函数名,但在协议栈层面、网络行为和应用场景上存在本质差异。理解这些差异,是设计健壮BLE应用的基础。
| 特性 | 通知(Notification) | 指示(Indication) |
|---|---|---|
| 协议栈定义 |
ATT Opcode:
0x1B
(Handle Value Notification)
|
ATT Opcode:
0x1D
(Handle Value Indication)
|
| 客户端确认 | 不需要 。服务端单向发送,不等待ACK。 |
必须
。服务端发送后,必须等待客户端返回
0x1E
(Handle Value Confirmation)。
|
| 服务端API |
esp_ble_gatts_send_notify()
|
esp_ble_gatts_send_indicate()
|
| CCCD值 |
0x0001
|
0x0002
|
| 可靠性 | 低。数据丢失无感知,适合非关键状态更新(如传感器读数)。 | 高。服务端可获知数据是否送达,适合关键指令(如固件升级指令)。 |
| 功耗与延迟 | 更低。无往返通信开销。 | 更高。每次指示均引入一次RTT延迟。 |
| 服务端实现复杂度 | 简单。仅需发送。 |
复杂。需在
ESP_GATTS_INDICATE_EVT
事件中处理确认,并可能需重传逻辑。
|
在代码层面,
led_notify_enabled
的值
1
与
2
正是对上述协议语义的直接映射。服务端在LED状态变更后,根据该值选择调用
send_notify()
或
send_indicate()
,从而严格遵循了BLE规范对两种机制的定义。
3.6.5 工程实践中的关键技巧与避坑指南
基于大量ESP32 BLE项目经验,以下技巧能显著提升通知功能的稳定性与可维护性:
技巧1:使用
esp_ble_gatts_send_indicate()
替代
send_notify()
进行调试
在开发初期,若通知无法被客户端接收,可临时将服务端的发送逻辑改为
send_indicate()
。因为指示必须获得客户端确认,服务端会收到
ESP_GATTS_INDICATE_EVT
事件。如果此事件从未触发,即可100%确定问题出在CCCD写入环节(客户端未写、服务端未处理、连接中断),而非通知触发环节。这是一种快速定位问题域的有效方法。
技巧2:在CCCD写入回调中添加服务端日志回显
在服务端的
gatts_write_evt_cb
中,当成功解析CCCD写入后,立即调用
esp_ble_gatts_send_response()
返回一个自定义的、包含状态信息的响应。例如:
// 在CCCD写入成功后
esp_ble_gatts_send_response(gatts_if, param->write.conn_id, param->write.trans_id,
ESP_GATT_OK, &response_data); // response_data可包含"NOTIFY_ON"
客户端在
onDescriptorWrite()
回调中检查此响应,即可实时获知服务端是否已正确解析并启用了通知。这比单纯依赖
status == ESP_GATT_OK
提供了更丰富的上下文。
技巧3:为每个特征值维护独立的CCCD句柄缓存
在复杂服务中,可能有多个特征值支持通知。切勿使用全局的
led_cccd_handle
变量来存储所有CCCD句柄。应为每个特征值定义独立的句柄变量(如
temp_cccd_handle
,
battery_cccd_handle
),并在服务端初始化时,通过
esp_ble_gatts_create_attr_tab()
创建属性表时,明确指定每个CCCD的句柄索引。这能从根本上避免因句柄混淆导致的“A特征值的通知被B特征值的CCCD控制”这类诡异Bug。
技巧4:处理连接断开时的CCCD状态清理
当客户端意外断开连接(
ESP_GATTS_DISCONNECT_EVT
),服务端应将
led_notify_enabled
重置为0。否则,在下次连接建立后,服务端可能仍按旧状态发送通知,而新连接的客户端尚未注册,导致数据被丢弃。这是一个常被忽视的边缘Case,但在长周期运行的网关类设备中至关重要。
case ESP_GATTS_DISCONNECT_EVT: {
ESP_LOGI(GATTS_TAG, "Device disconnected. Resetting notify flags.");
led_notify_enabled = 0;
break;
}
我在一个工业环境下的BLE传感器网关项目中,就曾因遗漏此步,导致设备在断电重启后,短暂时间内向未注册的客户端发送通知,造成GATT层短暂拥塞。加入此清理逻辑后,系统稳定性得到质的提升。
3.6.6 属性表设计:通知能力的基石
通知功能的实现,最终都映射到GATT属性表(Attribute Table)的结构设计上。一个完整的、支持通知的LED服务,其属性表至少应包含以下四个条目(Attributes):
| 序号 | 句柄(Handle) | UUID | 类型 | 描述 |
|---|---|---|---|---|
| 1 | 0x0001 |
0x2800
(Primary Service)
| Primary Service | LED服务声明 |
| 2 | 0x0002 |
0x2803
(Characteristic Declaration)
| Characteristic Declaration | LED状态特征值声明 |
| 3 | 0x0003 |
0x2A53
(LED State)
| Characteristic Value | LED状态特征值本身(可读写) |
| 4 | 0x0004 |
0x2902
(CCCD)
| Descriptor | 客户端配置描述符(可写) |
此表结构是通知机制的物理载体。句柄
0x0004
的CCCD,是客户端唯一能写入以开启通知的“开关”。句柄
0x0003
的特征值,是通知所承载的“数据源”。服务端代码中所有的
led_char_val_handle
和
led_cccd_handle
,都必须与此表的物理布局严格对应。任何在
esp_ble_gatts_create_attr_tab()
中对
attr_table
数组的顺序、UUID、权限(
ESP_GATT_PERM_READ
/
ESP_GATT_PERM_WRITE
)的配置错误,都会导致通知链路的断裂。
因此,在开始编写通知逻辑前,务必使用
nRF Connect
或
LightBlue
等工具,连接服务端并导出其GATT浏览器视图,逐项核对服务、特征值、CCCD的UUID、句柄和权限。这是所有BLE调试工作的起点,也是最高效的问题排查手段。
418



被折叠的 条评论
为什么被折叠?



