MQTT & MQTTS

Terminology

MQTT (Message Queuing Telemetry Transport) is a protocol that allows data to be shared between devices using strings, locally or across the internet. An MQTT Broker is the server and is typically cloud-based. The Client is any device that can query the server. To upload data to the broker, a client will publish a string. To receive data from a broker, a client will subscribe to a topic. A topic is a path to the desired data, is case-sensitive, and will be formatted in a style like “Weather/USA/Springfield/Temperature”.The actual layout of the topics and topic levels will be determined by the publisher topic fields.

Description

The CPU uses the MQTT feature to accumulate process data from machines, sensors, and devices and publish this data to an MQTT broker. The CPU can also use the MQTT feature to subscribe to known publisher topics. Once connected, the CPU can publish topics to the broker and subscribe to topics from the broker. The MQTT feature is client-only, and can target up to 4 different MQTT brokers. Each broker target can support up to 3 Publisher functions and 1 Subscriber function. Each Publisher and Subscriber support up to 10 different Broker Topics.

MQTT Client Setup

To configure the CPU as an MQTT Client, use the setup tools found in the Hardware Configuration window. The MQTT options are found under the MQTT tab of the Hardware Configuration window as shown below. To configure a connection to a broker, click and drag MQTT Client from the right-hand column onto the MQTT palette.

Note: A maximum of 4 MQTT Clients are allowed per CPU.

Once the MQTT Client has been placed on the MQTT palette, the following MQTT Client Properties window will appear.

a. Device Name [REQUIRED]: Each MQTT Client added to the MQTT window must contain a unique Device Name (Client ID).

b. Enable [REQUIRED]: A Boolean tag that, when true, opens the TCP connection to the broker. Once the TCP connection to the broker is established, an MQTT Connect Command is sent. If the Boolean tag goes from true to false, the PLC unsubscribes from any subscriptions, issues an MQTT Disconnect request and then closes the TCP connection.

c. Use IP Address: If this option is selected and the IP radio button is selected, then a valid IP address must be entered in the adjacent field. Otherwise, if the Tag radio button is selected, a String tag is required in this field. This is the IP address of the MQTT broker the CPU will target.

d. Use Server Name: If this option is selected, then the server name of the MQTT broker target must be entered in the adjacent field. The Server Name can be static text (indicated by quotation marks on either side of the text) or a String tag.This also requires appropriate DNS settings in the CPU and the most current CPU firmware.

e. TCP Port Number: Default value is 1883 for non-encrypted MQTT and 8883 for encrypted MQTT. Any port number from 1-65535 may be entered as an integer value or integer tag. The port number must match the configured port number of the MQTT broker. It is the TCP port number where clients must open a TCP connection to begin publish and subscribe transactions with the broker.

f. Keep Alive Time (10-60 seconds): Default value is 30. Any amount between 10-60 may be entered as an integer value or integer tag. Once connected to a broker, the CPU will send periodic PING messages, at the rate specified by the Keep Alive Time, to ensure the broker is still available. If there is no reply to the PING message, the CPU will send 2 more PING messages at 1 second intervals. If there is still no reply, the CPU will close the TCP connection and wait 10 seconds. After waiting 10 seconds, if any of the Publisher Enable bits are true or the Subscriber Enable bit is true, the CPU will attempt to re-connect to the Broker and follow the same pattern above.

g. Use Authentication: If the MQTT broker requires authentication, select this option. Once this option is selected, a Username and Password must be entered in the adjacent fields. Usernames and Passwords up to 128 characters are allowed.

1. Username can be static text (indicated by quotation marks on either side of the text) or a String tag.

2. Password can be static text, if the PW radio button is selected, or a String tag, if the Tag radio button is selected.

