From d8990664eac9a07cb6396651d73cd4f865a81638 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Nov 2025 04:27:42 +0000 Subject: [PATCH 1/4] Add BTHome BLE component documentation This adds comprehensive documentation for the new BTHome v2 BLE component that enables ESP32 devices to broadcast sensor data using the BTHome protocol. The documentation covers: - Complete configuration options including sensors, binary sensors, and encryption - All supported sensor types (temperature, humidity, battery, etc.) - All supported binary sensor types (motion, door, window, etc.) - Detailed examples showing basic and advanced usage - Integration with Home Assistant - Explanation of immediate advertising for event-driven sensors Related to esphome/esphome#11962 --- content/components/_index.md | 1 + content/components/bthome.md | 215 +++++++++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+) create mode 100644 content/components/bthome.md diff --git a/content/components/_index.md b/content/components/_index.md index b00c2c89ff..f0e2463b3e 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -117,6 +117,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning ## Bluetooth/BLE {{< imgtable >}} +"BTHome BLE","components/bthome","bluetooth.svg","dark-invert" "ESP32 BLE Beacon","components/esp32_ble_beacon","bluetooth.svg","dark-invert" "ESP32 BLE Client","components/ble_client","bluetooth.svg","dark-invert" "ESP32 BLE Tracker","components/esp32_ble_tracker","bluetooth.svg","dark-invert" diff --git a/content/components/bthome.md b/content/components/bthome.md new file mode 100644 index 0000000000..a454b0e0b6 --- /dev/null +++ b/content/components/bthome.md @@ -0,0 +1,215 @@ +--- +description: "Instructions for setting up BTHome BLE sensor broadcasting on ESP32 devices." +title: "BTHome BLE" +params: + seo: + description: Instructions for setting up BTHome v2 BLE sensor broadcasting on ESP32 devices. + image: bluetooth.svg +--- + +The `bthome` component enables your ESP32 device to broadcast sensor data using the [BTHome v2](https://bthome.io/) Bluetooth Low Energy (BLE) protocol. This allows your ESP32 to function as a battery-powered BLE sensor that can be automatically discovered and integrated with Home Assistant and other BTHome-compatible receivers. + +BTHome is a standardized format for transmitting sensor data over BLE advertising packets, providing efficient, low-power communication for IoT devices. + +> [!WARNING] +> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. +> +> **Crashes are likely to occur** if you include too many additional components in your device's +> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other +> audio components are most likely to cause issues. + +> [!NOTE] +> This component requires the {{< docref "esp32_ble/" >}} component to be configured. The BTHome component will automatically enable BLE advertising. + +```yaml +# Example configuration entry +esp32_ble: + +bthome: + sensors: + - type: temperature + id: my_temperature + - type: humidity + id: my_humidity + - type: battery + id: my_battery + binary_sensors: + - type: motion + id: my_motion + advertise_immediately: true +``` + +## Configuration variables + +- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID for code generation. +- **esp32_ble_id** (*Optional*, [ID](/guides/configuration-types#id)): The ID of the {{< docref "esp32_ble/" >}} component. Defaults to the only `esp32_ble` component if only one is configured. + +- **min_interval** (*Optional*, [Time](/guides/configuration-types#time)): The minimum BLE advertising interval in milliseconds. Setting this less than `max_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. + +- **max_interval** (*Optional*, [Time](/guides/configuration-types#time)): The maximum BLE advertising interval in milliseconds. Setting this greater than `min_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. + +- **tx_power** (*Optional*, int): The transmit power of the BLE advertisements in dBm. One of -12, -9, -6, -3, 0, 3, 6, 9. Defaults to `3dBm`. + +- **encryption_key** (*Optional*, string): A 32-character hexadecimal string (16 bytes) used for AES-CCM encryption of the BLE advertisements. Spaces and dashes in the key are ignored. When set, all sensor data will be encrypted. Example: `"0123456789ABCDEF0123456789ABCDEF"` or `"01-23-45-67-89-AB-CD-EF-01-23-45-67-89-AB-CD-EF"`. + +- **sensors** (*Optional*, list): A list of sensors to broadcast. Each sensor requires: + - **type** (**Required**, string): The BTHome sensor type (see [Supported Sensor Types](#supported-sensor-types)). + - **id** (**Required**, [ID](/guides/configuration-types#id)): The ID of an existing sensor component. + - **advertise_immediately** (*Optional*, boolean): When set to `true`, the component will immediately broadcast an advertisement when this sensor's value changes, rather than waiting for the next scheduled advertisement. Useful for time-sensitive sensors. Defaults to `false`. + +- **binary_sensors** (*Optional*, list): A list of binary sensors to broadcast. Each binary sensor requires: + - **type** (**Required**, string): The BTHome binary sensor type (see [Supported Binary Sensor Types](#supported-binary-sensor-types)). + - **id** (**Required**, [ID](/guides/configuration-types#id)): The ID of an existing binary sensor component. + - **advertise_immediately** (*Optional*, boolean): When set to `true`, the component will immediately broadcast an advertisement when this binary sensor's state changes. Particularly useful for motion detectors, door sensors, and other event-driven sensors. Defaults to `false`. + +## Supported Sensor Types + +The following sensor types are supported by the BTHome protocol. Type names are case-insensitive: + +- `battery` - Battery level (%) +- `temperature` - Temperature (°C) +- `humidity` - Humidity (%) +- `pressure` - Pressure (hPa) +- `illuminance` - Illuminance (lux) +- `weight` - Weight (kg) +- `dewpoint` - Dew point (°C) +- `energy` - Energy (kWh) +- `power` - Power (W) +- `voltage` - Voltage (V) +- `pm2_5` - Particulate Matter 2.5 (µg/m³) +- `pm10` - Particulate Matter 10 (µg/m³) +- `co2` - Carbon Dioxide (ppm) +- `tvoc` - Total Volatile Organic Compounds (µg/m³) +- `moisture` - Moisture (%) +- `current` - Current (A) +- `speed` - Speed (m/s) +- `timestamp` - Timestamp (seconds since epoch) + +## Supported Binary Sensor Types + +The following binary sensor types are supported. Type names are case-insensitive: + +- `generic` - Generic on/off +- `power` - Power state +- `battery_low` - Low battery warning +- `battery_charging` - Battery charging status +- `carbon_monoxide` - Carbon monoxide detected +- `cold` - Cold temperature detected +- `door` - Door open/closed +- `garage_door` - Garage door open/closed +- `light` - Light detected +- `lock` - Lock state +- `motion` - Motion detected +- `occupancy` - Occupancy detected +- `smoke` - Smoke detected +- `window` - Window open/closed + +## Complete Example + +```yaml +# Complete example with multiple sensors and encryption +esp32_ble: + +bthome: + # Optional encryption for secure communication + encryption_key: "0123456789ABCDEF0123456789ABCDEF" + + # Adjust advertising intervals + min_interval: 1s + max_interval: 1s + tx_power: 3dBm + + sensors: + - type: temperature + id: room_temperature + - type: humidity + id: room_humidity + - type: battery + id: device_battery + - type: pressure + id: barometric_pressure + - type: illuminance + id: light_level + + binary_sensors: + - type: motion + id: pir_sensor + advertise_immediately: true # Broadcast immediately on motion + - type: door + id: door_sensor + advertise_immediately: true # Broadcast immediately on door state change + - type: battery_low + id: low_battery_alert + +# Example sensor definitions +sensor: + - platform: bme280 + temperature: + name: "Room Temperature" + id: room_temperature + humidity: + name: "Room Humidity" + id: room_humidity + pressure: + name: "Barometric Pressure" + id: barometric_pressure + + - platform: adc + pin: GPIO34 + name: "Device Battery" + id: device_battery + filters: + - multiply: 0.048828125 # Convert to percentage + + - platform: bh1750 + name: "Light Level" + id: light_level + +binary_sensor: + - platform: gpio + pin: GPIO5 + name: "PIR Sensor" + id: pir_sensor + device_class: motion + + - platform: gpio + pin: GPIO4 + name: "Door Sensor" + id: door_sensor + device_class: door + + - platform: template + name: "Low Battery Alert" + id: low_battery_alert + lambda: |- + return id(device_battery).state < 20.0; +``` + +## How It Works + +The BTHome component periodically broadcasts BLE advertisements containing your sensor data in a standardized format that can be received by compatible devices like Home Assistant. Here's how it operates: + +1. **Regular Broadcasts**: The component broadcasts all configured sensor values at the interval specified by `min_interval` and `max_interval`. + +2. **Immediate Updates**: When `advertise_immediately` is enabled for a sensor, value changes trigger an instant broadcast instead of waiting for the next scheduled interval. This is ideal for event-driven sensors like motion detectors or door sensors. + +3. **Packet Cycling**: If you have many sensors and the data doesn't fit in a single BLE advertisement packet (31-byte limit), the component automatically cycles through multiple packets. + +4. **Encryption**: When an `encryption_key` is provided, all sensor data is encrypted using AES-CCM encryption, ensuring secure transmission. Home Assistant and other receivers will need the same encryption key to decrypt the data. + +5. **Advertisement Size**: Each BLE advertisement is limited to 31 bytes total. Without encryption, this provides 23 bytes for sensor data. With encryption, only 15 bytes are available due to the encryption overhead (counter and message integrity code). + +## Integration with Home Assistant + +Home Assistant will automatically discover BTHome devices when the [Bluetooth](/integrations/bluetooth/) integration is enabled. The sensor data will appear as entities in Home Assistant without any additional configuration required. + +If you've configured encryption, you'll need to provide the same encryption key in Home Assistant when adding the device. + +## See Also + +- {{< docref "esp32_ble/" >}} +- {{< docref "esp32_ble_beacon/" >}} +- {{< docref "esp32_ble_tracker/" >}} +- {{< docref "bluetooth_proxy/" >}} +- [BTHome Protocol Specification](https://bthome.io/) +- {{< apiref "bthome/bthome.h" "bthome/bthome.h" >}} From 6cb47dd2ccad4a0e912f940249a7690cec65cb7c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Nov 2025 09:29:39 +0000 Subject: [PATCH 2/4] Use standard markdown links instead of docref shortcodes - Replace docref shortcodes with standard markdown links - Add full domain to external Home Assistant Bluetooth link - Replace apiref shortcode with direct API reference link --- content/components/bthome.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/components/bthome.md b/content/components/bthome.md index a454b0e0b6..413722e938 100644 --- a/content/components/bthome.md +++ b/content/components/bthome.md @@ -15,11 +15,11 @@ BTHome is a standardized format for transmitting sensor data over BLE advertisin > The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. > > **Crashes are likely to occur** if you include too many additional components in your device's -> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other +> configuration. Memory-intensive components such as [Voice Assistant](/components/voice_assistant) and other > audio components are most likely to cause issues. > [!NOTE] -> This component requires the {{< docref "esp32_ble/" >}} component to be configured. The BTHome component will automatically enable BLE advertising. +> This component requires the [ESP32 BLE](/components/esp32_ble) component to be configured. The BTHome component will automatically enable BLE advertising. ```yaml # Example configuration entry @@ -42,7 +42,7 @@ bthome: ## Configuration variables - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID for code generation. -- **esp32_ble_id** (*Optional*, [ID](/guides/configuration-types#id)): The ID of the {{< docref "esp32_ble/" >}} component. Defaults to the only `esp32_ble` component if only one is configured. +- **esp32_ble_id** (*Optional*, [ID](/guides/configuration-types#id)): The ID of the [ESP32 BLE](/components/esp32_ble) component. Defaults to the only `esp32_ble` component if only one is configured. - **min_interval** (*Optional*, [Time](/guides/configuration-types#time)): The minimum BLE advertising interval in milliseconds. Setting this less than `max_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. @@ -201,15 +201,15 @@ The BTHome component periodically broadcasts BLE advertisements containing your ## Integration with Home Assistant -Home Assistant will automatically discover BTHome devices when the [Bluetooth](/integrations/bluetooth/) integration is enabled. The sensor data will appear as entities in Home Assistant without any additional configuration required. +Home Assistant will automatically discover BTHome devices when the [Bluetooth](https://www.home-assistant.io/integrations/bluetooth/) integration is enabled. The sensor data will appear as entities in Home Assistant without any additional configuration required. If you've configured encryption, you'll need to provide the same encryption key in Home Assistant when adding the device. ## See Also -- {{< docref "esp32_ble/" >}} -- {{< docref "esp32_ble_beacon/" >}} -- {{< docref "esp32_ble_tracker/" >}} -- {{< docref "bluetooth_proxy/" >}} +- [ESP32 BLE](/components/esp32_ble) +- [ESP32 BLE Beacon](/components/esp32_ble_beacon) +- [ESP32 BLE Tracker](/components/esp32_ble_tracker) +- [Bluetooth Proxy](/components/bluetooth_proxy) - [BTHome Protocol Specification](https://bthome.io/) -- {{< apiref "bthome/bthome.h" "bthome/bthome.h" >}} +- [API Reference](https://esphome.io/api/bthome_2bthome_8h) From 33d1c5fc5ae1736c21dcf8a59a64bd39f67924ab Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Nov 2025 09:37:23 +0000 Subject: [PATCH 3/4] Keep apiref shortcode for API reference link --- content/components/bthome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/bthome.md b/content/components/bthome.md index 413722e938..23687b300d 100644 --- a/content/components/bthome.md +++ b/content/components/bthome.md @@ -212,4 +212,4 @@ If you've configured encryption, you'll need to provide the same encryption key - [ESP32 BLE Tracker](/components/esp32_ble_tracker) - [Bluetooth Proxy](/components/bluetooth_proxy) - [BTHome Protocol Specification](https://bthome.io/) -- [API Reference](https://esphome.io/api/bthome_2bthome_8h) +- {{< apiref "bthome/bthome.h" "bthome/bthome.h" >}} From ebc024c04c39af938c1dbd6de85f60698e1ba252 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Nov 2025 09:42:51 +0000 Subject: [PATCH 4/4] Fix markdownlint: use 1. for all ordered list items --- content/components/bthome.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/components/bthome.md b/content/components/bthome.md index 23687b300d..cf5adb3a6e 100644 --- a/content/components/bthome.md +++ b/content/components/bthome.md @@ -191,13 +191,13 @@ The BTHome component periodically broadcasts BLE advertisements containing your 1. **Regular Broadcasts**: The component broadcasts all configured sensor values at the interval specified by `min_interval` and `max_interval`. -2. **Immediate Updates**: When `advertise_immediately` is enabled for a sensor, value changes trigger an instant broadcast instead of waiting for the next scheduled interval. This is ideal for event-driven sensors like motion detectors or door sensors. +1. **Immediate Updates**: When `advertise_immediately` is enabled for a sensor, value changes trigger an instant broadcast instead of waiting for the next scheduled interval. This is ideal for event-driven sensors like motion detectors or door sensors. -3. **Packet Cycling**: If you have many sensors and the data doesn't fit in a single BLE advertisement packet (31-byte limit), the component automatically cycles through multiple packets. +1. **Packet Cycling**: If you have many sensors and the data doesn't fit in a single BLE advertisement packet (31-byte limit), the component automatically cycles through multiple packets. -4. **Encryption**: When an `encryption_key` is provided, all sensor data is encrypted using AES-CCM encryption, ensuring secure transmission. Home Assistant and other receivers will need the same encryption key to decrypt the data. +1. **Encryption**: When an `encryption_key` is provided, all sensor data is encrypted using AES-CCM encryption, ensuring secure transmission. Home Assistant and other receivers will need the same encryption key to decrypt the data. -5. **Advertisement Size**: Each BLE advertisement is limited to 31 bytes total. Without encryption, this provides 23 bytes for sensor data. With encryption, only 15 bytes are available due to the encryption overhead (counter and message integrity code). +1. **Advertisement Size**: Each BLE advertisement is limited to 31 bytes total. Without encryption, this provides 23 bytes for sensor data. With encryption, only 15 bytes are available due to the encryption overhead (counter and message integrity code). ## Integration with Home Assistant