MQTT

Click here to see this page in full context

MQTT

MQTT (Message Queueing Telemetry Transport) is a messaging protocol that runs over TCP/IP, with a publish - subscribe structure.

A Publisher sends messages according to Topics, to specified Brokers.
A Broker acts as a switchboard, accepting messages from publishers on specified topics, and sending them to subscribers to those topics.
A Subscriber receives messages from connected Brokers and specified Topics.

UniStream supports MQTT as a 'client' that can both publish, and subscribe, to messages. UniStream can:

Publish data:
- To a defined Broker according to a configured Topic. For example, the Topic may be Kiln; the messages can include application data such as temperature or pressure.
- Periodically, according to a time period set in the configuration
- Aperiodically, via Ladder Function

Receive data from a defined Broker on a defined Topic, to which UniStream is subscribed.

Configuring MQTT

Before you begin, configure the PLC's IP address, default gateway, and DNS Server.
If you do not know your provider's DNS setting, note that you can try the most common setting, which is DNS 8.8.8.8.

In order to implement MQTT, you must first configure the Broker Connections.

You can configure and create both Subscriptions and Publications.

When you begin configuring MQTT, UniLogic automatically creates the MQTT General struct and the MQTT Statistics struct.

MQTT General Struct

Parameter Name	Type	Purpose
MQTT Process Status	UINT32	These indicate the status of the UniStream - broker connection 0 - MQTT Initialization in Progress 1- MQTT is running 2 - MQTT is in "Pause" mode
Number of Brokers	UINT16	This shows the number of configured Brokers
Number of Publications	UINT16	This shows the number of configured Publications
Number of Subscriptions	UINT16	This shows the number of configured Subscriptions

MQTT Statistics Struct

Parameter Name	Type	Purpose
Sent Publications	UINT32
Acknowledged Publications	UINT32
Received Publications	UINT32
Dropped	UINT32

Broker Connections

To enable UniStream to publish and subscribe to messages, you must configure Broker Connections.

Note that you can modify these parameters at run-time via the Ladder element Set Broker Configuration.

Broker Connection Properties

Name	Definition
Name	This is a name that you assign to the broker for your own reference, and that UniLogic will assign to the MQTT Broker Struct. It has no significance in the MQTT protocol.
ID	This is a unique ID# for this broker; you use this number to link Ladder element parameters to the broker. It has no significance in the MQTT protocol.
Mode	Select IP or .url.
IP /URL	Enter the IP address or .url of the broker
Port	By default, UniLogic uses the common MQTT port 1883; edit this if your application requires. The range is 1-65535.
Clean Session	Clean Session determines the behavior of the broker if the connection to a subscriber is broken. 0 = the broker saves all subscription data and incoming messages for that subscriber, and sends them all at re-connection. 1 = the broker does not retain any subscription data; the Subscriber must re-subscribe
Client ID	You can assign a unique Client ID, or leave it blank. In this event UniLogic generates an ID. Limited to 23 characters.
User Name (optional)	Limited to 64 characters.
Password (optional)	Limited to 128 characters.
Last Will Topic (optional)	In the event of disconnection, this is the last topic that will be published to the broker. Note that you can include the following identifiers: {PLC.MAC},{PLC.SN},{PLC.NAME}
Last Will Message (optional)	In the event of disconnection, this is the message that will be published to the broker, under the Last Will Topic.
Keep Alive (seconds)	This is the amount of time the broker will wait before determining that the connection is broken.
Auto-connect Bit	Select to auto-connect UniStream at power-up.
Connection Attempts Interval (seconds)	If the connection is broken, this is the amount of time UniStream will attempt to reconnect with a broker
Encryption	Click the field to select the connection security level: MQTT/TCP: normal unsecured connection MQTT/SSL -- No Server Authentication: with this option, a secured encrypted connection is set up but neither the broker nor UniStream is required to provide authentication. MQTT/SSL -- CA certificate Only – the client will be prompted to provide a certificate file matching the broker's; UniStream will require a valid certificate from the broker. MQTT/SSL -- CA Signed Server certificate: the broker is required to provide a certificate issued by a known authority. A list of such certificates is included in UniStream and updated at intervals. MQTT/SSL -- Self-Signed Server certificate. MQTT/SSL -- Google Clould IoT Self-Signed Server certificate. Note that you must set the MQTT client ID to the full device path projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID

Broker Struct

When you add a broker, UniLogic automatically creates a supporting struct. Note that these parameters are read-only.

Parameter Name	Type	Purpose
Connection Status	Bit	0 = Broker is not connected 1 = Broker is connected
Session Present	Bit	Indicates whether the broker already has a persistent session of the client from previous interactions.
Return Code	INT8	This indicates the status of the UniStream - broker connection 0 - Connection accepted 1 - Connection refused, unacceptable protocol version 2 - Connection refused, identifier rejected 3 - Connection refused, server unavailable 4 – Connection refused, unknown user name or password 5 – Connection refused, not authorized -11 - The UniStream broker is already connected -12 - The UniStream broker is not connected -13 - The connection with the server/broker was lost

Subscription Configuration

