PI Bailey Sem API Interface Manual
Interface to the PI System
Windows Version 1.4.2.0
v
Bailey semAPI Interface to the PI System v
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-2008 OSIsoft, Inc. PI_BaSemAPI.doc
v
Bailey semAPI Interface to the PI System v
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 2
Diagram of Hardware Connection 5
Principles of Operation 7
Installation Checklist 9
Windows 9
Interface Installation on Windows 11
Naming Conventions and Requirements 11
Interface Directories 11
The PIHOME Directory Tree 11
Interface Installation Directory 12
Interface Installation Procedure 12
Installing the Interface as a Windows Service 12
Installing Interface Service with PI ICU 12
Installing the Interface Service Manually 14
Testing Connection to ICI 17
Digital States 19
PointSource 21
PI Point Configuration 23
Point Attributes 23
Tag 23
PointSource 23
PointType 23
Location1 23
Location2 24
Location3 24
Location4 24
Location5 24
InstrumentTag 25
ExDesc 25
Scan 26
SourceTag 26
Shutdown 27
Output Points 27
Trigger Method 1 (Recommended) 27
Trigger Method 2 28
Bailey Point Types 29
Supported Input Point Types (Bailey Data to PI) 29
Output Point Types (PI Data to Bailey) 30
Detailed Description of Bailey Point Types 31
Tag Configuration from Bailey Database 40
Performance Point Configuration 43
I/O Rate Tag Configuration 45
Monitoring I/O Rates on the Interface Node 45
Configuring I/O Rate Tags with PI ICU (Windows) 45
Configuring I/O Rate Tags Manually 47
Configuring the PI Point on the PI Server 47
Configuring on the Interface Node 47
Startup Command File 49
Configuring the Interface with PI ICU 49
Basemapi Interface Page 51
General Tab 52
Failover / Debug Tab 54
Command-line Parameters 56
Sample blysem.bat File 61
Interface Node Clock 63
Windows 63
Security 65
Windows 65
Starting / Stopping the Interface on Windows 67
Starting Interface as a Service 67
Stopping Interface Running as a Service 67
Buffering 69
Configuring Buffering with PI ICU (Windows) 69
Configuring Buffering Manually 72
Example piclient.ini File 74
Restrictions and Other Information 75
Exclusive Control of ICI Device 75
Interface and semAPI Version Compatibility 75
OSM01 Not Recommended 75
semAPI 1.2 Disconnection Problems 75
Timeout in the Middle of the Connect Point Command 75
Adaptec 2940 U SCSI, 50-pin Card with the ICI03 76
Install the semAPI Device Driver as a Service 76
Invalid Security Device Present 76
Appendix A: Error and Informational Messages 79
Message Logs 79
Messages 79
System Errors and PI Errors 79
Revision History 81
v
Bailey semAPI Interface to the PI System v
Introduction
The PI Bailey semAPI interface provides bi-directional data transfer between a PI system and a Bailey Infi90 instrument system. The interface runs on Windows-Intel computers.
This interface was developed to take advantage of Bailey’s semAPI library. The semAPI software handles all of the Bailey communications protocol and thereby makes it possible for the PI interface to communicate to Bailey ICI modules via a variety of transport methods (serial, Ethernet, and SCSI).
Note: Currently, interface version 1.3 and greater is compatible with semAPI version 2.0 and greater. Interface version 1.2 is compatible with semAPI version 1.2. For version compatibility and other semAPI issues, see the restriction section at the end of the manual.
The new features introduced in version 1.4.2.0 of the interface consist of Disconnected Startup, Multi-Character Point Source, UniInt Health Tags including SetDeviceStatus and are only supported by the version built for use with semAPI 2.0 and higher (blysem.exe).
Communication using the semAPI software requires that the customer purchase the Bailey semAPI software and computer interface module as well as the PI interface software.
The interface works with the following Bailey computer interface modules:
· INICI03, INFI-NET to Computer Interface.
· HNCC, Harmony Network Communications Coupler
The INICI03 supports serial and SCSI connection to the host computer. The module supports a maximum of 30,000 points. Each instance of the interface connects to one computer interface module.
Bailey has come out with an ICI12 communications module. This module only supports a serial connection to the host computer and per Bailey; communication is through use of the Bailey semAPI. The PI Bailey semAPI interface should be compatible with this module but we have not yet had a chance to test it.
Reference Manuals
OSIsoft
· UniInt Interface User Manual
· PI Data Archive Manual
· PI API Installation Instructions
Vendor
· SemAPI Instruction Manual
· Function Code Application Manual
Supported Features
Feature / Support /Part Number / PI IN-BA-SEMAP-NTI /
*Platforms / Windows 2000/XP/2003 Server /
APS Connector / Yes /
Point Builder Utility / No /
ICU Control / Yes /
PI Point Types / Float32 / Float16 / Digital / Int16 / Int32 / string /
Sub-second Timestamps / No /
Sub-second Scan Classes / No /
Automatically Incorporates PI Point Attribute Changes / Yes /
* Exception Reporting / Done by Bailey System /
Outputs from PI / Yes /
Inputs to PI: Scan-based / Unsolicited / Event Tags / Unsolicited /
Supports Questionable Bit / No /
Supports Multi-character PointSource / Yes /
Maximum Point Count / 30,000 /
* Uses PI SDK / No /
PINet String Support / Yes /
* Source of Timestamps / PI server /
History Recovery / No /
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes /
* Failover / Yes /
Vendor Software Required on PI Interface Node / Yes /
* Vendor Software Required on Foreign Device / Yes /
* Vendor Hardware Required / Yes /
Additional PI Software Included with Interface / No /
* Serial-Based Interface / Yes /
See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported.
Please contact OSIsoft Technical Support for more information.
Exception Reporting
The Bailey System sends data to the PI interface by exception. Hence, by default, the interface does not apply the PI tag’s exception reporting on top of the Bailey events.
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
The interface keeps tracks of the current time of the PI server. It applies that time to the timestamp of the exception-based event sent from Bailey.
Failover
The interface supports failover to provide redundant data collection on both VMS platform and on Windows platform. The failover setup involves two instances of the interface, one in primary data collection mode and one in secondary or standby data collection mode. Each interface communicates to a separate ICI module. The secondary interface would monitor the ICI module status of the primary interface. If the primary ICI module is not in execute mode, the secondary interface will start collecting data. When the primary ICI module comes back on-line, the secondary interface would go back to standby mode.
Since the failover mechanism depends on the ICI module, do not set the ICI watch dog timer to 0 for the primary interface. Otherwise, the ICI module will continue to be in execute mode even if the primary interface stops communicating to the ICI module.
When installing the interface in failover setup, test the failover configuration by stopping the primary interface program and verifying that the secondary interface picks up data collection. If the secondary interface cannot read the module status of the primary ICI module within five minutes of the interface startup, the interface program will terminate, assuming the PCU address provided by the command file is incorrect. This safety check is designed to avoid having both instances of the interface collecting data at the same time.
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 PI Bailey semAPI 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
New functionality 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 the tag:
a) “1 | Starting” – the interface is starting.
b) “Good” – the interface is properly communicating and reading data from the Bailey semAPI system.
c) “2 | Connected/No data | ICI Offline” – this event represents that the Bailey semAPI system is offline.
d) “3 | 1 device(s) in error | Not connected to semAPI” – This event represents a failure to communicate with the Bailey semAPI system.
e) “4 | Intf Shutdown” – the interface is stopped.
Please refer to the UniInt Interface User Manual.doc for more information on how to configure UniInt health points.
Vendor Software Required
The interface needs the Bailey semAPI Runtime, Supervisory Control, or Development Kit to be installed on the interface node.
Vendor Hardware Required
The interface connects to ICI03 via SCSI or serial connection.
Serial Based Interface
The semAPI software handles all of the Bailey communications protocol and thereby makes it possible for the PI interface to communicate to Bailey ICI modules via a variety of transport methods (serial, Ethernet, and SCSI).
Server class machines often have inferior serial ports. Server class machines are not required for most interfaces and should not be used, especially not when serial port connections are required.
Diagram of Hardware Connection
v
Bailey semAPI Interface to the PI System v
Principles of Operation
The PI Bailey semAPI interface supports the major Bailey point types for reading data from the Bailey Infi90. It also supports data output to the Bailey Infi90 system via the Analog and Digital Report functions.
All data read by the interface come from the Bailey system as exception reports. Bailey generates an exception report whenever the value or the status changes, or when a specific amount of time has elapsed since the last report (exception maximum time). Data is output to Bailey with any change in the related value or the event time in PI.
The most common network topology used by the interface is peer-to-peer. With this approach, the interface process and semAPI software reside on the same computer. The computer is physically connected via serial, SCSI or Ethernet cable to a Bailey communications module, which is connected to the Bailey Infi90 network.
At startup, the interface retrieves all the PI tags for the specified point source and processes only those tags with matching ICI number. The interface builds the tags into a sequential list keyed by list index position.
The interface attempts to initiate communication with the Bailey communications modules via calls to Bailey semAPI libraries. These, in turn, establish a device driver process to talk to the Bailey communications module. The Bailey device driver handles physical and low-level protocol communication.
Via the semAPI call, the interface then establishes the tags in the Bailey communications module point table. After all points are established and connected, the interface enters the data collection phase.
The interface keeps reading exception data from the Bailey communications module until the maximum number of exceptions specified in the interface startup parameters have been reached or ten read exception calls have been made.
The interface checks for output events to be processed. Whenever output tags are triggered within PI, data will be sent to the Bailey system.
If more than two minutes have been passed since the last PI point database check, the interface will check for point database changes. Tags are added, modified, or deleted from the interface if necessary.
When the interface encounters ten consecutive communication errors with the ICI, the interface will attempt to clear the error by going through the error recovery procedure. The error recovery starts with disconnecting from the semAPI. Then the interface goes back to the startup phase of the operation, as described in the beginning of the manual. This auto error recovery feature normally clears problems caused by line noise. However, hardware failure will still require human intervention.