OPC UA PubSub JSON mapping component: Difference between revisions

From OPC Labs Knowledge Base
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:OPC UA PubSub]]
[[Category:OPC UA PubSub]]
= Introduction =
= Introduction =
(tbd!!!)
The OPC UA PubSub JSON mapping component provides JSON mapping for OPC UA PubSub. It is invoked whenever JSON encoding is used in OPC UA PubSub, that is:
* With transport profiles that use JSON message mapping, such as when MQTT or AMQP is used with JSON.
* With transport profiles that use JSON in the message "envelope", such as MQTT version 5.0 (even when the message itself might not be encoded in JSON).


= Installation =
= Features =
With some software (such as the OpcCmd and UADemoPublisher tools), this package comes preinstalled; you do not have to do any additional installation steps before you can start working with it. In other cases, such as if you are developing your own software, you need to make sure that the package is properly installed.
== Output prettification ==
Instead of simply emitting a minimalistic JSON string on a single line and with no formatting, the OPC UA PubSub JSON mapping component (by default) prettifies the JSON messages by separating the lines and indenting them. This makes the output more readable and understandable by humans, but it also slightly increases the amount of data sent (length of messages). The level of prettification can be controlled by the configuration, or it can even be completely turned off.
== Automatic format recognition ==
OPC UA PubSub subscribers that implement the PubSub configuration model per OPC UA specification are expected to use certain settings from the PubSub configuration that give them the knowledge of how the JSON message is formatted. These settings are:
* JsonNetworkMessageContentMask
* JsonDataSetMessageContentMask
* DataSetFieldContentMask
Specifying the message format like this when you need to subscribe can be painful. The receive message mapping in the OPC UA PubSub JSON mapping component therefore uses (by default) an automatic recognition algorithm that does not require you to specify the format of the message upfront. The algorithm is capable of correctly recognizing the message format in vast majority of cases.


The 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 package alongside the assemblies of your own project.
You can turn off the automatic format recognition by setting a property in the component configuration. if you do so, remember then to properly set all the parameters in the PubSub configuration that influence the expected message format.
== Reversing the non-reversible ==
OPC UA defines two JSON encodings: reversible and non-reversible, and the OPC UA PubSub JSON mapping component supports them both. When you receive message encoded with OPC UA non-reversible JSON encoding, you must count with the fact that the non-reversible encoding is, well, non-reversible. That is, the precise OPC UA types and values of the data that the publisher has sent cannot always be reconstructed at the subscriber side. The OPC UA PubSub JSON mapping component (the receive message mapping) has an additional logic to "reverse" a range of encoded values that are normally non-reversible. For example, when the encoded value can be interpreted as a NodeId, StatusCode, QualifiedName or DataValue, it decodes it as such. Of course, given the design of the non-reversible encoding, this kind of "reversal" cannot be 100% reliable. The details of this process can be influenced by a configuration settings (including a possibility to turn it off altogether).


