language
keyboard_arrow_up
language

Plugin permettant d’exécuter des scripts (shell, php, ruby…​), des requêtes http, de récupérer des informations dans du XML ou JSON.

Configuration du plugin

La configuration est très simple, après téléchargement du plugin, il vous suffit de l’activer et c’est tout.

script1

La seule option est l’endroit où jeedom met les scripts par défaut, il est conseillé de ne pas y toucher.

Configuration des équipements

La configuration des équipements Script est accessible à partir du menu plugin :

script2

Voilà à quoi ressemble la page du plugin Script (ici avec déjà 1 équipement) :

script3

Vous retrouvez ici la liste de vos Scripts. Une fois que vous cliquez sur un équipement vous obtenez :

script4

Tip

Comme à beaucoup d’endroits sur Jeedom, mettre la souris tout à gauche permet de faire apparaître un menu d’accès rapide (vous pouvez à partir de votre profil le laisser toujours visible).

Vous retrouvez ici toute la configuration de votre équipement :

  • Nom de l’équipement script : nom de votre équipement script

  • Catégorie : les catégories de l’équipement (il peut appartenir à plusieurs catégories)

  • Activer : permet de rendre votre équipement actif

  • Visible : le rend visible sur le dashboard

  • Objet parent : indique l’objet parent auquel appartient l’équipement

  • Auto-actualisation : permet de spécifier un cron d’actualisation automatique pour toutes les commandes de type info.

En dessous vous retrouvez la liste des commandes :

  • Nom : Ce champ contient le nom que vous souhaitez donner à votre commande/information.

  • Icône : Ce champ permet d’associer une icône à votre nom (dans ce cas Jeedom remplace le nom par l’icône dans le dashboard).

  • Type de script :

    • Le type http : permet d’envoyer une requête vers un équipement externe sans forcément attendre un retour de cette commande. L’exemple qui servira de support au type http sera la configuration d’une requête vers une Vera pour allumer une lumière.

    • Le type script : sert principalement à lancer des scripts internes à Jeedom. L’exemple qui servira de support au type script sera la configuration du script de monitoring température du raspberry disponible sur le market.

    • Le type XML : permet de rapatrier des informations encodées en XML depuis un équipement distant. L’exemple qui servira de support au type XML sera la configuration du script pour interroger un Eco-Device.

    • Le type JSON : permet de rapatrier des informations encodées en JSON depuis un équipement distant. L’exemple qui servira de support au type JSON sera la configuration du script pour interroger Sickbeard (ou XBMC).

  • le type et le sous-type

  • Le champ requête

    • Ce champ doit contenir la requête en elle-même, ou le chemin du script si le champ “type de script” est script. Le bouton “parcourir” : permet de sélectionner le fichier contenu dans le dossier interne à Jeedom.

      Tip

      Ce dossier est accessible en SSH dans /usr/share/nginx/www/jeedom/plugins/script/core/ressources/. Pour info, la commande SSH pour attribuer les droits www-data à un fichier est : sudo chown www-data:www-data NOMDUSCRIPT.EXTENSION. A savoir que pour exécuter un script, celui-ci doit avoir les droits www-data.

    • Le bouton Editer : permet d’éditer à l’aide d’un éditeur de code interne un des fichiers contenus dans le répertoire permettant l’accès au code du fichier.

    • Le bouton Nouveau : permet de créer un fichier de commande.

      Tip

      Ne pas oublier de saisir le nom du fichier ainsi que son extension complète sous peine de voir votre superbe script ne pas fonctionner. Sans extension Jeedom ne saura pas reconnaiître le langage associé à votre fichier. CF : Généralité

    • Le bouton Supprimer : permet de supprimer un fichier de commande.

    • Le bouton Partager : un des plus importants, et après avoir validé les CGU développeurs dans votre profil sur le market, permet de partager votre création avec la communauté.

  • Le champ Options : Champ aux options variables suivant le choix du type de script.

  • unité : unité de la donnée (peut être vide).

  • min/max : bornes de la donnée (peuvent être vides).

  • historiser : permet d’historiser la donnée.

  • afficher : permet d’afficher la donnée sur le dashboard.

  • évènement : retour en cas d’évènements. Dans le cas du RFXcom cette case doit toujours être cochée car on ne peut pas interroger un module RFXcom.

  • Autoriser memcache : autorise Jeedom à utiliser du cache pour la valeur (par défaut 5 min) avant de réexécuter le script pour avoir à nouveau la valeur.

  • Lifetime cache : permet de modifier la durée de vie du cache (par défaut 5 min).

