Tuto HC2 Résumé Des Fonctions Lua (Doc Fibaro)

[Tomzebest]

Voici une interprétation / traduction du premier onglet « Résumé des fonctions » (Spis funkcji) de la page officielle de documentation Fibaro http://docs.fibaro.com/?page_id=861. Il s’agit surtout des bases du langage LUA pour les scripts Fibaro.

 

J’ai rajouté quelques interprétations, moyens de compréhension… pour que cette traduction ressemble également à  un tutoriel comme j’aurai aimé le trouver quand j’ai commencé il y a quelques mois à  écrire quelques bouts de code.

 

Certaines fonctions semblent manquer, avoir changé, avoir disparu, ou même ne fonctionnent pas encore (j’ai cru lire ça quelque part à  propos des scripts utilisant les données géographiques), car je ne pense pas que Fibaro mettent à  jour très régulièrement cette base de donnée.

 

J’espère que les débutants surtout, apprécieront, et pour les pros, n’hésitez pas à  me faire corriger les mauvaises traductions / interprétations.

Je ferai surement par la suite, d’autres traductions de leurs pages car cette première m’a vraiment été d’une grande utilité pour démarrer dans le monde de l’automatisme (en LUA ici) sachant que je partais presque de zéro (juste des notions avec excel, si on peut les apparenter de loin…)

 

 

Comprendre certaines choses avant de démarrer :

• Un script LUA doit toujours commencer par l’entête suivant. Certes cela fonctionne aussi sans, mais si vous voulez modifier plus tard le script pour :

 - intégrer des déclenchements automatiques de la scène (trigger) en fonction de certaines actions ou évenements extérieurs

 - démarrer automatiquement la scène après enregistrement (pratique dans le cas d’une lecture infinie de la boucle de code, puisque cela vous permet de ne pas oublier d’appuyer sur le bouton ‘démarrer’ la scène après enregistrement)

 - d’autres choses encore,

il faudra insérer des éléments dans cet entête.

--[[
%% properties
%% globals
--]]

• Le mot " local "  permet de signaler dans le script qu’on va stocker derrière, une variable en tant que ‘variable locale’. Imaginez que vous ouvrez un tiroir et que vous y mettiez la variable 'a' (ou appelez la comme vous voulez).

Vous pouvez lui donner une valeur directement (cas 1) :

local a = 50

ou l’associer à  une fonction (cas 2) :

a = fibaro:getValue(107, 'value')

Dans le script vous pourrez rouvrir ce tiroir pour chercher la valeur de 'a' dans le cas 1, ou éviter de retaper plusieurs fois la fonction entière dans le cas 2.

 

- Cas 1 : Imaginons qu’on associe 'a' à  l’intensité lumineuse en pourcent d’un spot branché sur un variateur (dimmer fibaro par exemple).

Dans le script on pourra faire allumer le spot à  une certaine intensité (50%) en demandant à  ce que le paramètre de luminosité du variateur associé au spot prenne la valeur de 'a' (ainsi pas besoin de lui donner la valeur 50) ou bien de a + 10 par exemple.

local a = 50 -- on définit la variable locale avec nom et valeur
fibaro:call(12, 'setValue', a) -- on demande au système d'appeler (call) le module 12 et de lui donner la valeur (setValue) de 'a' (soit 50)
-- ou par exemple
fibaro:call(12, 'setValue', a + 10)

- Cas 2 : Imaginons maintenant que 'a' représente la fonction qui vérifie l'intensité du spot 107. On va créer une scène qui éteint le spot numéro 108, si le spot 107 est allumé et inversement. 

local a = fibaro:getValue(107, 'value') -- 'a' représente la fonction qui récupère (get) la valeur (Value) de l'intensité (value) du spot 107
if tonumber(a) >= 1 then -- si la valeur récupérée (ramenée en valeur numérique grâce à  tonumber) est supérieure à  1 (allumé), alors
fibaro:call(108, 'turnOff') -- le spot 108 s’éteint.
else fibaro:call(108, 'turnOn') -- sinon le spot 108 s’allume
end -- fin de la condition

En utilisant 'a' dans ce genre de cas et si on doit répéter plusieurs fois la fonction associée, on évite de surcharger le script ou de faire des erreurs de saisie en retapant plusieurs fois une longue fonction.

 

• Le mot " local " n’est pas obligatoire, les variables locales fonctionnent même sans les introduire par ce mot. Cependant il est plus aisé à  la relecture d’un script de retrouver les variables qu’on va utiliser en les précédant de ce mot.

 

• Ne mettez pas d’accents, d’espace ou de caractères spéciaux dans le nom de vos variables.

 

• Il est important de respecter les minuscules et les majuscules des commandes, fonctions, par contre vous pouvez utiliser ‘ ‘ou « » dans vos scripts ça ne changera rien â€¦

 

• Dans une parenthèse on peut mettre un espace après l’ouverture de parenthèse et avant la fermeture, ou ne pas en mettre. Cela n’a aucune incidence. Il semble d’ailleurs que les espaces ne soient pas importants dans la construction du script (sauf entre les mots évidemment, mais pas importants entre les mots et les ponctuations).

 

• La fonction fibaro:debug() permet « d’imprimer » des messages dans la case sous le script, au fur et à  mesure de sa lecture par le système et ainsi permet à  l’utilisateur de pouvoir vérifier des résultats de l’automate.

Si vous avez besoin de mettre une apostrophe dans une phrase pour la fonction debug, il faut mettre devant le \ pour que la lecture du script ne bug pas sur l’apostrophe.

fibaro:debug('Il n\’y a qu\’une action en cours')

• Une seconde correspond à  1000ms. Lorsqu’on veut donner une durée dans le script il faut convertir le temps voulu en ms.

 

• Les tabulations automatiques ou manuelles lors de l’écriture du script ne sont pas importantes, mais un script bien agencé sera plus facile à  comprendre, ou permet de repérer des erreurs ou oublis (par exemple en utilisant du conditionnel if then else, il faut finir cette condition par end, mais dans certains cas cette condition se retrouve dans une autre condition ou dans une autre chaîne qui nécessite également un end à  la fin).

