optiCLOUD Dashboard module "opticloud"

Description

The "opticloud" module provides an interface to the optiCLOUD dashboard. Both telemetry data and client attributes can be transferred from the measuring device to the dashboard. It is also possible to feed so-called shared attributes from the dashboard to the measuring device. It is also possible to communicate from the dashboard to the device via an RPC interface.

Interfaces & protocols used

• MQTT

JSON configuration

The following section describes the entire JSON configuration of the module and explains the individual parameters.

Example configuration (minimum)

The following is a minimal example configuration:

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

Example configuration (typical)

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

Example configuration (maximum)

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

The "splitGpsLocationChannels" JSON array only needs to be specified if GPS locations are actually transferred to the dashboard, e.g. from the GPS module, are actually transmitted to the dashboard AND the splitting of this data is to be freely configured. In this case, the split channels are automatically named as follows, either by

• Append ".Latitude", ".Longitude", ".Altitude" to the GPS location channel name, or
• Remove the ".Location" suffix and append ".Latitude", ".Longitude", ".Altitude" to the GPS location channel name if this suffix exists in the GPS location channel name.

Global swapping of device-specific parameters

The connection-specific parameters can be outsourced to the following global section of the static smartCORE configuration (smartcore.json), i.e:

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

These global parameters have priority over the module-specific configured parameters. This makes it easier to roll out the same new dynamic measurement configuration (smartcore_dynamic.json) to several devices.

(Global) connection-specific module parameters

Parameter Name	Required	Data Type	Meaningful Value Range	Default	Description
brokerAddress	No	STRING	valid dashboard URL		"ssl://dashboard.opticloud.io:8883" , "tcp://awe.some.io:1883" (not recommended)
brokerUserId	No	STRING		Serial number	Password of the device
brokerUserPassword	No	STRING	""	""	Password of the dashboard server
brokerAuthentication	No	BOOL	true, false	true	Dashboard server authentication
trustStore	No	STRING		/etc/ssl/certs/ca-certificates.crt	Trust Store for dashboard server authentication
clientCertificate	No	STRING BASE64	valid certificate		certificate for device authentication (not supported)

Module parameters

Parameter name	Required	Data type	Meaningful value range	Default	Description
pollingIntervalMs	No	INT	1000 -	1000	Module-related channel data acquisition interval [ms]
transmitBoolAsInt	No	BOOL	false, true	false	transmit Boolean values (false,true) as integers (0,1)
transmitStatusChannels	No	BOOL	false, true	false	Determines whether STATUS signals should be created and transmitted
channelnameTransmitData	No	STRING	valid channel name	""	Channel used to suspend and resume the transmission of measurement data, see below (from smartCORE 2.12)
connectTimeoutS	No	INT	1 -	10	Timeout regarding connection establishment
disconnectTimeoutS	No	INT	1 -	10	Timeout regarding disconnection after request
keepaliveIntervalS	No	INT	1 -	10	Timeout regarding detection of a disconnected connection
completionIntervalS	No	INT	1 -	10	Timeout regarding acknowledgement receipt after sending an MQTT message
sendingIntervalS	No	INT	1 -	10	Timeout for sending an MQTT message
maxBufferedMessages	No	INT	1 -	10	Maximum number of buffered MQTT messages within the MQTT client
channels	YES	JSON Array			see below
splitGpsLocations	optional for GPS channels	JSON array			see below
sharedAttributes	No	JSON Array			see below

Channel configuration "channels"

The telemetry/client attribute channels transmitted to the dashboard are each configured as a JSON object with the following parameters

Parameter Name	Required	Data Type	Meaningful Value Range	Default	Description
name	YES	STRING	valid channel name		channel name, simplified wildcards "*" and "?" are supported
messageType	No	STRING	"telemetry", "clientAttribute"	"telemetry"	Type of transmission to the dashboard. "telemetry,clientAttribute" is also possible
sendOnlyOnChange	No	BOOL	true, false	true	Data reduction of unchanged channel values
refreshIntervalMs	No	INT	1 -	60000 (60 s)	Resend the same values after an interval has expired if their associated trusted timestamp has been updated
minimumSendIntervalMs	No	INT	0 -	0 (0 s)	Channel-related minimum transmission interval
useTrueTimestamps	No	BOOL	false, true	false	Transmission using the production timestamps, if set (otherwise timestamp of the processing cycle)

Splitting the GPS location channels "splitGpsLocationChannels"

The GPS location channels must be split before being sent to the dashboard. The split can be defined in the form of a JSON object for each channel

Parameter name	Required	Data type	Meaningful value range	Default	Description
gpsLocationChannelName	YES	STRING	valid GPS location channel name		input channel from the smartCORE
gpsLatitudeChannelName	No	STRING		see above	Channel name for transmission of geo. Latitude to the dashboard
gpsLongitudeChannelName	No	STRING		see above	Channel name for transmitting the geo. Longitude to the dashboard
gpsAltitudeChannelName	No	STRING		see above	Channel name for transmitting the geo. Altitude above sea level to the dashboard

Channel configuration "sharedAttributes"

Attributes created by the dashboard can be loaded onto the device via "sharedAttributes" and produced in corresponding channels. The configuration is carried out via the following JSON object for each channel.

Parameter name	Required	Data type	Meaningful value range	Default	Description
name	YES	STRING	valid channel name		channel name
type	YES	STRING	valid data type		"bool", "double", "float", "string", "[u]int8"
persistent	no	BOOL	false, true	true	should the last value of the channel be persistent across a smartCORE restart
requestInitialValue	No	BOOL	false, true	true	additional reference to the sharedAttribute directly after the start of measurement operation
bufferSize	No	INT	1 -	1024	Buffer size of the created channel
physicalDimension	No	STRING			Physical dimension
physicalUnit	No	STRING			Physical unit

Controlling the data transmission "channelnameTransmitData"

info

This parameter is available from smartCORE 2.12 onwards.

The optional parameter "channelnameTransmitData" suspends and resumes the transmission of measurement data at runtime without dropping the connection to the dashboard. It takes the name of a timestamped channel of data type "bool".

While that channel reads false, the module holds the measurement data back. Everything that keeps the device reachable continues unchanged:

Kind of data	Behaviour while the control channel reads false
Telemetry	held back
Client attributes	held back
STATUS values of this module	not transmitted, but still written to the local STATUS channels
The control channel itself	still transmitted, provided it is part of the "channels" configuration
Alarms	unaffected
Shared attributes (dashboard → device)	unaffected
RPC	unaffected
Serial number	unaffected

The control channel itself is deliberately exempt from the block, so that the dashboard can tell a deliberate silence from a lost connection. And because the connection stays up, the transmission can be switched back on from the dashboard at any time.

The state of the control channel is evaluated once per acquisition cycle ("pollingIntervalMs"); every change of state is written to the log.

When in doubt, data is transmitted. Transmission stays enabled in all of the following cases:

• the parameter is absent or empty,
• the configured channel does not exist,
• the configured channel is not timestamped or not of data type "bool",
• the channel does not carry a value yet.

A typo in the channel name can therefore not silence a device. The three channel-related cases are written to the log as a warning when the measurement starts.

The typical use case is control from the dashboard by way of a shared attribute:

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

A shared attribute created this way is a timestamped channel of the configured data type and therefore meets the requirements of the control channel. The module itself does not store the state: after a restart, data is transmitted until the control channel carries a value. "persistent" and "requestInitialValue" make the last value set available again.

The control channel does not have to come from the dashboard. A digital input or a calculated channel from the "math" module works just as well; all that is required is a timestamped channel of data type "bool".

Module information

Information	Value
Authors	optiMEAS GmbH
since smartCORE	0
Module type	Consumer, (optional) Producer
Dependencies	optiCLOUD Dashboard