How to develop compliant OPC-UA clients

INTRODUCTION

The OPC Foundation established the OPC Certification program to help vendors verify that their products meet end-user requirements of plug-and-play interoperability, robust behavior and meet minimum performance expectations by providing well-defined behavior, documentation and Test Tools for the testing of OPC Servers and Clients.

QuickOPC has been certified for OPC compliance by OPC Foundation as “UA Generic Client” (http://www.opcfoundation.org/Default.aspx/certifiedproduct.asp?MID=Compliance&certificate=1312CS0045 ). Be aware that products can only be certified individually. Because QuickOPC is a toolkit for development of OPC clients, this certification does NOT automatically award or guarantee the OPC certification to the application(s) that you develop with the toolkit.

Also, simply using QuickOPC in your application does not automatically guarantee that the application will be compliant with the OPC specifications, and/or pass the certification testing. The purpose of this document is to explain the steps you need to take to make your application OPC compliant, or pass the OPC certification testing.

Note that the OPC certification testing is performed by OPC Foundation. If you are interested in the certification, for its terms and conditions, and actual execution, please contact the OPC Foundation.

OPC COMPLIANCE TASKS

This section explains some of the tasks that are needed to make your application OPC compliant, and/or pass the OPC certification testing. Compliance-wise, you may generally have one of the two goals in mind:

1. You want to develop an application that behaves in a compliant way on the OPC-UA communication level, without actually having it certified for OPC compliance.
   In order to achieve this, you should just do the tasks outlined below under “Parameter Settings” – in essence, set the parameters of EasyUAClient object to OpcCompliance, and you should be all set. Ideally (and it is strongly recommended), you would also perform the other tasks mentioned below, under “Result Handling”, “Logging” and “Other Requirements”, but they are not necessary.
2. You want to develop an application that will be later certified for OPC compliance.
   In this case, you need to perform all tasks described in this chapter, i.e. “Parameter Settings”, “Result Handling”, “Logging” and “Other Requirements”.

We have consistently used maximum effort to put everything possible that is needed for compliance into the QuickOPC libraries themselves, leaving as little as possible to be done in the custom code. There are still, however, some rules you need to follow, and they are explained below.

Parameter Settings

In its “out of the box” state, the EasyUAClient component (which provides the core OPC-UA client functionality) is configured for maximum interoperability. This means that we wherever possible (given certain reliability and security constraints), the OPC client code tries to be “forgiving”, and fairly relaxed about the OPC server behavior. The component thus works well even with many servers that do not fully conform to the OPC specifications.

The OPC compliance certification process for the clients, however, has some tests that require the client to reject connection to the server (or reject data coming from the server, etc.) when the OPC server exhibits certain non-compliant behavior, even though technically it could be made to work. We did not want to harm the out-of-the-box experience with our product by defaulting to this restrictive behavior, because many users won’t appreciate it. After all, the aim of developing an OPC client application is to make the OPC connection and transfer the data, and not to the compliance level of the OPC servers.

There are many individual parameters that have effect on the OPC client compliance. In order to make it easy for the developer to properly configure the document, we have defined two “canned” settings of all relevant parameters that can be easily chosen:

• Interoperability (the default)
• OpcCompliance

In order to switch the EasyUAClient component to use the parameters that are tuned for OPC compliance, your code should do one of the following:

1. Before an EasyUAClient instance is created, set the static EasyUAClient.AdaptableParameters property to EasyUAAdaptableParameters.OpcCompliance. This will then have influence on all subsequently created EasyUAClient instances that have their Isolated property set to false (which they have by default).
   or
2. Right after creating an EasyUAClient instance, set its Isolated property to true, and set its IsolatedParameters property to EasyUAAdaptableParameters.OpcCompliance. With this approach, you can either do this on each EasyUAClient instance, or you can even have separate instances with differing behavior.M/li>

If you have the same concerns as we do, i.e. that the OPC compliant settings may sometimes harm the interoperability of your product, you may expose some configuration option in your product and allow your customers to choose the right behavior for themselves.

Result Handling

In your code, you need to make sure that all errors and warnings returned by the QuickOPC calls (or in event notifications) do manifest themselves somehow to the user. QuickOPC goes to great lengths to collect and provide all kinds of information about possible error situations, but it cannot influence how this information is dealt with in your application.

In order to achieve the OPC compliance with regard to result handling, first and foremost, your code should follow the Best Practices listed in the Concepts document. The practices that specifically address the result handling include:

• Always test the Exception property before accessing the actual result (Value, or AttributeData property).
• Always test the HasValue property before accessing UAAttributeData.Value.

Above, we are listing just the titles of the practices. Please refer to the Concepts document for details and explanations.

Second, besides “just” checking the abnormal conditions, for OPC compliance you should also take specific actions, as described below:

When the Exception associated with the operation is not a null reference, your code should make the exception message available to the user.

When the operation has succeeded (the Exception is a null reference), but there is no usable value (the HasValue property of UAAttributeData is false), your code should make the status code (UAAttributeData.StatusCode) (and/or its associated text) available to the user.

In addition, there are situations where the operation has succeeded, but either some unusual conditions have appeared during the execution, or a more detailed diagnostics has been requested. For some OPC compliance tests, your code should make the additional diagnostics available to the user as well. This information is available in the Diagnostics collection (or DiagnosticsSummary string) of the result objects (e.g. UAAttributeDataResult, UAWriteResult, or ValueResult), or event arguments (e.g. EasyUADataChangeEventArgs).

Note: When we say “make something available to the user”, we leave the actual implementation of it on your decision. If your software does not have a user interface where the information can be readily displayed, you will probably have to find some other way how to satisfy the OPC compliance testing process.

Logging

Wherever possible, errors or warnings are indicated through method results, or result objects in event notifications, as described above. There are, however, some situations that happen during OPC communication, that do not relate directly to a particular operation. For OPC compliance, such situations should be logged, or otherwise made available to the end user.

In order to achieve this, you need to write a handler for the (static) EasyUAClient.LogEntry event, and display or physically log the messages that this event provides. The LogEntry event has an argument of type LogEntryEventArgs, which carries the log entry data, such as the numerical category and event ID, entry type (Error, Warning, Information, SuccessAudit, or FailureAudit), the event source, and most importantly, the actual Message string. For OPC compliance, as a minimum, the Message should be logged or displayed.

Other Requirements

If you want to obtain OPC compliance certification for your product, there are also other requirements that you need to fulfill. To give you an idea of what to expect, below are some requirements that are currently included in the certification test plan:

• Vendor-made Compliance Testing. It is expected that you test your application using the UA Compliance Test Tool (CTT) prior to testing by OPC Foundation.
• Interoperability Testing. It is assumed that you test and document interoperability with other products.
• Performance and Load Testing. You should document the “volume” capabilities of your product, because OPC Foundation will use it as basis for the load test that is part of the compliance certification process.
• Robustness.
• Usability in the configuration.
• Diagnostics.
• Documentation. You must have an up-to-date documentation to your product.
• Installation. The certification process expects certain specified level of installation experience.
• 36-hour test. Among others, tests the resource leaks.

For the precise rules, please refer to OPC Foundation.

OPC COMPLIANCE SETTINGS

The table below lists the differences between the default settings (tuned for interoperability), and the settings for OPC compliance. The settings that do not differ are not listed.

	Interoperability (Default)	OpcCompliance
Discovery.CheckApplicationDescription	false	true
Session.CertificateAcceptancePolicy.AcceptAnyCertificate	true	false
Session.CheckAvailableSequenceNumbers	false	true
Session.CheckBrowseResults	false	true
Session.CheckEndpointDomain	false	true
Session.CheckNotificationMessage	false	true
Session,CheckSessionId	false	true
Session.EndpointDescriptionChecks.CheckEndpointUrl	false	true
Session.EndpointDescriptionChecks.CheckSecurityMode	false	true
Session.EndpointDescriptionChecks.CheckSecurityPolicyUri	false	true
Session.EndpointDescriptionChecks.CheckServerApplication	false	true
Session.EndpointDescriptionChecks.CheckServerCertificate	false	true
Session.EndpointDescriptionChecks.CheckTransportProfileUri	false	true
Session.EndpointDescriptionChecks.CheckUserIdentityTokens	false	true
Session.EndpointDescriptionChecks.RequireValidDiscoveryUrls	false	true
Session.EndpointSelectionPolicy.EnforceSameSite	false	true
Session.RequireServerEndpointsMatchDiscovery	false	true
Session.RequireUniqueAuthenticationToken	false	true
Session.RequireUniqueServerNonce	false	true
Session.RequireValidAuthenticationToken	false	true
Session.RequireValidServerNonce	false	true
Session.SanitizeReferenceDescriptions	false	true
Session.ShortestAllowedRevisedSessionTimeout	0	500
Subscription.AllowPublishTimeAhead	true	false
Subscription.AllowPublishTimStale	true	false
Subscription.CheckSubscriptionId	false	true
Subscription.RequireMinimumRevisedLifetimeCount	false	true
MonitoredItem.CheckMonitoredItemId	false	true
MonitoredItem.RequireValidRevisedSamplingInterval	false	true
MonitoredItem.SanitizeNotificationDataValue	false	true

You can find details about individual settings in the reference documentation. Note that the specific settings are subject to change without notice, and more settings may be added or included in the future.