Tutoriel ESPHome : connecter un ESP32 à un appareil Bluetooth (client BLE)

3 min de lecture

Tous les gadgets Bluetooth ne diffusent pas leurs données comme un thermomètre Xiaomi. Beaucoup restent silencieux tant que quelque chose ne s'y connecte pas : une ceinture cardiaque, une serrure connectée, une lampe, une batterie. L'ESP32 peut être ce quelque chose, et ESPHome en fait un court fichier YAML.

Ce tutoriel connecte un ESP32 à n'importe quel appareil Bluetooth Low Energy (BLE) et lit son niveau de batterie. Une fois que ça marche, vous savez lire tout le reste.

Deux façons d'utiliser le Bluetooth avec ESPHome : écouter ou se connecter

Ce qu'il vous faut

  • Une carte ESP32 DevKit : l'ESP32 DevKit, ou l'ESP32-S3 N16R8 si vous prévoyez plusieurs connexions.
  • Un appareil BLE qui expose le service batterie standard (beaucoup le font).
  • Un téléphone avec une application de scan BLE comme nRF Connect, pour explorer l'appareil.

Une carte ESP32 DevKit

Écouter ou se connecter ?

  • Écouter (esp32_ble_tracker) : l'appareil crie ses données (annonces), l'ESP32 les entend simplement. Pas d'association, pas de coût en batterie. C'est ainsi que fonctionne le thermomètre Mijia.
  • Se connecter (ble_client) : l'ESP32 ouvre une liaison et demande des valeurs, appelées caractéristiques. Nécessaire quand l'appareil ne répond que sur demande.

Règle simple : essayez d'abord d'écouter. Ne vous connectez que si vous y êtes obligé.

Étape 1 : explorer l'appareil

Ouvrez nRF Connect sur votre téléphone, scannez et connectez-vous à votre appareil. Vous verrez des services et des caractéristiques, chacun avec un UUID. Les standards sont courts :

Quoi Service Caractéristique
Niveau de batterie 180F 2A19
Fréquence cardiaque 180D 2A37

Notez aussi l'adresse MAC de l'appareil. Certains appareils n'acceptent qu'une connexion à la fois : déconnectez votre téléphone avant d'utiliser l'ESP32.

Étape 2 : la 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

Comment ça marche :

  • esp32_ble_tracker: est toujours requis, même pour un client.
  • ble_client déclare l'appareil par son adresse MAC et lui donne un id.
  • on_connect et on_disconnect exécutent des actions. Ici elles écrivent simplement dans le log, mais vous pourriez commander un relais.
  • Le capteur ble_client lit une caractéristique. notify: true demande à l'appareil de pousser les changements, et update_interval rafraîchit aussi la valeur.

Étape 3 : flasher et regarder les logs

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

Installez, puis ouvrez les logs. Vous devriez voir le message de connexion, puis la valeur de la batterie.

Le tableau de bord ESPHome en train d'éditer ble-client.yaml

Dépannage

  • Il ne se connecte jamais : l'appareil est peut-être hors de portée, déjà connecté à votre téléphone, ou demande une association.
  • Le capteur reste vide : vérifiez les UUID dans nRF Connect. Certains appareils utilisent des UUID personnalisés de 128 bits.
  • Tout devient lent : une connexion BLE consomme de la RAM et du temps radio. Gardez peu d'appareils connectés et partagez raisonnablement la radio avec le Wi-Fi. L'ESP32-S3, avec plus de mémoire, aide.
  • Association nécessaire : certains appareils exigent un appairage, ce qui dépasse cette configuration simple.

Conclusion

Vous connaissez maintenant les deux modes Bluetooth d'ESPHome. Lire une batterie est le « hello world » : le même schéma lit d'autres caractéristiques. Pour savoir qui est à la maison, continuez avec le détecteur de présence BLE.

Cette configuration a été validée avec esphome config, pas testée sur votre appareil. Les caractéristiques varient d'un appareil à l'autre.