MatrikonOPC UA Wrapper for COM OPC Servers User Manual

MatrikonOPC UA Wrapper for COM OPC Servers User's Manual

MatrikonOPC UA Wrapper for COM OPC Servers v1.2.3 User’s Manual 2

MatrikonOPC UA Wrapper for COM OPC Servers User's Manual

This manual is a product of Matrikon Inc.

Matrikon Inc. Suite 1800, 10405 Jasper Avenue Edmonton, AB T5J 3N4 Canada Phone: +1.780.448.1010 Fax: +1.780.448.9191 www.matrikonopc.com

Document Revision History:

Date Document Version Description Author

2008-11-05 0.1 Initial document. RN, LB

2008-12-10 0.2 Added information related to UA Wrapper as part of Security Gateway. Updated files in UAWrapper (Table 2) and UA (Table 4) folders in Installed Files section. Updated files in Configured Settings folder (Table 6) in the Configuration section.

RN, LB

2009-01-08 0.3 Updated the Installation section steps 18 through 30. Added Licensing Procedures.pdf to Table 2 (UAWrapper folder) in Installed Files section.

LB

2009-01-14 1.0 Removed Windows 2000 from Software Requirements section. Removed references to UA Wrapper as a stand-alone application.

LB

2009-07-03 2.0

Updated software to v1.0.1.0. Updated Software Requirements. Applied generic template updates. Updated UAWrapper folder in Installed Files section. Updated Contacting Support information. Updated the Stopping and Starting the MatrikonOPC UA Wrapper for COM OPC Servers section. Updated MatrikonOPC UA Wrapper for COM OPC Servers Configuration section. Updated MatrikonOPC UA Wrapper for OPC COM Servers (as part of MatrikonOPC Security Gateway).

RN, LB

2009-07-17 2.1 Installed Files – UA Wrapper (Table 2) updated. LB

2009-08-11 2.2 Added Starting and Stopping the UA Local Discovery Server.

LB

http://www.matrikonopc.com/�


2009-09-15 2.3

Removed DEP settings note from Installation section. Welcome to MatrikonOPC UA Wrapper for COM OPC Servers Maintenance screenshot updated in Un-Installation section.

LB

2009-09-24 2.4 Updated Software Requirements section to include Microsoft Windows XP and 2003 minimum requirements.

LB

2010-04-21 2.5

Updated software to version 1.1.0.0. Added Wrapped COM OPC Server Configuration section. Updated Troubleshooting section. Removed information related to UA Wrapper as part of Security Gateway.

RN, DP

2010-04-23 2.6 Reviewed and edited 2.5 updates. Updated Installed Files, Limitations, and Troubleshooting sections.

LB

2011-03-30 2.7 Updated Installed Files, removed instructions for stopping the UA Discovery Server. DP

2011-08-19 3.0 Updated software to version 1.2.0.0. Updated Troubleshooting section. RN, DP

2011-11-09 4.0 Updated software to version 1.2.1.0. Updated Wrapped COM OPC Server Configuration and Troubleshooting sections.

RN

2012-03-26 4.1

Updated Introduction to include two types of communication protocol (TCP and HTTP) supported by UA Wrapper, instead of one (TCP), after-hours support number in Contacting Support, and Copyright Information.

LB

2012-05-10 5.0 Updated software version to 1.2.2.0. Updated Copyright Information. LB

2013-02-11 6.0 Updated software version to 1.2.3. SG


SOFTWARE VERSION Version: 1.2.3 DOCUMENT VERSION Version: 6.0 COPYRIGHT INFORMATION

© Copyright 1997 - 2013, Matrikon Inc. All rights reserved. No part of this document may be reproduced, stored in a retrieval system, translated, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of Matrikon Inc. CONFIDENTIAL The information contained herein is confidential and proprietary to Matrikon Inc. It may not be disclosed or transferred, directly or indirectly, to any third party without the explicit written permission of Matrikon Inc. IMPORTANT NOTICE Although every endeavor has been made to ensure that the information contained within this document is up to date and accurate, Matrikon cannot be held responsible for any inaccuracy or error in the information contained within this document. Matrikon makes no warranty of any kind with regard to the information contained within this document and Matrikon shall not be liable for any direct, indirect, incidental or consequential damages which may arise in connection with the furnishing, reliance, or use of the information contained within this document. Specifications and statements as to performance in this document are Matrikon estimates, intended for general guidance. Matrikon reserves the right to change the information contained within this document and any product specification without notice. Statements in this document are not part of a contract or program product licence insofar as they are incorporated into a contract or licence by express preference. Issue of this document does not entitle the recipient to access or use of the products described, and such access or use shall be subject to separate contracts or licenses. The receiving party shall not disclose, publish, report, communicate, or otherwise transfer any information in this document to any third party, and shall protect all information contained herein from unauthorized disclosure. The receiving party shall permit access to this document only to its employees, agents, subcontractors, and affiliates who reasonably require access to such information contained herein, have been made aware of the confidential nature of this document and have executed a written employment or other confidentiality agreement party to maintain the confidential status of this document. LICENSE AGREEMENT This document and the software described in this document are supplied under a license agreement and may only be used in accordance with the terms of that agreement. Matrikon reserves the right to make any improvements and/or changes to product specifications at any time without notice. TRADEMARK INFORMATION The following are either trademarks or registered trademarks of their respective organizations: Matrikon and MatrikonOPC are trademarks or registered trademarks of Matrikon Inc. OTHER MatrikonOPC™ is a division of Matrikon™ Inc. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). Copyright © 1998-2008 The OpenSSL Project. All rights reserved.

http://www.openssl.org/�


Table of Contents Introduction ..................................................................................................................... 7

Who Should Use This Manual ............................................................................................ 7 Overview of Manual ......................................................................................................... 7 References ..................................................................................................................... 8 Document Terminology .................................................................................................... 8

Getting Started ............................................................................................................... 10 System Requirements .................................................................................................... 10

Software Requirements ............................................................................................... 10 Hardware Requirements .............................................................................................. 10

