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