Archives par étiquette : Plugin

Tutoriel Jeedom n°2 : Des commandes et des tâches

Introduction

Dans la continuité de mon apprentissage, je me suis attaqué aux commandes et aux tâches cron. Du coup, je vous fais un petit tutoriel sur le sujet afin de vous expliquer ce que j’ai compris. Il se peut donc qu’il y est des erreurs et je vous invite à m’en faire part si vous en voyez.

Il est conseillé de lire le premier tutoriel si vous commencez dans le développement de plugin. Vous le trouverez ici et le code source final ici.

Mise en place de l’environnement

Je vous invite une fois de plus à installer Jeedom sur votre poste et ne pas faire vos essais sur votre installation domotique.

Si n’avez pas de plugin en cours de développement, vous pouvez récupérer celui du premier tutoriel en tapant la commande suivante dans votre répertoire /var/www/html/plugins/ :

Ainsi l’ensemble des modifications se feront dans ce répertoire tutoriel. Pour la suite de ce tutoriel, l’identifiant du plugin sera donc tutoriel, vous devrez donc remplacer ce mot si vous avez donné un autre nom.

N’oubliez pas d’activer le plugin si vous voulez le voir apparaitre dans l’interface.

Du javascript dans votre plugin

Pour utiliser les commandes liées aux équipements, il faut passer par un fichier javascript qui va ajouter les lignes dynamiquement pour chaque commande dans le tableau.

Pour cela, il faut créer le fichier tutoriel.js dans le répertoire desktop/js et le charger en ajoutant dans votre fichier desktop/php/tutoriel.php :

Pour rappel, les paramètres de la fonction include_file sont :

  1. Répertoire de base dans lequel se trouve le fichier,
  2. Nom du fichier,
  3. Type du fichier,
  4. Entité dans laquelle trouver ce fichier. Si ce paramètre n’est pas renseigné, ce seront les fichiers du core de Jeedom qui seront chargés.

Dans ce fichier javascript, nous allons rajouter une fonction :

Cette fonction sera appelée dans deux cas :

  • Lorsque vous cliquez sur le bouton pour ajouter une commande,
  • Lorsque vos équipements contiennent des commandes par défaut.

Elle possède un seul paramètre _cmd qui contient les données de la commande. C’est un objet JSON qui contient les options de la commande.

Lorsque nous créons une commande manuellement, elle ne fournit pas ce paramètre, il faut donc créer l’objet, pour cela nous ajoutons le code suivant :

Ainsi la variable _cmd sera un objet JSON contenant une clé configuration vide.

Cette commande va s’ajouter dans le tableau en dessous qui ne contient pour le moment que la colonne champ.

Nous allons donc ajouter une ligne à ce tableau en javascript :

Ainsi, on créé la ligne directement avec une chaîne de caractère et on l’insère dans la balise <tbody> qui représente le contenu du tableau.

Si on clique sur le bouton pour ajouter une commande, on voit les lignes se rajouter.

On remarque dans le code l’ajout d’un champ caché qui contiendra l’identifiant de la commande.

Ajouter des champs aux commandes

Avoir des noms aux commande, c’est bien, mais faire quelque chose avec, c’est mieux.

Nous allons donc ajouter quelques colonnes à notre tableau. Celui-ci est affiché à partir du fichier desktop/php/tutoriel.php. Actuellement nous avons ceci :

Nous allons juste rajouter deux colonnes :

Nous aurons donc un type pour chaque commande (info ou action), la gestion de l’historique des données pour les infos et des actions que l’on peut réaliser pour chaque commande.

Maintenant, nous pouvons retourner dans le fichier javascript et ajouter les trois colonnes :

Nous avons 4 nouvelles parties :

L’identifiant

L’identifiant de la commande est indiqué dans un champ caché qui sera mis à côté du nom.

Historique

Cette case à cocher permet de conserver un historique de la valeur de cette commande.

Actions