Installation ................................................................................................................... 10 Installed Files ............................................................................................................... 24 Licensing ..................................................................................................................... 25 Contacting Support ....................................................................................................... 26

Configuration ................................................................................................................. 27 Starting and Stopping the MatrikonOPC UA Wrapper for COM OPC Servers ............................ 27 MatrikonOPC UA Wrapper for COM OPC Servers Configuration ............................................. 27 Wrapped COM OPC Server Configuration .......................................................................... 28

Limitations ..................................................................................................................... 35 Troubleshooting ............................................................................................................. 36

Problems and Solutions .................................................................................................. 36 Questions and Answers .................................................................................................. 39

Un-Installation ............................................................................................................... 41

Table of Figures Figure 1 - InstallAware Wizard Verification Window ...................................................... 11 Figure 2 - MatrikonOPC UA Wrapper for COM OPC Servers Pre-Requisites Screen ......... 12 Figure 3 - Installing MatrikonOPC UA Wrapper for COM OPC Servers Pre-Requisites Screen ............................................................................................................................ 13 Figure 4 - OPC Core Components Redistributable License Agreement Window .............. 14 Figure 5 - OPC Core Components Redistributable Select Installation Folder Window ..... 15 Figure 6 - Confirm Installation Window ......................................................................... 16 Figure 7 - Installing OPC Core Components Redistributable Window ............................. 17 Figure 8 - Installation Complete Window ....................................................................... 18 Figure 9 - License Agreement Screen ............................................................................. 19 Figure 10 - Setup Type Screen ....................................................................................... 20 Figure 11 - Destination Folder Screen ............................................................................ 21 Figure 12 - Licensing Screen .......................................................................................... 22 Figure 13 - Ready to Install Screen ................................................................................ 23 Figure 14 - MatrikonOPC UA Wrapper for COM OPC Servers Setup Complete Screen ...... 24 Figure 15 - MatrikonOpcUaWrapper Configuration Window ........................................... 29 Figure 16 – Wrapped COM OPC Servers Configuration Window ...................................... 30 Figure 17 - Add Wrapped COM OPC Server Window ....................................................... 30 Figure 18 - Edit Wrapped COM OPC Server Window ....................................................... 31 Figure 19 - Add/Remove Programs ................................................................................ 41 Figure 20 - Welcome to MatrikonOPC UA Wrapper for COM OPC Servers Maintenance Screen ............................................................................................................................ 42 Figure 21 - Ready to Uninstall Screen ............................................................................ 43


Figure 22 - Uninstalling MatrikonOPC UA Wrapper for COM OPC Servers Screen ............ 44 Figure 23 - MatrikonOPC UA Wrapper for COM OPC Servers Setup Complete Screen ...... 45

Table of Tables Table 1 - Terms and Definitions ........................................................................................ 9 Table 2 - Files Installed in "UAWrapper" Folder ............................................................. 25 Table 3 - Files Installed in "Common" Folder ................................................................. 25 Table 4 - Files Installed in “C:\Documents and Settings\All Users\Application Data\Matrikon\UA” Folder ............................................................................................. 25 Table 5 - MatrikonOPC Support Regional Contact Information ....................................... 26 Table 6 - After-Hours Support ........................................................................................ 26 Table 7 - MatrikonOpcUaWrapper.config.xml Configured Settings ................................. 28 Table 8 - MatrikonOpcUaWrapper.config.xm, section ComOpcClientConfiguration Settings....................................................................................................................................... 34


Introduction The MatrikonOPC™ UA Wrapper for COM OPC Servers is intended to provide OPC UA clients with access to legacy COM OPC DA, HDA, and AE servers using OPC UA communication protocol. The UA Wrapper exposes COM OPC servers as folders in the OPC UA server’s address space. The UA Wrapper can be configured to host multiple OPC servers. Two types of communication protocol are supported by the UA Wrapper: TCP and HTTP.

The MatrikonOPC UA Wrapper for COM OPC Servers is built using the OPC UA SDK from the OPC® Foundation. The version used and the list of changes made, comparing the OPC Foundation’s UA Sample Server, can be found in the MatrikonOPC UA Wrapper for COM OPC Servers Release Notes that accompany this manual.

Notes:

• The MatrikonOPC UA Wrapper for COM OPC Servers is available as either an independent application, or as part of MatrikonOPC Security Gateway. If it is being installed as part of Security Gateway, please read the MatrikonOPC Security Gateway User’s Manual before reading this UA Wrapper manual.

• The install for MatrikonOPC UA Wrapper for COM OPC Servers includes the OPC Foundation’s UA Local Discovery Server which can be installed optionally.

Who Should Use This Manual This manual is intended for use by all users of the MatrikonOPC UA Wrapper for COM OPC Servers.

This manual explains how to install and configure the software along with the section on troubleshooting.

Overview of Manual This document uses icons to highlight valuable information. Remember these icons and what they mean, as they will assist you throughout the manual.

This symbol denotes important information that must be acknowledged. Failure to do so may result in the software not functioning properly.

BOLD Font displayed in this color and style indicates a hyperlink to the applicable/associated information within this document, or if applicable, any external sources.

The User’s Manual has been designed as such so that you can click on references in the document to jump to that referenced point without having to scroll through several pages (in some cases). For example, if you were to see the sentence “Refer to Figure 1 for more information”, pressing the CTRL key and clicking your mouse on the text “Figure 1” will automatically take you to the location of Figure 1 within the document.

This manual consists of several sections and is structured as follows:

• Introduction – this introductory chapter.

• Getting Started – provides instructions for installing the tool, and how to contact MatrikonOPC’s Support team.

• Configuration – shows how to start and configure the tool.

http://www.opcfoundation.org/�



• Limitations - provides information on specific performance and operational limitations of the software.

• Troubleshooting – provides solutions for common problems that may be encountered, and answers to frequently asked questions.

• Un-installation – provides instructions on un-installing software.

References This document references information found within the following documents/sites:

• www.opcfoundation.org

• www.matrikonopc.com

• www.opcsupport.com

Document Terminology The following terms are used interchangeably throughout this document:

• screen and window

• MatrikonOPC UA Wrapper for COM OPC Servers, MatrikonOPC UA Wrapper, and UA Wrapper

Table 1 provides a list of definitions for terms and abbreviations used throughout this document.

Term/Abbreviation Description

AE OPC Alarms and Events.

COM Component Object Model. A method for organizing software, specifying how to build components that can be dynamically interchanged.

DA OPC Data Access. Provides access to real-time process data.

HDA OPC Historical Data Access.

HTTP Hypertext Transfer Protocol. A communications protocol.

Matrikon Matrikon Inc.

MatrikonOPC Matrikon’s brand name for its OPC servers and clients.

OPC A communication standard. Refer to www.opcfoundation.org for more information.

TCP Transmission Control Protocol. A transport layer protocol.

UA Unified Architecture.

UA SDK

The UA SDK is a set of interfaces, libraries, and executables that allow developers to quickly create UA applications with the .NET programming environment. The SDK includes:

• Implementations of the XML Web Services and UA Native Binary stack profiles.

• Server and client development toolkits. • Sample applications. • A wrapper for COM DA (DA 2.05a and DA 3.00) and AE servers. • A proxy for COM DA and COM AE clients (DA 2.05a and AE 1.1).


http://www.matrikonopc.com/�

http://www.opcsupport.com/�



Term/Abbreviation Description • Local discovery server. • Configuration tool1

Table 1 - Terms and Definitions

.

1 “UA SDK 1.00.281.1 Readme”. (July 26, 2008). OPC Foundation website.


Getting Started This chapter contains important information about installing the MatrikonOPC UA Wrapper for COM OPC Servers and how to contact Matrikon’s Support team.

The System Requirements section shows how to avoid future problems by ensuring that the system meets the minimum software and hardware requirements. Detailed step-by-step instructions in the Installation section walks the user through the installation process and lists the files that are installed during this process.

Once the software has been installed, refer to the Licensing Procedures document that was installed along with the tool and this User’s Manual, to learn how to obtain the appropriate license. If any problems are encountered during installation or licensing, refer to the Contacting Support section for information about how to contact the MatrikonOPC Support team for assistance.

System Requirements The software has minimum Software and Hardware system requirements. These requirements must be met for the software to function properly.

Note: To install and configure a MatrikonOPC UA Wrapper, you must be set up as an administrative user account rather than a restricted user account.

Software Requirements The tool requires the following software:

• Microsoft Windows XP, 2003, 2008, or 7

Notes:

• The minimum requirement for Microsoft Windows XP is Service Pack (SP) 2. The minimum requirement for Microsoft Windows 2003 is SP1.

• It is recommended that the most current service packs are installed.

• Microsoft .NET Framework Runtime 3.5 (can be downloaded from www.microsoft.com)

• Microsoft Visual Studio 2008 Redistributable (can be downloaded from www.microsoft.com)

• OPC Core Components Redistributable version 3.00 or newer (refer to the Installation section in this document for information on installing these components)

Hardware Requirements The server requires the following hardware:

• Intel® Pentium® 4 Processor

• 512 MB RAM

• 40 GB 7200 RPM hard drive

Installation Once the system requirements have been met, you are ready to install the software.

http://www.microsoft.com/�

http://www.microsoft.com/�


Note: As part of the installation process, the MatrikonOPC Analyzer tool is installed and used to detect the system settings that affect the use of this software. No information is communicated back to Matrikon. Information is stored on this system only for future use by MatrikonOPC Support to assist with troubleshooting, if required.

To install the software:

1. Insert the MatrikonOPC UA Wrapper for COM OPC Servers CD into the CD drive.

2. If the MatrikonOPC Welcome screen does not automatically appear, double-click the MatrikonOPCUAWrapperCOM.exe file. The MatrikonOPC UA Wrapper for COM OPC Servers – InstallAware Wizard verifies its contents (Figure 1).

Figure 1 - InstallAware Wizard Verification Window

3. If your system lacks the pre-requisites to install the UA Wrapper, the MatrikonOPC UA Wrapper for COM OPC Servers Pre-Requisites screen (Figure 2) appears. Go to step 4.

Note: If the pre-requisites already reside on your system, the Licensing Agreement screen is displayed. Go to step 15.


Figure 2 - MatrikonOPC UA Wrapper for COM OPC Servers Pre-Requisites Screen

4. Click on the Next button. The Installing MatrikonOPC UA Wrapper for COM OPC Servers Pre-Requisites screen (Figure 3) appears.


Figure 3 - Installing MatrikonOPC UA Wrapper for COM OPC Servers Pre-Requisites Screen

5. While the pre-requisites are being installed, the OPC Core Components Redistributable License Agreement window (Figure 4) appears.


Figure 4 - OPC Core Components Redistributable License Agreement Window

6. Select the I Agree option button. Click on the Next button.

7. The OPC Core Components Redistributable Select Installation Folder window (Figure 5) appears.


Figure 5 - OPC Core Components Redistributable Select Installation Folder Window

8. Specify the required installation folder.

9. Select the appropriate option to define whether the OPC Core Components Redistributable is to be installed just for your or for anyone using the machine.

10. Click on the Next button. The Confirm Installation window (Figure 6) appears.


Figure 6 - Confirm Installation Window

11. Click on the Next button to start the OPC Core Components Redistributable installation.

12. The Installing OPC Core Components Redistributable window (Figure 7) appears and the install occurs.


Figure 7 - Installing OPC Core Components Redistributable Window

13. The Installation Complete window (Figure 8) appears once the OPC Core Components Redistributable has been successfully installed.


Figure 8 - Installation Complete Window

14. Click on the Close button to close the Installation Complete window.

15. The License Agreement screen (Figure 9) appears.

Notes:

• If the OPC Core Components are already installed on your machine, the License Agreement screen is the first screen the InstallAware Wizard displays.

• The Version number located in the lower left corner indicates the version number of the software that is being installed. The text “X.X.X.X” will be replaced with the specific product version.

