Configuring an MQTT Publisher

The MQTT protocol allows the OI Server and associated software to communicate with edge devices that have published MQTT data to an MQTT broker. The publisher functionality allows the OI Server to expose, and publish only the specific references that are configured for publishing purposes. Hence, the user can then select a specific set of references whose data will be published to the MQTT broker.

To configure an MQTT publisher, create and configure the hierarchy of the data source and groups. Use the proper item naming conventions in its client(s).

Ensure the following steps are completed before attempting to configure the MQTT publisher.

1. Configuring an OPC Data Source Object

2. Configuring an OPC Group Object

3. Configuring an MQTT Data Source Connection

4. Configuring an MQTT Group Connection

   Note: We recommend you to set up an MQTT Broker connection before configuring the MQTT Publisher. Refer Configuring an MQTT Data Source Connection section for steps to configure the MQTT Broker.

Workflow to configure an MQTT Publisher

Follow the workflow given below to configure an MQTT publisher.

Add an OPC Data Source Object to your OI Gateway Hierarchy

5. Right-click Configuration in the hierarchy, and select Add OPC Object from the shortcut menu. The following rules apply:

   • A new object is created in the hierarchy tree and is named New_OPC_000 by default (in "edit mode"). Rename it, if desired. You are allowed to add an unlimited number of OPC data sources. The object is named as OPC_001 in this example.

6. Configure the new OPC object according to the following option definitions:

   • Server Node – The computer node on which the specified data source can be found. Default value is localhost. Use the browse button to select from a list of all nodes on your network.

   • Server Name – ProgID or ClassID of the OPC server (example of a ProgID: OI.Gateway.1, ClassIDs are GUIDs). Use the browse button to select from a list of OPC server ProgIDs on your network. Default value is blank. We are using the OI.SIM.1 as the OPC server.

   • Reconnect Attempts – Number of times OI Gateway attempts to reconnect to the specified data source if a connection fails. The value (-1) means no limit to the number of attempts. The value Zero (0) means no attempts. Minimum/maximum range is -1 to 1,000,000. Default value is 3.

   • Reconnect Period –Delay (in ms) between reconnect attempts if a connection fails. Minimum/maximum range is 10,000 to 300,000 ms (corresponding to the range of 10 sec to 5 min). Default value is 30000 ms.

   • Poke Retries – Number of times OI Gateway attempts to retry the write operation if a write operation fails. The value zero (0) means no retry attempts. Minimum/maximum range is 0 to 100. Default value is zero (0).

   

For more information, see Configuring an OPC Data Source Object.

Note: Currently, only an OPC Data Source can be configured to publish data to an MQTT Broker.

Add an OPC Data Source Group Object

7. Select the new data source object (OPC_001), right-click it, and then click Add OPCGroup Object on the shortcut menu.

   • A new object is created in the hierarchy tree and is named New_OPCGroup_000 by default (in "edit mode").Rename it, if desired. You are allowed to add up to 100 negroup objects. We have renamed the group object to OPCGroup_1 in this example.

8. Configure the new group object according to the following option definitions:

   • Device Group Name – Name of the topic that DDE or SuiteLink clients of OI Gateway connect to in order to access items at the OPC group. Default value is the concatenation of the OPC data source object’s name and the group object’s name (this cannot be edited).

   • Update Rate – Value (in ms) used by OI Gateway to update the OPC group. Minimum/maximum range is 0 to 2147483646 ms. If the OPC server supports it, zero (0) update rate means the data source sends data changes immediately. If the server does not support zero update rate, it typically returns a message including information about its fastest possible update rate. Default value is 1000 ms.

     The update rate can also be adjusted at run time by setting the $SYS$OPCUpdateInterval system item.

   • OPC Item ID Prefix – String prefixed to all item names added to the OPC group. Default value is blank.Example: Item Prefix=40, Item=001, Item requested from data source=40001. In this instance, using the OI Sim server as the selected server, this value is entered as <PORT.PLC.>.

     

9. Save the configuration.

   For more information, see Configuring an OPC Group Object.

 

Add an MQTT Group Connection

10. Select the MQTT Broker connection (BROKER_01), right-click it, and then click Add MQTTGroup Connection on the shortcut menu.

    • A new MQTT group connection is created in the hierarchy tree and is named New_MQTTGroup_000 by default. Rename it, if desired. The group has been renamed to Group_1 in this example.

    • The Device Group Name field is automatically filled in and cannot be edited.The Device Group Name is used for accessing MQTT data from a DDE/SuiteLink client.

11. Select a level of Quality of Service (QoS) from the drop down list box.The QoS level determines message delivery parameters, with 0 as the lowest level of service, and 2 as the highest level.

    • 0 - At Most Once: The message is delivered no more than one time, meaning that it may not be delivered. There is no backup of the message, and if the connection to the client is lost, the message will not be delivered. No delivery acknowledgement is provided.

    • 1 - At Least Once: The message is delivered at least one time, but it may be delivered more than once if the sender does not receive an acknowledgement of a successful transmission. The sender stores the message until a receipt acknowledgement is received.

    • 2 - Exactly Once: The message is delivered one time only. The sender stores the message until it receives confirmation of receipt. This is the safest, and slowest, message transfer mode.

12. Under Identity, select the Enable checkbox and enter the user credentials (user name and password) for the group connection (optional).

13. Click the Validate Identity button to verify that the MQTT Broker can be accessed on the configured MQTT channel.

Note: Multiple groups can be added to a single MQTT broker.

Add an MQTT Reference Item

14. In the OPCGroup Object parameter, click the MQTT Publish Items tab.

    • Publish User Group: From the list of broker groups, select a broker group (BROKER_01.Group_1).

    • Unique Item ID: A unique item ID (UID) for the selected user group is automatically generated by the system. Rename it, if desired. The UID has been renamed to MB-1 in this example.

      Note: The characters + and # are considered invalid and cannot be used in the Unique Item ID.

15. To add a reference item, right click anywhere on the tabular space.

16. Select the Add command from the shortcut menu.

    • A device item is created, and it is numerically named by default. For example, Item_0, Item_1, and so on.

17. Change the default name by double-clicking on it and entering the new name.

    • Enter a unique name for the new device item (i1 in this example).

18. The MQTT Syntax column is automatically populated with the syntax of the format:

    <Unique Item ID>/<Reference Item>

    In this example, we have MB-1/i1.

19. Multiple reference items can be added for the selected Publish User Group.

    

20. Save the configuration.

Publish MQTT Information

21. To activate the OI Server, right click OI Gateway.1 and click Activate Server.

22. The server in this example, OI.SIM.1, activates automatically, as is had been configured as the server we want to use.

23. The MQTT information for the reference items is published and can be viewed in the following paths

    • OI.GATEWAY.1 > Diagnostics > Client Groups > MQTT Plugin

    • Wonderware – SIM > OI.SIM.1 > Diagnostics > Client group > OPC_001.OPCGroup_1.

24. Double click the row to display the Diagnostic info pop-up window showing the following parameters: Name, Client Value, Client Time, Quality, Location, Subscription Message and Device Group.