Pourquoi ?

Vos scénarios conçus avec Jeedom vous permettront d’exécuter des actions de manière programmée, récurrente, ou déclenchée par une autre action. Ainsi, vous pourrez faire vivre votre installation domotique grâce aux interactions entre vos équipements intégrés à Jeedom.

Comment ?

Premièrement, rendez-vous dans « Outils » > « Scénarios » et ajoutez en un en lui donnant le nom de votre choix.

Ensuite, activez-le et rendez-le visible si vous souhaitez l’observer depuis votre dashboard.

Enfin, voyons les différentes actions/options possibles avec un scénario.

Les options dédiées aux scénarios

Premièrement, en tête de page sur la droite, vous trouverez plusieurs boutons dont voici les fonctionnalités :

• Ajouter un bloc : permet de concevoir votre scénario. Nous reviendrons dessus un peu plus tard dans ce guide.
• Variables : permet d’observer vos variables. Nous reviendrons également sur cette partie plus tard.
• Expression : test une expression pour vous en retourner le résultat.
• Exécuter : lance le scénario manuellement.
• Supprimer : supprime le scénario.
• Sauvegarder : enregistre les modifications apportées sur votre scénario.
• Edition textuelle : édite votre scénario en mode texte. A n’utiliser que si vous êtes sur de ce que vous faites.
• Template : permet d’accéder à un Market de scénarios que vous pouvez installer et utiliser.
• Exporter : exporte votre scénario.
• Log : affiche les logs du scénario, sous réserve que la génération des logs soit activée (voir les options suivantes).
• Dupliquer : créer un duplicata du scénario.
• Liens : affiche un schéma des liens entre vos différents équipements et scénarios.

Ensuite, dans l’onglet « Général » de votre scénario, vous trouverez quelques options disponibles :

• Timeout : durée maximale d’exécution du scénario. Cette option est intéressante si vous craignez de générer une boucle infinie dans votre scénario par exemple.
• Log : configuration de la génération des logs pour l’exécution de ce scénario.
• Multi-lancement : permet d’exécuter à plusieurs reprises le scénario de manière simultannée. Si l’option est décochée, l’exécution du scénario stop la précédente.
• Timeline : affiche le scénario dans la Timeline lorsque celui-ci est exécuté.
• Synchrone : exécute le scénario dans le thread courant au lieu d’un thread dédié. Ca permet d’augmenter la vitesse de lancement du scénario mais cela peut rendre le système instable. Je vous suggère d’activer ce mode que si vous savez pourquoi vous le faites.

Déclencheurs et programmation

Enfin, sur la partie droite de l’onglet « Général » vous trouverez deux manières d’exécuter vos scénarios :

• Provoqué : vous permet d’exécuter le scénario lorsqu’un évènement est observé sur une commande (l’ouverture d’une fenêtre par exemple) :

• Programmé : vous permet d’exécuter le scénario à un moment donné ou de manière récurrente.

Voici également des déclencheurs spécifiques (autre que ceux fournis par les commandes) :

• #start# : déclenché au (re)démarrage de Jeedom.
• #begin_backup# : événement envoyé au début d’une sauvegarde.
• #end_backup# : événement envoyé à la fin d’une sauvegarde.
• #begin_update# : événement envoyé au début d’une mise à jour.
• #end_update# : événement envoyé à la fin d’une mise à jour.
• #begin_restore# : événement envoyé au début d’une restauration.
• #end_restore# : événement envoyé à la fin d’une restauration.
• #user_connect# : connexion d’un utilisateur.

Vous pouvez aussi déclencher un scénario quand une variable est mise à jour en mettant : #variable(nom_variable)# ou en utilisant l’API HTTP.

Les blocs de scénarios

Lors de la conception de votre scénario vous pourrez choisir entre ces différents blocs :

• Si/Alors/Sinon : exécute l’action à l’intérieur du bloc si les conditions sont remplies.
• Action : exécute les actions définies dans ce bloc.
• Boucle : exécute le contenu du bloc Boucle X fois (X étant à définir après avoir choisi ce bloc).
• Dans : exécute le contenu du bloc Dans dans X mintues (X étant à définir après avoir choisi ce bloc). Il n’est pas possible d’exécuter le bloc dans un délai inférieur à 1 minute, mais vous pouvez utiliser la commande Pause à la place.
• A : exécute le contenu du bloc A à une heure définie. (à définir également après avoir choisi le bloc).
• Code : crée un bloc dans lequel vous pourrez coder les actions à réaliser (en PHP par exemple).
• Commentaire : commente vos scénarios (aucune action n’est réalisée sur votre scénario).