• From the License Agreement screen, you have the option of selecting the I reject the license agreement option. Selecting the I reject the license agreement option button disables the Next button so your options are to return to cancel the install by clicking on the Cancel button, or select the I accept the license agreement option button enabling you to proceed through the install.


Figure 9 - License Agreement Screen

16. Read the Software License Agreement, using the scroll bar to view the entire message.

17. Select the I accept the license agreement option button.

18. Click on the Next button. The Setup Type screen (Figure 10) appears.


Figure 10 - Setup Type Screen

19. Select the type of setup to be performed.

Notes:

• MatrikonOPC recommends that you select the Complete Setup option.

• From this point onward, the Back button is available allowing you to return to the previous screen or screens.

20. Click on the Next button. The Destination Folder screen (Figure 11) appears.


Figure 11 - Destination Folder Screen

21. Select the folder in which to install MatrikonOPC UA Wrapper for COM OPC Servers, or accept the default location displayed in the Folder path field.

22. Click on the Next button. The Licensing screen (Figure 12) appears.


Figure 12 - Licensing Screen

23. Select the applicable licensing option.

24. Click on the Next button. The Ready to Install screen (Figure 13) appears.


Figure 13 - Ready to Install Screen

25. Click on the Next button. The Installing MatrikonOPC UA Wrapper for COM OPC Servers screen appears.

26. Installation begins, and the product files are copied to the computer.

Note: Prior to starting the installation, you have the option of clicking on the Back button to change any of the installation information. Click on the Cancel button if you wish to stop or cancel the installation.

27. When the installation has finished, the MatrikonOPC UA Wrapper for COM OPC Servers Setup Complete screen (Figure 14) appears stating that the tool has been successfully installed.


Figure 14 - MatrikonOPC UA Wrapper for COM OPC Servers Setup Complete Screen

28. At this point you have the options of launching the UA Wrapper’s Release Notes and/or User’s Manual. Select the necessary checkbox or checkboxes.

29. Click on the Finish button to complete the installation and exit the Wizard.

30. The necessary files are copied to the target computer, the software components are registered, and shortcut icons are created in the Start menu.

Installed Files The installation program copies all necessary files to the target computer and creates shortcut icons in the Start menu.

All files installed with the UA Wrapper are listed in the following tables. For a list of the files installed for any accompanying software (e.g., MatrikonOPC Server for Simulating and Testing, MatrikonOPC Analyzer), refer to corresponding User’s Manual installed with corresponding software.

The files listed in Table 2 are installed by default, in the following location:

C:\Program Files\Matrikon\OPC\UAWrapper


File Name Description

Licensing Procedures.pdf Licensing Procedures document. MatrikonOPC UA Wrapper for COM OPC Servers Release Notes.pdf Release Notes for this product.

MatrikonOPC UA Wrapper for COM OPC Servers User Manual.pdf User’s Manual for this product.

MatrikonOpcUaWrapper.exe UA Wrapper executable file.

MatrikonOpcUaWrapper.exe.config Allows some logging parameters to be set and points to the main configuration file.

LicensingWrapperCLR.dll

UA Wrapper application extensions.

Opc.Ua.Client.dll

Opc.Ua.Configuration.dll

Opc.Ua.ComInterop.dll

Opc.Ua.Core.dll

Opc.Ua.QuickstartsLibrary.dll

Opc.Ua.Server.dll

lsapiw32.dll RmsApiProxy.dll

Licensing library.

Table 2 - Files Installed in "UAWrapper" Folder


C:\Program Files\Common Files\MatrikonOPC\Common


LicenseRemover.exe MatrikonOPC License Remover executable.

LicenseWizard.exe MatrikonOPC Licensing Wizard executable. Table 3 - Files Installed in "Common" Folder


C:\Documents and Settings\All Users\Application Data\Matrikon\UA


MatrikonOpcUaWrapper.Config.xml Main configuration file. MatrikonOpcUaWrapper.log.txt Log file

Table 4 - Files Installed in “C:\Documents and Settings\All Users\Application Data\Matrikon\UA” Folder

Licensing Most MatrikonOPC products require some form of licensing criteria be met to ensure that it functions successfully.

The MatrikonOPC UA Wrapper for COM OPC Servers supports software licensing only. Licensing information is described, in detail, within the Licensing Procedures document that accompanies this manual.


Contacting Support The MatrikonOPC Customer Services department (www.opcsupport.com) is available 24 hours a day, seven days a week.

Contact MatrikonOPC Support using the information below, or send an email ([email protected]).

For Monday to Friday daytime support requests, contact MatrikonOPC Support using the regional phone numbers provided in Table 5.

Region Office Hours Contact Information

North America UTC/GMT -7 hours (MST)

8:00am-5:00pm +1-877-OPC-4-ALL

Europe /Africa * UTC/GMT +1 hours (CET)

9:00am-5:00pm +49-221-969-77-0 (Request OPC Support)

Australia/Asia * UTC/GMT +10 hours (AEST)

9:00am-5:00pm +61-2-4908-2198 (Request OPC Support)

* Toll-free regional numbers coming soon! Table 5 - MatrikonOPC Support Regional Contact Information

For after-hours support in all regions, please use the following number. There is no extra charge from MatrikonOPC for calling their after-hours support number.

Region Contact Information

All +1-780-231-9480 Table 6 - After-Hours Support


mailto:[email protected]�


Configuration The MatrikonOPC UA Wrapper allows users to alter configuration parameters using configuration files.

Minimal configuration of the MatrikonOPC UA Wrapper for COM OPC Servers is required for it to function properly. You can customize its behaviour as required. This section of the manual shows you how to start, configure, and shut down the software—describing each step in detail.

Starting and Stopping the MatrikonOPC UA Wrapper for COM OPC Servers shows you how to start and/or stop the software. The MatrikonOPC UA Wrapper for COM OPC Servers Configuration section describes in detail how to configure the tool.

