Modulo "opticloud" per il dashboard optiCLOUD

Descrizione

Il modulo "opticloud" fornisce un'interfaccia verso il dashboard optiCLOUD. Dal dispositivo di misura al dashboard possono essere trasmessi sia dati di telemetria sia client attribute. Inoltre il dashboard può inviare al dispositivo di misura i cosiddetti shared attribute. È inoltre possibile la comunicazione dal dashboard al dispositivo tramite interfaccia RPC.

Interfacce e protocolli utilizzati

• MQTT

Configurazione JSON

La sezione seguente descrive l'intera configurazione JSON del modulo e illustra i singoli parametri.

Configurazione di esempio (minima)

Di seguito una configurazione di esempio minima:

    {
      "module":"Opticloud",
      "factory":"opticloud",
      "config":{
        "channels":[
          {
            "name":"*"
          }
        ]
      }
    }

Configurazione di esempio (tipica)

    {
      "module": "Opticloud",
      "factory": "opticloud",
      "config":{
        "pollingIntervalMs":1000,
        "channels":[
          {
            "name": "*",
            "refreshIntervalMs":60000,
            "minimumSendIntervalMs":0
          }
        ]
      }
    }

Configurazione di esempio (massima)

    {
      "module":"Opticloud",
      "factory":"opticloud",
      "config":{
        "transmitBoolAsInt": false,
        "transmitStatusChannels": false,
        "channelnameTransmitData": "TransmitData",
        "connectTimeoutS": 10,
        "disconnectTimeoutS": 10,
        "keepaliveIntervalS": 10,
        "completionIntervalS": 10,
        "sendingIntervalS": 10,
        "maxBufferedMessages": 10,
        "channels":[
          {
            "name":"can*",
            "messageType":"telemetry,clientAttribute",
            "sendOnlyOnChange":true,
            "refreshIntervalMs":60000,
            "minimumSendIntervalMs":0,
            "useTrueTimestamps":false
          }
        ],
        "splitGpsLocationChannels":[
          {
            "gpsLocationChannelName":"GPS.Location",
            "gpsLatitudeChannelName":"GPS.Latitude",
            "gpsLongitudeChannelName":"GPS.Longitude",
            "gpsAltitudeChannelName":"GPS.Altitude"
          }
        ],
        "pollingIntervalMs":1000,
        "sharedAttributes":[
          {
            "name":"dataFromDashboardChannel",
            "type":"double",
            "persistent":true,
            "requestInitialValue":true,
            "bufferSize":1024,
            "physicalDimension":"temperature",
            "physicalUnit":"K"
          }
        ],
        "brokerAddress": "ssl://dashboard.opticloud.io:8883",
        "brokerUserId": "",
        "brokerUserPassword": "",
        "brokerAuthentication": true,
        "trustStore": "/etc/ssl/certs/ca-certificates.crt",
        "clientCertificate": "notImplementedYet"
      }
    }

Il JSON array "splitGpsLocationChannels" deve essere specificato solo se al dashboard vengono effettivamente trasmesse posizioni GPS, ad esempio dal modulo GPS, E se la suddivisione di questi dati deve essere configurata liberamente. I canali ottenuti dalla suddivisione vengono denominati automaticamente come segue, alternativamente

• aggiungendo ".Latitude", ".Longitude", ".Altitude" al nome del canale GPS Location, oppure
• rimuovendo il suffisso ".Location" e aggiungendo ".Latitude", ".Longitude", ".Altitude" al nome del canale GPS Location, se tale suffisso è presente nel nome del canale GPS Location.

Spostamento globale dei parametri specifici del dispositivo

I parametri specifici della connessione possono essere spostati nella seguente sezione globale della configurazione statica di smartCORE (smartcore.json), ovvero:

    "device_based":{
        "instances":{
            "opticloudInstance1":{
                "brokerAddress": "ssl://awe.some.io:8883",
                "brokerUserId": "",
                "brokerUserPassword": "",
                "brokerAuthentication": true,
                "clientCertificate": "notImplementedYet"
            }
        }
    },

