BTHome 组件

BTHome 组件用于实现 BTHome V2 协议，支持传感器数据上报、二进制传感器数据上报、事件数据上报等功能。该组件支持加密和非加密模式，可以与 Home Assistant 等智能家居平台无缝集成。

BTHome 使用方法

初始化 BTHome：
- 使用 bthome_create() 创建 BTHome 实例
- 使用 bthome_register_callbacks() 注册回调函数
- 使用 bthome_set_encrypt_key() 设置加密密钥（可选）
- 使用 bthome_set_peer_mac_addr() 设置对端 MAC 地址
配置存储：
- 使用 settings_store() 存储配置
- 使用 settings_load() 加载配置
解析广播数据：
- 使用 bthome_parse_adv_data() 解析广播数据
- 使用 bthome_free_reports() 释放报告数据

示例代码

// 创建 BTHome 实例
bthome_handle_t bthome_recv;
ESP_ERROR_CHECK(bthome_create(&bthome_recv));

// 注册回调函数
bthome_callbacks_t callbacks = {
    .store = settings_store,
    .load = settings_load,
};
ESP_ERROR_CHECK(bthome_register_callbacks(bthome_recv, &callbacks));

// 设置加密密钥
static const uint8_t encrypt_key[] = {0x23, 0x1d, 0x39, 0xc1, 0xd7, 0xcc, 0x1a, 0xb1, 0xae, 0xe2, 0x24, 0xcd, 0x09, 0x6d, 0xb9, 0x32};
ESP_ERROR_CHECK(bthome_set_encrypt_key(bthome_recv, encrypt_key));

// 设置对端 MAC 地址
static const uint8_t peer_mac[] = {0x54, 0x48, 0xE6, 0x8F, 0x80, 0xA5};
ESP_ERROR_CHECK(bthome_set_peer_mac_addr(bthome_recv, peer_mac));

// 解析广播数据
bthome_reports_t *reports = bthome_parse_adv_data(bthome_recv, result.ble_adv, result.adv_data_len);
if (reports != NULL) {
    // 处理报告数据
    for (int i = 0; i < reports->num_reports; i++) {
        // 处理每个报告
    }
    bthome_free_reports(reports);
}

API 参考

Header File

components/bluetooth/ble_adv/bthome/include/bthome_v2.h

Functions

esp_err_t bthome_create(bthome_handle_t *handle)

Create a BTHome object.

参数: handle – pointer to the bthome handle
返回: esp_err_t ESP_OK: success others: fail

esp_err_t bthome_delete(bthome_handle_t handle)

Delete a BTHome object.

参数: handle – pointer to the bthome handle
返回: esp_err_t ESP_OK: success others: fail

esp_err_t bthome_set_encrypt_key(bthome_handle_t handle, const uint8_t *key)

set the encryption key used for encryption and decryption

参数

handle – bthome handle
key – pointer to the key

返回

esp_err_t ESP_OK: success others: fail

esp_err_t bthome_set_local_mac_addr(bthome_handle_t handle, uint8_t *mac)

set the local mac address used for encryption

参数

handle – bthome handle
mac – pointer to the local ble mac address

返回

esp_err_t ESP_OK: success others: fail

esp_err_t bthome_set_peer_mac_addr(bthome_handle_t handle, const uint8_t *mac)

set the peer mac address used for decryption

参数

handle – bthome handle
mac – pointer to the peer ble mac address

返回

esp_err_t ESP_OK: success others: fail

esp_err_t bthome_register_callbacks(bthome_handle_t handle, bthome_callbacks_t *callbacks)

register the callback function

参数

handle – pointer to the bthome handle
callbacks – pointer to the callback structure

返回

esp_err_t ESP_OK: success others: fail

esp_err_t bthome_load_params(bthome_handle_t handle)

load the parameters from the storage

参数: handle – pointer to the bthome handle
返回: esp_err_t ESP_OK: success others: fail

void bthome_free_reports(bthome_reports_t *reports)

free the reports structure

参数: reports – pointer to the reports need to be freed

uint8_t bthome_payload_add_sensor_data(uint8_t *buffer, uint8_t offset, bthome_sensor_id_t obj_id, uint8_t *data, uint8_t data_len)

Add sensor data to the payload.

参数

