bthome_ble_receiver.rst

ESP32 BTHome Receiver

BTHome is an energy efficient but flexible BLE (Bluetooth Low Energy) format for devices to broadcast their sensor data and button presses. Devices can run over a year on a single battery. It allows data encryption and is supported by popular home automation platforms, like Home Assistant, out of the box.

This component implements local reception and decoding without the need of a central hub.

Note: as for now this component is limited to V1 and V2 unencryted formats. Encryption support might be implemented later on.

# Example configuration entry
external_components:
  - source: github://afarago/esphome_component_bthome

esp32_ble_tracker:

bthome_ble_receiver:
  dump: unmatched
  devices:
    - mac_address: 11:22:33:44:55:55
      name_prefix: BTHome TestDevice
      expected_remote_passkey: 0x1234
      dump: all

sensor:
  - platform: bthome_ble_receiver
    mac_address: 11:22:33:44:55:55
    sensors:
      - measurement_type: temperature
        name: Temperature
      - measurement_type: humidity
        name: Humidity
      - measurement_type: 0x02
        name: Temperature_Second
        accuracy_decimals: 2
        unit_of_measurement: °C

  - platform: bthome_ble_receiver
    mac_address: 22:33:44:55:55:66
    sensors:
      - measurement_type: temperature
        name: BTHome Garage Temperature

binary_sensor:
  - platform: bthome_ble_receiver
    mac_address: 11:22:33:44:55:55
    name_prefix: BTHome Garage
    sensors:
      - measurement_type: opening
        name: Opening

Component/Hub

The bthome_ble_receiver component creates a global hub so that you can track bluetooth low energy devices using your ESP32 node over the BTHome protocol using both v1 and v2 protocols.

The component depends on the esp32_ble_tracker component which needs to be added to the configuration.

The bthome receiver component is an internal model that acts as a central reception and dispatcher hub to which bthome virtual devices and sensors are connected to.

Configuration variables:

• dump (Optional): Decode and dumpincoming remote readings codes in the logs (at log.level=DEBUG) for any device.
  • all: Decode and dump all readings.
  • unmatched: Decode and dump readings that are not mapped in configuration.
  • none: (default) Decode but do not dump any readings.
• id (Optional): Manually specify the ID for this Hub.
• devices (Optional): List of remote devices connected to this hub. Any devices not specified here, but only in sensor sections will use default settings.
  • mac_address (Required, mac-address): The address of the sensor.
  • name_prefix (Optional): Device name to append before any sensor name as a prefix.
  • dump (Optional): Decode and dump incoming remote readings codes in the logs (at log.level=DEBUG) for this device.

Sensor and Binary Sensor as virtual device

The bthome sensor allows you use a sensor to display received measurement from a remote BTHome device. First, you need to define a :ref:`bthome hub component <bthome-component>`.

The bthome sensor component (or "device") is an internal model that acts as a central reception and dispatcher hub for a specific remote device identified by a mac_address to which bthome sensors are connected to.

To initialize a sensor, first supply mac_address to identify the remote BTHome device.

# Example configuration entry
bthome_ble_receiver:

# Individual sensors
sensor:
  - platform: bthome_ble_receiver
    mac_address: 11:22:33:44:55:55
    sensors:
      - measurement_type: temperature
        name: Temperature
      - measurement_type: humidity
        name: Humidity
      - measurement_type: 0x02
        name: Temperature_Second
        accuracy_decimals: 2
        unit_of_measurement: °C

Configuration variables:

• mac_address (Required, mac-address): The address of the sensor.

• sensors (Required): List of remote sensor connected to this virtual device.

  • name (Optional): The name for the sensor. At least one of id and name must be specified.

  • measurement_type (Required, int or string): Measurement type as defined in BTHome format specification either as a string or a numeric value. If selected by name (string) the accuracy and unit of measurement are automatically defaulted to the correct values.

    Measurement type further details to be taken into account.

See Also

• BTHome by Ernst Klamer, Victor, Paulus Schoutsen.