Specifiche OHMq
Specifiche per integrare dispositivi di terze parti.
Per facilitare l'integrazione di dispositivi di terze parti, in grado di comunicare attraverso il protocollo MQTT, sono state definite delle specifiche che permettono facilmente di comunicare con un Sistema Domotico Ohm Automation.
La comunicazione avviene nella rete locale sfruttando il protocollo MQTT, e richiede di rispettare un preciso formato per topic e payload.
I topic sono in generale definiti come segue:
ohmq/<device_id>/<message_type>/<category>/<item_id>
Dove:
ohmq: prefisso necessario.device_id: ID del dispositivo che desideriamo integrare e che deve essere univoco, per questo è preferibile usare il MAC address senza i:.message_type: definisce la tipologia del messaggio, se ad esempio si tratta di un messaggio di stato (state) o comando (command).category: se il messaggio è indirizzato ad un elemento specifico, indica la sua categoria (es.board,output, ecc.).item_id: ID dell'elemento della scheda a cui è riferito il messaggio.
Ad esempio il topic
ohmq/a861a504ab/command/output/R1 si riferisce ad un messaggio per eseguire un comando sull'output con ID R1 (in seguito un esempio più specifico).item_id indica l'ID dell'elemento, che di fatto viene fatto coincidere con la codifica assegnatagli (scritta magari sul morsetto); non ci sono particolari vincoli sul formato dell'ID, ma deve essere univoco sul dispositivo. Se l'output rappresenta il primo relé della scheda, la sua codifica (quindi il suo ID) potrebbe essere R1.Esiste inoltre un topic "universale" a cui si devono sottoscrivere tutte le schede che supportano le specifiche OHMq:
ohmq/universe
I messaggi inviati su questo topic devono essere gestiti da tutti e in particolare tutte le schede devono supportare il Discovery.
Il payload è in generale in formato JSON e il suo contenuto varia a seconda del tipo di messaggio.
Di seguito le due principali tipologie di messaggio:
state: messaggio di stato.command: messaggio di comando.
I messaggi di comando devono contenere tutti il campo
action, che permette di definire l'operazione da eseguire, ad esempio per accendere un output avremo:{
"action": "on"
}
[!warning] Importante I messaggi di comando devono essere sempre inviati come con l'impostazioneretainsufalse, in quanto non devono essere assolutamente conservati, ma hanno valore solo nell'istante in cui vengono inviati.
Questi messaggi devono essere inviati per avvisare il Sistema del cambio di stato di un dato elemento, quindi in seguito all'accensione di una luce verrà ad esempio inviato il messaggio:
{
"on": true,
"value": 255
}
Alla pressione di un pulsante avremo invece:
{
"value": 1
}
[!warning] Importante I messaggi di stato richiedono che l'impostazioneretainsiatrue, così da permettere di recuperare lo stato anche in un secondo momento.
Tutte le schede devono supportare questa funzionalità, perché rappresenta il modo ufficiale per permettere al sistema di individuare le schede.
Per garantire questa funzione è necessario che le schede effettuino il subscribe al topic
ohmq/universe e rispondano con la propria configurazione al messaggio seguente:{
"action": "announce"
}
La configurazione dovrà essere inviata in formato JSON e deve essere qualcosa del tipo:
{
"id": "a861a504ab",
"name": "Example",
"model": "ESP32",
"ip": "192.168.0.x",
"mac": "00:00:00:00:00",
"supported_commands": ["find", "set_network", "set_name", "restart"],
"outputs": [{"code": "R1", "n": 14}],
"inputs": [{"code": "I1", "n": 16}],
"sensors": [{"code": "S1", "n": 2}]
}
Tra i campi quelli che meritano attenzione sono:
supported_commands: indica la tipologia di comandi supportati dalla scheda (es.findindica la possibilità di essere localizzata visivamente, magari con un led che lampeggia o cambia colore).outputs/inputs: la lista di output/input gestiti dalla scheda.
Il messaggio contenente l configurazione dovrà essere inviato al topic seguente:
ohmq/<device_id>/hi
Per permettere una più rapida e facile implementazione è presente il supporto al servizio
_mqtt._tcp.local. di mDNS, così da permettere la connessione al broker usando come hostname ohmb-master.local e 1883 come porta.Queste sono le categorie principali:
board: rappresenta la scheda.output: per la gestione degli output (uscite).input: per la gestione degli input digitali (ingressi binari).sensor: per la gestione degli input analogici.
Il topic che permette di inviare comandi alla scheda è il seguente:
ohmb/<device_id>/command/board
I comandi devono sempre contenere il parametro
action, che definisce l'operazione da eseguire. Di seguito le principali operazioni e il relativo del payload.Questa operazione permette di localizzare fisicamente la scheda, utile se ci sono numerosi dispositivi ed è necessario individuare quello corretto per il cablaggio.
Il messaggio che verrà inviato alla scheda sarà semplicemente:
{
"action": "find"
}
In seguito alla ricezione di questo messaggio è possibile effettuare qualsiasi operazione che permetta l'identificazione visiva del dispositivo, è possibile ad esempio far lampeggiare un led dedicato.
Questa operazione richiede il riavvio della scheda e il messaggio inviato sarà:
{
"action": "restart"
}
Per garantire una facile identificazione della scheda nell'app di configurazione, è consigliato assegnare un nome che permetta di distinguere facilmente le schede, quindi la scheda deve supportare il comando
set_name e prevedere una strategia di salvataggio del nome assegnato.Il messaggio ricevuto dalla scheda sarà una cosa del tipo:
{
"action": "set_name",
"name": "Scheda 1"
}
Ogni output viene definito come segue:
{
"code": "R1",
"n": 10
}
Dove
code indica la codifica visibile all'utente e indicata ad esempio sul morsetto, mentre n rappresenta il numero del pin usato sul microcontrollore.Quando viene inviata la configurazione della scheda è fondamentale allegare perlomeno il parametro
code, in quanto viene usato per la comunicazione via MQTT.Il topic relativo ai comandi inviati ad un output è il seguente:
ohmb/<device_id>/command/output/<item_id>
Per semplicità e convenienza la scheda può effettuare un subscribe al topic
ohmb/<device_id>/command/output/+, sfruttando il wildcard +.Come nel caso della scheda, i comandi vanno inviati in formato JSON definendo il parametro
action, e sono:on: per l'attivazione.off: per la disattivazione.toggle: per il cambio di stato.set: per il set di un valore tra0e255nel caso di output analogico.preset: per impostare il valore di un output analogico senza attivarlo, così da assumere il valore desiderato solo in seguito ad una successiva accensione.
Quindi ad esempio:
{
"action": "set",
"value": 120
}
Lo stato dell'output deve essere inviato al topic:
ohmb/<device_id>/state/output/<item_id>
È fondamentale inviare lo stato ogniqualvolta l'elemento cambia di stato.
Lo stato deve essere inviato come segue:
{
"is_on": false,
"value": 210
}
Nel caso di output digitale (binario) il valore indicato dal parametro
value sarà 0 (quando disattivo) o 255 (se attivo).Il parametro
is_on indica se l'output è attivo o disattivo. Il parametro value va assolutamente inviato nel caso di output analogico, anche quando l'elemento è disattivo, in quanto permette di riabilitare lo stato precedente alla riaccensione.Ogni input viene definito come segue:
{
"code": "I1",
"n": 16
}
Dove
code indica la codifica visibile all'utente e indicata ad esempio sul morsetto, mentre n rappresenta il numero del pin usato sul microcontrollore.Quando viene inviata la configurazione della scheda è fondamentale allegare perlomeno il parametro
code, in quanto viene usato per la comunicazione via MQTT.Lo stato dell'input deve essere inviato al topic:
ohmb/<device_id>/state/input/<item_id>
È fondamentale inviare lo stato ogniqualvolta l'elemento cambia di stato.
Lo stato deve essere inviato come segue:
{
"value": 1
}
Gli elementi della categoria
input vanno intesi come ingressi digitali (binari), quindi assumono solo i valori 0 e 1. Per input analogici bisogna riferirsi alla categoria sensor.Ogni sensore (input analogico) viene definito come segue:
{
"code": "S1",
"n": 2
}
Dove
code indica la codifica visibile all'utente e indicata ad esempio sul morsetto, mentre n rappresenta il numero del pin usato sul microcontrollore.Quando viene inviata la configurazione della scheda è fondamentale allegare perlomeno il parametro
code, in quanto viene usato per la comunicazione via MQTT.Lo stato del sensore deve essere inviato al topic:
ohmb/<device_id>/state/sensor/<item_id>
Nel caso dei sensori è consigliabile prevedere dei limiti nell'invio dei dati, così da evitare di sovraccaricare il Broker MQTT. Ad esclusione di alcune tipologie di sensori (es. sensori di allarme) in genere non c'è alcun vantaggio nell'inviare cambi di stato in tempo reale. È quindi opportuno prevedere dei filtri (es. livellamento esponenziale).
Lo stato deve essere inviato come segue:
{
"value": 22.5
}