Utiliser l’API REST Home Assistant [update]

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.

Récupérez vos token

Dans un premier temps vous devez récupérer votre token d’authentification. Ce dernier vous permettra de vous identifier. Pour ce faire rendez-vous sur votre profile en entrant un URL du type

http://url-home-assistant/profile

Tout en bas vous devriez avoir un encart vous permettant de créer des jetons de connexions

Renseigner un nom de token et copiez la clé générée. Ne la perdez pas vous ne pourrez plus la récupérer. En cas de perte vous serez obligé de la supprimer et d’en créer une nouvelle.

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 Authorization à votre cas.

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 !

12 réponses

  1. Alexandre VAULE dit :

    Bonjour ! J’ai bien téléchargé POSTMAN mais quand je tape l’adresse http://url-home-assistant/api/ ca ne me trouve rien :/ Et un message erreur ! HELP MEEEE !!!! :p

  2. Chevalier dit :

    Quel est le mot de passe ? De mon compte google? Car la je ne vois pas merci

  3. Nicolas dit :

    Bonjour,
    J’ai Google Home et un chromecast branché sur ma télé. Je souhaiterai contrôler le volume, changer de chaîne par la voix.
    Lorsque je tape http://192.168.1.81:8123/api/states aucun matériel n’est reconnu.
    Mon Google Home se nomme Salon. Mon Chromecast se nomme Télé.
    Pouvez-vous m’indiquer où dois-je indiquer ces noms dans mon Home Assistant ?
    Voici ce que j’obtiens actuellement :
    [
    {
    « attributes »: {
    « message »: « Here are some resources to get started:\n\n – [Configuring Home Assistant](https://home-assistant.io/getting-started/configuration/)\n – [Available components](https://home-assistant.io/components/)\n – [Troubleshooting your configuration](https://home-assistant.io/docs/configuration/troubleshooting/)\n – [Getting help](https://home-assistant.io/help/)\n\nTo not see this card popup in the future, edit your config in\n`configuration.yaml` and disable the `introduction` component. »,
    « title »: « Welcome Home! »
    },
    « entity_id »: « persistent_notification.notification »,
    « last_changed »: « 2018-01-29T21:39:33.985817+00:00 »,
    « last_updated »: « 2018-01-29T21:39:33.985817+00:00 »,
    « state »: « notifying »
    },
    {
    « attributes »: {
    « azimuth »: 313.23,
    « elevation »: -51.35,
    « friendly_name »: « Sun »,
    « next_dawn »: « 2018-01-30T06:28:24+00:00 »,
    « next_dusk »: « 2018-01-30T16:58:19+00:00 »,
    « next_midnight »: « 2018-01-29T23:43:27+00:00 »,
    « next_noon »: « 2018-01-30T11:43:21+00:00 »,
    « next_rising »: « 2018-01-30T07:02:19+00:00 »,
    « next_setting »: « 2018-01-30T16:24:24+00:00 »
    },
    « entity_id »: « sun.sun »,
    « last_changed »: « 2018-01-29T21:39:36.012581+00:00 »,
    « last_updated »: « 2018-01-29T21:49:30.235477+00:00 »,
    « state »: « below_horizon »
    },
    {
    « attributes »: {
    « message »: « The following components and platforms could not be set up:\n\n – [discovery](https://home-assistant.io/components/discovery/)\n – [cloud](https://home-assistant.io/components/cloud/)\n\nPlease check your config. »,
    « title »: « Invalid config »
    },
    « entity_id »: « persistent_notification.invalid_config »,
    « last_changed »: « 2018-01-29T21:39:39.764402+00:00 »,
    « last_updated »: « 2018-01-29T21:40:47.036783+00:00 »,
    « state »: « notifying »
    },
    {
    « attributes »: {
    « attribution »: « Weather forecast from yr.no, delivered by the Norwegian Meteorological Institute and the NRK. »,
    « entity_picture »: « https://api.met.no/weatherapi/weathericon/1.1/?symbol=4;content_type=image/png »,
    « friendly_name »: « yr Symbol »
    },
    « entity_id »: « sensor.yr_symbol »,
    « last_changed »: « 2018-01-29T21:40:48.217708+00:00 »,
    « last_updated »: « 2018-01-29T21:40:48.217708+00:00 »,
    « state »: « 4 »
    }
    ]

    Je vous remercie.
    Bonne Soirée. Nicolas

    • Bonjour,

      S’agit-il d’une installation Home Assistant ou Hass.io ? Dans tous les cas le soucis semble venir de votre configuration. Les composant discovery et cloud sont en erreur. Généralement c’est via le composant discovery que sont paramétré les périphérique de type chromecast. Votre problème de périphérique absent n’est donc pas étonnant puisque discovery ne fonctionne pas. Deux solutions donc, tenter de reprendre votre fichier de config pour voir ce qui cloche et pour avoir le droit à la découverte automatique de vos périphériques ou tenter une configuration manuelle (https://home-assistant.io/components/media_player.cast/).

      Bonne journée.

      • Nicolas dit :

        Bonjour,

        Merci pour votre réponse.
        J’ai installé Home assistant depuis une commande dos sur Windows 10.

        Voici mon fichier configuration.yaml :
        homeassistant:
        # Name of the location where Home Assistant is running
        name: Home
        # Location required to calculate the time the sun rises and sets
        latitude: 48.4521
        longitude: 7.4617
        # Impacts weather/sunrise data (altitude above sea level in meters)
        elevation: 0
        # metric for Metric, imperial for Imperial
        unit_system: metric
        # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
        time_zone: Europe/Paris
        # Customization file
        customize: !include customize.yaml

        # Show links to resources in log and frontend
        introduction:

        # Enables the frontend
        frontend:

        # Enables configuration UI
        config:

        http:
        # Secrets are defined in the file secrets.yaml
        # api_password: !secret http_password
        # Uncomment this if you are using SSL/TLS, running in Docker container, etc.
        # base_url: example.duckdns.org:8123

        # Checks for available updates
        # Note: This component will send some information about your system to
        # the developers to assist with development of Home Assistant.
        # For more information, please see:
        # https://home-assistant.io/blog/2016/10/25/explaining-the-updater/
        updater:
        # Optional, allows Home Assistant developers to focus on popular components.
        # include_used_components: true

        # Discover some devices automatically
        discovery:

        # Allows you to issue voice commands from the frontend in enabled browsers
        conversation:

        # Enables support for tracking state changes over time
        history:

        # View all events in a logbook
        logbook:

        # Enables a map showing the location of tracked devices
        map:

        # Track the sun
        sun:

        # Weather prediction
        sensor:
        – platform: yr

        # Text to speech
        tts:
        – platform: google

        # Cloud
        cloud:

        group: !include groups.yaml
        automation: !include automations.yaml
        script: !include scripts.yaml

        J’ai tenté d’inscrire manuellement dans le fichier conf après homeassistant :
        media_player:
        – platform: cast
        host: adresse IP de mon chromecast

        et ça me met une erreur quand je le démarre en tapant hass :

        Config directory: C:\Users\nicol\AppData\Roaming\.homeassistant
        ERROR:homeassistant.util.yaml:while parsing a block collection
        in « C:\Users\nicol\AppData\Roaming\.homeassistant\configuration.yaml », line 3, column 3
        expected , but found ‘?’
        in « C:\Users\nicol\AppData\Roaming\.homeassistant\configuration.yaml », line 7, column 3
        ERROR:homeassistant.bootstrap:Error loading C:\Users\nicol\AppData\Roaming\.homeassistant\configuration.yaml: while parsing a block collection
        in « C:\Users\nicol\AppData\Roaming\.homeassistant\configuration.yaml », line 3, column 3
        expected , but found ‘?’
        in « C:\Users\nicol\AppData\Roaming\.homeassistant\configuration.yaml », line 7, column 3

        Voici mes logs :

        2018-02-03 14:55:30 WARNING (Recorder) [homeassistant.components.recorder] Ended unfinished session (id=10 from 2018-01-31 22:29:49.017740)
        2018-02-03 14:55:38 ERROR (SyncWorker_3) [homeassistant.util.package] Unable to install package netdisco==1.2.4: Command « c:\users\nicol\appdata\local\programs\python\python36\python.exe -u -c « import setuptools, tokenize;__file__=’C:\\Users\\nicol\\AppData\\Local\\Temp\\pip-build-dyj0_z9h\\netifaces\\setup.py’;f=getattr(tokenize, ‘open’, open)(__file__);code=f.read().replace(‘\r\n’, ‘\n’);f.close();exec(compile(code, __file__, ‘exec’)) » install –record C:\Users\nicol\AppData\Local\Temp\pip-k6k2l88c-record\install-record.txt –single-version-externally-managed –compile –user –prefix= » failed with error code 1 in C:\Users\nicol\AppData\Local\Temp\pip-build-dyj0_z9h\netifaces\
        2018-02-03 14:55:38 ERROR (MainThread) [homeassistant.setup] Not initializing discovery because could not install dependency netdisco==1.2.4
        2018-02-03 14:55:38 ERROR (MainThread) [homeassistant.setup] Setup failed for discovery: Could not install all requirements.
        2018-02-03 14:56:00 ERROR (SyncWorker_0) [homeassistant.util.package] Unable to install package warrant==0.6.1: Command « c:\users\nicol\appdata\local\programs\python\python36\python.exe -u -c « import setuptools, tokenize;__file__=’C:\\Users\\nicol\\AppData\\Local\\Temp\\pip-build-zpgc95su\\pycryptodome\\setup.py’;f=getattr(tokenize, ‘open’, open)(__file__);code=f.read().replace(‘\r\n’, ‘\n’);f.close();exec(compile(code, __file__, ‘exec’)) » install –record C:\Users\nicol\AppData\Local\Temp\pip-a43kuki8-record\install-record.txt –single-version-externally-managed –compile –user –prefix= » failed with error code 1 in C:\Users\nicol\AppData\Local\Temp\pip-build-zpgc95su\pycryptodome\
        2018-02-03 14:56:00 ERROR (MainThread) [homeassistant.setup] Not initializing cloud because could not install dependency warrant==0.6.1
        2018-02-03 14:56:00 ERROR (MainThread) [homeassistant.setup] Setup failed for cloud: Could not install all requirements.

        Je n’arrive pas à installer netifaces, ni netdisco. Peut-être que j’ai pas la bonne source ou la bonne commande.

        Je ne sais pas si vous pouvez m’aider, je ne suis pas très doué pour ce type d’installation.
        Si je ne suis pas assez clair, n’hésitez pas à me demander.

      • Bonjour,

        c’est assez compliqué de vous aider puisque tout les caractères y compris les espaces sont important dans ce fichier. Le formatage du commentaire semble les avoirs retiré… Pouvez vous m’envoyer directement votre fichier à l’adresse suivante devotics.blog@gmail.com afin que je regarde rapidement si je peux vous aider?

        Merci

  4. PITP2 dit :

    Merci pour tous ces tutos car on ne trouve pas encore bcp de choses en Francais sur Home Assitant.

    Y a t il un tuto de prévu pour l’écriture des automates. Par exemple on ne trouve pas grand chose pour les boucles de base If Then Else etc …

    • Bonjour,
      Merci de votre retour. Pour le moment nous n’avons rien sur ce thème en cours d’écriture pour le moment mais il y a de quoi faire et c’est très probable qu’un article sur le sujet pointe le bout de son nez un jour 🙂

  5. Laurent Caillaud dit :

    Bonjour,
    Merci pour ce tuto mais j’ai un gros souci, je n’arrive pas à trouver l’url de mon assistant. Où le trouver ?
    Merci d’avance.

  6. Sylvain PROUST dit :

    Bonjour,
    Tout d’abord, merci pour ce tuto. Tout fonctionne à part lorsque j’envois la commande turn_on, j’ai le message suivant :405: Method Not Allowed. Pourtant elle se trouve bien dans la liste des services pour l’entité en question.

    Merci d’avance pour votre réponse.
    Cordialement, Sylvain PROUST

  7. fabien dit :

    Il ont ajouté le fonction dans l’api pour filtrer le state d’un seul element :
    ex: http://192.168.1.13:8123/api/states/sun.sun

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.