Manuale collegamento/comandi MQTT e HTTP per ControlHUB
 
Si può "parlare" a ControlHUB sia in standard HTTP che in standard MQTT. 
Sebbene sia ControlHUB generalmente "quello che comanda", sia tramite HTTP che tramite MQTT gli si possono far fare da remoto un sacco di cose. 
In sintesi: 
- si possono lanciare le Azioni definite dall'utente e anche quelle predefinite (azionamento dei relè incluso) 
- si possono leggere variabili o settare variabili, anche creando nuove variabili 
- si può leggere lo Stato e le variabili predefinite/di sistema 
- si possono inviare dati (es. da sensori) 
 
L'input HTTP è molto utile per far arrivare dati da sensori remoti siccome si può usare facilmente sia tramite WiFi che da rete Internet e anche da rete mobile usando GSM. Per esempio i nostri TXdata, TXtemp e TXsoil sfruttano questa possibilità. 
Il sistema per mandare dati a ControlHUB che illustriamo qui sotto è così semplice che qualunque sviluppatore può ri-utilizzarlo anche per inviare altri tipi di dati. 
 
Ricordiamo che per poter raggiungere ControlHUB via GSM o via Web sarà necessario "affacciare sul Web vero" il Web interno di ControlHUB, ovvero l'interfaccia Web che normalmente puoi vedere collegandoti all'hotspot wifi "autoprodotto" da Control HUB o al wifi di casa/laboratorio/ufficio a cui hai collegato ControlHub
Come rendere accessibile ControlHUB su Web/Internet lo spieghiamo in una pagina a parte (clic qui)... 
 
Per quanto riguarda MQTT un compito molto comune per le versioni DX DY CX CY NX NY che possono "leggere" dispositivi ModBus (con Azioni/Lettura) e allo stesso tempo "comandare" dispositivi ModBus (con Azioni "normali") è usarlo come ponte tra MQTT e ModBus per poter usare in un'automazione o domotica MQTT dei sensori e attuatori Modbus (molto diffusi e disponibili per i compiti più svariati). 
 
Ovviamente si può poi fare qualsiasi altra cosa sia in HTTP che in MQTT. 
 
 
Collegamento WiFi e HTTP <<< 
Dal tuo dispositivo ci si può collegare al WiFi interno generato da ControlHUB, oppure si può collegare ControlHUB al Wifi di casa nella pagina di configurazione Wifi / MQTT / ModBus, ed eventualmente renderlo accessibile su Web/Internet
 
Comandi WiFi / HTTP ( /c ) 
I comandi si possono mandare tramite una richesta HTTP GET fatta a:  
- http://wfeasy.com/c (se siete connessi al wifi interno di ControlHUB) 
- oppure qualcosa come http://192.168.1.20/c  (se hai collegato ControlHUB al tuo WiFi; l'IP che abbiamo esemplificato con 192.168.1.20 è assegnato dal router, ControlHUB lo scrive in calce a tutte le pagine una volta collegato; e si può fissare dentro alle opzioni di configurazione del router, così che non cambi; tipicamente si fa in un menù tipo DHCP utilites o Avanzate DHCP).  
- oppure qualcosa come http://2.34.44.39/c o http://qualcosa.dyndns.com/c (se ControlHUB è affacciato su Internet
 
Si possono mandare a ControlHUB dei comandi nel formato classico delle richieste GET (e quindi usando & per inserire parametri multipli e separarli, e usando il classico URL encode per gestire i caratteri non alfanumerici).  
I comandi disponibili sono nel seguito. 
Esempio: http://wfeasy.com/c?Brightness=100 setta la luminosità a 100; http://wfeasy.com/c?One=ciao mostra sul display la stringa "ciao" (se la tua versione di ControlHUB ha un display!). 
Se usi l'IP, sarà (per esempio) http://192.168.1.4/c?One=ciao e così via. 
Se usi un DYN dns, potrà invece essere http://qualcosa.dyndns.com/c?One=ciao 
Tutto questo lo si può provare per esempio collegandosi al WiFi interno con un PC e scrivendo queste cose sulla barra del browser (es. Chrome, Firefox, Explorer); ovviamente lo si può fare anche con Mac, Raspberry o altri dispositivi... 
 
