View source for Using communication packages

[[Category:Communication packages]] [[Category:OPC UA PubSub]]
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 ==
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 for .NET Framework, as an alternative, when there is a ZIP package available, you can unpack all its files to some directory, and reference the assemblies (or just the main assembly) from your project.
When developing for COM, when there is a ZIP package available, you unpack all its files to 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
* '''Property name''': MessageChannel!
* '''Property datatype''': String
* '''Property value''': ''The type name of the message channel object. See the communication package documentation (example: {{Style=Identifier|OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt}}).''
How this is done depends on the concrete software you are using. The actual value is an [https://docs.microsoft.com/en-us/dotnet/api/system.type.assemblyqualifiedname 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 {{Style=Identifier|UAPubSubConnectionDescriptor}}.{{Style=Identifier|CustomPropertyValueDictionary}} (in the {{Style=Identifier|UADataSetSubscriptionDescriptor}}.{{Style=Identifier|ConnectionDescriptor}} passed to the {{Style=Identifier|EasyUASubscriber}}.{{Style=Identifier|SubscribeDataSet}} or similar method). The {{Style=Identifier|CustomPropertyValueDictionary}} is of type {{Style=Identifier|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:
<syntaxhighlight lang="csharp">
var subscriber = new EasyUASubscriber();
var dataSetSubscriptionDescriptor = new UADataSetSubscriptionDescriptor
{
    CommunicationParameters = { BrokerDataSetReaderTransportParameters = { QueueName = "opcuademo/uadp/none" } },
    ConnectionDescriptor =
    {
        CustomPropertyValueDictionary =
        {
            {new UAQualifiedName("http://opclabs.com/OpcUA/PubSub", "MessageChannel!"), "OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt"}
        },
        ResourceAddress = "mqtt://test.mosquitto.org"
    }
};
subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor, (_, args) => Console.WriteLine(args));
</syntaxhighlight>
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 --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 subscribe to messages using the [[OpcLabs.Mqtt communication package]], you can use the following command:
<pre>OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org --BrokerQueueName opcuademo/uadp/none --ConnectionProperties {http://opclabs.com/OpcUA/PubSub}MessageChannel!=OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt</pre>
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:
<pre>
OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org --BrokerQueueName opcuademo/uadp/none --ConnectionProperties @MessageChannel-Mqtt
OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org -bqn opcuademo/uadp/none -cp @MessageChannel-Mqtt
</pre>
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 --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:
<pre>UADemoPublisher --MqttUadpTcp --ConnectionProperties {http://opclabs.com/OpcUA/PubSub}MessageChannel!=OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt</pre>
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:
<pre>
UADemoPublisher --MqttUadpTcp --ConnectionProperties @MessageChannel-Mqtt
UADemoPublisher -mut -cp @MessageChannel-Mqtt
</pre>
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. 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 member, or its symbolic name (a string). For values of type System.Boolean, use strings False or True (case-insensitive).

Beside 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
* '''Property name''': ''"MessageChannel.", followed by 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 MessageChannel.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 ===

=== 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 --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, with the default [[OpcLabs.MqttNet communication package]], you can use the following command to set the MQTT protocol version to 5.0:
<pre>OpcCmd uaSubscriber subscribeDataSet mqtt://test.mosquitto.org --BrokerQueueName opcuademo/uadp/none --ConnectionProperties {http://opclabs.com/OpcUA/PubSub}MessageChannel.MqttClientOptions.ProtocolVersion=V500</pre>
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 --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, with the default [[OpcLabs.MqttNet communication package]], you can use the following command to set the MQTT protocol version to 5.0:
<pre>UADemoPublisher --MqttUadpTcp --ConnectionProperties {http://opclabs.com/OpcUA/PubSub}MessageChannel.MqttClientOptions.ProtocolVersion=V500</pre>
Some response files come with the tool to make the typing easier, for frequently used configuration tasks with common communication packages.