Using communication packages

Before you use any communication package, make sure you understand its licensing terms, and the licensing terms of any other software it depends on (recursively). If you are using the package from NuGet, the NuGet client will allow you to review the licensing terms for each software involved. In other cases (such as when the communication package comes preinstalled with other software, or when you are using the ZIP package), consult the corresponding documentation. You may still end up having to use a NuGet client (e.g. Visual Studio) and install a NuGet package, just for the purpose of reviewing the license terms.

Selecting the communication package

In order to use the chosen communication package in OPC UA PubSub tools, you need to select it by setting a custom property on a PubSub connection as follows:

• Property namespace: http://opclabs.com/OpcUA/PubSub
• Property name: MessageChannel!
• Property datatype: String
• Property value: The type name of the message channel object. See the communication package documentation (example: OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt).

How this is done depends on the concrete software you are using. The actual value is an assembly-qualified name, so if needed, you can specify the version of the assembly, its public key token, and so on.

EasyUASubscriber object

Usually, you will use the same communication package across your solution, but there is nothing that prevents you to use a different one with each PubSub connection, e.g. for compatibility reasons with different MQTT brokers.

UADemoPublisher tool

In UADemoPublisher, you set the custom property on a PubSub connection using the --ConnectionProperties (-cp) option. They key is in the form {url}name, where url is the property namespace, and name is the property name. For example, to publish messages using the OpcLabs.Mqtt communication package, you can use the following command:

UADemoPublisher --MqttUadpTcp --ConnectionProperties {http://opclabs.com/OpcUA/PubSub}MessageChannel!=OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt

As typing this in would be cumbersome, UADemoPublisher comes with several ready-made response files which contain the necessary settings for common MQTT communication packages. With the help of the response file, the command above can be shortened to:

UADemoPublisher --MqttUadpTcp @MessageChannel-Mqtt

Since the command-line option name is the same as in the "uaSubscriber subscribeDataSet" or "uaSubscriber subscribeDataSetField" commands in the OpcCmd tool, the same response files can be used for communication package selection as with the OpcCmd tool.

Configuring the communication package

The specific information necessary for establishing and maintaining the communication is provided by the host software. In addition to that, the communication packages typically have various configuration parameters that influence their behavior, and the parameters differ from package to package. The defaults are set in such a way that in most cases, you do not need to care about the configuration at all. If the configuration needs to be changed, the primary way of doing so is using the configuration properties. The names, types, and meaning of the configuration properties are described in the documentation of the communication package.

When assigning values to configuration properties, the value needs to be of the same type as the type of the property, or convertible to it. This is relatively easily achievable from programming tools (such as when using the EasyUASubscriber object). In command-line tools (such as OpcCmd, UADemoPublisher), the property values are given as strings, so only strings and types that can be converted from a string can be used. This should not normally be a problem. Conversions exist for all numeric types. Conversion for enumerations exists as well, and you can either use a string representation of the numerical value of the enumeration members, or its symbolic name (a string).

Beside programmatically accessible configuration properties, the communication package may provide other means of configuration, described in its documentation.

UADemoPublisher tool

with the default OpcLabs.MqttNet communication package

UADemoPublisher --MqttUadpTcp --ConnectionProperties {http://opclabs.com/OpcUA/PubSub}MessageChannel.MqttClientOptions.ProtocolVersion=V500