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

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.

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.

É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_clientdéclare l'appareil par son adresse MAC et lui donne unid.on_connecteton_disconnectexécutent des actions. Ici elles écrivent simplement dans le log, mais vous pourriez commander un relais.- Le capteur
ble_clientlit une caractéristique.notify: truedemande à l'appareil de pousser les changements, etupdate_intervalrafraî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.

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.