Exemple : la chaine while true do en 1 nécessite end en 14 quand on veut arrêter la lecture en boucle qu’elle commande et reprendre la lecture au début. Dans cette boucle de lecture on a inséré une condition qui commence en 3-4 et se finit en 12, dans laquelle on a glissé une autre condition en 6-7 qui se finit en 10.

L’architecture structurée permet de voir plus clair dans le script.

while true do
 
   local---
   if then
   ---------
      local---
      if then
      --------
      else ------
      end
   else ------
   end
 
end

• On retrouvera des couleurs dans le script.

1. Le gris correspond à  des notes personnelles, il faut commencer chaque ligne par -- puis votre texte, ou --[[ texte ]]-- (sur plusieurs lignes). Le système ne tiendra pas compte de nos notes, sauf dans l’entête. Les caractères spéciaux et accents ne posent pas de problème dans ces notes.
2. Le vert correspond aux actions à  effectuer sur les modules (‘turnOff’, ‘setValue’…) ; au nom d’une propriété que l’on veut surveiller ou sur laquelle on veut agir (‘value’, ‘dead’, ‘isLight‘…) ; aux messages qu’on associera aux fonctions debug :

   fibaro:debug('La scène est en cours d\’exécution')

   ) ; à  une valeur à  atteindre par une fonction (ouverture de volet ou allumage d’une lampe sur variateur  ‘50’, ‘75’). Attention aux valeurs ‘1’ et ‘0’ qui peuvent correspondent à  un état d’une propriété d’un module (le module gère l'éclairage ('1') ou le module ne gère pas l'éclairage('0') est le retour d’état de la propiété isLight d'un module dimmer, ON ('1) et OFF ('0') est le retour d'état de la propriété value  d'un module relai switch) ; au nom d'une variable globale qu'on utilise dans une fonction; à  une position géographique « 52.5648 ;-12.5861 » ; et encore d'autres choses...
3.  Le rouge correspond au numéro d’identification d'un module ou d'une scène (DeviceID, SceneID… : 12, 54…) ; à  une durée dans la fonction sleep ;  à  une valeur assignée à  une variable locale ou une valeur à  comparer.
4.  Le bleu correspond à  toute l’architecture du système : local qui permet de signaler une variable du nom qu’on choisira et à  laquelle on peut associer une fonction ou une valeur ; à  des conditions if then else (si alors sinon), while true do (lance une lecture en boucle infinie du script); des valeurs booléennes (false et true dans par exemple la vérification de l'activité ou non d'une scène) ….
5. Le jaune correspond aux variables dont on choisit le nom (en français, en anglais ou autre, sans espace entre les mots ex : MaVariable, qu’on peut retrouver derrière local forcément, mais aussi dans des messages de la fonction fibaro:debug, ou de la fonction  fibaro:call, ou bien dans une condition if then pour récupérer ou comparer une valeur associée à  cette variable) ; ainsi qu’à  toutes les fonctions (fibaro:abort, fibaro:get...).
6. Le orange correspond à  des outils système (os.date, string.format, tonumber…)

 

• Liste des fonctions (par ordre alphabétique)

fibaro:abort()
fibaro:calculateDistance(position1, position2)
fibaro:call(deviceID, actionName, …)
fibaro:countScenes()
fibaro:countScenes(sceneID)
fibaro:debug(text)
fibaro:get(deviceID, propertyName)
fibaro:getGlobal(varName)
fibaro:getGlobalModificationTime(varName)
fibaro:getGlobalValue(varName)
fibaro:getModificationTime(deviceID, propertyName)
fibaro:getRoomID(deviceID)
fibaro:getSectionID(deviceID)
fibaro:getSourceTrigger()
fibaro:getSourceTriggerType()
fibaro:getType(deviceID)
fibaro:getValue(deviceID, propertyName)
fibaro:isSceneEnabled(sceneID)
fibaro:killScenes(sceneID)
fibaro:setGlobal(varName, value)
fibaro:setSceneEnabled(sceneID, enabled)
fibaro:sleep(time)
fibaro:startScene(sceneID)

 

• Résumé des fonctions (thématique)

DISPOSITIFS DE CONTRà”LE
fibaro:call(deviceID, actionName, …)

fibaro:get(deviceID, propertyName)
fibaro:getValue(deviceID, propertyName)
fibaro:getModificationTime(deviceID, propertyName)
fibaro:getType(deviceID)
fibaro:getRoomID(deviceID)
fibaro:getSectionID(deviceID)

 

SCENES DE CONTROLE
fibaro:abort()

fibaro:getSourceTrigger()
fibaro:getSourceTriggerType()

fibaro:startScene(sceneID)
fibaro:killScenes(sceneID)

fibaro:setSceneEnabled(sceneID, enabled)
fibaro:isSceneEnabled(sceneID)

fibaro:countScenes()
fibaro:countScenes(sceneID)

 

TRAITEMENT DES GLOBALS

fibaro:setGlobal(varName, value)
fibaro:getGlobal(varName)
fibaro:getGlobalValue(varName)
fibaro:getGlobalModificationTime(varName)

 

CARACTÉRISTIQUES SUPPLÉMENTAIRES
fibaro:debug(text)
fibaro:calculateDistance(position1, position2)

 

 

 

Liste des fonctions (par ordre alphabétique)

 

- fibaro:abort()

DESCRIPTION

On arrête le script en cours d'exécution.

CARACTÉRISTIQUES

Aucune

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

local a = 0 -- on définit la variable avec nom et valeur
-- On démarre une boucle infinie de lecture, le script sera relu sans arrêt grâce à  la commande:
while true do
-- si a est supérieur à  10 alors la lecture du script s'arrête  en 7
if (a > 10) then
fibaro:abort()
end -- fin de la condition
-- si a est inférieur à  10, la lecture du script continue
-- on augmente maintenant de 1 la valeur de la variable a
a = a + 1
-- on attend 1 seconde
fibaro:sleep(1000)
end -- fin de la boucle de lecture. La lecture reprend en 3
-- la lecture s'arrête en 13 et redémarre en 3 avec la nouvelle valeur de a jusqu'à  ce que a soit supérieur à  10 et que la lecture du script s'arrête

