Telegyr EMS
Interface to the PI System
Version 1.5.65.0
Revision A
Telegyr EMS Interface to the PI System1
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.
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
Unpublished – rights reserved under the copyright laws of the United States.
© 1998-2009 OSIsoft, Inc.PI_TgyrEMS.doc
Telegyr EMS Interface to the PI System1
Table of Contents
Terminology
Introduction
Reference Manuals
Supported Features
Diagram of Hardware Connection
Principles of Operation
Input Tags
Output Tags
Tag Attributes Update
Failover
Data Quality
Installation Checklist
Data Collection Steps
Interface Diagnostics
Advanced Interface Features
Interface Installation
Naming Conventions and Requirements
Interface Directories
PIHOME Directory Tree
Interface Installation Directory
Interface Installation Procedure
Installing Interface as a Windows Service
Installing Interface Service with PI Interface Configuration Utility
Installing Interface Service Manually
Connection Tool
Filename: PITgyrEMS_Test.exe
Testing the Connection to the EMS
Digital States
PointSource
PI Point Configuration
Point Attributes
Tag
PointSource
PointType
Location1
Location2
Location3
Location4
Location5
InstrumentTag
ExDesc
Scan
Shutdown
Output Points
Trigger Method 1 (Recommended)
Trigger Method 2
Startup Command File
Configuring the Interface with PI ICU
tgyrems Interface page
General Tab
Troubleshooting Tab
Data Quality Tab
Command-line Parameters
Sample PITgyrEMS.bat File
PI EMS.ini Initialization File
EMS API Initialization – [INIT]
EMS Control Center Connection – [LOGIN]
Sample PI EMS.ini
Interface Node Clock
Security
Starting / Stopping the Interface on Windows
Starting Interface as a Service
Stopping Interface Running as a Service
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
Interface Diagnostics Configuration
Scan Class Performance Points
Performance Counters Points
Interface Health Monitoring Points
I/O Rate Point
Interface Status Point
Appendix A: Error and Informational Messages
Message Logs
System Errors and PI Errors
Appendix B: PI SDK Options
Revision History......
Telegyr EMS Interface to the PI System1
Terminology
In order 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 in order 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.
Telegyr EMS Interface to the PI System1
Introduction
The PI Telegyr EMS Interface provides communication between PI and the Telegyr Energy Management Systems (EMS). It is based on a version of OSIsoft’s standard Universal Interface (UniInt), adapted for the EMS environment.
Data is transferred between the EMS and PI using the TCP/IP network services via the Telegyr EMS application programming interface (API) and the PI API. The interface runs on Microsoft Windows platforms listed below.
The interface supports input tags (from the EMS to PI) and output tags (from PI to the EMS). It counts the events to and from these tags, including exception tests, and sends its totals periodically to PI.
Each EMS point parameter to be stored will usually correspond to a single PI tag, thus one EMS point may have multiple PI tags associated with it. A PI tag can be configured to store data quality alternately in the same tag as the data or to store all of its data and send its data quality to a separate PI tag. Multiple data quality flags are resolved by priority.
Data from the EMS is received at cyclic frequencies or by exception in the data. The frequencies of the cycles is configured by the user through the interface and controlled by the EMS. The maximum number of tags that the interface will service is dependant on how the data is retrieved, as shown in the summary table below.
Changes that are made to the PI point database are reflected in the interface. This includes the adding, editing and deleting of tags.
All error information and some summary information is output to a log file. If the interface is run interactively from an MS-DOS prompt, it is also displayed on the screen. The amount of summary information that is output is configurable by the user and is minimal by default.
Reference Manuals
OSIsoft
- PI Server manuals
- PI API Installationmanual
- UniInt Interface User Manual
Vendor
- EMS API Manual
Supported Features
Feature / SupportPart Number / PI-IN-TG-EMS-NTI
* Platforms / Windows (2000 SP4, XP, 2003)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Float16 / float32 / float 64 / int16 / int32 / digital
Sub-second Timestamps / No
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based-requested (not recommended),
Scan-based-unsolicited, Exception-based-unsolicited
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / 65536 per EMS point type
* Uses PI SDK / No
PINet String Support / No
* Source of Timestamps / Telegyr EMS or 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 / Yes
Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes
* Device Point Types / Counter (Accumulator), Measurand (Analog) and Indication (Digital)
* Serial-Based Interface / No
* 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.
The Telegyr EMS Interface is distributed in seven different executables based on which version of the Telegyr API is installed on the target system. Below is a list of these different features in the installation kit.
Telegyr API Version / OSIsoft Installation File7.2d17 / Feature: Telegyr API 7.2d Patch 17
7.2d18 / Feature: Telegyr API 7.2d Patch 18b
7.3e2 / Feature: Telegyr API 7.3e Patch 2
7.3g / Feature: Telegyr API 7.3g
7.3h1 / Feature: Telegyr API 7.3h Patch 1
8.0.1 / Feature: Telegyr API 8.0 Patch 1
8.2 / Feature: Telegyr API 8.2
Note: Support for Telegyr 7.2d Patch 10 has been removed from this release of the interface, as the format of the Telegyr EMS-API libraries are not compatible with the Visual Studio required to compile and link the current version of UniInt.
If support for Telegyr 7.2d Patch 10 is required, please use version 1.5.61.0 of the interface.
Please contact OSIsoft Technical Support for more information.
Uses PISDK
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
Timestamps are provided by the EMS at the time the data was scanned. These timestamps can be overridden by using the /UPT startup parameter, in which case the PI Server time is used for all data. This is prone to error because the timestamp will be taken as the time that the interface receives the data. Because there may be a delay between the time the data was scanned by the EMS and the time that the interface receives the data, the time may be inaccurate. Using the PI Server time is best used when the EMS and the PI Server are in different time zones.
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 TgyrEMS 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
The PI Telegyr EMS interface supports UniInt health tags. The health tag with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the connection to the Telegyr EMS system. The following events can be written into the tag:
a) "1 | Starting" - the interface is starting
b) "Good" - the interface is scanning the Telegyr EMS system for
data
or
- the interface is running as the secondary interface is
available for data collection if required.
c) “3 | 1 device(s) in error”- interface unable to connect to Telegyr EMS system
c) “4 | Intf Shutdown” - the interface has exited.
Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points.
Failover
ThePI TgyrEMS interface supports an interface specific form of failover to help reduce data loss. While running two instances of the interface concurrently, one instance acts as the primary interface and is the principal data collector while the other (secondary) interface acts as a backup. See the Failover section below for more information.
Vendor Software Required
The Telegyr EMS API is required to run the interface. This API is in two parts: the API server and the API client. The API server is usually installed on the EMS system at the time the EMS system was installed, so no further action need be taken. The API client is Windows-based and must be installed on the same machine as the PI Telegyr EMS Interface. The API client is distributed by Telegyr.
Additional PI Software
The PITgyrEMS_Test connection tool is included with the interface. This utility can be used test the connection to the Telegyr EMS server and read or write Telegyr points.
Device Point Types
The interface is able to read and write to indications (digitals), measurands (analogs) and counters (accumulators) within the Telegyr EMS system.
Diagram of Hardware Connection
Telegyr EMS Interface to the PI System1
Principles of Operation
When the interface starts up, it process the startup parameters. These parameters define the PI Point Source code and the set of Scan Class time periods to be available and other parameters as described in the Command-line Parameters section.
Log messages are recorded either in the PI log file or the PI application log file. The PI log file is named PI\PILog\pimsg_yymmdd.dat and is renewed daily. It generally has more information about the status of PI than the application log file. The PI application log file is PIPC\Dat\Pipc.log and is renewed once it reaches a certain size. It is the system administrator’s responsibility to handle its back-up and/or deleting.
The interface begins by searching the PI Point Database for all tags configured with the PointSource code specified by the /ps=x parameter. It records these tags in dynamic group structures in computer memory based on logical grouping, e.g. one list per scan class, per point type, etc. If any tag makes reference to a PI tag that is not present in the PI point database, a message indicating this is logged and the tag is rejected by the interface.
Data is retrieved from a data queue that is automatically added to and managed by the EMS. The conditions under which this happens are specified either by individual PI tags or by the interface startup parameters. When the interface reads from this queue, the data is filtered through the exception and compression specifications of each PI tag.
When the interface process has completed these initial tasks, it enters a permanent loop in which it continuously checks for the presence of data in the EMS data queue. This loop is repeated until the interface is stopped. The actions taken within this loop are described below. The interface can be configured to write a digital state to PI for every tag, indicating that the interface has been stopped.
If failover is set up and the interface is running as the secondary interface, it will not collect data unless the primary interface has stopped collecting. See the Failoversection below.
Input Tags
Input tags are serviced by the interface to collect data from the EMS and send it to PI. They can either be scan-based or event-based. Scan-based tags are serviced regularly at a pre-defined time interval. Event-based tags are serviced when a change occurs in the EMS real-time database.