buffer – pointer to the buffer
offset – current offset of the buffer
obj_id – sensor ID
data – pointer to the data
data_len – length of the data

返回

length of the data added to the buffer

uint8_t bthome_payload_adv_add_bin_sensor_data(uint8_t *buffer, uint8_t offset, bthome_bin_sensor_id_t obj_id, uint8_t data)

Add binary sensor data to the payload.

参数

buffer – pointer to the buffer
offset – current offset of the buffer
obj_id – binary sensor ID
data – data

返回

length of the data added to the buffer

uint8_t bthome_payload_adv_add_evt_data(uint8_t *buffer, uint8_t offset, bthome_event_id_t obj_id, uint8_t *evt, uint8_t evt_size)

Add event data to the payload.

参数

buffer – pointer to the buffer
offset – current offset of the buffer
obj_id – event ID
evt_size – event size
evt – event value

返回

length of the data added to the buffer

bthome_reports_t *bthome_parse_adv_data(bthome_handle_t handle, uint8_t *adv, uint8_t len)

Parse the advertisement data.

参数

handle – bthome handle
adv – pointer to the advertisement data
len – length of the advertisement data

返回

bthome_reports_t * pointer to the reports structure NULL if the parsing fails

uint8_t bthome_make_adv_data(bthome_handle_t handle, uint8_t *buffer, uint8_t *name, uint8_t name_len, bthome_device_info_t info, uint8_t *payload, uint8_t payload_len)

Create a BTHome advertisement data.

参数

handle – bthome handle
buffer – advertisement data buffer
name – advertisement name
name_len – length of the name
info – bthome device info
payload – pointer to the payload
payload_len – length of the payload

返回

length of the advertisement data

Unions

union bthome_device_info_t

#include <bthome_v2.h>

BTHome device info.

Public Members

uint8_t encryption_flag: bit 0: Encryption flag

uint8_t reserved1: bit 1: Reserved for future use

uint8_t trigger_based_flag: bit 2: Trigger based device flag

uint8_t reserved2: bit 3-4: Reserved for future use

uint8_t bthome_version: bit 5-7: BTHome Version

struct bthome_device_info_t::[anonymous] bit: Bit field representation of device info

uint8_t all: Byte representation of device info

Structures

struct bthome_report_t

BTHome report structure.

Public Members

uint8_t id: Object ID: One of the BTHome Sensor ID, Binary Sensor ID or Event ID

uint8_t len: Length of the data

uint8_t *data: Pointer to the data

struct bthome_reports_t

BTHome reports structure.

Public Members

uint8_t num_reports: Number of reports in the array

bthome_report_t report[BTHOME_REPORTS_MAX]: Array of reports

struct bthome_callbacks_t

BTHome callback functions.

Public Members

bthome_store_func_t store: Function pointer to store data

bthome_load_func_t load: Function pointer to load data

Macros

BTHOME_REPORTS_MAX

Type Definitions

typedef struct bthome_t *bthome_handle_t: bthome handle type

typedef void (*bthome_store_func_t)(bthome_handle_t handle, const char *key, const uint8_t *data, uint8_t len): BTHome store function.

typedef void (*bthome_load_func_t)(bthome_handle_t handle, const char *key, uint8_t *data, uint8_t len): BTHome load function.

Enumerations

enum bthome_sensor_id_t

BTHome sensor ID.

Values:

enumerator BTHOME_SENSOR_ID_PACKET

enumerator BTHOME_SENSOR_ID_BATTERY

enumerator BTHOME_SENSOR_ID_TEMPERATURE_PRECISE

enumerator BTHOME_SENSOR_ID_HUMIDITY_PRECISE

enumerator BTHOME_SENSOR_ID_PRESSURE

enumerator BTHOME_SENSOR_ID_ILLUMINANCE

enumerator BTHOME_SENSOR_ID_MASS

enumerator BTHOME_SENSOR_ID_MASSLB

enumerator BTHOME_SENSOR_ID_DEWPOINT

enumerator BTHOME_SENSOR_ID_COUNT

enumerator BTHOME_SENSOR_ID_ENERGY

enumerator BTHOME_SENSOR_ID_POWER

enumerator BTHOME_SENSOR_ID_VOLTAGE

enumerator BTHOME_SENSOR_ID_PM25

enumerator BTHOME_SENSOR_ID_PM10

