Skip to content

Latest commit

 

History

History
528 lines (411 loc) · 35.6 KB

LEGGIMI20.md

File metadata and controls

528 lines (411 loc) · 35.6 KB
Raw

IoTwebUI 2.0: Tuya WEBAPP open extension

english version

Stanco delle limitazioni di SmartLife? IoTwebUI 2.0 è arrivato per dare nuova linfa alla tua casa intelligente, con un arsenale di funzionalità che ti faranno dire "finalmente!".
La filosofia 'open' è nel DNA di questa APP, che esalta la customizzazione ed il controllo da parte dell'utente.

Cosa puoi fare?
👀 Controlla tutto: Interfaccia intuitiva e personalizzabile, dati sempre a portata di mano, visualizzazione flessibile.
🔬 Esportazione dati: Salva le serie storiche per le tue analisi, nel formato più utile
⚡️ Automazioni potenti: Crea automazioni complesse con tap-to-run e RULE, impossibili con SmartLife!
⏱️ Alert personalizzati: Monitora ogni aspetto della tua domotica e ricevi avvisi realtime.
👌 Integrazione perfetta: Combina device, proprietà, RULE e Tuya tap-to-run per un'automazione fluida e completa.

aspetto della versione 2.0

Interfaccia: un piacere per gli occhi e per il controllo

  • Scegli tra il tema chiaro o scuro, a seconda dei tuoi gusti.
  • Naviga tra i tuoi dispositivi e le 'home' con un albero trascinabile e zoommabile, perfetto per tenere tutto sotto controllo.
  • Popup informativi con nuove icone ti terranno aggiornato sullo stato di ogni proprietà di un device, senza perderti neanche un dettaglio.
  • Un menu a scomparsa con informazioni sulla configurazione e opzioni dinamiche ti darà accesso rapido a tutto ciò che ti serve.
  • E se vuoi personalizzare ancora di più, libera la tua creatività con icone, colori e popup informativi a tua scelta.

Dati: al sicuro e sempre a portata di mano

  • Registra i dati delle proprietà che ti interessano su file, così avrai sempre un archivio completo della tua domotica.
  • Calcola medie mobili, valori decodificati o normalizzati per un'analisi ancora più approfondita.
  • Scegli il salvataggio automatico o manuale, con opzioni di formato dati (CSV o JSON), periodo di campionamento e cadenza di salvataggio per adattarsi alle tue esigenze.
  • Gestione al runtime: flessibilità senza limiti

Tap-to-run Tuya: il potere a portata di dito

  • Una pagina dedicata con un tab per ogni "home" ti permette di avere tutto sotto controllo.
  • Caricamento automatico all'avvio per una domotica sempre pronta all'azione.
  • Lancia i tap-to-run Tuya con un semplice click e personalizza i colori dei pulsanti per un'esperienza ancora più intuitiva.
  • Escludi i tap-to-run che non ti servono per avere un'interfaccia pulita e ordinata.

Alert: mai più un evento perso

  • puoi attivare una funzione di controllo su qualsiasi proprietà dei dispositivi e sceglere i test "maggiore", "uguale" o "minore" per monitorare ogni aspetto della tua domotica.
  • Stessa logica delle condizioni Tuya, per un linguaggio comune ed affidabile.
  • Scegli tra diverse azioni conseguenziali: silente, beep, pop-up, messaggio vocale, lancio di URL o tap-to-run Tuya.
  • Real Time, con un ritardo medio garantito pari al 50% del periodo di campionamento Tuya, per un equilibrio perfetto tra rapidità e precisione.
  • Definizione degli Alert al runtime: controllo totale in tempo reale

RULE: Domanda di automazioni più potenti? IoTwebUI 2.0 ha la risposta!

  • Effettuare operazioni logiche ed aritmetiche e utilizzare variabili per una flessibilità senza limiti.
  • Confrontare i valori di due proprietà diverse, per automazioni ancora più libere.
  • Eseguire azioni complesse, come attivare tap-to-run Tuya o inviare comandi ad altre applicazioni via REST.
  • Come funziona?
    1. Crea le RULE al runtime con un'interfaccia user-friendly, anche se non sei un programmatore esperto.
    2. Utilizza MACRO predefinite per i compiti comuni e ripetitivi, risparmiando tempo e fatica.
    3. Testa le tue RULE in tempo reale per assicurarti che funzionino perfettamente.
    4. In caso di errore durante il test, un popup ti indicherà la riga e il tipo di errore per una risoluzione rapida e precisa.
    5. Esporta le tue RULE per inserirle nel file di configurazione e renderle permanenti.

