Difference between revisions of "UADemoPublisher Basics"

From OPC Labs Knowledge Base
Jump to navigation Jump to search
Line 233: Line 233:
 
= Receiving Messages =
 
= Receiving Messages =
  
You can use any compliant OPC UA PubSub subscriber to receive and process messages from the UADemoPublisher. It needs to be configured, of course, according to format and contents of the messages sent by the UADemoPublisher. For ethernet and UDP transport protocol mappings, the subscriber, regardless of its type, needs to be either on the same computer as the UADemoPublisher (for simplest test), or on the same local subnetwork, or you need to configure the multicast routing appropriately.
+
You can use any compliant OPC UA PubSub subscriber to receive and process messages from the UADemoPublisher. It needs to be configured, of course, according to format and contents of the messages sent by the UADemoPublisher. For Ethernet and UDP transport protocol mappings, the subscriber, regardless of its type, needs to be either on the same computer as the UADemoPublisher (for simplest test), or on the same local subnetwork, or you need to configure the multicast routing appropriately.
  
 
Examples in the QuickOPC documentation show how to use the '''EasyUASubscriber''' object, and other QuickOPC facilities, to subscribe to messages generated by the UADemoPublisher.
 
Examples in the QuickOPC documentation show how to use the '''EasyUASubscriber''' object, and other QuickOPC facilities, to subscribe to messages generated by the UADemoPublisher.

Revision as of 22:05, 4 February 2020

Introduction

The UADemoPublisher program is a demonstration publisher for OPC UA PubSub.

UADemoPublisher is a console application, running on .NET. It is available for .NET Framework (Windows only), or .NET Core (Windows or Linux). It is available free of charge (does not require a license for QuickOPC or other OPC Labs product).

This version supports following transport protocol mappings:

  • OPC UA UDP (UADP over UDP; IPv4 or IPv6)
  • OPC UA Ethernet (UADP over Ethernet; with or without VLAN tagging)
  • OPC UA MQTT (UADP or JSON)

Security is not supported. Discovery is not supported.

Note2-icon.png

Note: This page describes a preliminary version (5.57.0.12) of the program; the behavior is subject to change in future versions. We plan to add more features and mappings in the future.

Installation

If you have installed QuickOPC (version 2019.2 or later) using its Setup program, and have not excluded the Tools setup component, the UADemoPublisher is already installed on your computer, under the Bin subfolder of the QuickOPC installation folder. There are also shortcuts to it from the Start menu and the Launcher program. In other cases, for stand-alone installation, and for latest version of the tool, see Tool Downloads. If you want to use OPC UA PubSub Ethernet transport protocol mapping, you will also need

See also: OPC UA PubSub Common Traps And Pitfalls

Technical Support

For technical support, use the corresponding category on our Online Forums.

Usage

In order to run the UADemoPublisher, open a command prompt, and switch to the directory that contains the program. You can start the program without any additional parameters. If you are using the .NET Framework version, type UADemoPublisher and press Enter. If you are using the .NET Core version, type dotnet UADemoPublisher.dll and press Enter. In the text that follows, when discussing the command line options, we will be listing the commands simply with the UADemoPublisher at the beginning; remember to use dotnet UADemoPublisher.dll in .NET Core instead.

The published data sets and the way they are published are hard-coded into the program and cannot be changed (for most part).

After the program starts, it prints out a summary of the configuration it uses when publishing the datasets, and then continuously displays a statistics of messages sent on each configured connection.

By default, the UADemoPublisher sends messages to IPv4 multicast address 239.0.0.1. This can be changed using the --ConnectionResourceUri (-cru) option (see further below). If you have multiple network interfaces and the messages do not get sent to the one you want, use the --ConnectionNetworkInterface (-cni) command-line option to specify the interface name.

The UADemoPublisher runs until you interrupt it using the X key, or until a given time period elapses. This time period can be configured using the wait sub-command. You can also use Ctrl+Break key combination to terminate the UADemoPublisher at any time, but without giving it a chance to perform any finalization tasks.