Trois balises qui permettent de :

  • Configurer la commande,
  • Tester la commande,
  • Supprimer la commande.

Intégration

3 lignes qui configurent la ligne du tableau :

  1. Ajoute la ligne au tableau,
  2. Sélectionne la dernière ligne (celle que l’on vient d’ajouter) et configure les valeurs,
  3. Configure la gestion des types de la commande.

Tests

On peut maintenant ajouter des commandes

Vous pouvez tester les différents éléments, Jeedom s’occupe de la gestion dynamique de la commande.

Nous avons des commandes mais notre équipement n’est pas activé (ni visible), nous allons donc remédier à cela.

Un équipement activé et visible

Ces options s’ajoutent dans le fichier desktop/php/tutoriel.php dans le panneau de commande de l’équipement. Ainsi nous allons ajouter deux champs en dessous de celui du nom.

Les deux options ont l’attribut data-l1key avec une valeur isEnable pour l’activation et isVisible pour la visibilité.

Lorsque vous actualisez la page, vous aurez la possibilité d’activer votre équipement.

Seulement, rien ne se passe. C’est normal car nous n’avons aucun traitement des actions.

Malgré l’activation de l’équipement, les commandes ne font toujours rien. C’est normal car nous n’avons pas dit à Jeedom comment traiter celles-ci.

Exécuter une action

Lorsque vous cliquez sur Tester, Jeedom exécute une requête Ajax et appelle la méthode execute de la classe tutorielCmd définit dans le fichier core/class/tutoriel.class.php de votre projet.

Pour le moment cette méthode est vide :

Pour vérifier si cette méthode est bien appelée, nous allons inscrire un message dans les journaux de Jeedom. Pour cela, ajoutez la ligne suivante :

Si vous cliquez sur Tester sur une commande de type action, rien ne se passera, mais vous pourrez retrouver votre message. Pour cela, rendez-vous sur Plugins -> Gestion des plugins. Vous n’aurez plus qu’à cliquer sur le bouton Tutoriel dans la section Log pour voir votre message s’afficher.

On peut ainsi afficher l’identifiant de l’équipement et le nom de la commande :

Après, on peut lancer un processus ou tout ce que l’on veut d’autre, cependant, il n’est pas pratique de demander à l’utilisateur de créer les commandes une par une.

Créer des commandes par défaut

Nous allons ajouter deux commandes par défaut. La première sera une commande d’état qui fournira une donnée et la seconde sera une action qui actualisera la donnée.

Dans ce fichier core/class/tutoriel.class.php, nous allons maintenant aller dans la classe de l’équipement tutoriel hérité de eqLogic.

Dans cette classe, on peut trouver 8 méthodes particulières. La documentation de Jeedom fournit les informations suivantes :

  • preInsert ⇒ Méthode appelée avant la création de votre objet
  • postInsert ⇒ Méthode appelée après la création de votre objet
  • preUpdate ⇒ Méthode appelée avant la mise à jour de votre objet
  • postUpdate ⇒ Méthode appelée après la mise à jour de votre objet
  • preSave ⇒ Méthode appelée avant la sauvegarde (création et mise à jour donc) de votre objet
  • postSave ⇒ Méthode appelée après la sauvegarde de votre objet
  • preRemove ⇒ Méthode appelée avant la suppression de votre objet
  • postRemove ⇒ Méthode appelée après la suppression de votre objet

On ne peut pas créer les commandes à n’importe quel moment sinon l’équipement n’existera pas encore ou ce sera trop tard. Généralement, les commandes sont créées dans la méthode postUpdate. Nous allons donc ajouter nos commandes par défaut :

On voit ici la création des deux commandes. La première qui s’appellera Données fournit une information de type string. La deuxième est une action comme celle que nous avons créé précédemment.

On peut remarquer setLogicalId qui permet de donner un code à notre commande ce qui permet de traduire les noms affichés. Ce sera ce champ qui sera maintenant vérifier lors d’une requête Ajax.

