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.

Choosing the communication package

In many cases, there is just one communication package that fits the given purpose. For example, OpcLabs.Pcap communication package is necessary with OPC UA PubSub when you want to use the Ethernet transport ("opc.eth" scheme), or read or write Wireshark capture files.

For MQTT: See MQTT communication packages .

Installing the communication package

With some software (such as the OpcCmd and UADemoPublisher tools), several communication packages are either built-in, or come preinstalled; you do not have to do any additional installation steps before you can start working with them. When this is not the case with the communication package you want to use, or you are developing your own software, you need to make sure that the communication package is properly installed.

Each communication package consists of one or more .NET assemblies. In runtime, the host software must be able to find and load these assemblies. This is usually assured by placing the assemblies of the communication package alongside the assemblies of your own project.

When developing a software in .NET (for .NET Framework, or targeting .NET Standard), when there is a NuGet package available, you can add it as a dependency to your project, and this in turn will include the necessary communication package's assemblies in the output of your project.

When developing in Python, when there is a NuGet package available, you can install it into your project, and/or add it to your requirements.txt file, and this in turn will include the necessary communication package's assemblies with your program.

When developing for COM, when there is a ZIP package available, on the top level of the package you will find directories with files for specific targets platforms (such as 'net472' or 'net6.0'). Unpack all files for your target platform you are using into the output directory of your project.

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 (can be shortened to {OpcLabs}, using a pre-defined replacement variable)
• 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

When you are using the EasyUASubscriber object, you set the custom property on a PubSub connection using the UAPubSubConnectionDescriptor.CustomPropertyValueDictionary (in the UADataSetSubscriptionDescriptor.ConnectionDescriptor passed to the EasyUASubscriber.SubscribeDataSet or similar method). The CustomPropertyValueDictionary is of type UAKeyValueDictionary, that is, a dictionary where the key is an OPC UA qualified name, and the value can be any value valid in OPC UA. For example, to subscribe to messages using the OpcLabs.Mqtt communication package, you can use the following code:

var subscriber = new EasyUASubscriber();
var dataSetSubscriptionDescriptor = new UADataSetSubscriptionDescriptor
{
    CommunicationParameters = { BrokerDataSetReaderTransportParameters = { QueueName = "opcuademo/uadp/none" } },
    ConnectionDescriptor =
    {
        CustomPropertyValueDictionary =
        {
            {new UAQualifiedName("{OpcLabs}", "MessageChannel!"), "OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt"}
        },
        ResourceAddress = "mqtt://opcua-pubsub.demo-this.com"
    }
};
subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor, (_, args) => Console.WriteLine(args));

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.

OpcCmd tool

In "uaSubscriber subscribeDataSet" or "uaSubscriber subscribeDataSetField" commands in the OpcCmd tool (Using OpcCmd Utility as OPC UA PubSub Subscriber), you set the custom property on a PubSub connection using the --ConnectionProperty (-cp) option. They key is in the form {url}name, where url is the property namespace, and name is the property name. The value is in the form [uaBuiltInType]value. For example, to subscribe to messages using the OpcLabs.Mqtt communication package, you can use the following command:

OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org --BrokerQueueName opcuademo/uadp/none --ConnectionProperty {{OpcLabs}}MessageChannel!=[String]OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt

As typing this in would be cumbersome, OpcCmd 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 one of the following:

OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org --BrokerQueueName opcuademo/uadp/none @MessageChannel-Mqtt
OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org -bqn opcuademo/uadp/none @MessageChannel-Mqtt

Since the syntax of this command-line option is the same as in the UADemoPublisher tool, the same response files can be used for communication package selection as with the OpcCmd tool.

UADemoPublisher tool

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

UADemoPublisher publish --MqttUadpTcp --ConnectionProperty {{OpcLabs}}MessageChannel!=[String]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 one of the following:

UADemoPublisher publish --MqttUadpTcp @MessageChannel-Mqtt
UADemoPublisher publish -mut @MessageChannel-Mqtt

