ESPHome tutorial: connect an ESP32 to a Bluetooth device (BLE client)

3 min read

Not every Bluetooth gadget broadcasts its data like a Xiaomi thermometer. Many of them stay silent until something connects to them: a heart-rate belt, a smart lock, a lamp, a battery pack. The ESP32 can be that something, and ESPHome makes it a short YAML file.

This tutorial connects an ESP32 to any Bluetooth Low Energy (BLE) device and reads its battery level. Once that works, you know how to read anything else.

Two ways to use Bluetooth with ESPHome: listening or connecting

What you need

  • An ESP32 DevKit: ESP32 DevKit, or the ESP32-S3 N16R8 if you plan several connections.
  • A BLE device that exposes the standard battery service (many do).
  • A phone with a BLE scanner app such as nRF Connect, to explore the device.

An ESP32 DevKit board

Listening or connecting?

  • Listening (esp32_ble_tracker): the device shouts its data (adverts), the ESP32 just hears it. No pairing, no battery cost. This is how the Mijia thermometer works.
  • Connecting (ble_client): the ESP32 opens a link and asks for values, called characteristics. Needed when the device only answers on request.

Rule of thumb: try listening first. Connect only when you must.

Step 1: explore the device

Open nRF Connect on your phone, scan, and connect to your device. You will see services and characteristics, each with a UUID. The standard ones are short:

What Service Characteristic
Battery level 180F 2A19
Heart rate 180D 2A37

Note the device's MAC address too. Some devices accept only one connection at a time, so disconnect your phone before using the ESP32.

Step 2: the configuration

esphome:
  name: ble-client

esp32:
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

esp32_ble_tracker:

ble_client:
  - mac_address: "AA:BB:CC:DD:EE:FF"
    id: my_ble_device
    on_connect:
      then:
        - logger.log: "Connected to the BLE device"
    on_disconnect:
      then:
        - logger.log: "Disconnected from the BLE device"

sensor:
  - platform: ble_client
    type: characteristic
    ble_client_id: my_ble_device
    name: "BLE device battery"
    service_uuid: "180F"
    characteristic_uuid: "2A19"
    notify: true
    update_interval: 60s
    unit_of_measurement: "%"
    device_class: battery

How it works:

  • esp32_ble_tracker: is always required, even for a client.
  • ble_client declares the device by MAC address and gives it an id.
  • on_connect and on_disconnect run actions. Here they just write to the log, but you could switch a relay.
  • The ble_client sensor reads one characteristic. notify: true asks the device to push changes, and update_interval refreshes the value too.

Step 3: flash and watch the logs

docker run --rm -p 6052:6052 -v "$PWD/config":/config esphome/esphome

Install, then open the logs. You should see the connection message, then the battery value.

The ESPHome dashboard editing ble-client.yaml

Troubleshooting

  • It never connects: the device may be out of range, already connected to your phone, or asking for pairing.
  • The sensor stays empty: check the UUIDs in nRF Connect. Some devices use 128-bit custom UUIDs.
  • Everything gets slow: a BLE connection uses RAM and radio time. Keep the number of connected devices low, and share the radio with Wi-Fi sensibly. The ESP32-S3 with more memory helps.
  • Pairing needed: some devices require bonding, which is outside this simple setup.

Conclusion

You now know the two Bluetooth modes of ESPHome. Reading a battery is the "hello world": the same pattern reads other characteristics. To know who is home, continue with the BLE presence detector.

This configuration was validated with esphome config, not tested on your device. Characteristics vary from device to device.