On peut maintenant créer un objet. Vous aurez deux commandes créées :

Il faudra avant tout activer votre objet et le sauvegarder pour pouvoir les utiliser :

Des commandes qui font des choses

Pour l’exemple, nous allons modifier la valeur stockée dans la commande Données en mettant l’heure à chaque fois que l’on demande un rafraichissement. Nous allons donc modifier la méthode execute :

Maintenant, nous détectons la commande refresh. Nous allons ensuite rechercher la commande data. Puis nous lui affectons une valeur que nous sauvegardons.

On peut ensuite cliquer sur Tester de la commande Rafraichir, puis Tester sur la commande Données qui vous donnera l’heure :

Mettre à jour régulièrement nos données

C’est bien de forcer le rafraichissement d’une donnée, mais c’est mieux de ne pas avoir à le faire manuellement. Pour cela nous allons utiliser une tâche planifiée. Jeedom utilise le système cron et implémente certaines fonctions afin de faciliter son utilisation.

Pour cela, il suffit de déclarer une méthode dans votre classe tutoriel qui va s’exécuter toutes les 30 minutes :

A partir de ce moment, vous pourrez voir que votre plugin utilise des tâches cron :

Ce panneau vous indique également le nom des autres méthodes si vous voulez d’autres tâches planifiées à des intervalles différents.

Maintenant, nous allons juste récupérer l’ensemble des équipements liés au plugin et mettre à jour l’information comme précédemment :

Maintenant, vous pourrez-voir le résultat lorsque la tâche sera appelée. Pour forcer son exécution, vous pouvez aller dans le Moteur de tâches puis exécutez l’action plugin / cron30.

Conclusion

Maintenant, vous devriez avoir les connaissances nécessaires pour vous retrouver dans les fichiers de votre plugin et pour commencer à mettre en œuvre vos projets. Pour aller plus loin, n’hésitez pas à regarder le code source de vos plugins ou ceux accessibles sur GitHub.

Vous pourrez retrouver le code de ce tutoriel à cette adresse : https://github.com/Sylvaner/JeedomPluginTutoriel2

Tutoriel Jeedom n°1 : Réaliser son premier plugin

Introduction

Ce tutoriel a pour but de vous initier au développement de plugin pour Jeedom. Il n’a pas la prétention d’être exhaustif étant donné que je suis en train d’apprendre et qu’il y a très peu de documentation sur le sujet.

Voici les informations dont je dispose :

A partir de là, j’ai écrit un script qui permet de générer un squelette de plugin basique. Vous pouvez l’obtenir à cette adresse : https://github.com/Sylvaner/JeedomPluginSkeletonGenerator

Bien entendu pour ce tutoriel nous allons tout faire à la main.

Connaissances nécessaires

Pour le développement d’un plugin vous aurez besoin de connaitre un minimum les technologies suivantes :

  • PHP,
  • HTML/CSS,
  • Bootstrap (optionnel),
  • Javascript

Il vous faudra également beaucoup de motivation.

Préparation de l’environnement de travail

Afin de développer dans de bonnes conditions, je vous conseille d’installer Jeedom en local sur votre machine et de ne pas faire de tests sur votre installation.

Pour cela, rien de plus simple, vous exécutez les commandes suivantes à la racine de votre serveur web (habituellement /var/www/html) :

C’est dans le répertoire plugins de cette installation que vous pourrez développer votre projet (donc /var/www/html/plugins).

Pour ce tutoriel, le nom du plugin sera Tutoriel et l’identifiant sera donc tutoriel.

Structure

La première étape est de créer un répertoire qui sera l’identifiant de votre plugin, il doit être en minuscule et sans espace. Vous pouvez utiliser des underscores ( _ ) si nécessaire.