Command-line Options

Parameters of the UADemoPublisher can be influenced by various options given on its command line. The commands are case insensitive. The options are case sensitive, and can be entered using the long form (starts with --) or the short form (starts with -).

UADemoPublisher supports parsing of response files. Arguments beginning with '@' are treated as a file path to a response file. A response file contains additional arguments that will be treated as if they were passed in on the command line. Response files can have comments that begin with the # symbol. Each argument or option in the response file needs to be on its own line.

The options are (obtained through UADemoSubscriber --help):

OPC Labs OPC-UA Demo Publisher 5.57.0.12
Usage: UADemoPublisher [options] [command]

Options:
  -?|-h|--help                                                                Show help information
  -eth|--Ethernet                                                             Presets for Ethernet (no tagging), opc.eth://eth-broadcast
  -ethv|--EthernetVlan                                                        Presets for Ethernet with VLAN tagging, opc.eth://eth-broadcast:2
  -mjt|--MqttJsonTcp                                                          Presets for MQTT JSON over TCP, mqtt://test.mosquitto.org
  -mjts|--MqttJsonTls                                                         Presets for MQTT JSON over TLS, mqtts://test.mosquitto.org
  -mjw|--MqttJsonWs                                                           Presets for MQTT JSON over WebSocket, ws://test.mosquitto.org:8080/mqtt
  -mjws|--MqttJsonWss                                                         Presets for MQTT JSON over WSS, wss://test.mosquitto.org:8081/mqtt
  -mut|--MqttUadpTcp                                                          Presets for MQTT UADP over TCP, mqtt://test.mosquitto.org
  -muts|--MqttUadpTls                                                         Presets for MQTT UADP over TLS, mqtts://test.mosquitto.org
  -muw|--MqttUadpWs                                                           Presets for MQTT UADP over WebSocket, ws://test.mosquitto.org:8080/mqtt
  -muws|--MqttUadpWss                                                         Presets for MQTT UADP over WSS, wss://test.mosquitto.org:8081/mqtt
  -udp                                                                        Presets for UDP over IPv4 (default)
  -udp6                                                                       Presets for UDP over IPv6, opc.udp://ip6-allnodes
  -bqn|--BrokerQueueName <name>                                               Broker queue name (default opcuademo/uadp/none)
  -brdg|--BrokerRequestedDeliveryGuarantee <guarantee>                        Broker requested delivery guarantee (default AtLeastOnce)
  -cni|--ConnectionNetworkInterface <name>                                    PubSub connection network interface
  -cp|--ConnectionProperty <uaKey-uaValue-pair>                               PubSub connection property (*)
  -cru|--ConnectionResourceUri <uri>                                          PubSub connection resource URI (default opc.udp://239.0.0.1)
  -ctpn|--ConnectionTransportProfileName <uaPubsubTpn>                        PubSub connection transport profile name
  -ctpu|--ConnectionTransportProfileUri <uri>                                 PubSub connection transport profile URI
  -pib|--PublisherIdBase <uint16>                                             Publisher Id base (default 30)
  -gv|--GroupVersion <uint32>                                                 Group version (default 615377159 = 7/2/2019 10:05:59 AM)
  -kat|--KeepAliveTime <double>                                               Keep-alive time (milliseconds, default 2000)
  -kfc|--KeyFrameCount <uint32>                                               Key frame count (>= 1, only where applicable, default 25)
  -mnms|--MaximumNetworkMessageSize <uint32>                                  Maximum network message size (0 = no limit, default 65507)
  -pi|--PublishingInterval <double>                                           Publishing interval (milliseconds, default 500)
  -sgi|--SecurityGroupId <name>                                               Security group Id (default MySecurityGroup)
  -sksu|--SecurityKeyServiceUri <uri>                                         Security key service URI ("compute:" for built-in simulation)
  -sksun|--SecurityKeyServiceUserName <string>                                Security key service user name token - user name
  -sksup|--SecurityKeyServiceUserPassword <string>                            Security key service user name token - user password
  -sm|--SecurityMode <None/Sign/SignAndEncrypt>                               Security mode (default None)
  -wgp|--WriterGroupProperty <uaKey-uaValue-pair>                             Writer group property (*)
  -sp|--SetProperty <key-value-pair>                                          Set property to a given value (<path>=<value>, see documentation) (*)
  -au|--ApplicationUri <uri>                                                  Application URI
  -ec|--EnabledConnection <name>                                              Enabled PubSub connection (*)
  -edsw|--EnabledDataSetWriter <name>                                         Enabled data set writer (*)
  -ewg|--EnabledWriterGroup <name>                                            Enabled writer group (*)
  -x-cs-ai|--X-CertificateSecurity-AllowInteraction <bool>                    Certificate security: Allow interaction (default True)
  -x-cs-as|--X-CertificateSecurity-AllowStatic <bool>                         Certificate security: Allow static (default True)
  -x-cs-lcfn|--X-CertificateSecurity-LocalCertsFileName <string>              Certificate security: Local certs: File name (*)
  -x-cs-lcfv|--X-CertificateSecurity-LocalCertsFindValue <string>             Certificate security: Local certs: Find value
  -x-cs-lcsl|--X-CertificateSecurity-LocalCertsStoreLocation <storeLocation>  Certificate security: Local certs: Store location (default CurrentUser)
  -x-cs-lcsn|--X-CertificateSecurity-LocalCertsStoreName <storeName>          Certificate security: Local certs: Store name (default My)
  -x-cs-lcft|--X-CertificateSecurity-LocalCertsFindType <findType>            Certificate security: Local certs: Find type (default FindByThumbprint)
  -x-cs-lcst|--X-CertificateSecurity-LocalCertsSourceTypes <sourceTypes>      Certificate security: Local certs: Source types
  -x-cs-rpaa|--X-CertificateSecurity-RemotePolicyAcceptAny <bool>             Certificate security: Remote policy: Accept any certificate
  --commandLine                                                               Display a copy of the command line used
  --pause                                                                     Suspend the processing after running a command

Commands:
  about                                                                       Displays software information and legal notices
  more                                                                        Enter options for additional configuration part (up to 5 levels)
  saveConfiguration|sc                                                        Save the configuration data, as specified, to a file
  wait                                                                        Specifies how long will the parent command execute (default Infinite)

Run 'UADemoPublisher [command] --help' for more information about a command.
Use 'UADemoPublisher @<file>' to read arguments from a response file.
(*) Indicates options that can be specified multiple times with multiple values.

Parameter values:
  <key-value-pair>      <key>=<value>
  <guarantee>           NotSpecified|BestEffort|AtLeastOnce|AtMostOnce|ExactlyOnce
  <clarkNotation>       [{<url>}]<name>
  <uaBuiltInType>       Null|Boolean|SByte|Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64|Float|Double|String|DateTime|Guid|ByteString|XmlElement|NodeId|ExpandedNodeId|StatusCode|QualifiedName|LocalizedText|ExtensionObject|DataValue|Variant|DiagnosticInfo|Number|Integer|UInteger|Enumeration
  <uaKey-uaValue-pair>  <clarkNotation>=<ua-value>
  <uaPubsubTpn>         AmqpJson|AmqpUadp|EthUadp|MqttJson|MqttUadp|UdpUadp
  <uaValue>             [<uaBuiltInType>]<value>
  <findType>            FindByThumbprint|FindBySubjectName|FindBySubjectDistinguishedName|FindByIssuerName|FindByIssuerDistinguishedName|FindBySerialNumber|FindByTimeValid|FindByTimeNotYetValid|FindByTimeExpired|FindByTemplateName|FindByApplicationPolicy|FindByCertificatePolicy|FindByExtension|FindByKeyUsage|FindBySubjectKeyIdentifier
  <sourceTypes>         None|File|PkiStore[,None|File|PkiStore]...
  <storeLocation>       CurrentUser|LocalMachine
  <storeName>           AddressBook|AuthRoot|CertificateAuthority|Disallowed|My|Root|TrustedPeople|TrustedPublisher

The --ConnectionTransportProfileUri (-ctpu) does not have to be specified if it can be inferred from the --ConnectionResourceUri (-cru; for example, opc.udp and opc.eth schemes in the --ConnectionResourceUri imply the transport profile unambiguously, and therefore you do not have to specify --ConnectionTransportProfileUri with them).

Parameters such as --KeepAliveTime or --KeyFrameCount affect all targets where they can apply; you can cannot specify them differently for individual connections, writer groups or dataset writers. When, for example, a fixed header layout does not allow the use of delta frames, the key frame count is always 1 on such writer groups, regardless of what you specify in the parameter. It should therefore be not possible to "break" the header layout contract by improperly setting any of the parameters available.

Several "pre-set" options are available to make the demoing of OPC UA PubSub easy without having to specify multiple complicated parameters. The presets include:

-udp 
UDP over IPv4. Publishes on opc.udp://239.0.0.1 .
-udp6 
UDP over IPv6. Publishes on opc.udp://ip6-allnodes (same as opc.udp://[ff02::1], see Enhanced Host Name Resolution).
--Ethernet (-eth) 
Ethernet with no tagging. Publishes on opc.eth://eth-broadcast (same as opc.eth://FF-FF-FF-FF-FF-FF, see Enhanced Host Name Resolution).
--EthernetVlan (-ethv) 
Ethernet with VLAN tagging. Publishes on opc.eth://eth-broadcast:2 (same as opc.eth://FF-FF-FF-FF-FF-FF:2, see Enhanced Host Name Resolution).

PubSub Configuration

The configuration of the UADemoPublisher is based on the setup used on OPC UA PlugFests and Interoperability Workshops. There are following published data sets:

Simple
4 fields. A boolean, 32-bit integers, and a DateTime.
AllTypes
9 fields. Types are suitable for fixed layout (raw encoding). Includes signed and unsigned integers of various sizes, and 4-byte/8-byte floats.
MassTest
100 fields, all unsigned 32-bit integers.
AllTypes-Dynamic
16 fields. Compared to AllTypes, it adds 64-bit integers, a string, a byte string, a GUID, and an array of (unsigned 32-bit) integers.

The UADemoPublisher uses following writer groups (each on its own PubSubConnection):

FixedLayoutGroup (default publisher ID is 30, as UInt16)
Uses the "Message headers for periodic data with fixed layout" as per OPC UA Amendment 6. Among other characteristics, the fields use raw encoding.
DynamicLayoutGroup (default publisher ID is 31, as UInt64)
Uses the "Message headers for Events and Data with dynamic layout" as per OPC UA Amendment 6. The fields in Data messages are encoded as DataValue-s, with StatusCode and SourceTimestamp. We have also included an Event message writer, which uses the Simple dataset for its event fields.
FlexibleLayoutGroup (default publisher ID is 32, as String)
This group uses a "made up" header profile, with following basic characteristics: PublisherID, PayloadHeader, DataSetClassId and PromotedFields (not currently implemented) included in the UADP network message. Dataset fields are encoded as Variant-s, KeyFrameCount is 1, and the UADP dataset message does not contain any additional fields (timestamps or versions).

The publisher IDs used by the PubSub connections are always in an incrementing sequence (30, 31, 32 by default); the first number in the sequence can be changed using the --PublisherIdBase (-pib) command-line option. Parameters such as the publishing interval (defaults to 500 milliseconds), keep-alive time or key frame count can be changed using other options.

Saving the Configuration

Many OPC UA PubSub subscribers have the ability to import PubSub configuration data from a file in UA binary format. This can be used to making it easier to configure the subscriber in terms of connections, reader groups, and dataset readers. The file also contains dataset metadata, and thus allows decoding of message that use the raw encoding.

The UADemoPublisher can generate the PubSub configuration file that corresponds to published messages. To do so, specify the saveConfiguration command on the UADemoPublisher command line. You can place the options that modify the configuration before the command. The configuration will be saved with contents according to the options specified. By default, the configuration is saved into a file named UADemoPublisher.uabinary in the program's directory. You can use the command-line option --FileName (-fn), placed after the saveConfiguration command, to specify a different file name. Default file name extension is .uabinary.

The UADemoPublisher can also save the configuration in an XML format. This format is created by serializing the PubSub configuration file using the standarding XML encoding of OPC UA, but it isn't standardized by itself. To save the configuration in the XML format, specify the --FileFormat (-ff) command-line option after the saveConfiguration, with value "XML". When the XML file format is used, the default file name extension is .xml.

Examples

Do not use delta frames (only key frames):

UADemoPublisher -kfc 1

Send all messages to IP multicast address 224.0.2.0:

UADemoPublisher -cru opc.udp://224.0.2.0

Send all messages to IPv6 multicast address ff02::1 (all nodes on the local network segment):

UADemoPublisher -cru opc.udp://[ff02::1]

Send all messages to Ethernet broadcast address, using VID (VLAN identifier) 1000 and PCP (Priority Code Point) 3 (CA, critical applications):

UADemoPublisher -cru opc.eth://FF-FF-FF-FF-FF-FF:1000.3

Send all messages through network interface "Ethernet" (you can leave out the double-quotes if there are no spaces in the interface name):

UADemoPublisher -cni "Ethernet"

Only enable the MassTestWriter in DynamicLayoutGroup:

UADemoPublisher -ewg DynamicLayoutGroup -edsw MassTestWriter

Set the publishing interval to 5 seconds:

UADemoPublisher -pi 5000

Run the UADemoPublisher for 15 minutes:

UADemoPublisher -sts 0:15:00

Show help information:

UADemoPublisher --help

Example Output

Below is a sample output from the UADemoPublisher, also showing its configuration with the default values.

OPC Labs OPC-UA Demo Publisher (.NET Core) 5.55.0.6

TransportProfileUri: http://opcfoundation.org/UA-Profile/Transport/pubsub-udp-uadp
Loading configuration...
PublishedDataSets:
  Simple: DataSetClassId=eae79794-1af7-4f96-8401-4096cd1d8908, 4 fields
  AllTypes: DataSetClassId=c51be198-9ade-4a72-8d75-1fbebee173d6, 9 fields
  MassTest: DataSetClassId=96976b7b-0db7-46c3-a715-0979884b55ae, 99 fields
  AllTypes-Dynamic: DataSetClassId=cc7cb5f4-4272-45c2-9a4d-f85a8b331f6a, 16 fields
Connections (enabled objects only):
  FixedLayoutConnection: {opc.udp://239.0.0.1 | } PublisherId=[UInt16]30
    FixedLayoutGroup: WriterGroupId=101, MaxNetworkMessageSize=65507, PublishingInterval=500, KeepAliveTime=2000
      SimpleWriter: DataSetWriterId=1, DataSetName=Simple, KeyFrameCount=1
      AllTypesWriter: DataSetWriterId=2, DataSetName=AllTypes, KeyFrameCount=1
      MassTestWriter: DataSetWriterId=3, DataSetName=MassTest, KeyFrameCount=1
  DynamicLayoutConnection: {opc.udp://239.0.0.1 | } PublisherId=[UInt64]31
    DynamicLayoutGroup: WriterGroupId=102, MaxNetworkMessageSize=65507, PublishingInterval=500, KeepAliveTime=2000
      SimpleWriter: DataSetWriterId=1, DataSetName=Simple, KeyFrameCount=25
      MassTestWriter: DataSetWriterId=3, DataSetName=MassTest, KeyFrameCount=25
      AllTypes-DynamicWriter: DataSetWriterId=4, DataSetName=AllTypes-Dynamic, KeyFrameCount=25
      EventSimpleWriter: DataSetWriterId=51, DataSetName=Simple, KeyFrameCount=0
  FlexibleLayoutConnection: {opc.udp://239.0.0.1 | } PublisherId=[String]32
    FlexibleLayoutGroup: WriterGroupId=103, MaxNetworkMessageSize=65507, PublishingInterval=500, KeepAliveTime=2000
      SimpleWriter: DataSetWriterId=1, DataSetName=Simple, KeyFrameCount=1
      MassTestWriter: DataSetWriterId=3, DataSetName=MassTest, KeyFrameCount=1
      AllTypes-DynamicWriter: DataSetWriterId=4, DataSetName=AllTypes-Dynamic, KeyFrameCount=1

Starting to publish...
Sleeping for Infinite (press Ctrl+Break to abort)...
Messages sent: DynamicLayoutConnection 1, FixedLayoutConnection 1, FlexibleLayoutConnection 3

Receiving Messages

You can use any compliant OPC UA PubSub subscriber to receive and process messages from the UADemoPublisher. It needs to be configured, of course, according to format and contents of the messages sent by the UADemoPublisher. For Ethernet and UDP transport protocol mappings, the subscriber, regardless of its type, needs to be either on the same computer as the UADemoPublisher (for simplest test), or on the same local subnetwork, or you need to configure the multicast routing appropriately.

Examples in the QuickOPC documentation show how to use the EasyUASubscriber object, and other QuickOPC facilities, to subscribe to messages generated by the UADemoPublisher.

You can also use our OpcCmd utility to verify that UADemoPublisher is working, and view the datasets it is publishing. For the default configuration of UADemoPublisher, enter following command:

OpcCmd uaSubscriber subscribeDataSet -cru opc.udp://239.0.0.1

Or, for a specific publisher ID (31, in 64 bits) and dataset writer ID (4):

OpcCmd uaSubscriber subscribeDataSet -cru opc.udp://239.0.0.1 -pi [UInt64]31 -dswi 4

For more information, see Using OpcCmd Utility as OPC UA PubSub Subscriber. Note that without providing a way for OpcCmd to resolve the configuration metadata, you won't be able to actually see the data published by FixedLayoutConnection/FixedLayoutGroup (with UADP message mapping), because it uses raw encoding. Data published by DynamicLayoutConnection/DynamicLayoutGroup, and FlexibleLayoutConnection/FlexibleLayoutGroup can be viewed immediately. In order to view the data published by FixedLayoutConnection/FixedLayoutGroup, you can provide the OpcCmd utility with the PubSub configuration file of UADemoPublisher. Such file, for the default UADemoPublisher configuration, is supplied with it and is called UADemoPublisher.bin. For a non-default configuration, created by specifying additional parameters ob UADemoPublisher command line, you can generate the configuration file using the UADemoPublisher saveConfiguration command.

Sample Capture Files

UADemoPublisher ships with several packet capture files showing its network output. These files can be e.g. fed to your test programs or the OpcCmd Utility, making it possible to play with the PubSub subscriptions without the need to actually have the publisher and messaging infrastructure in place.

The files are:

UADemoPublisher-Ethernet.pcap 
1 minute of UADemoPublisher output in its default configuration, using presets for Ethernet (no tagging).
UADemoPublisher-EthernetVlan.pcap 
1 minute of UADemoPublisher output in its default configuration, using presets for Ethernet with VLAN tagging.
UADemoPublisher-UDP.pcap 
1 minute of UADemoPublisher output in its default configuration, using presets for UDP over IPv4.
UADemoPublisher-UDP6.pcap 
1 minute of UADemoPublisher output in its default configuration, using presets for UDP over IPv6.

See also