Important

Il faut eviter,autant que possible, dans le chemin du script ou dans les parametres de celui-ci les caractères spéciaux. Les caractères autorisés étant : les chiffres, les lettres (majuscule ou minuscule)

script5

Permet d’appeller une url ou de récupérer le retour d’une URL.

  • une case à cocher “Ne pas vérifier SSL” : si cochée, permet à Jeedom de ne pas envoyer les champs “Utilisateur” et “Mot de passe” à la requête. Jeedom ne cherchera pas à s’identifier au site/machine distant.

  • une case à cocher “Autoriser réponse vide” : si cochée, permet à Jeedom de ne pas attendre de réponse, ou d’ignorer toute réponse à la trame émise. En général, on coche si Jeedom nous renvoit un “Curl error : Empty reply from server”.

  • une case à cocher “Ne jamais remonter les erreurs” : permet de ne pas remonter d’alerte en cas d’erreur.

  • un champ “timeout” : sans être renseigné, le timeout de la requête vaut par défaut 2 secondes, sinon il vaut la valeur renseignée.

  • un champ “Essais au maximum” : 4 essais au maximum par défaut.

  • un champ “Utilisateur” : pour renseigner un nom d’utilisateur.

  • un champ “Mot de passe” : pour renseigner un mot de passe.

Le choix HTML

script8

Permet de parser une page Web (fichier HTML) pour récupérer une valeur dessus. La syntaxe est la même que pour jquery.

Le champ option possède un champ “URL du fichier HTML” : ce champ contient donc le lien vers la machine hébergeant le fichier HTML en question.

Le choix XML

script6

Permet de récupérer du xml et d’aller chercher spécifiquement une valeur dedans.

Le champ option possède un champ “URL du fichier XML” : ce champ contient donc le lien vers la machine hébergeant le fichier XML en question.

Important

Il n’est possible de récupérer que des valeurs, les attributs ne peuvent être récuperés.

Le choix JSON

script7

Permet de récupérer du json et d’aller chercher spécifiquement une valeur dedans.

Le champ option possède un champ “URL du fichier JSON” : ce champ contient donc le lien vers la machine hébergeant le fichier JSON en question.

Exemple HTTP : Pilotage d’une Vera

L’exemple est basé sur une Vera et consiste à piloter une ampoule dimmable. Je ne vais pas m’étendre sur la manière de piloter une Vera par requête http, le forum TLD est rempli de réponses. De plus, l’exemple correspond à mon type de matériel et devra être adapté au vôtre.

Tip

Une méthode pour ceux qui tâtonnent pour l’écriture de requêtes http, valider d’abord la syntaxe dans votre navigateur et seulement ensuite passer à la configuration sous Jeedom. Quand un script Action ne fonctionne pas, passer en script Info/Autre permet de voir l’erreur retournée.

Allons-y :

  • On crée un équipement : par exemple LUM CUISINE (je pense qu’on a tous une cuisine sous la main)

  • On l’associe à un objet parent : par exemple VERA, moi ça me permet de centraliser toutes les commandes liées à la VERA sur un unique parent.

  • Choisissez votre catégorie.

  • Activez votre équipement, ne cochez pas visible, on verra un peu plus tard comment l’associer à un virtuel (plus sexy, plus WAF)

  • Pour l’auto-actualisation, ne rien mettre, il s’agit d’une commande impulsionnelle liée à un appui sur un bouton ou un scénario !

  • Ajoutez une commande script

  • Pensez à sauvegarder

Explications :

  • Nom : 100 % car on va allumer une lumière à pleine puissance

  • Type de script : http

  • Type : Action (c’est une commande)

  • Sous type : défaut

  • Requête :