Starting and Stopping the MatrikonOPC UA Wrapper for COM OPC Servers The MatrikonOPC UA Wrapper for COM OPC Servers is installed as a Windows service. You can start or stop it using the Service Control Manager applet under the Control Panel.

To start or stop the MatrikonOPC UA Wrapper for COM OPC Servers:

1. Click on the Windows Start button and select Control Panel -> Administrative Tools -> Services.

2. The Services window appears,

3. From the Services window, choose MatrikonOPC UA Wrapper for COM OPC Servers.

4. Start or stop the service, as required.

The MatrikonOPC UA Wrapper for COM OPC Servers can also run as a standalone application from the Start menu. However, only one instance of the application can run at a time. An attempt to run a second instance displays a warning message window (or logs a warning message into the Windows Event Log should an attempt be made to start it as a service) and the application exits.

MatrikonOPC UA Wrapper for COM OPC Servers Configuration The MatrikonOPC UA Wrapper for COM OPC Servers is configured by editing configuration files in any text editor. There are two configuration files:

1. MatrikonOpcUaWrapper.exe.config – allows some logging parameters to be set and points to the main configuration file.

2. MatrikonOpcUaWrapper.Config.xml – main configuration file (its full path is set on the MatrikonOpcUaWrapper/ConfigurationLocation/FilePath element of the MatrikonOpcUaWrapper.exe.config file). By default, this file is located in the C:\Documents and Settings\All Users\Application Data\Matrikon\UA folder (refer to the Installed Files section). Table 7 lists some of the parameters configured in this file.

Note: The structure of the configuration files is similar to that of the OPC Foundation’s UA Sample Server configuration file.

Element Description

SecurityConfiguration/ ApplicationCertificate

Configures the certificate which is used to verify the UA server instance. If the certificate does not exist, a self-signed certificate is created automatically.

ServerConfiguration/ BaseAddresses

Allows modification of the URL used to access the UA server, including TCP port number.


Element Description

ServerConfiguration/ UserTokenPolicies

Lists available User Token Policies. By default, three types of user identity are enabled: • Anonymous: No user information is available. • UserName: A user identified by Windows domain user name and password. • IssuedToken: A user identified by a Kerberos token. Refer to the Questions and Answers section for more information about Kerberos authentication.

Registration Endpoint Configures the data required to register the UA server’s instance on the UA Discovery server.

TraceConfiguration Configures log file options.

Extensions/ ComWrapperServerConfiguration/ WrappedServers

This section defines the list of COM OPC servers that should be wrapped. The default configuration file has the following pre-configured settings:

• If MatrikonOPC UA Wrapper for OPC COM Servers is installed as part of MatrikonOPC Security Gateway, then it has one wrapped OPC DA server: MatrikonOPC Security Gateway Server.

• If MatrikonOpcUaWrapper is installed not as part of MatrikonOPC Security Gateway, then it has multiple wrapped instances of MatrikonOPC Server for Simulation and Testing (instances utilize different connection interfaces: DA, HDA, DA and HDA combined, A&E).

The list of wrapped COM OPC servers can also be configured from the configuration window. Refer to the following section below for more details.

Table 7 - MatrikonOpcUaWrapper.config.xml Configured Settings

Wrapped COM OPC Server Configuration When the MatrikonOPC Wrapper for COM OPC Servers is run in application mode, it displays a configuration window (Figure 15).


Figure 15 - MatrikonOpcUaWrapper Configuration Window

The configuration window has three panels:

• Server Endpoint URLs – contains the list of available endpoints to access the server.

• Sessions – contains the list of open UA client sessions.

• Subscriptions – contains the list of open subscriptions.

To add, edit, or remove wrapped COM OPC servers, click on Config and then select Wrapped COM OPC Servers to display the Wrapped COM OPC Servers window (Figure 16).

Click on any of the Add, Edit, or Remove buttons to modify the wrapped servers list.


Figure 16 – Wrapped COM OPC Servers Configuration Window

Click on the Add to open the Add Wrapped COM OPC Server window (Figure 17).

Figure 17 - Add Wrapped COM OPC Server Window


The Add Wrapped COM OPC Server window contains a list of the COM OPC servers that are accessible from the given host. Type a new Host Name and click on the Refresh button to view the OPC servers of another computer. Select the A&E option button and then again click on the Refresh button to view the available A&E OPC servers.

The list of COM OPC servers is retrieved using the OPCEnum service. Therefore, OPCEnum must be running on the specified host. Additionally, the DCOM settings must be properly configured.

The Add Wrapped COM OPC Server window allows you to select only an OPC server. To finish configuring the wrapped server, select the server and click on the Edit button on the Wrapped COM OPC Servers window. The Edit Wrapped COM OPC Server window is displayed.

Figure 18 - Edit Wrapped COM OPC Server Window

To change the host computer of the COM OPC server, type the computer name in the Host field. Click on the Refresh URLs button to reload the lists of available OPC servers.

To change the URL of a DA, HDA, or A&E server, type or select from the drop-down list, the URL in DA URL, HDA URL, or A&E URL fields. These URLs are composed of the UA protocol, the host name, the ProgId, and, optionally, the class ID. To make both of a COM OPC server’s DA and HDA interfaces available from a single point in the UA Wrapper, you must supply both the DA URL and HDA URL, even if they are identical.

The Display Name is the name that appears in the UA Wrapper’s address space. This name must be unique among the wrapped servers, and the name cannot be Server.

The Namespace URL is the URL that is used to distinguish the items in one wrapped OPC server from another wrapped OPC server. If the field is left empty, the DA URL or HDA URL is used. The Namespace URL must be unique among the wrapped servers. If one server is to be wrapped multiple times, a unique namespace URL must be specified for each.

If both the DA and HDA URLs are specified, select from Browse Interface to specify how the UA Wrapper should browse the OPC server.

When you are finished and click OK on the Wrapped COM OPC Servers window, you must restart the server to apply the changes.


Notes:

• This GUI-based tool allows you to configure only basic settings for wrapped COM OPC servers.

• Advanced settings can be modified by manually editing the configuration file.

• Some settings descriptions can be found in the Table 8. Note that the order of the configuration elements must be as described.