When developing a software in .NET (for .NET Framework, or targeting .NET Standard), you can add the available NuGet package ([https://www.nuget.org/packages/OpcLabs.UAPubSubJson OpcLabs.UAPubSubJson]) 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, you can unpack all files of the ZIP package to some directory, and reference the assemblies (or just the main assembly) from your project. When developing for COM, you unpack all files of the ZIP package to the output directory of your project. In QuickOPC, links to the various ZIP packages are available from the Launcher ("Start menu") under {{Style=menu|Redistributables}}.
= Configuration =
= Configuration =
The configuration of the OPC UA PubSub JSON mapping package consists of three parts that correspond to the three areas of functionality that the package provides:
The configuration of the OPC UA PubSub JSON mapping component consists of three parts that correspond to the three areas of functionality that the component provides:
; Send message mapping: The full name of the corresponding configuration part type is '''{{Style=Identifier|OpcLabs.UAPubSubJson.JsonSendMessageMapping}}'''.
; Send message mapping: The full name of the corresponding configuration part type is '''{{Style=Identifier|OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonSendMessageMapping}}'''.
; Receive message mapping: The full name of the corresponding configuration part type is '''{{Style=Identifier|OpcLabs.UAPubSubJson.JsonReceiveMessageMapping}}'''.
; Receive message mapping: The full name of the corresponding configuration part type is '''{{Style=Identifier|OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonReceiveMessageMapping}}'''.
; Envelope mapping: The full name of the corresponding configuration part type is '''{{Style=Identifier|OpcLabs.UAPubSubJson.JsonEnvelopeMapping}}'''.
; Envelope mapping: The full name of the corresponding configuration part type is '''{{Style=Identifier|OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonEnvelopeMapping}}'''.


In order to configure properties of the OPC UA PubSub JSON mapping package, you need to set one or more custom properties on a PubSub connection as follows:
In order to configure properties of the OPC UA PubSub JSON mapping component, you need to set one or more custom properties on a PubSub connection as follows:
* '''Property namespace''': http://opclabs.com/OpcUA/PubSub
* '''Property namespace''': http://opclabs.com/OpcUA/PubSub (can be shortened to {OpcLabs}, using a pre-defined replacement variable)
* '''Property name''': Full name of the configuration part type (see above), followed by "." and the property name from the documentation below. For example, the PubSub connection custom property name for the MessageFormattingParameters.PrettificationLevel property of the send message mapping will be "OpcLabs.UAPubSubJson.JsonSendMessageMapping.MessageFormattingParameters.PrettificationLevel".
* '''Property name''': Full name of the configuration part type (see above), followed by "." and the property name from the documentation below. For example, the PubSub connection custom property name for the MessageFormattingParameters.PrettificationLevel property of the send message mapping will be "OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonSendMessageMapping.MessageFormattingParameters.PrettificationLevel".
* '''Property datatype''': ''As given by the documentation below.''
* '''Property datatype''': ''As given by the documentation below.''
* '''Property value''': ''The desired value.''
* '''Property value''': ''The desired value.''
How this is done depends on the concrete software you are using.  
How this is done depends on the concrete software you are using.  
== EasyUASubscriber object ==
== 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 instruct the message parser to turn off the automatic recognition of message format, you can use the following code:
<syntaxhighlight lang="csharp">
UAPubSubConnectionDescriptor pubSubConnectionDescriptor = "mqtt://opcua-pubsub.demo-this.com";
pubSubConnectionDescriptor.TransportProfileUriString = UAPubSubTransportProfileUriStrings.MqttJson;
pubSubConnectionDescriptor.CustomPropertyValueDictionary[new UAQualifiedName("{OpcLabs}",
    "OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonReceiveMessageMapping.MessageParsingParameters.AutoRecognizeMessageFormat")] =
    false;
</syntaxhighlight>


== OpcCmd tool ==
== 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 [String]''stringValue''.
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''.


== UADemoPublisher 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 send JSON messages without any prettification, you can use the following command:
<pre>UADemoPublisher --MqttJsonTcp --ConnectionProperty &#123;&#123;OpcLabs}}OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonSendMessageMapping.MessageFormattingParameters.PrettificationLevel=[String]None</pre>
As typing this in would be cumbersome, UADemoPublisher comes with some response files for common cases like this. With the help of the response file, the command above can be shortened to one of the following:
<pre>
UADemoPublisher --MqttJsonTcp @JsonMessageFormatting-NoPrettification
UADemoPublisher -mjt @JsonMessageFormatting-NoPrettification
</pre>


= Parameters =
= Parameters =
This chapter describes the configurable parameters of the package.
This chapter describes the configurable parameters of the component.
== Send message mapping ==
== Send message mapping ==
The table below lists the available properties, their types, and descriptions.
The table below lists the available properties, their types, and descriptions.
Line 39: Line 65:
|-
|-
|MessageFormattingParameters
|MessageFormattingParameters
|OpcLabs.UAPubSubJson.Sdk.PubSub.JsonMessageFormattingParameters
|OpcLabs.EasyOpc.UA.Sdk.PubSub.Json.<br>JsonMessageFormattingParameters
|
|
|
|
Line 45: Line 71:
|MessageFormattingParameters.IndentChars
|MessageFormattingParameters.IndentChars
|System.String
|System.String
|" " ''(two spaces)''
|" &nbsp;&nbsp;" ''(two spaces)''
|The character string to use when indenting.
|The character string to use when indenting.
|-
|-
|MessageFormattingParameters.PrettificationLevel
|MessageFormattingParameters.PrettificationLevel
|OpcLabs.UAPubSubJson.Sdk.PubSub.JsonMessagePrettificationLevel
|OpcLabs.EasyOpc.UA.Sdk.PubSub.Json.<br>JsonMessagePrettificationLevel
|JsonMessagePrettificationLevel.DataSetMessageData
|JsonMessagePrettificationLevel.DataSetMessageData
|A value indicating how to prettify the output.
|A value indicating how to prettify the output.
Line 89: Line 115:
|-
|-
|MessageParsingParameters
|MessageParsingParameters
|OpcLabs.UAPubSubJson.Sdk.PubSub.JsonMessageParsingParameters
|OpcLabs.EasyOpc.UA.Sdk.PubSub.Json.<br>JsonMessageParsingParameters
|
|
|
|
Line 108: Line 134:
|Determines whether data set metadata will always be required for parsing.
|Determines whether data set metadata will always be required for parsing.
|}
|}
== Envelope mapping ==
== Envelope mapping ==
There are no parameters that can be set for the envelope mapping.
There are no parameters that can be set for the envelope mapping.