Note: If unauthorized connection requests (e.g. wrong username and/or password or publish to unauthorized topic) are sent to the MQTT broker, it may disconnect the MQTT session before the MQTT client is able to determine the cause of the disconnection. If the MQTT client does not know the reason for the disconnection, it will attempt to reconnect to the broker every 5 seconds. If the MQTT client does know the reason for disconnection, it will attempt to reconnect to the broker at the same frequency as the Keep Alive Time.”

h. Clean Session: The MQTT Client only supports non-persistent connections. When Clean Session = True the broker does not store any relevant client state information on the server (e.g. current subscriptions or queued publish messages). If the connection is terminated, the broker discards queued publish messages and the client needs to subscribe to topics again on a new connect. This field cannot be changed by the user..

i. Use Structure: Enables use of Structures.

j. Connected: Boolean tag indicating that the TCP connection with the MQTT broker was successful.

k. Error: Boolean tag is set to true if the PLC receives an error when establishing the TCP connection or sending the MQTT Connect Command. This tag is reset when Enable tag is set to false and may also be reset in ladder.

l. Error Code: Integer tag containing the error code generated when the TCP connection fails. This tag should be used to help troubleshoot connections to adapter devices. This tag is reset to 0 when Enable tag is set to false and may also be cleared/changed in ladder.

m. Last Will and Testament: Select this option to enable the broker to send a message to other MQTT clients if the CPU loses its connection with the broker function. Enabling this option requires the following fields to be completed:

• Topic: Name of topic for Last Will and Testament (required if Last Will and Testament option is selected). The Topic can be static text (indicated by quotation marks on either side of the text) or a String tag.
• Payload: Content of Last Will and Testament (required if Last Will and Testament option is selected). The Payload can be static text (indicated by quotation marks on either side of the text) or a String tag.
• Retain Topic [optional]: Select this option if the broker should retain the Last Will and Testament
• Will QoS: Drop-down option that allows a value of 0 or 1 (default is 0). QoS (or Quality of Service) is an agreement between the sender and receiver of a message regarding the guarantee of delivering a message.

  i.  Connect QoS value of 0 (at most once) is the fastest method but also the most unreliable transfer mode because the CPU does not wait for the message to be acknowledged by the broker. With this QoS level the message will be delivered only one time, but possibly not at all, but there is no possibility of duplicate messages.

  ii.  Connect QoS value of 1 (at least once) causes the CPU to send a message and wait for an acknowledgment. This guarantees that the message will be delivered at least once, but it also means that it may be delivered more than once.

n. Subscriber / Publisher: For each MQTT Client, there must be at least 1 Publisher or Subscriber created. See Publisher and Subscriber Setup details in the sections below.

o. Certificate Verification: Default is No Encryption (Standard MQTT). The user can select between: 

• No Encryption
• Encrypt (No Verification)
• Encrypt (Single-sided Verification)
• Encrypt (Mutual Verification)

Note: If either Encrypt (Single-sided Verification) or Encrypt (Mutual Verification) are selected, then certificate and key files will be needed to match those of the MQTT broker. See the Secure MQTT (TLS) section below for more details on MQTT encryption and certificates.

Note: Certificate Verification/Encryption (MQTTS) is only available with P2-622 and newer (next-generation) CPUs.

Publisher Setup

a. Enable [REQUIRED]: Boolean tag that when true, sends the Publish message to the broker for the Publisher topics.

b. Publish Rate (1-1200 sec); Default value is 10:Any integer value between 1 and 1200 may be entered as an integer or integer tag. The Publish Rate is the frequency that the Publish message is sent to the broker.

c. QoS: Drop-down option that allows a value of 0 or 1. QoS (or Quality of Service) is an agreement between the sender and receiver of a message regarding the guarantee of delivering a message.

d. Success: Boolean tag that is set to true when the ACK message is received from the broker after a Publish message is sent. This tag should be reset in ladder to prepare for the next Publish message.

e. Error: Boolean tag that is set to true when an error is received from the broker after Publish message is sent. This tag is reset when Enable tag is set to false and may also be reset in ladder.

