Utiliser l’API REST Home Assistant

Nous avons déjà beaucoup parlé d’Home-assistant, de sa mise en place et de son utilisation. Ainsi, nous avons vu qu’il permet d’utiliser simplement, tous vos objets connectés. Mais voilà, il vous manque encore quelque chose… Vous aimeriez mieux l’adapter à votre quotidien. Là encore il y a une solution ! En effet, Home assistant propose de nombreuses APIs qui permettent une flexibilité quasi infinie.Je vous propose de commencer un nouveau dossier ! Vous pourrez y apprendre à composer avec ces APIs.  Commençons aujourd’hui par découvrir une partie des possibilités qui nous sont offertes et comment les utiliser rapidement.

Les APIs

Afin de partir sur de bonnes bases, commençons par définir ce qu’est une API

En informatique, une interface de programmation applicative (souvent désignée par le terme API pour Application Programming Interface) est un ensemble normalisé de classes, de méthodes ou de fonctions qui sert de façade par laquelle un logiciel offre des services à d’autres logiciels. Elle est offerte par une bibliothèque logicielle ou un service web, le plus souvent accompagnée d’une description qui spécifie comment des programmes consommateurs peuvent se servir des fonctionnalités du programme fournisseur.

Wikipédia

Home assistant décline son offre en six types différents :

  • Home Assistant API :  Permet de développer de nouveaux modules en python3. Cette API n’est donc pas fondamentalement faite pour contrôler à distance notre système.
  • Python API : C’est un sous-ensemble du premier point à l’exception près que son but et de fournir des méthodes python permettant de communiquer via HTTP.
  • RESTful API : Les APIs REST sont très répandues, car très simples à mettre en oeuvre. Elles permettent de communiquer via des requêtes HTTP basiques.
  • Websocket API : Permet d’interagir avec Home assistant via un client/programme compatible avec cette technologie. Pour faire simple, les communications seront streamées via des canaux des communications bi-directionnels. L’intérêt : des performances accrues et du “temps réel” entre le serveur et le client. L’inconvénient : plus complexe à mettre en place.
  • Server-sent events : Cette technologie permet d’ouvrir un canal unidirectionnel du serveur vers le client. Cela permet de réagir rapidement à des événements envoyés par le serveur.

Pour la suite de cet article, je vous propose de voir plus en détails comment utiliser les API REST. En effet,  ce sont celles-ci que nous privilégierons dans les prochains articles de ce dossier.

Testez vos APIs

Dans un premier temps, nous devons tester que tout fonctionne.  Il vous faut donc un client HTTP.  Pour ma part j’aime beaucoup postman que j’utilise en extension Chrome.  Il y a cependant beaucoup d’autres alternatives.

Une fois installé, ouvrez votre client. Nous allons paramétrer notre première requête qui nous permettra de vérifier que tout est fonctionnel.  Configurez votre client comme l’exemple ci-dessous en adaptant l’url et le champ x-ha-access à votre cas.

Testez votre api avec postman

Testez votre api avec postman

Cliquez sur “send” et vous devriez normalement recevoir :

{"message": "API running."}
Si vous recevez le message 404: Not Found vérifier que l’adresse de la requête est bonne (le ‘/’ de fin est primordial).

Faisons plus ample connaissance

Cartographiez vos équipements

Dans un premier temps il est nécessaire de déterminer les différents éléments que vous voulez contrôler. Pour ce faire nous allons utiliser l’API states :

http://url-home-assistant/api/states

De la même manière que dans le chapitre précédent lancez une requête à l’adresse ci-dessus via postman. Vous obtiendrez ainsi une liste de toutes les entités ainsi que de leur état.

Api States

Si vous avez beaucoup de périphériques gérés via votre installation Home assistant, le retour de cette API peut être un peu volumineux. Malheureusement, il n’existe pas aujourd’hui de méthode permettant de filtrer les retours.

Toutes ces informations vous permettent de connaître l’état de vos installations, mais aussi de comprendre comment chaque élément fonctionne. Prenons un exemple. Si vous avez lu cet article, vous n’êtes pas sans savoir que mon installation hue est composée de plusieurs pièces dont un salon. Je vais donc naturellement, retrouver ce salon dans le résultat de la requête précédente.