Latest revision as of 13:20, 30 May 2024

Introduction

The OPC UA PubSub JSON mapping component provides JSON mapping for OPC UA PubSub. It is invoked whenever JSON encoding is used in OPC UA PubSub, that is:

  • With transport profiles that use JSON message mapping, such as when MQTT or AMQP is used with JSON.
  • With transport profiles that use JSON in the message "envelope", such as MQTT version 5.0 (even when the message itself might not be encoded in JSON).

Features

Output prettification

Instead of simply emitting a minimalistic JSON string on a single line and with no formatting, the OPC UA PubSub JSON mapping component (by default) prettifies the JSON messages by separating the lines and indenting them. This makes the output more readable and understandable by humans, but it also slightly increases the amount of data sent (length of messages). The level of prettification can be controlled by the configuration, or it can even be completely turned off.

Automatic format recognition

OPC UA PubSub subscribers that implement the PubSub configuration model per OPC UA specification are expected to use certain settings from the PubSub configuration that give them the knowledge of how the JSON message is formatted. These settings are:

  • JsonNetworkMessageContentMask
  • JsonDataSetMessageContentMask
  • DataSetFieldContentMask

Specifying the message format like this when you need to subscribe can be painful. The receive message mapping in the OPC UA PubSub JSON mapping component therefore uses (by default) an automatic recognition algorithm that does not require you to specify the format of the message upfront. The algorithm is capable of correctly recognizing the message format in vast majority of cases.

You can turn off the automatic format recognition by setting a property in the component configuration. if you do so, remember then to properly set all the parameters in the PubSub configuration that influence the expected message format.

Reversing the non-reversible

OPC UA defines two JSON encodings: reversible and non-reversible, and the OPC UA PubSub JSON mapping component supports them both. When you receive message encoded with OPC UA non-reversible JSON encoding, you must count with the fact that the non-reversible encoding is, well, non-reversible. That is, the precise OPC UA types and values of the data that the publisher has sent cannot always be reconstructed at the subscriber side. The OPC UA PubSub JSON mapping component (the receive message mapping) has an additional logic to "reverse" a range of encoded values that are normally non-reversible. For example, when the encoded value can be interpreted as a NodeId, StatusCode, QualifiedName or DataValue, it decodes it as such. Of course, given the design of the non-reversible encoding, this kind of "reversal" cannot be 100% reliable. The details of this process can be influenced by a configuration settings (including a possibility to turn it off altogether).

