ESPHome-Tutorial: einen ESP32 mit einem Bluetooth-Gerät verbinden (BLE-Client)

Nicht jedes Bluetooth-Gerät sendet seine Daten offen wie ein Xiaomi-Thermometer. Viele bleiben stumm, bis sich etwas mit ihnen verbindet: ein Brustgurt, ein Smart Lock, eine Lampe, ein Akkupack. Der ESP32 kann dieses Etwas sein, und ESPHome macht daraus eine kurze YAML-Datei.
Dieses Tutorial verbindet einen ESP32 mit einem beliebigen Bluetooth-Low-Energy-Gerät (BLE) und liest dessen Akkustand aus. Wenn das klappt, können Sie alles andere auch lesen.

Was Sie brauchen
- Ein ESP32 DevKit: das ESP32 DevKit oder das ESP32-S3 N16R8, wenn Sie mehrere Verbindungen planen.
- Ein BLE-Gerät mit dem Standard-Batteriedienst (viele haben ihn).
- Ein Smartphone mit einer BLE-Scanner-App wie nRF Connect, um das Gerät zu erkunden.

Zuhören oder verbinden?
- Zuhören (
esp32_ble_tracker): Das Gerät ruft seine Daten hinaus (Advertisements), der ESP32 hört sie einfach. Keine Kopplung, keine Batteriebelastung. So funktioniert das Mijia-Thermometer. - Verbinden (
ble_client): Der ESP32 baut eine Verbindung auf und fragt Werte ab, sogenannte Characteristics. Nötig, wenn das Gerät nur auf Anfrage antwortet.
Faustregel: Versuchen Sie zuerst das Zuhören. Verbinden Sie sich nur, wenn es sein muss.
Schritt 1: das Gerät erkunden
Öffnen Sie nRF Connect auf dem Smartphone, scannen Sie und verbinden Sie sich mit Ihrem Gerät. Sie sehen Services und Characteristics, jeweils mit einer UUID. Die Standard-UUIDs sind kurz:
| Was | Service | Characteristic |
|---|---|---|
| Akkustand | 180F |
2A19 |
| Herzfrequenz | 180D |
2A37 |
Notieren Sie auch die MAC-Adresse des Geräts. Manche Geräte erlauben nur eine Verbindung gleichzeitig, trennen Sie also das Smartphone, bevor Sie den ESP32 nutzen.
Schritt 2: die Konfiguration
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
So funktioniert es:
esp32_ble_tracker:ist immer nötig, auch für einen Client.ble_clientlegt das Gerät über seine MAC-Adresse an und gibt ihm eineid.on_connectundon_disconnectführen Aktionen aus. Hier schreiben sie nur ins Log, Sie könnten aber ein Relais schalten.- Der
ble_client-Sensor liest eine Characteristic.notify: truebittet das Gerät, Änderungen zu melden, undupdate_intervalaktualisiert den Wert zusätzlich.
Schritt 3: flashen und das Log beobachten
docker run --rm -p 6052:6052 -v "$PWD/config":/config esphome/esphome
Installieren Sie und öffnen Sie dann das Log. Sie sollten die Verbindungsmeldung und danach den Akkuwert sehen.

Fehlersuche
- Es verbindet sich nie: Das Gerät ist vielleicht außer Reichweite, schon mit Ihrem Smartphone verbunden oder verlangt eine Kopplung.
- Der Sensor bleibt leer: Prüfen Sie die UUIDs in nRF Connect. Manche Geräte nutzen eigene 128-Bit-UUIDs.
- Alles wird langsam: Eine BLE-Verbindung braucht RAM und Funkzeit. Halten Sie die Zahl verbundener Geräte klein und teilen Sie das Funkmodul vernünftig mit dem WLAN. Der ESP32-S3 mit mehr Speicher hilft.
- Kopplung nötig: Manche Geräte verlangen ein Bonding, das über diesen einfachen Aufbau hinausgeht.
Fazit
Sie kennen jetzt beide Bluetooth-Modi von ESPHome. Einen Akkustand zu lesen ist das „Hello World": Dasselbe Muster liest auch andere Characteristics. Um zu wissen, wer zu Hause ist, geht es weiter mit dem BLE-Anwesenheitsmelder.
Diese Konfiguration wurde mit esphome config geprüft, nicht an Ihrem Gerät getestet. Characteristics unterscheiden sich von Gerät zu Gerät.