optiCLOUD Dashboard Modul "opticloud"

Beschreibung

Das "opticloud" Modul stellt eine Schnittstelle zum optiCLOUD Dashboard zur Verfügung. Es können hierbei sowohl Telemetriedaten als auch Client-Attribute vom Messgerät ans Dashboard übertragen werden. Darüberhinaus ist eine Einspeisung sogenannter Shared-Attribute seitens des Dashboards an das Messgerät möglich. Zusätzlich besteht die Möglichkeit der Kommunikation via RPC-Schnittstelle vom Dashboard aus an das Gerät.

Verwendete Schnittstellen & Protokolle

• MQTT

JSON-Konfiguration

Im folgenden Abschnitt soll die gesamte JSON-Konfiguration des Moduls beschrieben und die einzelnen Parameter erläutert werden.

Beispielkonfiguration (minimal)

Im folgenden eine minimale Beispielkonfiguration:

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

Beispielkonfiguration (typisch)

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

Beispielkonfiguration (maximal)

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

Das "splitGpsLocationChannels" JSON Array ist nur dann zu spezifizieren, falls tatsächlich GPS Locations, etwa aus dem GPS Modul, an das Dashboard übertragen werden UND das Splitting dieser Daten frei konfiguriert werden soll. Hierbei werden die aufgeteilten Kanäle wie folgt automatisch benannt, entweder duch

• Anhängen von ".Latitude", ".Longitude", ".Altitude" an den GPS Location Kanalnamen, oder
• Entfernen des ".Location" Suffix und Anhängen von ".Latitude", ".Longitude", ".Altitude" an den GPS Location Kanalnamen, falls dieser Suffix im GPS Location Kanalnamen existiert.

Globale Auslagerung gerätespezifischer Parameter

Die verbindungsspezifischen Parameter können hierbei in die folgende globale Sektion der statischen smartCORE Konfiguration (smartcore.json) ausgelagert werden, d.h.:

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

Diese globalen Parameter haben Vorrang vor den modulspezifisch konfigurierten Parametern. Es wird hierdurch das Ausrollen einer gleichen neuen dynamischen Messkonfigurationen (smartcore_dynamic.json) auf mehrere Geräte vereinfacht.

(Globale) Verbindungsspezifische Modulparameter

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
brokerAddress	Nein	STRING	gültige Dashboard URL		"ssl://dashboard.opticloud.io:8883" , "tcp://awe.some.io:1883" (nicht empfohlen)
brokerUserId	Nein	STRING		Seriennummer	Password des Geräts
brokerUserPassword	Nein	STRING	""	""	Password der Dashboard-Servers
brokerAuthentication	Nein	BOOL	true, false	true	Dashboard-Server-Authentifizierung
trustStore	Nein	STRING		/etc/ssl/certs/ca-certificates.crt	Trust Store für Dashboard-Server-Authentifizierung
clientCertificate	Nein	STRING BASE64	gültiges Zertifikat		Zertifikat für Geräte-Authentifizierung (nicht unterstützt)

Modulparameter

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
pollingIntervalMs	Nein	INT	1000 -	1000	Modulbezogenes Kanaldatenaquisitionsintervall [ms]
transmitBoolAsInt	Nein	BOOL	false, true	false	Boole'sche Werte (false,true) als Ganzzahlen (0,1) übertragen
transmitStatusChannels	Nein	BOOL	false, true	false	Gibt an, ob STATUS Signale erstellt und Übertragen werden sollen
channelnameTransmitData	Nein	STRING	gültiger Kanalname	""	Kanal zum Anhalten und Fortsetzen der Messdatenübertragung, siehe unten (ab smartCORE 2.12)
connectTimeoutS	Nein	INT	1 -	10	Timeout bzgl. Verbindungsherstellung
disconnectTimeoutS	Nein	INT	1 -	10	Timeout bzgl. Verbindungstrennung nach Aufforderung
keepaliveIntervalS	Nein	INT	1 -	10	Timeout bzgl. Detektion einer getrennten Verbindung
completionIntervalS	Nein	INT	1 -	10	Timeout bzgl. Quittierungsempfang nach Versand einer MQTT Botschaft
sendingIntervalS	Nein	INT	1 -	10	Timeout bzgl. Versand einer MQTT Botschaft
maxBufferedMessages	Nein	INT	1 -	10	Maximale Anzahl gepufferter MQTT Botschaften innerhalb des MQTT Clients
channels	JA	JSON Array			siehe unten
splitGpsLocations	optional bei GPS Kanälen	JSON Array			siehe unten
sharedAttributes	Nein	JSON Array			siehe unten

Kanalkonfiguration "channels"

Die an das Dashboard übertragenen Telemetrie-/Client-Attribute-Kanäle werden jeweils als JSON Object mit folgenden Parametern konfiguriert

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
name	JA	STRING	gültiger Kanalname		Kanalname, es werden vereinfachte Wildcards "*" und "?" unterstützt
messageType	Nein	STRING	"telemetry", "clientAttribute"	"telemetry"	Art der Übertragung an das Dashboard. "telemetry,clientAttribute" ist ebenso möglich
sendOnlyOnChange	Nein	BOOL	true, false	true	Datenreduktion unveränderter Kanalwerte
refreshIntervalMs	Nein	INT	1 -	60000 (60 s)	Erneuter Versand gleicher Werte nach Ablauf eines Intervalls, falls ihr zugehöriger vertrauenswürdiger Zeitstempel aktualisiert wurde
minimumSendIntervalMs	Nein	INT	0 -	0 (0 s)	Kanalbezogenes minimales Übertragungsintervall
useTrueTimestamps	Nein	BOOL	false, true	false	Übertragung unter Verwendung der Produktionszeitstempel, wennn gesetzt (sonst Zeitstempel des Verarbeitungszyklus)

