MQTT

MQTT Device Driver allows Iotellect Server to connect to an MQTT broker and to subscribe to topics. Received messages are presented as device events. The driver communicates with the broker using the MQTT version 5 protocol.

MQTT is an ISO standard publish-subscribe based messaging protocol for use on top of the TCP/IP protocol.

Driver Information

Driver Plugin ID Suffix:

device.mqtt

Global Settings

None defined.

User Level Settings

None defined.

Device Account Properties

Connection Properties

Connection settings define how Iotellect Server communicates with an MQTT broker. These settings may be accessed using the Edit Device Properties action of Device Context. The following connection properties are available, listed by the groups they are arranged in within the properties editor. Properties marked as advanced are initially hidden in the editor and are revealed by the Show/Hide Advanced Properties button, unless their values differ from the defaults:

Setting	Description
Connection Method	Dictates how the device establishes a connection with the MQTT broker. Options include: TCP: A standard, unencrypted connection method using TCP, suitable for local networks where security isn't critical. SSL/TLS: A secure, encrypted connection using SSL/TLS, protecting data transmitted between client and broker and essential for sensitive data over untrusted networks. WebSocket: Uses the WebSocket protocol for persistent, bidirectional communication, often employed in web browsers but lacking inherent encryption. Secure WebSocket: Combines WebSockets with SSL/TLS encryption, providing secure and persistent connections for web-based MQTT applications handling sensitive data.
Broker Address	The IP address or host name of the MQTT broker.
Port	Indicate the port where the MQTT broker is listening. If no port is specified, the device will attempt to connect to the broker using the default port appropriate for the selected Connection Method.
Topics	List of topics and topic filters to subscribe to. Columns of the Topics table are described below.
Message Data Format	Data type of the Message Data field of Message events. Possible types are: Text Message Data field of Message events will contain received message text. Binary Message Data field of Message events will contain the raw data of received messages in the Data Block format.
Client ID	This is an identifier of each client connecting to a server. Client ID must be unique across all clients. It is used by the server to store data related to the client, hence it is important that this parameter remains the same when connecting to a server if durable subscriptions or reliable messaging are required. By default, Client ID is generated automatically.
Clean Session	Sets whether the client and server should remember state across restarts and reconnects. If set to false both the client and server will maintain state across restarts of the client, the server and the connection. Message delivery will be reliable meeting the specified QoS even if the client, server or connection are restarted. If set to true the client and server will not maintain state across restarts of the client, the server or the connection.
Keep Alive Interval	Advanced property. This value, measured in seconds, defines the maximum time interval between messages sent or received. It enables the client to detect if the server is no longer available, without having to wait for the TCP/IP timeout. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during the time period, the client sends a very small "ping" message, which the server will acknowledge. A value of 0 disables parameter processing in the client. The default value is 60 seconds.
Connection Timeout	Advanced property. Sets the connection timeout value. This value, measured in seconds, defines the maximum time interval the client will wait for the network connection to the MQTT server to be established. The default timeout is 30 seconds. A value of 0 disables timeout processing meaning the client will wait until the network connection is made successfully or fails.
User Properties	Advanced property. The user-defined properties that let the user add metadata to MQTT messages and transmit additional user-defined information to the broker. These properties are sent to the broker upon connection. Columns of the User Properties table are described below.
Security
Certificate Trust Policy	Advanced property. Defines how to verify certificates provided via an SSL/TLS connection.
Certificate	Advanced property. Alias of an SSL/TLS certificate to use for authentication. The certificate with that alias must exist in the server's client certificate storage.
User Name	The user name to use for the connection to the MQTT broker.
Password	The password to use for the connection to the MQTT broker.
Offline Buffering
Enable Offline Buffering	Advanced property. Enables the use of an offline message buffer for unconfirmed messages.
Buffer Size	Advanced property. Maximum number of messages that can be stored in the buffer.
Delete Oldest Messages	Advanced property. Whether older messages must be deleted when the number of messages in the buffer reaches its maximum. If this value is false, extra messages are ignored.
MQTT version 5
Largest Number of Incoming Messages	Advanced property. The largest number of incoming messages with QoS 1 and 2 that the MQTT device account is willing to process simultaneously, that is, the maximum sending quota that the broker can use.
Maximum Packet Size	Advanced property. Used to negotiate the maximum packet length that the MQTT device account can handle.
Topic Alias Maximum	Advanced property. Indicates the maximum number of topic aliases that the MQTT device account can use in this connection. The default value is zero, which means that no broker-assigned topic aliases are accepted.
Session Expiry Interval	Advanced property. Maximum time that a session can be retained on the MQTT device account after the network is disconnected. The default value is zero, which means that a session ends when a connection closes.

