Additional information for software release
moneo edgeConnect MQTT adapter
Release 1.10.1: No Changes
1.1
Purpose of moneo MQTT adapter
The purpose of the moneo edgeConnect MQTT adapter is to allow a moneo user to easily transmit
process data from selected data sources to one or more MQTT 3.1.1 compliant brokers running in the
environment. Consuming users or applications will then be able to connect to such an MQTT broker
and subscribe to all or some of the data source that are published by moneo.
This is a standard function of moneo|OS and will be available whenever a moneo|OS license is active.
Figure 1 schematic overview of MQTT communication
Caveat: In order for this function to work, the MQTT broker must be accessible by moneo. There are
multiple protocol options available and depending on their choice, the respective protocols and
network destinations must be reachable via an outbound connection.
1.2
Setting up an MQTT broker connection in moneo
In order to connect to an MQTT broker, a target system of type Custom MQTT Broker must be
added. This is done via the Add new target button in the Target Systems tab of the edgeConnect
main screen. This screen can always be reached by clicking the EdgeConnect tile on the moneo
Home screen.
Figure 2 adding an MQTT target system
moneo edgeConnect MQTT adapter_en 1.10.1
1/4
2022-09-14
Additional information for software release
After choosing the Custom MQTT Broker option, a configuration dialog will appear that allows to set
up the broker connection and give a name for the newly generated target system.
Figure 3 example for configuring an MQTT broker
The individual parameters are:
• Label: a display name for the target system that later identifies it in the data source mapping
page
• Host: the host name or IP address of the MQTT broker
• Client Id: the MQTT client ID. It is pre filled with the moneo tenant identifier but can be
changed by the user. It is used to identify the connection for the broker and it serves as a
hierarchy level in the MQTT topic structure
• Topic prefix: this string is prepended to the MQTT topics that moneo uses to publish process
data to. It is empty by default, but can be used for example to add a topic hierarchy level in
front of the one built from the client ID. In this case, it should end in a “/” (MQTT topic
hierarchy separator)
• Port: the MQTT port provided by the broker. If empty, the standard port for the chosen
protocol is used (as displayed in the URL text box automatically generated from the
connection parameters)
• TLS (yes/no): use TLS for authentication and transport layer encryption
• WebSockets (yes/no): use WebSockets instead of raw TCP. This is useful to connect via an
http proxy (configured elsewhere in moneo)
• User name (only if Use authentication is checked): the MQTT user name provided by the
broker, if no anonymous connection is intended
• Password (only if Use authentication is checked): the MQTT password provided by the
broker, if no anonymous connection is intended
After saving the configuration, moneo attempts to connect to the broker to validate the settings, but no
process data is transmitted yet. A row is added to the Target Systems tab with Status indicating the
outcome of the connectivity check. When hovering over the row, you will see buttons that allow you to
Edit or Delete the target system or to Validate the connectivity again.
Figure 4 the target systems list displaying the added MQTT target system
1.3
Mapping of moneo data sources
Publication of moneo process data on a MQTT broker is configured in the edgeConnect Data
Management tab on a per-data-source basis. On the right hand side, a mapping table provides a
column for each configured target system and a row for each data source that is available in the
moneo Navigator. In addition to the target systems columns, there are two columns identifying the
data sources. In Source, you see a path representation of the data source in the moneo Navigator. In
Datasource path, you additionally see the physical path as given in moneo device management. For
moneo edgeConnect MQTT adapter_en 1.10.1
2/4
2022-09-14
Additional information for software release
most target systems, this physical path is the preferred basis for addressing the destination of process
data for each data source. In the case of MQTT, it is used to build the MQTT topics used when
publishing a stream of process data messages for each data source.
On the left hand side of the Data Management tab, the Navigator is available and allows to filter the
mapping table by clicking on the desired subtree node.
For each combination of data source and target system, process data transmission can be started and
stopped individually via a toggle button. In order for process data to flow, the data source must
additionally be activated in moneo Navigator. moneo is publishing process data as soon as it arrives.
Figure 5 mapping data sources to target systems
1.4
MQTT information model
MQTT allows senders (publishers) and receivers (subscribers) to communicate with each other via
messages. In order to do so, they must both be connected to the same MQTT broker. Each message
is posted to a so called topic defined by the publisher, while each subscriber can subscribe to an
individual topic or a topic wildcard pattern (“#”, for example). The “/” character is used as a topic
hierarchy separator, so it is common that publishers and subscribers agree on a common tree-like
topic structure. MQTT does not make any assumptions about the structure of the message content
(payload) itself (see chapter 1.5).
In moneo, the message content is UTF8 encoded JSON, while the topic structure is based on the
moneo physical topology displayed in the data source mapping table. The following examples show
the detailed structure for the example of an IO-Link master and sensor. Other device types (like VSE,
etc.) might differ slightly in the meaning of the topic hierarchy levels.
Sample moneo MQTT message topic:
moneo/c2818e07-4c09-42f0-ba24-ddb712573ab5/AL1352/192168221/80/X03/VVB001StatusB/Crest
hierarchy levels from left to right:
• topic prefix: moneo
• client ID: c2818e07-4c09-42f0-ba24-ddb712573ab5
• top level device type (IO-Link master): AL1352
• top level device IP address (without dots): 192168221
• top level devices IP port: 80
• subdevice (sensor) IO-Link port: X03
• subdevice (sensor) type: VVB001StatusB
• data source name: Crest
• (Additional note: moneo calculated data sources are provided under the top level device type
suitevdevice and not under Calculated Values as shown in the data source path)
moneo edgeConnect MQTT adapter_en 1.10.1
3/4
2022-09-14
Additional information for software release
Sample moneo MQTT message payload:
[
{
"tid":"5e4bac9f-b47a-499e-8601-68fc16a9847c",
"psid":"Crest",
"devicePath":"c2818e07-4c09-42f0-ba24-ddb712573ab5_AL1352_192168221_80_X03_VVB001StatusB_Crest",
"processDataUnit":"",
"values":[
{
"value":4.6,
"timestamp":1648562285347
}
]
}
]
JSON properties from top to bottom:
• tid: internal moneo thing ID
• psid: data source name
• devicePath: physical path of device (~ MQTT topic)
• processDataUnit: physical unit of process vaule
• values: array of one or many process values
• value: numeric process value
• timestamp: UTC timestamp for process value; UNIX time in ms
Figure 6 moneo process data in generic MQTT client
Changing the display unit of a data source in moneo Device Management has no effect on the MQTT
message payload. The processDataUnit and value are displayed in the original measurement unit as
delivered by the device.
1.5
Further info
1. Introduction to MQTT by HiveMQ: https://www.hivemq.com/mqtt/mqtt-protocol/
2. Freely available MQTT client (used for screenshot): http://mqtt-explorer.com/
moneo edgeConnect MQTT adapter_en 1.10.1
4/4
2022-09-14