MQTT

Databoom offre la possibilità di collegare un proprio dispositivo con un server (broker) attraverso il protocollo MQTT. Per poter trasmettere i dati è necessaria la corretta configurazione di un dispositivo su Databoom e la creazione di un client che invii i parametri nel formato richiesto. Di seguito la procedura in Node.js.

Leggi anche: Come comunicare con Databoom utilizzando MQTTBox o MQTTLens

Configurazione di un dispositivo MQTT in Databoom

Prima di creare un client MQTT per l'invio di dati a Databoom, è necessario creare un dispositivo sulla piattaforma e configurarlo in modo da poter comunicare correttamente. In fase di creazione di un dispositivo è necessario selezionare il tipo MQTT. Una volta selezionato il tipo, verranno visualizzati i campi necessari alla comunicazione.

I topic di un dispositivo (e template) MQTT si distinguono in: 

• Topic sul quale pubblicare per inviare dati, dove il client dovrà pubblicare i dati affinché vengano ricevuti e processati da Databoom
• Topic sul quale si ricevono informazioni da Databoom, dove il client potrà sottoscriversi per ricevere informazioni da Databoom

Il campo Progetti permette di inserire una o più stringhe che andranno a costituire le radici dei topic. Inserendo più progetti si avranno quindi più topic per la pubblicazione e più topic per la sottoscrizione.

I topic dei dispositivi MQTT seguono la struttura <progetto>/<token dispositivo>/<topic>

Il token dispositivo viene utilizzato per comporre, insieme all'ambito utente visualizzabile nel profilo personale, il ClientId da impostare nel proprio client MQTT, che avrà quindi la struttura <ambito utente>-<token dispositivo>

Si considerino, ad esempio, MQTTTest come progetto, data come topic di pubblicazione e info come topic di sottoscrizione, verranno visualizzati nella sezione sottostante i topic così formati:

• MQTTTest /<token dispositivo>/data
• MQTTTest /<token dispositivo>/info

Modulo mqtt

Per la creazione di un client si utilizza il modulo mqtt

All’interno del proprio script è necessario il riferimento:

Creazione di un client in Node.js

La creazione del client segue il modello:

var settings = {
    clientId:"<ambito utente>-<token dispositivo>", 
    username:"<username Databoom>",
    password:"<oAuth Databoom>"
};

var client = mqtt.connect("mqtt://mqtt.databoom.com:1883", settings);

Il clientId sarà formato dall'ambito utente, visionabile nel profilo personale, e dal token del proprio device, visualizzabile nella sua pagina di dettaglio, seguendo la struttura <ambito utente>-<token dispositivo>. Il clientId così formato è visionabile direttamente nel dettaglio del dispositivo MQTT in Databoom.

Per l'autenticazione al broker MQTT è necessario utilizzare il proprio username e, come password, un OAuth token generato in Databoom con permessi di Pubblicazione.

• Nel menù laterale Impostazioni -> Credenziali, cliccare il pulsante Aggiungi OAuth nel riquadro Chiavi OAuth
• Per garantire una sicurezza ottimale, si consiglia di generare un OAuth token diverso per ogni dispositivo

L’indirizzo del broker è mqtt.databoom.com, sulla porta 1883, si utilizza pertanto mqtt://mqtt.databoom.com:1883.

Struttura parametri da inoltrare

