15/11/22, 16:06 MQTT

Show 
Home > Communications > MQTT

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

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 1/9
15/11/22, 16:06 MQTT
MQTT Process UINT32 These indicate the status of the UniStream - broker connection
Status
0 - MQTT Initialization in Progress
1- MQTT is running
2 - MQTT is in "Pause" mode

Number of UINT16 This shows the number of configured Brokers

Brokers

Number of UINT16 This shows the number of configured Publications

Publications

Number of UINT16 This shows the number of configured Subscriptions

Subscriptions

MQTT Statistcs Struct

Parameter Name Type Purpose

Sent Publications UINT32  

Acknowledged UINT32  
Publications

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-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 In the event of disconnection, this is the last topic that will be published to the broker
(optional)

Last Will Message In the event of disconnection, this is the message that will be published to the broker, under the Last Will Topic.
(optional)

Keep Alive (seconds) This is the amount of time the broker will wait before determining that the connection is broker.

Auto-connect Bit Select to auto-connect UniStream at power-up.

Connection Attempts If the connection is broken, this is the amount of time UniStream will attempt to reconnect with a broker
Interval (seconds)

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.

 
https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 2/9
15/11/22, 16:06 MQTT
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 UINT8 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

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.

ID 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.

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 This causes UniStream to automatically subscribe to the topic at Power-up.
Time

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

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 3/9
15/11/22, 16:06 MQTT
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 Status Bit 0 = Topic not currently subscribed

1 = Topic subscribed

Subscribed Status UINT8 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
Bit Turns ON each time a message arrives to the CPU.
(Received bit)
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 String This is the last message received by UniStream on the topic
Topic

Last Message UINT32 UTC time stamp, indicating when the last message was received.
Received Time

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.

ID 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.

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.

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 4/9
15/11/22, 16:06 MQTT
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.

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

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 5/9
15/11/22, 16:06 MQTT

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

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

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 6/9
15/11/22, 16:06 MQTT

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 In the event of disconnection, this is the last topic that will be published to the broker
(optional)

Keep Alive (seconds) This is the amount of time the broker will wait before determining that the connection is broker.

Connection Attempts If the connection is broken, this is the amount of time UniStream will attempt to reconnect with a broker
Interval (seconds)

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.

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 7/9
15/11/22, 16:06 MQTT
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 0 - Raw data,
Time
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

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 8/9
15/11/22, 16:06 MQTT

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

https://www.unitronicsplc.com/Download/SoftwareHelp/UniLogic_Knowledgebase/Communications/MQTT.htm 9/9