Element Description

ServerUrl ProgID for DA connection.

ServerName Display name of the wrapped COM OPC server’s root branch.

ServerNamespaceUrl Namespace URL of the wrapped COM OPC server. Note: Namespace URL values must be unique.

MaxReconnectWait The number of milliseconds to wait between attempts to reconnect to the COM OPC server. Default = 5000.

MaxReconnectAttempts The maximum number of reconnect attempts (no limit if 0). Default = 0.

FastBrowsing If set to true, item data type and EU/IU ranges/units are not defined at browse time, which speeds up browsing. Default = false.

ItemIdEqualToName If this option is true, then no GetItemId is called at browse, assuming that matches the node name. Default = false.

QueryPropertiesOnBrowse

Applicable when the IOPCBrowse interface is used for browsing. If set to true, then IOPCBrowse.Browse call will retrieve item properties too, so there will not be need to read properties on different call. Default = true.

SecurityModeString

Depending on this option, UA Wrapper will use user identity of the UA Sessions accessing nodes under the wrapped COM OPC server. Possible values are: • Empty value - no security (default value). • Impersonation - impersonation of the current thread

with Windows user account matching to the UA Session’s user identity, without calling of IOPCSecurityNT.ChangeUser method.

• IOPCSecurityNT - impersonation of the current thread with Windows user account matching to the UA Session’s user identity, followed by calling of IOPCSecurityNT.ChangeUser method.


Element Description • IOPCSecurityPrivate –> IOPCSecurityPrivate ->

Logon method is called using user name and password of the session’s UserNameIdentityToken. Later IOPCSecurityPrivate -> Logoff method is called.

MapAnonymousIdentityTo

Applicable when the SecurityModeString option is set to IOPCSecurityNt and the UA Client Session’s user identity token is AnonymousIdentityToken. Possible values are: • ANONYMOUS - "ANONYMOUS LOGON" Windows

account is used for impersonation (by calling ImpersonateAnonymousToken Windows API function). Note: Usually by default, COM OPC connections under this account fail. Additional DCOM and other settings need to be configured to make OPC COM connections under Anonymous user account working.

• UAWRAPPER - no impersonation is performed, so the thread runs under UA Wrapper process account. IOPCSecurityPrivate -> ChangeUser method will be called anyway. Attention: If this option is set to the UAWRAPPER value, carefully configure access permissions on the wrapped COM OPC servers for the user account under which the UA Wrapper process is running. Any session which uses AnonymousUserIdentity will have these access rights. Note: The IOpcServer -> GetStatus, IOPCHDA_Server -> GetItemAttributes, IOPCHDA_SyncUpdate -> QueryCapabilities, IOPCHDA_Server -> GetHistorianStatus calls must be permitted, because UA Wrapper uses default OPC connections (which run under UA Wrapper process account too) to monitor status of OPC Servers and get basic server information.

Default = ANONYMOUS.

Note: When the SecurityModeString option is set to IOPCSecurityPrivate, UA Wrapper calls IOPCSecurityPrivate -> Logon method with user name “Anonymous” and empty password for the session with AnonymousIdentityToken.

IgnoreServerMinImpersonationLevel

Applicable when the SecurityModeString option is set to IOPCSecurityNt. If set to true, UA Wrapper does not call IOPCSecurityNT -> QueryMinImpersonationLevel method. If set to false, then the UA Wrapper will call the QueryMinImpersonationLevel method and will not


Element Description communicate with the OPC server in case the impersonation level required by the OPC server is higher than the current thread’s level (which is set to the “Impersonation” level for the whole process by the CoInitializeSecurity function call at application start-up). Default = true.

ServerIdleTimeInSeconds

Determines how long will it take (in seconds) for a COM OPC Connection, associated with a corresponding UA Session's user, to close after inactivity. Default = 1.

ServerUrlHda

ProgID for HDA OPC server. Note: Both ServerUrl and ServerUrlHda options can be defined. In this case, the UA Wrapper will create both DA and HDA connections to that OPC server.

PreferredBrowseInterface

Browsing interface. Possible values are: • IOPCBrowse (applicable for DA3 connections only) • IOPCBrowseServerAddressSpace (applicable for

DA2 connections only) • IOPCHDA_Browser (applicable for HDA connections

only) If this option is omitted, then the UA Wrapper defines browsing interface as follows: If the ServerUrl option is set to a valid OPC DA Server ProgID, it tries to use IOPCBowse interface. If that attempt does not succeed, it tries to use IOPCBrowseServerAddressSpace interface. Otherwise, if the ServerUrlHda option is set to a valid OPC HDA Server ProgID, it will try to use the IOPCHDA_Browser interface.

SeperatorChars

Applicable when the FastBrowsing option is set to true, to define OPC item’s display name and its parent branch’s display name by parsing its node ID (which in turn contains OPC Item ID). Parsing is performed based on assumption that Item ID has the following format: [ParentFolderId | Delimiter | ItemName]. For example, if the Item ID is Random.Int1, then ParentFolderId=Random, Delimiter=. and ItemName=Int1. The UA Wrapper attempts to parse the Item IDs by looking for the one of these characters starting from the end.

Table 8 - MatrikonOpcUaWrapper.config.xm, section ComOpcClientConfiguration Settings


Limitations MatrikonOPC UA Wrapper for COM OPC Servers has no known or expected limitations. Refer to the MatrikonOPC UA Wrapper for COM OPC Servers Release Notes for known issues.


Troubleshooting The following section addresses some of the most common problems encountered, and questions asked, while using this OPC server. Please check the following Problems/Solutions and Questions/Answers sections before contacting the MatrikonOPC Support team.

Problems and Solutions

Browsing many tags results in a time out error

Problem: If the UA client does not restrict the maximum number of references to return, browsing can appear to freeze or time out when the wrapped OPC server has a large number of tags in its address space.

Solution: Browsing a large address space can be optimized by using the new Filtered Browsing functionality introduced in version 1.1.0.0 of the UA Wrapper. A browsing filter can be set for the entire session by using the Set Browse Filter method. This method has three arguments:

• Browse Filter, String: Filter expression which is passed to the OPC server as is.

• Apply for items, Boolean: If true, the filter is applied to items. • Apply for branches, Boolean: If true, the filter is applied to branches.

Note: Browsing is performed in two stages - the first is for branches and the second is for items. A filter can also be set in a Browse request. In this case, the filter expression is appended to the node identifier following a colon. :i and :b can additionally be appended to limit the filter to items or branches respectively. To use a colon in the filter expression, prefix the colon with an ampersand. Following are examples of node identifiers with filter expressions:

• bRandom:Int* - browse the Random branch for all items and branches that start with “Int”.

• bRandom:Int*:i – browse the Random branch for all items that start with Int, and all branches.

• bSimulation&:Items:R*:b – browse the Simulation:Items branch for all branches that start with R, and all items.

Note: If a non-empty filter is set for the entire session (by calling the SetBrowseFilter method), the filter is applied to all Browse requests that do not specify a filter.

Cannot connect to the UA Wrapper after renaming the computer

Problem: After renaming the computer, UA clients cannot to the UA Wrapper or Discovery Server.

Solution: Open the configuration files (MatrikonOpcUaWrapper.Config.xml and Opc.Ua.DiscoveryServer.Config.xml) and search for all instances of the old computer name. Replace these with the new computer name.

Remote OPC UA Client cannot connect to MatrikonOPC UA Wrapper

Problem: The remote OPC UA client cannot connect to the MatrikonOPC UA Wrapper, although


the local OPC UA client connects without a problem.

Solution: One possible reason for this issued could be that the firewall settings on the host, where the MatrikonOPC UA Wrapper runs, does not allow TCP/HTTP communication on configured ports (default port numbers are 21380 for HTTP and 21381 for TCP). Check the firewall settings and open any ports that were closed.

“No connection could be made because the target machine actively refused it” error

Problem: When the UA Wrapper service runs under a User account which is not an Administrator group member, it can start. However, a UA client (either local or remote) cannot connect to it and the following error is displayed “No connection could be made because the target machine actively refused it”.

Solution: There can be two reasons preventing the UA server from opening a communication channel over TCP:

1. User account does not have access rights to the application certificate defined in the .xml configuration file.

2. User account does not have access rights to create a TCP port for listening.

Solution for Reason 1: Make sure the user account, under which the UA Wrapper process is running, has access rights to the application certificate defined in the configuration file. There are two tools for configuring access rights for a certificate’s private keys:

1. Using the command-line winhttpcertcfg.exe tool. 2. Using Web Services Enhancements 3.0 for Microsoft .NET (WSE) with

GUI. Using the winhttpcertcfg.exe tool: To print the list of user accounts that has access to a particular certificate, use the following command line: winhttpcertcfg /l /c “local_machine\my” /s “MatrikonOPC UA Wrapper for COM OPC Servers”. Here “local_machine\my” matches “Local Computer\Personal\Certificates” in the certificates store (i.e., Console Root\Certificates (Local Computer)\Personal\Certificates). If the UA Wrapper process user account is not listed, then access rights should be granted to that account. For example, to grant access to the user “test”, enter the following: winhttpcertcfg /g /c “local_machine\my” /s “MatrikonOPC UA Wrapper for COM DA Server” /a test More detailed information on how to use the winhttpcertcfg utility can be obtained by using the winhttpcertcfg /h command. Note that winhttpcertcfg tool is included in Windows Server 2003 Resource Kit Tools which can be downloaded from the following link: http://www.microsoft.com/downloads/details.aspx?familyid=9d467a69-57ff-4ae7-96ee-b18c4790cffd&displaylang=en winhttpcertcfg.exe can be also downloaded using the following link: http://www.microsoft.com/downloads/details.aspx?displaylang=en&familyid=C42E27AC-3409-40E9-8667-C748E422833F Note: Supported operating systems for winhttpcertcfg.exe are the Windows

http://www.microsoft.com/downloads/details.aspx?familyid=9d467a69-57ff-4ae7-96ee-b18c4790cffd&displaylang=en�

http://www.microsoft.com/downloads/details.aspx?familyid=9d467a69-57ff-4ae7-96ee-b18c4790cffd&displaylang=en�

http://www.microsoft.com/downloads/details.aspx?displaylang=en&familyid=C42E27AC-3409-40E9-8667-C748E422833F�

http://www.microsoft.com/downloads/details.aspx?displaylang=en&familyid=C42E27AC-3409-40E9-8667-C748E422833F�


server 2003 family, Windows XP, and Windows 2000 family. For information on how to use WSE, use the following link: http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en#Overview WSE can be downloaded from the following location: http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en

Solution for Reason 2: Access rights for user accounts can be configured by using the httpcfg.exe utility which is included in the Windows XP Service Pack 2 Support Tools and can be downloaded from the following location: http://go.microsoft.com/fwlink/?LinkId=88606 In the case of Windows Vista, these settings are configured with the Netsh.exe tool. Example: Httpcfg set urlacl /u ”http://+:21380/UA/MatrikonOpcUaWrapper” /a D:(A;;GX;;;S-1-1-0) In this example, D:(A;;GX;;;S-1-1-0) is the Security Descriptor Definition Language (SDDL) string, which translates to grant (A) Generic Execution (GX) permission to user account EVERYONE, defined by SID “S-1-1-0”. The SID of user accounts can be obtained using the getsid utility included in the same Windows XP Service Pack 2 Support Tools. For more information see the article entitled Httpcfg Overview which can be accessed via the following link: http://go.microsoft.com/fwlink/?LinkId=88605

Browsing a wrapped OPC server returns fewer results than browsing from an OPC client directly

Problem: When a wrapped OPC server is browsed via MatrikonOPC UA Wrapper from a UA client, returned results are fewer than when browsing from MatrikonOPC Explorer connected to the same OPC server. For example, tables cannot be browsed from a wrapped MatrikonOPC Server for GDA or processes cannot be browsed from MatrikonOPC Server for Performance Monitor.

