Création et utilisation de scripts Lua

Sujet avancé

Avertissement

  • Soyez prudent et effectuez des tests approfondis lorsque vous utilisez des scripts Lua pour le contrôle automatisé de périphériques distants afin d'éviter tout fonctionnement inattendu ou tout dommage aux équipements connectés.

Introduction

Les compteurs eGauge disposent d'un environnement de script Lua qui permet la création de fonctions avancées d'enregistrement de formules et d'alerte, ainsi que le contrôle automatisé des appareils pris en charge tels que le module de relais de puissance eGauge PRM3 .

Consultez l'article « Présentation du langage de script Lua » pour une introduction générale à Lua et aux modules supplémentaires fournis par le firmware eGauge.

Interface de script Lua

L'interface web d'eGauge possède un éditeur de script Lua intégré avec 3 volets, comme le montre la capture d'écran ci-dessus.

  • Éditeur ( en haut à gauche ) : L’éditeur de code Lua. Ce panneau comporte quatre boutons.
    • [1] Enregistrer : Ceci enregistre les fonctions et les rend disponibles pour utilisation par le compteur.
    • [2] Recherche : Ceci permet de rechercher et de remplacer du texte dans le code.
    • [3] Téléchargement : Ceci remplace le script actuel sur le compteur par un fichier téléchargé.
    • [4] Téléchargement : Ceci télécharge le script actuel du compteur sous forme de fichier.
  • Journal de sortie ( en bas à gauche ) Sous l'éditeur, le journal Lua s'affiche. Il contient les erreurs de script et les instructions d'impression. Si aucune fonction Lua personnalisée n'est chargée pour le script, une erreur du type « Erreur Lua : impossible d'ouvrir xxx.lua : Aucun fichier ou répertoire de ce type » peut survenir. Vous pouvez ignorer cette erreur. Ce panneau comporte quatre boutons :
    • [5] Filtre : Appliquer un filtre pour n'afficher que les lignes de journal contenant un certain texte.
    • [6] Défilement automatique : Active le défilement automatique vers la sortie de journal la plus récente.
    • [7] Téléchargement : Télécharge le fichier journal.
    • [8] Agrandir la fenêtre : Agrandit la fenêtre de sortie du journal.
  • Barre latérale ( à droite ) La barre latérale de droite propose un explorateur de méthodes permettant de trouver et de décrire toutes les fonctions et tous les modules fournis par eGauge. Un clic sur une fonction ou un module permet de l'insérer automatiquement dans le volet Éditeur à gauche. La barre latérale comporte une barre de recherche [9] facilitant la recherche de méthodes, de fonctions et de documentation.

Plusieurs raccourcis clavier s'affichent lors du chargement de l'interface :

  • F1 : Ouvrir le menu des raccourcis clavier
  • F2 : Afficher/masquer la barre latérale de droite
  • Ctrl-␣ : Activer/désactiver la saisie semi-automatique
  • Ctrl-, : Ouvrir le menu des paramètres de l'interface graphique

Accès à l'environnement de script Lua

Étape 1 : Si vous utilisez l’« interface classique », cliquez sur Affichage → Interface utilisateur moderne

Si nécessaire, accédez à l'interface utilisateur moderne depuis la vue classique, comme indiqué ci-dessus.

Étape 2 : Accédez à Configuration → Lua et choisissez le type de script approprié :

Types de scripts

Script de formules

La création de fonctions Lua dans l'éditeur de scripts Formulas permettra d'utiliser ces fonctions dans un registre de formules.
Par exemple, voici deux fonctions créées dans l'éditeur de scripts Lua Formulas qui renverront le minimum ou le maximum de deux nombres :

-- function returning the larger of two numbers
function lua_max(num1, num2)
 if (num1 > num2) then
    result = num1;
 else
    result = num2;
 end
 return result;
end

--function returning the lesser of two numbers
function lua_min(num1, num2)
 if (num1 < num2) then
    result = num1;
 else
    result = num2;
 end
 return result;
end

Elles peuvent ensuite être utilisées dans un registre de formules :

Et nous pourrons constater que les registres fonctionnent comme défini par les fonctions du script :

Script tarifaire

Ce script Lua permet de mettre en œuvre des systèmes de facturation avancés en fonction des heures d'utilisation et à plusieurs niveaux.

  • Le service d'assistance eGauge n'est pas en mesure de fournir des modèles de tarifs pour différents fournisseurs de services publics.

