Télécharger le PDF
        SAMOVAR 
×
Menu
Recherche
 
   
   
   
 
  Manuel d’utilisation    

À propos du langage de script Lua.

 
Samovar prend en charge l'automatisation basée sur le langage de programmation de script Lua. La prise en charge de Lua s'active à la compilation du micrologiciel : dans le configurateur — la case « Utiliser Lua » («Использовать Lua») (section « Équipement » («Оборудование»)), dans PlatformIO — l'environnement Samovar_lua, dans une compilation manuelle — la ligne #define USE_LUA dans le fichier user_config_override.h. L'éditeur de scripts s'ouvre avec le bouton « Éditeur » («Редактор») de la page Réglages (adresse http://samovar.local/edit). Aucun identifiant ni mot de passe n'est demandé.
La version actuelle de Lua est 5.4.4
 
Au démarrage de Samovar, le fichier init.lua s'exécute. Son rôle est d'activer ou de désactiver la boucle d'exécution des scripts toutes les secondes et d'initialiser les variables qui seront utilisées dans d'autres scripts. Dans la version livrée, init.lua désactive la boucle : setNumVariable("loop_lua_fl",0).
Si l'exécution des scripts en boucle est activée, deux scripts sont lancés chaque seconde : d'abord script.lua, puis le script dont le nom dépend du mode de fonctionnement : rectificat.lua (Rectification), dist.lua (Distillation), beer.lua (Bière), bk.lua (Colonne à moût), nbk.lua (NBK), suvid.lua (Sous vide), cheese.lua (Fabrication du fromage). En « mode Lua » («Lua-режим») (un élément de la liste des modes dans les Réglages, visible uniquement dans une version avec Lua), il n'y a pas de script de mode — toute la logique du mode est écrite dans script.lua. Une paire de scripts peut aussi être lancée une seule fois en ouvrant http://samovar.local/lua, et un fichier isolé à l'adresse http://samovar.local/lua?script=file_name.
Les scripts s'exécutent l'un après l'autre dans une seule tâche : pendant que l'un tourne, l'autre attend. Une exécution de script ne peut pas durer plus de 20 secondes — au-delà, elle est interrompue avec le message « Lua : exécution du bloc interrompue par délai dépassé » («Lua: выполнение чанка прервано по таймауту»). Si un script de mode se termine par une erreur 5 fois de suite, la boucle d'une seconde s'arrête (loop_lua_fl est remis à 0) et un message récapitulatif est affiché dans la console ; script.lua cesse d'être exécuté après 5 erreurs de suite jusqu'au rechargement des scripts, sans arrêter la boucle. Les erreurs des scripts sont écrites dans la console du navigateur et dans le moniteur du port.
 
Vous pouvez aussi ajouter à l'interface des boutons qui lancent des fichiers. Nom du fichier : btn_<mode>_button<N>.lua, où mode vaut rect, dist, beer, bk, nbk, suvid ou cheese, et N est le numéro du bouton. Par exemple, btn_rect_button1.lua, btn_beer_button2.lua. Les boutons s'affichent dans l'onglet « Supplémentaire » («Дополнительно») de la page principale du mode pour lequel ils ont été créés, dans le bloc Lua ; on y trouve aussi le champ « Lua : » («Lua:») avec le bouton « Exécuter Lua » («Выполнить Lua») pour lancer une ou deux lignes de code, et « État Lua » («Статус Lua») — une ligne que le script définit avec la fonction setLuaStatus.
Le nom du bouton se définit dans la première ligne du fichier par un commentaire de la forme --|Nom^ (par exemple, --|Start^). En l'absence de cette ligne, les boutons s'appellent LUA1, LUA2, etc., dans l'ordre des fichiers trouvés.
Dans la version livrée, chaque mode a deux boutons : « Démarrer » («Начать») (btn_*_button1.lua — active la boucle d'une seconde) et « Arrêter » («Остановить») (btn_*_button2.lua — la désactive).
Le rôle principal des boutons est de lancer l'exécution des scripts en boucle (par exemple en définissant la valeur d'une variable qui pourra ensuite être lue dans le script exécuté en boucle), ou d'allumer ou éteindre un organe de commande (par exemple une pompe).
 