La conception du scénario

Après cela, attaquons maintenant le cœur du sujet : accédez à l’onglet « Scénario« . Ainsi, vous trouverez l’espace dédié à la création de vos blocs qui détermineront les actions que vous exécuterez, dans quel ordre, quelle condition…

Cliquez sur « Ajouter un bloc« .

Dans cet exemple je commence par choisir le bloc « Si/Alors/Sinon« . Enregistrez ensuite ce choix.

Une fois le bloc créé, vous allez pouvoir définir quelles seront les conditions pour exécuter les actions présentes dans ce bloc. Servez-vous des boutons situés à droite pour choisir dans un premier temps la commande, le scénario, ou l’équipement de désiré.

Ici par exemple, je choisi une condition relative à la température de mon séjour qui doit être inférieur à 16 degrés pour que la condition soit remplie.

Ajoutez ensuite un bloc « Action » dans le bloc « Si/Alors/Sinon« .

Utilisez ensuite les boutons situés à droite de la ligne d’action pour recherche votre commande. Ici par exemple, j’envoi un message sur Messenger dans lequel j’indique qu’il faut allumer le chauffage.

Vous remarquerez deux cases à gauche de l’action. Celles-ci permettent de :

• Désactiver l’action.
• Exécuter la commande en parallèle des autres actions. Si vous souhaitez utiliser cette option, je vous invite à prendre soin de vérifier que l’action concernée n’ait pas d’impact sur le reste du scénario.

Sauvegardez ensuite le scénario.

Pour aller plus loin

Les opérateurs, tags et fonctions ont été repris de la documentation officielle disponible ici de sorte à regrouper toutes les informations dans ce guide.

Les opérateurs de comparaison

Si vous avez besoin de vérifier plusieurs commandes dans un même bloc « Si/Alors/Sinon« , vous pouvez les ajouter en les séparant par ces opérateurs :

• == : égal à,
• > : strictement supérieur à.
• >= : supérieur ou égal à.
• < : strictement inférieur à.
• <= : inférieur ou égal à.
• != : différent de, n’est pas égal à.
• matches : contient (ex : [Salle de bain][Hydrometrie][etat] matches “/humide/” ).
• not ( …​ matches …​) : ne contient pas (ex : not([Salle de bain][Hydrometrie][etat] matches “/humide/”)).

Vous pouvez combiner n’importe quelle comparaison avec les opérateurs suivants :

• && / ET / et / AND / and : et.
• | / OU / ou / OR / or : ou.
• |^ / XOR / xor : ou exclusif.

Les tags (créés par défaut)

Les tags sont des termes à utiliser sous la forme #montag#. Ces derniers seront, à l’exécution du scénario, automatiquement remplacés par la valeur correspondante au moment où le tag sera utilisé. Voici la liste des tags disponibles :

• #seconde# : Seconde courante (sans les zéros initiaux, ex : 6 pour 08:07:06).
• #heure# : Heure courante au format 24h (sans les zéros initiaux, ex : 8 pour 08:07:06 ou 17 pour 17:15).
• #heure12# : Heure courante au format 12h (sans les zéros initiaux, ex : 8 pour 08:07:06).
• #minute# : Minute courante (sans les zéros initiaux, ex : 7 pour 08:07:06).
• #jour# : Jour courant (sans les zéros initiaux, ex : 6 pour 06/07/2017).
• #mois# : Mois courant (sans les zéros initiaux, ex : 7 pour 06/07/2017).
• #annee# : Année courante.
• #time# : Heure et minute courante (ex : 1715 pour 17h15).
• #timestamp# : Nombre de secondes depuis le 1er janvier 1970.
• #date# : Jour et mois. Attention, le premier nombre est le mois. (ex : 1215 pour le 15 décembre).
• #semaine# : Numéro de la semaine (ex : 51).
• #sjour# : Nom du jour de la semaine (ex : Samedi).
• #njour# : Numéro du jour de 0 (dimanche) à 6 (samedi).
• #smois# : Nom du mois (ex : Janvier).
• #IP# : IP interne de Jeedom.
• #hostname# : Nom de la machine Jeedom.
• #trigger# : Peut être le nom de la commande qui a déclenché le scénario, ‘api’ si le lancement a été déclenché par l’API, ‘schedule’ si il a été lancé par une programmation, ‘user’ si il a été lancé manuellement.
• #query# : interaction ayant déclenché le scénario.
• #profil# : profil de l’utilisateur ayant déclenché le scénario (peut être vide).