This determines the topics on which UniStream will receive messages

Name

Definition

Name

This is a name that you assign to the subscription for your own reference, and that UniLogic uses to identify the subscriptions. It has no significance in the MQTT protocol.

This is a unique ID# for this subscription; you use this number to link Ladder element parameters to the subscription.
It has no significance in the MQTT protocol.

Broker

The name of the broker UniStream is subscribing to.

Topic

This is the name of the topic that UniStream is subscribing to. It is a fixed string of up to 256 characters that can contain wildcards.

Note that you can include the following identifiers: {PLC.MAC},{PLC.SN},{PLC.NAME}

Data

UniStream stores the incoming message into the linked data tag; you may also link a buffer or a struct.

Quality of Service

Quality of Service is a feature of the MQTT protocol that controls retransmission
of messages in specific situations.

Level	Definition
0	Message is sent once. Reception is not acknowledged.
1	Message will be delivered at least once. Reception is acknowledged.
2	Message will be delivered only once. Reception is acknowledged.

Buffered Mode

Select this to cause the UniStream to save a queue of messages published on this topic.

Note that this means that, after UniStream receives a message, you must reset the Message Received bit in the Subscription's struct in order to receive the next message in the queue.

If you do not select Buffered Mode, UniStream will simply accept messages as they arrive.

Subscribe at Boot Time

This causes UniStream to automatically subscribe to the topic at Power-up.

Format

Click on the field to select whether the data will be interpreted as Raw Data (bytes), or according to JSON format.

Subscription Struct

When you add a subscription, UniLogic automatically creates a supporting struct. Note that these parameters are read-only.

Parameter Name	Type	Purpose
Subscribed	Bit	0 = Topic not currently subscribed 1 = Topic subscribed
Subscribed Status	INT8	Indicates if the subscription is successful, according to the Quality of Service selected - 0 – success – Max QoS 0 - 1 – Success – max QoS 1 - 2 – Success – max QoS 2 - 128 – Failure
Message Received (Received bit)	Bit	Turns ON each time a message arrives to the CPU. If Buffered Mode is selected, the user must reset this bit to enable UniStream to receive the next message in the queue.
Queue Full	Bit	Turns ON when message queue is full.
Last Message in Topic	String	This is the last message received by UniStream on the topic
Last Message Received Time	UINT32	UTC time stamp, indicating when the last message was received.
Buffered Data Status	INT8	Indicates status of data in buffer: - 0 – Data Ready - 1 – Transferring Data - 2 – Data Arrived

Publication Configuration

This determines the topics on which UniStream will send messages.

You can create Periodic and Aperiodic messages. Periodic messages are published according to a time period set in the configuration
Aperiodic messages are published via Ladder Function.

Name

Definition

Name

This is a name that you assign to the Publication for your own reference, and that UniLogic uses to identify the subscriptions. It has no significance in the MQTT protocol.

This is a unique ID# for this Publication; you use this number to link Ladder element parameters to the Publication .
It has no significance in the MQTT protocol.

Broker

The name of the broker UniStream is Publishing to.

Topic

This is the name of the topic that UniStream is subscribing to. It is a fixed string of up to 256 characters that can contain wildcards.

Note that you can include the following identifiers: {PLC.MAC},{PLC.SN},{PLC.NAME}

Data

UniStream stores the incoming message into the linked data tag; you may also link a buffer or a struct.

Quality of Service

Quality of Service is a feature of the MQTT protocol that controls retransmission
of messages in specific situations.

Level	Definition
0	Message is sent once. Reception is not acknowledged.
1	Message will be delivered at least once. Reception is acknowledged.
2	Message will be delivered only once. Reception is acknowledged.

Retain Flag

Selecting this notifies the broker to retain the last message in a topic. If a subscriber is off-line when the message is received, and Retain Flag is selected, the broker will send the message when the connection is restored.

Format

Click on the field to select whether the data will be interpreted as Raw Data (bytes), or according to JSON format.

Every Period

This parameter is shown only for periodic publications.

Broker Received

This turns ON after a broker receives a publication. Reset by user.

MQTT Ladder Functions

Use these to manage MQTT via Ladder.

The maximum number of active requests is 16.

Subscribe to Topic

	Parameter Name
A	Select the subscription ID of the topic to subscribe to
B	Status of the function

Subscribe All

	Parameter Name
A	Select the ID of the broker to subscribe to, to receive all Topics published by that broker
B	Status of the function

Unsubscribe Topic

	Parameter Name
A	Select the subscription ID of the topic to unsubscribe from
B	Status of the function

Connect Broker

	Parameter Name
A	Select the broker ID to connect to
B	Status of the function

Disconnect Broker

	Parameter Name
A	Select the broker ID to connect to
B	Status of the function

Send Aperiodic message

	Parameter Name
A	Select the ID of the Publication to send
B	Status of the function

Get/Set Broker Configuration

The Ladder functions Get/Set Broker Configuration require you to use a struct Data type called MQTT Broker Configuration.

Get Broker Configuration

	Parameter Name
A	Select the ID of the Broker you want to get the configuration from
B	Select the Broker Configuration Struct you wish to contain the parameters you receive from the Broker
C	Status of the function

