API REST

Interroger et piloter le capteur directement en HTTP, pour scripts et autres systèmes

En plus de l'interface web, chaque capteur Eco dispose d'une API REST. Elle permet de lire des mesures et de commuter ou régler des éléments directement via l'adresse IP du capteur, sans cloud et sans Home Assistant. Tout système capable d'envoyer des requêtes HTTP peut l'utiliser : scripts (curl, Python), Node-RED, ioBroker, openHAB, FHEM et bien d'autres.

L'API fait partie d'ESPhome et est intégrée à chaque capteur Eco, il n'y a rien à activer. La page web du capteur l'utilise elle aussi.

Quelle interface pour quoi ?

API REST API Home Assistant ecosensors.cloud
Pour vos propres scripts et tout système Home Assistant tableau de bord, historiques, notifications
Portée réseau local uniquement réseau local uniquement de n'importe où
Protection mot de passe d'accès, non chiffré (http) clé propre, chiffré votre compte

Prérequis

  • Le système qui interroge le capteur se trouve dans le même réseau que le capteur.
  • Vous connaissez l'adresse du capteur (nom ou adresse IP, voir Trouver le capteur). Configurez dans le routeur une adresse IP fixe pour le capteur, sinon votre intégration ne fonctionne plus dès que le routeur attribue une nouvelle adresse. Les exemples ci-dessous utilisent 192.168.1.95.
  • Les identifiants sont les mêmes que pour l'interface web : utilisateur admin et le mot de passe du capteur. L'API demande une authentification HTTP (appelée « Digest » dans ESPhome). Sur l'EcoMBR1, aucun mot de passe n'est défini en usine, l'API n'en demande donc pas non plus : définissez quand même un mot de passe d'accès.

Structure d'une requête

Chaque valeur et chaque commande d'un capteur est une entité avec une adresse fixe :

http://<adresse>/<type>/<nom>

Le nom s'écrit exactement comme le capteur le connaît (en anglais, p. ex. Grid Frequency). Écrivez les espaces %20, donc Grid%20Frequency. Les entités de votre capteur sont indiquées par le flux d'événements. Le type indique la nature de l'entité :

Type Signification Exemple value dans la réponse
sensor mesure Grid Frequency nombre
binary_sensor état à deux valeurs Relay Override true / false
text_sensor texte Tibber Price Level texte
switch interrupteur Relay 1 true / false
number valeur numérique réglable Grid Relay ON nombre sous forme de texte, p. ex. "-500"
button déclenche une action Restart (pas de réponse avec valeur)

Les entités disponibles dépendent du capteur ; les exemples ici viennent de l'EcoMBR1.

Lire des valeurs

Une valeur se lit avec une simple requête GET, dans un navigateur comme avec curl :

curl http://192.168.1.95/sensor/Grid%20Frequency
{"id":"sensor/Grid Frequency","value":50.01,"state":"50.0 Hz"}

value est la valeur à traiter, state la même valeur sous forme de texte avec son unité, comme l'affiche l'interface web. Autres exemples :

curl http://192.168.1.95/switch/Relay%201
# {"id":"switch/Relay 1","value":false,"state":"OFF"}

curl http://192.168.1.95/text_sensor/Tibber%20Price%20Level
# {"id":"text_sensor/Tibber Price Level","value":"EXPENSIVE","state":"EXPENSIVE"}

Si un mot de passe d'accès est défini, transmettez les identifiants. --anyauth laisse curl choisir lui-même la méthode d'authentification :

curl --anyauth -u admin:VotreMotDePasse http://192.168.1.95/sensor/Grid%20Frequency

Commuter et régler

Tout ce qui modifie quelque chose est une requête POST. L'action se place à la fin de l'adresse :

# Interrupteur : activer, désactiver, basculer
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/turn_on
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/turn_off
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/toggle

# Définir une valeur numérique (ici : seuil d'enclenchement de la commande par puissance réseau)
curl -X POST -d '' "http://192.168.1.95/number/Grid%20Relay%20ON/set?value=-500"

# Appuyer sur un bouton (ici : redémarrage)
curl -X POST -d '' http://192.168.1.95/button/Restart/press

La réponse est 200 sans contenu ; lisez le nouvel état avec GET comme ci-dessus. Le -d '' est important : le capteur rejette une requête POST sans contenu et sans indication de longueur avec l'erreur 411. D'autres outils ont besoin de la même chose : une requête vide avec Content-Length: 0.

Sur l'EcoMBR1, le relais ne peut être commuté à la main que tant qu'aucune commande (puissance réseau, Tibber) n'est activée, voir Régler le relais. Une commande activée décide elle-même du relais.

Toutes les valeurs et mises à jour en direct

Il n'existe pas d'adresse distincte listant toutes les entités. À la place, le capteur fournit sous /events un flux d'événements (Server-Sent Events) : juste après la connexion, il envoie toutes les entités avec leur valeur actuelle, puis chaque modification immédiatement.

curl -N http://192.168.1.95/events
event: state
data: {"id":"sensor/Phase A Voltage","domain":"sensor","name":"Phase A Voltage","value":234,"state":"234.0 V","uom":"V", ...}

Le champ id est exactement la partie à ajouter à l'adresse du capteur. Vous savez ainsi quelles entités existent et recevez les modifications sans interrogation permanente. Si vous n'avez besoin d'une valeur que de temps en temps, interrogez-la simplement régulièrement avec GET.

Un capteur est un petit microcontrôleur et ne supporte que peu de connexions simultanées. N'interrogez pas plus vite que toutes les quelques secondes et fermez un flux d'événements dès que vous n'en avez plus besoin.

Exemples pour vos propres applications

Python (avec la bibliothèque requests) :

import requests
from requests.auth import HTTPDigestAuth

auth = HTTPDigestAuth("admin", "VotreMotDePasse")   # à omettre si le capteur n'a pas de mot de passe
base = "http://192.168.1.95"

puissance = requests.get(f"{base}/sensor/Grid%20Active%20Power", auth=auth, timeout=5).json()["value"]
print(puissance, "W")

if puissance < -500:   # injection : relais activé
    requests.post(f"{base}/switch/Relay%201/turn_on", data="", auth=auth, timeout=5)

Node-RED, ioBroker, openHAB et systèmes similaires : il vous faut un bloc qui envoie des requêtes HTTP (dans Node-RED le nœud http request, nommé de façon similaire ailleurs), avec authentification Digest si un mot de passe est défini. Pour les valeurs, saisissez l'adresse GET et lisez le champ value de la réponse JSON. Pour commuter, envoyez une requête POST à l'adresse se terminant par turn_on, turn_off ou toggle.

Sécurité

Sans mot de passe d'accès, toute personne sur votre WiFi peut lire les valeurs et commander le capteur (p. ex. commuter le relais). La connexion n'est pas chiffrée (http) : le mot de passe ne circule pas en clair sur le réseau, mais un attaquant déterminé dans le même réseau n'en est pas empêché.

  • Ne rendez pas l'API accessible depuis Internet (pas de redirection de port dans le routeur). Pour y accéder en déplacement, utilisez le tableau de bord sur ecosensors.cloud ou un VPN vers votre réseau domestique.
  • Ne mettez pas le mot de passe en clair dans des scripts que vous transmettez.
  • L'API Home Assistant est une interface distincte et chiffrée, voir Home Assistant.