UADemoPublisher Basics
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 or .NET 5.0+ (Windows, Linux or macOS). 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)
Discovery is only partially supported.
Note: This page describes a preliminary version (5.60.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.
On Linux or macOS, the TGZ file can be extracted using tar -xvzf <filename>.
If you want to use OPC UA PubSub Ethernet transport protocol mapping, you will also need
- on Linux: libpcap (also see https://www.tcpdump.org/)
- on Windows: Npcap (formerly WinPcap)
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, or .NET Core 3.1 or later version on Windows, type UADemoPublisher and press Enter.
- If you are not on Windows, or are using the .NET Core 2.1 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.
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 publish Command
This is the main command of UADemoPublisher. It configures the publisher and allows you to start the actual publishing of data. If the UADemoPublisher is started with no arguments on its command line, it assumes the publish command automatically. Otherwise, you must always precede the command-line options for the publish command with the command name itself.
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 command 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
The options for the publish command are (obtained through UADemoSubscriber publish --help):
OPC Labs OPC-UA Demo Publisher (.NET Framework) 5.70.0.63
Configure the publisher, and start publishing data.
Usage: UADemoPublisher publish|p [options] [command]
Options:
-?|-h|--help Show help information
-!op|--!option <key-typedValue-pair> Execute with given program option value (*)
-!xe|--!extractElement <index> Extract element at given index of the result sequence
-!xm|--!extractMember <elementPath> Extract member of the result object
-!if|--!inputFile <filePath> Read input from a specified file
-!of|--!outputFile <filePath> Write output to a specified file
-!ao|--!appendOutput Append to the existing content of the output file
-!to|--!teeOutput Write to the output file in addition to the original output destination
-!t2s|--!treeToSequence <treeTraversalType> Define how to convert trees to sequences
-!ve|--!viewEvent[:<viewValueSpecifier>] Specify how to view events
-!vv|--!viewValue[:<viewValueSpecifier>] Specify to view the result as a value, and how
-!vs|--!viewSequence[:<viewSequenceSpecifier>] Specify to view the result as a sequence, and how
-!vt|--!viewTree[:<viewTreeSpecifier>] Specify view the result as a tree, and how
-!0e|--!clearEvents[:<bool>] Determines whether collected events will be clear before execution of the
command
-!ce|--!collectEvents[:<bool>] Determines whether events will be collected during execution of the command
-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 615377160 = 7/2/2019 10:06:00 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)
-sksms|--SecurityKeyServiceMessageSecurity <messageSecurityMode> SKS message security mode
-sksui|--SecurityKeyServiceUserInfo <userInfo> SKS user name token - user info
-sksun|--SecurityKeyServiceUserName <string> SKS user name token - user name
-sksup|--SecurityKeyServiceUserPassword <string> SKS user name token - user password
-sm|--SecurityMode <messageSecurityMode> Security mode (default None)
-wgp|--WriterGroupProperty <uaKey-uaValue-pair> Writer group property (*)
-au|--ApplicationUri <uri> Application URI
-ec|--EnabledConnection <name> Enabled PubSub connection (*)
-edsw|--EnabledDataSetWriter <name> Enabled data set writer (*)
-ewg|--EnabledWriterGroup <name> Enabled writer group (*)
-mdsc|--ManualDataSetClock[:<dateTimeOffset>] Use manually set date&time in datasets
-sc|--SaveConfiguration Save the configuration to UADemoPublisher.uabinary file
-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
Commands:
!wait Specify how long will the parent command execute (default Infinite)
more Enter options for additional configuration part (up to 5 levels)
saveConfiguration|sc Save the configuration data, as specified, to a file
Run 'publish|p [command] --help' for more information about a command.
(*) Indicates options that can be specified multiple times with multiple values.
Parameter values:
<clarkNotation> [{<url>}]<name>
<findType> FindByThumbprint|FindBySubjectName|FindBySubjectDistinguishedName|FindByIssuerName|FindByIssuerDistinguishedName|FindBySerialNumber|FindByTimeValid|FindByTimeNotYetValid|FindByTimeExpired|FindByTemplateName|FindByApplicationPolicy|FindByCertificatePolicy|FindByExtension|FindByKeyUsage|FindBySubjectKeyIdentifier
<format> <string>
<guarantee> NotSpecified|BestEffort|AtLeastOnce|AtMostOnce|ExactlyOnce
<key-typedValue-pair> <name>=<typedValue>
<messageSecurityMode> Invalid|None|Sign|SignAndEncrypt
<sourceTypes> None|File|PkiStore[,None|File|PkiStore]...
<storeLocation> CurrentUser|LocalMachine
<storeName> AddressBook|AuthRoot|CertificateAuthority|Disallowed|My|Root|TrustedPeople|TrustedPublisher
<treeTraversalType> None|DepthFirst|BreadthFirst
<typeCode> Empty|Object|DBNull|Boolean|Char|SByte|Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64|Single|Double|Decimal|DateTime|String
<typedValue> [<typeCode>]<value>
<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|MqttAutoOrJson|MqttAutoOrUadp|MqttJson|MqttUadp|UdpUadp
<uaValue> [<uaBuiltInType>]<value>
<userInfo> <string>[:<string>]
<viewSequenceSpecifier> [<viewSequenceType>][:<format>]
<viewSequenceType> Default|None|Simple|Table|Browse
<viewTreeSpecifier> [<viewTreeType>][:<format>]
<viewTreeType> Default|None|Simple|Table
<viewValueSpecifier> [<viewValueType>][:<format>]
<viewValueType> Default|None|Simple|Properties|Table|Write|Dump|Save
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 publish -kfc 1
Send all messages to IP multicast address 224.0.2.0:
UADemoPublisher publish -cru opc.udp://224.0.2.0
Send all messages to IPv6 multicast address ff02::1 (all nodes on the local network segment):
UADemoPublisher publish -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 publish -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 publish -cni "Ethernet"
Only enable the MassTestWriter in DynamicLayoutGroup:
UADemoPublisher publish -ewg DynamicLayoutGroup -edsw MassTestWriter
Set the publishing interval to 5 seconds:
UADemoPublisher publish -pi 5000
Run the UADemoPublisher for 15 minutes:
UADemoPublisher publish -sts 0:15:00
Show help information:
UADemoPublisher publish --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 Category: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.
