Vous le savez incorpore le langage Lua

au même titre que 

ou bien

Essayons, nous aussi, de jouer avec et de préciser les bases de l’utilisation de ces scripts qui parfois déroutent les débutants.

Il ne s’agit pas ici de faire un cours de lua mais de détailler l’intégration de ces scripts dans Domoticz.

La page source sur le wiki Domoticz https://www.domoticz.com/wiki/Events#Using_the_events_system

Généralités

Il en existe de 4 types différents basés sur les événements qui surviennent sur le matériel, le temps, les variables, le panel de sécurité. Par événement on entend toute modification qui survient.

Il est important de comprendre (et je le répéterai)  que TOUS les scripts événements se déclenchent à toute modification sur l’événement correspondant (changement d’état d’un des matériels, toutes les minutes, à chaque changement d’une variable).

• Tous les scripts Lua se trouvent dans le dossier domoticz/scripts/lua
• Ils finissent par l’extension .lua sinon ils ne sont pas exécutés par Domoticz
• Pour nos amis modifiant les fichiers sous Windows, enregistrez les en UTF8 sans BOM (Notepad++)
• Ils n’ont pas besoin d’être chmodés (pas de chmod +x, +777) chrgp … non plus
• Les scripts ne sont pas lancés en tache de fond, il sont lancés par Domoticz et n’ont que 10 secondes pour faire leur boulot, passé ce temps Domoticz les tue. En vertu de quoi évitez les sleep (20), d’interroger des services web qui répondent trop lentement …
• Les noms à utiliser à l’intérieur des scripts sont ceux donnés dans la colonne Nom des périphériques, respectez EXACTEMENT l’orthographe majuscules/minuscules/espaces/accent. Et pour ne pas être embêtés bannissez les espaces/accents/caractères bizarres (‘/&…) en renommant votre matériel
• Les valeurs reçues des capteurs ne sont pas modifiables via Lua, utilisez JSON
• Tous les script doivent contenir un bloc commandArray={} puis return commandArray contenant les instructions à effectuer

Ex :

commandArray = {}
    print('coucou')
return commandArray

N.B. Les instructions print sont affichées dans le log de Domoticz.

Les différents types de scripts Lua

Il en existe donc de 4 types

1. Les scripts device basés sur le changement d’état du matériel : Le nom de ces script est script_device_xxxxxxxxx.lua
2. Les scripts basés sur le temps , il s’exécutent toutes les minutes. Ces script DOIVENT se nommer script_time_xxxxxxxx.lua
3. Les scripts basés sur le changement de valeur d’une variable Domoticz: Ces script DOIVENT se nommer script_variable_xxxxxx.lua
4. Les script bases sur le panel de sécurité : script_security_xxxxxx.lua qui réagit au security panel de Domoticz.

Vous remarquerez que rien dans le nom du fichier ne fait référence au matériel concerné, toutefois pour des facilités de lecture l’usage veut que dans le nom du script_  on mette le nom du matériel après les tirets bas script_time_EDF.lua, script_device_CPU_Usage.lua.

Il est important de comprendre  que TOUS les scripts évènementiels se déclenchent à tout événement ci dessus :

Lorsque n’importe quelle variable change, TOUS les script_variable sont passés en revue pour voir si il y a quelque chose à faire avec la variable qui vient de changer de valeur.

Lorsque n’importe quel matériel change de valeur TOUS les script_device sont passés en revue pour voir si il y a quelque chose à faire avec ce matériel qui vient de changer de valeur. Cela est vrai avec les interrupteurs qui passent de On à Off mais aussi avec les capteurs dont la valeur se modifie au cours du temps.

Lorsque la minute change, ce qui arrive toutes les minutes 🙂 , TOUS les script_time sont lus pour voir si il y a quelque chose à faire avec.

Comment gérer les scripts Lua

Vous voyez donc que rapidement et sans précaution on peut avoir de nombreux scripts qui se déclenchent à mauvais escient. C’est pour cela que votre script doit commencer par l’instruction if (devicechanged[‘Materiel 1’] afin de quitter le plus rapidement possible le script en question si le matériel Materiel 1 n’a pas changé de valeur et passer ainsi au script_device suivant

Illustration :

commandArray = {}
if (devicechanged['Materiel 1'] == 'On' ) then
        commandArray['Materiel 2']='On'
end
return commandArray

• Les noms font référence à la colonne Nom des périphériques, respectez EXACTEMENT l’orthographe majuscules/minuscules/espaces/accent. Et pour ne pas être embêtés bannissez les espaces/accents/caractères bizarres (‘/&…) en renommant votre matériel Ex: Lumiere_Exterieure sera mieux que Lumière Extérieure.
• Dans les scripts les noms doivent être entourés de simples guillemets ‘
• N’hésitez pas à placer dans le commandArray des print réguliers pour debugger tout ça.

            val_rasp = tonumber(otherdevices_svalues['CPU_Usage'])
            print("cpu = "..val_rasp)

• Sans entrer dans les détails sachez que il y a deux instructions basiques à connaitre:

le devicechanged[‘XXXXXX’] qui permet de lancer le script et le otherdevices_svalues qui permet de récupérer la valeur, par exemple pour le matériel Cpu_Usage

commandArray = {}
if (devicechanged['CPU_Usage'])
        then
            val_rasp = tonumber(otherdevices_svalues['CPU_Usage'])
            print("cpu = "..val_rasp)
end
return commandArray

• Le langage permet de gérer de nombreux éléments de Domoticz comme les scènes, les groupes, les dimmables, de faire du déclenchement aléatoire(RANDOM X), pour une durée déterminée en minutes (FOR 2) …

Quelques exemples tirés du Wiki :

 commandArray['Switch']='On'
 commandArray['Scene:Livingroom']='On'
 commandArray['Group:Kitchen']='Inactive'
 commandArray['Keyfob']='Group On'
 commandArray['DimmableDevice']='Set Level 50'
 commandArray['SendNotification']='subject#body#0'
 commandArray['SendEmail']='subject#body#your@email.com'
 commandArray['OpenURL']='www.yourdomain.com/api/movecamtopreset.cgi' 
 commandArray['Blinds']='On RANDOM 30'
 commandArray['Porch Light']='On FOR 2'
 commandArray['Variable:MyVar']='Some value'
 commandArray['Variable:MyVar']='Some value AFTER 3'

• On peut également appeler des modules systèmes tel que os.date pour avoir une date local today = os.date("%A"),lancer un programme externe par  os.execute('/home/pi/domoticz/scripts/python/put_iot.py').
• Dans le dossier scripts/lua il y a des exemples de script time et script device dont on peut s’inspirer.

Références

Cet article n’est qu’un condensé de https://www.domoticz.com/wiki/Events#Using_the_events_system

D’autres discussions ici

https://easydomoticz.com/forum/viewtopic.php?f=10&t=929

et plus de discussions ici

https://easydomoticz.com/forum/viewforum.php?f=10

Le manuel de référence Lua http://www.lua.org/pil/contents.html

Cet article n’avait pas pour but l’exhaustivité du sujet mais de poser quelques base de départ.

J’espère qu’il vous aura donné envie d’en savoir plus et d’élucider quelques mystères.

comme le fait que lua signifie lune en portugais.