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

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

Version 2.3.8.66
Revision B

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
/ OSIsoft Australia
Perth, Australia
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, 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
OSIsoft do Brasil Sistemas Ltda.
Sao Paulo, Brazil
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast Asia
South KoreaTaiwan

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, Inc.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. All other trademarks or trade names used herein are the property of their respective owners.

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

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

Table of Contents

Terminology

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Buffered Access

Unbuffered Access

Object Status

Outputs

Installation Checklist

Data Collection Steps

Interface Diagnostics

Advanced Interface Features

Interface Installation on Windows

Naming Conventions and Requirements

Interface Directories

PIHOME Directory Tree

Interface Installation Directory

FoxAPI Installation

Interface Installation Procedure

Installing Interface as a Windows Service

Installing Interface Service with PI Interface Configuration Utility

Installing Interface Service Manually

Interface Installation on UNIX

Naming Conventions and Requirements

Interface Directories

PIHOME Directory

Interface Installation Directory

FoxAPI Installation

PI API Installation Procedure

Interface Installation Procedure

Installing Multiple Instances of the Interface

Multiple Instances in a Single Directory

Multiple Instances in a Separate Directories

FoxAPI Test Program

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

UserInt1

Scan

Shutdown

Output Points

Trigger Method 1 (Recommended)

Trigger Method 2

Point Configuration Examples

Profile Points

Startup Command File

Configuring the Interface with PI ICU

Fxbais Interface page

Command-line Parameters

Sample fxbais.bat file

Sample fxbais.sh file

fxbais.ini Configuration File

Interface Node Clock

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 UNIX

Interface Startup Script

Interface Stop Script

Automatic startup and shutdown

Automatic startup on a reboot

Terminating Background Processes

Anomalous Background Job Termination

Buffering

Which Buffering Application to Use

How Buffering Works

Buffering and PI Server Security

Enabling Buffering on an Interface Node with the ICU

Choose Buffer Type

Buffering Settings

Buffered Servers

Installing Buffering as a Service

Configuring PI API Buffer Server (BufServ) Manually

Buffering Settings

BufServ and n-way buffering

Kernel Resource Configuration on Solaris

Interface Diagnostics Configuration

Scan Class Performance Points

Configuring Scan Class Performance Points on UNIX

Performance Counters Points on Windows

Interface Health Monitoring Points

Configuring Interface Health Points with the ICU

Configuring Interface Health Points Manually

Interface Health Point Keywords

I/O Rate Point

Configuring I/O Rate Tags On UNIX

Configuring PI Point on the PI Server

Configuration on the Interface Node

Interface Status Point

Appendix A: Error and Informational Messages

Message Logs

System Errors and PI Errors

Extra Debugging Messages

List Event Counters and Location5

Common Problems

Operational Hints

Solaris/Unix

Updates and HotFixes for the FoxAPI

Reading an Entire MCIN/MCOUT Block

Reading I/A Series Messages

FoxAPI Configuration Settings (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: Notes on Upgrading from Previous Versions

Required -host= argument

ExDesc keywords no longer supported

PIHOME and LD_LIBRARY variables defined in /.cshrc

Install Procedure

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

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

Terminology

To understand this interface manual, you should be familiar with the terminology used in this document.

Buffering

Buffering refers to an Interface Node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.

N-Way Buffering

If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)

ICU

ICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure and run PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.

You can configure and run an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.

ICU Control

An ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface Node

An Interface Node is a computer on which

the PI API and/or PI SDK are installed, and
PI Server programs are not installed.

PI API

The PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.

PI Collective

A PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.

PIHOME

PIHOME refers to the directory that is the common location for PI client applications. A typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME directory. For example, ICU files in [PIHOME]\ICU.

PI SDK

The PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.

PI Server Node

A PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.

PI SMT

PI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.

Pipc.log

The pipc.log file is the file to which OSIsoft applications write informational and error messages. While a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.

Point

The PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.

Service

A Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

The ICU allows you to configure a PI interface to run as a Service.

Tag (Input Tag and Output Tag)

The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.

Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.

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

Diagram of Hardware Connection

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. Foxboro’s I/A Series systems run on either Solaris (51 Series) or Windows NT/XP (70 Series) computers.

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

OSIsoft PI API version 1.3.x or higher (the current released version of the PIAPI is recommended).
Foxboro local FoxAPI version 4.x.x if the Interface is to run on an I/A Series AW/AP, or
Foxboro netFoxAPI version 4.x.x if the Interface is to run on a generic Solaris machine

Foxboro recommends the use of the current release of the FoxAPI.

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. Note that Foxboro does not install the FoxAPI on WP machines, and so they cannot be used to run the interface.
A generic Solaris machine which is not a part of the Foxboro I/A system, then 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.

Reference Manuals

OSIsoft

PI Server manuals
PI API Installation Manual
UniInt Interface User Manual

Foxboro

Foxboro I/A Series documentation
I/A Series FoxAPI Installation Guide (B0193UC)
I/A Series FoxAPI User’s Guide (B0193UD)

Supported Features

Feature / Support
Part Number / PI-IN-FX-IA-SOL2
PI-IN-FX-IA-NTI
* Platforms / Solaris 2.5.1 / 8 / 10
Windows (XP, 2003)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes (Windows only)
PI Point Types / float16 / float 32 / float 64 / int16 / int32 / digital / string
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes (but of limited use. See note below)
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 / Yes
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
* Uses PI SDK / No
PINet String Support / No
* Source of Timestamps / Synchronized to the PI server
* History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / Interface specific
* 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 / See below
Serial-Based Interface / No

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run on the above mentioned UNIX and Microsoft Windows operating systems and their associated service packs.

Please contact OSIsoft Technical Support 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.

Uses PI SDK

On the Windows platform, the PI SDK and the PI API are bundled together and must be installed on each Windows PI Interface node. This Interface does not specifically make PI SDK calls.

Source of Timestamps

The time on the PI server is treated as the master clock when time-stamping values received by the interface. The timestamp is calculated by using the current time on the interface node and applying an offset calculated from the different in the interface node time and the time on the PI server.

Because the Foxboro I/A series workstation may have its time zone set to GMT and its clock set to wall clock time, the time as indicated internally 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.

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.

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.

Disconnected Start-Up

The PIfxbais interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.

SetDeviceStatus

Functionality has been added to UniInt 4.3.0.15 and later to support health tags. The PI Foxboro I/A interface is built against a version of UniInt that supports the health tags.

The Health tag with a string point type and the attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the interface. The possible values for this string point are:

“1 | Starting” – The Interface remains in this state until it has loaded the PI points and either starts scanning, or if running in failover, it initializes the failover state.
“2 | Connected/No Data” - the interface is part of a failover pair and currently initializing or changing failover state.
“Good” – The interface is able to collect data. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems. When using failover, a “Good” status can indicate that the interface is active or on standby. The failover status PI points will show the status of the individual instances of the interface.
“4 | Intf Shutdown” – The Interface has shut down.

The Interface updates this point whenever the interface is started or stopped.

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.

The netFoxAPI version of the interface does not run in a failover configuration.

Note The failover mechanism used by the interface is specific to the Foxboro interface. The interface does not support the UniInt-based failover. -UFO_ID= is not supported.

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.

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 Connection

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”.