http://<IP_VERA>:3480/data_request?id=lu_action&output_format=json&DeviceNum=12&serviceId=urn:upnp-org:serviceId:Dimming1&action=SetLoadLevelTarget&newLoadlevelTarget=100

Tip

le “100” à la fin de la requête correspond au pourcentage de puissance à affecter donc mettre “0” à la fin de la requête correspond à éteindre l’ampoule.

Le bouton “test” vous permet de tester votre commande !

Vous pouvez donc multiplier les commandes dans le même équipement en mettant par exemple une commande à 60 % pour une lumière tamisée, créer une troisième à 30 % pour les déplacements nocturnes à associer dans un scénario, …​

Il est aussi possible de créer une commande de type slider en mettant le tag #slider# dans la requête :

http://<IP_VERA>:3480/data_request?id=lu_action&output_format=json&DeviceNum=12&serviceId=urn:upnp-org:serviceId:Dimming1&action=SetLoadLevelTarget&newLoadlevelTarget=#slider#

Tip

Si votre commande est de type message vous pouvez utiliser les tags #message# et #title#, idem pour une commande de type couleur avec le tag #color#, ou de type slider avec #slider# ou liste avec #select#

Exemple HTTP : Envoyer une notification à XBMC

But : Envoyer une notification vers XBMC lors de l’ouverture d’une porte d’entrée.

  • Nom : PUSH XBMC

  • Type de script : http

  • Type : Action (c’est une commande)

  • Sous-type : défaut

  • Requête :

http://IP_DE_XBMC:8080/jsonrpc?request={ %22jsonrpc%22:%222.0%22,%22method%22:%22GUI.ShowNotification%22,%22params%22:{ %22title%22:%22Mouvement%20Detecté%22,%22message%22:%22Porte%20Entrée%22},%22id%22:1}

A vous de tester ça dans un scénario par exemple !

API XBMC ici (seuls les champs notés “required” sont obligatoires)

But : Envoyer une notification vers XBMC lorsque la température tombe sous un certain seuil

Prenez l’exemple ci-dessus :

  • remplacez “Mouvement%20Détecté” par “Risque%20de%20gel”

  • remplacez “Porte%20Entrée” par “Température%20extérieur%20:%20#[EXTERIEUR][EXTERIEUR][TEMPERATURE]#%20”

Testez sur un scénario [EXTERIEUR][EXTERIEUR][TEMPERATURE] < 15 par exemple

Action : Lancez le script, via un équipement virtuel, lié à votre script !

Exemple SCRIPT

Le plus sympa mais pas le plus simple à expliquer.

Pré-requis : savoir développer un script en php, python ou ruby.

IMPORTANT

L’extension de votre script doit absolument correspondre à son type. Ex .php pour un type php. En effet Jeedom se base sur l’extension du script pour l’executable à lancer (php si .php, python si .py….)

Le script de monitoring température du Raspberry va servir d’exemple pour l’utilisation du type de script : Script

Après avoir téléchargé le script depuis le market, le bouton “Parcourir” vous permet de sélectionner le fichier temp_rasp.php.

Par curiosité, vous pouvez aller voir le contenu du fichier en appuyant sur le bouton “Editer”, vous devriez obtenir le code suivant :

Ceci est un script php qui peut tout à fait être réutilisé hors Jeedom !

 <?php
    $temp = shell_exec("cat /sys/class/thermal/thermal_zone0/temp");
    $temp = $temp / 1000;
    $temp = round($temp,1);
    echo $temp
 ?>

Note : concrètement, c’est la fonction php “echo” qui va donner la valeur à Jeedom

Les paramètres

Récupérer les infos de Jeedom pour les exploiter dans un script. La récupération dépend du type de script utilisé :

