Foxboro I/A 51 and 70 Series Interface to the PI System
Version 2.2.7.35
i
UniInt End-User Interface to the PI System
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web / http://www.osisoft.com
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrabe 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
Unpublished - rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph I(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_fxbais.doc
Ó 1997-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
i
UniInt End-User Interface to the PI System
Table of Contents
Introduction 1
FoxAPI Compatability 2
FoxAPI Version 5 Incompatability 3
Reference Manuals 3
Supported Features 4
Diagram of Hardware Connections 7
Principles of Operation 9
Installation Checklist 11
Interface Installation on Windows NT 13
Naming Conventions and Requirements 13
PI-Interface Configuration Utility 13
Interface Directories 14
The PIHOME Directory Tree 14
Interface Installation Directory 14
Interface Installation Procedure 14
Installing the Interface as a Windows NT Service 14
Installing the Interface Service with PI-Interface Configuration Utility 15
Installing the Interface Service Manually 17
Interface Installation on Solaris 19
PI-API Verification 19
Interface Directories 20
The PIHOME Directory 20
Interface Installation Directory 20
Interface Installation Procedure 20
Naming Conventions and Requirements 22
FoxAPI Test Program 25
Digital States 29
PointSource 31
PI Point Configuration 33
Point Attributes 33
Tag 33
PointSource 33
PointType 33
Location1 34
Location2 34
Location3 35
Location4 36
Location5 36
InstrumentTag 36
ExDesc 37
UserInt1 38
Scan 38
Shutdown 39
Exception Specifications 39
Other Attributes 40
Point Configuration Examples 40
Profile Points 41
Performance Point Configuration 43
Configuring Performance Points with PI-ICU 43
Configuring Performance Points Manually 44
I/O Rate Point Configuration 45
Monitoring I/O Rate Points 45
Configuring I/O Rate Points with PI-ICU 45
Configuring I/O Rate Points Manually 46
Configuring the PI Point on the PI Server 47
Configuration on the Interface Node 47
Startup Command File 49
Program Executable Name 49
Notes for NT 49
Configuring the Interface with PI-ICU 49
Notes for Solaris 55
Command-line Parameters 55
Sample fxbais.bat file 58
Sample fxbais.sh file 59
Configuration File 61
Interface Node Clock 63
Windows 63
Solaris 63
Security 65
Starting / Stopping the Interface on Windows 67
Using the PI-ICU 67
Not Using the PI-ICU 67
Starting / Stopping the Interface on Solaris 69
Interactive Execution 69
Command-Line Syntax for Background Processes 69
Terminating Background Processes 70
Interface Shutdown Script 70
Foxboro VT100 Windows and Anomalous Background Termination 70
Startup Summary 71
Buffering 73
Configuring Buffering with PI-ICU (NT-Intel) 73
Configuring Buffering Manually 76
Example piclient.ini File 78
Appendix A: Error / Informational Messages, and Troubleshooting 79
Message Logs 79
Messages 79
System Errors and PI Errors 80
List Event Counters and Location5 81
Extra Debugging Messages 81
Common Problems 82
Operational Hints 87
Solaris/Unix 87
Fixes to FoxAPI 87
Status of an I/A Series Object 87
Reading an Entire MCIN/MCOUT Block 89
Reading I/A Series Messages 89
Settings in foxapi.cfg 89
Time Difference Reported by the Interface 89
Appendix B: Failover Support 91
Parameters for Operation 92
Design Details 94
Operational Scenarios 97
Failover Installation Checklist 99
Miscellaneous Information on Failover 100
Appendix C: Migration from v1.16.x 103
Appendix D: FoxAPI Configuration 105
Revision History 107
v
Foxboro I/A 51 and 70 Series Interface to the PI System v
Introduction
The PI-Foxboro data collection interface program provides for the bi-directional transfer of data between OSIsoft’s PI Server and Foxboro’s I/A Series system. The PI Server runs on Windows NT/2000/XP, Unix, or OpenVMS machines. Foxboro’s I/A Series system runs on either Solaris (51 Series) or Windows NT/XP (70 Series) computers.
In the rest of this document, versions of the PI Server running on Windows NT/2000/XP or Unix are also referred to as PI 3. Versions running on OpenVMS are referred to as PI 2.
In order to run the PI-Foxboro Interface, a computer must have the following software installed:
· PI-API version 1.3.x or higher
o On Solaris, latest version of the PI-API is recommended.
o On Windows, the latest version of the PI-API is recommended.
· local FoxAPI version 4.x.x if the Interface is to run on an I/A Series AW/AP, or
· netFoxAPI version 4.x.x if the Interface is to run on a generic Solaris machine
The first of these products comes from OSIsoft. Foxboro supplies the others. Foxboro recommends the use of FoxAPI v4.2.8.
The choice of the FoxAPI version (i.e., whether local or networked) depends on the type of machine on which the PI-Foxboro Interface runs. If this machine is:
· an I/A Series AW/AP, local FoxAPI is required. Local FoxAPI ships on all I/A Series AW/APs sold to date. Note that Foxboro do not install the FoxAPI on WP machines, and so can not be used to run the interface.
· a generic Solaris machine, netFoxAPI must be purchased and installed on this generic Solaris machine. In addition, netFoxAPI software must also be licensed at the netFoxAPI server machine. The standard FoxAPI manuals describe this operation.
The following table summarizes these scenarios:
Platform / Description / Software on PI-Foxboro machine // PI-Foxboro / Local FoxAPI / netFoxAPI /
50-Series AW/AP / PI-Foxboro loaded on an I/A Series AW/AP uses local FoxAPI to acquire data. / Yes / Yes / No
70-Series AW / PI-Foxboro loaded on an I/A Series AW uses local FoxAPI to acquire data. / Yes / Yes / No
Generic Solaris / PI-Foxboro loaded on a generic Solaris machine uses netFoxAPI to acquire data from an I/A Series AW/AP over a customer supplied TCP/IP based network. / Yes / No
But, local FoxAPI is required on the AW/AP feeding the data to the PIFoxboro machine / Yes
Generic Windows NT / This configuration is not supported. / N/A / N/A / N/A
The remainder of this document uses the term “FoxAPI” to refer to FoxAPI and netFoxAPI in general. When an issue or feature specific to one or the other arises, it will be so noted. For example, the version of the Interface that specifically uses the netFoxAPI is called “PI-FoxboroNet”.
FoxAPI Compatability
Customers have reported compatibility between the Interface and the following versions of FoxAPI software and I/A software:
· FoxAPI version - 4.2.0 to 4.2.8 (and 4.3 Beta)
· Solaris 2.5 I/A Version - 4.3 to 6.5.1
· Solaris 8 I/A Version - 7.0 to 7.1
· Windows I/A version - 6.0 to 7.1
Foxboro recommends the use of the most current release of the FoxAPI, which at the time of this manual is version 4.2.8. To confirm compatibility with newer versions, contact OSIsoft technical support.
If a version of the interface prior to 2.2.6.x is used with the FoxAPI 4.2.6 or later, the PI-Foxboro interface requires three new features of the FoxAPI to be disabled (see Appendix D). Version of the interface 2.2.6.x or later do not required these features to be disabled.
FoxAPI Version 5 Incompatability
Please note that on Solaris, FoxAPI v5.x is NOT compatible with the PI-Foxboro. Interface.
FoxAPI v5.0 is no longer supported by Foxboro. Its primary purpose was to support Foxboro’s PIMS suite, which they no longer sell.
Windows NT
Customers have reported compatibility between the PI-Foxboro Interface and FoxAPI version 5.0.0 running on Windows NT (70-Series AW).
Solaris
The following information comes from Foxboro:
Simply stated, certain programs do not work with V5.x of FoxAPI installed on the same box. V5.x of FoxAPI is shipped with the PIMS 2.0 package. V4.x is the default version of FoxAPI.
FoxAPI V5.x has been withdrawn and replaced by AIM*API for applications that require the V5.x functionality and by FoxAPI V4.2.4 or later for programs that do not require the functionality of FoxAPI Version 5.x.
In general, FoxAPI Version 5.x is found only on those systems that have applied the PIMS 2.0 package. PIMS 2.0 changed libfoxapi.so such that all programs linked against the previous FoxAPI release will break.
The PIMS 2.0 package has been superseded by AIM* V3.x. If possible, the system should be upgraded to use AIM* V3.x instead of FoxHistory and PIMS 2.0 and the latest version of FoxAPI V4.x should be installed.
If the upgrade is not possible, there are several possible fixes/workarounds, each with its own problems. Please contact Foxboro for more information.
Reference Manuals
OSIsoft
· UniInt End User document
· PI Server manuals
· PI-API Installation Instructions
· PI-API manual
· PI-ICU User Manual
Foxboro
· Foxboro AIS System Manager’s Guide For Unix Computers
· Foxboro AIS Programmer’s Guides
· Foxboro INI documentation
· Foxboro IA Series documentation
· I/A Series FoxAPI User’s Guide (B0193UD)
· I/A Series FoxAPI Installation Guide (B0193UC)
Supported Features
Feature / Support /Part Numbers / PI-IN-FX-IA-SOL2
PI-IN-FX-IA-NTI /
Platforms / Solaris 2.5 / Solaris 8
Windows NT / 2000 / XP (Intel) /
APS Connector / No /
Point Builder Utility / No /
ICU Control / Yes /
PI Point Types / PI 2: real / integer / digital
PI 3: float16 / float 32 / float 64 / int16 / int32 / digital / string /
* Sub-second Timestamps / Yes /
* Sub-second Scan Classes / Yes /
Automatically Incorporates PIPoint Attribute Changes / Yes /
Exception Reporting / Yes; performed by the Interface /
Outputs from PI / Yes /
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based / event tags /
Maximum Point Count / Unlimited /
Uses PI-SDK / No /
PINet to PI 3 String Support / Not applicable /
* Source of Timestamps / PI Server machine /
History Recovery / No /
* Failover / Yes /
* UniInt-based / Yes /
* Vendor software required on PI Interface node / Yes /
Vendor software required on Foreign Device / No /
Vendor Hardware Required / No /
Additional PI software included with the Interface / No /
* Device Point Types / See below /
*See paragraphs below for further explanation.
Source of Timestamps
Because the Foxboro I/A series workstation always has its time zone set to GMT and its clock set to wall clock time, the time as indicated on this machine is technically incorrect. Therefore, PI-Foxboro uses the PI-API to determine the PI Server’s local time. The Interface then applies an additional time offset to obtain the correct Coordinated Universal Time (UTC). This offset is recalculated every 10 minutes.
Data sent by the Interface to the PI Server normally contain the PI Server’s timestamp as represented in UTC. Profile data points have a timestamp that corresponds to the value of the I/A object associated with the Profile Trigger tag. See the section on Profile Points for more information.
Sub-second Timestamps and Scan Classes
The interface supports sub-second scan classes and timestamps. However, there are limitations within the I/A system which mean that the accuracy of the timestamps may not be reliable.
Firstly, the fastest the I/A stations check for updates for the FoxAPI is 0.5 second (this is independent of the station BPC). Therefore, defining a scan class for the interface faster than 0.5 second will only result in duplicate values being read.
Secondly, the FoxAPI does not return timestamps with the values. Therefore the interface must apply a timestamp when it reads the value and there will be a delay between the value scanned in the I/A control station and when the timestamp is applied.
Also note that high scan frequencies impose a high CPU load on the system and should be avoided if not absolutely required.
Failover
The user may simultaneously run two copies of PI-Foxboro in a failover configuration. In this manner, if one copy of the Interface fails, the other automatically assumes responsibility for data collection. See the Failover section of this manual for details.
PI-FoxboroNet does not run in a failover configuration.
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, such as the PI-Foxboro Interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our 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 UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt End User Document is a supplement to this manual.
Vendor Software Required
The PI-Foxboro Interface program requires software from Foxboro, Inc. This software is either:
· FoxAPI, version 4.x.x, or
· netFoxAPI, version 4.x.x.
However, on Windows NT, customers have reported success with using FoxAPI version 5.0.0.
Device Point Types
The PI-Foxboro Interface supports the following Foxboro I/A point types:
· char (I/A type 1)
· short integer (I/A type 2)
· float (I/A type 3)
· string (I/A type 4)
· Boolean (I/A type 5)
· long integer (I/A type 6)
· short integer (I/A type 8)
· packed Boolean (I/A type 9)
· long packed Boolean (I/A type 10)
The Interface does not support the reading of I/A Series Messages. For example, messages such as: