L’API JSON de Domoticz démythifiée

Oui, oui on dit bien « démythifiée » et non pas « démystifiée » puisque il s’agit bien de « détruire » un mythe, celui de la complexité de l’API JSON de Domoticz.

Définissons tout ça et démythifions donc.

Une API qu’est ce ?

Ce sont des commandes que met à notre disposition un logiciel pour pouvoir le piloter.

Ces jeux d’instructions sont prévus par les développeurs du soft. Ils peuvent être soumis à des restrictions de droits, on peut avoir par exemple le droit d’interroger mais pas de commander le logiciel.

De nombreuses plateformes web permettent ainsi de les interroger pour obtenir quelque chose, citons météo france pour les prévisions de pluie, la SNCF pour les horaires de trains, Airparif pour la qualité de l’air et bien d’autres encore. De la même manière Domoticz peut être interrogé pour obtenir l’état d’un switch, la valeur d’un capteur et on peut également par son API, lui faire exécuter des actions comme changer l’état d’un switch, affecter une valeur à un widget.

Tout cela passe par des envois http/https vers Domoticz en interrogeant son API, qui nous répondra par un retour de texte au format JSON.

Cela signifie que les informations que nous devrons échanger entre nous et Domoticz devront respecter un formatage précis: celui de l’API.

Et JSON qu’est ce?

Wikipedia nous dit :

Un document JSON a pour fonction de représenter de l’information accompagnée d’étiquettes permettant d’en interpréter les divers éléments, sans aucune restriction sur le nombre de celles-ci.

il s’agit d’un format de présentation de texte à base d’étiquettes : un exemple fictif de formatage :

On  voit donc que j’ai  l’étiquette soleil puis des « sous-étiquettes » lever/coucher avec les valeurs correspondantes entourées de  {}.

C’est ainsi que Domoticz renverra des valeurs lorsque on l’interrogera.

Il nous faudra donc des outils pour découper ces blocs de résultats et en retirer facilement ce que l’on souhaite,  jq en shell, json.decode en lua, libraire json en python, ce ne sont pas les outils qui manquent.

Mise en œuvre

Voyons comment interroger Domoticz via les URL et l’API.

la page de référence esthttp://www.domoticz.com/wiki/Domoticz_API/JSON_URL%27s  dont une traduction française est en cours  nous indique que le format à respecter est celui-ci :

 

  • <username:password@> = le login et le mot de passe Domoticz (optionnels).
  • domoticz-ip = l’adresse  IP ou le nom de votre Domoticz .
  • <:port> = le numéro de port (8080 par défaut, optionnel).

la commande API peut être trouvée sur la page en anglais, on y apprend que pour obtenir l’état d’un matériel, je dois envoyer :

avec IDX qui correspond à l’IDX de ce matériel dans Domoticz.

Rappel : on le trouve dans « Réglages » et « Dispositifs »

idx_domoticz

 

me donnera les valeurs actuelles du dispositif 72 nommé ci-dessus « Temp interieur »

Ah, oui d’accord mais ou je tape le http://192……

Déjà,vérifiez que vous avez compris en le tapant DANS LA BARRE D’ADRESSE de votre navigateur web.

api_json

Ensuite des langages tels que shell (curl), python (requests), lua sont capables d’envoyer de telles chaines que vous aurez construites vous même correctement au préalable dans votre script.

On voit ici que le simple appel d’une URL renvoie un pavé de donnée en JSON, dont il faudra extraire la/les couples rubrique:valeur qui m’intéressent.

C’est le rôle d’outils comme ./jq , article ici https://easydomoticz.com/manipuler-les-donnees-json-de-domoticz-en-shell/ vers lequel je vous renvoie pour les bases de l’extraction.

N.B : Pour aider à la lecture de fichiers json il y a ici http://jsonviewer.stack.hu/un outil qui reformate de façon claire les données que vous lui donnerez par un copier/coller.

 

Voila, normalement vous devriez maintenant mieux voir le rôle de l’API JSON de Domoticz, et comprendre comment activer, obtenir des données.

 

Pour toute question technique concernant cet article, veuillez utiliser les forum situés à https://easydomoticz.com/forum/

Les périphériques USB, les Raspberry et Domoticz

Question récurrente du débutant sur Raspberry et Domoticz, la déclaration et l’utilisation des ports USB sur le Raspberry et leur utilisation au sein de Domoticz.