Exemple :

  • Dans la ligne : /usr/share/nginx/www/jeedom/plugins/script/core/ressources/MON_SCRIPT_PHP.php list , l’argument “list” est une chaîne de caractères (fixe) récupérée dans le script php grâce à la fonction suivante $argv[1] cf : Google pour plus de détails sur la récupération de paramètres en PHP.

  • Nous avons vu précédement qu’il était possible de récupérer des valeurs dynamiques à partir de Jeedom.

  • Dans la ligne : /usr/share/nginx/www/jeedom/plugins/script/core/ressources/radio.py VOL slider , l’argument “slider” est récupéré de cette façon argv[2]. Au moment de l’exécution du script par jeedom, il remplacera automatiquement slider par la valeur (numérique) du slider. cf : Google pour plus de détails sur la récupération de paramètres en Python.

  • Plus fort : Potentiellement, toutes les variables accessibles par Jeedom sont exploitables par le plugin script :

    • Vous voulez récupérer la valeur de la température de la cuisine pour l’historiser en dehors de Jeedom ?

    • Passer [CUISINE][CUISINE][Température] comme paramètre au script et Jeedom le remplacera par la valeur lue lors de l’envoi.

Préconisation pour tester les paramètres dans le script php :

 if (isset($argv)) {
     foreach ($argv as $arg) {
         $argList = explode('=', $arg);
         if (isset($argList[0]) && isset($argList[1])) {
             $_GET[$argList[0]] = $argList[1];
         }
     }
 }

Exemple XML simple

Voici la format du xml type :

<root>
    <led0>1</led0>
    <leds>
      <led1>toto</led1>
    </leds>
</root>

Si vous voulez la valeur de la led0 dans requête vous mettez led0. Si vous voulez la valeur de la led1 qui est le fils de leds vous mettez leds > led1.

Notez que l’élément racine <root> n’est pas à préciser dans le champ requête.

Exemple XML complexe

 <root>
   <led0>1</led0>
   <leds>
     <led1>toto</led1>
   </leds>
   <leds>
     <led1>tata</led1>
   </leds>
 </root>

la syntaxe est :

leds > 1 > led1 qui donne en réponse tata, 1 étant le numéro de rang du tableau !

Exemple XML plus complexe

<AKT_Data ID="SMS-Liste" ZeitSt="01.05.2017 18:55">
 <MesPar DH="HBCHa" StrNr="2167" Typ="02" Var="02">
   <Name>Tresa - Ponte Tresa, Rocchetta</Name>
   <Datum>01.05.2017</Datum>
   <Zeit>18:50</Zeit>
   <Wert>268.56</Wert>
   <Wert dt="-24h">268.51</Wert>
   <Wert Typ="delta24">0.051</Wert>
   <Wert Typ="m24">268.52</Wert>
   <Wert Typ="max24">268.56</Wert>
   <Wert Typ="min24">268.50</Wert>
 </MesPar>
 <MesPar DH="HBCHa" StrNr="2265" Typ="03" Var="02">
  <Name>Inn - Tarasp</Name>
  <Datum>01.05.2017</Datum>
  <Zeit>18:50</Zeit>
  <Wert>4.85</Wert>
  <Wert dt="-24h">7.98</Wert>
  <Wert Typ="delta24">-3.130</Wert>
  <Wert Typ="m24">6.15</Wert>
  <Wert Typ="max24">7.98</Wert>
  <Wert Typ="min24">4.85</Wert>
 </MesPar>
 <MesPar DH="HBCHa" StrNr="2270" Typ="02" Var="32">
  <Name>Doubs - Combe des Sarrasins</Name>
  <Datum>01.05.2017</Datum>
  <Zeit>18:00</Zeit>
  <Wert>500.65</Wert>
  <Wert dt="-24h">500.65</Wert>
  <Wert Typ="delta24">0.000</Wert>
  <Wert Typ="m24">500.65</Wert>
  <Wert Typ="max24">500.65</Wert>
  <Wert Typ="min24">500.64</Wert>
 </MesPar>
</AKT_Data>

Pour recuperer l’information du champ Wert du 1er bloc:

MesPar>0>Wert>0 qui retourne donc "268.56 "

Pour retourner l’élément suivant dans la “structure” Wert, il faut simplement indiquer le numéro d’ordre dans la structure. Ce qui donne pour l’élément ‘<Wert Typ=”delta24”>0.051</Wert>’ le code suivant :