Configuration

The configuration of the OPC UA PubSub JSON mapping component consists of three parts that correspond to the three areas of functionality that the component provides:

Send message mapping
The full name of the corresponding configuration part type is OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonSendMessageMapping.
Receive message mapping
The full name of the corresponding configuration part type is OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonReceiveMessageMapping.
Envelope mapping
The full name of the corresponding configuration part type is OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonEnvelopeMapping.

In order to configure properties of the OPC UA PubSub JSON mapping component, 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 configuration part type (see above), followed by "." and the property name from the documentation below. For example, the PubSub connection custom property name for the MessageFormattingParameters.PrettificationLevel property of the send message mapping will be "OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonSendMessageMapping.MessageFormattingParameters.PrettificationLevel".
  • Property datatype: As given by the documentation below.
  • 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, to instruct the message parser to turn off the automatic recognition of message format, you can use the following code:

UAPubSubConnectionDescriptor pubSubConnectionDescriptor = "mqtt://opcua-pubsub.demo-this.com";
pubSubConnectionDescriptor.TransportProfileUriString = UAPubSubTransportProfileUriStrings.MqttJson;

pubSubConnectionDescriptor.CustomPropertyValueDictionary[new UAQualifiedName("{OpcLabs}",
    "OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonReceiveMessageMapping.MessageParsingParameters.AutoRecognizeMessageFormat")] = 
    false;

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.

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 send JSON messages without any prettification, you can use the following command:

UADemoPublisher --MqttJsonTcp --ConnectionProperty {{OpcLabs}}OpcLabs.EasyOpc.UA.Toolkit.PubSub.Sdk.JsonSendMessageMapping.MessageFormattingParameters.PrettificationLevel=[String]None

As typing this in would be cumbersome, UADemoPublisher comes with some response files for common cases like this. With the help of the response file, the command above can be shortened to one of the following:

UADemoPublisher --MqttJsonTcp @JsonMessageFormatting-NoPrettification
UADemoPublisher -mjt @JsonMessageFormatting-NoPrettification

Parameters

This chapter describes the configurable parameters of the component.

Send message mapping

The table below lists the available properties, their types, and descriptions.

Property Type Default Description
MessageFormattingParameters OpcLabs.EasyOpc.UA.Sdk.PubSub.Json.
JsonMessageFormattingParameters
MessageFormattingParameters.IndentChars System.String "   " (two spaces) The character string to use when indenting.
MessageFormattingParameters.PrettificationLevel OpcLabs.EasyOpc.UA.Sdk.PubSub.Json.
JsonMessagePrettificationLevel
JsonMessagePrettificationLevel.DataSetMessageData A value indicating how to prettify the output.

The JsonMessagePrettificationLevel enumeration is defined in the following table:

Name Value Description
None 0 The JSON message is not prettified.
NetworkMessage 1 The message is prettified to the network message level.
NetworkMessageData 2 The message is prettified to the network message data level.
DataSetMessage 3 The message is prettified to the dataset message level.
DataSetMessageData 4 The message is prettified to the dataset message data level.

Receive message mapping

The table below lists the available properties, their types, and descriptions.

Property Type Default Description
MessageParsingParameters OpcLabs.EasyOpc.UA.Sdk.PubSub.Json.
JsonMessageParsingParameters
MessageParsingParameters.AutoRecognizeMessageFormat System.Boolean True Determines whether the message format will be automatically recognized when possible.
MessageParsingParameters.RecognizedNonReversibleBuiltInTypesMask System.Int32 NodeId, ExpandedNodeId, StatusCode,
QualifiedName, DataValue, DiagnosticInfo
The built-in types that be recognized when parsing the non-reversible JSON encoding.
MessageParsingParameters.RequireDataSetMetadata System.Boolean False Determines whether data set metadata will always be required for parsing.

Envelope mapping

There are no parameters that can be set for the envelope mapping.