PI OPC DA Server User Guide

Transcription

1 PI OPC DA Server 2017 User Guide

2 OSIsoft, LLC 1600 Alvarado Street San Leandro, CA USA Tel: (01) Fax: (01) Web: PI OPC DA Server 2017 User Guide by OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive, PI DataLink, PI DataLink Server, PI Developer s Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB Provider, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK, and RtReports are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Version: Published: 21 March 2017

3 Contents Introduction... 1 Requirements... 1 OPC compatibility... 1 Reference manuals... 1 Supported features... 2 Principles of Operation... 3 Connecting to PI OPC DA Server ItemIDs, browsing, and PI tags... 3 Browsing and filtering... 3 Quality codes... 4 Update rates... 4 DA Advise vs. Read...4 DA groups... 4 Canonical data types... 5 Additional resources... 7 Installation and configuration... 9 DCOM Configuration... 9 Notes on DCOM configuration...10 Run PI OPC DA Server 2017 as a service Security Message logs Technical support and other resources PI OPC DA Server 2017 User Guide iii

4 Contents iv PI OPC DA Server 2017 User Guide

5 Introduction PI OPC DA Server 2017 (OPCDA2) is an OPC Server for OSIsoft s PI System. It implements the OPC Data Access (DA) standard 2.05a. It supports browsing, synchronous reads, asynchronous reads, read on change (also known as advise data), and writes. This server interoperates with any OPC Client that is compliant with the above standard, to allow the user to read data from the PI System and write data to the PI System. The server can be installed on the same machine as a PI System, or it can be installed on a separate machine. It communicates with any PI Server in the Known Servers Table (see the Connections option from your PI System), and can serve data from multiple PI Servers simultaneously. It is not intended or designed to be used as a high speed data collection tool, as its generic nature means it is not optimized for high throughput. Note: You can install PI OPC DA Server 2017 on the same node as the PI System. However, OSIsoft does not recommend this because it might lead to resource contention between PI OPC DA Server 2017 and the PI System and might substantially affect the performance of both systems. Requirements PI Server minimum PI AF SDK 2.7 or higher Microsoft Windows 2008 Server R2, Windows 7, or later. Both 32-bit and 64-bit operating systems are supported. OPC compatibility OPC Data Access (DA) 2.05a Reference manuals The following references might be helpful when working with PI OPC DA Server: OPC Data Access Custom Interface Standard Version 2.05a, available at the OPC Foundation Archives ( Note: In order to view or download this manual from the OPC Foundation Archives you must have an account with OPC Foundation. The same applies to other copies of the OPC DA standard that are available from the OPC Foundation website ( DCOM Configuration Guide ( action=html&resource=publist_home.html&pub_category=dcom-security-and- Configuration). PI OPC DA Server 2017 User Guide 1

6 Introduction Supported features Feature Part number Platforms Support OPC Data Access Standard 2.05a PI-OPC-SRV Windows 7, Windows Server 2008 R2, or later PI point types real / digital / integer / float32 / float16 / float64 / string / int16 / int32 Sub-second timestamps Automatically incorporates PI point attribute changes Exception reporting Outputs from the PI System Inputs to the PI System Uses PI AF SDK Platforms PI OPC DA Server 2017 is designed to run on the above mentioned Microsoft Windows operating systems. Please refer to the DCOM Configuration Guide ( LiveLibrary/web/ui.xql?action=html&resource=publist_home.html&pub_category=DCOM- Security-and-Configuration) when configuring PI OPC DA Server 2017 DCOM for the first time. Please contact OSIsoft Tech Support ( for more information. Yes Yes Yes Yes Yes Yes 2 PI OPC DA Server 2017 User Guide

7 Principles of Operation PI OPC DA Server 2017 provides access to PI System data for any OPC Client. It allows a user to browse the PI namespace and get information about the properties of PI tags. Users can read and write current values, and sign up to receive new values as they become available. PI OPC DA Server 2017 does not provide read or write access for annotations. PI OPC DA Server 2017 uses the PI AF SDK to access data from the PI System. Connecting to PI OPC DA Server 2017 PI OPC DA Server 2017 ProgID is OSISOFT.OPCDA2.DA.1. This ProgID should appear in the server list of any OPC DA Client. Restricting requests to the proper server is currently left up to the user, to allow for the most flexibility. ItemIDs, browsing, and PI tags OPC DA is based on an ItemID, which identifies a data store for a particular variable. PI tags are mapped to an ItemID so that a client can read from and write data to a PI tag. The fully qualified ItemID for a PI tag has the following structure: servername\tagname, or in the case of a PI Collective: collectivename\tagname. Browsing and filtering The OPC DA standard allows browsing and filtering, based on a hierarchical model. For PI servers, it's a very shallow hierarchy, with PI servers being at the topmost level, and their tags below them. DA supports browsing for a BRANCH, a LEAF, and an entire namespace (FLAT). The filtering for DA is also very basic. DA allows for a filter string to be sent to the server which will be applied to the ItemID. This DA Server recognizes a string of the form localhost \sinusoid. DA filtering also supports wildcards, with * standing for zero or more letters. Each of the filter strings localhost\sinus*, localhost\*nusoid or *nuso* would match sinusoid, but only the first and last would match on sinusoidu, and only the last would find sinusoid and sinusoidu if the PI System is not on the local machine. DA filters are applied to the fully qualified name, such as localhost\sinusoid. Therefore, if only sinus is used in the filter, the server will not return any PI tags. The proper filter string should also contain either the beginning of the fully qualified name (that is localhost\) or the wildcard character. The DA Server treats filters strings as case sensitive. There are other special characters that can be used within the filter string: "?" character to represent one character, and "#" character to represent one numeric character. To specify a range of legal or illegal characters, use a set of characters in brackets, such as "[abcdz]", to match one character which is in the bracket set, or brackets with a "not", such as PI OPC DA Server 2017 User Guide 3

8 Principles of Operation "[!efghi]", to match one character which is not in the list. These filter strings behave the way the LIKE operator in Visual Basic works. For more information on how to use the filter strings, see the Microsoft website ( The combination of these wildcard characters provides a powerful tool for searching. Note: OPC DA filter strings are case sensitive. Quality codes The quality codes for OPC DA are specified in the standards, but they also allow for vendorspecific information to be passed in the high 16 bits of the Data Access quality. Where possible, PI OPC DA Server 2017 maps PI System states to the appropriate OPC quality codes, but in order to return as much information as possible, when the quality is bad, and thus there is no valid value to return, it uses the value field to return the system state code. While the OPC standard specifies that clients must not assume that the value field has a valid value if the quality is any bad quality, this allows client applications that are specifically aimed at using PI OPC DA Server 2017 to extract more useful information than could otherwise be sent. The system digital states are installed by default when the PI System is installed. See the PI Server manuals ( action=html&resource=publist_home.html&pub_category=pi-server) for more information on how to display them, or use the System Management Tool (SMT). Update rates PI OPC DA Server 2017 allows a minimum update rate of 20 milliseconds. The requested update rate will have an impact on the load on the server and might also have an impact on the load on the PI System and the network between the two. Therefore, it is advisable to use the largest appropriate update rate for each group. DA Advise vs. Read PI OPC DA Server 2017 offers two types of operations to get data from the PI System: Advise and Read. When the Advise operation is used, the server will only send an update for those PI tags that have changed their value, quality, or timestamp. The server will send those updates no more often than the update rate of the group. For example, if the update rate of the group is 2 seconds and the PI tag is getting new values every 10 milliseconds, the server will only send the most recent value to the OPC Client. The intervening values will not be seen by the OPC client. DA groups According to the OPC DA specification, DA operations are applied to groups, not to individual items. When a Read operation is applied, the server is required to send all updates for the items in the group in one response. This means that if the group has several thousand items (that is PI tags), the server must collect all the updates for all those tags from the PI System before it can send a response to the OPC client. It is obvious that if the group has many tags, this operation might not be very efficient. It might be better to have multiple groups with a 4 PI OPC DA Server 2017 User Guide

9 Principles of Operation smaller number of tags per group. Defining an optimal size for the group can be started with few hundred tags per group and adding more tags without affecting the performance. OSIsoft does not recommend you to have more than a thousand tags per group. Canonical data types Since PI data types do not exactly match the data types which can be stored in a VARIANT (which is what OPC standards specify), canonical data types have been assigned so as to allow all the PI System values to be sent through OPC. This means that, for instance, all the possible values that could be held in an Int16 tag can be read and written using an OPC data type of VT_UI2, but it is possible to store values into a VT_UI2 which cannot be stored in a PI Int16 tag. If a value is written which will not fit in the PI tag, the server will return an error indicating that the value is out of range. PI OPC DA Server 2017 will send the values as the requested data type, as long as the value can be represented in that data type. If no data type is requested, the DA server will use the following translation of PI data types to OPC data types. PI data type Digital Float16 Float32 Float64 Int16 Int32 String OPC data type VT_UI1 VT_R4 VT_R4 VT_R8 VT_UI2 VT_I4 VT_BSTR PI OPC DA Server 2017 User Guide 5

10 Principles of Operation 6 PI OPC DA Server 2017 User Guide

11 Additional resources PI OPC Client Tools The PI OPC Tools Set (OPCTools) ( dc199c3c-a499-40c0-9b0f-be4e9c5d9594) is available for download from OSIsoft Tech Support Downloads. PI OPC Tools Set includes the following two Clients which might be helpful: PI_OPCClient The simple client PI_OPCClient is an easy-to-use client with which users can browse, read, write, and monitor values. It does not require any other OSIsoft software and can be used with any OPC DA Server. PI_OPCTool PI_OPCTool is an OPC DA Client with which users can test all the OPC DA functions the PI OPC DA interface uses as well as a few additional functions. A short user manual for each the PI OPC Client Tool and the PI OPC Tool is included in the PI OPC Tools Set. PI OPC DA Server 2017 User Guide 7

12 Additional resources 8 PI OPC DA Server 2017 User Guide

13 Installation and configuration Prerequisites.NET Framework (Available through Windows update or for download at the Microsoft Download Center ( id=53344).) PI AF SDK version 2.7 or later (Available for download at the OSIsoft Tech Support Downloads ( SDK/).) PI OPC DA Server 2017 comes as part of a Windows Installer package which will perform the necessary installation functions, including installing Visual Studio 2013 redistributable libraries, if necessary. PI AF SDK version 2.7 or later and.net Framework are required. Installation is not possible if they are not found. DCOM Configuration All OPC Classic Servers and clients are based on Microsoft s DCOM technology. DCOM is the network connection protocol that allows communication between nodes through the network. This type of communication requires proper DCOM configuration for all DCOM applications. Hence, both the OPC Client and server nodes must have proper DCOM settings permitting them to securely access one another remotely. This section describes DCOM configuration on both client and server nodes. There are two major configurations that must be made to properly configure DCOM permissions: Default DCOM configuration for the client node or nodes. DCOM configuration for PI OPC DA Server The general steps for DCOM configuration are similar. However, depending on whether the nodes are within the same domain or different domains, or even no domain, the sequence of steps is different. General steps for DCOM configuration DCOM configuration can be done with the DCOM Configuration utility (dcomcnfg.exe) that comes with the Windows OS. In order to be able to use this utility, the user must be logged in with administrator s privileges. This utility allows for the configuration of special security rules for all DCOM objects on the local node. The DCOM Configuration utility might look slightly different and setting options might differ, depending on the version of the Windows OS. For detailed information on how to configure DCOM, please refer to the DCOM Configuration Guide ( action=html&resource=publist_home.html&pub_category=dcom-security-and-configuration). PI OPC DA Server 2017 User Guide 9

14 Installation and configuration Notes on DCOM configuration DCOM configuration on two nodes If the two nodes are being used, both nodes have to be configured to allow access. That is because the OPC Server makes calls to the client, and the client makes calls to the server, and if the configuration is not set up to give them both permission to communicate, then communication will not be allowed. DCOM configuration on a single node Even if the same node is used for both the OPC Server and the OPC Client, DCOM still needs to be configured. In this case, make sure that DCOM permissions have been granted to the accounts under which the OPC Server and the OPC Client will run. Registration of proxy DLLs The OPC clients use proxy DLLs to communicate with the OPC Server. On the client node the opcproxy.dll file and opccomn_ps.dll file are both needed. They usually get installed with the client. However, if they are missing, they can be copied from OPC Server node and then registered. Do the following to register: 1. Make sure that opcproxy.dll and opccomn_ps.dll are copied into the Windows \system32 directory. 2. Run C:>regsvr32 opcproxy.dll. The following window should be displayed: 3. Click OK. 4. Run C:>regsvr32 opccomn_ps.dll. The following window should be displayed: 5. Click OK to complete the procedure. 10 PI OPC DA Server 2017 User Guide

15 Installation and configuration Run PI OPC DA Server 2017 as a service Successful connection of the server and client depends on both DCOM configuration and whether the server is run as a service. PI OPC DA Server 2017 can be run as a windows service or process. When the server is run as a service, the Status column in the Services window will show that the service is started. Example from the Services window The clients should be connecting to this service without starting another instance of the server. The DCOM Access Permissions are the same as when the server is not running as a service. However, the User ID that is specified in the Identity tab of the server DCOM permissions is the one that also must be entered in the Log On permissions of the service. This way the service and the DCOM settings will be set for the same user account, and prevent the scenario where one copy of the server is running as a service and DCOM tries to start another copy under another user account. To set this up in the Services window: 1. Find a service for PI OPC DA Server Right-click the service and click Properties. 3. Click the Log On tab. PI OPC DA Server 2017 User Guide 11

16 Installation and configuration Properties of the OPC DA Server for PI 12 PI OPC DA Server 2017 User Guide

17 Security The PI Firewall Database and the PI Proxy Database must be configured so that the server is allowed to write data to the PI Server. See Modifying the Firewall Database and Modifying the Proxy Database in the PI Server manuals ( LiveLibrary/web/pub.xql?action=publist_home&pub_category=PI-Server). Note: The Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure. See Trust Login Security in the chapter PI System Management of the PI Universal Data Server System Management Guide. The system will log error in the PI Message Log if the server cannot write data to the PI Server due to insufficient privileges. See the Message logs for additional information on error messaging. Security configuration using piconfig The following example demonstrates how to edit the PI Trust table: C:\PI\adm> Trust,IPAddr,NetMask,PIUser The following values are used in the security configuration: Trust: An arbitrary name for the trust table entry (e.g., a_trust_name). IPAddr: The IP Address of the computer running the Interface (e.g., ). NetMask: The network mask. In the above example, specifies an exact match with IPAddr. PIUser: The PI user entrusted as PI OPC DA Server piadmin is usually an appropriate user. Security configuration using Trust Editor The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table. See the "PI System Management" chapter in the PI Server manuals ( livelibrary.osisoft.com/livelibrary/web/pub.xql?action=publist_home&pub_category=pi- Server) for more details on security configuration. PI OPC DA Server 2017 User Guide 13

18 Security 14 PI OPC DA Server 2017 User Guide

19 Message logs This server uses trace logs to provide information that can be used when troubleshooting an error in the system. Trace logs are accessed in the program files directory on the installed machine. Trace logs Messages are written to Trace_CurrentA.log in the installation directory when the server encounters an error for which the appropriate steps might not be known. These messages are intended to provide information to OSIsoft support in the event of a problem with the server. This file is the first place to look if configuration or installation problems are suspected with the server. PI message logs Information is contained in the PI Message logs for connection and data collection issues. In a normal situation, only connection messages can be seen. However, if trouble-shooting is required, these logs might contain further information. PI OPC DA Server 2017 User Guide 15

20 Message logs 16 PI OPC DA Server 2017 User Guide

21 Technical support and other resources For technical assistance, contact OSIsoft Technical Support at or through the OSIsoft Tech Support Contact Us page ( The website offers additional contact options for customers outside of the United States. When you contact OSIsoft Technical Support, be prepared to provide this information: Product name, version, and build numbers Details about your computer platform (CPU type, operating system, and version number) Time that the difficulty started Log files at that time Details of any environment changes prior to the start of the issue Summary of the issue, including any relevant log files during the time the issue occurred To ask questions of others who use OSIsoft software, join the OSIsoft user community, PI Square ( Members of the community can request advice and share ideas about the PI System. The PI Developers Club space within PI Square offers resources to help you with the programming and integration of OSIsoft products. PI OPC DA Server 2017 User Guide 17

22 Technical support and other resources 18 PI OPC DA Server 2017 User Guide