Parametro pw= 
Si deve obbligatoriamente aggiungere la password a qualsiasi richiesta, mettendola in pw 
Esempi: 
http://wfeasy.com/c?One=ciao&pw=a8d7f6k5 
mostra sul display la stringa "ciao", ma solo se la password è a8d7f6k5 - se invece la pass non è giusta, non fa nulla. 
 
Comando cm= 
Permette di inviare i comandi STATE, LISTVARS, LISTSYS. Esempio: 
cm=STATE 
http://wfeasy.com/c?cm=STATE&pw=a8d7f6k5  
Il comando STATE restituisce lo Stato del sistema (nome, data, ora, temperatura, stato dei relè e inputs I1/I2 se presenti es. ControlHUB versione MY o NY), LISTVARS restituisce un JSON che contiene tutte le variabili definite e il loro valore (escluse quelle predefinite/di sistema), LISTSYS elenca invece le variabili predefinite / di sistema
Tutte le variabili si possono eventualmente anche chiedere per nome con il comando GetVar=. 
 
Comando One= 
Per le versioni di ControlHUB con un display (DX, DY, CX, CY), visualizza sul display la stringa, facendo scrolling se la lunghezza della stringa è maggiore dei caratteri disponibili, una sola volta, poi ritorna a mostrare quello che stava mostrando precedentemente. 
Esempi: 
One=Ciao belli! 
http://wfeasy.com/c?One=Ciao%20belli&pw=a8d7f6k5 
Visualizza Ciao belli! facendo scrolling e poi ritorna a fare quello che stava facendo prima 
 
Comando Brightness= 
Setta la luminosità (o la luminosità max), generalmente da 0 a 100 
Esempi: 
Brightness=100 
Setta la luminosità (o luminosità max) a 100. 
 