I parametri da inviare al topic di pubblicazione (nell'esempio MQTTTest/<token dispositivo>/data) devono essere in formato JSON, in particolare si segue la struttura:

{
 "type": "data",
 "message": {
     "device": "<token dispositivo>",
     "date": "<data>",
     "signals" : [
       {
         "name": "<token segnale 1>",
         "value": <valore segnale 1>
       },
       { 
         "name": "<token segnale 2>", 
         "value": <valore segnale 2> 
       }
     ]
   }
}

Il <token dispositivo> è disponibile nel riquadro informazioni all'interno del dispositivo.

Il campo date non è obbligatorio, se non viene inserito viene memorizzata la data al momento della ricezione.

I token dei segnali, nell'esempio <token segnale 1> e <token segnale 2>, possono essere copiati direttamente dalla pagina del dispositivo o all'interno della pagina di dettaglio dei segnali corrispondenti.

Se si vuole aggiornare un segnale già presente nel proprio dispositivo su Databoom, name dovrà corrispondere al token esistente. Se il segnale non è presente in Databoom, verrà inserito utilizzando name come token. Il valore dovrà pertanto essere univoco all'interno del dispositivo.

I parametri vengono poi trasformati in stringa per poter essere pubblicati correttamente sul topic del broker

 post_data = JSON.stringify(post_data); 

Pubblicazione dati sul topic

Terminata la creazione dei parametri, è possibile procedere con la pubblicazione sul topic del broker di Databoom. Si consideri il topic d'esempio MQTTTest/<token dispositivo>/data

client.publish("MQTTTest/<token dispositivo>/data", JSON.stringify(post_data), function () {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTTTest/<token dispositivo>/data");
    console.log(JSON.stringify(post_data));
});

Il topic dove verranno pubblicati i parametri viene visualizzato in fase di creazione del dispositivo in Databoom, deve seguire la struttura dell'esempio MQTTTest/<token dispositivo>/data (dove MQTTTest e data sono personalizzabili dall'utente) altrimenti i dati inoltrati non verranno considerati. post_data deve essere una stringa. Nella callback vengono poi visualizzati dei messaggi di log per confermare l’avvenuto invio dei parametri.

E' anche possibile sottoscriversi al canale per la supervisione degli eventi di dispositivo, visualizzabile in fase di creazione.  Deve seguire la struttura dell'esempio MQTTTest/<token dispositivo>/info (dove MQTTTest e info sono personalizzabili dall'utente).

client.on('connect', function () {
    console.log(newDate().toISOString(), "\tCLIENT CONNECTED TO DATABOOM BROKER")
    client.subscribe('MQTTTest/<token dispositivo>/info');
});

client.on('message', function (topic, message) {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTTTest/<token dispositivo>/info");
    console.log(message.toString());
})

Creazione di un'allarme

E' possibile creare un'allarme in Databoom pubblicando sul topic per l'invio dei dati. La sintassi da utilizzare è la seguente:

{
    "type": "alarm",
    "message":  {
      "dateOn": "2018-04-13T09:00:00+02:00",
      "description": "Questo e' un test di allarme da mqtt",
      "comment": "Testo piu' verboso per allarme da mqtt",
      "status": "ON",
      "ack": "NACK"
    }
}

Creazione di un evento

E' anche possibile creare eventi, pubblicando sul topic i dati seguendo il formato:

{
    "type": "event",
    "message":  {
        "description": "Evento da mqtt su segnale di dispositivo",
      "from": "2018-04-13T09:00:00+02:00",
      "to": "2018-04-13T10:00:00+02:00",
        "link": {
            "device": "<token dispositivo>",
            "signal": "<token segnale>"
        },
      "tags": [
        "mqtt"
      ]
    }
}

Funzione di trasformazione per dati pubblicati

Nel caso non sia possibile personalizzare il contenuto dei dati da inoltrare nel formato compatibile con Databoom, è possibile specificare un Topic personalizzato dove pubblicare i dati direttamente al segnale, senza dover specificare il token nel payload. Si consideri il topic personalizzato orders, il topic per la pubblicazione diretta sul segnale sarà MQTTTest/<token dispositivo>/data/orders

Il contenuto sarà quindi elaborato dalla funzione di trasformazione e i valori memorizzati nel segnale.

La funzione deve ritornare uno o più valori (array []) nel formato:

{
    "date": <DATA>,
    "value": <VALORE>
}

Nell'esempio si può notare la funzione doIt 

function doIt(payload) {    
    return {
        'date': new Date(),
        'value': (payload[1].charCodeAt(0) - 97)
    };
}

Il parametro payload permette di accedere ai dati pubblicati e di elaborarli in modo da restituirli nel formato compatibile. Nell'esempio il valore viene ricavato sottraendo 97 al codice del primo carattere della prima componente del payload.

Configurazione completata!

Una volta completata la procedura, Databoom inizierà a registrare i dati inviati con MQTT. Per poter consultare i dati e avere una rappresentazione corretta, seguire le indicazioni in Modifica/validazione di un segnale.