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

3 Min. Lesezeit

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.

Zwei Arten, Bluetooth mit ESPHome zu nutzen: zuhören oder verbinden

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.

Ein ESP32-DevKit-Board

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_client legt das Gerät über seine MAC-Adresse an und gibt ihm eine id.
  • on_connect und on_disconnect führen Aktionen aus. Hier schreiben sie nur ins Log, Sie könnten aber ein Relais schalten.
  • Der ble_client-Sensor liest eine Characteristic. notify: true bittet das Gerät, Änderungen zu melden, und update_interval aktualisiert 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.

Das ESPHome-Dashboard beim Bearbeiten von ble-client.yaml

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.