Un plugin est composé de différents répertoires donc la structure est la suivante :

  • core : Contient les fichiers internes pour le fonctionnement du plugin ;
    • ajax : Contient les fichiers répondants aux requêtes Ajax ;
    • class : Contient la classe du plugin ;
    • php : Contient des fonctions nécessaires au fonctionnement du plugin ;
  • desktop : Contient les pages affichées dans l’interface ;
    • css : Feuilles de style ;
    • js : Javascript des pages ;
    • modal : Code des fenêtres ;
    • php : Code de la page ;
  • docs : Documentation du plugin ;
    • fr_FR : Documentation en français ;
  • plugin_info : Contient des fichiers d’informations, l’icône, des scripts, etc. ;

Il y a bien sûr plein d’autres répertoires optionnels mais leur utilisation dépassent de loin l’objet de ce tutoriel.

Fichiers

Et maintenant nous pouvons mettre quelques fichiers dans ces répertoires. Nous allons donc créer l’essentiel.

plugin_info/info.json

Ce fichier contient les informations du plugin au format JSON.

Il contient les informations suivantes au minimum :

  • id : Identifiant du plugin,
  • name : Nom du plugin,
  • licence : Licence sous laquelle le plugin est distribuée,
  • require : Version minimum de Jeedom nécessaire,
  • category : Catégorie du plugin pour la classification, la liste complète peut être trouvé dans le code contenu dans le fichier core/class/plugin.class.php de Jeedom accessible à cette adresse : https://github.com/jeedom/core/blob/beta/core/class/plugin.class.php,
  • hasDependency : Indique si des dépendances doivent être prises en compte,
  • hasOwnDaemon : Indique si le plugin possède un service,
  • maxDependancyInstallTime : Temps d’installation maximum des dépendances,
  • documentation : Lien internet des documentations,
  • changelog : Lien internet pour informer des changements entre les versions.

Pour notre exemple, le fichier aura cette forme :

Il existe d’autres champs pour indiquer des informations complémentaires telles que l’auteur (autor), une description (description).

plugin_info/tutoriel_icon.png

Icône du plugin, pour les dimensions je vous invite à vous calquer sur celui d’un autre plugin.

plugin_info/installation.php

Fichier appelé lors de l’installation, la mise à jour et la suppression du plugin. C’est une classe qui contient 3 méthodes pour répondre à ces différents besoins.

Comme dans la plupart des fichiers PHP de ce tutoriel, il sera nécessaire d’inclure le fichier core.inc.php de Jeedom.

core/tutoriel.class.php

Ce fichier contient le moteur du plugin. Il contient deux classes afin de ne pas simplifier la lisibilité du code.

La fonction execute de la classe tutorielCmd est appelée lorsque Jeedom exécute une commande. Les informations de cette commande sont stockées dans la variable $_options.

Premier résultat

A ce moment vous devriez avoir l’arborescence suivante :

  • tutoriel
    • core
      • ajax
      • class
        • tutoriel.class.php
      • php
    • desktop
      • css
      • js
      • modal
      • php
    • docs
      • fr_FR
    • plugin_info
      • info.json
      • installation.php
      • tutoriel_icon.png

Pour générer ceci automatiquement, vous pouvez télécharger le générateur de plugin présenté dans l’introduction et répondre aux quelques questions :

Tester son plugin pour la première fois

Vous pouvez maintenant aller sur Jeedom et activer le plugin dans le menu Plugin -> Gestion des plugins :

Cliquez sur le plugin grisé (désactivé) :

Cliquez sur Activer :

Le plugin est maintenant accessible.

Il apparait dans le menu. Si vous cliquez dessus, vous aurez une splendide page vide.

Un premier bouton

Maintenant, nous entrons vraiment dans la phase de développement du plugin.

Donc dans un premier, nous allons créer le fichier desktop/php/tutoriel.php et mettre le code suivant :

Nous allons maintenant ajouter du code HTML. N’essayez pas de ne mettre que ce qui vous semble essentiel, sinon ça ne fonctionnera pas.

