3.13. MQTT Broker


3.13. MQTT Broker
Prev	Chapter 3. Properties Window	Next

The MQTT Broker option lets you configure the DataHub program as an aggregation and distribution point for MQTT messages from devices and MQTT clients. It can operate as a standard MQTT broker, or as a gateway broker to the DataHub program's data set.

These are the configurable options for the MQTT Broker:

Enable MQTT Broker: This box enables or disables all MQTT Broker functionality.
Plain text connections: Check the box to enable plain text connections, and specify a port. Port 1883 is the MQTT default for plain text.
SSL connections: Check the box to enable SSL connections, and specify a port. Port 8883 is the MQTT default for SSL. If you are using a certificate for SSL connections, you can enter it here. Please see SSL Certificates for more information about SSL certificates in the DataHub program.

Message Content

Here you can set a DataHub instance to act as a standard MQTT broker or a gateway broker.

Standard MQTT broker In this mode the DataHub instance does not interpret MQTT messages and simply distributes them to its clients according to standard MQTT protocol. To select this mode, enable the option Do not process messages, just route them.

Gateway broker In this mode the DataHub instance still performs the role of a standard MQTT broker, while at the same time it interprets the incoming messages, mapping them to DataHub points. Messages from clients produce data changes in all configured DataHub protocols. Changes to data in the DataHub instance result in messages to MQTT subscribers. MQTT clients can participate in control systems as peers with OPC, DDE and DHTP clients and server.

Messages can be interpreted in three ways:

Treat messages as binary Messages are Base-64 encoded and stored in the DataHub instance as strings. They are not processed beyond that. Use this mode if you want the the DataHub instance to put the values into data points based on the MQTT topic name. For example, you could use this mode when the MQTT data is an image.

Treat messages as text Messages are interpreted as UTF-8 text and added to the DataHub instance as point values. No further interpretation is done. Use this mode when the MQTT messages are free-form text or you do not want them to be interpreted further.


	You can use this option to discover the client message format. It will cause the JSON parser to be bypassed, and the client messages to be written as text into the destination topic.

Interpret messages as JSON data point values Messages are expected to be text in JSON format. The DataHub instance can interpret the messages according to a message format you specify. To edit the message format, click the Edit button, which opens the Configure Parser window:
The JSON Path fields at the top show your current entry. To make changes, edit the Message Start, Per-Point Format, Per-Point Separator, and the Message End fields. When you press the OK button your changes will be registered. To make a new entry, such as "PointName", enter a string and the placeholder (like {point} in this example), using the same syntax as the other entries in the Per-Point Format entry field.
The Max message length field allows you to set a maximum number of bytes that the broker will send in an individual message. This setting is only relevant when the broker is interpreting messages, and the message format would allow for multiple point values to be combined into a single MQTT message. This setting will limit the number of point values that will be packed into each message. Do not set this value to be smaller than the expected length of a message containing only one point value.

Unparsed Values

The simplest way to pass an MQTT message is with unparsed values. To configure this in the DataHub instance, the message format must be simply {value}.

For a Simple format, click the Edit button to open the Configure Parser dialog, and ensure that the entry for Per-Point Format is only the string {value} with no extra characters. Also, there should be no entries in the Message Start, Per-Point Separator, and Message End fields.

To see how the {value} message format can be used to connect an MQTT client whose message format you do not know, please refer to Section 13.1, “Connecting MQTT Clients with the DataHub MQTT Broker”.

For Advanced message formats, please see MQTT Advanced Parser in Using MQTT.

Point Names

Place all points in this data domain: You can specify a DataHub domain in which all points related to MQTT topics will be collected.
Convert slash to dot: The MQTT protocol typically uses a slash ( / ) character in hierarchical names, while OPC and other industrial protocols often use a dot ( . ). This option will convert MQTT-style names.
Automatically create point hierarchy: The MQTT protocol supports hierarchical names. This option preserves the hierarchy within the DataHub instance.

Sparkplug

Check the Act as a Sparkplug smart broker box to have the DataHub MQTT broker function as a Sparkplug broker. The broker will interpret Sparkplug messages and may do additional processing as explained below. The broker will continue to act normally for MQTT messages, as configured in the Message Content settings.

The additional processing for Sparkplug includes:

Acts as a Sparkplug 3.0 application, or a Sparkplug 2.2 primary or non-primary application. This will collect all information from EoN devices and expose them as DataHub points. If the smart broker is not set to Read-only then changes to those data points will be transmitted back to the EoN devices.
Monitors the connection status of all EoN devices and changes the associated data point qualities to Not Connected when an EoN device disconnects.
When configured for Sparkplug 2.2, synthesizes a Sparkplug BIRTH message for all currently connected EoN devices whenever a primary or non-primary application connects. This ensures that applications will always be informed of EoN devices, regardless of connection order.
Monitors message sequence numbers from EoN devices. If an out-of-sequence message arrives the smart broker will force the EoN device to disconnect. This will cause the EoN device to reconnect and resynchronize its data.
Monitors writes to the EoN devices. If a write to a device occurs, and no subsequent data arrives from the device for that metric within 5 seconds, the smart broker will force the EoN device to disconnect. This will cause the EoN device to reconnect and resynchronize its data.

