Topic updated on September 17, 2021
An MQTT device represents a connection to an MQTT broker. The MQTT device type includes the features to:
- Create a connection to an MQTT broker. These devices are used by triggers to either publish on or subscribe to topics from that broker.
Support the trigger action, MQTT Publish.
This trigger action is used to publish a payload on a topic over the MQTT connection defined by this device. It is different from the TR50 MQTT Publish action and does not use the TR50 feature or the IoT Portal.
Support the trigger event, MQTT Publish Receive.
This trigger event is used to subscribe to a topic over the MQTT connection defined by this device. It is different from the TR50 MQTT Publish Receive event and does not use the TR50 feature or the IoT Portal.
Defining an MQTT device
To define an MQTT device, follow these steps:
- From the Workbench left pane, expand the node where you want to define the MQTT device.
Right-click on Devices to display its short cut menu, and then select New.
It is also possible to click New button at the bottom of the Devices panel.
- Enter a Name for the device. The device name can be up to 64 characters and include letters, numbers, and the underscore character. Spaces are allowed.
Click Type down-arrow, locate the MQTT category, and then select MQTT Connection.
MQTT Connection - Defines an MQTT client connection to an MQTT Broker.
The Device window changes to accommodate the device type.
The following describes the parameters that become available from the Device window:
Parameter Description Client ID Type Select a generated Client ID Type or the Input option to manually enter a Client ID. Generated Client IDs could be IMEI, MAC Address, Machine ID or a Machine GUID. Not all options will be available on all platforms. For example, the IMEI option is only found on Asset Gateways that have a SIM Card installed. Select Input to manually enter a unique Client ID. Client ID This field is displayed only if the Input option is made in the Client ID Type field. An ID that must be unique to the MQTT broker. The valid characters for a Client ID are: letters, numbers, "_" (underscore) , and "-" (hyphen). If multiple MQTT devices are attempted to be Started with the same Client ID (to the same MQTT broker), then the additional devices will not be Started and will be Disabled. Connection Type MQTT - Connect without TLS (Transport Level Security)
MQTT with TLS - Connect with TLS (Transport Level Security)
Broker Host The endpoint address for the MQTT Broker (Hostname or IP address) in dotted decimal format of the MQTT Broker. For example: nuj144148a.site.orgname.com or 10.200.15.110. Port The port on the MQTT broker to establish a connection with. Certificate The certificate to use for authentication. Only displayed when MQTT with TLS is selected in the Connection Type. Private Key The private key associated with the certificate. Only displayed when MQTT with TLS is selected in the Connection Type. Server Certificate The certificate associated to the server for authentication. Only displayed when MQTT with TLS is selected in the Connection Type. Username The username that the MQTT client will use to authenticate with the MQTT server. Password The password to use to connect to the remote node. This may or may not be required depending on the MQTT broker. Heartbeat Interval (sec) The MQTT client will periodically send heartbeats to the MQTT Server to ensure a healthy connection. When data is not being sent over the connection (from MQTT Publish actions or publishes to an MQTT Publish Receive event trigger), these heartbeats are needed to ensure that the connection has not become broken.
Increasing this value will reduce the data usage for the heartbeats, but increases the chance that the connection may not be available when it is needed in a scenario where the connection quality is poor.
Decreasing this value will increase the amount of data used by the connection, but will detect communication problems in a more timely manner.
The default is 60 seconds.
Last Will and Testament Select True, if a Last Will and Testament message should be sent when the connection to the broker is closed. Topic The topic to publish the Last Will and Testament message. Only displayed when the Last Will and Testament is set to True. Message Enter the message to publish to the broker when the connection is closed. Only displayed when the Last Will and Testament is set to True. QoS The Quality of Service associated with the Last Will and Testament message. Only displayed when the Last Will and Testament is set to True.
- After entering all of the parameters, click Validate to have the parameters validated.
- Click Save to save the device definition. The device will appear in the Devices window list of devices.
- You can now control the device (Start, Stop) and build solutions that use the device by referencing the device name in the MQTT Publish action and the MQTT Publish Receive event.