Comme expliqué en introduction, je ne maitrise pas du tout la création de plugin donc je vais m’inspirer de d’autres pour trouver l’information. Je vais principalement m’appuyer sur le plugin OpenZWave qui fait partie du dépôt officiel.

Ce fichier qui contient la gestion des plugins et est divisée en 3 parties :

  1. Le menu latéral,
  2. Les listes :
    • Les actions,
    • La liste des objets,
  3. Le panneau de contrôle des objets sous forme d’onglets :
    • Le formulaire de modification d’un objet,
    • La gestion des commandes.

C’est ici une version (très) épurée et le résultat ne donne rien d’intéressant.

Nous allons ajouter un bouton permettant d’accéder à la configuration. Il devra se trouver dans la balise ayant la classe eqLogicThumbnailContainer :

Vous allez voir cet attribut style partout, une des raisons est expliquée à la fin de ce tutoriel. Je n’ai pas vu un seul plugin qui utilisait des feuilles de styles, donc tout le monde utilise l’attribut style, nous verrons plus tard s’il est possible de faire un code plus propre. Pour le moment nous nous focalisons sur le fonctionnement.

On remarque que les chaînes de caractères sont entre double crochets. Cela permettra une internationalisation du plugin par la suite.

Dans cette portion de code nous avons un bouton possédant la classe eqLogicAction ayant un attribut data-action avec la valeur gotoPluginConf.

Les icônes des boutons proviennent de la police de caractère Font Awesome dont la liste est accessible à cette adresse : https://fontawesome.com/v4.7.0/

On peut aller voir le résultat. Ça ne marchera pas en l’état, mais le bouton est bien affiché.

Charger le javascript de Jeedom

Pour que les boutons et le menu latéral fonctionne, il faut indiquer à Jeedom de charger un fichier Javascript et lui passer quelques variables.

Pour cela nous allons ajouter quelques lignes en PHP.

Au début du fichier, on obtient dans un premier temps l’identifiant du plugin avec :

Puis nous envoyons ces variables à Javascript :

Les informations sont en fait ajoutées dans des balises <script>.

Et pour finir en bas de votre page, nous insérons le fichier Javascript de Jeedom nécessaire au fonctionnement de la page.

Ce fichier sera inséré en plein milieu du code, ça ne fera qu’une balise <script> supplémentaire…

Nous avons donc le code suivant à ce stade :

Miracle, le menu latéral fonctionne et quand on clique sur la clé à molette, la fenêtre de configuration s’affiche.

Le panneau de contrôle

Maintenant nous allons ajouter le panneau de contrôle qui est affiché lorsque l’on créé un objet. Il faudra donc ajouter le code à suivre dans cette balise :

Jeedom utilise la classe eqLogic pour identifier cet élément.

La barre de bouton

Cette barre bien connue des utilisateurs s’affiche avec le code suivant. Comme précédemment, il faut se focaliser sur le fonctionnement et occulter les balises de style qui agressent la rétine.

Ici nous avons principalement du code Bootstrap avec comme précedemment la classe eqLogicAction sur les bouton et l’attribut data-action qui indique l’action à réaliser. Si vous descendez dans la page, vous verrez la barre tant attendu.

Le contenu des onglets

Les onglets étant géré par bootstrap, il y aura beaucoup de code lié à son fonctionnement.

On Remarque surtout 2 lignes intéressantes :

On voit que les attributs d’un objet possèdent la class eqLogicAttr et que l’identifiant de cet attribut est défini par data-l1key.

Ça fonctionne. Tout va bien pour le moment sauf que le panneau devrait être caché par défaut. C’est normal j’ai volontairement retiré une partie du code.

Ainsi la ligne :

Va devenir :

On remarque le “display: none” qui cache bien le contenu par défaut.

Le bouton ajouter

Nous avons tout mis en place maintenant, il nous faut la possibilité de rajouter des objets, et pour cela il nous faut LE bouton +.

On cherche dans le code du plugin mobile cette fois ci, on trouve un bout de code et on obtient :

