Skip to content
BTHome for ESPHome (nRF52 fork)

Basic Setup

Configuration Options

Section titled “Configuration Options”

The BTHome component supports the following configuration options:

bthome:
  min_interval: 1s
  max_interval: 1s
  tx_power: 0
  ble_stack: bluedroid  # Optional, ESP32 only: bluedroid or nimble
  trigger_based: false  # Optional, for event-driven devices
  encryption_key: "your_32_hex_char_key"  # Optional
  sensors:
    # ... sensor configuration
  binary_sensors:
    # ... binary sensor configuration

Options Reference

Section titled “Options Reference”
Option Type Default Description
min_interval Time 1s Minimum advertising interval (1s - 10240ms)
max_interval Time 1s Maximum advertising interval (1s - 10240ms)
tx_power Integer 0 Transmit power in dBm
ble_stack String bluedroid ESP32 only: bluedroid or nimble (see BTHome Component)
trigger_based Boolean false Mark device as trigger-based (event-driven)
encryption_key String - Optional 16-byte encryption key (32 hex chars)
sensors List - List of sensor measurements to broadcast
binary_sensors List - List of binary sensor measurements to broadcast

Advertising Interval

Section titled “Advertising Interval”

The advertising interval controls how often your device broadcasts sensor data:

bthome:
  min_interval: 5s   # Broadcast at least every 5 seconds
  max_interval: 10s  # But no more than every 10 seconds

TX Power

Section titled “TX Power”

Transmit power affects range and battery consumption:

ESP32 TX Power Levels

Section titled “ESP32 TX Power Levels”
dBm Description
-12 Minimum power, shortest range
-9 Low power
-6 Below default
-3 Slightly below default
0 Default
3 Above default
6 High power
9 Maximum power, longest range

nRF52 TX Power Levels

Section titled “nRF52 TX Power Levels”
dBm Description
-40 Ultra low power
-20 Very low power
-16, -12, -8, -4 Low power options
0 Default
2, 3, 4, 5, 6, 7, 8 High power options

Example:

bthome:
  tx_power: 4  # Increase range

Trigger-Based Devices

Section titled “Trigger-Based Devices”

Set trigger_based: true for devices that only send data on events rather than continuously. This tells Home Assistant not to expect regular updates from the device.

Use cases for trigger-based mode:

  • Push buttons - Only broadcast when pressed
  • Remote controls - Only broadcast on button press
  • Door bells - Only broadcast when activated
  • Event-driven sensors - Any sensor that reports discrete events rather than continuous measurements
bthome:
  trigger_based: true
  binary_sensors:
    - type: generic_boolean
      id: button_press
      advertise_immediately: true

Sensor Configuration

Section titled “Sensor Configuration”

Each sensor measurement requires:

Option Required Description
type Yes BTHome sensor type (see Sensor Types)
id Yes Reference to an ESPHome sensor
advertise_immediately No Broadcast immediately on value change (default: false) 
bthome:
  sensors:
    - type: temperature
      id: my_temp_sensor
      advertise_immediately: false
    - type: humidity
      id: my_humidity_sensor
    - type: battery
      id: battery_percent

Binary Sensor Configuration

Section titled “Binary Sensor Configuration”

Each binary sensor measurement requires:

Option Required Description
type Yes BTHome binary sensor type (see Binary Sensor Types)
id Yes Reference to an ESPHome binary sensor
advertise_immediately No Broadcast immediately on state change (default: false) 
bthome:
  binary_sensors:
    - type: motion
      id: pir_motion
      advertise_immediately: true  # Important for motion sensors!
    - type: door
      id: door_contact
      advertise_immediately: true

Next Steps

Section titled “Next Steps”