L'architecture d'utilisation des boutons se présente donc ainsi (à titre d'exemple - pour le mode distillation) :
  1. La boucle principale pilotable : une fois par seconde script.lua => dist.lua => script.lua => dist.lua =>... (pilotable au sens où elle peut être lancée ou arrêtée par programme depuis n'importe quel script au moyen d'une variable globale)
  2. Le script script.lua est commun à tous les modes ; vous pouvez y placer le code qui doit s'exécuter dans n'importe quel mode (rectification, bière, sous vide, etc.)
  3. Le script dist.lua ne sera utilisé qu'en mode distillation ; vous pouvez y placer toute la logique qui doit s'exécuter une fois par seconde selon les paramètres que ce script obtient des variables globales de Samovar, par exemple getNumVariable("TankTemp"), ou des variables enregistrées par n'importe quel script dans l'espace de noms commun, par exemple getObject("StartTankFilling"). Autrement dit, dans le code de ce script, vous pouvez placer par exemple la condition :
    if (StartTankFilling == "true" and TankFillingPercent < 80) then StartPump() else StopPump() end
    et chaque seconde, le script vérifiera s'il existe un indicateur demandant de remplir le bouilleur et, si c'est le cas, s'il est déjà rempli à 80% et s'il faut maintenant arrêter la pompe lancée précédemment.
  4. Le script de bouton btn_dist_button1.lua qui, à l'appui sur le bouton, définit l'indicateur demandant de remplir le bouilleur via setObject("StartTankFilling", "true"). Au cycle suivant, une seconde plus tard, le script dist.lua lira cet indicateur et allumera la pompe (si le bouilleur n'est pas encore rempli). Ainsi, tous les scripts partagent un espace de noms commun, accessible via setObject/getObject, ce qui leur permet d'échanger des données.
  5. Le script de bouton btn_dist_button2.lua qui, à l'appui sur le bouton, peut arrêter la boucle principale pilotable via setNumVariable("loop_lua_fl", 0), par exemple si quelque chose ne va pas avec les scripts.
 
Ligne de programme de type L (étape Lua). Dans les programmes de tous les modes sauf la NBK (Rectification, Distillation, Colonne à moût, Bière, Fabrication du fromage), il existe une ligne de type L — une étape pilotée par Lua. Lorsque ce type est choisi dans l'éditeur de programme, la fenêtre « Étape Lua » («Lua-этап») s'ouvre ; vous y définissez :
Lorsque le programme atteint une ligne L, Samovar lance le fichier choisi et attend un appel à setNextProgram() — c'est le passage à la ligne suivante. Une erreur du script (« Lua s'est terminé avec une erreur » («Lua завершилась с ошибкой»)) ou un dépassement du délai arrête le mode. Les autres champs de la ligne (température, débit, récipient, appareil) ne sont pas renseignés pour le type L. Sous forme de texte, une telle ligne est stockée comme le fichier et les paramètres séparés par le caractère ^, par exemple L;120;hops.lua^3^45;0;0;0 pour la rectification.
Exemple du script dose.lua, qui allume le relais dont le numéro est donné dans le premier paramètre pendant la durée donnée dans le second (dans le programme : fichier dose.lua, paramètres 3 et 1500) :
set_i2c_rele_state(tonumber(arg[1]), 1)
delay(tonumber(arg[2]))
set_i2c_rele_state(tonumber(arg[1]), 0)
setNextProgram()
Si, pendant le fonctionnement, vous téléversez via l'éditeur de fichiers une nouvelle version du fichier en cours d'exécution par une ligne L, Samovar relira le script sans redémarrer le programme.
 
Fonctions de Samovar
Depuis les scripts, vous pouvez accéder aux variables internes de Samovar (certaines ne peuvent pas être modifiées, elles sont en lecture seule) et appeler les fonctions de Samovar. Pendant un changement de mode, les fonctions qui modifient l'état de Samovar se terminent avec l'erreur "mode switch blocks state changes".
Les numéros de broches dépendent de la carte. Ici et plus loin, transmettez leur valeur numérique :
Les constantes INPUT, OUTPUT, LOW, HIGH et les codes de résultat de commande ACTUATOR_COMMAND_ACCEPTED, ACTUATOR_COMMAND_PENDING, ACTUATOR_COMMAND_APPLIED, ACTUATOR_COMMAND_FAILED sont définis dans les scripts.
 
pinMode(pin, mode) – comme la fonction Arduino du même nom, définit le mode de fonctionnement de l'entrée/sortie (pin) indiquée : entrée ou sortie. Le changement de mode n'est disponible que pour les ports RELE_CHANNEL1–RELE_CHANNEL4 et LUA_PIN. Ainsi, pour configurer le port RELE_CHANNEL4 de la carte DEVKIT en entrée, appelez pinMode(13, INPUT) ; en sortie - pinMode(13, OUTPUT).
digitalWrite(pin, Value) – comme la fonction Arduino du même nom, applique une valeur HIGH ou LOW à une sortie numérique (pin). Les ports RELE_CHANNEL1–RELE_CHANNEL4, WATER_PUMP_PIN, LUA_PIN, ALARM_BTN_PIN et BTN_PIN sont disponibles, les autres sont ignorés. Ainsi, pour mettre un niveau haut sur la sortie RELE_CHANNEL4, appelez digitalWrite(13, 1). Pour WATER_PUMP_PIN avec une pompe PWM, la valeur 1 met la pompe en marche à pleine vitesse, 0 l'arrête. Si la protection d'urgence de la chauffe s'est déclenchée, l'écriture sur les canaux de chauffe (RELE_CHANNEL1, RELE_CHANNEL4) n'est pas effectuée.
digitalRead(pin) – comme la fonction Arduino du même nom, lit la valeur de l'entrée indiquée - HIGH ou LOW. Ainsi, pour lire la valeur présente sur l'entrée ou la sortie RELE_CHANNEL4, appelez digitalRead(13)
analogRead() – comme la fonction Arduino du même nom, lit la valeur de l'entrée analogique LUA_PIN (sans paramètres). La tension appliquée à l'entrée analogique est convertie en une valeur de 0 à 4095. ATTENTION ! Appliquer à l'entrée une tension supérieure à 3,3 volts peut endommager le port, voire tout l'ESP32. En mode Fabrication du fromage, LUA_PIN est occupé par le capteur de pH : pinMode et digitalWrite sur cette broche se terminent par une erreur.
exp_pinMode(pin, mode) – comme pinMode(pin, mode), mais pour commander l'extension de ports PCF8575 ; pin est le numéro de port de l'extension (0–15), mode vaut INPUT, OUTPUT ou INPUT_PULLUP. Tous les ports de l'extension peuvent être configurés en lecture ou en sortie
exp_digitalWrite(pin, Value) – comme digitalWrite(pin, Value), mais pour commander l'extension de ports PCF8575 ; pin est le numéro de port de l'extension (0–15), Value vaut 1 ou 0. Tous les ports de l'extension sont disponibles en écriture
exp_digitalRead(pin) – comme digitalRead(pin), mais pour commander l'extension de ports PCF8575 ; pin est le numéro de port de l'extension (0–15). Tous les ports de l'extension sont disponibles en lecture
exp_analogWrite(Value) – comme analogWrite(pin, Value), mais pour commander l'extension de ports PCF8591, Value est une valeur de 0 à 255. L'extension dispose d'un seul port en sortie.
exp_analogRead(pin) – comme analogRead(), mais pour commander l'extension de ports PCF8591 ; pin est le numéro d'entrée de l'extension (0–3), renvoie une valeur de 0 à 255.
Les fonctions exp_* n'existent que dans un micrologiciel compilé avec USE_EXPANDER (PCF8575) et USE_ANALOG_EXPANDER (PCF8591).
delay(ms) – comme la fonction Arduino du même nom, suspend l'exécution du programme pendant le nombre de millisecondes indiqué en paramètre (1000 millisecondes dans 1 seconde). Pas plus de 1000.
millis() – comme la fonction Arduino du même nom, renvoie le nombre de millisecondes écoulées depuis le démarrage de Samovar
setTimer(Num, Sec) – règle le minuteur numéro Num sur Sec secondes (jusqu'à 65535). Il y a 10 minuteurs, de 1 à 10. Les scripts peuvent donc utiliser au plus 10 minuteurs en même temps
getTimer(Num) – obtient le temps restant du minuteur numéro Num, en secondes. Si le minuteur n'est pas réglé ou si le temps est écoulé, la fonction renvoie 0
sendMsg(Msg, Level) – Si Level = -1, le message Msg est affiché sur le port COM et dans la console du navigateur, ce qui est pratique pour le débogage. Si Level vaut 0, 1 ou 2, le message est envoyé comme message du système (0 – alarme, 1 – avertissement, 2 – notification) : sur l'écran, dans l'interface web, dans les applications et sur le site.
setPower(Power) – allume/éteint Samovar. setPower(0) l'éteint, setPower(1) l'allume (comme le bouton de chauffe du mode en cours)
setCurrentPower(Value) – applique la valeur Value au régulateur. Si un régulateur à commande de puissance (SEM/AVR) est utilisé, Value est la puissance à appliquer en watts, sinon c'est la tension avec une précision de 0.1 V. La fonction n'existe que dans une version avec régulateur de puissance.
setBodyTemp() – fixe la température du cœur pendant la rectification. Ne fonctionne qu'en mode rectification. Dans les autres modes, elle affiche dans la console un message indiquant que la température du cœur ne peut pas être fixée
setMixer(Val) – allume/éteint l'agitateur. setMixer(0) – arrêt, setMixer(1) – marche
openValve(Val) – ouvre/ferme la vanne d'eau. openValve(0) – fermer, openValve(1) – ouvrir
setPumpPwm(Val) – règle la vitesse de la pompe à eau, Val de 0 à 1023. N'existe que dans une version avec pompe PWM (USE_WATER_PUMP).
setMixer, openValve, setCurrentPower et setPumpPwm renvoient le code de résultat de la commande (les constantes ACTUATOR_COMMAND_*).
setAlarm() – active le mode alarme. Samovar coupe la puissance, ferme la vanne d'eau et arrête la pompe à eau
setNextProgram() – passe au programme suivant. Comme l'appui sur le bouton « Programme suivant » («Следующая программа») de l'interface. Ne fonctionne que lorsque la chauffe est allumée.
setPauseWithdrawal(Val) – met en pause/reprend le soutirage. setPauseWithdrawal(0) – reprendre, setPauseWithdrawal(1) – pause
setCapacity(Num) – tourne le servomoteur vers le récipient numéro Num (0 – évacuation, 1 et plus – récipients).
setServoAngle(Angle) – tourne le servomoteur de Angle degrés (0–180). Renvoie 1 si le micrologiciel dispose d'une sortie servomoteur (SERVO_PIN), sinon 0. Sert aux doseurs d'additifs faits maison (voir Doseurs d'additifs) ; le servomoteur est partagé avec setCapacity, il faut donc redéfinir le récipient après l'avoir tourné en rectification.
getState() – obtient l'état de Samovar (un nombre), pratique pour savoir dans quel état se trouve Samovar : 0 – au repos ; rectification : 10 – soutirage en cours, 15 – pause automatique entre les lignes du programme, 20 – programme terminé, 30 – étalonnage de la pompe de soutirage, 50 – montée en température, 51 – stabilisation, 52 – stabilisation terminée ; 40 – pause manuelle (dans n'importe quel mode) ; 1000 – distillation en cours, 2000 – bière, 3000 – colonne à moût, 4000 – NBK, 5000 – fabrication du fromage.
setNumVariable("Variable", Val) – définit une variable numérique interne de Samovar. Toutes les variables ne peuvent pas recevoir de valeur (liste ci-dessous). setNumVariable("loop_lua_fl", 1) active la boucle des scripts toutes les secondes. Attention ! Si vous ne comprenez pas le fonctionnement de Samovar, mieux vaut ne pas utiliser cette fonction, car vous risquez de perturber son fonctionnement
setStrVariable("Variable", Val) – définit une variable chaîne interne de Samovar. Toutes les variables ne peuvent pas recevoir de valeur. setStrVariable("SamovarStatus", "Test Samovar status")
getNumVariable("Variable") – obtient une variable numérique interne de Samovar. TankTemp = getNumVariable("TankTemp") affecte la valeur de la température du bouilleur à la variable de script TankTemp
getStrVariable("Variable") – obtient une variable chaîne interne de Samovar.
program_type = getStrVariable("program_type")– affecte le type du programme en cours à la variable de script program_type.
 
Les variables de script n'existent que pendant l'exécution du script. Leurs valeurs ne sont pas conservées à l'exécution suivante. Il faut parfois mémoriser la valeur d'une variable lors d'une exécution et la relire lors d'une autre. Deux fonctions servent à cela – setObject("Object",Val) et getObject("Object")/getObject("Object","NUMERIC"). Les valeurs définies sont conservées jusqu'au redémarrage. Il ne peut pas y avoir plus de 32 objets différents ; au-delà, setObject se termine par une erreur.
setLuaStatus(Status) - affiche l'état du script dans l'interface (« État Lua » («Статус Lua») dans l'onglet « Supplémentaire » («Дополнительно»)). Par exemple, pour suivre l'exécution d'un script :
i = getObject("cnt", "NUMERIC")
i = i + 1
setLuaStatus("Counter cnt = "..i)
setObject("cnt", i)
setObject("Object",Val) – mémorise l'objet Object avec la valeur Val dans la mémoire de Samovar.
getObject("Object") – obtient la valeur enregistrée auparavant de l'objet Object. Si aucun objet de ce nom n'a été enregistré, une chaîne vide est renvoyée. Si vous essayez d'utiliser une chaîne vide comme nombre, elle prendra la valeur nil – non définie. Pour faciliter le travail avec les valeurs numériques et éviter de tester nil, vous pouvez appeler cette fonction avec le paramètre supplémentaire "NUMERIC" ; dans ce cas, si l'objet n'a pas encore été initialisé, 0 est renvoyé.
Exemple d'utilisation de setObject/getObject :
n = 156
setObject("MyObject", n)
print (n)
n = n + 5
print (n)
n = getObject("MyObject")
print (n)
Si vous lancez ce script, il affichera dans le moniteur de port Arduino
156
161
156
 
http_request(Url) – effectue une requête GET vers l'adresse Url et renvoie le corps de la réponse (ou la chaîne "error"). Vous pouvez par exemple envoyer des mesures vers votre propre service web. Vous pouvez aussi envoyer une requête POST en passant quatre paramètres : l'adresse, la méthode, l'en-tête Content-Type et le corps :
http_request("http://test.com:80/post?foo1=bar1", "POST", "Content-Type: text/text; charset=utf-8", "body")
Exemple de script qui envoie la température du bouilleur vers un service web externe (remplacez l'adresse et les paramètres par les vôtres) :
local char_to_hex = function(c)
  return string.format("%%%02X", string.byte(c))
end
 
local function urlencode(url)
  if url == nil then
    return
  end
  url = url:gsub("\n", "\r\n")
  url = url:gsub("([^%w ])", char_to_hex)
  url = url:gsub(" ", "+")
  return url
end
 
function SendToServer(text)
  local key = "my_secret_key" -- your service access key
  http_request("http://example.com/notify?key=" .. key .. "&text=" .. urlencode(text))
end
 
local text = "Current boiler temperature = ".. getNumVariable("TankTemp")
SendToServer(text)
 
Les fonctions de la carte I2CStepper (agitateur, pompe doseuse, relais) – set_stepper_by_time, set_stepper_target, get_stepper_status, i2cpump_start, i2cpump_stop, i2cpump_get_speed, i2cpump_get_target_ml, i2cpump_get_remaining_ml, i2cpump_get_running, set_mixer_pump_target, get_mixer_pump_status, set_i2c_rele_state, get_i2c_rele_state, check_I2C_device – sont décrites sur la page I2CStepper.
 
Variables
Liste des variables internes disponibles par défaut dans un script (leurs valeurs sont remplies avant chaque exécution du script, les modifier par affectation ne sert à rien) :
 
Variables disponibles via getNumVariable (lecture seule) : WFpulseCount, pump_started, valve_status, SamSetup_Mode, Samovar_Mode, Samovar_CR_Mode (le mode actuel et le mode vers lequel on bascule, numéros comme dans SamSetup_Mode), SteamTemp, PipeTemp, WaterTemp, TankTemp, ACPTemp, WFtotalMilliLitres, WFflowRate, program_volume, program_speed, program_temp, program_power, program_time, program_capacity_num, capacity_num, target_power_volt, PowerOn, PauseOn, program_Wait, alcohol (la teneur en alcool dans le bouilleur d'après la température), alcohol_s (la teneur en alcool d'après la vapeur), water_pump_speed (la vitesse de la pompe à eau 0–1023), pressure_value (la pression dans le bouilleur), YY, MM, DD, HH, MI, SS (année, mois, jour, heures, minutes, secondes).
Variables disponibles via getNumVariable et setNumVariable : acceleration_temp, boil_temp (la température d'ébullition mémorisée), wp_count, test_num_val, loop_lua_fl, SetScriptOff, show_lua_script. Uniquement via setNumVariable : pmpKp, pmpKi, pmpKd – les coefficients PID de la pompe à eau.
Variables chaînes (getStrVariable/setStrVariable) : SamovarStatus – le texte d'état de la page principale (lecture et écriture), test_str_val (lecture et écriture), program_type (lecture seule), Msg – en lecture, renvoie le message du système non lu suivant ou une chaîne vide, en écriture, ajoute un message.
 
Variables de commande des scripts :
loop_lua_fl – valeurs 0 ou 1. Si 0 – ne pas exécuter la boucle des scripts toutes les secondes, 1 – l'exécuter.
SetScriptOff – valeurs 0 ou 1. Si 1 – arrêter la boucle de chaque seconde (remet loop_lua_fl à zéro). Samovar la met lui-même à 1 à la fin d'un programme.
show_lua_script – valeurs 0 ou 1. Si 0 – ne pas afficher le script exécuté dans la console et le moniteur de port, 1 – l'afficher. Utile pour le débogage. Les valeurs de toutes les variables définies pour ce script s'affichent également.
Par exemple, si vous appelez ces deux fonctions dans le script init.lua, deux scripts (script.lua et celui déterminé par le mode actuel de Samovar) s'exécuteront chaque seconde, et chaque script sera affiché dans le moniteur de port et dans la console du navigateur
setNumVariable("loop_lua_fl",1)
setNumVariable("show_lua_script",1)

Sommaire À propos du langage de script Lua

Exemples de scripts