ESP32蓝牙开发笔记（十四）

在 ESP32 的 BLE 开发中，esp_ble_gatts_add_char 是用于向 GATT 服务中添加特征（Characteristic）的核心函数。以下是该函数的详细说明、参数解析及示例代码：

---

函数原型

esp_err_t esp_ble_gatts_add_char(uint16_t service_handle,                  // 服务句柄（由添加服务时返回）esp_bt_uuid_t *char_uuid,                  // 特征的 UUIDesp_gatt_perm_t perm,                      // 特征的访问权限esp_gatt_char_prop_t property,             // 特征的属性（可读、可写等）esp_attr_value_t *char_val,                // 特征的初始值（可选）esp_attr_control_t *control                // 特征的属性控制（安全模式等）
);

---

参数详解

1. service_handle（服务句柄）

• ​来源：由 esp_ble_gatts_create_service 或 esp_ble_gatts_add_service 创建服务后返回的句柄。
• ​作用：指定特征所属的服务。

2. char_uuid（特征 UUID）

• ​类型：esp_bt_uuid_t，可以是 16-bit、32-bit 或 128-bit UUID。
• ​示例：

  // 16-bit UUID（例如心率测量特征）
  esp_bt_uuid_t char_uuid = {.len = ESP_UUID_LEN_16,.uuid = {.uuid16 = 0x2A37}
  };

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. property（属性）

• ​类型：esp_gatt_char_prop_t，定义特征支持的操作类型。
• ​常用值​（按位或组合）：
  • ESP_GATT_CHAR_PROP_BIT_READ：可读
  • ESP_GATT_CHAR_PROP_BIT_WRITE：可写（无响应）
  • ESP_GATT_CHAR_PROP_BIT_WRITE_NR：可写（有响应）
  • ESP_GATT_CHAR_PROP_BIT_NOTIFY：支持通知
  • ESP_GATT_CHAR_PROP_BIT_INDICATE：支持指示

5. char_val（特征初始值）

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

  esp_attr_value_t char_val = {.attr_max_len = 10,  // 最大长度.attr_len = 4,       // 初始值长度.attr_value = {0x01, 0x02, 0x03, 0x04} // 初始值
  };

6. control（属性控制）

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

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

---

返回值

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

---

示例代码

步骤 1：创建服务

esp_bt_uuid_t service_uuid = {.len = ESP_UUID_LEN_16,.uuid = {.uuid16 = 0x180D} // 心率服务
};
uint16_t service_handle;
esp_ble_gatts_create_service(&service_uuid, 0, 5, &service_handle);

步骤 2：添加特征

// 定义特征 UUID（心率测量）
esp_bt_uuid_t char_uuid = {.len = ESP_UUID_LEN_16,.uuid = {.uuid16 = 0x2A37}
};// 特征权限和属性
esp_gatt_perm_t perm = ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE;
esp_gatt_char_prop_t property = ESP_GATT_CHAR_PROP_BIT_READ | ESP_GATT_CHAR_PROP_BIT_NOTIFY;// 添加特征
esp_err_t ret = esp_ble_gatts_add_char(service_handle,&char_uuid,perm,property,NULL,  // 初始值为空NULL   // 使用默认控制
);if (ret != ESP_OK) {ESP_LOGE("GATTS", "添加特征失败: %s", esp_err_to_name(ret));
}

步骤 3：启动服务

esp_ble_gatts_start_service(service_handle);

---

关键注意事项

1. ​特征描述符​（如 CCCD）：
   • 若特征支持通知或指示，需手动添加客户端特征配置描述符（CCCD），使用 esp_ble_gatts_add_char_descr。
2. ​回调处理：
   • 特征的操作（读/写）会触发 ESP_GATTS_READ_EVT 或 ESP_GATTS_WRITE_EVT，需在 esp_ble_gatts_register_callback 中处理。
3. ​动态值更新：
   • 使用 esp_ble_gatts_set_attr_value 可动态更新特征值。

---

错误排查

• ​无效句柄：确保 service_handle 来自已成功创建的服务。
• ​权限冲突：property 和 perm 需匹配（例如，若 property 包含 ESP_GATT_CHAR_PROP_BIT_READ，则 perm 必须包含 ESP_GATT_PERM_READ）。
• ​内存不足：检查 ESP32 的堆内存（heap_caps_get_free_size()）。

---

完整流程示意图

创建服务 (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，可以构建符合 BLE 标准的 GATT 服务，实现数据交互。