Questi parametri globali hanno la precedenza sui parametri configurati a livello di modulo. In questo modo si semplifica la distribuzione di una stessa nuova configurazione di misura dinamica (smartcore_dynamic.json) su più dispositivi.

Parametri del modulo (globali) specifici della connessione

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori consigliato	Default	Descrizione
brokerAddress	No	STRING	URL del dashboard valido		"ssl://dashboard.opticloud.io:8883" , "tcp://awe.some.io:1883" (sconsigliato)
brokerUserId	No	STRING		numero di serie	Nome utente (User-ID) del dispositivo
brokerUserPassword	No	STRING	""	""	Password del server del dashboard
brokerAuthentication	No	BOOL	true, false	true	Autenticazione del server del dashboard
trustStore	No	STRING		/etc/ssl/certs/ca-certificates.crt	Trust store per l'autenticazione del server del dashboard
clientCertificate	No	STRING BASE64	certificato valido		Certificato per l'autenticazione del dispositivo (non supportato)

Parametri del modulo

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori consigliato	Default	Descrizione
pollingIntervalMs	No	INT	1000 -	1000	Intervallo di acquisizione dei dati dei canali a livello di modulo [ms]
transmitBoolAsInt	No	BOOL	false, true	false	Trasmette i valori booleani (false, true) come numeri interi (0, 1)
transmitStatusChannels	No	BOOL	false, true	false	Indica se devono essere creati e trasmessi segnali STATUS
channelnameTransmitData	No	STRING	nome di canale valido	""	Canale per sospendere e riprendere la trasmissione dei dati di misura, vedere sotto (da smartCORE 2.12)
connectTimeoutS	No	INT	1 -	10	Timeout per lo stabilimento della connessione
disconnectTimeoutS	No	INT	1 -	10	Timeout per la disconnessione dopo la 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
maxBufferedMessages	No	INT	1 -	10	Numero massimo di messaggi MQTT in buffer all'interno del client MQTT
channels	SÌ	JSON Array			vedere sotto
splitGpsLocations	facoltativo per i canali GPS	JSON Array			vedere sotto
sharedAttributes	No	JSON Array			vedere sotto

Configurazione dei canali "channels"

I canali di telemetria / client attribute trasmessi al dashboard vengono configurati ciascuno come oggetto JSON con i seguenti parametri

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori consigliato	Default	Descrizione
name	SÌ	STRING	nome di canale valido		Nome del canale; sono supportati i wildcard semplificati "*" e "?"
messageType	No	STRING	"telemetry", "clientAttribute"	"telemetry"	Tipo di trasmissione al dashboard. È possibile anche "telemetry,clientAttribute"
sendOnlyOnChange	No	BOOL	true, false	true	Riduzione dei dati per i valori di canale invariati
refreshIntervalMs	No	INT	1 -	60000 (60 s)	Nuovo invio di valori identici allo scadere di un intervallo, se il relativo timestamp attendibile è stato aggiornato
minimumSendIntervalMs	No	INT	0 -	0 (0 s)	Intervallo minimo di trasmissione per canale
useTrueTimestamps	No	BOOL	false, true	false	Se impostato, trasmissione con i timestamp di produzione (altrimenti timestamp del ciclo di elaborazione)

Suddivisione dei canali GPS Location "splitGpsLocationChannels"

I canali GPS Location devono essere suddivisi prima dell'invio al dashboard. La suddivisione può essere definita per ciascun canale sotto forma di oggetto JSON

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori consigliato	Default	Descrizione
gpsLocationChannelName	SÌ	STRING	nome valido di canale GPS Location		Canale di ingresso da smartCORE
gpsLatitudeChannelName	No	STRING		vedere sopra	Nome del canale per la trasmissione della latitudine al dashboard
gpsLongitudeChannelName	No	STRING		vedere sopra	Nome del canale per la trasmissione della longitudine al dashboard
gpsAltitudeChannelName	No	STRING		vedere sopra	Nome del canale per la trasmissione dell'altitudine sul livello del mare al dashboard

Configurazione dei canali "sharedAttributes"