Modalità EXPERT: per controllare tutto il controllabile

La modalità EXPERT offre un controllo totale sulla personalizzazione di IoTwebUI.

  • Accedi alle interfacce di configurazione e apporta modifiche che saranno valide solo per quel run.
  • Copia i dati dal "pad" di esportazione nei file di configurazione per rendere stabili le tue scelte.
  • Puoi disattivare la modalità EXPERT nella configurazione quando hai finito di personalizzare.

Note di implementazione ed uso

  • IoTwebUI deriva da un'interfaccia analoga progettata per TuyaDAEMON.

  • La scelta della libreria di visualizzazione è caduta su Vis-Network per la buona flessibilità unita a semplicità di uso.

  • Un primo problema è il protocollo di sicurezza CORS, implementato sui moderni browser. Una applicazione (anche in js, node-red, etc) non ha questo problema, ma una APP che gira in un browser sì. E' necessario disabilitare CORS al memento del lancio del browser - testato Chrome (Versione 125.0.6422.61 - 64 bit):
    chrome.exe --user-data-dir="C://Chrome dev session" --disable-web-security
    (vedi file run-me.bat). Vale solo per questa istanza, le altre resteranno protette.
    Come alternativa al file 'bat', con alcuni browser si può usare l'estensione 'Cross Domains - CORS', vedi ISSUE4.

  • Tuya pone dei limiti alla frequenza degli accessi al cloud. IoTwebUI ne tiene conto, e la fase iniziale (quando legge tutti i dati dal Cloud) è bloccante e non brevissima (3-5 s, in funzione del numero di device). Come anche in SmartLife.

  • Un secondo problema è l'impossibilità di creare file direttamente da una pagina HTML, sempre per motivi di sicurezza. Per l'export dei dati sono ricorso ad una libreria di logging su file debugout.js. Per questo motivo il controllo sui file generati non è completo e sono necessari piccoli interventi manuali sui file esportati.

  • I file di datalog sono salvati nella dir download, con il nome tuyalog-hh-mm-ss.csv|json.

  • Per lo stesso motivo non è possibile aggiornare dall'APP i file di configurazione. Ho scelto una soluzione di compromesso, che prevede l'intervento dell'utente con un semplice copia-incolla.

  • Il funzionamento continua regolarmente anche con la finestra del browser iconizzata.

Interfaccia utente

Nei tooltip, che si aprono al passaggio del mouse su un'icona di device, sono presenti tutte le proprietà incluse nello 'status' del device, con i nomi ed i valori usati da Tuya Cloud. Alcuni valori possono essere codificati.
Alcune piccole icone forniscono ulteriori informazioni all'utente (vedi figure sopra):

  • tuya_bridge.switch_1 è sotto osservazione per un 'alert'
  • tuya_bridge.switch_inching è un esempio di valore codificato (AAAC).
    nota: Se siete interessati alla decodifica dei valori Tuya, molte funzioni sono state sviluppate per tuyaDAEMON (vedi 'core_device', nodo 'ENCODE/DECODE user library').
  • temperatura studio.va_temperature è salvato sul datafile, insieme agli altri dati in logList.
  • Per il device temperatura soggiorno è scattato l'Alert (icona speciale)
  • temperatura soggiorno.va _humidity è la causa dell'Alert, ed è anche indicata la condizione (>40)
  • Il tooltip termo studio è customizzato, per presentare le temperature con i corretti decimali. (nota: solo nel tooltip: Alert e RULE usano sempre il valore fornito da Tuya Cloud, i.e. 222 e 190).
  • In modo EXPERT sono aggiunti nei tooltip i seguenti valori:
    • isa: nome del 'tipo' Tuya del device (in codice è device.category). In totale circa 600 tipi.
    • id: device.id, richiesto da alcuni HUB (e.g. TuyaDAEMON, Homebridge, HA, etc..).
    • key: device.local_key, richiesto da alcuni HUB

tap-to_run Tuya

I 'tap-to-run sono presentati per 'home' (max 100) ed in ordine alfabetico. I nomi dei 'tap-to-run' possono avere due vicoli:

  • Utilizare prefissi per raggruppare in IoTwebUI i comandi correlati.
  • Essere facili da ricordare e da riconosere (se si usano i comandi vocali con Google o Alexa).

Logging ed esportazione dati

E' possibile esportare su un file alcuni dati: l'utente deve specificare solo device e status (proprietà) per identificare i dati che interessano e questi sono salvati ad intervalli regolari (minimo 1 minuto) in un buffer interno (max 5000 records - pari a 80h @1 rec/min), esportato poi su file automaticamente o su comando utente.
L'utente può scegliere in configurazione tra due formati: CSV (indicato, per esempio, per DB e spreadsheet tipo Excel) oppure JSON (per elaborazioni più complesse con programmi ad hoc) con pochissimi interventi di editing sui file (vedi oltre i formati).

