Chapter 13. Using MQTT
Prev Cogent DataHub™ software Next

Chapter 13. Using MQTT

Table of Contents
13.1. Connecting MQTT Clients with the DataHub MQTT Broker
13.2. Making MQTT Client Connections
13.3. MQTT Advanced Parser Tutorial
13.3.1. Example - Part One
13.3.2. Example - Part Two
13.3.3. Example - Part Three
13.4. MQTT Advanced Parser Reference
13.4.1. Overview
13.4.2. Receive Format
13.4.2.1. Testing a Receive Format
13.4.2.2. Script Execution
13.4.2.3. Topic Name Manipulation
13.4.2.4. Initialization Script
13.4.2.5. Parser Script
13.4.3. Common Formulas
13.4.4. Publish Formats
13.4.5. Exporting, Importing and Duplicating Parsers
13.5. Broker $SYS Topics

MQTT is a publish/subscribe messaging protocol. It allows data sources and users called clients to connect to a server called a broker, and exchange their data through it. Clients can act as both publishers and subscribers simultaneously. The DataHub program provides both MQTT client and MQTT broker functionality.

Because it is a messaging protocol, MQTT is different from a data communications protocol. MQTT acts as a data transport layer, similar to TCP, but it does not specify a particular format for the data payload. The message format is specified by a client when it connects. Any clients that want to connect to each other must use the same message format. The broker, of course, must also use that same message format.

13.1. Connecting MQTT Clients with the DataHub MQTT Broker

The DataHub MQTT Broker offers two modes of operation: standard and gateway.

Standard MQTT Broker Mode

In standard MQTT broker mode the DataHub MQTT Broker simply passes messages from one client to another, and the messages remain completely independent of the DataHub program's data set.

To configure the DataHub MQTT Broker as a stand-alone broker, simply select the Do not process messages, just route them option in the Message Content section of the MQTT Broker configuration.

Gateway Broker Mode

In gateway mode you can integrate MQTT messages with the DataHub data set, as normal DataHub data points. Here is how you configure a DataHub instance for each of these modes. There are three options for gateway mode:

  • Binary  messages are Base-64 encoded and stored in DataHub points as strings.

  • Text  messages are interpreted as UTF-8 text stored in DataHub points as strings.

  • JSON  messages get interpreted by the DataHub instance as data point values that can have associated quality, timestamps, and so on.

For more information about these options, please refer to Message Content for the MQTT Broker.

Changing the JSON client message format

The DataHub MQTT Broker's default JSON message format looks like this:

{ "Value": {value}, "Quality": {quality}, 
"Timestamp": {jsontimestamp}, "SenderId": {sender} }

This JSON format allows the DataHub instance to assign an MQTT topic to a data point, and send or receive a value, quality, timestamp, and sender ID for that point. To connect a client that uses a different JSON message format, you need to change this default format for that client's format, as follows:

  1. With a DataHub instance running, right click on the DataHub system-tray icon and choose Properties.

  2. In the Properties window, select MQTT Broker.

  3. In the Message Content section ...

    press the Edit button to open the Configure Parser window:

  • If you know the client message format

    1. In the Per-Point Format field, enter your MQTT client message format.

    2. Click OK and then Apply to save your settings.

    3. Make any other desired changes to the MQTT Broker configuration as described in Section 3.13, “MQTT Broker”.

    The DataHub MQTT Broker is now configured for your MQTT client.

  • If you want to accept any client message

    1. In the Per-Point Format field enter just the string: {value}.

    2. Delete any entries in the Message Start, Per-Point Separator, and Message End fields.

    3. Click OK and then Apply to save your settings. Your Message format should now look like this:

    Now the DataHub instance will accept any client message, parsing it as follows:

    • Numbers without decimal points become integer values.

    • Numbers with decimal points become real values.

    • Everything else becomes a text string.

  • If you want to discover and use the client message format

    If you don't know the client message format, but want to use it as the DataHub MQTT message format, you can use the {value} message format to discover it, as follows:

    1. Ensure that the DataHub MQTT Broker is configured with the {value} message format, as described above.

    2. Start your MQTT client, connect to the MQTT Broker, and send a message. For example, here is a message that is not in the DataHub program's default message format, but can write to the point MQTTBroker:DataPid.PID1.Mv in the DataHub instance.

      [{ "VAL": 33, "TPC": "DataPid/PID1/Mv", "TS": 1548276263.866, 
"QTY": 192, "ID": "" }]

    3. When the DataHub MQTT Broker receives this message, you will be able to see the entire, unparsed string as the value for a point in the Data Browser. The point is in the domain that you have configured for the MQTT Broker.

    4. Click on the point name to display the value in the Enter new value field.

    5. Copy the complete string and paste it into the Per-Point Format field of the Configure Parser window of the DataHub MQTT Broker configuration.

    6. Remove the outer pair of square brackets ( [ and ] ) from the string, and replace the values of the parameters with the placeholder values, like {topic}, {value}, {quality}, etc.

    7. Restore the entries for Message Start ( [ ), Per-Point Separator ( , ), and Message End ( ] ) fields.

    8. Click OK and then Apply to save your settings.

    9. Make any other desired changes to the MQTT Broker configuration as described in Section 3.13, “MQTT Broker”.

    The DataHub MQTT Broker is now configured for your MQTT client. If you push a message from the client with a new value, that value should appear in the Data Browser.

    To make the MQTT connection, use the IP address of the computer running the DataHub instance, and the port that you have configured. The defaults are 1883 for plain text and 8883 for SSL.

    [Note]

    The DataHub MQTT Broker does not support WebSocket connections for MQTT.

Prev Up Next
12.5. ASP File Locations Home 13.2. Making MQTT Client Connections