Modulo MQTT "mqtt"

Descrizione

Il modulo MQTT serve alla comunicazione bidirezionale con un broker MQTT.

È possibile associare più canali smartCORE a un topic MQTT, e il modulo consente la selezione di più topic.

Inoltre è possibile istanziare più moduli, per poter comunicare contemporaneamente con più broker diversi.

Per l'interpretazione e la preparazione dei payload MQTT sono supportati i cosiddetti payload hint, che servono alla descrizione del formato.

In direzione di pubblicazione servono a eseguire un controllo della sintassi dei modelli di pubblicazione, nei quali vengono poi inseriti i valori dei canali consumati (ad es. per formati comuni come JSON, XML, ...).

Viceversa, in direzione di sottoscrizione (subscribe) questi payload hint servono a fornire meccanismi di estrazione dei dati adatti ai formati citati, in modo che i valori così estratti possano essere prodotti nei corrispondenti canali smartCORE.

Interfacce e protocolli utilizzati

• MQTT

Configurazione JSON

Nella sezione seguente viene descritta l'intera configurazione JSON del modulo e vengono illustrati i singoli parametri.

Configurazione di esempio (minima e tipica)

Di seguito una configurazione di esempio minima:

    {
      "module":"MQTT",
      "factory":"mqtt",
      "config":{
        "brokerAddress": "ssl://awe.some.io:8883",
        "brokerUserId": "USER_ID",
        "brokerUserPassword": "USER_PASSWORD",
        "brokerClientId": "CLIENT_ID",
        "topics":[

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Configurazione di esempio (massima)

    {
      "module":"MQTT",
      "factory":"mqtt",
      "config":{
        "useLocalBroker":false,
        "enabled":true,
        "pollingIntervalMs":1000,

        "brokerAddress": "ssl://awe.some.io:8883",
        "brokerAuthentication": true,
        "trustStore": "/etc/ssl/certs/ca-certificates.crt",
        "brokerUserId": "USER_ID",
        "brokerUserPassword": "USER_PASSWORD",
        "brokerClientId": "CLIENT_ID",

        "maxBufferedMessages": 10,
        "connectTimeoutS": 10,
        "disconnectTimeoutS": 10,
        "keepaliveIntervalS": 10,
        "completionIntervalS": 10,
        "sendingIntervalS": 10,
        "topics":[

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Esempi di oggetti JSON per la configurazione dei topic...

I seguenti oggetti JSON possono essere inseriti nell'array topics citato sopra.

...in direzione di pubblicazione

Le stringhe indicate in mqttName fungono da segnaposto, che vengono sostituiti 1:1 dai valori dei canali smartCORE indicati in channelName.

{
    "name":"sensor/state",
    "direction":"publish",
    "payload":"{\"voltage\":%BAT_VOLTAGE%,\"current\":%BAT_CURRENT%}",
    "payloadHint":"json",
    "channels":[
        {
            "mqttName":"%BAT_VOLTAGE%",
            "channelName":"PowerSupplyVoltage"
        },
        {
            "mqttName":"%BAT_CURRENT%",
            "channelName":"PowerSupplyCurrent"
        }
    ]
}

...in direzione di sottoscrizione

Le stringhe indicate in mqttName descrivono come devono essere estratti i dati dei canali dal payload MQTT, cosa possibile in modi diversi (vedere sotto).

  {
    "name":"sensor/status/switch:0",
    "direction":"subscribe",
    "payloadHint":"json",
    "channels":[
      {
        "mqttName":"power",
        "channelName":"Power",
        "dataType":"float"
      },
      {
        "mqttName":"current",
        "channelName":"Current",
        "dataType":"float"
      },
      {
        "mqttName":"temperature/tC",
        "channelName":"TemperatureTC",
        "dataType":"float"
      }
    ]
  }

Parametri del modulo

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori sensato	Default	Descrizione
useLocalBroker	No	BOOL	true, false	false	Avvia un broker MQTT sul dispositivo e comunica con esso
enabled	No	BOOL	true, false	true	Attività della comunicazione con il broker
pollingIntervalMs	No	INT	1 -	1000	Intervallo di elaborazione relativo al modulo [ms]
brokerAddress	No	STRING	URL del broker valido		"ssl://awe.some.io:8883" , "tcp://awe.some.io:1883" (sconsigliato)
brokerAuthentication	No	BOOL	true, false	true	Autenticazione del broker
trustStore	No	STRING		/etc/ssl/certs/ca-certificates.crt	Trust store per l'autenticazione del broker
brokerUserId	No	STRING			Identificativo utente del broker
brokerUserPassword	No	STRING			Password utente del broker
brokerClientId	No	STRING			Identificativo del client/dispositivo del broker
maxBufferedMessages	No	INT	1 -	10	Numero massimo di messaggi MQTT in buffer all'interno del client MQTT
connectTimeoutS	No	INT	1 -	10	Timeout per lo stabilimento della connessione
disconnectTimeoutS	No	INT	1 -	10	Timeout per la disconnessione dopo richiesta
keepaliveIntervalS	No	INT	1 -	10	Timeout per il rilevamento di una connessione interrotta
completionIntervalS	No	INT	1 -	10	Timeout per la ricezione della conferma dopo l'invio di un messaggio MQTT
sendingIntervalS	No	INT	1 -	10	Timeout per l'invio di un messaggio MQTT
topics	SÌ	JSON Array			vedere Configurazione dei topic MQTT

Configurazione dei topic MQTT "topics"

Si distingue tra topic da pubblicare (published) e topic da sottoscrivere (subscribed).

Topic da pubblicare (published topics)

Un topic da pubblicare, che in genere contiene una selezione di canali smartCORE, viene configurato come oggetto JSON contenente i seguenti parametri.

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori sensato	Default	Descrizione
name	SÌ	STRING			Nome/percorso del topic sul broker
direction	SÌ	STRING	"publish"		da impostare su "publish" per un topic da pubblicare
payload	SÌ	STRING			Modello di payload
payloadHint	SÌ	STRING	"plain", "json"	"json"	Selezione del formato di payload da trasmettere, rispetto al quale viene eseguito un controllo della sintassi del modello di payload, se possibile
channels	SÌ	JSON Array			vedere sotto

La configurazione dei canali da pubblicare avviene sotto forma di JSON Array contenente oggetti JSON con i seguenti parametri.

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori sensato	Default	Descrizione
channelName	SÌ	STRING			Nome del canale smartCORE da consumare
mqttName	SÌ	STRING			Sottostringa all'interno del modello di payload che viene sostituita con una rappresentazione in stringa del valore attuale del canale.
format	NO	STRING			Istruzione di formattazione per la conversione del valore del canale in stringa
translateFalse	NO	STRING		"false"	Rappresentazione in stringa del valore booleano falso
translateTrue	NO	STRING		"true"	Rappresentazione in stringa del valore booleano vero

Topic da sottoscrivere (subscribed topics)

Un topic da sottoscrivere, che in genere mette a disposizione una selezione di canali smartCORE, viene configurato come oggetto JSON contenente i seguenti parametri.

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori sensato	Default	Descrizione
name	SÌ	STRING			Nome/percorso del topic sul broker
direction	SÌ	STRING	"subscribe"		da impostare su "subscribe" per un topic da sottoscrivere
payloadHint	SÌ	STRING	"plain", "json"	"json"	Selezione del formato di payload da ricevere, rispetto al quale viene eseguita l'estrazione dei dati nei canali configurati.
channels	SÌ	JSON Array			vedere sotto

La configurazione dei canali da pubblicare avviene sotto forma di JSON Array contenente oggetti JSON con i seguenti parametri.

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori sensato	Default	Descrizione
channelName	SÌ	STRING			Nome del canale smartCORE da produrre
dataType	SÌ	STRING	tipo di dati smartCORE valido		Tipo di dati del canale
bufferSize	NO	INT	1 -	1024	Dimensione del buffer del canale
physicalUnit	NO	STRING			Unità fisica del canale
mqttName	SÌ	STRING			Stringa che descrive un'istruzione per l'estrazione di singoli valori di canale da un payload (ad es. l'indicazione di un percorso per payload JSON)
translateFalse	NO	STRING		"false"	Rappresentazione in stringa del valore booleano falso
translateTrue	NO	STRING		"true"	Rappresentazione in stringa del valore booleano vero

Particolarità relative al contenuto del payload

Estrazione diretta 1:1 dei dati (payloadHint "plain")

In direzione di sottoscrizione (subscribe) l'intero contenuto del payload viene utilizzato integralmente come valore del canale. Viene eseguita una conversione automatica e tollerante agli errori nel tipo di dati di destinazione, nella misura in cui sia possibile. Viceversa, in direzione di pubblicazione non viene eseguito alcun controllo della sintassi.

JSON (payloadHint "json")

Per estrarre dati di canale da un topic sottoscritto con payload in formato JSON, come parametro "mqttName" può essere utilizzata l'indicazione di un percorso.

Esempio: il payload ricevuto contiene il seguente oggetto JSON.

{
  "someObject":{
    "someSubObject/with/slash":{
      "someKey": 42
    }
  }
  "someArray":[
    1,
    2,
    3
  ]
}

allora "mqttName":"someObject/someSubObject\/with\/slash/someKey" estrae il valore 42, che viene quindi prodotto nel canale definito come "channelName" (cioè è necessario eseguire l'escape del carattere separatore "/").

Analogamente "mqttName":"someArray/1" estrae il valore 2 dall'oggetto JSON citato (cioè, nel caso di un JSON Array, la componente del percorso viene utilizzata come indice).

Se vengono specificati più separatori "/" consecutivi, essi vengono considerati come un unico separatore.

Se viene specificato un percorso non valido, in ogni caso non viene prodotto alcun dato di canale.

Informazioni sul modulo

Informazione	Valore
Autori	optiMEAS GmbH
da smartCORE	2.6
Tipo di modulo	a scelta Consumer, Producer o entrambi
Dipendenze	broker MQTT disponibile