ESP32蓝牙开发笔记（十五）

在 ESP32 的 BLE 开发中，esp_ble_gatts_add_char_descr 是用于向特征（Characteristic）中添加描述符（Descriptor）的核心函数。描述符用于提供特征的额外信息（如客户端特征配置、用户描述等）。以下是该函数的详细说明、参数解析及示例代码：

---

函数原型

esp_err_t esp_ble_gatts_add_char_descr(uint16_t service_handle,          // 服务句柄esp_bt_uuid_t *descr_uuid,        // 描述符的 UUIDesp_gatt_perm_t perm,              // 描述符的访问权限esp_attr_value_t *descr_val,       // 描述符的初始值（可选）esp_attr_control_t *control        // 描述符的属性控制（安全模式等）
);

---

参数详解

1. service_handle（服务句柄）

• ​来源：由 esp_ble_gatts_create_service 或 esp_ble_gatts_add_service 创建服务后返回的句柄。
• ​作用：指定描述符所属的服务（实际属于服务中的某个特征）。

2. descr_uuid（描述符 UUID）

• ​类型：esp_bt_uuid_t，描述符的标准或自定义 UUID。
• ​常用预定义值：
  • ​CCCD（客户端特征配置描述符）​：0x2902，用于启用通知（Notify）或指示（Indicate）。
  • ​用户描述符：0x2901，用于提供人类可读的特征描述。
  • ​特征扩展属性：0x2900，用于声明扩展属性。

3. perm（权限）

• ​类型：esp_gatt_perm_t，定义客户端对描述符的访问权限。
• ​常用值：
  • ESP_GATT_PERM_READ：允许读
  • ESP_GATT_PERM_WRITE：允许写
  • ESP_GATT_PERM_READ_ENCRYPTED：需要加密读
  • ESP_GATT_PERM_WRITE_ENCRYPTED：需要加密写

4. descr_val（初始值）

• ​类型：esp_attr_value_t，可选参数。如果设为 NULL，描述符初始值为空。
• ​示例：

  // CCCD 默认初始值为 0x0000（通知和指示均禁用）
  esp_attr_value_t descr_val = {.attr_max_len = 2,.attr_len = 2,.attr_value = {0x00, 0x00}
  };

5. control（属性控制）

• ​类型：esp_attr_control_t，通常用于配置安全模式。如果不需要特殊配置，可设为 NULL。
• ​示例：

  esp_attr_control_t control = {.auto_rsp = ESP_GATT_AUTO_RSP  // 自动响应读/写请求
  };

---

返回值

• ESP_OK：描述符添加成功。
• 其他错误码：失败（如无效句柄、内存不足等）。

---

示例代码

步骤 1：添加特征

// 先添加特征（假设已创建服务）
uint16_t char_handle;
esp_ble_gatts_add_char(service_handle,&char_uuid,perm,property,NULL, NULL, &char_handle
);

步骤 2：添加 CCCD 描述符

// 定义 CCCD 的 UUID（0x2902）
esp_bt_uuid_t cccd_uuid = {.len = ESP_UUID_LEN_16,.uuid = {.uuid16 = 0x2902}
};// 描述符权限（允许读写）
esp_gatt_perm_t perm = ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE;// 添加 CCCD 描述符
esp_err_t ret = esp_ble_gatts_add_char_descr(service_handle,&cccd_uuid,perm,NULL,   // 初始值为空（客户端首次读取会返回 0x0000）NULL    // 使用默认控制
);if (ret != ESP_OK) {ESP_LOGE("GATTS", "添加描述符失败: %s", esp_err_to_name(ret));
}

步骤 3：处理客户端写入 CCCD 的事件

在 GATT 事件回调中处理客户端对 CCCD 的写入操作：

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_WRITE_EVT: {// 检查是否为 CCCD 描述符写入if (param->write.handle == descr_handle) {uint16_t cccd_value = *(uint16_t*)param->write.value;if (cccd_value & ESP_GATT_CLIENT_CHAR_CFG_NOTIFY) {ESP_LOGI("GATTS", "客户端启用了通知");}if (cccd_value & ESP_GATT_CLIENT_CHAR_CFG_INDICATE) {ESP_LOGI("GATTS", "客户端启用了指示");}}break;}// 其他事件处理...}
}

---

关键注意事项

1. ​描述符必须属于某个特征：
   • 描述符必须添加到已存在的特征所属的服务中，且通常紧随特征添加之后调用。
2. ​CCCD 的特殊性：
   • CCCD 的 UUID 必须为 0x2902，且其值长度为 2 字节（0x0000 表示禁用，0x0001 启用通知，0x0002 启用指示）。
3. ​动态更新描述符值：
   • 使用 esp_ble_gatts_set_attr_value 可动态更新描述符值。
4. ​权限匹配：
   • 若描述符支持写操作（如 CCCD），perm 必须包含 ESP_GATT_PERM_WRITE。

---

错误排查

• ​无效句柄：确保 service_handle 有效且属于已创建的服务。
• ​UUID 错误：CCCD 必须使用 0x2902，否则客户端无法识别。
• ​权限不足：客户端尝试写入描述符时，若未配置 ESP_GATT_PERM_WRITE 会导致写入失败。

---

完整流程示意图

创建服务 (esp_ble_gatts_create_service)|v
添加特征 (esp_ble_gatts_add_char)|v
添加描述符 (esp_ble_gatts_add_char_descr)|v
启动服务 (esp_ble_gatts_start_service)|v
处理读写事件 (ESP_GATTS_READ_EVT / WRITE_EVT)

通过 esp_ble_gatts_add_char_descr，可以为特征添加必要的描述符，实现更复杂的 BLE 交互逻辑（如通知、指示）。