OPC UA PubSub JSON mapping component

Introduction

The OPC UA PubSub JSON mapping package (OpcLabs.UAPubSubJson) provides JSON mapping for OPC UA PubSub. It is needed 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).

Licensing

The OpcLabs.UAPubSubJson package depends on Newtonsoft.Json, which is licensed under MIT license. If you are targeting .NET Standard, this is nothing new because the Newtonsoft.Json package is already used by the OPC Foundation .NET Standard stack and SDK on which our software for .NET Standard depends. It might be a new license to comply with if you are using this package under .NET Framework, COM, or from product tools.

Installation

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.

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.

When developing a software in .NET (for .NET Framework, or targeting .NET Standard), you can add the available NuGet package (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 Redistributables.

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:

Send message mapping

The full name of the corresponding configuration part type is OpcLabs.UAPubSubJson.JsonSendMessageMapping.

Receive message mapping

The full name of the corresponding configuration part type is OpcLabs.UAPubSubJson.JsonReceiveMessageMapping.

Envelope mapping

The full name of the corresponding configuration part type is OpcLabs.UAPubSubJson.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:

• Property namespace: http://opclabs.com/OpcUA/PubSub
• 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 datatype: As given by the documentation below.
• Property value: The desired value.

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

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 {http://opclabs.com/OpcUA/PubSub}OpcLabs.UAPubSubJson.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 package.

Send message mapping

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

Property	Type	Default	Description
MessageFormattingParameters	OpcLabs.UAPubSubJson.Sdk.PubSub.JsonMessageFormattingParameters
MessageFormattingParameters.IndentChars	System.String	" " (two spaces)	The character string to use when indenting.
MessageFormattingParameters.PrettificationLevel	OpcLabs.UAPubSubJson.Sdk.PubSub.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.UAPubSubJson.Sdk.PubSub.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.