Foxboro I/A 51 and 70 Series Interface to the PI System

Version 2.3.2.45
Rev B

1

UniInt End-User Interface to the PI System

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
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


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.
RESTRICTEDRIGHTS 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
Unpublished -- rights reserved under the copyright laws of the United States.
© 2002-2006 OSIsoft, Inc. PI_FXBAIS.doc

1

UniInt End-User Interface to the PI System

Table of Contents

Introduction

FoxAPI Compatability

FoxAPI Version 5 Incompatability

Reference Manuals

Supported Features

Diagram of Hardware Connections

Principles of Operation

Installation Checklist

Interface Installation on Windows

Naming Conventions and Requirements

PI Interface Configuration Utility

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as a Windows Service

Installing the Interface Service with PI Interface Configuration Utility

Installing the Interface Service Manually

Interface Installation on Solaris

PI API Verification

Interface Directories

The PIHOME Directory

Interface Installation Directory

Interface Installation Procedure

Naming Conventions and Requirements

FoxAPI Test Program

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

UserInt1

Scan

Shutdown

Point Configuration Examples

Profile Points

Performance Point Configuration

Configuring Performance Points with PI ICU

Configuring Performance Points Manually

I/O Rate Point Configuration

Monitoring I/O Rate Points

Configuring I/O Rate Points with PI ICU

Configuring I/O Rate Points Manually

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Program Executable Name

Notes for Windows

Configuring the Interface with PI ICU

Notes for Solaris

Command-line Parameters

Sample fxbais.bat file

Sample fxbais.sh file

Configuration File

Interface Node Clock

Windows

Solaris

Security

Windows and UNIX

Starting / Stopping the Interface on Windows

Starting Interface as a Service

Stopping Interface Running as a Service

Starting / Stopping the Interface on Solaris

Interactive Execution

Command-line Syntax for Background Processes

Terminating Background Processes

Interface Shutdown Script

Foxboro VT100 Windows and Anomalous Background Termination

Startup Summary

Buffering

Configuring Buffering with PI ICU (Windows-Intel)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error / Informational Messages and Troubleshooting

Message Logs

Messages

System Errors and PI Errors

List Event Counters and Location5

Extra Debugging Messages

Common Problems

Operational Hints

Solaris/Unix

Fixes to FoxAPI

Reading an Entire MCIN/MCOUT Block

Reading I/A Series Messages

Settings in foxapi.cfg

Time Difference Reported by the Interface

Appendix B: Failover Support

Parameters for Operation

Design Details

Operational Scenarios

Failover Installation Checklist

Miscellaneous Information on Failover

Appendix C: Migration from v1.16.x

Appendix D: FoxAPI Configuration

Appendix E: FoxAPI Status Definition

Status Definition for I/A Series Version 4.1 and Earlier

Status Definition for I/A Series Version 4.2 and Later

Storing Status Values in PI

Revision History

1

Foxboro I/A 51 and 70 Series Interface to the PI System1

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.

In order to run the PI Foxboro Interface, a computer must have the following software installed:

  • PI API version 1.3.x or higher
  • On Solaris, latest version of the PI API is recommended.
  • 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 PI Foxboro 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.3.1
  • Solaris 2.5 I/A Version - 4.3 to 6.5.2
  • Solaris 8 I/A Version - 7.0 to 7.1.1
  • Windows I/A version - 6.0 to 8.0B

Foxboro recommends the use of the most current release of the FoxAPI, which at the time of this manual is version 4.3.1. 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

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
  • FoxboroIA 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 (Windows version only)
PI Point Types / 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
Supports Questionable Bit / Yes
Supports Multi-character Point Source / No
Maximum Point Count / Unlimited
*Uses PI SDK / No
PINet to PI 3 String Support / Not Applicable
* Source of Timestamps / PI Server
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.

Platforms

The Interface is designed to run on the above mentioned UNIX and Microsoft Windows operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported.

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.

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

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.

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 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 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:

Control Station Generated:

Process Alarms

Sequence of Events

Sequence Block

System Monitor

Operator Action Journal

are not supported.

Diagram of Hardware Connections

The following diagrams indicate the connectivity between the various hardware and software components. Note that the Interface must run on a machine that is separate from the PI Server. That is, the user must install the Interface on a machine known in OSIsoft’s terminology as a “PI Interface node”.

Please note that PI FoxboroNet connects to a single netFoxAPI server only. If the user wishes to connect to multiple netFoxAPI servers, run multiple copies of PI FoxboroNet. For example:

1

Foxboro I/A 51 and 70 Series Interface to the PI System1

Principles of Operation

The following description of the PI Foxboro Interface assumes that the user is familiar with running OSIsoft interface programs in general. First-time users of the PI System may wish to skim this section and return at a later time.

Before PI Foxboro can start up, the FoxAPI processes must already be running. On Solaris, these processes are launched by Foxboro’s aisstart command. On Windows, the service control manager starts up Fox Apps, Fox Monitor, Fox NTApp Service, and Fox Shm Service.

Upon startup, PI Foxboro reads the PI point database and determines which PI points it services by looking at the Point Source and Location1 point attribute fields. The InstrumentTag field should contain the name of the Foxboro I/A object. Otherwise, the Extended Descriptor must have the name of the Foxboro I/A object.

PI Foxboro makes calls to FoxAPI functions in order to retrieve data from the I/A system. The Location2 value determines whether the Interface utilizes unbuffered or buffered FoxAPI access routines. Values written from PI to the I/A are also via either buffered or unbuffered FoxAPI function calls. Buffered access involves reading from or writing to I/A object values in the I/A shared memory.

Values that are retrieved from the I/A shared memory have already gone through Foxboro’s exception reporting mechanism. In addition, unless the user specifies the -sn parameter during Interface startup, the Interface program itself also performs exception reporting on these values before sending them to PI.

For a value received from an I/A object that has its “bad” bit set, the user may choose to send to PI:

  • the value, or
  • Bad Input, or
  • the value with the PI questionable bit set (PI 3 only)

Bit 8 of the I/A object status indicates whether an object is “bad”.

Outputs from the PI System to the Foxboro I/A are performed via OSIsoft’s standard event-based mechanism. That is, when the Interface determines that a PI point has received a new value, it sends this value to the corresponding I/A object.

1

Foxboro I/A 51 and 70 Series Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps get the PI Foxboro Interface running. If the user is unfamiliar with PI interfaces, he/she should return to this section after reading the rest of the manual in detail.

Note: For Solaris systems, the PI API and the interface should be installed and run by the “root” user. To access the FoxAPI, the interface must have “root” privileges.

Similarly, for Windows systems, the interface service must be started with an account that has local administrator rights, and so we recommend the standard Foxboro user “fox”.

Follow the steps in the order listed below.

  1. If the Interface will run on a 70-Series AW and the PI Server is version 3.3.361.43 or higher, install the PI Interface Configuration Utility (PI ICU) which installs the PI SDK and PI API. In all other cases, install the PI API software.
  2. Confirm connectivity between the PI Interface node and the PI Server by running the apisnap program.
  3. Confirm the correct operation of the FoxAPI. Run Foxboro’s foxtst program. When using netFoxAPI, make sure that the netFoxAPI client machine (the machine running the Interface) has permission to create, name, and read objects on the netFoxAPI server machine.
  4. Install the PI Foxboro Interface program files. On Solaris, “untar” the compressed tar interface distribution file. On Windows, run the installation program.
  5. When using PI digital tags, define digital states. Digital state sets must also be defined.
  6. Choose a point source for use by the Interface.
  7. Configure PI points to be used by the Interface.

The InstrumentTag specifies the Foxboro I/A object.