Aufteilung der GPS Location Kanäle "splitGpsLocationChannels"

Die GPS Location Kanäle müssen vor dem Versand an das Dashboard aufgeteilt werden. Die Aufteilung kann in Form eines JSON Objekts für jeden Kanal definiert werden

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
gpsLocationChannelName	JA	STRING	gültiger GPS Location Kanalname		Eingangskanal aus dem smartCORE
gpsLatitudeChannelName	Nein	STRING		siehe oben	Kanalname für Übertragung der geo. Breite an das Dashboard
gpsLongitudeChannelName	Nein	STRING		siehe oben	Kanalname für Übertragung der geo. Länge an das Dashboard
gpsAltitudeChannelName	Nein	STRING		siehe oben	Kanalname für Übertragung der geo. Höhe über NN an das Dashboard

Kanalkonfiguration "sharedAttributes"

Über "sharedAttributes" können seitens des Dashboards angelegte Attribute auf das Gerät geladen und in entsprechende Kanäle produziert werden. Die Konfiguration erfolgt hierbei über folgendes JSON Objekt für jeden Kanal.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
name	JA	STRING	gültiger Kanalname		Kanalname
type	JA	STRING	gültiger Datentyp		"bool", "double", "float", "string", "[u]int8"
persistent	Nein	BOOL	false, true	true	soll der letzte Wert des Kanals über einen smartCORE Neustart hinweg beständig sein
requestInitialValue	Nein	BOOL	false, true	true	zusätzlicher Bezug des sharedAttributes direkt nach Start des Messbetriebs
bufferSize	Nein	INT	1 -	1024	Puffergröße des angelegten Kanals
physicalDimension	Nein	STRING			Physikalische Größe
physicalUnit	Nein	STRING			Physikalische Einheit

Steuerung der Datenübertragung "channelnameTransmitData"

info

Dieser Parameter steht ab smartCORE 2.12 zur Verfügung.

Über den optionalen Parameter "channelnameTransmitData" kann die Übertragung der Messdaten zur Laufzeit angehalten und wieder aufgenommen werden, ohne die Verbindung zum Dashboard zu trennen. Angegeben wird der Name eines zeitgestempelten Kanals vom Datentyp "bool".

Solange dieser Kanal den Wert false führt, hält das Modul die Messdaten zurück. Alles, was das Gerät erreichbar hält, läuft unverändert weiter:

Datenart	Verhalten, solange der Steuerkanal false führt
Telemetrie	wird zurückgehalten
Client-Attribute	werden zurückgehalten
STATUS-Werte dieses Moduls	werden nicht übertragen, aber weiterhin lokal in die STATUS-Kanäle geschrieben
Steuerkanal selbst	wird weiterhin übertragen, sofern er Teil der "channels" Konfiguration ist
Alarme	unverändert
Shared Attributes (Dashboard → Gerät)	unverändert
RPC	unverändert
Seriennummer	unverändert

Der Steuerkanal selbst ist bewusst von der Sperre ausgenommen: dadurch bleibt im Dashboard ein gewolltes Schweigen von einem Verbindungsabbruch unterscheidbar. Da die Verbindung bestehen bleibt, kann die Übertragung jederzeit vom Dashboard aus wieder eingeschaltet werden.

Der Zustand des Steuerkanals wird einmal je Erfassungszyklus ("pollingIntervalMs") ausgewertet, jeder Zustandswechsel wird ins Log geschrieben.

Im Zweifel wird übertragen. Die Übertragung bleibt in allen folgenden Fällen aktiv:

• der Parameter fehlt oder ist leer,
• der angegebene Kanal existiert nicht,
• der angegebene Kanal ist nicht zeitgestempelt oder nicht vom Datentyp "bool",
• der Kanal führt noch keinen Wert.

Ein Tippfehler im Kanalnamen kann ein Gerät also nicht stumm schalten. Die drei kanalbezogenen Fälle werden beim Start des Messbetriebs als Warnung ins Log geschrieben.

Der typische Anwendungsfall ist die Steuerung aus dem Dashboard heraus über ein Shared Attribute:

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

Ein so angelegtes Shared Attribute ist ein zeitgestempelter Kanal des angegebenen Datentyps und erfüllt damit die Anforderungen an den Steuerkanal. Das Modul selbst speichert den Zustand nicht: nach einem Neustart wird übertragen, bis der Steuerkanal einen Wert führt. "persistent" und "requestInitialValue" sorgen dafür, dass der zuletzt gesetzte Wert wieder zur Verfügung steht.

Der Steuerkanal muss nicht aus dem Dashboard stammen. Ebenso möglich ist etwa ein Digitaleingang oder ein berechneter Kanal aus dem "math" Modul; verlangt wird lediglich ein zeitgestempelter Kanal vom Datentyp "bool".

Modul-Informationen

Information	Wert
Autoren	optiMEAS GmbH
seit smartCORE	0
Modultyp	Consumer, (optional) Producer
Abhängigkeiten	optiCLOUD Dashboard