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:

Name	Description
UInt8	Unsigned Integer 8 bits
UInt16	Unsigned Integer 16 bits
UInt32	Unsigned Integer 32 bits
Int8	Signed Integer 8 bits
Int16	Signed Integer 16 bits
Int32	Signed Integer 32 bits
Float	Floating number
Double	Floating double-precision number
String	ASCII value (text string)

Protocol Parameters#

The protocol supports the following parameters:

Name	Type	Possible Values	Default Value	Description
address	String			Address of MQTT broker
port	Integer		1883	Port of MQTT broker
user	String			Login Username
password	String			Login Password
pollInterval	Integer		2000	Time between variable polling when no change value notification is available. Only used in events. (milliseconds)
byteOrder	Enum	BigEndian LittleEndian	BigEndian	Byte order of the data of the message
Convert Non Printable ASCII Chars On Send	Boolean		False	Does character substitution on values sent. Replaces ASCII name tokens with the correspondent ASCII value.(e.g.: <NUL> to #00, ..., <DEL> to #127, on command values)
Convert Non Printable ASCII Chars On Receive	Boolean		False	Does character substitution on values received. Replaces non printable ascii codes to correspondent <NAME>.(e.g.: #00 to <NUL>, #01 to <SOH>,...,#7F to <DEL>)

Extended Parameters#

Property#

Name	Type	Possible Values	Default Value	Description
identifierType	Enum	None RegularExpression Token	None	Method used to identify a property. Must be one of: `None`, `RegularExpression` or `Token`. If `None` is used, `Identifier Value` will be ignored and all messages will update that property. `Token` type will match the `Identifier Value` text only on the beginning of the message and `RegularExpression` will match on configured Regular Expression `Identifier Value` field.
identifierValue	String			Value of the Property Identifier. Valid on `RegularExpression` or `Token` Identifier Type. Non printable ASCII character may be converted if `Convert Non Printable ASCII Chars on Identifiers` option is used
Convert Identifier Non Printable ASCII Chars				Replaces non printable ascii codes with <NAME> to correspondent ascii code (e.g., <NULL> to #0, <SOH> to #1, <STX> to #2, ..., <US> to #31, <DEL> to #127
QoS	Enum	0 1 2	0	MQTT Quality of Service. MQTT provides three levels of QoS:At most once (QoS 0), At least once (QoS 1) or Exactly once (QoS 2)
Retain	Boolean		false	A retained message is a normal MQTT message with the retained flag set to true. The broker stores the last retained message and the corresponding QoS for that topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message immediately after they subscribe.

Event#

Name	Type	Possible Values	Default Value	Description
triggerMode	Enum	Always OnChange OnInterval	Always	Data can be published (event based): `Always`: every time the trigger property value is received `OnChange`: every time a different trigger property value is received `OnInterval`: On a periodic basis (every periodic interval, in milliseconds), disregarding property update cycles or values
interval	Integer		1000	Number of milliseconds to publish data. Only valid on triggerMode `OnInterval`

Event Property#

Name	Type	Possible Values	Default Value	Description
isTrigger	Boolean		true	Trigger the event when the property is received (event triggerMode `Always`), or when the value is changed (event triggerMode `OnChange`)

Remarks/Behavior#

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/+

Command#

Not Applicable

Command Parameters#

Not Applicable

Non Printable ASCII Chars - Token/Value Substitution#

token	value	token	value	token	value	token	value	token	value
<NUL>	0	<SOH>	1	<STX>	2	<ETX>	3	<EOT>	4
<ENQ>	5	<ACK>	6	<BEL>	7	<BS>	8	<TAB>	9
<LF>	10	<VT>	11	<FF>	12	<CR>	13	<SO>	14
<SI>	15	<DLE>	16	<DC1>	17	<DC2>	18	<DC3>	19
<DC4>	20	<NAK>	21	<SYN>	22	<ETB>	23	<CAN>	24
<EM>	25	<SUB>	26	<ESC>	27	<FS>	28	<GS>	29
<RS>	30	<US>	31	<DEL>	127

Methods#

Get Properties Values#

Requests the server for the values of one or more properties

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.

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.

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

Note

The events will be published to the listeners connect.iot.driver.template.registerEvent appended with the name of the event registered and a random id. Example: connect.iot.driver.template.registerEvent.test

Example#

{
   "event":{
      "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.

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

Example#

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