Sparkplug version

Choose the version of Sparkplug you are using, 2.2 or 3.0. Configuration is similar for these, with a few differences as mentioned below.

Type

For Sparkplug 2.2, if you already have a primary application in your system, choose Non-primary application here. Otherwise, choose Primary application. Sparkplug 3.0 does not make this distinction, so this option is not needed.

Sparkplug application ID

This is a string that uniquely identifies an application. It is used by Sparkplug EoN clients and monitoring applications to distinguish the on-line state of an application. Normally the application ID should be unique on the broker. Sparkplug 2.2 non-primary applications do not have an application ID.


	Sparkplug identifier strings can contain any valid UTF-8 alphanumeric characters except for the plus sign ( `+` ), forward slash ( `/` ), and number sign ( `#` ).

Data point prefix

An identifier string that will be added to the name of each data point, after the DataHub domain name (if any), and before the group or node name. If the data domain name (specified by Place all points in this data domain) is blank, or the point prefix specified here ends with a colon ( : ) character, then this value will be used as the data domain name for data points derived from Sparkplug data. Sparkplug STATE points are not affected by this option, and will be processed as plain-text MQTT messages.

Live data

Choose whether to process or ignore live data. See the description of Live data in the MQTT Client Sparkplug Application section for more information.

Historical data

Choose whether to process or ignore historical data, or to process it as live data. See the description of Historical data in the MQTT Client Sparkplug Application section for more information.

Detect out-of-order messages

This will allow the DataHub instance to identify out of order or lost messages from an EoN (Edge of Network) device. Should this occur, the DataHub instance will disconnect the device and allow it to reconnect, causing it to re-send its BIRTH (startup) message, and thereby resynchronize all the receiving applications.

Detect failed EoN writes

When a write to an EoN (Edge of Network) device fails, the device will not necessarily retransmit its correct current value. Connected applications will thus not know that the write failed and will reflect an incorrect value. Choosing this option uses a timer to identify that a write request was transmitted, but no subsequent DATA message was received from the EoN device. If so, the DataHub instance will force the EoN device to disconnect, causing it to retransmit its BIRTH message and thereby resynchronize any applications.

Emit EoN BIRTH messages

This feature is only needed for Sparkplug 2.2. It allows the DataHub instance to synthesize a BIRTH message on behalf of an EoN (Edge of Network) device when a new application connects. This causes the newly connected application to synchronize correctly and subsequently receive and process DATA messages from the EoN device. This option works even for non-primary applications that otherwise are unable to synchronize with EoN devices.

Read-only

Checking this box will prevent the smart broker from writing values back to EoN devices and clients.

Options

Require authentication

Forces all client connections to the MQTT Broker's to supply a username and password. Anonymous connections will be rejected. The usernames and passwords for this are created in the DataHub Security option, following the Common Scenario recommendations for TCP or tunnel/mirror connections. The MQTT Broker applies the user’s Read permission when the connection attempts to subscribe to a topic, and applies the user’s Write permission when the connection attempts to write to a topic. All other data permissions are ignored by the MQTT Broker.

If this option is not checked, clients can still supply a username and password and read/write permissions will be enforced. Anonymous connections will receive both read and write permissions.


	Cogent DataHub users: When the broker is running from a single domain, permissions are applied to the whole broker domain. When the broker is exposing all domains, permissions are applied on a per-domain basis.

Mark data as Not Connected when client disconnects

When the DataHub Broker is running in gateway mode it writes the values of MQTT messages into DataHub data points, with Good quality. If an MQTT client disconnects from the broker then this option will cause the broker to change the qualities of every point originating from that client to Not Connected, indicating that the client is no longer connected and the value of the data point is not necessarily up to date. This option applies only to those points whose values were updated by the client during the time it was connected.

Overflow Management

When the broker receives messages more quickly than clients can accept them, it stores the messages in queues, one per client. Here you can manage overflows in those queues.

Maximum per-client message queue length: Set a limit for the maximum number of outstanding messages that are queued per client. The default queue length is zero, no limit. This causes the Broker to use its own smart queue management based on the recipient's data ingestion rate.


	In DataHub v10, the MQTT broker would always send all QoS 0 retained messages in response to a subscription, regardless of this setting. In DataHub v11, the Broker respects the queue length setting. This may result in unexpected loss of retained topic information when the client initially connects. To restore the behaviour of v10, set the Maximum per-client message queue length to zero.

Prev	Up	Next
3.12.3.4. Sparkplug	Home	3.14. Modbus