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 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.
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 <<<
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).
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).
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=)
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
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.
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.
- 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
|
|
LISTSYS
|
|
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.
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.