BTHome Component

[中文]

The BTHome component implements the BTHome V2 protocol, supporting sensor data reporting, binary sensor data reporting, and event data reporting. This component supports both encrypted and non-encrypted modes, and can be seamlessly integrated with smart home platforms like Home Assistant.

BTHome Usage

Initialize BTHome:
- Use bthome_create() to create a BTHome instance
- Use bthome_register_callbacks() to register callback functions
- Use bthome_set_encrypt_key() to set encryption key (optional)
- Use bthome_set_peer_mac_addr() to set peer MAC address
Configuration Storage:
- Use settings_store() to store configuration
- Use settings_load() to load configuration
Parse Advertising Data:
- Use bthome_parse_adv_data() to parse advertising data
- Use bthome_free_reports() to free report data

Example Code

// Create BTHome instance
bthome_handle_t bthome_recv;
ESP_ERROR_CHECK(bthome_create(&bthome_recv));

// Register callback functions
bthome_callbacks_t callbacks = {
    .store = settings_store,
    .load = settings_load,
};
ESP_ERROR_CHECK(bthome_register_callbacks(bthome_recv, &callbacks));

// Set encryption key
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));

// Set peer MAC address
static const uint8_t peer_mac[] = {0x54, 0x48, 0xE6, 0x8F, 0x80, 0xA5};
ESP_ERROR_CHECK(bthome_set_peer_mac_addr(bthome_recv, peer_mac));

// Parse advertising data
bthome_reports_t *reports = bthome_parse_adv_data(bthome_recv, result.ble_adv, result.adv_data_len);
if (reports != NULL) {
    // Process report data
    for (int i = 0; i < reports->num_reports; i++) {
        // Process each report
    }
    bthome_free_reports(reports);
}

API Reference

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.

Parameters: handle – pointer to the bthome handle
Returns: esp_err_t ESP_OK: success others: fail

esp_err_t bthome_delete(bthome_handle_t handle)

Delete a BTHome object.

Parameters: handle – pointer to the bthome handle
Returns: 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

Parameters

handle – bthome handle
key – pointer to the key

Returns

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

Parameters

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

Returns

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

Parameters

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

Returns

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

Parameters

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

Returns

esp_err_t ESP_OK: success others: fail

esp_err_t bthome_load_params(bthome_handle_t handle)

load the parameters from the storage

Parameters: handle – pointer to the bthome handle
Returns: esp_err_t ESP_OK: success others: fail

void bthome_free_reports(bthome_reports_t *reports)

free the reports structure

Parameters: 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.

Parameters

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

Returns

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.

Parameters

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

Returns

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.

Parameters

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

Returns

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.

Parameters

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

Returns

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.

Parameters

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

Returns

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

Provide feedback about this document