enumerator BTHOME_SENSOR_ID_CO2

enumerator BTHOME_SENSOR_ID_TVOC

enumerator BTHOME_SENSOR_ID_MOISTURE_PRECISE

enumerator BTHOME_SENSOR_ID_HUMIDITY

enumerator BTHOME_SENSOR_ID_MOISTURE

enumerator BTHOME_SENSOR_ID_COUNT2

enumerator BTHOME_SENSOR_ID_COUNT4

enumerator BTHOME_SENSOR_ID_ROTATION

enumerator BTHOME_SENSOR_ID_DISTANCE

enumerator BTHOME_SENSOR_ID_DISTANCEM

enumerator BTHOME_SENSOR_ID_DURATION

enumerator BTHOME_SENSOR_ID_CURRENT

enumerator BTHOME_SENSOR_ID_SPD

enumerator BTHOME_SENSOR_ID_TEMPERATURE

enumerator BTHOME_SENSOR_ID_UV

enumerator BTHOME_SENSOR_ID_VOLUME1

enumerator BTHOME_SENSOR_ID_VOLUME2

enumerator BTHOME_SENSOR_ID_VOLUMEFR

enumerator BTHOME_SENSOR_ID_VOLTAGE1

enumerator BTHOME_SENSOR_ID_GAS

enumerator BTHOME_SENSOR_ID_GAS4

enumerator BTHOME_SENSOR_ID_ENERGY4

enumerator BTHOME_SENSOR_ID_VOLUME

enumerator BTHOME_SENSOR_ID_WATER

enumerator BTHOME_SENSOR_ID_TIMESTAMP

enumerator BTHOME_SENSOR_ID_ACCELERATION

enumerator BTHOME_SENSOR_ID_GYROSCOPE

enumerator BTHOME_SENSOR_ID_TEXT

enumerator BTHOME_SENSOR_ID_RAW

enumerator BTHOME_SENSOR_ID_VOLUME_STORAGE

enum bthome_bin_sensor_id_t

BTHome binary sensor ID.

Values:

enumerator BTHOME_BIN_SENSOR_ID_GENERIC

enumerator BTHOME_BIN_SENSOR_ID_POWER

enumerator BTHOME_BIN_SENSOR_ID_OPENING

enumerator BTHOME_BIN_SENSOR_ID_BATTERY

enumerator BTHOME_BIN_SENSOR_ID_BATTERY_CHARGING

enumerator BTHOME_BIN_SENSOR_ID_CARBON_MONOXIDE

enumerator BTHOME_BIN_SENSOR_ID_COLD

enumerator BTHOME_BIN_SENSOR_ID_CONNECTIVITY

enumerator BTHOME_BIN_SENSOR_ID_DOOR

enumerator BTHOME_BIN_SENSOR_ID_GARAGE_DOOR

enumerator BTHOME_BIN_SENSOR_ID_GAS

enumerator BTHOME_BIN_SENSOR_ID_HEAT

enumerator BTHOME_BIN_SENSOR_ID_LIGHT

enumerator BTHOME_BIN_SENSOR_ID_LOCK

enumerator BTHOME_BIN_SENSOR_ID_MOISTURE

enumerator BTHOME_BIN_SENSOR_ID_MOTION

enumerator BTHOME_BIN_SENSOR_ID_MOVING

enumerator BTHOME_BIN_SENSOR_ID_OCCUPANCY

enumerator BTHOME_BIN_SENSOR_ID_PLUG

enumerator BTHOME_BIN_SENSOR_ID_PRESENCE

enumerator BTHOME_BIN_SENSOR_ID_PROBLEM

enumerator BTHOME_BIN_SENSOR_ID_RUNNING

enumerator BTHOME_BIN_SENSOR_ID_SAFETY

enumerator BTHOME_BIN_SENSOR_ID_SMOKE

enumerator BTHOME_BIN_SENSOR_ID_SOUND

enumerator BTHOME_BIN_SENSOR_ID_TAMPER

enumerator BTHOME_BIN_SENSOR_ID_VIBRATION

enumerator BTHOME_BIN_SENSOR_ID_WINDOW

enum bthome_event_id_t

BTHome event ID.

Values:

enumerator BTHOME_EVENT_ID_BUTTON

enumerator BTHOME_EVENT_ID_DIMMER

提供有关此文档的反馈