Un script tarifaire doit fournir (au moins) une fonction cost( register, negate, schedule ) qui calcule le coût supplémentaire en fonction de la consommation d'énergie enregistrée par `register`. `negate` peut être défini sur `true` si la valeur de `register` décrémente la consommation électrique. `schedule` est facultatif et peut être défini sur le nom (non par défaut) du planning à utiliser pour le calcul du coût.

Un registre de formules de type « monétaire » serait utilisé avec la fonction cost() .

Voici un exemple de script de facturation, tiré de l'interface classique :

  1. Accédez à Paramètres → Facturation .
  2. Choisissez Xcel Colorado comme fournisseur de services tarifaires.
  3. Cliquez sur « OK » pour enregistrer et revenir à la page principale des paramètres.
  4. Retournez à Paramètres → Facturation .
  5. Changez le fournisseur de tarifs en « personnalisé ».
  6. Cliquez sur le bouton « Personnaliser le script tarifaire », ce qui ouvrira une copie du tarif de facturation Xcel Colorado dans l'éditeur de script Lua.

Script d'alerte

Les scripts d'alertes fonctionnent de la même manière que les scripts de formule, mais sont utilisés dans les alertes des compteurs eGauge, configurées dans Configuration → Autres paramètres puis Alertes à gauche.

Scripts de contrôle

Avertissement

  • L'utilisation de scripts de contrôle comporte un risque d'endommagement du matériel externe. Seuls les développeurs Lua expérimentés, connaissant bien l'appareil et le logiciel eGauge, devraient tenter d'utiliser des scripts de contrôle Lua.

Information

Consultez la section principale « Scripts de contrôle » du document « Présentation du langage Lua » pour obtenir des informations supplémentaires sur l’environnement de contrôle Lua.

Les scripts de contrôle peuvent être utilisés pour contrôler les équipements pris en charge tels que le module de relais de puissance eGauge (PRM3).

Par exemple, le script suivant lit la valeur instantanée d'un registre nommé « Température » et commande un contact de relais PRM3. Si la température est inférieure à 21 °C, le relais n° 0 du PRM3 est fermé (activé) ; sinon, il est ouvert (désactivé). Le système se met ensuite en veille pendant 15 minutes avant de procéder à une nouvelle vérification.

Dans la réalité, le script de contrôle devrait être plus avancé.

dev = ctrl:dev({interface='relay'})
  relay = dev:interface('relay')

  while true do
    print("Temperature is currently: " .. __r("Temperature"))
    if __r("Temperature") < 21 then
        relay:close(0)
    else
        relay:open(0)
    end
    sleep(60*15)
  end

Variables persistantes

Consultez la section principale « Présentation du langage Lua » sur les variables persistantes.

Les variables persistantes sont des variables qui sont conservées entre les redémarrages ou les cycles d'alimentation.

Le script Formula suivant crée et met à jour une variable persistante avec un nom et un numéro donnés qui lui sont transmis dans un registre de formule, et affiche les informations de débogage dans le journal de sortie :

function persistent_variable_example(name, number)
  
     obj = persistent:new(name, number, "Variable stored by formula function persistent_variable_example")
  
     current_value = obj:get()
     print(name .. " currently has value " .. current_value)
  
     print("updating " .. name .. "to new value " .. number)
  
     obj:set(number)
  end

Un registre est configuré pour exécuter le script de formule :

Cela crée ou met à jour une variable persistante appelée variable test 1 avec l'heure actuelle.

L'éditeur de script de formule affiche les informations de débogage à mesure que la variable est mise à jour une fois par seconde lors de l'exécution du registre de formule :

15:26:28.168 variable test 1 currently has value 22.043333333333
15:26:28.168 updating variable test 1 to new value 22.043611111111
15:26:29.171 variable test 1 currently has value 22.043611111111
15:26:29.172 updating variable test 1 to new value 22.043888888889
15:26:30.168 variable test 1 currently has value 22.043888888889
15:26:30.168 updating variable test 1 to new value 22.044166666667
15:26:31.168 variable test 1 currently has value 22.044166666667
15:26:31.168 updating variable test 1 to new value 22.044444444444

Bien que cet exemple précis puisse paraître anodin, les variables persistantes peuvent être utilisées dans n'importe quel script Lua. Les scripts de contrôle s'exécutent en continu ; il n'est donc pas nécessaire de créer un registre de formules pour les exécuter.