Car, un peu comme dans Windows, les ports USB affectés à un USB peuvent changer ou tout du moins on aime bien savoir que le rfxcom est USB10 et le z-wave USB11, voyons donc cette méthode dite des « persistent USB »

L’article d’origine ici https://www.domoticz.com/wiki/PersistentUSBDevices

L’exemple ci dessous est celui de la connexion d’ un stick Z-Wave Aeon Labs Serie 2

z-stick z-wave

z-stick z-wave

Installation

Je ne vais pas réinventer la roue, mais passer en revue les trucs incontournables pour la mise en place.

J’ai déjà un module Rfxcom sur le USB, on peut le constater avec un

qui affiche plein d’infos et entre autre une ligne ID_VENDOR=RFXCOM dont on se servira par la suite, ou toute autre ligne qui ne se répète qu’une fois sur tous vos USB pourra servir (ID_SERIAL_SHORT est pas mal aussi).

Estimant que le Z-stick devrait être en USB1,  un

me donne

En effet la ligne ID_Vendor_Enc affiche Silicons Labs, c’est donc bien le Z-Stick AEON qui est sur USB1.

Fixons définitivement cette affectation dans le Raspberry  sur un port USB de notre choix: USB11 par exemple.

ATTENTION :

Il est déconseillé de garder USB01,USB02 dans Domoticz à cause des zéros préliminaires et il faut préférer des notations à 2 chiffres sans 0 préliminaires 10,11…(c.f. le wiki de Domoticz (http://www.domoticz.com/wiki/PersistentUSBDevices)

Je nommerai USB11 mon stick Z-Wave.

On fait un

Notez ou copiez les lignes, (avancez par appui sur la touche espace) et trouvez

  • idVendor
  • idProduct
  • iSerial (éventuellement)

Ici j’ai  idVendor=10c4 et IdProduct=ea60

Pour cela installons des USB persistants et afin d’éviter que les ports USB changent à chaque fois (comme dans Windows) , on fixe dans un fichier les liens entre le nom du périphérique et le port USB que l’on veut toujours utiliser.

On configure  donc  le fichier /etc/udev/rules.d/99-usb-serial.rules

On reconnait les ID_VENDOR notés plus haut.

Un reboot.

Paramétrage Domoticz

Repassez dans la config Domoticz à « Configuration/Matériel »

Ajoutez un matériel Open-Zwave-USB et affectez le selon votre config du fichier 99-usb-serial.rules

Config_usb_Domoticz

Config_usb_Domoticz

Idem pour le RfxCom à lier au USB10

Et voila, maintenant vous devez avoir un périphérique USB définitivement lié à votre Domoticz, elle est pas belle la vie !

Pour toute question technique concernant cet article, veuillez utiliser les forum situés à https://easydomoticz.com/forum/

Mon premier script Lua dans Domoticz : La mise en oeuvre

Cet article fait suite à deux autres permettant de poser les bases du langage Lua dans Domoticz.

Le premier  (https://easydomoticz.com/point-scripts-lua/)  décrivait quels étaient les principes de fonctionnement des script Lua.

Le second donnait quelques notions de langage.

Ici pour faire suite nous allons prendre un exemple que nous allons dérouler et complexifier étape par étape.

L’exemple que je souhaite détailler ici part du fait que je possède un capteur de luminosité, des volets roulants. Je voudrais que lorsque la luminosité descend en dessous de 170 et que il est plus de 17h30, fermer tous les volets automatiquement. 😯

fenetres_maison

N.B :Pour simplifier j’ai rassemblés tous (!) mes volets roulants au sein d’un groupe (une scène au sens Domoticz)  pour pouvoir les commander tous ensemble.

Dans un pseudo langage on pourrait écrire :

  • A chaque fois que la valeur de mon capteur de luminosité change

je regarde si il est plus de 17H30

ET si

elle est inférieure a 170

ALORS

je passe le groupe des volets à ON

Ce qui signifie qu’il nous faut un script basé sur les devices puisque je cherche à déclencher tout cela lorsque la luminosité change, il faudra récupérer la valeur de notre capteur , la comparer à un seuil, aller chercher l’heure actuelle la comparer à un seuil horaire, puis passer le groupe de volets à ON.

N.B : il y a un petit bug de conception car une fois que les volets vont être fermés, si j’allume puis éteint la lumière de mon salon, la luminosité va changer, il sera plus de 17h30 et on tentera de fermer les volets en permanence alors qu’ils le sont déjà.

Lire la suite

Pour toute question technique concernant cet article, veuillez utiliser les forum situés à https://easydomoticz.com/forum/

Mon premier script Lua dans Domoticz : Les fondations

Nous avons vu précédemment https://easydomoticz.com/point-scripts-lua/ quels sont les principes de fonctionnement des script Lua au sein de Domoticz, voyons dans cet article les premières base de la rédaction de scripts puis nous prendrons un exemple que nous allons dérouler et complexifier de bout en bout afin de voir quelques instructions.

Les bases des scripts : Avoir les idées claires

idees

Avant toute chose, il faut que vous ayez les idées claires concernant les actions que vous devez réaliser, prenez un papier et un crayon et écrivez en français ce que vous devez faire.

Partant du fait que je possède un capteur de luminosité, des volets roulants que j’ai tous rassemblés dans un groupe (une scène au sens Domoticz)  pour pouvoir les commander tous ensemble, je voudrais que lorsque la luminosité descend en dessous de 170 et que il est plus de 17h30, fermer tous les volets.

 

Ce qui pourrait commencer à se traduire par :

  • A chaque fois que la valeur de mon capteur de luminosité change

je regarde si elle est inférieure a 170

ET si

il est plus de 17H30

ALORS

je passe le groupe des volets à ON

Ce qui signifie qu’il nous faut un script basé sur les devices puisque je cherche à déclencher tout cela lorsque la luminosité change, il faudra récupérer la valeur de notre capteur , la comparer à un seuil, aller chercher l’heure actuelle la comparer à un seuil horaire, puis passer le groupe de volets à ON.

N.B : il y a un petit bug de conception car une fois que les volets vont être fermés, si j’allume puis éteint la lumière de mon salon, la luminosité va changer, il sera plus de 17h30 et on tentera de fermer les volets alors qu’ils le sont déjà.

Lire la suite

Pour toute question technique concernant cet article, veuillez utiliser les forum situés à https://easydomoticz.com/forum/

Le point sur les scripts lua de Domoticz

Vous le savez logo_domoticzincorpore le langage Lua

au même titre que  wc

ou bien fc

Essayons, nous aussi, de jouer avec et de préciser les bases de l’utilisation de ces scripts qui parfois déroutent les débutants.

Il ne s’agit pas ici de faire un cours de lua mais de détailler l’intégration de ces scripts dans Domoticz.

La page source sur le wiki Domoticz https://www.domoticz.com/wiki/Events#Using_the_events_system

Généralités

Il en existe de 4 types différents basés sur les événements qui surviennent sur le matériel, le temps, les variables, le panel de sécurité. Par événement on entend toute modification qui survient.

Il est important de comprendre (et je le répéterai)  que TOUS les scripts événements se déclenchent à toute modification sur l’événement correspondant (changement d’état d’un des matériels, toutes les minutes, à chaque changement d’une variable).

 

  • Tous les scripts Lua se trouvent dans le dossier domoticz/scripts/lua
  • Ils finissent par l’extension .lua sinon ils ne sont pas exécutés par Domoticz
  • Pour nos amis modifiant les fichiers sous Windows, enregistrez les en UTF8 sans BOM (Notepad++)
  • Ils n’ont pas besoin d’être chmodés (pas de chmod +x, +777) chrgp … non plus
  • Les scripts ne sont pas lancés en tache de fond, il sont lancés par Domoticz et n’ont que 10 secondes pour faire leur boulot, passé ce temps Domoticz les tue. En vertu de quoi évitez les sleep (20), d’interroger des services web qui répondent trop lentement …
  • Les noms à utiliser à l’intérieur des scripts sont ceux donnés dans la colonne Nom des périphériques, respectez EXACTEMENT l’orthographe majuscules/minuscules/espaces/accent. Et pour ne pas être embêtés bannissez les espaces/accents/caractères bizarres (‘/&…) en renommant votre matériel
  • Les valeurs reçues des capteurs ne sont pas modifiables via Lua, utilisez JSON
  • Tous les script doivent contenir un bloc commandArray={} puis return commandArray contenant les instructions à effectuer

Lire la suite

Pour toute question technique concernant cet article, veuillez utiliser les forum situés à https://easydomoticz.com/forum/