How to Develop Compliant OPC-UA Clients General Guidelines Page 2 of 10 Table of Contents INTRODUCTION 3 OPC COMPLIANCE TASKS 4 Parameter Settings 4 Result Handling 5 Logging 6 Other Requirements 7 OPC COMPLIANCE SETTINGS 8 CONTACT US 10 Page 3 of 10 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. OPC Data-UA has been certified for OPC compliance by OPC Foundation as “UA Generic Client” (http://www.opcfoundation.org/Default.aspx/certifiedproduct.asp?MID=Compliance&certificate=13 12CS0045 ). Be aware that products can only be certified individually. Because OPC Data-UA 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 OPC Data-UA 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. Page 4 of 10 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: A) You want to develop an application that behaves in a compliant way on the OPCUA 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. B) 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 OPC Data-UA 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 Page 5 of 10 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: a) 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 b) Right after creating an EasyUAClient instance, set its Isolated property to true, and set its IsolatedAdaptableParameters 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. 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 OPC Data-UA calls (or in event notifications) do manifest themselves somehow to the user. OPC Data-UA 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. Page 6 of 10 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. EasyUAMonitoredItemChangedEventArgs). 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 Page 7 of 10 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. Page 8 of 10 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 OpcCompliance (Default) 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 Page 9 of 10 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. Page 10 of 10 Contact Us If you have any questions or are seeking further assistance, please contact us at: Online Support: http://support.softwaretoolbox.com Email Support: [email protected] Phone Support: +1 (704) 849-2773 Fax: +1 (704) 849- 6388 Mailing Address: Software Toolbox, Inc. 148A East Charles Street, Matthews, NC 28105, USA