Connect IoT - MQTT Driver#

MQTT is a machine-to-machine (M2M)/Internet of Things connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport.

Data Types#

These are the supported specific data types:

Protocol Parameters#

The protocol supports the following parameters:

Extended Parameters#

Property#

Event#

Event Property#

Remarks/Behavior#

• The protocolVersion parameter selects only the protocol level negotiated with the broker. Subscribe, publish, QoS, retained messages, wildcards, and MQTT or MQTTS with CA validation and mutual TLS work the same under 3.1.1 and 5.0. Advanced MQTT 5.0 features, such as user properties, topic aliases, response topics, and subscription identifiers, are not available. Where a payload needs metadata, carry it in the message itself.
• The driver writes the selected protocol version to the log when connecting. If the broker refuses that version, the connection fails with the reason given by the broker and the driver keeps retrying.
• Communication parameters are sent to the driver only while it is not communicating, so changing the protocol version on a running instance requires restarting it.
• Each connection is opened as a clean session, so the broker keeps no subscription state for the driver between connections. Subscriptions are re-established on every reconnect.

• When an event has more than one property with the isTrigger flag:

  • It will be triggered every time any of the properties value changes.
  • The value of the other properties will be requested at that time.
  • It is possible to have multiple triggers with the same set values (because they have not changed). If this behavior is not intended, separate into multiple events each one with its own trigger set.

• When an event has no property with the isTrigger flag, it will never be triggered (unless event is defined as Periodic)

• Original value now returns topic and data in the following format: { "topic": "<topic_name>", "value": <raw_value> }

• We allow the MQTT wildcards:

  • # - can be used as a wildcard for all remaining levels of hierarchy. This means that it must be the final character in a subscription. For example: sensors/#
  • + - can be used as a wildcard for a single level of hierarchy. For example: sensors/+/temperature/+

• A property whose topic is # alone, or starts with $, never matches a received message.

• The driver subscribes to the topics of the readable properties when the setup completes. A property read during the setup has no value, and a message published before then is received only if the broker retained it.
• When messages on several topics that match one wildcard property arrive within a few milliseconds, an event occurrence can carry the value and the topic of a later message. Some of those messages are then never reported with their own value.
• Writing a readable property publishes to a topic that the driver also subscribes to, so the broker delivers the written value back to the driver as a received message, which can trigger events.
• When a property has identifierType Token or RegularExpression and the written value does not match identifierValue, the driver publishes nothing and logs an error, and the write still reports success.

Command#

• Not Applicable

Command Parameters#

• Not Applicable

Non Printable ASCII Chars - Token/Value Substitution#

Driver Extensions#

This protocol driver provides a set of extension that allow the customization to perform actions that are independent of the Driver Definitions associated. This means you can, using customization, get/set node values without needing to describe them.

This is particularly useful when accessing equipment data that is shared/too complex to access using the regular mechanisms. Also useful when needing to access data whose naming convention may vary from device to device.

Objects#

The objects are structures that are either passed as parameters or returned as result values.

Event#

Property#

PropertyValue#

PropertyValuePair#

RegisterHandler#

UnregisterHandler#

Methods#

Get Properties Values#

Requests the server for the values of one or more properties

Signature

PropertyValue[] connect.iot.driver.template.getProperties(request Property[])

Example

Request connect.iot.driver.template.getProperties

[
  {
    "name": "test1",
    "deviceId": "production/something",
    "dataType": "String",
    "isWritable": true,
    "isReadable": true,
    "deviceType": "String",
    "extendedData": { "propertyType": "", "defaultValue": "defaultP1" }
  },
  {
    "name": "test2",
    "deviceId": "production/otherthing",
    "dataType": "String",
    "isWritable": true,
    "isReadable": true,
    "deviceType": "String",
    "extendedData": { "propertyType": "", "defaultValue": "defaultP2" }
  }
]

Reply:

[
  {
    "propertyName": "test1",
    "originalValue": {
        "topic": "production/something",
        "value": <Buffer>,
    },
    "value": "defaultP1",
  },
  {
    "propertyName": "test2",
    "originalValue": {
        "topic": "production/otherthing",
        "value": <Buffer>,
    },
    "value": "defaultP2",
  }
]

Set Property Values#

Requests the server to define the values of one or more properties.

Signature

boolean connect.iot.driver.template.setProperties(request PropertyValuePair[])

Example

Request connect.iot.driver.template.setProperties

[
  {
    {
    "property": {
        "name": "test",
        "deviceId": "production/something",
        "dataType": "String",
        "isWritable": true,
        "isReadable": true,
        "deviceType": "String",
        "extendedData": { }
    },
    "value": "testValue"
  },
  {
    {
    "property": {
        "name": "test2",
        "deviceId": "production/otherthing",
        "dataType": "String",
        "isWritable": true,
        "isReadable": true,
        "deviceType": "String",
        "extendedData": { }
    },
    "value": "testValue2"
  }
]

Reply:

true

Register Event#

Notifies the protocol driver to raise the occurrences of a specific event when it occurs.

Signature

void connect.iot.driver.template.registerEvent(data: Event)

Example

{
      "name":"CustomEvent",
      "isEnabled":true,
      "properties":[
         {
            "name":"property1",
            "deviceId":"production/property1",
            "dataType":"String",
            "deviceType":"String",
            "extendedData":{
               "isTrigger":true
            }
         }
      ]
}

Unregister Event#

Notifies the protocol driver to stop raising the occurrences of a specific event when they occur.

Signature

void connect.iot.driver.template.unregisterEvent(data: UnregisterHandler)

Example

{
   "event":{
      "name":"CustomEvent"
   }
}