- fibaro:calculateDistance(position1, position2)

DESCRIPTION

On calcule la distance entre deux points géographiques: position1 et position2.

CARACTÉRISTIQUES

• position1: premier point
• position2: second point

Le point est exprimé avec sa latitude et sa longitude. Ces deux valeurs sont exprimées en degrés avec une partie décimale, et sont séparées par un point-virgule. Une valeur négative est donnée pour les valeurs de l'ouest et du sud. Le séparateur décimal est un point.

Par exemple, le point 40°44'55"N, 73°59'11"W doit être enregistré comme une chaîne (string)  "40.7486;-73.9864".

Ce format correspond à  la propriété « Location » (emplacement) du device « HC_user » (l’utilisateur) et stocke la dernière position de l'utilisateur du Home Center 2.

VALEURS RÉCUPÉRÉES

La distance, exprimée en mètres.

EXEMPLE

-- le système repère l'emplacement (propriété Location) du device 123 (moi par exemple grâce à  mon smartphone) et stocke les données de mon emplacement dans la variable :
local MonEmplacement = fibaro:getValue(123, 'Location') -- on crée une variable correspondant à  la fonction qui récupère (get) la valeur (Value) de la propriété Location (emplacement) du device 123 (moi)
-- on va ensuite stocker l'emplacement de notre maison dans une seconde variable:
local EmplacementMaison = "52.4325295140701;16.8450629997253"
-- on crée une dernière variable qui correspondra au résultat de la fonction qui calcule la distance entre nos 2 points:
local Distance = fibaro:calculateDistance(MonEmplacement, EmplacementMaison)
-- enfin la fonction debug m'indiquera cette distance grâce au texte que j'y associe et dans lequel j'ai inséré le résultat de ma variable Distance (qui sera retranscrite en valeur numérique)
fibaro:debug('La distance est de '..Distance..'m')

- fibaro:call(deviceID, actionName, arguments)

DESCRIPTION

On envoie une demande à  un module (device) pour qu’il exécute une action.

CARACTÉRISTIQUES

• deviceID: numéro du module (c’est son identité dans le système)
• actionName: chaîne (string) qui représente le nom de l’action
• argument: les arguments peuvent se succéder. De 0 à  7 arguments par action.

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

-- on demande au module d'ID=12 de s'éteindre
fibaro:call(12, 'turnOff')
 
-- on demande au module d'ID=12 de fixer sa valeur à  23 (intensité en % d'une lampe sur variateur, ouverture d'un volet)
fibaro:call(12, 'SetValue', '23')

DESCRIPTION ÉTENDUE

