Récupérer la température et l'hygrométrie de thermomètres Switch-Bot à l'aide de leur API+petit bonus

Hello,

Les thermomètres Switch-Bot ne peuvent pas, par défaut, être intégrés dans Home-Assistant.
Une intégration switch-bot native existe mais ne permet que d’utiliser le premier appareil de cette marque, qui permet de connecter un interrupteur.

Cependant, il existe une API qui permet, entre autre, de consulter la température de ses thermomètres Switchbot.

Prérequis

  • Avoir installé l’application de la marque
  • Avoir créé son compte
  • Avoir ajouté ses thermomètres
  • Possèder un Hub Switchbot comme le Hub mini
  • Avoir activé le mode cloud sur les thermomètres à intégrer, même si ça fonctionne peut-être sans ; la documentation n’est pas claire à ce sujet, pour ça aller dans les paramètres de chaque thermomètre puis aller dans le mode cloud
  • Avoir installé curl qui est déjà dispo sous Windows 10 et jq optionnel mais qui aide néanmoins à faciliter les choses pour récupérer les informations.

Récupération du token

Pour accéder à l’API, il faut connaître son jeton d’accès :
Dans l’application Switchbot, aller dans Profile→Paramètres→Developer options et notez le token affiché.

Récupération des identifiants des thermomètres

C’est là que ça devient barbu, tout se passe en ligne de commande.
Voici comment récupérer la liste de vos appareils (désolé pour les utilisateurs de Windows, je ne suis pas entièrement convaincu que ça passe en l’état) :
curl -H "Content-Type: application/json; charset=utf8" -H "Authorization: <token>" https://api.switch-bot.com/v1.0/devices | jq -r ".body.deviceList[] | \"ID : \"+.deviceId+\" ; Nom : \"+.deviceName+\" ; type : \"+.deviceType"
Penser à remplacer <token> par le token récupéré depuis l’application.

On récupère ainsi une liste présentée comme suit :
ID: <id> ; nom : <nom> ; type : <type>

Pour tous les éléments qui ont le type meter, on aura besoin du id pour les futures sensors.
Le nom nous permettra de savoir comment nommer chaque sensor.

Mise en place des sensors

Nous allons utiliser un ensemble de rest sensors pour tout récupérer d’un coup.
D’autres aproches sont possibles mais c’est celle que je trouve la plus directe.

Dans config.yaml, mettre ceci :

rest:
  - resource: "https://api.switch-bot.com/v1.0/devices/<id>/status"
    scan_interval: 60
    method: GET
    headers:
      Authorization: <token>
      Content-Type: "application/json; charset=utf8"
    sensor:
      - name: Thermomètre Bureau
        value_template: "{{ value_json.body.temperature if value_json.statusCode==100 else states('sensor.thermometre_bureau') }}"
        device_class: temperature
        unit_of_measurement: "°C"
        force_update: true # Peut-être superflu 

      - name: Hygromètre Bureau
        value_template: "{{ value_json.body.humidity if value_json.statusCode==100 else states('sensor.hygrometre_bureau') }}"
        device_class: humidity
        unit_of_measurement: "%"
        force_update: true # Peut-être superflu

Les valeurs retournées par l’API ne tiennent pas compte de l’étalonage qui aurait été fait dans l’application Switch-Bot.
Pour tenir compte de celui-ci, il faut refaire le calcul dans le sensor, par exemple pour ajouter 0.3 :

    sensor:
      - name: Thermomètre Bureau
        value_template: "{{ value_json.body.temperature+0.3 if value_json.statusCode==100 else states('sensor.thermometre_bureau') }}"
        device_class: temperature
        unit_of_measurement: "°C"
        force_update: true # Peut-être superflu 

La même chose est à faire dans le sensor hygromètre si l’hygrométrie est à étaloner.

Pensez à remplacer <token> par votre token API et <id> par l’identifiant du thermomètre.
Pour rajouter des thermomètres, il suffit de recopier toutes les lignes à partir de - resource: "https://api.switch-bot.com/v1.0/devices/<id>/status"

Le souci que j’ai eu avec cette méthode est qu’il n’est pas possible de placer les entités dans des pièces vu qu’on ne peut pas leur attribuer d’identifiant unique.

