Manuale collegamento/comandi MQTT e HTTP per ControlHUB
 
Si può "parlare" a ControlHUB sia in standard HTTP che in standard MQTT. 
Sebbene in genere sia ControlHUB "quello che comanda", sia tramite HTTP che tramite MQTT gli si possono far fare da remoto alcune cose che possono sempre venire utili... 
 
Un compito molto comune visto che può "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 sensori e attuatori Modbus (molto diffusi e disponibili per i compiti più svariati) anche nel mondo MQTT
 
L'input HTTP è particolarmente utile per far arrivare dati da sensori remoti che trasmettano sia usando WiFi che usando una SIM GSM, e questo è un altro aspetto da evidenziare. 
Un esempio di questi sensori sono TXdata, TXtemp e TXsoil, che già abbiamo pre-programmato per poter mandare dati, ma il sistema richiesto per mandare dati a ControlHUB (che illustriamo qui sotto) è così semplice che qualunque sviluppatore può ri-utilizzarlo per inviare altri tipi di dati. 
Per poter raggiungere ControlHUB via GSM sarà necessario "affacciare sul Web vero" il Web interno di ControlHUB, ovvero l'interfaccia Web che normalmente potete vedere collegandovi al wifi interno "autoprodotto" da Control HUB o al wifi di casa/laboratorio/ufficio a cui avete collegato ControlHub va resa "accessibile" su Internet. 
Come rendere accessibile ControlHUB su Web/Internet lo spieghiamo in una pagina a parte (clic qui)... 
 
 
Ora vediamo i comandi, prima per HTTP e poi quelli per MQTT... 
 
Collegamento WiFi e HTTP <<< 
Dal vostro 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 avete collegato ControlHUB al vostro 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 vostro 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 uno o più comandi contemporaneamente, 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?l=100 setta la luminosità a 100; http://wfeasy.com/c?s=ciao mostra sul display la stringa "ciao"; http://wfeasy.com/c?l=100&s=ciao setta la luminosità a 100 e mostra sul display la stringa "ciao". 
Se usate l'IP, sarà (per esempio) http://192.168.1.4/c?s=ciao e così via. 
Se usate un DYN dns, potrà invece essere http://qualcosa.dyndns.com/c?s=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... 
 
Comando pw= 
Se l'uso di una password è abilitato (la si abilita e definisce tramite il WiFi interno, nelle Impostazioni), la si deve obbligatoriamente aggiungere a qualsiasi richiesta, mettendola in pw 
Esempi: 
http://wfeasy.com/c?s=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 x= 
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. La stringa è max 252 caratteri. 
Esempi: 
x=Ciao belli! 
Visualizza Ciao belli! facendo scrolling e poi ritorna a fare quello che stava facendo prima 
 
Comando l= 
Setta la luminosità (o la luminosità max), generalmente da 0 a 511 
Esempi: 
l=230 
Setta la luminosità (o luminosità max) a 230. 
 
Comando a=  (e comando c=) 
Esegue una delle azioni definite, che va chiamata per nome. Se è specificato un valore per c, esso è passato come variabile $c$ (ovvero quella che è normalmente la valutazione della condizione chiamante) altrimenti se non compare il parametro c, $c$ è supposta essere 1.  
Esempi: 
a=AzionaVentola 
Chiama l'azione AzionaVentola (qualunque cosa essa faccia). 
a=AzionaVentola&c=23 
Chiama l'azione AzionaVentola specificando che $c$=23. 
Esempi più estesi: 
(se da Internet con un DNS dinamico) http://qualcosa.duckdns.org/c?pw=bellapass&a=AzionaVentola 
(se collegati a wifi interno) http://wfeasy.com/c?pw=bellapass&a=AzionaVentola 
(se si usa l'IP di ControlHUB nella rete locale) http://192.168.1.20/c?pw=bellapass&a=AzionaVentola 
 
Comando o= 
Accende o spegne i relè interni (se presenti) 
Esempi: 
o=G1,C0  (relè G on, relé C off) 
o=ONG,OFFC  (relè G on, relé C off) 
http://qualcosa.duckdns.org/c?pw=bellapass&o=G1,C0  (relè G on, relé C off) 
http://qualcosa.duckdns.org/c?pw=bellapass&o=ONG,OFFC  (relè G on, relé C off) 
 
Inviare dati 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), tramite una richesta HTTP GET fatta a: 
- http://wfeasy.com/x (se siete connessi al wifi interno di ControlHUB) 
- oppure qualcosa come http://192.168.1.20/x  (se avete collegato ControlHUB al vostro 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) 
t= (temperatura moltiplicata * 100 - opzionale, usato da TXtemp) 
h= (umidità 0..100 - opzionale, usato da TXtemp) 
b= (carica batteria del dispositivo in % - opzionale) 
n= (nome del dispositivo - opzionale) 
dm= (corrente intervallo di trasmissione: >0 minuti <0 giorni - opzionale) 
Il server risponde: 
- Pass KO se la password è sbagliata 
- RXOK se tutto OK 
Puoi prendere questi dati e metterli dentro delle variabili creando nuove variabili e impostando come fonte dei dati un Canale Wifi
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"); se vengono ricevuti diversi set di dati (di solito è quello che succede quando il trasmettitore è RXTXeasy) invece per permettervi di elaborare i dati con il sistema esistente ControlHUB creerà lui stesso un JSON formato come nell'esempio seguente, che sarà la risposta del canale Wifi scelto per RXTXeasy: 
{a0:"dati-da-0",a123:"dati-da-123"} 
 
 
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 vi serve specificare un prefisso (alcuni Broker gratuiti richiedono che i topic vostri incomincino per esempio con vostrousername/feeds/ o cose del genere), altrimenti lasciate 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 potete vedere i nomi dei Topic da usare per comandare ControlHUB e per ricevere i messaggi di ControlHUB. 
Vi suggeriamo per sicurezza di utilizzare un Broker installato su un vostro PC 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 vi vuol dire qualcosa, ControlHUB pubblica un messaggio sul topic hub-o-nome (dove Nome è il nome che avete dato al vostro dispositivo un po' più in basso sempre nelle Impostazioni); potrebbe essere un'idea se avete intenzione di pubblicare messaggi MQTT (come Azione) di farlo usando questo stesso topic - ma non è obbligatorio. 
Dovete mettervi in ascolto su questo Topic per poter leggere cosa dice ControlHUB. 
La risposta/payload è un testo, per es. data, ora e temperatura dopo che avete dato il comando STATE; gli altri comandi danno generalmente come risposta il reinvio del comando, per far capire che è stato ricevuto, oppure anche nulla. 
All'accensione, non appena collegato a MQTT (o non appena attivato il broker MQTT interno), ControlHUB pubblica un messaggio come se rispondesse a STATE. 
 
Topic di Comando/Ascolto 
ControlHUB rimane sempre in ascolto sul topic hub-c-nome (dove Nome è il nome che avete dato al vostro dispositivo un po' più in basso sempre nelle Impostazioni). Per comandarlo, un Assistant oppure un altro HUB, oppure voi tramite funzioni programmi e/o librerie di invio messaggi MQTT, deve 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!"} 
oppure {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"} oppure {Exe:AzLanciarazzi}
esegue l'azione AzLanciarazzi (se esiste nella lista di Azioni definite); l'azione può anche essere specificata per numero (sconsigliato)
{Exe:"Azione1,14.5"} o {"Exe":"Azione1,14.5"}
esegue l'azione Azione1 (se esiste nella lista di Azioni definite) e gli passa come $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
STATE oppure {"STATE"}
restituisce data e ora
 
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. 
 
Per domande e suggerimenti posta sul forum di ControlHUB... 
 
 
 
ControlHUB Home - il controller programmabile da smartphone, il modo facile per leggere sensori e comandare dispositivi MQTT ModBus HTTP RS232 Web... 
 
Soluzioni Semplici - Home - L'hardware di VisualVision 
(C) 2020 VisualVision