Les tags (crées par vos soins)

Jeedom permet également de créer ses propres tags. Imaginez que vous ayez besoin, par exemple, d’utiliser un scénario qui envoi un message à une personne via Messenger. Cependant, ce message peut varier, et il se peut aussi que vous ayez besoin d’envoyer ce message à une ou plusieurs personnes. Nous avons donc deux variables :

• Le message.
• La/Les personne(s).

Pour gérer ma liste de destinataires, je crée d’abord un scénario dédié à l’envoi de message.

Ainsi, selon la valeur que je passerai en paramètre pour la variable #qui# en appelant mon scénario, je pourrai choisir quel sera le destinataire du message. Aussi, je pourrai adapter le message selon la situation. Cependant, attention à n’utiliser que des lettre de a à z : pas de majuscules, pas d’accents et pas de caractères spéciaux.

Ensuite, je crée un scénario qui va appeler celui-ci en lui donnant la valeur de mon choix pour chacun de ces paramètres. A titre d’exemple, je vous suggère d’observer le scénario d’alerte pour sortir les poubelles qui se situe à la fin du tuto.

Fonctions de calcul

• average(commande,période) et averageBetween(commande,start,end)
  Retourne la moyenne de la commande sur la période (period=[month,day,hour,min] ou expression PHP) ou entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• min(commande,période) et minBetween(commande,start,end)
  Retourne le minimum de la commande sur la période (period=[month,day,hour,min] ou expression PHP) ou entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• max(commande,période) et maxBetween(commande,start,end)
  Retourne le maximum de la commande sur la période (period=[month,day,hour,min] ou expression PHP) ou entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• statistics(commande,calcul,période) et statisticsBetween(commande,calcul,start,end)
  Retourne le résultat de différents calculs statistiques (sum, count, std, variance, avg, min, max) sur la période (period=[month,day,hour,min] ou expression PHP) ou entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• tendance(commande,période,seuil)
  Retourne la tendance de la commande sur la période (period=[month,day,hour,min] ou expression PHP).
• stateChanges(commande,[valeur], période) et stateChangesBetween(commande, [valeur], start, end)
  Retourne le nombre de changements d’état (vers une certaine valeur si indiquée, ou au total sinon) sur la période (period=[month,day,hour,min] ou expression PHP) ou entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• median(commande1,commande2…​.commandeN)
  Retourne la médiane des valeurs.
• time_op(time,value)
  Retourne le résultat des opérations sur le temps, avec time=temps (ex : 1530) et value=valeur à ajouter ou à soustraire en minutes.
• odd(valeur)
  Retourne 1 = impair, 0 = pair.
• round(valeur,[decimal])
  Retourne l’arrondi au-dessus, [decimal] nombre de décimales après la virgule.

Fonctions de durée

• duration(commande, valeur, période) et durationbetween(commande,valeur,start,end)
  Retourne la durée en minutes pendant laquelle l’équipement avait la valeur choisie sur la période (period=[month,day,hour,min] ou expression PHP) ou entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• stateDuration(commande)
  Retourne la durée en secondes depuis le dernier changement de valeur. Cependant, -1 = aucun historique n’existe ou la valeur n’existe pas dans l’historique et -2 = la commande n’est pas historisée.
• lastChangeStateDuration(commande,valeur).
  Retourne la durée en secondes depuis le dernier changement d’état à la valeur passée en paramètre. Cependant, -1 = aucun historique n’existe ou la valeur n’existe pas dans l’historique et -2 = la commande n’est pas historisée.