{
"attributes": {
"brightness": 254,
"color_temp": 366,
"effect_list": [
"colorloop",
"random"
],
"friendly_name": "Salon",
"is_hue_group": true,
"max_mireds": 500,
"min_mireds": 154,
"rgb_color": [
255,
207,
120
],
"supported_features": 127,
"xy_color": [
0.4573,
0.41
]
},
"entity_id": "light.salon",
"last_changed": "2017-05-09T18:37:16.698594+00:00",
"last_updated": "2017-05-09T18:37:16.698594+00:00",
"state": "off"
},

On peut voir que les lampes sont éteintes ("state":"off") et on en apprend un peu plus sur l’installation (avec les attributs notamment).

Agissez sur vos équipements

Nous allons maintenant apprendre à contrôler notre système. Pour ce faire il est nécessaire de connaître les actions qu’il nous est possible de faire.  Ouvrez à nouveau postman et remplacez l’adresse précédente par celle-ci :

http://url-home-assistant/api/services

Vous devriez avoir une grande quantité d’informations semblables à l’exemple ci-dessous :

{
"domain": "nom",
"services": { ... }
}

Si on reprend l’exemple précédent, nous allons travailler avec le domaine nommé light.

Le domaine light

C’est grâce à la partie service que nous allons pouvoir en apprendre plus sur l’utilisation de l’API.

Nous aimerions allumer le salon, regardons donc plus en détail le service “turn_on”.  En plus de la description du service, nous trouvons une liste de champs accompagnée d’une description.

"turn_on": {
"description": "Turn a light on",
"fields": {
"brightness": {
"description": "Number between 0..255 indicating brightness",
"example": 120
},
"color_name": {
"description": "A human readable color name",
"example": "red"
},
"color_temp": {
"description": "Color temperature for the light in mireds",
"example": "250"
},
"effect": {
"description": "Light effect",
"values": [
"colorloop",
"random"
]
},
"entity_id": {
"description": "Name(s) of entities to turn on",
"example": "light.kitchen"
},
"flash": {
"description": "If the light should flash",
"values": [
"short",
"long"
]
},
"profile": {
"description": "Name of a light profile to use",
"example": "relax"
},
"rgb_color": {
"description": "Color for the light in RGB-format",
"example": "[255, 100, 100]"
},
"transition": {
"description": "Duration in seconds it takes to get to next state",
"example": 60
},
"white_value": {
"description": "Number between 0..255 indicating level of white",
"example": "250"
},
"xy_color": {
"description": "Color for the light in XY-format",
"example": "[0.52, 0.43]"
}
}

Dans notre cas nous allons allumer le salon en vert. Pour ce faire, retour à postman.

    • Choisissez le mode POST (liste à gauche de l’URL)
    • Paramétrez l’URL
http://url-home-assistant/api/services/light/turn_on
    • Configurez les champs à envoyer grâce à l’onglet “body”
{
"entity_id":"light.salon",
"brightness": 255,
"rgb_color": [20,30,20]
}
  • Envoyez et les lumières s’allume en vert !

Si vous n’arrivez pas à allumer vos lampes voici une impression écran de postman avec la bonne configuration

Allumez vos lumières

Vous connaissez à présent les bases. Cependant, si vous souhaitez aller plus loin, vous trouverez une documentation détaillée de ces API ici.

Conclusion

Voilà c’est fini pour aujourd’hui !  Si vous avez bien suivi toutes les étapes vous devriez normalement pouvoir vous débrouiller avec à peu près toutes les APIs.  Vous pouvez déjà facilement vous amuser grâce à des applications d’automatisation (on en parle par ici) ou via des scripts (comme expliqué ici).

La seconde partie arrive très vite ! Nous commencerons le développement d’une application capable d’exploiter ce que nous avons vu aujourd’hui !

A bientôt !

Cadre en informatique dans une multinationale je suis un touche-à-tout passionné de nouvelles technologies.

Tu aimes cet article ? Alors partage le Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInPin on PinterestShare on RedditShare on Tumblr

Laisser un commentaire