In modo EXPERT cliccando su un device si apre un dialogo, nella parte superiore interessa l'export dei dati su file:
  • newLog - aggiunge al log (solo per il run corrente)
  • clear dev - elimina il device dal log, (tutte le proprietà)
  • config - apre pop-up per vedere le definizioni del log attuale
    I 'log' permanenti sono nel file `config.js`: possono essere editati direttamente o copiati dal pop-up.
  • cancel - chiude il dialogo.

In modalità EXPERT è disponibile nel menu un comando per avere nella console l'intera struttura dati ottenuta da Tuya Cloud ('Dump data'): può essere esplorata a ogni livello nel pad della console oppure può essere copiata con copy&paste in formato JSON.

Alert ed avvisi

In modo EXPERT cliccando su un device si apre un dialogo che nella parte inferiore permette la definizione degli 'Alert':

  1. Scelta della condizione: 'maggiore', 'uguale' o 'minore'
  2. Il valore di confronto, un numero (24) o una stringa (e.g. true) senza apici (").
  3. Messaggio associato: è usato
    • negli Alert con 'pop-up'
    • è il testo letto nel caso 'voice'
    • oppure è un URL ed allora è aperto nel browser
    • oppure è il nome di un 'tap-to-run' che è eseguito
  4. Azione: una o più a scelta tra 'beep' 'pop' e 'voice' (URL e tap-to-run sono automatiche)

note:

  • Se non si sceglie nessuna azione e si lascia vuoto 'message', l'azione di default è il cambio dell'icona del device e l'aggiornamento del tooltip, sempre eseguiti.
  • Gli 'alert' non hanno, per semplicità, un filtro a tempo: se definiti sono attivi 24/7. Se occorre qualche condizionamento, è possibile creare RULE ad hoc.
  • Notare che 'connected' non è incluso nelle proprietà, e quindi non si possono definire 'Alert'. Ma è disponibile come MACRO nelle RULE.
  • Per avere sia 'pop' che 'tap-to-run', creare due Alert con le stesse condizioni: in uno 'message' sarà il testo per il 'pop-up', nell'altro il nome del 'tap-to-run'.

Bottoni:

  • newTest - aggiunge un nuovo Alert (solo per il run corrente)
  • clear dev - elimina tutti gli Alert del device (solo per il run corrente)
  • config - apre pop-up per vedere le definizioni degli alert attuali.
    Gli 'Alert' permanenti sono nel file `config.js`: possono essere editati direttamente o copiati dal pop-up.
  • cancel - chiude il dialogo.

RULE: automazioni no limits.

In modo EXPERT il menu presenta l'opzione "RULE page" che apre una pagina dedicata alla gestione delle RULE:

Una parte importante è dedicata ad un pad di editing delle RULE (per dettagli vedi oltre).
Nota: se preferite usare un editor esterno più performante, potete certamente farlo, con copia-incolla.
Si possono gestire due insiemi di RULE: quelle in uso, inizialmente lette dal file `usrrulesXX.X.js`, e quelle nuove, in Edit nel pad.

I bottoni presenti offrono le seguenti funzionalità;

  • Clear - pulisce l'area di edit
  • Load - copia in Edit le RULE attualmente in uso
  • Replace - le RULE attualmente in uso sono sostitute da quelle in edit.
  • Export - Crea un pop-up per vedere le definizioni delle RULE in uso. Le RULE permanenti sono nel file 'usrrulesXX.X.js': possono essere editate direttamente o copiate dal pop-up.
  • Test Start - Start test delle RULE in Edit: le RULE in uso sono sospese.
  • Test End- Termina il Test e ripristina le RULE precedenti (auto in caso di errore)

NOTE sulla sicurezza

Per garantire la massima sicurezza, IoTwebUI opera esclusivamente in modalità di sola lettura, senza apportare alcuna modifica ai tuoi dati su Tuya Cloud.

Questa APP è totalmente aperta, priva di ogni protezione, e contiene nei file le vostre credenziali in chiaro!
NON rendetela accessibile dall'esterno o da terzi, altrimenti tutti i vostri dati, credenziali Tuya incluse, sono esposti!

Versioni

  • 2.0 Importante aggiornamento funzionale.

    • Aggiunta la possibilità di attivare le scene "Tap-to-Run" di Tuya da questa APP.
    • Aggiunto 'Avvisi' (Alert): controlla valori ed eseguire azioni (opzioni): segnale acustico, pop-up, messaggio vocale, apertura URL, esecuzione 'Tap-to-Run'
    • Aggiunte "REGOLE utente" (RULE) per automazioni utente senza limiti (richiede competenze js di base)
    • Aggiunto "Registro avvisi" (Alert register) per avvisi e regole
    • Aggiunta interfaccia per la definizione dei dati da registrare sul file dataLog, con esportazione nella configurazione, per una facile manutenzione
    • Aggiunta interfaccia per la definizione degli avvisi, con esportazione nella configurazione, per una facile manutenzione
    • Aggiunta interfaccia per l'editing e il test delle regole al run-time, con esportazione nella configurazione, per una facile manutenzione
    • Interfaccia ridisegnata con Bootstrap 5.3, fluida e con modalità chiara/scura, per una migliore esperienza utente
    • Menu dinamico a scomparsa, per avere il massimo spazio a disposizione del grafo.

  • 1.2 Aggiornamento funzionale.

    • Aggiunta in 'config' la possibilità di escludere alcune 'home'
    • Introdotti due modi: normale | expert
      1. Il DUMP dei dati Tuya in console è possibile solo in modo expert
      2. In modo 'expert' sono aggiunti al tooltip 3 nuovi dati (se disponibili)

  • 1.1 Correzione bugs

  • 1.0 Versione iniziale

Installazione

  1. Scaricare e dezippare il file IoTwebUI.x.x.zip in una dir (con le autorizzazioni richieste dal S.O.).
  2. Eseguire le operazioni di configurazione
  3. Il file principale è IoTwebUI.html. NON è necessario un server WEB, in quanto il codice è tutto in javaScript, eseguito dal browser. Per lanciarlo vedi file run_me.bat (per Windows - Chrome). Per altri S.O. creare uno script analogo. (Ignorare il messaggio Chrome: "stai utilizzando una segnalazione della riga di comando non supportata: - disable-web-security...": non supportata ma funzionante).
    nota: L'addon "Cross Domain - CORS" sembra risolvere il problema senza file BAT, vedi ISSUE4.
  4. In fase di installazione e setup è utile la console (nel browser - strumenti per programmatori -, o menu contestuale 'ispeziona') perchè lì vanno i messaggi di informazione e di errore di IoTwebUI.
    Nelle immagini: a sinistra avvio OK (Chrome, CORS disattivato) a destra in caso di errore CORS (Opera):
normal start CORS error

Configurazione

L'app IoTwebUI non è per utenti alle prime armi, pertanto è accettabile che la configurazione avvenga direttamente editando un file (config.js). Le solite avvertenze: fare una copia del file prima di ogni modifica, usare un editor UTF8 (io uso Notepad-plusplus), e attenzione a NON ALTERARE niente altro (soprattutto virgole ',' ed apici '"' e "`").

  • I dati INDISPENSABILI da inserire sono le proprie credenziali Tuya per la 'platform.tuya'.
    Gli utenti di tuyaDAEMON, Homebridge, HA ed altri hub simili dovrebbero già averle, ma i nuovi utenti si devono iscrivere, ci sono molte guide nel web. Questa è una delle più chiare, altre sono elencate qui. Un vantaggio è che si ha accesso alla piattaforma Tuya, con molti dati sui propri device, ed alla documentazione tecnica.

  • Altre opzioni riguardano: timing (Cloud e log) e configurazione del log: il formato, l'autosave, i valori richiesti, oppure il look&feel, come la presenza dei bottoni di pan/zoom.
    Dalla versione 1.2 la possibilità di escludere alcune home (hide_homes array), e dalla versione 2.0 quella di escludere alcuni tap-to-run (hide_scenes array).

  • Sempre in config.js, la variabile expertModeEnabled = false permette di disabilitare il modo 'EXPERT'.

. Dalla versione 2.0 le definizioni per 'dataLog' (logList in config.js), 'Alert'(testList in config.js) e RULE (usrRules in usrrulesXX.X.js) possono essere create nella APP, con semplici interfacce utente, e poi esportate per essere copiate nei rispettivi file.

  • Aggiornare con i path del sistema ospite il file di lancio run_me.bat.

Customizzazioni

Il IoTwebUI è OpenSource, in HTML+Javascript, è abbastanza documentato e modulare. Quindi è possibile ogni intervento. Alcune aree sono state privilegiate e le rispettive funzioni poste per semplicità in file separati -custom.js e usrrulesXX.X.js con dettagliate istruzioni ed esempi:

  • Tuya non permette più di cambiare le icone, per una opinabile interpretazione dei suoi consulenti legali delle attuali leggi sul copyright.
    Per questa APP, invece, ho scelto le icone awesome4, con un'ampissima scelta e di libero uso. Di default tutti i device hanno la stessa icona, un cubo.
    Ma sono facilmente personalizzabili dall'utente: basta fornire un criterio di selezione dei device e l'indicazione dell'icona awesome4 da usare. Come esempio, hanno icone speciali (vedi immagini):
    • i Termometri (device con nome 'Temp...').
    • le Valvole termostatiche (device con nome 'Termo...').
    • i Gateway (device con 'Gateway' nel nome).

Anche l'icona speciale che indica un'alert è customizzabile: vedi alertIcon in 'config.js'.

  • Il contenuto dei tooltip, varia a seconda del device. E' un settore dove è utile la possibilità di personalizzazioni, il metodo scelto (un filtro) permette ogni libertà:

    • Alcuni valori sono criptati: si può scegliere di non farli vedere - oppure di decodificarli, il codice necessario è disponibile in TuyaDAEMON, ma ho scartato questa opzione per non avere tooltip troppo grandi.
    • In altri casi occorre dividere per 10 o 100 per avere il valore in unità SI.
    • Come sviluppatore preferisco avere i nomi delle proprietà originali Tuya, ma si possono rendere più frendly traducendoli.
    • Se si desidera si possono anche aggiungere nuove informazioni per esempio derivandole da quelle del device (e.g. temperatura in °C ed anche in °F).

  • Per i 'tap-to-run' Tuya, è possibile personalizzare il colore dei pulsanti modificando sceneColor(scene) in custom.js.

  • Per le RULE, i più avventurosi possono aggiungere le loro MACRO personali nel file usrrulesXX.X.js.

Queste customizzazioni NON sono necessarie, ma redono più utile e gradevole l'uso di TuyaUIweb.

formato CSV

Questo è un esempio di file di log in formato CSV:

[date, time, ROMA.TF_frigo.va_temperature, ROMA.Temperatura studio.va_temperature]
[2024-05-17, 06:35:28, 71, 22]
[2024-05-17, 06:37:28, 71, 22]
... more ...

La prima riga contiene l'intestazione delle colonne, le righe succesive i dati. Le operazioni da fare sono le seguenti (in un editor ASCII, ad esempio Notepad++, con 'global find&replace'):

  1. Eliminare la parentesi quadra '[' all'inizio di ogni riga.
  2. Sostituire la parentesi quadra finale con un punto e virgola ';'.

Il risultato CSV corretto è il seguente, importabile in molti DB e spreadsheet:

date, time, ROMA.TF_frigo.va_temperature, ROMA.Temperatura studio.va_temperature;
2024-05-17, 06:35:28, 71, 22;
2024-05-17, 06:37:28, 71, 22;
... more ...

formato JSON

Questo è un esempio di file di log in formato JSON:

[{"home":"ROMA","device":"TF_frigo","status":"va_temperature","result":70,"day":"2024-05-17","time":"19:37:51"},
 {"home":"ROMA","device":"Temperatura studio","status":"va_temperature","result":25,"day":"2024-05-17","time":"19:37:51"}],
[{"home":"ROMA","device":"TF_frigo","status":"va_temperature","result":70,"day":"2024-05-17","time":"19:39:51"},
 {"home":"ROMA","device":"Temperatura studio","status":"va_temperature","result":25,"day":"2024-05-17","time":"19:39:51"}],

Notare che tutti i dati identificativi sono aggiunti ad ogni misura, ottenendo un risultato più verboso del caso CSV. L'operazioni da fare è la seguente (in un editor ASCII, ad esempio Notepad++):

  1. Aggiungere una coppia di parentesi quadre '[]' per racchiudere tutto il contenuto.

Il risultato JSON corretto è il seguente, utilizzabile con parser JSON per ricreare gli oggetti:

[
[{"home":"ROMA","device":"TF_frigo","status":"va_temperature","result":70,"day":"2024-05-17","time":"19:37:51"},
 {"home":"ROMA","device":"Temperatura studio","status":"va_temperature","result":25,"day":"2024-05-17","time":"19:37:51"}],
[{"home":"ROMA","device":"TF_frigo","status":"va_temperature","result":70,"day":"2024-05-17","time":"19:39:51"},
 {"home":"ROMA","device":"Temperatura studio","status":"va_temperature","result":25,"day":"2024-05-17","time":"19:39:51"}],
]

E' un array di array contenenti le singole misure (oggetti).

RULE - sintassi

Il particolare ambiente in cui sono valutate le RULE comporta qualche limite alla sintassi js standard:

  • importante: il codice è eseguito una riga alla volta, non è possibile scrivere blocchi js che occuppino più righe! Per contenere la lunghezza delle righe, usare delle variabili intermedie (vedi esempi).
  • definire le variabili sempre con la sintassi: var _pippo =...
  • usare sempre un underscore _ come primo carattere nel nome delle variabili: si evitano così interferenze con altre variabili.
  • Volori predefiniti:true e false per le condizioni; le costanti numeriche sono con il punto, all'inglese (3.14), e tutte le stringhe vogliono gli apici ("oggi ");
  • Usare // per i commenti, continuano fino a fine riga
  • Le operazioni js più utili sono quelle aritmetiche (+, -, *, /), quelle logiche per le condizioni: (&& -and, || -or, ! -negazione) e le operazioni di confronto ( >, ==, !=, <, >=, <=); la concatenazione delle stringhe è fatta semplicemente con il + ("ore " + "10:30").
  • attenzione al '+': in a + b, se a e b sono numeri, fa la somma, ma se uno dei due è una stringa, automaticamente anche l'altro è convertito in stringa. E la conversione numero => stringa può portare a sorprese quando non sono numeri interi! Usare sempre ROUND() quando dovete usare dei numeri con la virgola nelle stringhe (vedi esempi). . importante è anche l'uso delle parentesi, "()", sempre a coppie. Parentesi servono dopo ogni MACRO - nota, anche se non ci sino parametri, e.g. BEEP() - e dopo un if, per la condizione. comunque usatele liberamente per raggruppare risultati intermedi nelle espressioni e.g. if((_a > 10) && (_b/2 == 0))....
  • le RULE sono eseguite ad ogni loop, dopo un aggiornamento dei dati Tuya. Molte MACRO devono quindi conservare lo stato tra un run ed il successivo, e sono individuate con (*).
  • Il costrutto js più utile nelle RULE è l'if (esecuzione condizionale), che assume varie forme:
    if( condizione ) azione;
    if( condiz1 && condiz2 ) azione1, azione2;
    if ( condizione ) azione1 else azione2;
  • importante: per come sono implementate, le MACRO che usano memoria (*) NON possono essere usate nella parte azione di un if. Per ragioni analoghe non sono ammessi if nidificati (un if nella zona azione di un altro if). Sono vincoli che non pongono, però, serie limitazioni.

ESEMPIO 1: usato per testare le MACRO, funziona con i miei device (deve essere modificato per i vostri). 

// -- various temperature calculations with popup and logging:
//  using variables, and MACROS: GET() AVG() ROUND() EVERY() POP() DATALOG()
 var _tf = GET("TF_frigo","va_temperature"); // read temperature sensor
 var _tm = AVG(_tf, 12);                     // get average from last 12 values
 var _tr = ROUND( _tm/10,  -1);              // round to the nearest ten
 if(EVERY(8)) POP( "FRIGO", "Frigo: "+ _tf/10 + "°C, media: "+_tm/10 +"°C, round " + _tr +"°C");                   // divisions can get problems in numbers!
 DATALOG("frigo.media", _tm/10);            // saves average on file
 
// using again _tf, and MACROS: ISCONNECTED() ISCHANGED()  TIME() VOICE() ROUND()
// note: the delay is a function of the Tuya polling interval and  the device data period.
// In strings, ROUND can be used to cut a number. 

 var _annonce = "Alle ore " + TIME(hrs)+" la temperatura è cambiata. Il frigo è a " + ROUND(_tf/10, 1) + " gradi";
 if(ISCONNECTED("TF_frigo") && ISCHANGED(_tf)) VOICE(_annonce);    

// -- more functions (testing purpose):
// using MACROS: WEEKMAP() BEEP()

 if ( WEEKMAP("DLMM-VS")) BEEP();  // stupid beep every Tuya polling, but not Thursday

// using variables, and MACROS: ISTRIGGERL() DAYMAP() SCENA()

 var _trgl = ISTRIGGERL(GET("tuya_bridge", "switch_1"));
 if(DAYMAP(false,"08:30", true, "22:00") && _trgl) SCENA('sirena2');

// Voice message if someone keeps the door open
// using variables and MACROS: CONFIRMH() ALERTLOG()
// note: this example shows how to debug RULES, using single functions per line and 'console.log()' to see the values of variables.
// note: after an if()  you can use a comma ',' to execute more than one action. 

var _doorev = GET("Sensore porta", "doorcontact_state") ;   //event: true if door open
var _dooropen = CONFIRMH(_doorev, "01:20");         // true only after 1:20
if(ISTRIGGERH(_dooropen)) VOICE("chiudere la porta, grazie"), ALERTLOG("ingresso", "porta aperta") ;
console.log("DOOR", _doorev, _dooropen);

ESEMPIO 2 - Un caso concreto di controllo del riscaldamento
Ho il riscaldamento centralizzato, con valvole termostatiche su ogni radiatore: ogni stanza ha il suo profilo di temperatura desiderato (Ttarget). Tutto funziona molto bene, tranne in casi eccezionali (esempio, impianto spento per manutezione).
Vorrei implementare con Tuya una strategia di questo tipo: se la temperatura ambiente è minore di un 'tot' rispetto a Ttarget, accendere il condizionatore come pompa di calore con lo stesso Ttarget. Cioè:

Se (( Ttarget - Tambiente ) > tot) => clima.warm( Ttarget )

Questa automazione non è realizzabile con Smartlife, nè con Alexa o Google, perchè:

  • non si possono usare operazioni aritmetiche,
  • si possono fare confronti solo con valori costanti,
  • non esistono tap-to-run parametrici od almeno con nomi dinamici.

Chiedo troppo? Un sistema 'open' devrebbe permettere queste automazioni. O no? infatti con le RULE si può fare!
Alcune precondizioni: la mia termovalvola ('Termo letto') ha le proprietà 'temp_set' e 'temp_current'. Per semplicità ho utilizzato come temperatura Target solo i valori 16, 20, 21 °C: in questo modo mi occorrono solo 3 tap-to-run chiamati Tletto16, Tletto20 e Tletto21, per accendere ed impostare il clima.

var _tot = 2.3;  // da tarare il prossimo inverno
var _Ttarget =  GET("Termo letto", "temp_set") ;
var _nowClima = ISTRIGGERH( ( _Ttarget -  GET("Termo letto", "temp_set") ) > _tot);
if (_nowClima) SCENA("TLetto" + ROUND( _Ttarget, 0) ), ALERTLOG("RULE Tletto", "acceso clima") ;

RULE - MACRO

Possiamo dividere le MACRO in due gruppi: il primo che gestisce le interazioni con le risorse disponibili in IoTwebUI (una sorta di API interna). Il secondo gruppo di MACRO sono invece generali, modificando in qualche modo utile i dati in input. nota: obiettivo delle MACRO non è quello di duplicare le funzionalità delle automazioni Tuya (anche se a volte c'è sovrapposizione) e.g. non esistono MACRO per 'meteo' o 'delay', quanto quello di fornire strumenti più avanzati di calcolo, per ottenere 'automazioni' fin'ora impossibili. L'uso di device virtuali e di tap-to-run permette di suddividere i compiti tra scene Tuya (automazioni e tap-to-run) e RULE nel modo più efficiente.
Ovviamente si possono sempre aggiungere nuove MACRO, o come customizzazione (se create nuove MACRO comunicatemelo) oppure in nuove release di IoTwebUI.

MACRO per risorse

ISCONNECTED(device)
Ritorna 'true' se il device (nome o ID) è connesso.
nota: il dato proviene dal Cloud, può differire dal valore locale mostrato da SmartLife.
GET(device, property)
Ritorna il valore di 'property' (i nomi originali mostrati nel tooltip) del device (nome o ID)
DATALOG(name, value) (*)
Aggiunge un nuovo 'value' al file di log dati, con il 'name' indicato.
nota: il salvataggio dati durante un test inizia subito, ma, nel formato CSV, la prima riga con i nomi non è aggiornata. Eventualmente salvare il file di log per avere un nuovo file aggiornato. Questo solo in fase di test: con le RULE in uso dall'avvio non c'è problema.
ALERTLOG(name, message)
Aggiunge il 'message' al registro degli avvisi, identificato da 'name'
BEEP()
Segnale di avviso.
POP(device, message)
Segnale di avviso.
XURL(url)
Segnale di avviso.
VOICE(message)
Segnale di avviso.
SCENA(scenaNome)
Esegue un _tap-to-Run_, presente nell'elenco letto dal Cloud.

MACRO funzionali

ISTRIGGERH(condition) (*)
Ritorna 'true' solo al passaggio della "condizione" da 'false a true', evita che la "condizione" 'true' agisca ad ogni run (analogo alle condizioni delle automazioni Tuya).
ISTRIGGERL(condition) (*)
Ritorna 'true' solo al passaggio della "condizione" da 'true a false' (inverso di ISTRIGGERH).
CONFIRMH(condition, time) (*)
Ritorna 'true' solo se la "condizione" rimane 'true' per almeno il tempo 'time'. Poi resta 'true' fino a quando la 'condizione' è 'true'. Caso tipico una porta aperta: vedi esempi.
time = costante nei formati "hh:mm:ss" oppure "mm:ss" oppure "ss". Deve essere maggiore di TuyaInterval.
CONFIRML(condition, time) (*)
Ritorna 'true' solo se la "condizione" rimane 'false' per almeno il tempo 'time' (inverso di CONFIRMH).
HYSTERESIS (value, test, delta) (*)
Confronta 'value' con 'test', usando come intervallo di isteresi 'delta'. L'output diventa 'true' se 'value > test + delta/2', oppure 'false' se 'value < test - delta/2'.
EVERY(n) (*)
Semplice timer: ritorna 'true' solo dopo "n" esecuzioni, ciclico
E' garantito un singolo valore 'true' per ogni n-simo loop (non richiede ISTRIGGERH()). 'n' è in numero di loop, in tempo: t = n x tuyaInterval (definito in 'config.js' file).
TIME(wath)
ritorna una stringa, "hh:mm:ss" oppure "mm:ss" oppure "ss" calcolata dall'ora attuale, a seconda di 'wath'. 'wath': una delle costanti così definite: hrs = 11, min = 14, sec = 17 (senza apici, non sono stringhe).
Esempio: "Alle ore " + TIME(hrs)
DAYMAP(val1, time1, val2, time2, ... more)
Ritorna: fino a 'time1' l'output è 'val1', da 'time1' a 'time2' l'output è 'val2'... avanti così fino all'ultimo 'time' dopo di che l'output è di nuovo 'val1'.
Naturalmente i valori 'val' e 'time' devono essere presenti a coppie, tanti quanti ne servono. Tutti i 'time' in formato "hh:mm:ss".
Usi: profili di temperatura giornalieri, eventi ad orario o abilitazione per intervalli di tempo, etc., a seconda se 'val' sono temperature, oppure 'buongiorno'/'buonasera', oppure true/false, etc..
WEEKMAP(map)
'map' è una stringa di sette caratteri qualsiasi, uno per giorno della settimana, partendo dalla Domenica (e.g.: 'DLMMGVS' o 'SMTWTFS' o '1234567'). Solo se il carattere corrispondente ad oggi è '-' (trattino) ritorna 'false' altrimenti torna 'true'.
Esempio: WEEKMAP("DLMM-VS") è falso solo il Giovedì.
AVG(value, n) (*)
Media mobile degli ultimi 'n' valori: torna una stringa con 2 decimali.
'n' è in numero di loop, in tempo: t = n x tuyaInterval (definito in 'config.js' file).
MAX(value, n) (*)
Ritorna il più grande degli ultimi 'n' valori.
'n' è in numero di loop, in tempo: t = n x tuyaInterval (definito in config.js file).
ZEROMAX()
Azzera tutti i MAX() presenti in caso di lunghi periodi, e.g. 24h.
nota: deve essere posizionato dopo tutti i MAX() presenti. Esempio: 'if(ISTRIGGERH(DAYMAP(false, '00:00:00', true, '00:20:00'))) ZEROMAX();'
ISCHANGED(value) (*)
ritorna 'true' ogni volta che 'value' cambia rispetto al valore precedente.
ROUND(number, pos)
Torna una stringa con 'pos' cifre decimali (se 'pos' >0)
oppure un numero intero ('pos' = 0)
oppure un numero intero con zeri ('pos' < 0)
Esempi: 'ROUND (123.567, 2)' = "123.57"; 'ROUND(123.567, 0)' = "124"; 'ROUND(123.567, -2)' = "100";
(*): identifica le MACRO che fanno uso di memoria per salvare lo stato.

Progetto OpenSource, Licenza MIT, (c)2024 marco sillano

Questo progetto è un work-in-progress: viene fornito "così com'è", senza garanzie di alcun tipo, implicite o esplicite.

  • Se sviluppate qualche estensione o applicazione interessante con IoTwebUI fatemelo sapere: possiamo inserirla qui, o nella prossima release.
  • Per problemi riguardanti il codice ed il funzionamento di IoTwebUI, aprite un 'issue' qui (github).
  • Per problemi più generali riguardanti Tuya, SmartLife (Tuya smart) e IoTwebUI, che possono interessare anche altri utenti, postate pure nel gruppo Tuya e Smart Life Italia

Grazie per l'interesse m.s.

Riconoscimenti

Tutti i marchi riportati appartengono ai legittimi proprietari.