MQTT Connection Tag

Introduction

The MQTT Connection Tag provides a SCADA communication channel to Message Queuing Telemetry Transfer (MQTT) server.

You can associate I/O Data Point Tags with an MQTT Connection Tag. When the association is made:

The IOItemName property of the I/O Data Tag is used as the topic name in the MQTT Broker.
Fernhill SCADA creates a subscription for each I/O Data Tag associated with the MQTT Connection Tag.
Values published by the MQTT Broker update the value of the I/O Data Point Tags.
A WriteValue Tag Command to the I/O Data Tag is published to the MQTT Broker.

Configuration Properties

The MQTT Connection Tag supports the properties of the Active Channel Tag plus these properties:

Property	Type	Version	Description
EnableDirectWrite	BOOL	3.25	Whether the DirectWrite tag commands are allowed on this tag.
HostName	WSTRING	3.22	The host name or IP address of the MQTT Broker.
MaxRxMessageSize	UDINT	3.22	The maximum size of message the MQTT driver will read from an MQTT Broker. If an MQTT Broker sends a message larger than this limit, the MQTT Driver will drop the connection. Following a disconnect event, the MQTT Driver will automatically try and reconnect to the MQTT Broker after a timeout period. Note: This value is clamped internally to the range 64 to 65536.
MaxTxMessageSize	UDINT	3.22	The maximum size of message sent by Fernhill SCADA to an MQTT Broker. If you make this value artificially small, you may see the following side effects: Tags with long topic names may fail to subscribe because the subscription request would exceed this limit. Write requests may fail if the Publish message exceeds this limit. Note: This value is clamped internally to the range 64 to 65536.
PortNumber	WSTRING	3.22	The port number used for communications. The default port number for MQTT is 1883.
UseTLS	BOOL	3.25	Whether the connection to the MQTT Broker uses TLS. If UseTLS is True, the connection uses TLS. If UseTLS is False, the connection does not use TLS (no encryption).
UserName	WSTRING	3.25	The username sent in the MQTT connection request
Password	WSTRING	3.25	The password value sent in the MQTT connection request. Note: The password value is encrypted and not stored as plain text.
PingInterval	TIME	3.22	The interval between each PING request sent from the Fernhill SCADA Driver to the MQTT Broker. See Interval and Offset for information on how Intervals and Offsets define the time of activities.
PingOffset	TIME	3.22	The offset added to the PingInterval to get the actual ping time. See Interval and Offset for information on how Intervals and Offsets define the time of activities.
LastWillOfflineValue	WSTRING	3.26	The value to publish to the LastWillTopic when the MQTT Driver disconnects from the MQTT Broker. If the LastWillTopic property is an empty string, this property has no effect.
LastWillOnlineValue	WSTRING	3.26	The value to publish to the LastWillTopic when the MQTT Driver connects to the MQTT Broker. If the LastWillTopic property is an empty string, this property has no effect.
LastWillTopic	WSTRING	3.26	The topic name used for the last will value in the MQTT Broker.

MQTT Security

Security in MQTT depends on how the MQTT Broker is configured. For successful communication, the configuration of the MQTT Connection Tag should match the configuration of your MQTT Broker. MQTT Brokers generally provide five security options:

Option	Description
Client ID Prefix	The MQTT Broker may require the Client ID to start with a prefix. Fernhill SCADA uses the prefix string FH in the Client ID sent in the connection request.
Username	The MQTT Broker may require a valid username sent in the connection request. In Fernhill SCADA, the UserName property configures the username sent in the connection request.
Password	The MQTT Broker may require a valid password sent in the connection request. In Fernhill SCADA, the Password property configures the password sent in the connection request. The password is not shown in diagnostic logs. If you monitor communication using the Data Log Window, the password will not be shown.
TLS	The MQTT Broker may require Transport Layer Security (TLS). In Fernhill SCADA, the UseTLS property configures whether TLS is used. If UseTLS is True, the driver will attempt the connection with TLS. If UseTLS is False, the driver will use TCP/IP without encryption.
Client Certificate	The MQTT Broker may require a valid client certificate during the Transport Layer Security (TLS) connection. Fernhill SCADA does not currently support a client Certificate.

Information: If you have configured a UserName or Password consider using Transport Layer Security (TLS). Transport Layer Security encrypts the connection between Fernhill SCADA and the MQTT Broker. Encryption helps to keep the UserName and Password fields private. Without encryption the username and password may be read by anyone who has access to the network.

Last Will

The LastWillTopic property is optional. If LastWillTopic property is configured it indicates if Fernhill SCADA is online or offline.

When Fernhill SCADA connects to the MQTT Broker, the MQTT driver does the following:

The LastWillTopic and LastWillOfflineValue properties are sent in the connection request in the Will Topic and Will Message fields.
The LastWillOnlineValue is published to the LastWillTopic.

When Fernhill SCADA disconnects from the MQTT Broker, the MQTT driver does the following:

The LastWillOfflineValue is published to the LastWillTopic.
The driver sends a DISCONNECT message to the MQTT Broker.

Note: In this clean disconnect scenario, the MQTT Broker deletes the Will Message without publishing it.

If the connection is lost between the MQTT Broker and Fernhill SCADA, The MQTT Broker does the following:

The LastWillOfflineValue (sent in the connection request) is published to the LastWillTopic.

Tag Commands

The MQTT Connection Tag supports the tag commands of the Active Channel Tag plus these tag commands:

Tag Command	Version	Description
DirectWriteBit	3.25	Directly publishes a boolean value to an MQTT topic. The boolean value is published as 'True' or 'False' depending on the value.
DirectWriteString	3.25	Directly publishes a string value to an MQTT topic.

Relationships to Other Tag Types

The MQTT Connection Tag builds on the features of these tag types:

Further Information

Active Channel Tag

To learn about the properties common to all active channels.

Alarm Conditions

To learn about abnormal conditions in SCADA applications.

Glossary

For the meaning of terms used in Fernhill SCADA.