跳转到内容
ESPHome - 智能家居，简单易用

BLE 服务器

ESPHome 中的 esp32_ble_server 组件设置一个 BLE GATT 服务器，暴露设备名称、制造商和开发板信息。可以向服务器添加 BLE GATT 服务和特征以暴露数据和控制功能。

WARNING

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

如果您在设备配置中包含太多额外的组件，很可能会发生崩溃。内存密集型组件，如 语音助手 和其他音频组件，最有可能导致问题。

# 示例配置


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);

配置变量

Section titled “配置变量”

  • manufacturer (可选, 值配置): 制造商/固件创建者的名称。默认为 ESPHome。

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

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

  • firmware_version (可选, 值配置): 设备的固件版本。如果存在，默认为核心配置中定义的项目版本，否则为 ESPHome 版本。

  • manufacturer_data (可选, 字节列表): 要包含在广播数据包中的制造商特定数据。应该是字节列表，其中前两个字节是 Bluetooth SIG 分配的 16 位制造商 ID 的小端表示。

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

  • on_disconnect (可选, 自动化): 当客户端从 BLE 服务器断开连接时要执行的操作。它提供 id 变量，包含已断开客户端的 ID。

  • services (可选, 服务配置 列表): 要在 BLE GATT 服务器上暴露的服务列表。

服务配置

Section titled “服务配置”

服务是通过 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!"

配置变量

Section titled “配置变量”
  • uuid (必需, string, int): 服务的 UUID。
  • advertise (可选, boolean): 是否广播该服务。默认为 false。
  • characteristics (可选, 特征配置 列表): 要在此服务中暴露的特征列表。

特征配置

Section titled “特征配置”

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

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

配置变量

Section titled “配置变量”
  • id (可选, string): 在自动化中引用此特征的 ID。
  • uuid (必需, string, int): 特征的 UUID。
  • description (可选, 值配置): 特征的描述 - 不可模板化。它将为特征添加一个值为描述内容的 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 (可选, 值配置): 特征的值。
  • descriptors (可选, 描述符配置 列表): 要在此特征中暴露的描述符列表。
  • on_write (可选, 自动化): 当特征被写入时要执行的操作。特征必须具有 write 属性。参见 on_write 触发器。

描述符配置

Section titled “描述符配置”

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

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

配置变量

Section titled “配置变量”

值配置

Section titled “值配置”

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

esp32_ble_server:
  services:
    - uuid: # ...
      characteristics:
        - uuid: # ...
          # 简单值（自动检测类型）
          value: "Hello, World!"
        - uuid: # ...
          # 字符串值
          value:
            data: "Hello, World!"
            type: string
            string_encoding: utf-8
        - uuid: # ...
          # 整数值
          value:
            data: "123"
            type: uint16_t
            endianness: LITTLE
        - uuid: # ...
          # 字节数组值
          value:
            data: [9, 9, 9]
        - uuid: # ...
          # Lambda 值
          value:
            data: !lambda 'return std::vector<uint8_t>({9, 9, 9});'
        - uuid: # ...
          # 使用 ByteBuffer 的 Lambda 值
          value:
            data: !lambda 'return bytebuffer::ByteBuffer::wrap(0.182).get_data();'

配置变量

Section titled “配置变量”
  • data (必需, string, int, float, boolean, 字节列表, 可模板化): 特征或描述符的值。对于可模板化值，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 触发器

Section titled “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 动作

Section titled “ble_server.characteristic.set_value 动作”

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

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

配置变量

Section titled “配置变量”
  • id (必需, string): 要设置值的特征的 ID。
  • value (*必需, 值配置): 特征的新值。

ble_server.characteristic.notify 动作

Section titled “ble_server.characteristic.notify 动作”

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

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

配置变量

Section titled “配置变量”
  • id (必需, string): 要通知客户端的特征的 ID（必须具有 notify 属性）。

ble_server.descriptor.set_value 动作

Section titled “ble_server.descriptor.set_value 动作”

此动作设置描述符的值。

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

配置变量

Section titled “配置变量”
  • id (*必需, string): 要设置值的描述符的 ID。
  • value (*必需, 值配置): 描述符的新值。

另请参阅

Section titled “另请参阅”