BLE 服务端

esp32_ble_server 组件在 ESPHome 中设置一个 BLE GATT 服务端，暴露设备名称、 制造商和板。可以向服务端添加 BLE GATT 服务和特征，以暴露数据和控制。

WARNING

ESP32 上的 BLE 软件协议栈会占用设备大量的 RAM。

如果在设备的 配置中加入了过多的组件，很可能会发生崩溃。语音助手等 消耗大量内存的组件和其它音频组件最可能导致问题。

# Example configuration

esp32_ble_server:
  manufacturer: "Orange"
  manufacturer_data: [0x4C, 0, 0x23, 77, 0xF0 ]
  on_connect:
    - lambda: |-
        ESP_LOGD("BLE", "Connection from %d", id);
  on_disconnect:
    - lambda: |-
        ESP_LOGD("BLE", "Disconnection from %d", id);

配置变量

• manufacturer (可选, Value Configuration)：制造商/固件创建者的名称。默认为 ESPHome。

• model (可选, Value Configuration)：设备的型号名称。如果 核心配置 中定义了项目的名称则默认为该名称，否则默认为在 核心配置 中选择的 board 的友好名称。

• appearance (可选, int)：设置设备的外观（包含在广播数据中）。默认为 0。

• firmware_version (可选, Value Configuration)：设备的固件版本。如果 核心配置 中定义了项目的版本则默认为该版本，否则默认为 ESPHome 版本。

• manufacturer_data (可选, list of bytes)：包含在广播 数据包中的制造商特定数据。应为字节列表，其中前两个字节是以小端表示的 16 位 制造商 ID，该 ID 由蓝牙 SIG 分配。

• max_clients (可选, int)：服务端接受的同时 BLE 客户端连接的最大数量。当设为大于 1 的值时，客户端连接后服务端会恢复广播，以便 更多客户端能够发现并连接，直到达到此限制。不得超过 ESP32 BLE 组件中配置的 max_connections 值。默认为 1。范围：1 至 9。

• on_connect (可选, 自动化)：客户端连接到 BLE 服务端时执行的动作。它提供 id 变量，其中包含已连接客户端的 ID。

• on_disconnect (可选, 自动化)：客户端从 BLE 服务端断开时执行的动作。它提供 id 变量，其中包含已断开客户端的 ID。

• services (可选, list of Service Configuration)：要在 BLE GATT 服务端上暴露的服务列表。

服务配置

服务是通过 BLE 暴露数据和控制的主要方式。服务通过特征与客户端通信。每个服务可以有多个特征。

esp32_ble_server:
  services:
    - uuid: 2a24b789-7aab-4535-af3e-ee76a35cc42d
      advertise: false
      characteristics:
        - uuid: cad48e28-7fbe-41cf-bae9-d77a6c233423
          read: true
          value:
            value: "Hello, World!"

配置变量

• uuid (必选, string, int)：服务的 UUID。
• advertise (可选, boolean)：是否广播该服务。默认为 false。
• characteristics (可选, list of Characteristic Configuration)：要在该服务中暴露的特征列表。

特征配置

特征为 BLE 服务暴露数据和控制。每个特征都有一个值，该值可以是可读和/或可写的，并允许客户端订阅通知。 特征还可以有多个描述符，以提供有关该特征的附加信息。

esp32_ble_server:
  services:
    # ...
    advertise: true
    characteristics:
      - id: test_characteristic
        uuid: cad48e28-7fbe-41cf-bae9-d77a6c233423
        description: "Sample description"
        read: true
        value:
            data: "123.1"
            type: float
            endianness: BIG
        descriptors:
          - uuid: cad48e28-7fbe-41cf-bae9-d77a6c211423
            value: "Hello, World Descriptor!"

配置变量

• id (可选, string)：在自动化中引用此特征的 ID。
• uuid (必选, string, int)：特征的 UUID。
• description (可选, Value Configuration)：特征的描述 - 不可模板化。它将为特征添加一个 CUD 描述符（0x2901），其值为描述内容。
• read (可选, boolean)：是否使特征可读。默认为 false。
• write (可选, boolean)：是否使特征可写。默认为 false。
• broadcast (可选, boolean)：是否使特征可广播。默认为 false。
• notify (可选, boolean)：是否支持通知。如果为 true，将自动为该特征添加 CCCD 描述符。默认为 false。
• indicate (可选, boolean)：是否支持指示。如果为 true，将自动为该特征添加 CCCD 描述符。默认为 false。
• write_no_response (可选, boolean)：是否支持无响应写入。默认为 false。
• value (可选, Value Configuration)：特征的值。
• descriptors (可选, list of Descriptor Configuration)：要在该特征中暴露的描述符列表。
• on_write (可选, 自动化)：写入特征时执行的动作。特征必须具有 write 属性。参见on_write 触发器。