The Topics table has the following columns:

Column Name	Type	Description
Topic Filter	String	Single topic name or multiple topics wildcard to subscribe to. Examples of valid filters are `home/bedroom/temperature`, `home/bedroom/#`, or `home/+/temperature`.
QoS	Integer	The maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe. The QoS parameter can be set to 0, 1 or 2, with 0 as the default: QoS 0 indicates that a message should be delivered at most once (zero or one times). QoS 1 indicates that a message should be delivered at least once (one or more times). QoS 2 indicates that a message should be delivered once.
No Local Messages	Boolean	Advanced column. Prevents a client from receiving messages that it has published itself. The default value is false.
Retain Flag as in Published Message	Boolean	Advanced column. Controls whether messages forwarded to the MQTT device account should preserve the original Retain flag from the publisher. When enabled, retained messages are delivered with the retain flag exactly as they were published; when disabled, the broker clears the retain flag on forwarded messages, except when sending retained messages as part of a new subscription. The default value is false.
Retain Messages Handling	Integer	Advanced column. Controls whether the broker sends retained messages when the MQTT device account subscribes to a topic. It can be configured to: always send retained messages (Send at subscription time, the default) send them only when the subscription is new (Send only for new subscriptions) not send retained messages at all (Do not send), allowing clients to avoid receiving old retained values when they only want future updates.

The User Properties table has the following columns:

Column Name	Type	Description
Key	String	Name of the property. The key is mandatory and cannot be empty.
Value	String	Value of the property.

Device Assets

Assets are not supported by the driver.

Device Settings

MQTT Device Driver creates the following Device setting variable:

Variable Name	Variable Description	Comments
messageCount	Received Message Count	Count of received messages. Value is updated every synchronization. The count persists across reconnections and resets to zero when the device connection settings are changed or the server is restarted.
clientId	Client ID	Client ID associated with this device.
errorCount	Error Count	Count of errors reported by the MQTT client. Value is updated every synchronization. The count survives reconnections and is reset to zero when the device connection properties are changed or the server is restarted.
brokerCapabilities	Broker Capabilities	Read-only table of capabilities and connection parameters reported by the MQTT broker. The value is populated upon each successful connection to the broker.

The Broker Capabilities variable has the following fields:

Field Name	Field Type	Field Description
receiveMaximum	Integer	Largest Number of Incoming Messages. Largest number of messages with QoS 1 and 2 that the broker is willing to process simultaneously.
maximumQoS	Integer	Maximum QoS. Highest QoS level supported by the broker.
maximumPacketSize	Long	Maximum Packet Size. Maximum packet length that the broker can handle.
topicAliasMaximum	Integer	Topic Alias Maximum. Maximum number of topic aliases that the broker accepts in this connection.
retainAvailable	Boolean	Retain. Whether the broker supports retained messages.
wildcardSubscriptionsAvailable	Boolean	Wildcard Subscriptions. Whether the broker supports topic filters with wildcards.
subscriptionIdentifiersAvailable	Boolean	Subscription Identifiers. Whether the broker supports subscription identifiers.
sharedSubscriptionAvailable	Boolean	Shared Subscription. Whether the broker supports shared subscriptions.
serverKeepAlive	Integer	Server Keep Alive. Keep alive interval reported by the broker.
sessionExpiryInterval	Long	Session Expiry Interval. Maximum time the broker retains the session after the network connection is closed.
assignedClientIdentifier	String	Assigned Client Identifier. Client ID assigned by the broker.
reasonString	String	Reason String. Text returned by the broker in response to the connection request.

