MQTT Config Reference

Below is a comprehensive list of each configuration option on the MQTT driver with its default, a description of its purpose and what effect it will have.

The driver options are set on the Drivers screen. The options a tag uses to subscribe to a topic are set per tag on the Tags screen, and are listed under Subscriber tag properties. The MQTT broker built into the OAS engine is configured on the Options screen, not on the driver, and has its own page: MQTT Broker.

Minimum configuration requirements

These are the fields that need a value before the driver will do anything. Everything else has a working default.

Driver interface

Connection

TLS

The certificate fields are shown when TLS is on. Which of them are shown depends on Create Certificate: on, the certificate is given as separate certificate and private key files; off, it is given as a PFX file and its password.

Message format New

Shown when Publish Selected Tags is on.

The schemas that Load from library... offers in that dialog are kept in the Message Schemas section of the Options screen, which the MQTT broker also uses - see Message Schemas.

Publishing

Publishing is off until Publish Selected Tags is turned on. A driver interface with it off only subscribes.

Topic patterns New

With Publish All Tags As One Topic on, Publish Topic Id can hold message variables in braces, so one driver interface publishes to many topics. Each tag goes to the topic the pattern gives it, and the tags of one publish that share a topic share a message. This works with every Output Format.

• A variable that changes with every value or every message - {value}, {quality}, the timestamps, {uuid} and the others the variable tables mark - cannot be used in a topic.
• Text in braces that is not a variable is kept as written. To keep a variable name as text, double its braces: data/{{site}} publishes on data/{site}.
• A tag whose topic comes out empty, contains + or #, or has no value for a variable in it, is not published, and System Errors gets one entry for it.
• Topics are worked out again once a minute, so a renamed group or a changed property reaches the topic without a restart.

Topic preview

The line under Publish Topic Id in the web app checks the text as you type:

• Topic pattern. or One topic. says which the text is, with an example topic.
• Insert a variable… adds a variable at the cursor.
• Try a tag… picks a tag and shows the topic it would get. Try another tag… picks a different one.
• Not published: … says why the tag tried would not be published.
• A warning names any text in braces that is not a variable, which is published as written, and any variable that changes with every value or message, which a topic may not use.

A tag with several Ids New

Tags To Publish can list the same tag more than once, each time with a different Id. The driver publishes the tag under every Id:

With a tag map keyed by something other than the Id, while another field reads it, both Ids give the same key: the last Id is kept, and System Errors notes it once.

Payload field names

These name the fields inside a Default format message. They do not apply to ISA-95 Lite or Custom AVRO Schema, where the schema's field mapping sets the names, the quality and the timestamps.

Payload examples

With the defaults, every tag is published to the one topic named by Publish Topic Id.

Topic: oas_tags

{
    "values": [
        {
            "id": "Ramp",
            "value": 39,
            "quality": true,
            "timestamp": "2022-03-21T08:55:39.000Z"
        },
        {
            "id": "Sine",
            "value": 0.8090169943749475,
            "quality": true,
            "timestamp": "2022-03-21T08:55:39.000Z"
        },
        {
            "id": "Random",
            "value": 10,
            "quality": true,
            "timestamp": "2022-03-21T08:55:39.000Z"
        }
    ]
}

With Publish Latest Value Only off the message has the same shape, but carries every value change since the last publish, so a tag that changed twice appears twice.

With Publish All Tags As One Topic off, each tag is published to a topic of its own, named by its Id.

Topic: Ramp

{
    "value": 35,
    "quality": true,
    "timestamp": "2022-03-21T09:07:15.000Z"
}

Topic: Sine

{
    "value": -1,
    "quality": true,
    "timestamp": "2022-03-21T09:07:15.000Z"
}

Store and Forward

Failover

Shown when Enable Failover is on. These describe a second broker, with its own address, credentials and certificates, that the driver moves to when the primary broker fails.

Communication status

Each of these sets a Boolean tag from the state of the driver interface. Turning one on shows the field that names the tag: Comm Bad Tag, Comm Good Tag or Comm Buffering Tag.

Subscriber tag properties

A tag subscribes to a topic through its own properties on the Tags screen, not through the driver.

Troubleshooting

Where next

• Getting Started with MQTT - these options in a working configuration.
• MQTT How-To guides - logging, transferring and routing MQTT data.
• Message Schemas - the schema library and the Edit AVRO schema dialog.
• Message Variables - every variable a topic pattern or a schema can use.