如何自定义低功耗蓝牙服务¶
本文档介绍了如何利用 ESP-AT 提供的低功耗蓝牙服务源文件在 ESP 设备上自定义低功耗蓝牙服务。
低功耗蓝牙服务被定义为 GATT 结构的多元数组，该数组至少包含一个属性类型 (attribute type) 为 0x2800 的首要服务 (primary service)。每个服务总是由一个服务定义和几个特征组成。每个特征总是由一个值和可选的描述符组成。更多相关信息请参阅 《蓝牙核心规范》 中的 Generic Attribute Profile (GATT) 一节。
低功耗蓝牙服务源文件¶
低功耗蓝牙服务源文件是 ESP-AT 工程创建低功耗蓝牙服务所依据的文件，文件位于 components/customized_partitions/raw_data/ble_data/example.csv，内容如下表所示。
index |
uuid_len |
uuid |
perm |
val_max_len |
val_cur_len |
value |
|---|---|---|---|---|---|---|
0 |
16 |
0x2800 |
0x01 |
2 |
2 |
A002 |
1 |
16 |
0x2803 |
0x01 |
1 |
1 |
2 |
2 |
16 |
0xC300 |
0x01 |
1 |
1 |
30 |
3 |
16 |
0x2901 |
0x11 |
1 |
1 |
30 |
… |
… |
… |
… |
… |
… |
… |
以下内容是对上表的说明。
perm字段描述权限，它在 ESP-AT 工程中的定义如下所示。/* relate to BTA_GATT_PERM_xxx in bta/bta_gatt_api.h */ /** * @brief Attribute permissions */ #define ESP_GATT_PERM_READ (1 << 0) /* bit 0 - 0x0001 */ /* relate to BTA_GATT_PERM_READ in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_READ_ENCRYPTED (1 << 1) /* bit 1 - 0x0002 */ /* relate to BTA_GATT_PERM_READ_ENCRYPTED in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_READ_ENC_MITM (1 << 2) /* bit 2 - 0x0004 */ /* relate to BTA_GATT_PERM_READ_ENC_MITM in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_WRITE (1 << 4) /* bit 4 - 0x0010 */ /* relate to BTA_GATT_PERM_WRITE in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_WRITE_ENCRYPTED (1 << 5) /* bit 5 - 0x0020 */ /* relate to BTA_GATT_PERM_WRITE_ENCRYPTED in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_WRITE_ENC_MITM (1 << 6) /* bit 6 - 0x0040 */ /* relate to BTA_GATT_PERM_WRITE_ENC_MITM in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_WRITE_SIGNED (1 << 7) /* bit 7 - 0x0080 */ /* relate to BTA_GATT_PERM_WRITE_SIGNED in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_WRITE_SIGNED_MITM (1 << 8) /* bit 8 - 0x0100 */ /* relate to BTA_GATT_PERM_WRITE_SIGNED_MITM in bta/bta_gatt_api.h */ #define ESP_GATT_PERM_READ_AUTHORIZATION (1 << 9) /* bit 9 - 0x0200 */ #define ESP_GATT_PERM_WRITE_AUTHORIZATION (1 << 10) /* bit 10 - 0x0400 */
上表第一行是 UUID 为
0xA002的服务定义。第二行是特征的声明。UUID
0x2803表示特征声明，数值 (value)2设置权限，权限长度为 8 位，每一位代表一个操作的权限，1表示支持该操作，0表示不支持。位
权限
0
BROADCAST
1
READ
2
WRITE WITHOUT RESPONSE
3
WRITE
4
NOTIFY
5
INDICATE
6
AUTHENTICATION SIGNED WRITES
7
EXTENDED PROPERTIES
第三行定义了服务的特征。该行的 UUID 是特征的 UUID，数值是特征的数值。
第四行定义了特征的描述符（可选）。
有关 UUID 的更多信息请参考 蓝牙技术联盟分配符。
如果直接在 ESP 设备上使用默认源文件，不做任何修改，并建立低功耗蓝牙连接，那么在客户端查询服务器服务后，会得到如下结果。
自定义低功耗蓝牙服务¶
请根据以下步骤自定义低功耗蓝牙服务。
修改低功耗蓝牙服务源文件¶
可定义多个服务，例如，若要定义三个服务（Server_A、Server_B 和 Server_C），则需要将这三个服务按顺序排列。由于定义每个服务的操作大同小异，这里我们以定义一个服务为例，其他服务您可以按照此例进行定义。
添加服务定义。
本例定义了一个值为 0xFF01 的主要服务。
index
uuid_len
uuid
perm
val_max_len
val_cur_len
value
31
16
0x2800
0x01
2
2
FF01
添加特征说明和特征值。
本例定义了一个 UUID 为 0xC300 的可读可写特征，并将其值设置为 0x30。
index
uuid_len
uuid
perm
val_max_len
val_cur_len
value
32
16
0x2803
0x11
1
1
0A
33
16
0xC300
0x11
1
1
30
添加特征描述符（可选）。
本例添加了客户端特征配置，数字 0x0000 表示通知 (notification) 和指示 (indication) 被禁用。
index
uuid_len
uuid
perm
val_max_len
val_cur_len
value
34
16
0x2902
0x11
2
2
0000
完成以上步骤后，自定义的低功耗蓝牙服务定义如下。
index |
uuid_len |
uuid |
perm |
val_max_len |
val_cur_len |
value |
|---|---|---|---|---|---|---|
31 |
16 |
0x2800 |
0x01 |
2 |
2 |
FF01 |
32 |
16 |
0x2803 |
0x11 |
1 |
1 |
0A |
33 |
16 |
0xC300 |
0x11 |
1 |
1 |
30 |
34 |
16 |
0x2902 |
0x11 |
2 |
2 |
0000 |
生成 ble_data.bin 文件¶
可采用以下任意一种方式生成 ble_data.bin 文件。
重新编译 ESP-AT 工程，生成 ble_data.bin，详情请见 编译工程。
执行
BLEService.py脚本，生成 ble_data.bin 文件。BLEService.py的路径为tools/BLEService.py，您可以在 ESP-AT 的根目录执行以下命令生成 ble_data.bin 文件。python ./tools/BLEService.py components/customized_partitions/raw_data/ble_data/example.csv
下载 ble_data.bin 文件¶
可采用以下任意一种方式下载 ble_data.bin 文件，分别对应 生成 ble_data.bin 文件 这一小节中提到的生成 ble_data.bin 文件的方法。
下载重新编译过的 ESP-AT 固件，详情请见 烧录到设备。
仅下载 ble_data.bin，这种方法只更新设备中的 ble_data 区域。
您可以在 ESP-AT 根目录执行以下命令下载 ble_data.bin 文件。
esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS ble_data.bin
将
PORTNAME替换为您的串口名称，ADDRESS替换为下载 ble_data.bin 文件的地址，不同的模组有不同的下载地址。ESP32：0x21000
ESP32-C3：0x1F000
ESP32-C3 QCLOUD：0x21000
下载完成后，重新建立低功耗蓝牙连接，在客户端查询的服务器服务如下所示。
