Wonderware InTouch
Interface to the PI System
Version 1.5.0.0
Rev A
iii
UniInt End-User Interface to the PI System
How to Contact Us
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA 94577 USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. 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
Sales Outlets and Distributors
· Brazil
· Middle East/North Africa
· Republic of South Africa
· Russia/Central Asia / · South America/Caribbean
· Southeast Asia
· South Korea
· Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
© 1997-2007 OSIsoft, Inc. PI_WInTouch.doc
iii
UniInt End-User Interface to the PI System
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 5
Principles of Operation 7
Installation Checklist 9
Interface Installation 11
Naming Conventions and Requirements 11
Interface Directories 12
The PIHOME Directory Tree 12
Interface Installation Directory 12
Interface Installation Procedure 12
Installing the Interface as a Windows Service 13
Installing the Interface Service with PI-Interface Configuration Utility 13
Installing the Interface Service Manually 16
Digital States 17
PointSource 19
PI Point Configuration 21
Point Attributes 21
Tag 21
PointSource 21
PointType 21
Location1 21
Location2 22
Location3 22
Location4 22
Location5 22
InstrumentTag 23
ExDesc 23
Scan 25
Shutdown 25
Output Points 25
Trigger Method 1 (Recommended) 26
Trigger Method 2 26
Convers 26
Performance Point Configuration 27
Configuring Performance Points with PI ICU 27
Configuring Performance Points Manually 28
I/O Rate Tag Configuration 29
Monitoring I/O Rates on the Interface Node 29
Configuring I/O Rate Tags with PI ICU (Windows) 29
Configuring I/O Rate Tags Manually 31
Configuring the PI Point on the PI Server 31
Configuration on the Interface Node 31
Startup Command File 33
Configuring the Interface with PI ICU 33
Wintouch Interface Page 36
Command-line Parameters 38
Sample PI_InTouch.bat File 43
System Variable Path 45
Interface Node Clock 47
Security 49
Starting / Stopping the Interface on Windows 51
Starting Interface as a Service 51
Stopping Interface Running as a Service 51
Buffering 53
Configuring Buffering with PI ICU (Windows) 53
Configuring Buffering Manually 57
Sample piclient.ini File 58
Appendix A: Error and Informational Messages 59
Message Logs 59
Messages 59
System Errors and PI Errors 60
Revision History 61
25
Wonderware InTouch Interface to the PI System 25
Introduction
The PI Wonderware InTouch interface is designed to integrate the PI System from OSIsoft with the InTouch system from Wonderware. It consists of the OSI Universal Interface core linked with a module, which customizes it for the InTouch environment. The interface is compatible with InTouch versions 6.0b – 9.x.
This interface transfers data between the InTouch database and the PI archive via the InTouch Database External Access (IDEA) Software Development Kit (SDK). The interface runs on Microsoft WINDOWS. Input tags (for sending data from InTouch to PI) as well as output tags (from PI to InTouch) are supported.
Reference Manuals
OSIsoft
· UniInt Interface User Manual
· PI Server Manuals
· PI API Installation manual
Vendor
· The Extensibility Toolkit for InTouch User’s Guide
Supported Features
Feature / Support /Part Number / PI-IN-WW-INTCH-NTI
* Platforms / Windows NTI NT4/W2K/XP/2003
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Digital, Int16, Int32, Float16, Float32, Float64 and String
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based / Event Tags
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
*Uses PI SDK / No
PINet String Support / N/A
* Source of Timestamps / PI Server
*History Recovery / No
* UniInt-based
Disconnected Startup
SetDeviceStatus / Yes
Yes
Yes
* Failover / Yes – InTouch I/O Server failover supported
* Vendor Software Required on PI Interface Node/PINet Node / Yes
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
* Device Point Types / Discrete, Integer, Real, and String
* See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater. Windows XP requires service pack 2 (SP2).
Please contact OSIsoft Technical Support for more information.
Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls.
Source of Timestamps
When the value of a tag is read from InTouch, the PI server time is used as the event’s timestamp. This timestamp may be adjusted using the /to=n parameter. This parameter specifies the number of seconds (as a positive or negative number) to adjust the timestamp by. This offset, when specified, applies to all tags and all scans.
There is also a mechanism for adjusting the timestamp of individual tags. This is typically used when there is a significant delay between the value of a tag actually being scanned in the field and the value being received by InTouch. For example, a tag may be scanned in the field every 15 minutes but takes several minutes to reach InTouch. In this case you would typically want the timestamp in PI to represent the time the tag was scanned in the field rather than when it was written to InTouch. This can be achieved by using a combination of scan class and Location2 settings. See the section on Location2 on page 22 for more information.
The /tm parameter tells the interface to output timestamp messages to the error log file. This is useful for debugging any timestamp manipulation that is configured.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt Interface User Manual is a supplement to this manual.
SetDeviceStatus
The Wonderware InTouch Interface is built with UniInt 4.3.0.31. New functionality has been added to support health tags. The Health tag with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the source device. The following events can be written into this tag:
a) “1 | Starting” - the interface is starting.
b) “Good” - the interface is properly communicating and reading data from the Wonderware InTouch system.
c) The following event represents a failure to communicate with the Wonderware InTouch system (the system is not running):
"3 | 1 device(s) in error | InTouch is not running"
This event will be written into the Health tag only if the interface is running interactively. If the interface is running as a Windows service, this event will never be written into the tag. The interface service will stop when Wonderware InTouch View service stops.
Please refer to the UniInt Interface User Manual for more information on how to configure health points.
d) “4 | Intf Shutdown” - the interface is stopped.
Failover
In a typical Wonderware InTouch – PI InTouch application, there are three components that can fail:
- I/O Server (The means by which real-world data is brought into InTouch).
- InTouch (The actual MMI product).
- PI InTouch (The interface used to exchange data between InTouch and PI).
The Failover mechanism built into the PI InTouch Interface only applies to failure of the I/O Server.
The failover mechanism in this interface is very simple and works with any number of InTouch hosts. The interface simply examines a specified InTouch point, which holds the name of the active/online I/O Server, and if it is not the current host (also specified), then it does not scan that InTouch node for updated point values.
To operate using failover simply install and run the interface on the two or more InTouch hosts, making sure to specify the /fp and /fs parameters in the startup command file. The /fp parameter (InTouch failover point name) will be identical on each of the hosts, but the /fs parameter (local server name for failover) will differ. See the “Command-Line Parameters” section on page 38 for a description of these parameters.
Vendor Software Required
The IDEA SDK (InTouch Database External Access Software Development Kit) must be purchased with InTouch version 6.0b. Subsequent releases have the necessary components embedded.
Device Point Types
InTouch uses the following point types: Discrete, Integer, Real, and String. The interface supports the following point types: Digital, Int16, Int32, Float16, Float32, Float64, and String. The interface supports all combinations and makes every effort to convert between types – even strings.
Diagram of Hardware Connection
25
Wonderware InTouch Interface to the PI System 25
Principles of Operation
The PI Wonderware InTouch interface is a console-based, UniInt-based, interface.
The interface starts by first searching the PI tag database for all tags whose PointSource matches the interface’s PointSource as designated at startup. The interface then attempts to make a connection to each of the associated tags within InTouch.
When the interface process has completed these initial tasks, it enters a permanent loop in which it checks for the expiration of the update period for each scan class, and the expiration of the tag attributes update period. This loop is repeated until the interface is stopped.
The PI Wonderware InTouch interface supports scan-based input tags, event-based input tags, and output tags. The interface groups all the event-based tags having a common event tag into a dynamic list for servicing together, so that all event-based tags in the list are updated when their event tag has an exception.
The manner in which the interface manages the connection to InTouch is determined by the /ws and the /ht parameters that are specified in the startup command file. If the /ws parameter is not specified, the interface will exit when a connection attempt fails – this includes the initial connection at startup. Otherwise, the value of the /ws parameter is the number of seconds to delay between reconnection attempts. This allows the interface to start before InTouch does, in which case a connection will be attempted periodically until successful. Also, if InTouch exits, the interface will continue to operate, attempting a connection periodically until successful.
The /ht parameter tells the interface to hold a tag connection open between scans. If this is not specified, a tag connection is made, the tag is read, and then the tag is disconnected, for each scan. This is obviously an inefficient way to process tags. For the sake of efficiency this parameter should be specified except when the system resources are low and the interface becomes unstable.
25
Wonderware InTouch Interface to the PI System 25
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI Wonderware InTouch interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.
1. Install the PI Interface Configuration Utility (which installs PI SDK and PI API)
2. Verify that PI API has been installed.
3. Install the PI Wonderware InTouch interface.
4. Choose a point source.
5. Configure PI points.
Location1 is the interface number.
Location2 is the time offset in seconds.
Location3 specifies whether the point is an input point (0) or output point (1).
Location4 is the scan class.
Location5 is not used.
ExDesc specifies whether tags are event-based.
InstrumentTag specifies the InTouch point name associated with the PI tag.
6. Configure the interface using the PI ICU utility or edit startup command file manually. It is recommended to use PI ICU whenever possible.
/id=# defines the connection.
7. Configure performance points.
8. Configure I/O Rate tag.
9. Add the InTouch directory to the System Variable Path.
10. Set interface node clock.
11. Set up security.
12. Start the interface without buffering.
13. Verify data.
14. Stop interface, start buffering, start interface.
25
Wonderware InTouch Interface to the PI System 25
Interface Installation
OSIsoft recommends that interfaces be installed on PI 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) has been installed (see the PI APIInstallation Instructions manual). 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.