Heatzy OpenAPI 3
Interpréter les données pX_dataY
Comme on l’a vu précédemment, la réponse serveur d’une requête GET app/latest peut faire peur. Il y a beaucoup de paramètres en réponse, et notamment des paramètres du type p1_data1, p4_data6, p2_data8 etc.
On va donc éclaircir ce mystère et voir ensemble comment ces paramètres sont reliés à la programmation horaire de votre pilote.
pX_dataY, ça correspond à quoi ?
Comme vous le savez peut-être déjà. Vous pouvez utiliser l’app heatzy pour programmer votre pilote. Et bien, cette programmation est ensuite enregistrée par votre pilote et également envoyée à notre serveur. Donc vous pouvez à tout moment consulter cette programmation grâce aux APIs.
Le serveur organise ensuite l’information pour qu’on puisse la visualiser en appelant une API. Ici, cela correspond aux paramètre pX_dataY (ou X et Y sont des nombres entiers).
Pour pX, c’est facile. X est un nombre entre 1 et 7 et représente le jour de la semaine. 1=lundi 2=mardi etc.
Pour dataY, c’est un peu plus complexe. l’API découpe chaque journée en 12 tranches horaires de 2 heures. Par exemple de 04h à 6h, ou bien de 18h à 20h. Ensuite chacune de ses tranches de voit attribuer un numéro. La première tranche data1 correspond à la plage horaire 00h-02h. La seconde tranche data2 correspond à la plage horaire 02h-04h etc.
Les deux tableaux ci-dessous vous permettent de mieux comprendre comment interpréter ces paramètres.
Prenons quelques exemples :
p1_data1 correspond à lundi de 00h à 02h
p1_data2 correspond à lundi de 02h à 04h
p2_data1 correspond à mardi de 00h à 02h
p7_data6 correspond à dimanche de 12h à 14h
p7_data12 correspond à dimanche de 22h à 00h
Prenez le temps de bien relire pour comprendre, vous pourrez ensuite passer à la suite de l’interprétation de la réponse.
p4_data11 = 85 ça veut dire quoi ?
Maintenant qu’on a établi à quoi correspondait chaque paramètre pX_dataY, il faut expliquer à quoi correspondent les valeurs renvoyées par ces paramètres. Pour cela, on va commencer avec un exemple très simple : une programmation entièrement en mode éco du lundi au dimanche.
Pour un pilote appairé à votre compte, programmez le pour rester en mode éco toute la semaine. Puis renvoyez un requête GET, vous aurez une réponse avec tous les paramètres pX_dataY = 85.
Pourtant on a vu précédemment que pour envoyer un ordre à un pilote, on avait le choix en 4 valeurs allant de 1 à 4. (1=confort, 2=éco, 3=hors-gel, 4=off). Donc 85, c’est une valeur innatendue.
En réalité la valeur 85 est une combination de 4 valeurs binaires !
En effet, lorsque vous utilisez l’app pour programmer votre pilote, vous pouvez paramétrer tout au long de la journée par tranche de 30 minutes. Or, le serveur renvoie les infos avec dataY en tranches de deux heures. Faites le calcul, dans une tranche de deux heures on a quatre tranches de 30 minutes.
Maintenant, on va convertir la valeur 85 en binaire (utilisez votre tête, une calculatrice, ou une application web pour ça). 85 convertit en binaire, ça donne 01010101. Autrement dit, ça donne quatre fois la valeur 01. Ce qui équivaut à quatre fois le mode éco.
Pour faire simple : heatzy fonctionne avec 4 modes de chauffe et chaque mode a une valeur. La première valeur en binaire c’est 00, la seconde c’est 01, la troisième 10, et la quatrième 11.
Donc si on reprend nos quatre tranches de 30 minutes, ça donne quatre fois la valeur 01. On les met ensuite bout-à-bout et on convertit en décimal pour obtenir la valeur 85.
Quelques exemples pour mieux comprendre
Lancez une programmation avec tous les jours de la semaine en mode confort. Le mode confort renvoie à la valeur 00. Donc quatre fois cette valeur, et tous les paramètres pX_dataY seront égaux à 0. (0 en binaire et en décimal c’est la même chose, donc facile à comprendre)
Lancez maintenant une programmation lundi, de 00h à 03h en mode confort, de 03h à 06h en mode éco ; puis toutes les autres plages horaires en confort. Ensuite envoyez une requête GET et vous devriez obtenir une réponse comme ci-dessous
Tous les paramètres pX_dataY sont à 0 (mode confort). Et on a jute p1_data2 = 80 et p1_data3=85.
Comme on le sait déjà p1_data3=85 signifie que lundi de 04h à 06h le pilote est en mode éco. On va regarder p1_data2 de plus près. Donc on prend la valeur 80, on la convertit en binaire, on obtient 01010100. Donc 3 blocs éco et 1 bloc confort.
Attention : les blocs sont mis à la suite à l’inverse du sens chronologique. Donc, le dernier bloc en mode confort correspond en fait à la plage horaire 02h00-02h30. Les trois autres blocs éco correspondent à la plage horaire 02h30-04h00.
Conclusion
Si vous avez réussi à aller au bout de ce chapitre, félicitations, il était particulièrement difficile. On vous conseille de le relire plusieurs fois et de faire des tests chez vous pour voir comment le serveur répond lorsque vous changez vos paramètres de programmation.
Etant donné la complexité de l’encodage de la programmation sur les APIs, on vous conseille plutôt d’utiliser l’app pour modifier votre programmation. Néanmoins, si vous vous en sentez capable et que vous voulez pouvoir consulter la programmation d’un pilote en dehors de l’application, vous pouvez créer vos propres outils pour simplifier la lecture de ces données (si par exemple vous faites des projets Arduino ou Raspberry).
Enfin, si vous voulez en savoir plus sur nos APIs, nous avons mis une documentation complète à votre disposition qui regroupe plus de fonctions. Mais pour la suite, il vous faudra expérimenter de votre côté pour bien tout comprendre !
Si jamais vous êtes créatif et que vous avez développé un projet pour améliorer l’utilisation du Heatzy pilote, n’hésitez pas à les partager avec nous. Nous serons ravis d’en faire profiter à la communauté Heatzy !