Tramite "sharedAttributes" gli attributi creati sul dashboard possono essere caricati sul dispositivo e prodotti nei canali corrispondenti. La configurazione avviene per ciascun canale mediante il seguente oggetto JSON.

Nome del parametro	Obbligatorio	Tipo di dati	Intervallo di valori consigliato	Default	Descrizione
name	SÌ	STRING	nome di canale valido		Nome del canale
type	SÌ	STRING	tipo di dati valido		"bool", "double", "float", "string", "[u]int8"
persistent	No	BOOL	false, true	true	indica se l'ultimo valore del canale deve rimanere persistente dopo un riavvio di smartCORE
requestInitialValue	No	BOOL	false, true	true	richiesta aggiuntiva dello shared attribute subito dopo l'avvio del funzionamento di misura
bufferSize	No	INT	1 -	1024	Dimensione del buffer del canale creato
physicalDimension	No	STRING			Grandezza fisica
physicalUnit	No	STRING			Unità fisica

Controllo della trasmissione dei dati "channelnameTransmitData"

informazioni

Questo parametro è disponibile a partire da smartCORE 2.12.

Tramite il parametro facoltativo "channelnameTransmitData" è possibile sospendere e riprendere la trasmissione dei dati di misura durante il funzionamento, senza interrompere la connessione al dashboard. Si indica il nome di un canale con timestamp di tipo di dati "bool".

Finché questo canale ha il valore false, il modulo trattiene i dati di misura. Tutto ciò che mantiene raggiungibile il dispositivo continua a funzionare invariato:

Tipo di dati	Comportamento finché il canale di controllo ha il valore false
Telemetria	viene trattenuta
Client attribute	vengono trattenuti
Valori STATUS di questo modulo	non vengono trasmessi, ma continuano a essere scritti localmente nei canali STATUS
Canale di controllo stesso	continua a essere trasmesso, purché faccia parte della configurazione "channels"
Allarmi	invariato
Shared attribute (dashboard → dispositivo)	invariato
RPC	invariato
Numero di serie	invariato

Il canale di controllo stesso è volutamente escluso dal blocco: in questo modo nel dashboard un silenzio voluto resta distinguibile da un'interruzione della connessione. Poiché la connessione rimane attiva, la trasmissione può essere riattivata in qualsiasi momento dal dashboard.

Lo stato del canale di controllo viene valutato una volta per ciclo di acquisizione ("pollingIntervalMs"); ogni cambio di stato viene scritto nel log.

In caso di dubbio si trasmette. La trasmissione resta attiva in tutti i casi seguenti:

• il parametro manca o è vuoto,
• il canale indicato non esiste,
• il canale indicato non ha timestamp oppure non è di tipo di dati "bool",
• il canale non ha ancora alcun valore.

Un errore di battitura nel nome del canale non può quindi mettere a tacere un dispositivo. I tre casi relativi al canale vengono scritti nel log come avviso all'avvio del funzionamento di misura.

Il caso d'uso tipico è il controllo dal dashboard tramite uno shared attribute:

    "channelnameTransmitData":"TransmitData",
    "sharedAttributes":[
      {
        "name":"TransmitData",
        "type":"bool",
        "persistent":true,
        "requestInitialValue":true
      }
    ]

Uno shared attribute creato in questo modo è un canale con timestamp del tipo di dati indicato e soddisfa quindi i requisiti per il canale di controllo. Il modulo stesso non memorizza lo stato: dopo un riavvio si trasmette finché il canale di controllo non ha un valore. "persistent" e "requestInitialValue" fanno sì che l'ultimo valore impostato sia nuovamente disponibile.

Il canale di controllo non deve necessariamente provenire dal dashboard. È possibile ad esempio anche un ingresso digitale o un canale calcolato dal modulo "math"; è richiesto soltanto un canale con timestamp di tipo di dati "bool".

Informazioni sul modulo

Informazione	Valore
Autori	optiMEAS GmbH
da smartCORE	0
Tipo di modulo	Consumer, (facoltativo) Producer
Dipendenze	dashboard optiCLOUD