Communauté Heatzy : Siri mode boost
Un grand merci à Éric Herrmann pour la rédaction de cet article. Si vous avez des questions concernant ce tutoriel vous pourrez en discuter directement avec Éric sur twitter @ericisalolatara
Utilisateur Heatzy depuis plus plus d’un an (5 modules Pilote) je m'intéresse depuis quelques temps à l’API proposée par Heatzy et notamment son intégration dans l’écosystème Apple/iOS.
Aujourd’hui je vous propose de voir comment intégrer la gestion de vos modules Pilote au travers de la fonctionnalité ‘Raccourcis’ sous iOS.
Vous allez me dire: il existe déjà l’application Pilote sous iOS donc ca sert à quoi?
Et bien je dirais:
1. La flexibilité: possibilité par exemple de cibler des raccourcis pour un chauffage en particulier si vous ne voulez pas que vos enfants aient accès au réglage de tous les chauffages (non ce n’est pas du vécu :) )
Dans ce cas vous leur mettez sur leur smartphone un raccourci pour la gestion de leur chauffage uniquement et pas l’application Heatzy Pilote
2. L’automatisation: avec les scénarios de l’application Raccourcis vous pouvez intégrer la gestion de vos chauffages avec une multitude de critères comme: états d’autres capteurs, horaire, météo, token RFID, etc…
3. Commandes vocales: alors oui Heatzy le gère déjà de manière native mais si comme moi vous êtes par exemple gros utilisateur de la fonction Boost (je suis en voiture je rentre du sport et je veux mettre le chauffage juste 30 ou 45mn le temps d’arriver, que la salle de bain soit à température et le temps de prendre ma douche avec ensuite un arrêt automatique) il n’y a pas aujourd’hui de possibilité de gérer vocalement ce genre de scénarios (les durées de boost sont aussi figées et je vais vous montrer comment contourner cette limitation)
Avant de commencer
Vous avez évidemment besoin d’un appareil sous iOS (13 ou 14), l’application Raccourcis et un ou plusieurs modules Heatzy.
Nous allons également utiliser le service Postman sur lequel je ne vais pas revenir en détail sachant que tout est expliqué dans divers articles du blog notamment ici pour démarrer.
Bien évidemment ce tuto se veut simple et accessible. Je n’ai pas la prétention de maîtriser entièrement le sujet, il y a certainement des choses à améliorer, à faire différemment etc.. mais je pense que c’est une bonne base pour appréhender l’API Heatzy, Postman et les raccourcis iOS.
Principe
Le principe est simple: nous allons créer un raccourci iOS qui va nous présenter un menu nous permettant de choisir les fonctions suivantes:
Allumer le chauffage (en mode confort mais vous pouvez facilement changer pour un autre mode)
Arrêter le chauffage
Activer la fonction boost pour 30mn, 1h ou 2h (là aussi vous pouvez facilement l’adapter)
Je vous montre ici une capture de l'icône sur le bureau iOS (vous pouvez aussi lancer le raccourci depuis l’appli Raccourcis ou depuis un widget iOS 14)
Sur la 2ème capture le résultat final avec le menu qui se lance lorsque vous touchez l'icône.
Etape 1
Pour cette 1ère étape nous allons très fortement nous inspirer des articles déjà parus sur le blog Heatzy concernant l’utilisation de l’API avec Postman ici
Pour résumer, nous allons avoir besoin des éléments suivants:
Votre token Heatzy
Le did (device ID) du module que vous souhaitez piloter
L’application id qui est: c70a66ff039d41b4a220e198b0fcc8b3
J’ai créé plusieurs requêtes dans postman qui vont nous aider à récupérer ces éléments et également à vérifier que tout fonctionne bien.
Voici la capture:
Login & Get Token
C’est assez explicite: je m'authentifie auprès de l’API et je récupère mon token. Notez que votre token Heatzy a une durée de vie limitée, vous ne devez donc pas le ‘coder en dur’ dans votre raccourci sous peine de voir celui-ci devenir inutilisable au bout de quelques semaines Je vous laisse consulter la doc de l’API à cette adresse pour plus d’informations, choisissez bien la doc de l’API 2020 et pas l’ancienne
La requête d’authentification et récupération est expliquée dans l’article que j’ai mis en lien plus haut. Il faut passer les éléments suivants:
POST http://euapi.gizwits.com/app/login
Headers: X-Gizwits-Application-Id = c70a66ff039d41b4a220e198b0fcc8b3
Body:
{
"username": "xxx@xxx.xxx",
"password": "xxxxxx"
}
qui sont vos identifiants Heatzy utilisés notamment pour l’application iOS.
Cette requête va vous retourner votre token, uid et la date d’expiration du token (en format Unix donc à convertir si cela vous intéresse et à utiliser par exemple pour ne pas surcharger les serveurs en re-demandant le token chaque jour)
Get Devices
Maintenant que nous avons notre token nous pouvons requêter l’API pour récupérer le did (device id) du ou des modules que l’on souhaite piloter. Pour l’exemple je ne travaille que sur un seul de mes 5 modules mais le principe reste bien sûr le même avec plusieurs modules.
GET https://euapi.gizwits.com/app/bindings?limit=20&skip=0
Headers
X-Gizwits-Application-Id = c70a66ff039d41b4a220e198b0fcc8b3
X-Gizwits-User-token = ‘mon token’
Lancez la requête et récupérez le résultat en JSON et en sélectionnant l’option ‘pretty’ pour avoir quelque chose de lisible.
Pour info les paramètres limit et skip sont optionnels (limiter les résultats retournés et ignorer certains éléments)
Ce qui m'intéresse dans le résultat retourné est:
"did": "xxxxxxxxxxxx"
Pour le module Pilote que je veux utiliser.
Turn on Bureau (oui ok c’est pas très sexy comme nom…)
Avec cet appel je vais mettre le chauffage en mode confort sur mon module bureau. Nous allons intégrer plus tard ce type d’appel dans le raccourci iOS.
POST ttps://euapi.gizwits.com/app/control/did_votre_module
Headers
X-Gizwits-Application-Id = c70a66ff039d41b4a220e198b0fcc8b3
X-Gizwits-User-token = ‘mon token’
BODY
{
"attrs": {
"mode": 0}
}
Vous devez remplacer à la fin de l’url la mention did_votre_module par le did récupéré dans la requête précédente. Notez que ce did ne changera pas donc vous n’avez pas à utiliser la requête précédente Get Devices dans le code de votre raccourci. Simplement lancez là une fois dans Postman et récupérez le résultat à coller dans le code du raccourci
Notez aussi que mode 0 = confort, mode 1 = eco, mode 2 = hors gel, mode 3 = off
Tout ceci est expliqué dans la doc de l’API
Bureau Boost mode on
Ici nous allons activer le mode boost au travers d’une requête POST.
POST https://euapi.gizwits.com/app/control/did_votre_module
Headers
X-Gizwits-Application-Id = c70a66ff039d41b4a220e198b0fcc8b3
X-Gizwits-User-token = ‘mon token’
BODY
{
"attrs": {
"mode": 0,
"derog_mode": 2,
"derog_time": 30
}
}
Quelques commentaires: d’abord pensez bien à remplacer comme précédemment did_votre_module par le did de votre module
Ensuite dans le body nous modifions l’objet ‘attributs’ (attrs) du module dont le mode (je passe le chauffage en confort), l’attribut mode derog = 2 pour indiquer que l’on veut passer en mode Boost et derog_time qui indique ici que je veux rester en Boost pendant 30mn (vous pouvez évidemment changer le mode Confort par un autre mode et la durée dans le paramètre derog_time)
Attention car la doc de l’API n’est pas à jour (en tous cas au 21/10/20) et les attributs ‘boost_xxx’ ne fonctionnent plus, il faut vraiment gérer le mode boost avec l’attribut derog_mode = 2
Get data from Bureau
Cette requête nous permet de récupérer l’état du module ‘Bureau’...et pourquoi? Et bien parce que :)
Cela peut servir par exemple dans une boucle IF (si le chauffage est déjà en mode confort je ne vais pas relancer une requête pour le passer en confort etc..).
C’est aussi très utile pour vérifier que vos actions au niveau de l’API sont correctement exécutées (vous pouvez aussi utiliser l’appli iOS pour ca)
Vous pouvez même voir le temps restant lorsque vous activez le boost…
GET https://euapi.gizwits.com/app/devdata/did_votre_module/latest
Headers
X-Gizwits-Application-Id = c70a66ff039d41b4a220e198b0fcc8b3
X-Gizwits-User-token = ‘mon token’
Voilà on en a terminé avec la partie Postman et nous avons maintenant toutes les infos et requêtes à exécuter dans notre raccourci. On peut dire que le plus gros du travail est fait!
Etape 2: Création du raccourci iOS
Lancez l’application Raccourcis
Depuis l’onglet du bas ‘Mes raccourcis’ cliquez sur le + en haut à droite
Ensuite en cliquant sur les ‘...’ en haut à droite vous pourrez donner un nom à votre raccourci Pour le reste je vous laisse voir l’aide de l’application car pas d’utilité pour notre tuto. Quoi que mettre le mode boost de la salle de bain depuis son apple watch c’est quand même classe :)
Maintenant je vais vous détailler chaque étape avec des captures d’écran
Nous créons ici une première action avec l’objet “Obtenir le contenu de l’URL” qui comme son nom l’indique...va récupérer le contenu de l’URL que nous allons passer.
Cela correspond à la 1ere requête que nous avons créé dans postman: Login & Get Token
Voici le détail de cette commande:
Rien de particulier à signaler, la méthode à choisir est POST, le corps doit être en JSON et vous passez les paramètres HEADER et BODY comme vu plus haut (j’ai masqué ici mes identifiants)
Ensuite nous allons récupérer le TOKEN depuis cet appel en POST
Donc depuis l’objet “Documents” je récupère la variable de type ‘Nom’ depuis la clé ‘token’. Cette clé est récupérée depuis un objet de type ‘dictionnaire’. Voici ce que vous devez sélectionner pour le champ de droite (flèche verte vers le bas suivi de ‘token’)
Il s’agit donc du résultat de la requête sous forme d’un dictionnaire dans lequel nous recherchons la clé qui s’appelle ‘token’
Ensuite je mets la valeur de token dans une variable nommée ‘Token’ car je vais, à chaque prochaine requête, devoir la passer en header.
C’est important de la mettre en variable car je rappelle que le token a une durée de vie limitée donc la prochaine fois que vous utilisez ce raccourci il aura peut-être changé (le token, pas le raccourci!).
Maintenant que j’ai mon token et dans la mesure ou j’ai récupéré le did de mon module depuis Postman (requête Get Devices) je vais pouvoir créer mon menu déroulant me permettant de choisir entre les différentes actions (Allumer, Éteindre, Boost 30mn / 1h / 2h)
Le did du device (à moins de remplacer votre module pilote ou d’utiliser le raccourci pour un autre module) ne va pas changer donc vous pouvez le coder en dur. Nous allons voir ça de suite.
Pas grand-chose à dire ici, je crée un objet de type ‘menu’ (depuis le bouton ‘scripts’ sélectionner ‘choisir dans le menu’)
Je donne un nom à mon invite (‘Choisir l’action’) et je crée toutes les entrées dont j’ai besoin.
Vous nommez chaque entrée comme vous le souhaitez (c’est ce qui apparaîtra dans le menu lorsque vous lancez le raccourci)
Maintenant nous allons voir le contenu de chacune des entrées
Pour Allumer et Éteindre le principe est le même donc je ne vous mets que la capture pour Allumer.
Vous aurez compris que j’ai masqué le did de mon module Pilote :)
Ici on passe la requête POST Turn on Bureau
On voit bien ma variable ‘Token’ passée dans les en-têtes
Concernant le dictionnaire ‘attrs’ voici le détail de ce que je passe:
Comme je veux allumer mon chauffage en mode confort j’ai bien mode = 0 et je m’assure que le boost est désactivé (derog_mode=0) ainsi que la minuterie (derog_time=0)
Pour éteindre le chauffage vous aurez compris que c’est tout pareil sauf l’attribut mode qui doit être = 3
Dernière étape, je vous montre un exemple pour le mode Boost 2 heures. Evidemment ce sera la même chose pour les autres durées en changeant simplement derog_time = xx (minutes)
Ici encore je passe ma requête POST en indiquant bien mon did à la fin de l’URL.
Je ne l’ai pas précisé avant mais vous avez dû remarquer que pour chaque élément du menu j’affiche une notification iOS (fonction Aperçu) qui vient confirmer mon choix. Ce n’est pas obligatoire mais ca rend les choses un peu plus interactives.
Voici le détail des paramètres à passer dans notre requête POST:
Je pense que vous avez maintenant compris: j’active mode = 0 (le mode confort), j’active le boost et je règle la minuterie du boost à 120mn.
Et oui il est tard, mon iphone est passé en mode nuit :)
Il est donc temps de vous laisser, si quelque chose ne fonctionne pas dans les appels API testez les paramètres retournés par la requête Get Devices
Bien sûr, comme je l’ai dit au début ce n’est qu’un exemple qui peut être optimisé/amélioré. Par exemple ici je récupère le token à chaque utilisation (pas bien), on pourrait le demander une fois et récupérer la date de validité, et utiliser cette dernière pour limiter le nombre d’appels. Le menu peut également être étendu à plusieurs modules...bref je vous laisse expérimenter.
A bientôt!