Since the syntax of this command-line option 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. In programming tools (such as when using the EasyUASubscriber object), you can usually easily provide the precise type directly. In command-line tools (such as OpcCmd, UADemoPublisher), the property values are given as typed values, that is, preceded by the name of the built-in type in brackets, such as [String].SomeValue, which usually allows you to specify the precise type as well. In case the precise type is not used, many conversions exist, e.g. 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 member, or its symbolic name (a string). For values of type System.Boolean, you can use a string False or True (case-insensitive). In fact, it is sometimes beneficial to use the conversion from string values, because you may not want or be able to reference the types from the assemblies of the underlying library of the communication package.

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

In order to configure properties of the selected communication package in OPC UA PubSub tools, you need to set one or more custom properties on a PubSub connection as follows:

• Property namespace: http://opclabs.com/OpcUA/PubSub (can be shortened to {OpcLabs}, using a pre-defined replacement variable)
• Property name: Full name of the message channel configuration part type (which is usually the same as the full name of the message channel type itself), followed by "." and the property name from the communication package documentation. For example, the PubSub connection custom property name for the MqttClientOptions.ProtocolVersion property of the OpcLabs.MqttNet communication package will be "OpcLabs.MqttNet.ManagedMqttClientMessageChannel.MqttClientOptions.ProtocolVersion".
• Property datatype: As given by the communication package documentation.
• Property value: The desired value.

How this is done depends on the concrete software you are using.

EasyUASubscriber object

When you are using the EasyUASubscriber object, you set the custom property on a PubSub connection using the UAPubSubConnectionDescriptor.CustomPropertyValueDictionary (in the UADataSetSubscriptionDescriptor.ConnectionDescriptor passed to the EasyUASubscriber.SubscribeDataSet or similar method). The CustomPropertyValueDictionary is of type UAKeyValueDictionary, that is, a dictionary where the key is an OPC UA qualified name, and the value can be any value valid in OPC UA. For example, with the default OpcLabs.MqttNet communication package, you can use the following code to set the MQTT protocol version to 5.0:

var subscriber = new EasyUASubscriber();
var dataSetSubscriptionDescriptor = new UADataSetSubscriptionDescriptor
{
    CommunicationParameters = { BrokerDataSetReaderTransportParameters = { QueueName = "opcuademo/uadp/none" } },
    ConnectionDescriptor =
    {
        CustomPropertyValueDictionary =
        {
            {new UAQualifiedName("{OpcLabs}", "OpcLabs.MqttNet.ManagedMqttClientMessageChannel.MqttClientOptions.ProtocolVersion"), "V500"}
        },
        ResourceAddress = "mqtt://test.mosquitto.org"
    }
};
subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor, (_, args) => Console.WriteLine(args));

OpcCmd tool

In "uaSubscriber subscribeDataSet" or "uaSubscriber subscribeDataSetField" commands in the OpcCmd tool (Using OpcCmd Utility as OPC UA PubSub Subscriber), you set the custom property on a PubSub connection using the --ConnectionProperty (-cp) option. They key is in the form {url}name, where url is the property namespace, and name is the property name. The value is in the form [uaBuiltInType]value. For example, with the default OpcLabs.MqttNet communication package, you can use the following command to set the MQTT protocol version to 5.0:

OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org --BrokerQueueName opcuademo/uadp/none --ConnectionProperty {{OpcLabs}}OpcLabs.MqttNet.ManagedMqttClientMessageChannel.MqttClientOptions.ProtocolVersion=[String]V500

Some response files come with the tool to make the typing easier, for frequently used configuration tasks with common communication packages.

UADemoPublisher tool

In UADemoPublisher (UADemoPublisher Basics), you set the custom property on a PubSub connection using the --ConnectionProperty (-cp) option. They key is in the form {url}name, where url is the property namespace, and name is the property name. The value is in the form [uaBuiltInType]value. For example, with the default OpcLabs.MqttNet communication package, you can use the following command to set the MQTT protocol version to 5.0:

UADemoPublisher publish --MqttUadpTcp --ConnectionProperty {{OpcLabs}}OpcLabs.MqttNet.ManagedMqttClientMessageChannel.MqttClientOptions.ProtocolVersion=[String]V500

Some response files come with the tool to make the typing easier, for frequently used configuration tasks with common communication packages.