Solution: Try using a different browsing interface. The browsing interface can be changed from the configuration window or in the MatrikonOpcUaWrapper.Config.xml file by searching for the PreferredBrowseInterface element. Possible values are IOPCBrowse, IOPCBrowseServerAddressSpace, and IOPCHDA_Browser. For example, when the IOPCBrowseServerAddressSpace interface is used for MatrikonOPC Server for GDA, tables can be browsed correctly. By default, MatrikonOPC UA Wrapper uses the IOPCBrowse interface. Using this interface requires that the wrapped OPC server return branch Item IDs in the IOPCBrowse.Browse method call. Using the IOPCBrowseServerAddressSpace requires that the wrapped OPC server support the OPC_BROWSE_TO option in the IOPCBrowseServerAddressSpace.ChangeBrowsePosition method.

http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en#Overview�

http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en#Overview�

http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en�

http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en�

http://go.microsoft.com/fwlink/?LinkId=88606�

http://go.microsoft.com/fwlink/?LinkId=88605�


Questions and Answers

How do I remove the MatrikonOPC UA Wrapper for COM OPC Servers as a service?

Problem: How do I remove the MatrikonOPC UA Wrapper for COM OPC Servers as a service?

Solution: Use the MS-DOS command sc delete MatrikonOpcUaWrapper.

How do I configure the MatrikonOPC UA Wrapper for COM OPC Servers to pass through UA Session’s User Identity to the end OPC server?

Problem:

How do I configure the MatrikonOPC UA Wrapper for COM OPC Servers to pass through UA Session’s User Identity to the end OPC server?

Solution:

When a UA client connects to the UA Wrapper, it will provide information about the user credentials (in the ActivateSession request, UserIdentityToken parameter). The supported types of user identity are listed in the ServerConfiguration/ SecurityPolicies section of the configuration file and include the following:

1. AnonymousIdentityToken - no user information is sent to the UA Wrapper. 2. UserNameIdentityToken - a user is identified by their Windows or Active

Directory user name. The user would typically enter their user name and password into the UA client when connecting to the UA Wrapper.

3. IssuedIdentityToken - a user is identified by their Active Directory user name, but does not have to enter their name or password when connecting to the UA Wrapper. The user is authenticated automatically by the UA Wrapper (using a Kerberos token). Note that the Service Principal Name for the UA Wrapper application must be registered on domain controller, and the UA Wrapper process’s user account must have proper access rights to use Kerberos tokens (particularly “Account is trusted for delegation” and “Use DES encryption types for this account”). To set the Service Principal Name, the Windows command line tool setspn.exe (included in Windows Support Tools) can be used. The syntax is as follows: setspn -A MatrikonOpcUaWrapper/hostName userName where: hostName is the name of the computer where UA Wrapper is running. userName is the user account under which the UA Wrapper is running.

Once a session’s user identity is authenticated, UA Wrapper can use that identity on communications with wrapped OPC servers. When a UA client requests data from nodes on a wrapped OPC server, a separate DA and HDA OPC connection is created for each combination of LocaleId and User Name. Such connections remain open while the UA client sessions are not closed. Connection is closed when all sessions, which used that connection at least once, are closed (but not immediately) after a period of inactivity defined by the ServerIdleTimeInSeconds option of the configuration file.

Note: Additional DA connections may be created during Browse requests if the PreferredBrowseInterface is configured to use IOPCBrowse or IOPCBrowseServerAddressSpace.

How the user identity is used on OPC COM connections can be configured in the Extensions/ComWrapperServerConfiguration/WrappedServers/ComClientConfiguration section of the configuration file. See Table 8 for option descriptions.


Search the MatrikonOPC Support Knowledge Base at www.opcsupport.com to find the answers to other commonly-asked MatrikonOPC UA Wrapper for COM OPC Servers questions.



Un-Installation To successfully un-install MatrikonOPC UA Wrapper for COM OPC Servers, using the Add or Remove Programs from the Microsoft Windows Control Panel is recommended.

To un-install MatrikonOPC UA Wrapper for COM OPC Servers:

1. Click on the Start button and highlight the Control Panel item.

2. From the displayed menu, select Add or Remove Programs.

3. The Add or Remove Programs window (Figure 19) is displayed.

4. Scroll through the list of currently installed programs and updates to find and select MatrikonOPC UA Wrapper for COM OPC Servers.

Figure 19 - Add/Remove Programs

5. Click on the Remove button associated with the MatrikonOPC UA Wrapper for COM OPC Servers program to initiate the un-install process.

6. The MatrikonOPC UA Wrapper for COM OPC Servers – InstallAware Wizard appears and the Welcome to MatrikonOPC UA Wrapper for COM OPC Servers Maintenance screen (Figure 20) is displayed.


Figure 20 - Welcome to MatrikonOPC UA Wrapper for COM OPC Servers Maintenance Screen

7. Ensure the Remove option button is selected to un-install MatrikonOPC UA Wrapper for COM OPC Servers entirely.

8. Click on the Next button. The Ready to Uninstall window (Figure 21) is displayed.


Figure 21 - Ready to Uninstall Screen

9. Click on the Next button.

10. The Uninstalling MatrikonOPC UA Wrapper for COM OPC Servers screen (Figure 22) appears and the un-install takes place.


Figure 22 - Uninstalling MatrikonOPC UA Wrapper for COM OPC Servers Screen

11. When the un-install has finished, the MatrikonOPC UA Wrapper for COM OPC Servers Setup Complete screen (Figure 23) appears stating that MatrikonOPC UA Wrapper for COM OPC Servers was successfully un-installed.


Figure 23 - MatrikonOPC UA Wrapper for COM OPC Servers Setup Complete Screen

12. Click on the Finish button to complete the un-install and exit the Wizard.

13. The program no longer appears listed in the Add or Remove Programs window.

MatrikonOPC UA Wrapper for COM OPC Servers User Manual

Documents

Transcript of MatrikonOPC UA Wrapper for COM OPC Servers User Manual