• lastStateDuration(commande,valeur)
  Retourne la durée en secondes pendant laquelle l’équipement a dernièrement eu la valeur choisie. Cependant, -1 = aucun historique n’existe ou la valeur n’existe pas dans l’historique et -2 = la commande n’est pas historisée.
• lastScenarioExecution(scenario)
  Retourne la durée en secondes depuis le dernier lancement du scénario.

Fonctions de dates

• collectDate(cmd,[format])
  Retourne la date de la dernière donnée pour la commande donnée en paramètre, le 2ème paramètre optionnel permet de spécifier le format de retour (détails ici). Cependant, -1 = commande introuvable et -2 = la commande n’est pas de type info.
• valueDate(cmd,[format])
  Retourne la date de la dernière donnée pour la commande donnée en paramètre, le 2ème paramètre optionnel permet de spécifier le format de retour (détails ici). Cependant, -1 = commande introuvable et -2 = la commande n’est pas de type info.
• lastCommunication(equipment,[format])
  Retourne la date de la dernière communication pour l’équipement donnée en paramètre, le 2ème paramètre optionnel permet de spécifier le format de retour (détails ici). Cependant, -1 = commande introuvable.
• time_between(time,start,end)
  Retourne si un temps est entre deux valeurs avec time=temps (ex : 1530), start=temps, end=temps. Les valeurs start et end peuvent être à cheval sur minuit.
• time_diff(date1,date1[,format])
  Retourne la différence entre 2 dates (au format AAAA/MM/JJ HH:MM:SS). Par défaut, la méthode retourne le nombre de jours (ou secondes (s), minutes (m), heures (h)).

Fonctions de valeurs

• variable(mavariable,valeur par défaut)
  Retourne la valeur d’une variable ou de la valeur souhaitée par défaut.
• lastBetween(commande,start,end)
  Retourne la dernière valeur enregistrée pour l’équipement entre les 2 bornes demandées (sous la forme Y-m-d H:i:s ou expression PHP).
• value(cmd)
  Retourne la valeur d’une commande si elle n’est pas donnée automatiquement par Jeedom (cas lors du stockage du nom de la commande dans une variable).
• tag(montag,[defaut])
  Retourne la valeur d’un tag ou la valeur par défaut si il n’existe pas.
• triggerValue(commande)
  Retourne la valeur du déclencheur du scénario.

Les fonctions des blocs de scénarios

• Pause (sleep)
  Pause de x seconde(s).
• variable (variable)
  Création/modification d’une variable.
• Supprimer variable (delete_variable)
  Supprime une variable.
• Scénario (scenario)
  Contrôle vos scénarios avec possibilité d’y mettre un tag.
• Stop (stop)
  Arrête le scénario.
• Attendre (wait)
  Attend jusqu’à ce que la condition soit valide (maximum 2h).
• Aller au design (gotodesign)
  Affiche sur tous les navigateurs le design demandé.
• Ajouter un log (log)
  Ajoute un message dans les logs.
• Créer un message (message)
  Ajoute un message dans le centre de messages.
• Activer/Désactiver Masquer/afficher un équipement (equipement)
  Modifie les propriétés d’un équipement visible/invisible, actif/inactif.
• Faire une demande (ask)
  Pose une question à l’utilisateur. Attention, cette fonction est bloquante : tant qu’il n’y a pas de réponse ou que le timeout n’est pas atteint, le scénario attend.
• Arrêter Jeedom (jeedom_poweroff)
  Eteint Jeedom.
• Redémarrer Jeedom (jeedom_reboot)
  Redémarre Jeedom.
• Retourner un texte/une donnée (scenario_return)
  Retourne un texte ou une valeur pour une interaction par exemple.
• Icône (icon)
  Change l’icône de représentation du scénario.
• Alerte (alert)
  Affiche un message d’alerte sur tous les navigateurs qui ont une page Jeedom ouverte. Aussi, vous pouvez choisir 4 niveaux d’alerte.
• Pop-up (popup)
  Affiche un pop-up qui doit absolument être validé sur tous les navigateurs qui ont une page Jeedom ouverte.
• Rapport (report)
  Envoi une vue au format PDF,PNG, JPEG ou SVG via une commande de type « message ». Nécessite du HTTP ou HTTPS signé.