Il convient de noter que tous les arguments des fonctions call sont des chaînes (string). Ici '23' est une chaîne et non une valeur numérique (c'est pour cela qu'il faut mettre des guillemets sinon ça ne fonctionnera pas). Cependant, grâce au mécanisme intégré coercitif [lien Fibaro manquant pour l'explication], il n'est pas nécessaire de convertir les types numériques en chaîne (vous pouvez autant mettre une valeur numérique que le nom d'une variable qui est un format string). Nous verrons plus tard qu'à  certains moments il faudra convertir une chaîne en valeur numérique grâce l'outil tonumber).

-- le système stocke la valeur 50 pour la variable qu'on appelle 'a'
local a = 50
-- on demande au module d'ID=12 de prendre la valeur de 'a' qui est en format string
fibaro:call(12, 'SetValue', a)

Une description des actions disponibles ainsi que le nombre de paramètres requis est disponible ici. [lien Fibaro manquant].

 

- fibaro:countScenes()

DESCRIPTION

On obtient le nombre de lecture en cours de la scène. Par exemple, en cliquant 2x (ou plus) sur 'démarrer' avant la fin de la première lecture, vous démarrez une seconde (ou plus) lecture du script, la première ne s'arrêtera pas ; vous pouvez avoir également plusieurs scènes qui démarrent une scène particulière, il peut donc être utile en début de script de cette scène particulière, d'interdire une nouvelle lecture du script si une lecture est déjà  en cours d’exécution.

CARACTÉRISTIQUES

Aucune

VALEURS RÉCUPÉRÉES

Un entier positif qui spécifie le nombre d’exécution en cours de la scène.

EXEMPLES

-- on stocke dans la variable num, le nombre d'instances en cours de la scène
local num = fibaro:countScenes()
-- si il n'y a qu'une lecture en cours de la scène, alors la fonction debug m'indiquera la phrase que j'y associe ('il n'y a qu'une lecture en cours')
if num == 1 then
fibaro:debug('Il n\’y a qu\’une lecture en cours')
-- sinon la fonction debug intégrera le nombre de lectures de la scène dans une autre phrase que j'y associe ('nombre d'instances en cours: ')
else fibaro:debug('Nombre d\’instances en cours: '..num) -- notez que pour insérer une valeur d'une variable dans la fonction debug, il faut 2 points du coté du texte (avant et/ou après)
end

-- avant qu'une scène ne s'exécute, elle peut vérifier si elle est déja en cours d'exécution pour ne pas être lue plusieurs fois en même temps
if fibaro:countScenes() > 1 then -- si la scène est lancée plus d'une fois alors
fibaro:abort() -- arrêt de cette lecture du script
end -- fin de la condition
 
-- notez qu'on peut écrire aussi de cette façon
local num = fibaro:countScenes()
if num > 1 then
fibaro:abort()
end

- fibaro:countScenes(sceneID)

DESCRIPTION

On obtient le nombre d’exécution en cours pour une scène donnée (chaque scène est identifiée par son identité sceneID et peut être utilisée dans d’autres scènes)

CARACTÉRISTIQUES

sceneID: Numéro de la scène, identité de la scène

VALEURS RÉCUPÉRÉES

Un entier positif qui spécifie le nombre d'exécution en cours d'une scène donnée.

EXEMPLE

-- on veut afficher le nombre d'exécution en cours de la scène d'ID=12
local num = fibaro:countScenes(12)
fibaro:debug('Nombre d\’instances en cours de la scène 12 '..num)  
 
-- on veut vérifier que la scène 12 est en cours d'exécution
if fibaro:countScenes(12) >= 1 then
fibaro:debug('La scène 12 est en cours d\’exécution')
else fibaro:debug('La scène 12 n\’est pas en cours d\’exécution')
end

- fibaro:debug(text)

DESCRIPTION

On imprime le message dans la console de débogage associée au script.

CARACTÉRISTIQUES

text: texte à  afficher

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

fibaro:debug('Exemple de message')

Résultat dans la console de débogage du script:

 

- fibaro:get(deviceID, propertyName)

DESCRIPTION

On récupère les informations (valeur et heure de dernière modification) sur les propriétés d’un module

CARACTÉRISTIQUES

• deviceID: numéro d'identité du module
• propertyName: intitulé de la propriété

VALEURS RÉCUPÉRÉES

• Une chaîne contenant la valeur actuelle d’une des propriétés d’un module
• Horodatage (timeStamp) [lien Fibaro manquant pour l'explication] de la dernière modification

EXEMPLE

-- on veut récupérer (get) l'heure et la valeur de la dernière modification de la propriété 'value' du module d'ID=11. Il existe plusieurs propriétés qu'on peut récupérer ou modifier pour chaque module. La propriété 'value' peut correspondre à  une température, une intensité lumineuse en %, une ouverture d'un volet en %...
local valeur, HeureModification = fibaro:get(11,'value')
-- en LUA, on peut ignorer la seconde valeur de retour (pas très clair)
local valeur2 = fibaro:get(11, 'value')
-- les valeurs obtenues peuvent ensuite être utilisées dans des scènes
-- l'outil tonumber permet de convertir une variable (qui est au format chaîne (string)) en valeur numérique, afin de la comparer à  une autre valeur numérique
if tonumber(valeur2) >= 50 then -- si la valeur récupérée et transformée en valeur numérique est supérieure à  50 alors
fibaro:call(142, 'turnOff') -- le système demande au module d'ID=142 de s'éteindre

DESCRIPTION ÉTENDUE

Les principales fonctions :

fibaro:get(deviceID, propertyName)

fibaro:getValue(deviceID, propertyName)

fibaro:getModification(deviceID, propertyName)

Elles sont utilisées dans les scripts de scènes pour récupérer l'état actuel des modules. La valeur récupérée doit être affectée à  des variables locales afin de pouvoir utiliser des instructions conditionnelles (if, then). Voir exemple ligne 7.

Ces 3 fonctions ne diffèrent que par la valeur récupérée.

Notez que les valeurs récupérées sur les propriétés (propertyName), sont des variables de type ‘chaîne’ (string), ce qui signifie que, si on veut les comparer avec des valeurs numériques, il faut transformer ces variables en valeurs numériques elles aussi, grâce à  la commande tonumber. Voir exemple ligne 7.

 

Exemple concret, car l'exemple ci-dessus de la documentation Fibaro n'est pas très intéressant car pour récupérer les valeurs des propriétés des modules classiques, on peut autant utiliser la fonction fibaro:get(deviceID, propertyName) que la fonction fibaro:getValue(deviceID, propertyName).

Pour récupérer l'adresse IP d'un module virtuel d'ID=126

deviceIp = fibaro:get(126, "IPAddress") -- merci à  i-magin grâce à  qui j'ai trouvé l'exemple là  sur le forum

- fibaro:getGlobal(varName)

DESCRIPTION

On récupère des informations (valeur et heure de la dernière modification) de la variable globale enregistrée dans le système.

CARACTÉRISTIQUES

varName: Le nom de la variable globale

VALEURS RÉCUPÉRÉES

• Une chaîne contenant la valeur actuelle de la variable globale
• Horodatage (timeStamp) [lien Fibaro manquant pour l'explication] de la dernière modification

EXEMPLE

-- on veut récupérer l'heure et la valeur de la dernière modification de la variable globale appelée 'Nuit' à  laquelle on a associé les valeurs '0' (jour) ou '1' (nuit), on aurait pu choisir d'autres noms comme jour et nuit directement ou oui et non...
local valeur, HeureModification = fibaro:getGlobal('Nuit')
-- en LUA, on peut ignorer la seconde valeur de retour (pas très clair)
local valeur2 = fibaro:getGlobal('Nuit')
-- les valeurs ainsi obtenues peuvent être utilisées dans des scènes
if (value == '1') then
fibaro:debug('Il fait nuit')
end

DESCRIPTION ÉTENDUE

Les principales fonctions :

fibaro:getGlobal(varName)
fibaro:getGlobalValue(varName)
fibaro:getGlobalModificationTime(varName)

Elles sont utilisées dans les scripts de scènes pour récupérer l'état actuel des variables globales. La valeur récupérée  doit être affectée à  des variables locales afin de pouvoir utiliser des instructions conditionnelles (if then).

Ces 3 fonctions ne diffèrent que par la valeur récupérée.

 

- fibaro:getGlobalModificationTime(varName)

DESCRIPTION

On récupère des informations (seul l'horodatage de la dernière modification) de la variable globale enregistrée dans le système.

CARACTÉRISTIQUES

varName: Le nom de la variable globale

VALEURS RÉCUPÉRÉES

Horodatage de la dernière modification de la variable globale.

EXEMPLE

-- on veut récupérer la date de la dernière modification de la variable globale nommée 'compteur'
local DerniereModif = fibaro:getGlobalModificationTime('compteur')
-- si la valeur de cette variable globale a été modifiée il y a plus de 10 secondes
if os.time() - DerniereModif >= 10 * 1000 then
fibaro:debug('La modification a eu lieu il y a plus de 10s')
else fibaro:debug('La modification a eu lieu il y a moins de 10s')

VOIR AUSSI

fibaro:getGlobal
fibaro:getGlobalValue

 

- fibaro:getGlobalValue(varName)

DESCRIPTION

On récupère des informations (seule la valeur) de la variable globale enregistrée dans le système.

CARACTÉRISTIQUES

varName: Le nom de la variable globale

VALEURS RÉCUPÉRÉES

Une chaîne contenant la valeur actuelle de la variable globale.

EXEMPLE

-- on veut récupérer la valeur de la variable globale nommée 'compteur'
local ValeurCompteur = fibaro:getGlobalValue('compteur')

VOIR AUSSI

fibaro:getGlobal

fibaro:getGlobalModificationTime

 

- fibaro:getModificationTime(deviceID, propertyName)

DESCRIPTION

On récupère des informations (seule l'horodatage de la dernière modification) sur les propriétés d'un module.

CARACTÉRISTIQUES

• deviceID: numéro d'identité du module
• propertyName: nom de la propriété

VALEURS RÉCUPÉRÉES

Horodatage des dernières modifications de propriétés du module.

EXEMPLE

-- on veut récupérer la date de la dernière modification de la propriété 'value' du module d'ID=11, exemple l'heure à  laquelle la lampe a changé d'intensité
local HeureModif = fibaro:getModificationTime(11, 'value')
-- os.time() correspond à  l'horodatage au moment de la lecture du script
if os.time() - HeureModif >= 10*1000 then -- si la différence de temps entre le moment où le script est lu et le moment de la dernière modification est supérieur à  10s alors
fibaro:debug('La dernière modification de la valeur date de plus de 10s')
else fibaro:debug('La dernière modification de la valeur date de moins de 10s')

- fibaro:getRoomID(deviceID)

DESCRIPTION

On récupère le numéro de la pièce dans laquelle se trouve le module.

CARACTÉRISTIQUES

deviceID: numéro d’identité du module

VALEURS RÉCUPÉRÉES

RoomID: Numéro qui identifie la pièce dans laquelle se trouve le module (Le RoomID de la pièce sans nom ‘non assigné’ est  0)

EXEMPLE

-- on veut récupérer le numéro d'identité de la pièce dans laquelle se trouve le module d'ID=9
local Piece = fibaro:getRoomID(9) -- on demande au système de récupérer (get) l'identité de la pièce (RoomID) où se trouve le module d'ID=9 et on stocke cette valeur dans la variable qu'on appelera Piece
if Piece == 0 then
fibaro:debug('Le module se trouve dans la pièce \’non assigné\’')
else fibaro:debug('Le module se trouve dans la pièce d\’ID '..Piece)

VOIR AUSSI

fibaro:getSectionID
fibaro:getType

 

- fibaro:getSectionID(deviceID)

DESCRIPTION

On récupère le numéro d’identité de la section dans laquelle le module est situé.

CARACTÉRISTIQUES

deviceID: numéro d’identité du module

VALEURS RÉCUPÉRÉES

SectionID : numéro de la section dans laquelle l'appareil est situé (le SectionID de la section sans nom ‘non assigné’ est 0)

EXEMPLE

-- on veut récupérer le numéro d'identité de la section dans laquelle se trouve le module d'ID=9
local Section = fibaro:getSectionID(9) -- on demande au système de récupérer (get) l'identité de la section (SectionID) où se trouve le module d'ID=9 et on stocke cette valeur dans la variable qu'on appelera Section
if Section == 0 then
fibaro:debug('Le module se trouve dans la section \’non assigné\’'
else fibaro:debug('Le module se trouve dans la section '..Section)

VOIR AUSSI

fibaro:getRoomID
fibaro:getType

 

- fibaro:getSourceTrigger()

DESCRIPTION

On récupère les informations sur l’origine du trigger (déclencheur) qui a démarré la scène automatiquement.

CARACTÉRISTIQUES

Aucune

VALEURS RÉCUPÉRÉES

Des informations sur le « type » de déclenchement qu’on peut classer dans un tableau.

Selon le déclenchement, le « type », peut avoir ces 3 valeurs:

• ‘property’ - scène déclenchée par la modification d'une propriété d'un module
• ‘global’ - scène déclenchée par la modification d'une variable globale
• ‘other’ - dans les autres cas (scène lancée directement grâce à  un autre script ou en manuel depuis l'interface par l'utilisateur)

Selon la valeur du « type » de déclenchement, la table peut encore avoir des champs supplémentaires, qu'on pourra également récupérer.

 

DESCRIPTION ÉTENDUE

Cette fonction peut être utilisée pour déterminer l’origine directe du déclenchement du script.

En début de script, dans l’en-tête, on définit les paramètres déclencheurs qui peuvent causer l’exécution du script. Sans cet en-tête rempli correctement, le script ne s’exécutera pas automatiquement.

Grâce à  la fonction fibaro:getSourceTrigger() on peut récupérer plusieurs éléments en rajoutant derrière : ['type'],['deviceID],[propertyName] ou [varName] :

- Le 'type' de l'origine du déclenchement de la scène. On récuperera une des valeurs suivantes:

• property: si lancement auto de la scène grâce à  une modification d'une propriété d'un module
• global: si lancement auto de la scène grâce à  une modification d'une variable globale
• other: si déclenchement manuel de la scène par l'utilisateur ou depuis une autre scène

- 'deviceID' est le numéro d'identité du module surveillé dans l'entête, qui est à  l'origine du déclenchement automatique de la scène.

- 'propertyName' est le nom de la propriété d'un module surveillé dans l'entête, qui a vu sa valeur changer et qui est à  l'origine du déclenchement automatique de la scène. Par exemple une modification de la propriété 'value' quand un éclairage change d'intensité, ou qu'un radiateur se met en route etc, de la propriété 'baterryLevel' quand un module fonctionnant avec pile atteint un certain niveau de batterie, de la propriété 'armed' quand un module comme le capteur d'ouverture de porte est armé au moment de votre départ au travail et que cela démarre la scène qui vous préviendra par notification si la porte s'ouvre et que personne n'a désarmé le module...

- 'varName' est le nom de la variable qui a vu sa valeur changer et qui est à  l'origine du déclenchement automatique de la scène. Exemple on a crée une variable globale 'SAISON' qui peut prendre la valeur ETE ou HIVER. Quand on modifie cette saison via un module virtuel par exemple, une scène qu'on aura crée auparavant va se lancer automatiquement pour mettre les radiateurs en fonctionnement ou à  l'arrêt suivant la saison indiquée.

EXEMPLE

Démarrage auto de la scène si :

Changement de la propriété ‘value’ du module 13
Changement de la propriété ‘value’ du module 15
Changement de la variable globale 'JourNuit’

En outre, le script peut être exécuté directement à  partir de l'interface ou en utilisant une autre scène (voir Fibaro: runScene (sceneID)).

Lorsque le script est exécuté, il affiche les informations de débogage de la console sur l’origine de son exécution.

--[[
%% properties
13 value
15 value
 
%%  globals
JourNuit
--]]
local OrigineDeclenchement = fibaro:getSourceTrigger() -- on demande au système de récupérer (get) l'origine (Source) du déclenchement de la scène (Trigger)
 
if OrigineDeclenchement['type'] == 'property' then -- si l'origine du déclenchement de la scène est la modification d'une propriété d'un module surveillée dans l'entête alors
fibaro:debug('L\’ origine est la modification d\’une propriété du module '..OrigineDeclenchement['deviceID'])
elseif OrigineDeclenchement['type'] == 'global' then -- sinon si l'origine du déclenchement de la scène est la modification d'une variable globale surveillée dans l'entête alors
fibaro:debug('L\’ origine est la modification de la variable globale '..OrigineDeclenchement['varName'])
elseif OrigineDeclenchement['type'] == 'other' then -- sinon si l'origine du déclenchement de la scène est autre alors
fibaro:debug('La scène a été lancée manuellement')
end

VOIR AUSSI

fibaro:getSourceTriggerType()

 

- fibaro:getSourceTriggerType()

DESCRIPTION

On récupère des informations sur la valeur du « type » du déclencheur qui a causé la scène.

CARACTÉRISTIQUES

Aucune

VALEURS RÉCUPÉRÉES

Une chaîne (string) contenant la valeur du « type » du déclencheur (voir fibaro: getSourceTrigger () )

EXEMPLE

-- on veut vérifier si la scène a été lancée manuellement
if fibaro:getSourceTriggerType() == 'other' then -- si la fonction qui récupère (get) le type (Type) de l'origine (Source) du déclencheur (Trigger) est 'other' alors
fibaro:debug('La scène a été lancée manuellement')
end
 
-- on a vu au dessus que la même chose peut être obtenue en utilisant le tableau précédent avec l'utilisation de getSourceTrigger() et en se référant au champ 'type'
local OrigineDeclenchement = fibaro:getSourceTrigger()
if OrigineDeclenchement['type'] == 'other' then
fibaro:debug('La scène a été lancée manuellement')

VOIR AUSSI

fibaro:getSourceTrigger()

 

- fibaro:getType(deviceID)

DESCRIPTION

On récupère le type de l'appareil. Les différents types d'appareils sont référencés ici

PARAMàˆTRES

deviceID: numéro d’identification du module

VALEURS RÉCUPÉRÉES

Une chaîne contenant le type du module

EXEMPLE

-- on veut récupérer le 'type' du module d'ID=100
local TypeModule = fibaro:getType(100) -- on récupère (get) le type (Type) du module d'ID=100 et on stocke le résultat dans la variable qu'on appelle 'TypeModule'
 
if TypeModule == 'blind' then -- si le module commande un volet roulant alors
fibaro:debug('Le module commande un volet roulant')
else fibaro:debug('Type du module : '..TypeDispositif) -- sinon la fonction debug indique directement le type du module
end

VOIR AUSSI

fibaro:getRoomID
fibaro:getSectionID

 

- fibaro:getValue(deviceID, propertyName)

DESCRIPTION

On récupère des informations (uniquement la valeur) d'une propriété d'un module.

PARAMàˆTRES

• deviceID: numéro d’identification du module
• propertyName: nom de la propriété

VALEURS RÉCUPÉRÉES

une chaîne contenant la valeur actuelle de la propriété voulue

EXEMPLE

-- on veut récupérer la valeur de la 'valeur de luminosité' du module d'ID=11
local ValeurLum = fibaro:getValue(11, 'brightness') -- C'est ce qu'il y a indiqué sur le document fibaro mais la propriété brightness n'existe plus
local ValeurLum = fibaro:getValue(11, 'value') -- C'est maintenant la propriété 'value' d'un dimmer qui permet de récupérer la valeur de la luminosité en pourcentage

Exemple concret, une sonde de température dont on veut simplement récupérer la mesure :

local TempSalon = fibaro:getValue(115, 'value') -- on demande au système de récupérer (get) la valeur (Value) de la propriété mesure de la température (value) de la sonde de température de salon (module 115)
if tonumber(TempSalon) > 20 then -- si la valeur récupérée, une fois transformée en valeur numérique, est supérieure à  20 alors
fibaro:call(12, 'turnOff') -- le système demande au relai 12 connecté au radiateur de se couper

VOIR AUSSI

fibaro:get
fibaro:getModificationTime

 

- fibaro: isSceneEnabled (sceneID)

DESCRIPTION

On vérifie si la scène avec un sceneID donné est active.

PARAMàˆTRES

sceneID: numéro d’identification de la scène

VALEURS RÉCUPÉRÉES

valeur booléenne: true si la scène est active, false si non active : d'après la documentation Fibaro, HORS cela ne fonctionne pas. Voir exemple 2

EXEMPLE

if fibaro:isSceneEnabled(3) then -- si la scène 3 est activée cela activera la scène 5
fibaro:setSceneEnabled(5, true)
end

Exemple qui montre qu'on ne récupère pas la valeur true ou false

local SceneActive = fibaro:isSceneEnabled(3)
if SceneActive == 'true' then
fibaro:debug('active')
else fibaro:debug('inactive')
end

Que la scène soit active ou pas, le débogage indiquera inactive. Dans l'exemple précédent on ne pourrait donc pas activer la scène 5 si la scène 3 est inactive...

 

VOIR AUSSI

fibaro:setSceneEnabled(sceneID, enabled)

 

- fibaro:killScenes(sceneID)

DESCRIPTION

On termine toutes les instances en cours d’exécution d'une scène donnée. (On se rappelle que le système peut lire plusieurs fois en même temps un script déjà  en cours de lecture)

PARAMàˆTRES

sceneID: numéro d’identification de la scène

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

-- si la valeur de 'a' est comprise dans l'intervalle [1;5], toutes les lectures en cours de la scène d'ID=2 s'arrêtent
if a >= 1 and a <= 5 then
fibaro:killScenes(2)

VOIR AUSSI

fibaro: startScene (sceneID)
fibaro: countScenes ()
fibaro: countScenes (sceneID)

 

- fibaro:setGlobal(varName, value)

DESCRIPTION

Modifie la valeur d'une variable globale.

PARAMàˆTRES

• varName: le nom de la variable globale
• value: la nouvelle valeur de la variable globale

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

-- on veut attribuer la valeur de 1 à  une variable globale nommée 'index'
fibaro:setGlobal('index', 1)
 
-- on veut augmenter de 3 la valeur de la variable globale nommée 'test'
fibaro:setGlobal('test', fibaro:getGlobalValue('test') + 3)
 
-- on veut assigner à  la variable globale nommée 'index', la valeur de la variable locale 'a'
local a = 10 * 234
fibaro:setGlobal('index', a)

DESCRIPTION ÉTENDUE

La fonction fibaro:setGlobal(varName, value) ne peut être utilisée que pour les variables globales qui ne sont pas des variables en lecture seule. Si vous essayez de remplacer la valeur d’une variable en lecture seule, un avertissement sera généré et l'opération ne sera pas effectuée (pas clair).

 

- fibaro:setSceneEnabled(sceneID, enabled)

DESCRIPTION

Active ou désactive une scène donnée.

PARAMàˆTRES

• sceneID: numéro d’identification de la scène
• enabled: valeur booléenne (true - active la scène, false - désactive la scène)

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

if a > 0 then
fibaro:setSceneEnabled(3, false) -- si la valeur de la variable 'a' est positive, cela désactive la scène d'ID=3
else fibarosetSceneEnabled(3, true) -- sinon cela active la scène d'ID=3
end

VOIR AUSSI

fibaro:isSceneEnabled(sceneID)

 

- fibaro:sleep(time)

DESCRIPTION

On suspend l'exécution du script pendant le temps spécifié en millisecondes.

PARAMàˆTRES

time: le temps en millisecondes

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

-- on suspend la lecture du script pendant 10 secondes
fibaro:sleep(10000)
-- comme les durées doivent être indiquées en millisecondes, pour plus de compréhension on peut écrire
fibaro:sleep(10 * 1000)

- fibaro:startScene(sceneID)

DESCRIPTION

On veut démarrer l’exécution d'une scène donnée.

PARAMàˆTRES

sceneID: numéro d’identité de la scène qui doit être lancée

VALEURS RÉCUPÉRÉES

Aucune

EXEMPLE

if a > 20 then
fibaro:startScene(10) -- si la valeur de 'a' est supérieure à  20, on démarre l'exécution de la scène d'ID=10
end

[JM13]

Super, c'est vraiment sympa d'avoir poster cette doc.(autre qu'en Polonais) 

 

C'est vrai que cela manque...

 

Par contre, je recherche une explication sur les "triggers" que je ne trouve pas !!

J'arrive en "déduire" le fonctionnement de certains (expliqués dans dives posts) mais pas une petite avec la liste complète et leur utilisation. 

[cyssou]

Merci pour ton travail ;-)

Envoyé de mon iPhone àl'aide de Tapatalk

[cyssou]

Merci pour ton travail

Envoyé de mon iPhone àl'aide de Tapatalk

[BenjyNet]

Bon alors pour moi, ça il ne faut pas le laisser dans le forum. Il faut que ce soit une section àpart entière du site. Genre comme Doc Fibaro en haut mais en français.

Je m'en vais de ce pas alerter phil et yohan.

Merci àtoi @Tom.

[laranjeira61]

salut,

 

merci pour ton travail ça va être utile a beaucoup d'entre nous.

[Fredric]

 j'adore     Merci

[Shad]

Super, c'est vraiment sympa d'avoir poster cette doc.(autre qu'en Polonais) 

 

C'est vrai que cela manque...

 

Par contre, je recherche une explication sur les "triggers" que je ne trouve pas !!

J'arrive en "déduire" le fonctionnement de certains (expliqués dans dives posts) mais pas une petite avec la liste complète et leur utilisation. 

 

Je ne vois pas le soucis avec cette fonction

fibaro:getSourceTrigger()

Si tu prend pour un FGK (d'ailleurs je crois que sa dois être sur un des seul qu'ils fonctionnen), il sert juste à  executer une action au moment ou tu ouvres/fermes la portes.

[JossAlf]

Merci Tom ! Je vote aussi pour une section particulière dans le site comme le dit Benjy.

 

Tip top Tom The Best  Encore merci pour cette initiative.

[Lazer]

Bravo Tom

Et je vote aussi pour déplacer cette référence sur une page dédiée.

Et ça permettrait aussi de faire fonctionner les ancres (quand on clique sur le nom d'une fonction, on arrive sur le descriptif de la fonction).

[cyssou]

Oui oui, je vote aussi pour une section dédier.

Envoyé de mon iPhone àl'aide de Tapatalk

[Tomzebest]

Merci pour vos messages. Ça fait plaisir parce qu'il y a plusieurs semaines de travail c'est clair.

Oui lazer je comptais demander un coup de main pour les ancres parce que quand j'ai fait cette traduction sur word évidemment j'ai fait les signets mais sur cette page je n'arrivais pas avec du bbcode. Je comprends mieux alors si c'est pas possible ^^

JM13 je ne comprends pas trop ta question sur les triggers. Il y a la fonction getSourceTrigger où est bien indiqué le fonctionnement de ces déclencheurs de scène (àcause d'un module,d'une variable globale ou manuellement ou lancé par une autre scène). Il manque cependant le trigger %autostart.

[Moicphil]

Oui un grand merci à  toi pour le boulot de dingue que tu as fais.

 

Je rejoins tout à  fais les commentaires précédents à  savoir épingler ceci en haut de page...

 

 

 

Encore bravo Thomas! 

[JM13]

Tout d'abord, je vote moi aussi pour une section dédiée pour mettre en valeur ce travail (et je suis sur aussi les compléments qui viendront) ou même pour la création d'un petit wiki sur le sujet.

 

Pour répondre à  la question sur les triggers, j'en ai vu plusieurs (Autostart, reveil, armed, valueMeter, value, Lowbattery, ...) et l'utilisation n'est pas claire pour moi. Bien sur la fonction "getSourceTrigger" est simple mais :

 

• Dois-je le utiliser uniquement en en-tête, les appeler avec la fonction (tous ou certains uniquement) ?
• Quelle sont les conditions exactes pour chaque triggers (lowbattery OK mais quel niveau 20%, 50%...)
• value vs valueMeter

En fait, c'est peut être plus des questions sur la gestion des scènes que sur les triggers ! 

[Domotique-Home]

ouahhhhhhhhhhhaaaaaaaaa 

Un super travail merci a toi.

J'ai commencé a traduire les fonction Fibaro y a un certain temps ici mais la, BRAVO, rapide et claire.

[Steven]

Super travail.

 

Maintenant, il n'y a plus qu'à  maintenir tout cela, et je pense que cela ne va pas être une partie de plaisir. 

[Tomzebest]

@Steven : oui c'est clair il va falloir que je suive un peu les mises à  jour de Fibaro sur cette doc pour la maintenir correcte.
@Rems : je suis tombé sur ta traduction aussi en cherchant certaines infos sur des fonctions que je ne comprenais pas. Enfin sur les traductions google qui faisaient que je ne comprenais pas lol. D'autres points de vue ou des exemples sur internet m'ont souvent bien aidé. Content que tu l'ais vue, je voulais t'envoyer un message sur ton blog si cette traduction pouvait t'aider...
@JM13 : pour les triggers ce que je te disais c'est dans la description étendue de la fonction getSourceTrigger j'ai essayé d'être clair sur la fonction et mise en place des Triggers. D'apès ce que j'ai vu et compris et pour répondre à  tes dernières questions:

• c'est dans l'entete que tu décides quelles sont les propriétés d'un certain module que tu veux surveiller pour lancer la scène. Cela va donc dépendre de ce que tu veux et de ce que tu mettras dans ta scène. Si tu veux une notification quand il te reste moins de 20% de batterie sur ton module 150, tu mets dans l'entete

--[[
%% properties
150 batteryLevel
%% globals
--]]
local NiveauBatterie = fibaro:getValue(150, 'batteryLevel') -- on récupère (get) la valeur (Value) de la propriété batteryLevel du device d'ID=150 et on stocke cette valeur dans une variable globale appelée NiveauBatterie
if tonumber(NiveauBatterie) <= 20 then
fibaro:call(7, "sendDefinedPushNotification", "2") -- le système m'envoie une notification
end

 

Le trigger sert juste à  démarrer la scène en auto. Que ta batterie passe de 100% à  99% ou de 21% à  20% la scène se lancera à  chaque fois. C'est ce que tu mets dans ta scène qui fera qu'il se passe qqch ou non en fonction de ce que tu recherches et des conditions que tu mets dedans.

Chaque module à  des propriétés que tu peux utiliser en trigger. Pour connaitre ces propriétés, quand tu fais une scène en LUA, a gauche tu as la liste des variables globales, et des périphériques, quand tu passes la souris dessus ça ouvre des fenêtres qui te montre les propriétés ou les actions que tu peux faire avec ce module ; avec le toolkit de krikroff aussi surement mais je n'ai pas eu le temps de le tester encore

Les fonctions associées au trigger que tu vois quand tu passes d'un script en bloc vers un script LUA servent à  dire au script, lis le script (1ere partie) si la scène se déclenche automatiquement avec les trigger sinon si le 'type' du déclenchement (voir le tableau de la traduction de la fonction getSourceTrigger) est 'other' (c'est à  dire lancé par l'utilisateur ou depuis une autre scène via la fonction startScene), la scène sera (2eme partie du script). La scène en auto ou manu sera la même. Personnelement je n'aime pas basculer de bloc à  LUA, je fais directement en LUA. Parce que tu peux faire le ménage dans le script car il est surchargé de choses inutiles et plus difficile pour l'utilisateur à  lire.

le trigger %% autostart permet de lancer la scène automatiquement après enregistrement. à‡a peut être pratique dans le cas où tu utilises while true do. Mais tout ca est marqué dans ce très long tuto ^^ je te laisse farfouiller!

• La seconde question est un peu dans la réponse précédente ^^
• value et valuemeter je ne sais pas la différence, il y a pas mal de propriétés qui changent suivant les modules.

[sjhp]

Alors là! chapeau

Yapluka tout assimiler... et làc'est pas gagné!

Super boulot.

[Tomzebest]

Pour les admins! il y n'y a pas de problèmes pour le mettre en onglet haut de page ça serait même un honneur (j'ai essayé de joindre Yohan en MP il y a qqs jours mais apparemment il ne répond pas ou ce n'est pas transmis...)

Par contre il y a qqs points àvérifier. Ceux qui se sentent chaud faites une recherche sur la page avec "pas clair" (généralement j'ai mis en rouge)

[Shad]

Qu'est-ce que tu appelles variable en lecture seule ???

[Tomzebest]

Bah justement c'est la traduction polonaise avec google translate... J'ai essayé pas mal de truc en changeant les 2 types de variables globales avec cette fonction. Je pensais que les variables globales prédéfinies causeraient ce message d'erreur mais non, la valeur se modifie si elle est dans le menu déroulant sinon elle ne change pas de valeur... Je crois que j'ai eu ce message d'erreur un jour en faisant ce test mais c'était au début de la traduction et j'ai commencé il y a une paire de mois... Et je n'ai pas noté quand est ce que ça merdouillait ^^

[i-magin]

Merci @Tomzebest, c'est un super boulot 

[Tomzebest]

Merci a toi! Je t'ai piqué un exemple dans la fonction fibaro:get(deviceID, propertyName) et il y a un remerciement spécial dans l'exemple ^^

[Yohan]

Excellent travail Tom je ne m'attendais pas du tout à  ça. 

 

Je m'occupe de le mettre en Onglet en haut du forum.

 

Pour les Mp, ils sont passés, je viens de vérifié et ils étaient dans le dossier Conversations et non pas dans Nouveaux... bizarre tout ça.

 

Encore bravo pour ce gros travail

[Shad]

D'accord, parce que moi entre mes divers clients je n'ai jamais eu de problème.