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
adminet 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.