f. Error Code: Integer tag containing any error code received when sending a Publish message. This tag can be cleared/changed in ladder. This tag is reset to 0 when Enable tag is set to false and may also be cleared/changed in ladder.

g. Topic and Payload table:

• Broker Topics field allows up to 256 characters. This value can be static text (indicated by quotation marks on either side of the text) or a String tag.
• Payload can be static text (indicated by quotation marks on either side of the text) or a String tag.
• Retain checkbox allows each topic and payload to be retained by the broker.

Note: Up to 10 Topics and their corresponding payload options are allowed per Publisher. Wildcard topic filters (topics with “+” and “#” symbols) and $SYS topics are not supported.

Note: Network latency may cause MQTT communication issues and disconnect the client from the broker if an MQTT client is publishing or subscribing to large amounts data (i.e. topic and payload byte counts). In this case, it is recommended that the subscribing and/or publishing be divided between multiple MQTT clients. Maximum recommended topic/payload combinations, per MQTT client, in this situation, should be calculated using the following formula: - [[total number of publisher or subscriber topics] * 8] + [total topic + payload character count for all publisher or subscriber topics] less than or equal to 1448.

Example 1:

MQTT client 1

• Publisher1: 2 - 256 char topics each with 128 char payloads
• Publisher2: 1 - 256 char topic with 128 char payload
• Publisher3: 1 - 256 char topic with 8 char payload
• Total # topics = 4
• Total topic + payload character count = 2 * [256 + 128] + [256 + 128] + [256 + 8] = 1416

Formula: [4 * 8] + [1416] = 1448 (this should work fine if network latency is an issue)

 

Example 2:

MQTT client 1

• Publisher1: topics 1 thru 10 all have 74 char topic and 64 char payload
• Total # topics = 10
• Total topic + payload character count = 10 * [74 + 64] = 1380

Formula: [10 * 8] [1380] = 1460 (this may be an issue if there is network latency, especially with a public broker)”

Subscriber Setup

a. Enable [REQUIRED]: Boolean tag that when true, sends the Subscribe message to the broker and listens for the Publish messages from the broker for the Subscribed topics. Setting this tag to false sends an Unsubscribe message to the broker.

b. QoS: Drop-down option that allows a value of 0 or 1. QoS (or Quality of Service) is an agreement between the sender and receiver of a message regarding the guarantee of delivering a message.

c. Success: Boolean tag that is set to true when the ACK message is received from the broker after a Subscribe message is sent.

d. Error: Boolean tag that is set to true when an error is received while subscribed to a broker. This tag is reset when Enable tag is set to false and may also be reset in ladder.

e. Error Code: Integer tag containing any error code received while subscribed to a broker. This tag can be cleared / changed in ladder. This tag is reset when Enable tag is set to false and may also be reset in ladder.

f. Topic and Payload table:

• Broker Topics field allows up to 256 characters. This value can be statictext (indicated by quotation marks on either side of the text) or a String tag.
• Payload must be a single String tag. Contains data received for the corresponding topic.
• Received must be an integer tag. Indicates how many messages have been received for the corresponding topic. Tag value is not automatically reset and must be reset in ladder, if desired.

Note: Up to 10 topics and their corresponding payload options are allowed per Subscriber. Wildcard topic filters (topics with “+” and “#” symbols) and $SYS topics are not supported.

 

Secure MQTT (TLS)

In the Certificate Verification section of the MQTT Client Properties, the user can select between No Encryption, Encrypt (No Verification), Encrypt (Single-sided Verification), and Encrypt (Mutual Verification) options.

No Encryption

If No Encryption is selected the MQTT client and broker will communicate using plain text. All data exchanged will be easily visible if a data capture device or software is used to capture the data being exchanged. This option is only recommended where the MQTT client and broker are on a private network that has other methods of protection from unauthorized access.

Encrypt (No Verification)

If Encrypt (No Verification) is selected the MQTT client and broker will encrypt the data being exchanged using the broker’s CA signed Certificate (see below for more details on CA Certificates). During the initial establishment of the MQTT connection, the broker will send its CA signed Certificate to the client which the client will then use to encrypt the data that will be sent or received. This option is recommended if the broker is a known, secure, and trusted broker.

Encrypt (Single-sided Verification)

If Encrypt (Single-sided Verification) is selected, the MQTT client must provide the same CA Certificate that signed the MQTT broker certificate.

a. CA Certificate: A TLS certificate generated by a Certificate Authority which is a trusted entity that issues SSL (Secure Sockets Layer) certificates. This CA Certificate is used to validate the identity of the MQTT broker certificate. Use the Browse button to link to the appropriate file location.

Encrypt (Mutual Verification)

If Encrypt (Mutual Verification) is selected, the MQTT client must use a CA Certificate, Client Certificate, and Client Private key for the autthentication process.

a. CA Certificate: A TLS certificate generated by a Certificate Authority which is a trusted entity that issues SSL (Secure Sockets Layer) certificates. This CA Certificate is used to validate the identity of the MQTT broker certificate. Use the Browse button to link to the appropriate file location.

b. Client Certificate: Used to identify the MQTT client that is requesting a connection to the broker. Use the Browse button to link to the appropriate file location.

Note: the broker certificate is sometimes referred to as a server certificate.

c. Private Key: Used to encrypt data exchanged between the MQTT broker and client. The Private Key must be paired with the corresponding Public Key contained in the Client Certificate. Use the Browse button to link to the appropriate file location.

 

Timing Charts

 

Best Practices

• Never use a leading forward slash. A leading forward slash is permitted in MQTT. For example, “/Weather/USA/Springfield/Temperature”. However, the leading forward slash introduces an unnecessary topic level with a zero character at the front, which is not beneficial and often leads to confusion.
• Never use spaces in a topic. Spaces make it difficult to read and debug topics. As with leading forward slashes, just because something is allowed, doesn’t mean it should be used.
• Keep the topic short and concise. Each topic is included in every message in which it is used. Short and concise topics have a big impact when every byte counts.
• Use only ASCII characters and avoid non-printable characters. Non-ASCII characters often display incorrectly, which can make it very difficult to find typos or issues related to the character set. Unless absolutely necessary, avoid the use of non-ASCII characters in a topic.
• Embed a unique identifier or the Client ID into the topic. It can be very helpful to include the unique identifier of the publishing client in the topic. The unique identifier in the topic helps you identify who sent the message. The embedded ID can be used to enforce authorization. Only a client that has the same client ID as the ID in the topic is allowed to publish to that topic. For example, a client with the client1 ID is allowed to publish to client1/status, but not permitted to publish to client2/status.
• Don’t subscribe to #. Sometimes, it is necessary to subscribe to all messages that are transferred over the broker. For example, to persist all messages into a database. Do not subscribe to all messages on a broker by using an MQTT client and subscribing to a multi-level wildcard. Frequently, the subscribing client is not able to process the load of messages that results from this method (especially if you have a massive throughput). Best practice is to implement an extension in the MQTT broker.
• Don’t forget “extensibility”. Topics are a flexible concept and there is no need to preallocate them in any way. However, both the publisher and the subscriber need to be aware of the topic. It is important to think about how topics can be extended to allow for new features or products. For example, if your project adds new sensors, it should be possible to add these to your topic tree without changing the whole topic hierarchy.
• Use specific topics. When you name topics, differentiate the topics as much as possible. For example, if you have three sensors on your machine, create topics for “machine1/tank1/temperature", "machine1/tank1/level” and “machine1/tank1/weight”. Avoid sending all values over “machine1/tank1”.

Error Codes

The table shown below provides a list of MQTT error codes that may be reported by the Productivity CPU.

Productivity Suite MQTT Communication Error Codes