PI Interface for OPC XML-DA
PI Interface for OPC XML-DA
Version 1.5.1.x
OSIsoft, LLC777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • Montreal & Calgary, Canada
OSIsoft, LLC Representative Office • Shanghai, People’s Republic of China
OSIsoft Japan KK • Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V. • Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil
PI Interface for OPC XML-DA
Copyright: © 2002-2013 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, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts 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 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 01/2013
Table of Contents
Chapter 1. Introduction 1
Chapter 2. Principles of Operation 3
Chapter 3. Installation Checklist 5
Data Collection Steps 5
Advanced Interface Features 6
Chapter 4. Interface Installation 7
Diagram of Hardware Connection 8
Naming Conventions and Requirements 10
Interface Directories 10
Interface Installation Procedure 11
Installing Interface as a Windows Service 11
Installing Interface Service with PIInterfaceConfigurationUtility 11
Chapter 5. Testing the XML Server Connection 15
Chapter 6. Digital States 17
Chapter 7. Point Source 19
Chapter 8. PI Point Configuration 21
Point Attributes 21
Output Points 24
Chapter 9. Startup Command File 27
Configuring the Interface with PI ICU 27
Command-line Parameters 36
Sample PI XML.bat File 43
Chapter 10. UniInt Failover Configuration 45
Overview 45
Synchronization through a Shared File (Phase 2 Failover) 47
Configuring Synchronization through a Shared File (Phase 2) 48
Configuring UniInt Failover through a Shared File (Phase 2) 51
Detailed Explanation of Synchronization through a Shared File (Phase2) 58
Failover Configuration Using PI ICU 61
Create the Interface Instance with PI ICU 61
Configuring the UniInt Failover Startup Parameters with PIICU 62
Creating the Failover State Digital State Set 62
Creating the UniInt Failover Control and Failover State Tags (Phase 2) 66
Chapter 11. Interface Node Clock 67
Chapter 12. Security 69
Chapter 13. Starting and Stopping the Interface 71
Starting Interface as a Service 71
Stopping Interface Running as a Service 71
Chapter 14. Buffering 73
Which Buffering Application to Use 73
How Buffering Works 74
Buffering and PI Server Security 74
Enabling Buffering on an Interface Node with the ICU 75
Chapter 15. Interface Diagnostics Configuration 85
Scan Class Performance Points 85
Performance Counter Points 88
Interface Health Monitoring Points 94
I/O Rate Point 99
Interface Status Point 101
Appendix A. Supported Features 103
Appendix B. Error and Informational Messages 107
Message Logs 107
Messages 107
System Errors and PI Errors 109
UniInt Failover Specific Error Messages 110
Appendix C. PI SDK Options 113
Appendix D. Debugging Levels 115
Appendix E. Technical Support and Resources 117
Appendix F. Glossary 119
PI Interface for OPC XML-DA 25
Chapter 1. Introduction
The OPC XML-DA standard uses XML to transmit OPC data. The PI Interface for OPC XML-DA collects data from OPC XML-DA data sources and stores the data in PI points. Data sources are handled through plug-ins, as follows:
· The OPC plug-in accepts data from an OPC XML-DA compliant server through SOAP messages that conform to the OPC XML-DA specification (version 1.01).
· The file reader plug-in processes local XML files. Note that this interface is optimized to handle OPC XML-DA-compliant output from OPC XML servers. For other types of data sources, including local files, the PI Interface for Universal File and Stream Loading (UFL) interface is recommended. The UFL interface is highly configurable and well equipped to handle XML and file sets.
· The http plug-in processes XML documents retrieved from a Web server using HTTP. To convert non-OPC-compliant XML to compliant XML, you can specify an XSLT file that the plug-in uses to perform XSL transforms on the contents of the files. However, a better approach is to store the original XML files on a local computer and use the PI Interface for Universal File and Stream Loading (UFL) to process this data.
For more information on topics related to the PI System and OPC XML, refer to the following documents:
OSIsoft
· PI Server manuals
· PI API Installation Manual
· UniInt Interface User Manual
Vendor
· Extensible Markup Language (XML) 1.0 (Second Edition)
· OPC XML-DA specification (version 1.01)
PI Interface for OPC XML-DA 25
Chapter 2. Principles of Operation
The OPC XML-DA interface is a client that enables data to be passed between an XML data source and a PI server. The interface connects to a single data source. To handle multiple data sources, you must run separate instances of the interface. However, more than one interface instance can connect to the same data source.
The interface uses plug-in DLLs, which transform the data sources to the OPC XML-DA specification. In addition, the plug-in DLLs can define the method of connectivity and transport of the XML data. The name and location of the plug-in DLL is specified on the command line using the /dll parameter. If this parameter is omitted, the interface loads the OPC plug-in DLL
After the plug-in DLL is loaded, the OPC XML-DA interface tries to establish a connection to the PI server and check the status of the XML server. If a successful response is received, the interface will then initiate requests to get data from the XML server. If the connection is not successful, the interface will try to establish a connection periodically.
Note: The connection with the XML server is not persistent. However, if a connection is lost, data can be buffered by the XML server if supported by that server. Upon successful reconnection to the XML server, all historical values can be retrieved if the tag is configured to do so. The amount of data buffered is dependent on the XML server.
The interface identifies its tags based on the PointSource and Location1 point attributes. Tag configurations can be edited while the interface is running and these changes will be picked up by the interface automatically. In general, the interface will check for tag edits every 2 minutes. However, if it finds that at least 25 tags have been edited, it will check again in 30 seconds, otherwise it will wait another 2 minutes before checking again. All tag edits are performed in the following way: old versions of edited tags are deleted from the interface; new versions are added in. With some servers, this operation can require more time and more system resources. Therefore, it is more efficient to stop and restart the interface if a large number of tags are edited.
The OPC XML-DA interface logs the following information and events to the PI message log file:
· Informational messages on interface startup and shutdown;
· The scan rate for each scan class and the actual update rate provided by the XML Server.
· Error messages for points rejected by the PI server, or error messages sent from the XML server;
· Notification for all connections and disconnections from the server (for example, when the connection with the XML server is lost and the interface attempts to reconnect)
The interface obtains timestamps from the XML server if the /ts option is not specified. By default, the XML server will do its own exception-based processing using the ExcDev attribute for each tag if supported by the XML server. This can be turned off by using /returnallitems command-line parameter, in which case the XML server will return all values at the specified scan rate. For XML servers that do not support exception processing, the /returnallitems command-line parameter does nothing. Further information regarding XML server exception processing can be found in the plug-in DLLs manuals. In addition to specifying the ExcDev attribute to the XML server, the interface can support multiple values being sent per scan through the use of Location3, which can be useful if the XML server supports buffering. In this case, the XML server will buffer data if communication to the interface fails. Each buffered value will have a timestamp provided by the XML server. More detailed documentation regarding how the XML server supports buffering can be found in the corresponding plug-in DLL manual.
Plug-In DLLs
To handle different types of data sources, the OPC XML-DA interface uses plug-in DLLs, which are libraries of routines that tell the interface how to get the XML data. The default plug-in is for XML servers that use SOAP over HTTP/S, as described in the OPC XML-DA specification (version 1.01). The interface does include plug-ins for http and file-based data sources, but the PI UFL interface is better suited for handling such data sources.
Communication with an XML Server
Communication with an XML server is highly dependent on the plug-in being used. Typically, the OPC XML-DA interface will check whether the server is available on startup, and if not, it will periodically recheck until the server responds. If the interface loses the connection to the PI Server after initial connection, it will continue to gather data from the XML Server. To avoid losing data in this situation, the use of the PI API buffering program, bufserv, that buffers data on the interface node, is strongly recommended. Further information about communication to the XML server can be found in the plug-in documentation.
UniInt Failover
This interface supports UniInt failover. Refer to the UniInt Failover Configuration section of this document for details.
PI Interface for OPC XML-DA 25
Chapter 3. Installation Checklist
If you are familiar with running PI data collection interface programs, this checklist helps you get the interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.
This checklist summarizes the steps for installing this interface. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of buffering for every interface node regardless of how many interfaces run on that node.
Data Collection Steps
To install the interface, perform the following steps:
- Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT on the same computer on which you run this interface.
- If you are running the interface on an interface node, edit the PI Server’s Trust Table to allow the interface to write data.
- Run the installation kit for the PI Interface Configuration Utility (ICU) on the interface node if the ICU will be used to configure the interface. This kit runs the PI SDK installation kit, which installs both the PI API and the PI SDK.
- Run the installation kit for this interface. This kit also runs the PI SDK installation kit which installs both the PI API and the PI SDK if necessary.
- If you are running the interface on an interface node, check the computer’s time zone properties. An improper time zone configuration can cause the PI Server to reject the data that this interface writes.
- Configure the startup command file using the PI ICU. The only interface-specific required parameter is:
Server (/Server=URL) See the appropriate plug-in manual for other required parameters.
- Use the PI XMLTool to confirm connection between the interface node and the device.
- If you will use digital points, define the appropriate digital state sets.
- Build input tags and, if desired, output tags for this interface. Important point attributes and their purposes are:
Location1 / The interface instance ID
Location2 / Specifies whether the point is an input (0) or output (1) point.
Location3 / The buffering setting, which is plug-in-specific.
Location4 / Scan class.
InstrumentTag / Item name.
- Start the interface interactively and confirm its successful connection to the PI Server without buffering.
- Confirm that the interface collects data successfully.
- Stop the interface and configure a buffering application (either Bufserv or PIBufss). When configuring buffering, use the ICU menu item Tools Buffering… > Buffering Settings to make a change to the default value (32678) for the Primary and Secondary Memory Buffer Size (Bytes) to 2000000, to optimize the throughput for buffering.
- Start the buffering application and the interface. Confirm that the interface works together with the buffering application by either physically removing the connection between the interface node and the PI Server node or by stopping the PI Server.
- Configure the interface to run as a service. Confirm that the interface runs properly as a service.
- Restart the interface node and confirm that the interface and the buffering application restart.
Advanced Interface Features
- Configure the interface for disconnected startup. Refer to the UniInt Interface User Manual for more details.
- Configure UniInt failover.
PI Interface for OPC XML-DA 25
Chapter 4. Interface Installation
OSIsoft recommends that interfaces be installed on dedicated interface nodes instead of directly on the PIServer node. A PI interface node is any node other than the PI Server node where the PIApplication Programming Interface (PI API) is installed (see the PI APImanual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PIServer is to archive data and to service clients that request data.