Introduction

OPC UA Client is a backend application, whose role is to fetch data from OPC UA Server and write the data to DB using Vtrin API. OPC UA Client application can run on both Windows and Linux platforms.

OPC UA Client application is developed on with OPC Unified Automation .NET SDK and uses it to communicate and exchange data with OPC UA Servers. OPC UA is short for OPC Unified Architecture which is provided by Unified Automation.

Features

Collecting numerical process history from 3rd party UA servers.
Collecting process events and alarms from 3rd party UA servers. All attributes coming from standardized event types are supported.
Tag and Equipment model-based configuration to cross-connect signals.
Writing back to 3rd party UA server based on current value events in database when Tags-based configuration is used.
Storing received values both to Current History and Stream History
Supports all datatypes available in Current and Stream histories, including string and arrays of basic datatypes.
Supports application instance certificates and secure communication protocols. User authentication types: anonymous, password, user certificate.
Supports alarms and conditions.

Installation

Requires ABB Ability™ History to be installed, if you haven't installed ABB Ability™ History yet, follow the links below to installation guide.

Windows: https://docs.cpmplus.net/docs/installation-on-windows

Linux: https://docs.cpmplus.net/docs/installation-on-linux

OPC UA Client requires installation of .NET 8.0. You can check with command dotnet --info whether the correct version is already installed. To install, download and run the installer from https://dotnet.microsoft.com/en-us/download/dotnet. Select the ".NET Desktop Runtime" package.

#Go to the installation path "%RTDBRoot%\Bin\netcore\"
#For default installation folder
cd C:\Program Files\ABB Oy\RTDB\Bin\netcore\

#OpcUa client can be set up as a RTDB service
runcpm CSCommon_Cmd -setini [PATH_TO_DATBASE]\RTDB.INI Services Vtrin-OPCUAClient ON
runcpm CSCommon_Cmd -setini [PATH_TO_DATBASE]\RTDB.INI Vtrin-OPCUAClient CmdLine "%RTDBRoot%\Bin\netcore\VtrinOPCUAClient.exe -d [PATH_TO_DATBASE]"

#Alternatively OpcUa client can set itself up as standalone service with the -install flag.
VtrinOPCUAClient.exe --install -d [PATH_TO_DATBASE]

#Run the following command to install OPC UA Client
apt-get install cpmplusvtrinopcuaclient

#OpcUa client can be set up as a RTDB service
runcpm CSCommon_Cmd -setini [PATH_TO_DATBASE]/RTDB.INI Services Vtrin-OPCUAClient ON
runcpm CSCommon_Cmd -setini [PATH_TO_DATBASE]/RTDB.INI Vtrin-OPCUAClient CmdLine "/usr/share/dotnet/dotnet /usr/share/cpmplus/netcore/VtrinOPCUAClient.dll -d [PATH_TO_DATBASE]"

Running

Vtrin OPC UA Client can be started with this simple command:

cd C:\Program Files\ABB Oy\RTDB\Bin\netcore\
VtrinOPCUAClient.exe -d [PATH_TO_DATBASE]

VtrinOPCUAClient -d [PATH_TO_DATBASE]

Commandline arguments

Argument	Short	Description
--datasourcename [PATH_TO_DATBASE]	-d [PATH_TO_DATBASE]	Data source name. Direct connection to a local directory or remote connection.
--user [USERNAME or CREDENTIAL]	-u [USERNAME or CREDENTIAL]	User name or credential for the Data Source.
--savepassword	-p	Save user password to credential.
--service	-s	Run as a service.
-servicename	-n	Name of the service, default: 'VtrinOPCUAClient'.
--install	-i	Install as a service. Not available on Linux.
--remove	-r	Remove the service. Not available on Linux.
--logpath [PATH]	-l [PATH]	Path where log files "VtrinOPCUAClient_[DATE].log" are generated.
--verbose	-v	Display more verbose messages.
--receiverid [ID]	-e [ID]	Receiver id (RTDB process number) for command queue. Initialization only. Default: 32.
--configname [NAME]	-c [NAME]	Name of the Simple Config section, default: 'VtrinOPCUAClient'.

Examples

#Examples for data sources:
VtrinOPCUAClient.exe -d c:\rtdbdata
VtrinOPCUAClient.exe -d ws://127.0.0.1/History
VtrinOPCUAClient.exe -d wss://<REMOTE_IP>/History

#Examples for authentication for datasources:
#No authentication:
VtrinOPCUAClient.exe -d <DATASOURCE>
#Save/update password: (Saved credential will be printed. For example: "*VTRIN/c_rtdbdata")
VtrinOPCUAClient.exe -d <DATASOURCE> --user USERNAME --savepassword
#Start with saved credentials: (Instead of username, write the credential name, starting with asterix '*')
VtrinOPCUAClient.exe -d <DATASOURCE> --user *CREDENTIAL

#Examples for installing as a service: (credential should be saved beforehand)
VtrinOPCUAClient.exe -d <DATASOURCE> --user *CREDENTIAL --service --install

#Examples for data sources:
VtrinOPCUAClient -d /var/lib/rtdbdata
VtrinOPCUAClient -d ws://127.0.0.1/History
VtrinOPCUAClient -d wss://<REMOTE_IP>/History

#Examples for authentication for datasources:
#No authentication:
VtrinOPCUAClient -d <DATASOURCE>
#Save/update password: (Saved credential will be printed. For example: "*VTRIN/c_rtdbdata")
VtrinOPCUAClient -d <DATASOURCE> --user USERNAME --savepassword
#Start with saved credentials: (Instead of username, write the credential name, starting with asterix '*')
VtrinOPCUAClient -d <DATASOURCE> --user *CREDENTIAL

Configuration

SimpleConfig table

OpcUAClient can be configured from Vtrin SimpleConfig table under VtrinOPCUAClient section.

Bolded keys/values inside [brackets] are to be replaced with user set values.

Slash separated values inside [brackets] are choices.

Key	Default Value	Optional Values	Description
verboselog	false	true/false	If logging processing more details, for example value write details Change takes effect runtime
reconnectinterval	5000		Reconnect interval in case connection was not successfull Change takes effect runtime
maxoperationsperrequest	1000		UA parameter, suggest how many operations fit Change takes effect on restart
pkistorepath	On Windows: %AppData%ABB VtrinOPCUAClientPKI or: C:WindowsSystem32 configsystemprofile AppDataRoamingUnifiedAutomation VtrinOPCUAClientPKI On Linux: /root/.config/ABB/VtrinOPCUAClient/PKI		Starting from version 24.11. Default path to OPC UA Client certificates folder to use when machine specific pkistorepath is not specified. On Windows if the Log On As account is changed to RTDBAdmin user then the path will be %AppData%ABBVtrinOPCUAClientPKI If the log On As account is Local System then use C:WindowsSystem32configsystemprofileAppDataRoamingABBVtrinOPCUAClientPKI Change takes effect on restart On older versions key is: pkistorepathwin
[machinename]:pkistorepath	Same as pkistorepath		Starting from version 24.11. Machine specific path to OPC UA Client certificates folder. if pkistorepath is based on path on the same operating system, pkistorepath will be used as default value when running the client on the first time. Otherwise the value will revert to platform default value of: Windows: C:WindowsSystem32 configsystemprofile AppDataRoamingABB VtrinOPCUAClientPKI Linux: /root/.config/ABB/VtrinOPCUAClient/PKI Change takes effect on restart
minwritebackcycle	1000		Change takes effect on runtime
uatracelevel	0		The UA SDK Tracing level. Value 1..7 causes that tracing is printed to Diag directory of the database, with name UaTrace-RTDB-UaClient.txt (or if an instances with different appname is installed, then UaTrace-appname.txt) 0=Default 1 = NoTrace 2 = Errors 3 = Warning 4 = Info 5 = InterfaceCall 6 = CtorDtor 7 = ProgramFlow 8 = Data Change takes effect on restart
uatracemaxentries	100		Change takes effect on restart
maxreconnectionattemps	100		Change takes effect on restart
backfillenabled	false	true/false	Change takes effect on restart
monitoreditemqueuesize	10		Queue size used for monitored item creation Change takes effect runtime
maxconcurrentbackfills	10		Max number of concurrently running backfills Change takes effect runtime
uaserver:[uaserverurl/uaservername]_		securitypolicy=[none/basic128rsa15/basic256/basic256sha256/aes128Sha256rsaoaep/aes256sha256rsapss]; securitymode=[none/signandencrypt/sign/invalid]; securityselection=no; authentication=[username/certificate]; username=[stored credential vault name]; url=[uaserverurl]; (Since version 25.11)	if securitymode and securitypolicy not specified and securityselection=no not specified, client tries to ask server the best available configuration if authentication not specified anonymous is used if username not specified (credentials username from Vtrin credential storage, ) connection fails On Linux credentials can be added with this command: runcpm Vtrin-NetServer --username [root] --password [password] --addcredentials [vaultname] if usercertificatepath (user level certificate) not specified in case of authentication=certificate, connection fails. User certificate should be in .pfx format. securityselection=no; is option to force no security, when used securitymode and securitypolicy are not used same time with securityselection setting uaserver:[uaservername] and url=[uaserverurl]; You can apply long uaserver urls to the configuration. The [uaservername] can be arbitary. See example below. Change takes effect on restart
defaultserversettings		(Since version 25.11) Same as above, but excluding url=[uaserverurl]	See above row.
logbyidn		idn of variable	Logs attempts to write to DB for variable specified by idn Change takes effect runtime
monitoreditemcreationbatchsizelimit	500		Limitation number for Monitored Item creation in one request Change takes effect runtime
receiverid	32		RTDB process id for receiving commands Change takes effect runtime

SimpleConfig table example

Section	Key	Value
VtrinOPCUAClient	verboselog	false
VtrinOPCUAClient	uatracelevel	0
VtrinOPCUAClient	backfillenabled	true
VtrinOPCUAClient	uaserver:opc.tcp://127.0.0.1:4841	securitypolicy=basic256sha256;securitymode=sign;authentication=username;username=[credentialsname]
VtrinOPCUAClient	uaserver:opc.tcp://127.0.0.1:4842	securityselection=no;authentication=certificate;usercertificatepath=[path]
VtrinOPCUAClient	uaserver:UASERVER2	url=opc.tcp://127.0.0.1:48031;

Setting up data collection

OPC UA Client ONLY loads the records, whose attribute 'Owner Component' value is selected to 'OPC UA V3'.

Note: On Linux it may be required to add target machine IP and hostname to /etc/hosts file for connection to work.

Tags	OPC UA Client
Id	UUID, used as the primary key to acquire full information of a record
NumericalId	DataPoint IDN
Da Type	Data collection service to use, select: OPC UA V3
Activity	Decide if the record will be monitored in the program
DaPath	Contain UA Server URL, NodeId, UaIdType, Namespace and UaArrayElement Supported UaIdTypes: String: s Integer: i Guid: g (Since version 25.11) bse64 encoded bytestring: b (Since version 25.11) hexstring: h
DataFlowDirection	Option: [in] means OPC UA Client reads data from OPC UA Server, then write them to DB; Option: [out] means OPC UA Client reads data from DB, then write them to OPC UA Server.
DaFrequency	Used as both sampling interval and publishing interval if 'DataFlowDirection' is [in]; Used as interval to pull data from DB if 'DataFlowDirection' is [out].

Display Name	Proposal Name	DaType	DaPath	DaFrequency	Activity	Type	Id	NumericalId	DataFlowDirection
W1	W1	OPC UA V3	opc.tcp://PikkuPelle///Demo.Static.Scalar.Double;UaNamespace=http://www.unifiedautomation.com/DemoServer/	1,000	Active	Float	41afba9c-dfb2-488d-b2a0-2a4a	11,425	[out]
U2	U2	OPC UA V3	opc.tcp://PikkuPelle///Demo.Dynamic.Scalar.Double;UaNamespace=http://www.unifiedautomation.com/DemoServer/	1,000	Active	Float	fa91cf1f-1db1-45ae-a144-db1abc	11,329	[in]

DataAccessSource table

The value of attribute 'Access Type' should be selected to 'Realtime'.

The value of attribute 'Access Path' should match the pattern: opc.tcp://[ip]:[port]///[value];UaIdType=[type];UaNamespace=[url]* . For an example, please see the figure below.

Id	Target Reference	Target	Owner Component	Access Type	Access Path
{OPC UA V3, /Path_Car[MotorSpeed]}	/Path_Car[MotorSpeed]	MotorSpeed	OPC UA V3	RealTime	opc.tcp://127.0.0.1:48010///Demo.Dynamic.Scalar.Double;UaIdType=s;UaNamespace=http://www.unifiedautomation.com/DemoServer/

DataAccessRealTime table

Similar to the DataAccessSource table, the value of attribute 'Owner Component' should be selected as 'OPC UA V3'. For an example, please see the figure below.

id	Name	Target Reference	Target	Publishing Interval	Owner Component
{OPC UA V3, /Path_Car[RpmActual]	Drives.Siemes.Driver}	Drivers.Siemens Driver	/Path_Car[RpmActual]/	Drives.Siemens Driver	RpmActual	00:00:01	OPC UA V3
{OPC UA V3, /Path_Car[RpmActual]}	All property RpmActual	/Path_Car[RpmActual]	RpmActual	00:00:02	OPC UA V3

DataAccessEvent table

Attribute	Requirements
Id	UUID type. Used as the primary key to acquire full information of a record
Owner Component	must be 'OPC UA V3'
Target	A comma separated list of target database tables (supported values: OpcEventLog, EquipmentEventLog, EquipmentEvent) to where to store the events
AccessPath	Contain UA Server URL, NodeId, Queue Size, UaIdType and Namespace
Filter	See "DataAccessEvent Filter" section
Options	See "DataAccessEvent Options" section

DataAccessEvent Filter (Since version 25.01)

Filter column can be used to set conditions for event collection. No filter defined, means that all events are collected.

Filtering supports complex condition statements, and can target browsenames, such as event attribute like "Severity".

Syntax:

Filter can be inputted as whitespace ' ' separated array, position of the operator is not significant.

Operation inside parenthesis "(" and ")" will be resolved first. Operation in parenthesis can contain statements in parenthesis, and so on.

Text inside quotations " and ' is considered as constant string. Opening quotation must match the closing quotation.

Number is considered as a constant

Text without quotations are considered as browsename property, such as Severity or Message

Operators:

Operator	Shorthand	Number of operands	Example
Not_1	!	1	! (Severity == 500)
Equals_0	==	2	Message == "Error"
GreaterThan_2	>	2	(Message == 'Warning') && (Severity > 500)
GreaterThanOrEqual_4	>=	2	GreaterThanOrEqual_4 Severity 100
LessThan_3	<	2
LessThanOrEqual_5	<=	2
And_10	&&	2	(Severity > 50) && (Severity < 400)
Or_11	\|\|	2	(Severity >= 50) Or_11 (Severity <= 10)

Additional operators can be found from here: https://reference.opcfoundation.org/Core/Part4/v104/docs/7.4.3

Limitations:

'IsNotEqual' -operator doesn't exist in OPC UA standard.
Currently only properties of BaseEventType is supported.
Browsepaths are not currently supported.

DataAccessEvent Options (Since version 25.01)

Multiple options are separated by ';'

Table of supported options:

Option	Parameters	Example	Description
Attributes=	comma-separated list of attributes	Attributes=Attribute1,Attribute2,Attribute3	Manually defines comma-separated list of additional attributes
ScanAttributes			Tells OPC UA Client to automatically scan server for all attributes. Note: This feature can be too heavy for some servers.
ExcludeAttributes=	comma-separated list of attributes	ExcludeAttributes=Attribute1,Attribute2,Attribute	Tells OPC UA Client to ignore following attributes. NOTE: EventID and Time are mandatory attributes and cannot be excluded.
NoAlarms		NoAlarms	Ignores all alarms and conditions related attributes.

DataAccessEvent Example

The figure below show an example of DataAccessEvent configuration:

Name	OwnerComponent	Target	AccessPath	Filter
SampleEvent	OPC UA V3	EquipmentEventLog	opc.tcp://PikkuPelle:48010///5068;UaQueueSize=100;UaIdType=i;UaNamespace=http://www.unifiedautomation.com/DemoServer/
BaseServer	OPC UA V3	OpcEventLog	opc.tcp://PikkuPelle:48010///2253;UaQueueSize=100;UaIdType=i;UaNamespace=http://opcfoundation.org/UA/	(Severity > 200)	(Severity == 100)	ScanAttributes; Attributes=PumpState,PumpPressure;
AirConditioner_1	OPC UA V3	EquipmentEvent	opc.tcp://PikkuPelle:48010///2253;UaQueueSize=100;UaIdType=i;UaNamespace=http://www.unifiedautomation.com/DemoServer/

Diagnosing

Logging directory is defined by --logpath (or -l) command line argument.

Since version 25.10:

Logpath is automatically determined by --datasourcename (or -d) argument, logs will be then found

[PATH_TO_DATBASE]\Diag (e.g. D:\RTDBData\Diag)

If no valid path for logs are found (for example when using wss.// connection instead of direct connection), logs are printed into:

%APPDATA%\ABB\VtrinOPCUAClient\Logs

/root/.config/ABB/VtrinOPCUAClient/Logs