Device Operations

Publish Text Message

Send a text message to the broker.

Format of the function input parameters has the following fields:

Name	Type	Description
Topic	String	The topic that the message should be published on.
QoS	Integer	The Quality of Service level to use. Valid values are 0, 1 or 2.
Retained	Boolean	Whether or not the message should be retained by the broker.
Message	String	The text message to send.
User Properties	Data Table	Advanced field. The user-defined properties that let the user add metadata to the published message and transmit additional user-defined information. The same format as the User Properties connection property.
Content Type	String	Advanced field. A UTF-8 string (typically a MIME type) that describes the nature of the payload.
Response topic	String	Advanced field. Topic the responder should publish its reply to.
Correlation Data	String	Advanced field. Arbitrary binary data specified by the requester to identify the request associated with a response.
Payload Format Indicator	Integer	Advanced field. Specifies whether the payload is an Unspecified byte stream (Binary Data, the default) or UTF-8-encoded data (Text Data).
Message Expiry Interval	Long	Advanced field. Controls how long queued or retained messages persist for offline subscribers. A null value means no expiry (protocol default).

The function has no output parameters.

Publish Binary Message

Send a binary message to the broker.

Format of the function input parameters has the following fields:

Name	Type	Description
Topic	String	The topic that the message should be published on.
QoS	Integer	The Quality of Service level to use. Valid values are 0, 1 or 2.
Retained	Boolean	Whether or not the message should be retained by the broker.
Message	Data Block	Binary data message to send.
User Properties	Data Table	Advanced field. The user-defined properties that let the user add metadata to the published message and transmit additional user-defined information. The same format as the User Properties connection property.
Content Type	String	Advanced field. A UTF-8 string (typically a MIME type) that describes the nature of the payload.
Response topic	String	Advanced field. Topic the responder should publish its reply to.
Correlation Data	String	Advanced field. Arbitrary binary data specified by the requester to identify the request associated with a response.
Payload Format Indicator	Integer	Advanced field. Specifies whether the payload is an Unspecified byte stream (Binary Data, the default) or UTF-8-encoded data (Text Data).
Message Expiry Interval	Long	Advanced field. Controls how long queued or retained messages persist for offline subscribers. A null value means no expiry (protocol default).

The function has no output parameters.

Device Events

Message

Fired when Iotellect Server receives an incoming MQTT message.

Event Name	message
Records:	1

Record Format:

Field Name	Field Type	Description
topic	String	Topic the message was published on.
message	String	Message text if message was published as a string.
messageData	Data Block	Message Data Block if message was published as binary data.
id	String	ID of the message.
qos	Integer	QoS associated with the message.
retained	Boolean	Whether the message was retained by the broker.
duplicate	Boolean	Whether this message is a duplicate.
userProperties	Data Table	Advanced field. The user-defined properties of the received message. The same format as the User Properties connection property.
contentType	String	Advanced field. Content type of the message payload (typically a MIME type).
responseTopic	String	Advanced field. Topic the responder should publish its reply to.
correlationData	String	Advanced field. Correlation data specified by the requester to identify the request associated with a response.
payloadFormatIndicator	Integer	Advanced field. Specifies whether the payload is an Unspecified byte stream (Binary Data) or UTF-8-encoded data (Text Data).

Error

Fired when an error occurs in the MQTT client, or when the broker rejects a published message with an error reason code (0x80 or higher). Connection, disconnection, and publishing errors are additionally reported as Info events whose text includes the error code and error message.

Event Name	error
Records:	1

Record Format:

Field Name	Field Type	Description
errorCode	Integer	Code of the error.
errorMessage	String	Text of the error message.

Connection Handling

This driver makes the device Online if a connection with the MQTT broker was successfully established.

DPF_EXPORT_V5.8.8 / TIME_1787752610 / 2026-08-26 13:56:50 / STRLEN_47857 / STRLEN_HTML_35759

{VERSION}

Was this page helpful?