MQTT Client Driver
MQTT stands for Message Queuing Telemetry Transport
Never share a TCP/IP Port tag with multiple MQTT Client Drivers. Each driver must use its own port tag.
Do not use a Polling Driver with an MQTT driver. It is not possible to issue a poll for data because the MQTT driver works strictly on the basis of report by exception.
Redundant broker setup using DriverMUX
If a device is configured to use two redundant brokers, VTScada can accommodate this with the Driver Multiplexer tag and two MQTT drivers. The Driver Multiplexer should be configured with the following setup:
- Selection Mode -> Automatic
- Sequence Mode -> Parallel
- Failover Mode -> Switch Server First
- Write Mode -> Both Devices
- Ignore Data From Inactive Subordinate -> deselected
If configuring for redundant broker setup AND using Sparkplug B with the Automatic Tag Creation option enabled:
If the MQTT driver sees that it is a subordinate of a Driver Multiplexer, the automatic tag creation feature will place tags under the Driver Multiplexer instead of placing them under the MQTT driver. This ensures that the redundant broker, configured using a second MQTT tag and port, will use the same I/O tags.
If the MQTT driver was created and its child tags generated before being attached to a Driver Multiplexer, then when the MQTT driver is made a subordinate under a Driver Multiplexer a fresh set of the tags would be created under the Driver Multiplexer. The original tags are not moved and there is no link between history collected by the old tags and history collected by the new.
To avoid this situation, ensure that automatic tag creation is not selected / enabled in the MQTT driver until it has been linked as a subordinate driver to your Driver Multiplexer tag.
To repair this situation if it was not avoided, do the following:
- Deselect the automatic tag creation option in the MQTT driver.
- Delete the I/O tags that were generated below the Driver Multiplexer tag.
- Select all the I/O tags that are children of the MQTT driver.
- Cut.
- Paste those tags as children of the Driver Multiplexer tag.
- Re-enable the automatic tag creation option in the MQTT driver.
If nested Driver Multiplexers are used such that more than two redundant brokers are supported, automatic tag creation will place the tags under the topmost Driver Multiplexer.
History Addresses and Sparkplug B
If all of the following are true:
You are using the MQTT driver to read from a Sparkplug B device.
You are configuring I/O addresses yourself rather than letting the driver read them automatically.
The device sends messages that contain arrays of historical data.
Then...
Configure the History Address parameter of your I/O and Calculations tags to append the characters, $$History$$
If an array of data is sent to the Read address of an input tag (including legacy Status tags as well as the I/O and Calculations tag) then only the first value is read and the rest discarded. You must use the History address in order for the tag to process the full array.
Note also that the Read address and the History address must not be identical.
Example:
Read Address : spBv1.0/PT/DDATA/PTGateway/ET_EFB107_H_002++ACC00
History Address: spBv1.0/PT/DDATA/PTGateway/ET_EFB107_H_002++ACC00$$History$$
Determine whether a remote Sparkplug B device is online
If the broker tag's value (MQTT Driver instance) is 0 and any known good IO tag's value is equivalent to Invalid with Hold not enabled on the driver, then the field device for that IO tag is considered to be disconnected. The IO tag value would only be invalid if either a) no valid value for that tag was received after VTScada was started, OR b) following the receipt of a DEATH certificate, after which all IO tags associated with that device would be invalidated.
If the broker tag value is !=0, then the connection to the broker is disconnected.
MQTT Communication Messages Dialog
MQTT Client Driver Statistics Dialog
MQTT Client Driver properties ID tab
The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.
Name:
Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.
You may right-click on the tag's name to add or remove a conditional start expression.
Area
The area field is used to group similar tags together. By defining an area, you make it possible to:
- Filter for particular tag groups when searching in the tag browser
- Link dial-out alarm rosters to Alarm tags having a particular area
- Limit the number of tags loaded upon startup.
- Filter the alarm display to show only certain areas.
- Filter tag selection by area when building reports
When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)
To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.
You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).
To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.
There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).
Description
Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.
Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.
The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.
This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.
Help Search Key
Used only by those who have created their own CHM-format context sensitive help files to accompany their application.
Server List
Select (or create) a named server list.
MQTT Client Driver properties Connection tab
Set the communication properties of the driver with the following fields:
Port
Select the TCP/IP Port tag that holds the address information for the MQTT data source.
MQTT data is available only over TCP/IP connections.
When configuring your TCP/IP tag, note that port 1883 is reserved with IANA for use with MQTT. Port 8883 is registered with IANA for use with MQTT over a secured connection. Your data source may use a different port.
This port must not be shared with any other clients.
MQTT Client ID
Every MQTT client must have a unique identifier. This is generated for you using the following four components to guarantee uniqueness on the broker as well as across VTScada applications and within the same application across multiple machines
- Either of a configuration property called "MQTTClientIDPrefix" if set (useful for branding) or the string "VTScada"
- The application's GUID (guaranteed unique identifier)
- The workstation's unique identifier
- This tag's name
The Client ID may be edited, but do so with caution and only when a broker requires a specific ClientID to allow a connection to be established. Typically, this value must be machine-specific, but that will not be the case after editing.
If a custom value has been set, the edit button is grayed out. To return to the default of a VTScada-specified Client ID, unique to the current machine, delete the parameter and apply the change.
Sparkplug B SCADA Host ID
This field is generated automatically and is common to all instances of the MQTT Client Driver in an application. The SCADA Host ID should be entered into the EoN configuration of the remote device, if supported by that device.
This parameter is editable, but do not change unless necessary. If it is edited in a redundant broker configuration, then all drivers that are part of the redundancy must use the same value for the parameter.
Namespace Parameter
Allows the Sparkplug B subscription to be limited to a specific namespace instead of the root spBv1.0/#. This may be required by some brokers, or it can be used to limit what data is requested by the driver. The subscription becomes spBv1.0/namespace/#.
Keep Alive
Specifies the number of seconds, after which the connection will close if no new data is received.
Ensure that the Disconnect Delay in your TCP/IP Port tag is greater than the Keep Alive time set here.
QoS
QoS stands for Quality of Service and specifies an agreement between the sender and receiver of a message. Zero is the lowest quality and should be used for reliable connections and where you do not mind if the occasional message is lost. Use QoS 1 when you need to be sure that every message is sent and you have a system in place to handle duplicate messages. QoS 2 is the most reliable but (due to its nature) the slowest option, ensuring that every message is delivered exactly once.
Protocol
Select from JSON, XML, Sparkplug B, Pass Through, or Custom.
It is possible to configure the driver with one protocol, but then have an IO tag use a different protocol by specifying another Decoder in its address. Be aware that you cannot do Sparkplug communications unless the driver protocol is set to Sparkplug. You can use other protocols when in Sparkplug mode by specifying a Decoder in the address.
Timeout
Sets the length of time allowed for message processing before the attempt will timeout.
Must be between 0 and 90% of the Keep Alive time. While zero is allowed by the dialog, it is not advised.
Enable Auto Rewrite
If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.
Store Last Output Values
When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:
- For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
- When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.
If the last output values are stored, they may be re-written by either of two methods:
- Automatically, when communication is restored to the device.
- Manually by way of a button press. See, Rewrite Outputs Widget for details.
Changing this value from selected to deselected will cause all stored values to be erased immediately.
Hold
Select whether this driver should hold the last message received from the broker in the event of a communications failure.
Automatic Tag Creation Sparkplug B protocol only.
When selected, a hierarchy of Context and I/O tags will be created automatically under the driver tag whenever a BIRTH certificate is received.
After the tags are created, they can be modified as needed but should not be moved unless Automatic Tag Creation is disabled. Otherwise, new copies of the tags will be created in their place.
If using a Driver Multiplexer, refer to notes at the beginning of this topic for redundant broker setup. Ensure that automatic tag creation is OFF until you have finished driver configuration of both the MQTT driver and the Driver Multiplexer.
MQTT Client Driver properties Credentials tab
Use this tab to provide the user name and password if those are required to sign into the MQTT broker. (Not all brokers will require these.)
Username
The name required to sign in to the MQTT broker
Password
The password matching that user name. Passwords are never shown and are not stored in plain text. That said, security depends on ensuring that your link to the MQTT broker uses only a secure connection (TLS).
Hash Password with MD5
Select this option if the MQTT broker saves passwords using that algorithm. The password will be hashed before being sent to the broker.
MQTT Client Driver properties Last Will tab
This provides a mechanism for the broker to notify interested clients that the VTScada client has disconnected. For example, if you set the Last Will Message to "VTScada MQTT Client 1 has disconnected" and the Last Will Topic to be "VTScada/Client/1", then if your application disconnects from the broker for any reason, the broker will send all clients that have subscribed to the topic "VTScada/Client/1" a message saying " VTScada MQTT Client 1 has disconnected "
Last Will Topic
The topic should be specific to the device, although this is not mandatory. One way to do this is to include the device name as part of the topic.
Last Will Message
The information to be sent to the topic in the event of a disconnection. "Offline" is typical.
Last Will QoS
Specify the quality of service with which the Last Will should be sent. (See notes in the description of the Connection tab.)
Last Will Retain
Use a retained message to update the status of a device on a topic. New clients will see the last retained message.
MQTT Client Driver Tag Widgets
The following widgets are available to display information about your MQTT Client driver tags:
