如何自定义低功耗蓝牙服务

[English]

本文档介绍了如何利用 ESP-AT 提供的低功耗蓝牙服务源文件在 ESP32-C3 设备上自定义低功耗蓝牙服务。

低功耗蓝牙服务被定义为 GATT 结构的多元数组,该数组至少包含一个属性类型 (attribute type) 为 0x2800 的首要服务 (primary service)。每个服务总是由一个服务定义和几个特征组成。每个特征总是由一个值和可选的描述符组成。更多相关信息请参阅 《蓝牙核心规范》 中的 Generic Attribute Profile (GATT) 一节。

低功耗蓝牙服务源文件

低功耗蓝牙服务源文件是 ESP-AT 工程创建低功耗蓝牙服务所依据的文件,文件位于 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 的更多信息请参考 蓝牙技术联盟分配符

如果直接在 ESP32-C3 设备上使用默认源文件,不做任何修改,并建立低功耗蓝牙连接,那么在客户端查询服务器服务后,会得到如下结果。

ESP-AT 默认低功耗蓝牙服务

自定义低功耗蓝牙服务

请根据以下步骤自定义低功耗蓝牙服务。

修改低功耗蓝牙服务源文件

可定义多个服务,例如,若要定义三个服务(Server_AServer_BServer_C),则需要将这三个服务按顺序排列。由于定义每个服务的操作大同小异,这里我们以定义一个服务为例,其他服务您可以按照此例进行定义。

  1. 添加服务定义。

    本例定义了一个值为 0xFF01 的主要服务。

    index

    uuid_len

    uuid

    perm

    val_max_len

    val_cur_len

    value

    31

    16

    0x2800

    0x01

    2

    2

    FF01

  2. 添加特征说明和特征值。

    本例定义了一个 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

  3. 添加特征描述符(可选)。

    本例添加了客户端特征配置,数字 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-C3: 0x1F000

    • ESP32-C3 QCLOUD: 0x21000

下载完成后,重新建立低功耗蓝牙连接,在客户端查询的服务器服务如下所示。

ESP-AT 自定义低功耗蓝牙服务