Come comunicare con Databoom utilizzando MQTTBox o MQTTLens – Databoom

E' possibile collegarsi al broker MQTT di Databoom utilizzando utility online quali MQTTBox o MQTTLens.

Per la configurazione di un dispositivo MQTT in Databoom leggi anche: MQTT

Prima di iniziare

Per potersi collegare al broker MQTT è necessario annotare da Databoom:

il proprio username;
- nell'esempio verrà utilizzato lo username:
  - databoom
il proprio ambito utente (dal profilo personale);
- nell'esempio verrà utilizzato l'ambito:
  - aFk1
un token OAuth (Impostazioni 🡺 Credenziali 🡺 Chiavi OAuth/Aggiungi OAuth);
- nell'esempio verrà utilizzato un token fittizio:
  - kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M=
il token del proprio dispositivo (dalla pagina di dettaglio del dispositivo);
- nell'esempio verrà utilizzato il token fittizio:
  - 0ewpu6ewmj
i topic per la pubblicazione/sottoscrizione del proprio dispositivo (dalla pagina di dettaglio del dispositivo);
- nell'esempio verranno utilizzati i topic fittizi:
  - MQTT/0ewpu6ewmj/data per la pubblicazione
  - MQTT/0ewpu6ewmj/info per la sottoscrizione

TIP! E' consigliabile generare un token OAuth diverso per ogni client utilizzato per una maggiore sicurezza.

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. Se il campo date viene omesso verrà utilizzata la data di ricezione del valore.

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.

Coi valori dell'esempio avremo quindi:

{
 "type": "data",
 "message": {
     "device": "0ewpu6ewmj",
     "date": "2018-04-13T09:00:00+02:00",
     "signals" : [
       {
         "name": "MQTT_signal",
         "value": 123  
       }
     ]
   }
}

MQTTBox

I campi necessari per la creazione di un client MQTT sono:

MQTT Client Name, un nome a piacere per identificare il proprio client nell'applicazione;
MQTT Client Id, formato dall'ambito utente e dal token del dispositivo con la struttura <ambito utente>-<token dispositivo>;
- Il Client Id d'esempio è:
  - aFk1-0ewpu6ewmj
Protocol, è consentito l'utilizzo di mqtt / tcp o mqtts / tls;
Host, l'indirizzo del broker di Databoom mqtt.databoom.com e la porta utilizzata (1883 nel caso di tcp, 8883 nel caso di tls);
Username, il nome utente;
- Lo username di esempio è:
  - databoom
Password, un token OAuth generato dall'utente;
- il token di esempio è:
  - kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M=
Append timestamp to MQTT client id dev'essere deselezionato.

E' inoltre possibile autenticarsi attraverso l'utilizzo dei certificati, generati alla creazione di un dispositivo MQTT in Databoom:

Protocol dev'essere impostato a mqtts / tls
Host va impostato a mqttcert.databoom.com:8883
SSL / TLS Version va impostato a TLSv1.2
SSL / TLS Certificate Type va impostato a Self signed certificates
Nei campi CA file, Client certificate file, Client key file vanno caricati i file certificati scaricati dal dispositivo in Databoom

Una volta stabilita la connessione con il broker è possibile pubblicare dei dati oppure sottoscriversi al topic per supervisionare gli eventi del dispositivo.

Il topic per la pubblicazione è costituito da <progetto>/<token dispositivo>/<topic>, ed è visualizzato nella pagina di dettaglio del dispositivo. Il formato dei dati da inoltrare è un JSON contenente il token del dispositivo e i segnali con i loro valori, come riportato in capo all'articolo.

Con i dati dell'esempio il topic sarà:
- MQTT/0ewpu6ewmj/data

Il topic per la sottoscrizione è costituito da <progetto>/<token dispositivo>/<topic>, ed è visualizzato nella pagina di dettaglio del dispositivo. Sottoscrivendosi a dispositivo verranno visualizzati tutti gli eventi, come ad esempio la conferma di ricezione dei dati pubblicati.

Con i dati dell'esempio il topic sarà:
- MQTT/0ewpu6ewmj/info

Pubblicando sul topic dati è anche possibile creare allarmi ed eventi seguendo rispettivamente i formati:

{
    "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"
    }
}

{
    "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"
      ]
    }
}

Con i dati dell'esempio avremo:

{
    "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"
    }
}

{
    "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": "0ewpu6ewmj",
            "signal": "MQTT_signal"
        },
      "tags": [
        "mqtt"
      ]
    }
}

MQTTLens