MesPar>1>Wert>2

Pour passer au bloc “MesPar” suivant, il faut donc changer l’index en conséquence : le 1 par 2, par exemple.

ATENTION : Si dans le fichier XML l’ordre change, la requête ne fonctionne plus. Il faudra réadapter la requete en fonction de l’ordre retourné.

Exemple JSON

A l’instar du type XML, il est possible de lire des informations issues d’un retour JSON.

Pour expliquer, je vais me baser sur les informations JSON avec l’application Sickbeard (bouh …​ cpasbien) mais ici seule la technique prime, pas l’outil !

L’accès à ce fichier est possible grâce à l’URL suivante :

http://<IP_DELAMACHINEQUIEBERGESICKBEARD>:8083/api/XXXX/?cmd=history&limit=3

NOTE : XXXX est le numéro de clef api propre à chaque SICKBEARD.

Tout d’abord, avant de se lancer dans la configuration du plugin script JSON, il s’agit d’identifier correctement les infos à récupérer., car ici nous allons intégrer une notion de tableau dans les retours.

Valider l’affichage des informations à partir de votre navigateur (test sous Chrome).

Exemple de retour :

 {
     "data": [
         {
             "date": "2014-09-10 01:37",
             "episode": 4,
             "provider": "RNT",
             "quality": "SD TV",
             "resource": "XXX",
             "resource_path": "XXXX",
             "season": 2,
             "show_name": "Totovaalaplage S2E4",
             "status": "Downloaded",
             "tvdbid": XXXXX
         },
         {
             "date": "2014-09-10 01:36",
             "episode": 3,
             "provider": "RNT",
             "quality": "SD TV",
             "resource": "XXXX",
             "resource_path": "XXX",
             "season": 2,
             "show_name": "Totovaalaplage S2E3",
             "status": "Downloaded",
             "tvdbid": XXXXX
         },
         {
             "date": "2014-09-10 01:21",
             "episode": 1,
             "provider": "Cpasbien",
             "quality": "SD TV",
             "resource": "XXXX",
             "resource_path": "XXXX",
             "season": 1,
 ICI -->     "show_name": "Totovaplusauski mais Totovaalaplage S1E1",
             "status": "Snatched",
             "tvdbid": XXXX
         }
     ],
     "message": "",
     "result": "success"
 }

Dans l’hypothèse où nous voudrions retourner le show_name du 3ème élément en php (repéré ICI) , il faudrait faire : data > 2 >show_name, l’index du tableau de retour commençant à Zéro.

Dans cet exemple, le bouton “Tester” nous retournera “Totovaplusauski mais Totovaalaplage S1E1”.

Précisions :

Notez la syntaxe de la commande Requête, elle est de type élément0 > index du tableau > élément1

Inconvénients :

  • cette méthode ne permet que de récupérer un seul élément à la fois.

  • Si on désire retourner l’ensemble des valeurs de “show_name”, ce n’est malheureusement pas possible, il faudra dupliquer le script autant de fois que nécessaire.

Exemple HTML

Ici nous allons essayer de récupérer la dernière VDM.

Tout d’adord il faut configurer l’url :

http://www.viedemerde.fr

Ensuite il faut trouver le “chemin” de la dernière VDM. Pour ce faire, il faut aller sur le site puis faire clic droit sur l’élément voulu puis inspecter l’élément, on obtient :

script9

Là c’est la partie la plus complexe et qui demande un peu d’analyse. Ici mon texte est dans une balise “a” qui est lui dans un élément de type p qui est une div de class “post article”. Il faut donc que je sélectionne le premier élément div de class “post” et “article” puis le premier élément p et que je récupère tout ce qui est dans les balises “a” qu’il contient. J’ai donc : “div.post.article:first p:first a”.

On obtient donc :

script10

Pour une actualisation en temps réel, il est possible de mettre un cron de mise à jour.

Tip

Lors de la mise en place d’un cron de mise à jour, Jeedom va automatiquement cocher la case Evènement, c’est tout à fait normal.

Voilà ensuite vous pouvez imaginer un scénario qui vous envoie par SMS la dernière VDM.