---
alias: user-guide-driver-mqtt
tags:
- connect iot
description: "This documentation details the MQTT Driver for IoT device connectivity, outlining data types, protocol parameters, and event handling mechanisms"
---
# 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 |
| protocol | Enum | MQTT
MQTTS | MQTT | The protocol used for connecting to the MQTT broker. |
| protocolVersion | Enum | 3.1.1
5.0 | 3.1.1 | MQTT protocol version used to connect to the broker. Configurations created before this parameter existed have no value and use 3.1.1. |
| user | String | | | Login Username |
| password | Password | | | Login Password |
| certificate | Text | | | Client identity certificate used to authenticate the MQTT client to the broker. Accepts a file path or PEM-formatted content. |
| privateKey | Text | | | Private key associated with the client identity certificate. Accepts a file path or PEM-formatted content. |
| certificateAuthority | Text | | | Specifies the trusted Certificate Authority (CA) certificates used for SSL/TLS server certificate validation. Accepts a file path or PEM-formatted certificate content. |
| pollInterval | Integer | | 2000 | Not used by the driver. To raise an event periodically, set the event's `triggerMode` to `OnInterval`. (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 | Boolean | | false | Replaces non printable ascii codes with <NAME> to correspondent ascii code (for example, <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
* 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": "", "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
| 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 | | | | |
## Driver Extensions
{% include-markdown 'includes/pages/iot_driver_extensions_deprecated.md' %}
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
| Name | Type | Description |
| ---------- | ------------ | ------------------------------------------------------------------- |
| name | String | Name of the event. Will be used as identifier in the result calls. |
| isEnabled | Boolean | Is the event enabled and ready to be used? Default `false` |
| properties | `Property`[] | List of properties to link with the event |
#### Property
| Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| name | String | Name of the property. Will be used as identifier in the result calls. |
| deviceId | String | Topic to subscribe/publish on the MQTT broker. |
| deviceType | String | Data type as known by the broker. Must use one from the supported Data Types of this protocol driver. |
| dataType | String | Data Type of the value as known/used by the MES/System. |
#### PropertyValue
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| propertyName | String | Name of the property. Will match the `name` of the `property` object provided. |
| value | any | Value received from the broker, converted to the `dataType` of the `Property`. |
| originalValue | any | Value received from the broker without any conversion applied. |
#### PropertyValuePair
| Name | Type | Description |
| -------- | ---------- | ------------------------------------ |
| property | `Property` | Full description of the property |
| value | any | Value to associate with the property |
#### RegisterHandler
| Name | Type | Description |
| ----- | ------- | ------------------------------------ |
| event | `Event` | Event to register (full information) |
#### UnregisterHandler
| Name | Type | Description |
| ----- | ------- | ------------------------------------------------------------------- |
| event | `Event` | Event to unregister (at least the property `name` must be supplied) |
### Methods
#### Get Properties Values
Requests the server for the values of one or more properties
**Signature**
```ts
PropertyValue[] connect.iot.driver.template.getProperties(request Property[])
```
**Example**
Request `connect.iot.driver.template.getProperties`
```json
[
{
"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:
```json
[
{
"propertyName": "test1",
"originalValue": {
"topic": "production/something",
"value": ,
},
"value": "defaultP1",
},
{
"propertyName": "test2",
"originalValue": {
"topic": "production/otherthing",
"value": ,
},
"value": "defaultP2",
}
]
```
#### Set Property Values
Requests the server to define the values of one or more properties.
**Signature**
```ts
boolean connect.iot.driver.template.setProperties(request PropertyValuePair[])
```
**Example**
Request `connect.iot.driver.template.setProperties`
```json
[
{
{
"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:
```json
true
```
#### Register Event
Notifies the protocol driver to raise the occurrences of a specific event when it occurs.
**Signature**
```ts
void connect.iot.driver.template.registerEvent(data: Event)
```
!!! note
The events are published to the listeners `connect.iot.driver.template.event` appended with the name of the event registered. Example: `connect.iot.driver.template.event.CustomEvent`
**Example**
``` json
{
"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**
```ts
void connect.iot.driver.template.unregisterEvent(data: UnregisterHandler)
```
**Example**
```json
{
"event":{
"name":"CustomEvent"
}
}
```