L’utilisation d’un rest sensor par thermomètre avec toutes les données en atributs et de deux template sensors un pour la température et l’autre pour l’hygrométrie basé sur l’état des attributs respectifs du rest sensor permettrait de placer les deux dernières entités dans une pièce.
Mais j’ai préféré l’approche pour laquelle j’ai mis la config pour avoir le moins d’entités possible.

atention !

Le nombre d’appels à l’API est limité à 10000 apels par jour et par token.

Pour la fin, Contrôle infrarouge

Si vous avez rajouté des télécommandes, voici comment en contrôler.

On commence donc par récupérer la liste des appareils infrarouge enregistrés.
curl -H "Content-Type: application/json; charset=utf8" -H "Authorization: <token>" https://api.switch-bot.com/v1.0/devices | jq -r ".body.infraredDeviceList[] | \"ID : \"+.deviceId+\" ; Nom : \"+.deviceName+\" ; type : \"+.remoteType"

à l’aide d’une commande rest, on peut envoyer toute commande supportée :

rest_command:
  controler_barre_de_son:
    url: "https://api.switch-bot.com/v1.0/devices/<id>/commands"
    method: post
    content_type: "application/json; charset=utf8"
    headers:
      Authorization: <token>
    payload: '{"command": "{{ commande }}", "commandType": "{{ type_commande }}"}'

Ou <id> est à remplacer par l’identifiant de la télécommande et <token> par le token API.

Il est donc possible, avec une barre de son par exemple, de créer un switch pour l’allumer ou l’éteindre et de créer deux scripts : un pour augmenter le volume et l’autre pour le baisser :

switch:
  - platform: template
    switches:
      barre_de_son_salon:
        friendly_name: "Barre de Son Salon"
        unique_id: "switch.barre_de_son_salon"
        turn_on:
          service: rest_command.controler_barre_de_son
          data:
            commande: "turnOn"
            type_commande: ""
        turn_off:
          service: rest_command.controler_barre_de_son
          data:
            commande: "turnOff"
            type_commande: "command"

script:
  barre_son_volume_plus:
    alias: "Augmenter le volume de la barre de son"
    description: "Augmente le son de la barre de son"
    mode: queued
    sequence:
      - service: rest_command.controler_barre_de_son
        data:
          commande: "volumeAdd"
          type_commande: "command"

  barre_son_volume_moins:
    alias: "Diminuer le volume de la barre de son"
    description: "Diminue le son de la barre de son"
    mode: queued
    sequence:
      - service: rest_command.controler_barre_de_son
        data:
          commande: "volumeSub"
          type_commande: "command"

Un script serait suffisant pour allumer ou éteindre la barre de son mais on aimait trop la phrase de Google « j’éteint la barre de son salon » qu’on avait quand on utilisait l’intégration Switchbot pour Google Assistant.

Conclusion

Il est donc possible d’intégrer Switchbot à Home Assistant. Une lecture de la documentation de l’API permet de voir le champ d’action.
Elle permet également de contrôler les Switchbot curtains mais n’ayant pas le produit, je préfère vous renvoyer à la documentation.

J’espère que ce tutoriel aura été claire, compte tenu notamment de l’heure de sa rédaction :smiley: mais aussi du fait que la récupération des informations nécessaire n’est pas forcément aisée.

Changements

  • 11/11/2021 : la limite de 10000 demandes à l’API n’est dèsormais plus un secret
  • Ajout des modifications à faire si besoin d’étalonner la température ou l’hygrométrie, merci @NuM82
3 « J'aime »

Bonjour,

Si vous avez étalonné vos « Switchbot Meter », les infos récupérés via l’API (et ce super tuto) ne sont pas corrigées.
Pour y remédier, remplacer :

pour un éalonnage de +0.3 par :

Vous pouvez également appliquer ce correctif pour la partie hydromètre.

1 « J'aime »

Merci, je ne savais pas que l’API ne tenait pas compte de la valeur étalonnée, je supposais que ce paramètre était directement envoyé aux meters qui appliquaient en suite le calcul n’ayant pas eu besoin d’étalonner mes thermomètres.
J’ai donc rajouté une petite note au tuto :slight_smile:

Pour info, les valeurs retournées via bluetooth sont les valeurs étalonnées.

ça par exemple, sachant que l’API a ses valeurs un moment donné par le bluetooth vu que c’est par le hub ou un smart phone vu que les meters ne communiquent pas directement avec les serveurs switchbot, voilà un phénomène étrange :wink: