MQTT module "mqtt"

Description

The MQTT module is used for communication with an MQTT broker in both directions.

Several smartCORE channels can be assigned to one MQTT topic, whereby the module enables the selection of several topics.

In addition, several modules can be instantiated in order to be able to communicate with several different brokers at the same time.

With regard to the interpretation and preparation of MQTT payloads, so-called payload hints are supported, which serve to describe the format.

In the publication direction, these are used to perform a syntax check of the publication templates into which consumed channel values are then inserted (e.g. for common formats such as JSON, XML, ...).

Conversely, these payload hints in the subscribe direction serve to provide suitable data extraction mechanisms for the above-mentioned formats, so that the extracted values can be produced in the corresponding smartCORE channels.

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 and typical)

The following is a minimal example configuration:

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

          <MQTT TOPIC CONFIGURATIONS>

        ]
      }
    }

Example configuration (maximum)

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

        ]
      }
    }

Examples of JSON objects for topic configuration...

The following JSON objects can be inserted into the above array of topics.

...in the direction of publication

The strings listed under mqttName serve as placeholders, which are replaced 1:1 by the values of the smartCORE channels listed under 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 subscription direction

The strings listed under mqttName describe how channel data is to be extracted from the MQTT payload, which is possible in different ways (see below).

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

Module parameters

Parameter name	Required	Data type	Meaningful value range	Default	Description
useLocalBroker	No	BOOL	true, false	false	Start MQTT Broker on the device and communicate with it
enabled	No	BOOL	true, false	true	Activity of the communication to the broker
pollingIntervalMs	No	INT	1 -	1000	Module-related processing interval [ms]
brokerAddress	No	STRING	valid broker URL		"ssl://awe.some.io:8883" , "tcp://awe.some.io:1883" (not recommended)
brokerAuthentication	No	BOOL	true, false	true	Broker authentication
trustStore	No	STRING		/etc/ssl/certs/ca-certificates.crt	Trust Store for broker authentication
brokerUserId	No	STRING			Broker user ID
brokerUserPassword	No	STRING			Broker user password
brokerClientId	No	STRING			Broker client/device identifier
maxBufferedMessages	No	INT	1 -	10	Maximum number of buffered MQTT messages within the MQTT client
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
topics	YES	JSON Array			see MQTT Topic Configuration

MQTT topic configuration "topics"

A distinction is made between published and subscribed topics.

Topics to be published (published topics)

A topic to be published, which generally contains a selection of smartCORE channels, is configured as a JSON object containing the following parameters.

Parameter Name	Required	Data Type	Meaningful Value Range	Default	Description
name	YES	STRING			Name/path of the topic on the broker
direction	YES	STRING	"publish"		set to "publish" for a topic to be published
payload	YES	STRING			payload template
payloadHint	YES	STRING	"plain", "json"	"json"	Selection of the payload format to be transmitted with regard to which a syntax check of the payload template is performed, if this is possible
channels	YES	JSON array			see below

The channel configuration of channels to be published takes the form of a JSON array containing JSON objects with the following parameters.

Parameter Name	Required	Data Type	Meaningful Value Range	Default	Description
channelName	YES	STRING			Name of the smartCORE channel to be consumed
mqttName	YES	STRING			substring within the payload template, which is replaced with a string representation of the current channel value.
format	NO	STRING			Formatting instruction regarding conversion of the channel value to string
translateFalse	NO	STRING		"false"	String representation of the Boolean value for false
translateTrue	NO	STRING		"true"	String representation of the Boolean value for true

Topics to be subscribed to (subscribed topics)

A topic to be subscribed to, which generally provides a selection of smartCORE channels, is configured as a JSON object containing the following parameters.

Parameter Name	Required	Data Type	Meaningful Value Range	Default	Description
name	YES	STRING			Name/path of the topic on the broker
direction	YES	STRING	"subscribe"		to be set to "subscribe" for a topic to be subscribed to
payloadHint	YES	STRING	"plain", "json"	"json"	Selection of the payload format to be received for data extraction into configured channels.
channels	YES	JSON array			see below

The channel configuration of channels to be published takes the form of a JSON array containing JSON objects with the following parameters.

Parameter name	Required	Data type	Meaningful value range	Default	Description
channelName	YES	STRING			Name of the smartCORE channel to be produced
dataType	YES	STRING	valid smartCORE data type		data type of the channel
bufferSize	NO	INT	1 -	1024	Buffer size of the channel
physicalUnit	NO	STRING			Physical unit of the channel
mqttName	YES	STRING			String that describes an instruction for extracting individual channel values from a payload (e.g. a path specification for JSON payloads)
translateFalse	NO	STRING		"false"	String representation of the Boolean value for false
translateTrue	NO	STRING		"true"	String representation of the Boolean value for true

Payload content-related special features

Direct 1:1 data extraction (payloadHint "plain")

The entire content of the payload is used as the channel value in the subscription direction (subscribe). An automatic error-tolerant conversion to the target data type is carried out as far as this is possible. Conversely, there is no syntax check in the publication direction.

JSON (payloadHint "json")

To extract channel data from a subscribed topic with a JSON-formatted payload, a path can be used as the "mqttName" parameter.

Example: If the received payload contains the following JSON object.

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

then "mqttName": "someObject/someSubObject\/with\/slash/someKey" extracts the value 42, which is then produced in the channel defined as "channelName" (i.e. it is necessary to escape the separator "/").

Accordingly, "mqttName": "someArray/1" extracts the value 2 from the above-mentioned JSON object (i.e. in the case of a JSON array, the path component is used as the index).

If several separators "/" are specified in succession, they are regarded as a single separator.

If an invalid path is specified, no channel data is produced in any case.

Module information

Information	Value
Authors	optiMEAS Measurement and Automation Systems GmbH
since smartCORE	2.6
module type	either consumer, producer or both
Dependencies	existing MQTT broker