MQTT Client Connector
This connector provides MQTT publish and subscription functionality to an external MQTT Broker.
Config
Enabling
The default path to the PCCCEIP connector is Omniview.Connectors.MQTTClient.dll
Add the following entry to the <Connectors> section in the Syscon.xml config file.
<Connector Name="MQTTClient" Connector="Omniview.Connectors.MQTTClient.dll" Enabled="true"/>
Parameters
| Name | Descrption |
|---|---|
| Name | A unique name for the protocol. Used to refer to the protocol in the device config |
| Connector | The path to the connector. Paths are relative to the Connectors/ directiory within the OVSS |
| Enabled | Set to "true" or "false" to control whether the connector should be loaded and enabled |
Configuring a Device
To configure a device using the MQTTClient connector add an entry to the <Devices> section in the relevant Syscon Data Server config.
<Device Name = "Lora_Gateway" Protocol="MQTTClient" Priority ="1">
<Address>10.0.0.2</Address>
<Special Name="ScanTime" Value="500"/>
<Special Name="ReconnectDelay" Value = "10"/>
</Device>
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| Name | String | A unique name for the device. Used to refer to the device in the tag config | None |
| Protocol | String | The name given to the protocol in the Connector configuration | None |
| Priority | Integer | The priority of the connection to be used in redundant configurations. Lower priorities take precedence over higher priorities when connection failover occurs | 1 |
| Address | String | Specify the network address of the MQTT Broker in the format xxxx.xxxx.xxxx.xxxxx:port. The port is optional and if omitted the default port of 1883 for unencrypted connections or 8883 for encrypted connections will be used | None |
| ScanTime | Integer | The default scan time in milliseconds assigned to tags | 1000 |
| ReconnectDelay | Integer | The minimum time in seconds to wait before initiating a reconnect | 30 |
| ReadTimeout | Integer | The maximum time in milliseconds to wait for a response from the controller | 500 |
| Authentication | String | How the connection should be authorised. Credentials : use the username and password parameters. Certificate: use the certificate parameter. | Credentials |
| Username | String | Username to use for Credentials Authentication | Null |
| Password | String | Password to use for Credentials Authentication | Null |
| ProtocolVersion | String | MQTT Protocol Version V310: 3.1.0 V311: 3.1.1 V500: 5.0.0 | V311 |
| UseTls | Bool | Should TLS be used | True |
| TlsVersion | String | Version of TLS that should be enforced Tls11: TLS 1.1 Tls12: TLS 1.2 Tls13: TLS 1.3 | Tls12 |
| TlsCertificate | String | Use a specific certificate for TLS. This will be determined by the MQTT Broker | Null |
| QoS | Integer | Global Quality of Service. Quality of service can also be defined on a per tag basis 0 : At most once 1 : At least once 2 : Exactly once | 0 |
| CacheTimeout | Integer | Time in milliseconds to retain the last message. Quality of values in the cache will be updated to Old upon timeout. Values less than or equal to 0 will disable the cache timeout. | 0 |
Logging
By default Omniview is setup to log all error messages. To obtain further log messages from this connector the following base logger names can be used. It is recommended that * be prepended and appended to logger names to capture all instances of the logger where instances are delineated by additional information embedded in the logger name. For example *MQTT* will log all instances of the logs with MQTT in the logger name, to log only a specific instance the exact name can be used.
| Name | Descirption |
|---|---|
| Omniview.Connector.MQTTClient | Log messages from the Connector interface |
Addressing
The connector expects addresses to be in the format {topic}::{path}. The topic can be any valid MQTT topic as detailed in the Topics section.
| Payload | Path | Example | Description |
|---|---|---|---|
| Any | Empty | {topic}:: | Returns a UTF8 string encoding of the payload |
| Any | $raw | {topic}::$raw | Returns the raw payload as a byte array |
| JSON | {key}.{key n} | {topic}::{key}.{key n} | The payload is in JSON format. The Path to the required value should be the Key inside the JSON data. Nested objects can be mapped by specifying the required keys separated by a period (.) |
Topics
In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client. The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator).
Topic semantic and usage
The following rules apply to Topic Names and Topic Filters:
All Topic Names and Topic Filters MUST be at least one character long
Topic Names and Topic Filters are case sensitive
Topic Names and Topic Filters can include the space character
A leading or trailing ‘/’ creates a distinct Topic Name or Topic Filter
A Topic Name or Topic Filter consisting only of the ‘/’ character is valid
Topic Names and Topic Filters MUST NOT include the null character (Unicode U+0000)
Topic Names and Topic Filters are UTF-8 Encoded Strings; they MUST NOT encode to more than 65,535 bytes
There is no limit to the number of levels in a Topic Name or Topic Filter, other than that imposed by the overall length of a UTF-8 Encoded String.
Topic level separator
The forward slash (‘/’ U+002F) is used to separate each level within a topic tree and provide a hierarchical structure to the Topic Names. The use of the topic level separator is significant when either of the two wildcard characters is encountered in Topic Filters specified by subscribing Clients. Topic level separators can appear anywhere in a Topic Filter or Topic Name. Adjacent Topic level separators indicate a zero-length topic level.
Topic wildcards
The topic level separator is used to introduce structure into the Topic Name. If present, it divides the Topic Name into multiple “topic levels”.
A subscription’s Topic Filter can contain special wildcard characters, which allow a Client to subscribe to multiple topics at once.
The wildcard characters can be used in Topic Filters, but MUST NOT be used within a Topic Name
Multi-level wildcard
The number sign (‘#’ U+0023) is a wildcard character that matches any number of levels within a topic. The multi-level wildcard represents the parent and any number of child levels. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic Filter
For example, if a Client subscribes to “sport/tennis/player1/#”, it would receive messages published using these Topic Names:
“sport/tennis/player1”
“sport/tennis/player1/ranking
“sport/tennis/player1/score/wimbledon”
“sport/#” also matches the singular “sport”, since # includes the parent level.
“#” is valid and will receive every Application Message
“sport/tennis/#” is valid
“sport/tennis#” is not valid
“sport/tennis/#/ranking” is not valid
Single-level wildcard
The plus sign (‘+’ U+002B) is a wildcard character that matches only one topic level.
The single-level wildcard can be used at any level in the Topic Filter, including first and last levels. Where it is used, it MUST occupy an entire level of the filter. It can be used at more than one level in the Topic Filter and can be used in conjunction with the multi-level wildcard.
For example, “sport/tennis/+” matches “sport/tennis/player1” and “sport/tennis/player2”, but not “sport/tennis/player1/ranking”. Also, because the single-level wildcard matches only a single level, “sport/+” does not match “sport” but it does match “sport/”.
“+” is valid
“+/tennis/#” is valid
“sport+” is not valid
“sport/+/player1” is valid
“/finance” matches “+/+” and “/+”, but not “+”
Topics beginning with $
The Server MUST NOT match Topic Filters starting with a wildcard character (# or +) with Topic Names beginning with a $ character. The Server SHOULD prevent Clients from using such Topic Names to exchange messages with other Clients. Server implementations MAY use Topic Names that start with a leading $ character for other purposes.
$SYS/ has been widely adopted as a prefix to topics that contain Server-specific information or control APIs
Applications cannot use a topic with a leading $ character for their own purposes
A subscription to “#” will not receive any messages published to a topic beginning with a $
A subscription to “+/monitor/Clients” will not receive any messages published to “$SYS/monitor/Clients”
A subscription to “$SYS/#” will receive messages published to topics beginning with “$SYS/”
A subscription to “$SYS/monitor/+” will receive messages published to “$SYS/monitor/Clients”
For a Client to receive messages from topics that begin with $SYS/ and from topics that don’t begin with a $, it has to subscribe to both “#” and “$SYS/#”