Set Broker Configuration

	Parameter Name
A	Select the ID of the Broker you want to send the configuration to
B	Select the Broker Configuration Struct you wish to send to the Broker
C	Status of the function

Broker Configuration - Data Tag Struct

Name	Definition
IP /URL	Enter the IP address or .url of the broker
Port	By default, UniLogic uses the common MQTT port 1883; edit this if your application requires. The range is 1-655535.
Clean Session	Clean Session determines the behavior of the broker if the connection to a subscriber is broken. 0 = the broker saves all subscription data and incoming messages for that subscriber, and sends them all at re-connection. 1 = the broker does not retain any subscription data; the Subscriber must re-subscribe
Client ID	You can assign a unique Client ID, or leave it blank. In this event UniLogic generates an ID. Limited to 23 characters.
User Name (optional)	Limited to 64 characters.
Password (optional)	Limited to 128 characters.
Last Will Topic (optional)	In the event of disconnection, this is the last topic that will be published to the broker
Keep Alive (seconds)	This is the amount of time the broker will wait before determining that the connection is broken.
Connection Attempts Interval (seconds)	If the connection is broken, this is the amount of time UniStream will attempt to reconnect with a broker
Clean Session Flag	Clean Session determines the behavior of the broker if the connection to a subscriber is broken.

Get/Set Publication Configuration

The Ladder functions Get/Set Publication Configuration require you to use a struct Data type called MQTT Publication Configuration.

Get Publication Configuration

	Parameter Name
A	Select the ID of the Publication you want to get the configuration from
B	Select the Publication Configuration Struct you wish to contain the parameters in
C	Status of the function

Set Publication Configuration

	Parameter Name
A	Select the ID of the Publication you want to send the configuration to
B	Select the Publication Configuration Struct you wish to send to
C	Status of the function

Publication Configuration - Data Tag Struct

Parameter Name	Purpose
Topic	Contains the Topic Name
Quality of Service	contains the QoS setting
Retained Flag	Signifies broker behavior, whether the broker retains the last message in a topic.
Payload format	0 - Raw data, 1 - JSON

Set Publication State

	Parameter Name
A	Select the ID of the Publication to Enable/Disable
B	0= Enable 1=Disable
C	Status of the function

Get/Set Subscription Configuration

The Ladder functions Get/Set Subscription Configuration require you to use a struct Data type called MQTT Subscription Configuration.

Get Subscription Configuration

	Parameter Name
A	Select the ID of the Subscription you want to get the configuration from
B	Select the Subscription Configuration Struct you wish to contain the parameters in
C	Status of the function

Set Publication Configuration

	Parameter Name
A	Select the ID of the Subscription you want to send the configuration to
B	Select the Subscription Configuration Struct you wish to send to
C	Status of the function

Subscription Configuration - Data Tag Struct

Parameter Name	Purpose
Topic	Contains the Topic Name
Quality of Service	contains the QoS setting
Payload format	0 - Raw data, 1 - JSON
Subscribe at Boot Time	0 - Raw data, 1 - JSON
Buffered	Signifies behavior, whether UniStream saves a queue of messages published on this topic.

MQTT Pause/Start

Use Pause to cause MQTT to halt, and Start to restart it.

Status Messages, MQTT Ladder Functions

Code	Message
0	Success
1	Accepted
2	In progress
-1	Configuration Error. Check the values you are trying to assign and run the command again.
-2	ID does not exist (ID of Broker/Subscription/Publication linked to by the function).
-3	Contact support
-4	Pause required. Before running any MQTT "Set" Ladder Operation, you must use a Pause MQTT function.
-5	Duplicate Pause. MQTT communications are already in Pause mode.
-6	Paused. Function cannot run when MQTT is in Pause mode.
-7	You cannot run the function MQTT Set Publication State using the ID of a Publication configured as Aperiodic.
-8	You cannot run the function MQTT Send APeriodic using the ID of a Publication configured as Periodic.
-9	Configuration Error. Contact Support.
-10	Broker Error. Check the Status Messages for this broker in Broker Struct > Return Code
-11	Subscription Error. Check the Status Messages for this Subscription in Subscription Struct > Subscription Status.
-12	Publication Error. Check the Status Messages for the linked broker in Broker Struct > Return Code, and republish.
-13	Contact Support
-14	Contact Support

Status Messages, MQTT Broker

Code	Message
0	Success
2	Connection Refused: Server unavailable
3	Connection Refused: Incorrect User Name or Password
4	Connection Refused: Not Authorized
-1	Cannot connect to broker. Check communication parameters
-7	Topic tag includes a null character
-11	UniStream is already connected to the broker
-12	UniStream is not connected to the broker
-13	Broker Connection was lost

Status Messages MQTT Subscription

Code	Message
0	Success
-1	Cannot connect to broker. Check communication parameters
-7	Topic tag includes a null character
-11	UniStream is not connected to the broker
-12	JSON String Error--string invalid
-13	Not subscribed to Topic
-14	Already subscribed to Topic
-15	Broker Connection was lost