• Supprimer bloc DANS/A programmé (remove_inat)
  Supprime la programmation de tous les blocs DANS et A du scénario.
• Evènement (event)
  Pousse une valeur dans une commande de type information de manière arbitraire.
• Tag (tag)
  Ajoute/modifie un tag (n’existe que pendant l’exécution en cours du scénario à la différence des variables qui survivent à la fin du scénario).

Autres fonctions

• scenario(scenario)
  Retourne le statut du scénario : 1 = en cours, 0 = arrêté, -1 = désactivé, -2 = n’existe pas et -3 = état incohérent. Pour avoir le nom “humain” du scénario, utilisez le bouton à droite de la recherche de scénario.
• eqEnable(equipement)
  Retourne l’état de l’équipement : -2 = introuvable, 1 = actif et 0 = inactif.
• name(type,commande)
  Retourne le nom de la commande, équipement ou objet. « Type » vaut soit cmd, eqLogic ou object.
• color_gradient(couleur_debut,couleur_fin,valuer_min,valeur_max,valeur) :
  Retourne une couleur calculée par rapport à valeur comprise entre valeur_min et valeur_max dans l’intervalle couleur_debut/couleur_fin (périodes et intervalles utilisables avec des expressions PHP comme par exemple)
• rand(1,10)
  Retourne un nombre aléatoire de 1 à 10.
• randText(texte1;texte2;texte…​..)
  Retourne un des textes aléatoirement.
• randomColor(min,max)
  Retourne une couleur aléatoire compris entre 2 bornes ( 0 => rouge, 50 => vert, 100 => bleu).
• trigger(commande)
  Retourne le déclencheur du scénario ou de savoir si c’est bien la commande passée en paramètre qui a déclenché le scénario.
• formatTime(time)
  Retourne une chaine #time# de manière formatée.
• floor(time/60)
  Retourne une conversion des secondes en minutes ou des minutes en heures (floor(time/3600) pour des secondes en heures).

Périodes et intervalles disponibles

• Now : maintenant
• Today : 00:00 aujourd’hui (permet par exemple d’obtenir des résultats de la journée si entre ‘Today’ et ‘Now’)
• Last Monday : lundi dernier à 00:00
• 5 days ago : il y a 5 jours
• Yesterday noon : hier midi

Exemples de scénarios

Rappel : sortir les poubelles (programmé)

Ce scénario programmé basé sur l’heure vous alerte via la méthode de votre choix (ici via Messenger) qu’il faut sortir les poubelles. Par exemple, j’ai choisi un déclenchement le dimanche à 19h00.

Vous remarquerez que le scénario utilise les tags personnalisés #qui# et #message#. Si vous souhaitez obtenir plus de détails, cette partie se trouve un peu plus haut dans l’article.

Activer/désactiver l’alarme (provoqué)

Dans le scénario suivant je propose une activation ou une désactivation de mon alarme selon son état au moment d’une ou plusieurs pressions sur l’interrupteur Xiaomi. Aussi, le déclenchement du scénario se fait donc de manière provoquer, au clic sur l’interrupteur.

Vous pouvez aussi prendre connaissance du guide dédié au déploiement de votre alarme grâce au plugin dédié.

Boucle d’un scénario (simuler « While »)

Si vous avez besoin d’effectuer une action tant qu’une commande possède une valeur donnée, vous pouvez exécuter un scénario qui va réaliser l’action en question, vérifier la valeur de la commande, puis s’exécuter à nouveau.

Par exemple, voici un scénario fonctionnant ainsi :

Ici, lorsque le scénario s’exécute, attend 10 secondes, fait un rafraichissement de l’équipement, vérifie l’état de la commande d’ouverture, puis s’exécute lui même si la fenêtre est toujours ouverte.

A savoir que depuis peu, il semble nécessaire d’activer l’option « Multi-lancement » dans l’onglet « Général » de votre scénario. Dans le cas contraire, vous verrez dans les logs que le scénario doit se lancer lui même :

[2019-05-01 10:23:22][SCENARIO] Lancement du scénario : Chambre parentale options : []

sans cependant que ce soit le cas (puisqu’aucun log ne sera généré ensuite).