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 :

{

"soleil : [
{
"Lever" : "07:18",
"coucher" : "07:23'",
}
]

"lune : [
{
"Lever" : "06:32",
"coucher" : "09:46''",
}
]

}

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 :

http://<username:password>domoticz-ip/json.htm?la_commande_api

 

  • <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 :

....../json.htm?type=devices&rid=IDX

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

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

idx_domoticz

exemple . http://192.168.1.81:8080/json.htm?type=devices&ridx=72

 

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/
Posted in Débutants, domoticz, domotique, logiciel and tagged , , .

5 Comments

  1. une petite erreur qui fait que ca marche pas :

    au lieu de :

    http://192.168.1.81:8080/json.htm?type=device&ridx=72

    mettre

    exemple . http://'IP du serveur':'port'/json.htm?type=devices&rid='ldx du device'
    http://192.168.70.115:8080/json.htm?type=devices&rid=22

    enfin cher moi sur raspb-pi et sous wheesy

Comments are closed.