Ce qui donne :

Petit moment d’adrénaline quand on appuie sur le bouton +, on nomme le nouvel objet et rien ne se passe.

En fait l’objet a bien été enregistré, l’exécution du javascript ne fonctionne pas mais rien dans la console. Il doit manquer quelque chose, mais quoi…

Affichage des objets

On ne peut pas les voir, mais ils sont bien là. Pour cela nous allons ajouter une zone d’affichage des objets.

Donc nous allons ajouter la ligne suivante dans après la commande sendToVarJS :

Ainsi le tableau $eqLogics contiendra tous les objets du plugin.

Pour les afficher, nous allons ajouter une zone entre la liste des commandes et le panneau de contrôle. Si on vous demande un code HTML qui ne respecte aucune bonne pratique, celui-ci devrait convenir :

Nous avons donc ici une boucle foreach sur le tableau d’objets duquel on extrait l’identifiant $eqLogic->getId() et le nom lisible $eqLogic->getHumanName(true, true). Sinon, l’icône a les mêmes propriétés que les boutons précédemment créés.

A ce moment votre devrait ressembler à ceci :

On essaie l’affichage.

Merveilleux, tout s’affiche. Mais ça ne fonctionne pas.

Je l’avais dit, il faut bien tout reprendre car sinon nous allons avoir de nombreux problèmes. Et donc là, c’est normal nous n’avons pas rempli le panneau latéral.

Donc si vous laissez le menu à gauche vide, menu que personnellement je n’utilise jamais, et bien ça ne fonctionne pas.

La panneau latéral

Alors là du coup c’est simple, la structure est tout le temps la même.

Délimitant la liste du panneau latéral.

Nous allons insérer :

  • un bouton, sans balise <li> (n’essayez pas de faire autrement sous peine de problèmes),
  • un champ pour filtrer,
  • la liste des objets.

Ce qui nous donne le code suivant :

Magnifique maintenant tout fonctionne.

On peut ajouter, modifier et supprimer des objets.

Amélioration du code

Maintenant, nous avons le code suivant :

Il fonctionne donc ce tutoriel pourrait s’arrêter là. Mais je nous allons essayer d’améliorer le code. Nous allons donc déplacer toutes les balises styles dans une feuille de style.

Le fichier CSS

Il faudra créer un fichier tutoriel.css dans le répertoire desktop/css.Il est nécessaire de dire à Jeedom de le charger. Pour cela vous devez ajouter cette ligne au début du fichier. Cela nous fera une jolie balise de style en plein milieu de la page :

Cette commande prend 4 paramètres :

  • Répertoire,
  • Nom du fichier,
  • Type du fichier,
  • Nom du plugin.

A ce niveau, je m’étais dit « Allez HOP ! » on vire toutes les attributs de style, on colle ça dans le CSS et c’est bon.

Erreur ! Si vous faites ça, vous aurez plein de surprises car les positions des visuels sont recalculées en direct et utilisent les balises de style existante sans doute. Il n’est pas possible « facilement » de supprimer les attributs style. En fait vous ne pouvez pas à partir du moment où elles donnent des informations de dimension..

Au moins, nous allons faire une chose, supprimer la balise <center>. Elle est obsolète depuis…. 1999 (https://www.w3.org/TR/html4/present/graphics.html#edef-CENTER).

Pour cela c’est très simple, vous faites une recherche dans le code et vous supprimez <center> et </center> bien sûr. Et dans le fichier CSS, vous écrivez ceci :

Il est possible d’aller plus loin avec le CSS, mais attention, chaque modification doit être testé car si vous enlevez les informations de certaines balises, votre plugin ne fonctionnera plus du tout.

Conclusion

J’espère qu’avec ce tutoriel vous pourrez plus facilement que moi vous lancer dans le développement de plugin pour Jeedom, surtout n’hésitez pas à me contacter si vous trouvez des erreurs ou si vous voyez des améliorations à apporter à ce tutoriel.