描述符配置

描述符是可选的，用于提供有关特征的附加信息（元数据）。

esp32_ble_server:
  services:
    - uuid: # ...
      characteristics:
        - uuid: # ...
          descriptors:
            - uuid: 2901
              value:
                value: "Hello, World Descriptor!"

配置变量

• id (可选, string)：在自动化中引用此描述符的 ID。
• uuid (必选, string, int)：描述符的 UUID。
• value (必选, Value Configuration)：描述符的值。不允许使用可模板化的值。如需动态设置描述符的值，请使用ble_server.descriptor.set_value 动作。

Value 配置

值可以有不同的类型，用于定义特征或描述符的值。 特征的值是可模板化的。如果值使用了模板，则每次读取特征或触发通知时都会评估模板。描述符的值不可模板化，因为它被期望为静态值。

esp32_ble_server:
  services:
    - uuid: # ...
      characteristics:
        - uuid: # ...
          # Simple value (auto-detect type)
          value: "Hello, World!"
        - uuid: # ...
          # String value
          value:
            data: "Hello, World!"
            type: string
            string_encoding: utf-8
        - uuid: # ...
          # Integer value
          value:
            data: "123"
            type: uint16_t
            endianness: LITTLE
        - uuid: # ...
          # Array of bytes value
          value:
            data: [9, 9, 9]
        - uuid: # ...
          # Lambda value
          value:
            data: !lambda 'return std::vector<uint8_t>({9, 9, 9});'
        - uuid: # ...
          # Lambda value using ByteBuffer
          value:
            data: !lambda 'return bytebuffer::ByteBuffer::wrap(0.182).get_data();'

配置变量

• data (必选, string, int, float, boolean, list of bytes, 可模板化)：特征或描述符的值。对于可模板化的值，lambda 函数必须返回 std::vector<uint8_t>（可以使用 bytebuffer::ByteBuffer 辅助类将不同的数据类型转换为字节数组）。该值在每次读取特征时计算。
• type (可选, string)：值的 C++ 类型。可用值有 uint8_t、uint16_t、uint32_t、uint64_t、int8_t、int16_t、int32_t、int64_t、float、double 和 string。如果值不是可模板化的，则必须定义。
• endianness (可选, string)：值的字节序。可以是 BIG 或 LITTLE。默认为 LITTLE。
• string_encoding (可选, string)：字符串的编码。仅当类型为 string 时适用。转换在编译前由 Python 完成，因此编码必须是有效的Python 编码。默认为 utf-8。

on_write 触发器

通过此配置选项，可以编写在写入特征时触发的复杂自动化。它提供 x 变量，其中包含作为 std::vector<uint8_t> 的特征新值，以及 id 变量，其中包含写入特征的客户端 ID。

esp32_ble_server:
  services:
    - uuid: # ...
      characteristics:
        # ...
        write: true
        on_write:
          then:
            - lambda: |-
                ESP_LOGD("BLE", "Descriptor received: %s from %d", std::string(x.begin(), x.end()).c_str(), id);

ble_server.characteristic.set_value 动作

此动作设置特征的值。如果特征的配置中也有模板化的值，则特征不能有 set_value 动作。

on_...:
  then:
    - ble_server.characteristic.set_value:
        id: test_write_characteristic
        value: [0, 1, 2]

配置变量

• id (必选, string)：要设置其值的特征的 ID。
• value (必选, Value Configuration)：特征的新值。

ble_server.characteristic.notify 动作

此动作触发向客户端发送通知。发送的值将是特征当前的值，如果存在模板，则是模板求值后的值。

on_...:
  then:
    - ble_server.characteristic.notify:
        id: test_notify_characteristic

配置变量

• id (必选, string)：要向客户端发送通知的特征的 ID（必须具有 notify 属性）。

ble_server.descriptor.set_value 动作

此动作设置描述符的值。

on_...:
  then:
    - ble_server.descriptor.set_value:
        id: test_write_descriptor
        value: [0, 1, 2]

配置变量

• id (必选, string)：要设置其值的描述符的 ID。
• value (必选, Value Configuration)：描述符的新值。

另请参阅

• BLE 组件
• 通过 BLE 进行 Improv
• API 参考：ble.h