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 campi Progetti, Topic sul quale pubblicare per inviare dati e Topic sul quale si ricevono informazioni da Databoom possono essere compilati arbitrariamente per la formazione dei topic da utilizzare nella configurazione del proprio client MQTT.

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

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

Il <token dispositivo> viene utilizzato per comporre, insieme all'ambito utente visualizzabile nel profilo personale, l'id da impostare nel proprio client MQTT (ClientId). 

E' possibile associare più topic ad un dispositivo variando la parte di Progetto, mantenendo invariato il resto dell'indirizzo. Considerando l'esempio precedente, nello stesso dispositivo è possibile inserire altri topic quali 

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

Da notare la variazione nel Progetto, data e info sono invece comuni a tutti i progetti. Completata la configurazione avremo a disposizione il ClientId e i topic, si può quindi procedere con la creazione del client.

Modulo mqtt

Per la creazione di un client si utilizza il modulo mqtt

npm install mqtt

All’interno del proprio script è necessario il riferimento:

var mqtt = require('mqtt');

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 potersi collegare al broker è inoltre necessario autenticarsi con il proprio username e un token OAuth. E' possibile creare token OAuth dalla sezione Credenziali, accessibile dal menù laterale Impostazioni. 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 devono essere in formato JSON, in particolare si segue la struttura:

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

device è il token del proprio dispositivo mentre date è la data della rilevazione. I segnali vanno inseriti nell'array signals, sono costituiti dal campo name che costituisce il token del segnale, e value il suo valore.

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 MQTT/<token dispositivo>/data

client.publish("MQTT/<token dispositivo>/data", JSON.stringify(post_data), function () {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTT/<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 MQTT/<token dispositivo>/data (dove MQTT 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 MQTT/<token dispositivo>/info (dove MQTT e info sono personalizzabili dall'utente).

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

client.on('message', function (topic, message) {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTT/<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",
      "note": "Testo piu' verboso per allarme da mqtt",
      "status": "ON",
      "ack": "NACK"
    }
}

I campi da inoltrare per la creazione di un'allarme sono quelli visualizzati successivamente in Databoom. In particolare si distinguono:

  • status per indicare se l'allarme è attivo ON o disattivato OFF;
  • ack per indicare se l'allarme è stato riconosciuto dall'utente ACK o meno 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"
      ]
    }
}

I campi da inoltrare per la creazione di un evento sono quelli visualizzati successivamente in Databoom (nel widget note):

  • from e to rappresentano le date d'inizio e di fine evento;
  • link permette di legare all'evento un dispositivo od un segnale;
  • tags permette di assegnare etichette all'evento.

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à MQTT/<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>
}

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.

Altre domande? Invia una richiesta

0 Commenti

Accedi per aggiungere un commento.