Comando Exe=  (e comando Cond=) 
Esegue una delle azioni definite, che va chiamata per nome; si può anche specificare una condizione come parametro Cond. Se è specificato un valore per la condizione, esso è passato come variabile $c$ (ovvero quella che è normalmente la valutazione della condizione chiamante) altrimenti $c$ è supposta essere 1.  
Esempi: 
Exe=AzionaVentola 
(chiama l'azione AzionaVentola - qualunque cosa essa faccia). 
Exe=AzionaVentola&Cond=23 
(chiama l'azione AzionaVentola specificando che $c$=23) 
Esempi più estesi: 
- se si chiama CHUB da Internet associandolo a un IP fisso o a un DNS dinamico: 
http://qualcosa.duckdns.org/c?pw=bellapass&Exe=AzionaVentola 
- se collegati a wifi interno: 
http://wfeasy.com/c?pw=bellapass&Exe=AzionaVentola 
- se si usa l'IP di ControlHUB nella rete locale: 
http://192.168.1.20/c?pw=bellapass&Exe=AzionaVentola 
 
Comando Rly= 
Accende o spegne i relè interni (se presenti). 
Esempi: 
Rly=G1,C0   
(relè G on, relé C off) 
Rly=ONG,OFFC   
(relè G on, relé C off) 
http://qualcosa.duckdns.org/c?pw=bellapass&Rly=G1,C0  
http://qualcosa.duckdns.org/c?pw=bellapass&Rly=ONG,OFFC 
 
Comandi SetVar= e Value= 
Con questi due parametri si setta una variabile (se non esiste già, essa viene creata come variabile temporanea, che sparirà allo spegnimento di ControlHUB; il nome va specificato SENZA i $ a inizio/fine tipicamente usati in CHUB). Occhio che come per tutti gli altri comandi le maiuscole e le minuscole vanno rispettate o non funzionerà. 
NOTA che questo comando è utile solo se si vuole controllare ControlHUB da un altro sistema complesso; per "passare dati" da sensori è meglio usare il procedimento illustrato nel capitolo seguente perché dà ControlHUB maggior controllo. 
SetVar=nomevariabile&Value=valore 
http://wfeasy.com/c?SetVar=pippo&Value=ciao&pw=a8d7f6k5  
 
Comando GetVar= 
Con questo comando si chiede il valore di una variabile (specificando il nome della variabile). Sarà restituito in un JSON {"variabile":"valore"} 
GetVar=nomevariabile 
http://wfeasy.com/c?GetVar=time&pw=a8d7f6k5  
 
 
Passare dati, inviare dati raw a ControlHUB via WiFi / HTTP ( /x ) 
In modo molto simile ai comandi, si può usare HTTP per mandare dati a ControlHUB (proprio in questo modo funzionano TXdata, TXtemp e TXsoil, ecc). Si fa una richesta HTTP GET a: 
- http://wfeasy.com/x (se sei connesso al wifi interno di ControlHUB) 
- oppure qualcosa come http://192.168.1.20/x  (se hai collegato ControlHUB al tuo WiFi; vedi note sopra per /c).  
- oppure qualcosa come http://2.34.44.39/x o http://qualcosa.dyndns.com/x (se ControlHUB è affacciato su Internet
 
Qui siamo un po' più sintetici di sopra, anche perché il sistema è lo stesso. Si usano sempre parametri di tipo GET quindi parametri aggiunti alla URL dopo un ?, che sono: 
pw= (password, come sopra) 
w= (numero del Canale wifi 0..99 se viene mandato un solo set di dati in r=) 
r= (dati che si vuole passare, in formato JSON oppure in formato HEXAscii
z= (numero del Canale wifi 0..99 se vengono inviati più set di dati in a0=...a199= - usato da RXTXeasy) 
a0= .. a15=; a100=... a199=; (dati come in r= ma per trasmissioni multiple; usato da RXTXeasy) 
b= (carica batteria del dispositivo in % - opzionale) 
n= (nome del dispositivo - opzionale) 
dm= (corrente intervallo di trasmissione: >0 minuti <0 giorni - opzionale) 
Legacy: 
t= (temperatura moltiplicata * 100 - opzionale, usato da TXtemp) 
h= (umidità 0..100 - opzionale, usato da TXtemp) 
 
Il server risponde: 
- Pass KO se la password è sbagliata 
- RXOK se tutto OK 
 
Dentro ControlHUB puoi prendere questi dati e metterli dentro delle variabili così: 
- creando nuove variabili  
- impostando come fonte dei dati un Canale Wifi (formalmente Canale WiFi, ma sarebbe più corretto definirlo canale HTTP visto che ci puoi trasmettere anche via Web / con GSM se per esempio ControlHUB è affacciato su Web)  
 
SET DI DATI SINGOLO: Quando viene ricevuto un solo set di dati (da r=) esso è passato direttamente come risposta (impostando come fonte dei dati il Canale Wifi si riceve quello che è nella variabile CGI "r"); ControlHUB può elaborare dati HexAscii oppure in formato JSON. 
 
DATI MULTIPLI: Se vengono ricevuti diversi set di dati (di solito è quello che succede quando il trasmettitore è RXTXeasy), per permettere di elaborare i dati con le sue funzioni, ControlHUB creerà un JSON con un formato come nell'esempio seguente, che sarà la "risposta" del Canale WiFi/HTTP scelto per ricevere RXTXeasy. 
{a0:"dati-hex-o-testo-da-0",a12:"dati-da-123",a123:{Temperature:20.3,Humidity:50}} 
Ovvero ci può essere un JSON dentro un altro JSON, nella pagina di creazione variabili ci si potrà accedere la notazione standard con il puntino, per esempio per richiedere di estrarre e porre dentro una Variabile il campo Temperature di a123 si scriverà a123.Temperature 
 
CAMPO "NAME" E "DEVICE": C'è da notare che se tra i dati singoli è presente una variabile "Name", ControlHUB creerà automaticamente la variabile di sistema $i_salotto1$ mettendoci dentro l'IP del chiamante. La variabile è poi usabile in qualsiasi Azione
Questo è usato per esempio dai nostri DoorOpen, DoorSwitch e SuperClock. In questo esempio abbiamo la chiamata che arriva da un DoorSwitch appoggiato a ControlHUB tramite HTTP (ovvero con IP/Server e Pass impostate, nell'apposita sezione): 
http://chub_ip/x?pw=pass&w=ch&r={"RY2":1,"F2":1,"Name":"Salotto1"} 
Questo sistema è molto utile per impostare un'automazione HTTP anziché MQTT; noi lo usiamo e si può usare facilmente anche da periferiche di terze parti in modo che ControlHUB memorizzi il loro IP automaticamente (nome memorizzato: lunghezza massima 8 caratteri; alfanumerico no spazi; primo carattere alfabetico, se non lo è, diventa "_" ). 
La pagina Tempi Ricezioni/Letture mostra le variabili create (queste variabili speciali predefinite sono azzerate allo spegnimento e vengono create e mantenute aggiornate se ci sono periferiche collegate che chiamano ControlHUB; per esempio DoorOpen, DoorSwitch e SuperClock chiamano ogni qualche minuto per mantenere tutto aggiornato); se nel JSON è presente un campo Device con il nome del dispositivo (es. DoorSwitch) questo viene anche mostrato. 
Abbiamo un esempio di collegamento ControlHUB / DoorSwitch che usa questo sisteama... 
 
 
Collegamento WiFi e MQTT <<< 
Anche per MQTT è necessario un collegamento WiFi: ci si deve collegare a un WiFi che abbia accesso a un Broker MQTT; per cui basta collegarsi al WiFi interno generato da ControlHUB solo se si usa il Broker Interno MQTT di ControlHUB; negli altri casi ci si dovrà collegare al WiFi di casa / ufficio / laboratorio / ecc. Questo si fa nella pagina di configurazione Wifi / MQTT
Per configurare invece ControlHUB per MQTT ci si collega a ControlHUB e si va nel menù Impostazioni (per collegarsi ecc. vedi manuale veloce di ControlHUB), e alla voce MQTT si inserirà: 
- l'IP o il nome del server dove gira il Broker MQTT (nota: se lasciato vuoto, ControlHUB non userà MQTT) 
- eventualmente username e password del Broker, se li necessita 
 
ControlHUB mostra nella voce MQTT il nome dei topic di default usati per la pubblicazione/out e per ricevere comandi/cmd; è possibile se ti serve specificare un prefisso (alcuni Broker gratuiti richiedono che i topic tuoi incomincino per esempio con vostrousername/feeds/ o cose del genere), altrimenti lascia le caselle "prefix" vuote. 
 
Quindi si clicca Salva e ControlHUB ci si collegherà, e dopo qualche secondo comincerà a poter funzionare anche in MQTT. Se il collegamento è OK scriverà OK dopo la parola MQTT; e già da subito nella stessa pagina puoi vedere i nomi dei Topic da usare per comandare ControlHUB e per ricevere i messaggi di ControlHUB. 
Ti suggeriamo per sicurezza di utilizzare un Broker installato su un tuo PC, il broker interno di ControlHUB o altro (si può scaricare e installare e far girare un programma Broker come Mosquitto anche su un semplice PC Windows). 
 
Topic di Risposta/Pubblicazione 
Quando risponde ai comandi, oppure quando vuol dire qualcosa, ControlHUB pubblica un messaggio sul topic hub-o-nome (dove Nome è il nome che hai dato al tuo ControlHUB un po' più in basso sempre nelle Impostazioni); potrebbe essere un'idea se hai intenzione di pubblicare messaggi MQTT (come Azione) di farlo usando questo stesso topic - ma non è obbligatorio. 
Occorre mettersi in ascolto su questo Topic per poter leggere cosa dice ControlHUB. 
ControlHUB pubblica su questo topic come risposta ad alcuni comandi: di solito la risposta/payload è un testo JSON. 
All'accensione, non appena collegato a MQTT (o non appena attivato il broker MQTT interno), ControlHUB pubblica un messaggio come se rispondesse a STATE. 
La versione MY pubblica un messaggio JSON anche ogni volta che lo stato degli ingressi F1 e/o F2 cambia, includendo lo stato dei relè come RY1 e RY2, e lo stato degli ingressi come I1 e I2. 
 
Topic di Comando/Ascolto 
A meno che non sia crocettata la casella OFF di fianco, ControlHUB rimane sempre in ascolto sul topic hub-c-nome (dove Nome è il nome che hai dato al tuo ControlHUB un po' più in basso sempre nelle Impostazioni). Per comandarlo, un Assistant oppure un altro HUB, oppure tu tramite funzioni programmi e/o librerie di invio messaggi MQTT, dovete pubblicare su tale Topic di comando un messaggio/payload tra questi: 
 
{"Brightness":100}
setta la luminosità a 100 (i valori disponibili in genere sono da 1 a 511)
{"One":"bella scritta!"}
Visualizza sul display la stringa bella scritta!, facendo scrolling per una volta sola; poi ritorna a cosa mostrava in precedenza
{"Exe":"AzLanciarazzi"}
esegue l'azione AzLanciarazzi (se esiste nella lista di Azioni definite); l'azione può anche essere specificata per numero (sconsigliato)
{"Exe":"Azione1","Cond":14.5}
esegue l'azione Azione1 (se esiste nella lista di Azioni definite) e gli passa come condizione $c$ il numero 14.5 ($c$ normalmente è il risultato della valutazione della eventuale condizione che potrebbe chiamare l'azione; vedere nella pagina che spiega le condizioni)
{"Rly":"ONG"} oppure {"Rly":"G1"}
attiva il relè G
{"Rly":"OFFG"} oppure {"Rly":"G0"}
disattiva il relè G
{"Rly":"ONG,OFFC"} oppure {"Rly":"G1,C0"}
attiva il relè G e disattiva il relè C
{"SetVar":nomevariabile, 
"Value":valore}
setta la variabile $nomevariabile$ con il valore specificato (se non esiste già, essa viene creata come variabile temporanea, che sparirà allo spegnimento di ControlHUB; il nome va specificato SENZA i $)
{"GetVar":nomevariabile}
si richiede la variabile $nomevariabile$ => CHUB invia nel topic di uscita un JSON con quella variabile e il suo valore {variabile:valore}
LISTVARS
invia nel topic di uscita un JSON con elencate tutte le variabili (escluse le variabili predefinite/di sistema) e il loro valore
LISTSYS
invia nel topic di uscita un JSON con elencate tutte le variabili predefinite/di sistema e il loro valore
STATE
invia nel topic di uscita un JSON con data e ora, per la versione MY anche lo stato degli ingressi F1 e F2
 
Inviare dati via MQTT 
In modo molto simile ai comandi, si può usare MQTT per passare dati a ControlHUB. 
Si può usare un topic qualsiasi, l'importante è essere tutti connessi allo stesso broker. 
Per prendere dati e metterli dentro delle variabili è sufficiente creare nuove variabili e impostare come fonte dei dati un topic MQTT. Nella stessa pagina si dice a ControlHUB quale variabile prendere dal messaggio MQTT inviato nel topic (vedi info ed esempi). 
TXdata, TXtemp e TXsoil hanno già dei topic predefiniti in cui inviano i loro dati, per permetterne un facile uso con MQTT (è tutto documentato). 
Altre apparecchiature MQTT avranno nel manuale i topic che usano e un esempio dei dati che mandano (che cmq. si può vedere in ogni caso facendo una prova, l'interfaccia di ControlHUB è molto interessante, vedi esempio...) 
 
 
Come noto, per MQTT è necessario un sistema locale o remoto (accessibile via Internet) che faccia il Broker., per esempio il broker interno di ControlHUB
Se stai facendo un'automazione con ControlHUB e Wifi, e magari altri componenti VisualVision come TXdata, TXtemp e TXsoil, puoi evitare questo passaggio intermedio utilizzando anziché MQTT dei semplici comandi HTTP / Web, spiegati a inizio pagina, che daranno meno carico al sistema e permetteranno un funzionamento migliore e più veloce. 
 
Per domande e suggerimenti posta sul forum di ControlHUB... 
 
[ Variabili/dati - Variabili predefinite - Azioni/letture - Condizioni/espressioni
 
ControlHUB Home - il controller smart per automazione e domotica programmabile anche da smartphone, il modo facile per leggere sensori e comandare relè e dispositivi MQTT ModBus HTTP RS232 Web DoorSwitch DoorOpen SuperClock Smart Switch impostare timer, azioni anche periodiche, condizioni... 
 
Soluzioni Semplici - Home - L'hardware di VisualVision 
(C) 2021 VisualVision