Siemens Spectrum Power TG Interface
Version 1.0.1.0
Revision B
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web:
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • MontrealCalgary, Canada
OSIsoft, LLC 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
Siemens Spectrum Power TG Interface
Copyright: © 2018 OSIsoft, LLC. 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, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 05/2011
Table of Contents
Terminology
Chapter 1.Introduction
Reference Manuals
Supported Features
Diagram of Hardware Connection
Chapter 2.Principles of Operation
Processing of the Event Data File
Requesting Initial Values after Point is Added to the Interface
Processing of the Alarm Message File
Connection to PI Server Lost
Failover
Chapter 3.Installation Checklist
Data Collection Steps
Interface Diagnostics
Advanced Interface Features
Chapter 4.Interface Installation on Windows
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 PIInterfaceConfigurationUtility
Service Configuration
Installing Interface Service Manually
Chapter 5.DumpInputFile Utility
Chapter 6.DumpAlarmFile Utility
Chapter 7.BufStat Utility
Chapter 8.Digital States
Chapter 9.PointSource
Chapter 10.PI Point Configuration
Point Attributes
Tag
PointSource
PointType
Location1
Location2
Location3
Location4
Location5
InstrumentTag
ExDesc
Scan
Shutdown
Chapter 11.Startup Command File
Configuring the Interface with PI ICU
SIPowerTG Interface page
Command-line Parameters
Sample PISIPowerTG.bat File
Chapter 12.Interface Node Clock
Chapter 13.Security
Windows
Chapter 14.Starting / Stopping the Interface
Starting Interface as a Service
Stopping Interface Running as a Service
Chapter 15.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
Chapter 16.Interface Diagnostics Configuration
Interface Specific Performance Points
Scan Class Performance Points
Performance Counters Points
Performance Counters
Performance Counters for both (_Total) and (Scan Class x)
Performance Counters for (_Total) only
Performance Counters for (Scan Class x) only
Interface Health Monitoring Points
I/O Rate Point
Interface Status Point
Appendix A.Error and Informational Messages
Message Logs
Messages
Startup
Loading PI points
Data File Processing
Alarm File Processing
Getting Latest Timestamp
System Errors and PI Errors
Appendix B.PI SDK Options
Appendix C.Event Data File Structure
Appendix D.Alarm Message File Structure
Appendix E.Setting up a PI Archive on the Power TG System
PI Server Definition
Point Collection Definition
Installing Data from the SDB for a PI Archive
Appendix F.Technical Support and Resources
Before You Call or Write for Help
Help Desk and Telephone Support
Search Support
Email-based Technical Support
Online Technical Support
Remote Access
On-site Service
Knowledge Center
Upgrades
Appendix G.Revision History
Siemens Spectrum Power TG Interface1
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 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 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 32-bit client applications.
On a 32-bit operating system
A typical PIHOME is C:\Program Files\PIPC.
On a 64-bit operating system
A typical PIHOME is C:\Program Files (x86)\PIPC.
PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME.
For example, files for the Modbus Ethernet Interface are in
[PIHOME]\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory. For example, ICU files in [PIHOME]\ICU.
PIHOME64
PIHOME64will be found only on a 64-bit operating system and refers to the directory that is the common location for PI 64-bit client applications.
A typical PIHOME64 is C:\Program Files\PIPC.
PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.
For example, files for a 64-bit Modbus Ethernet Interface would be found in
C:\ProgramFiles\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 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. When 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.
Siemens Spectrum Power TG Interface1
Chapter 1.Introduction
The PI SIPowerTG interface allows real-time data from the Siemens Spectrum Power TG system to be written to a PI system.
The interface runs on the Siemens Power TG host station and processes data files generated by the Power TG HIS software.
The interface does not support UniInt failover, but failover within the Power TG system is supported.
Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface is being installed on a 32-bit operating system (C:\ProgramFiles\PIPC) or a 64bit operating system (C:\ProgramFiles(x86)\PIPC).
The value of [PIHOME64] variable for a 64-bit interface will be C:\ProgramFiles\PIPC on the 64-bit Operating system.
In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.
Reference Manuals
OSIsoft
PI Server manuals
PI API Installation manual
UniInt Interface User Manual
Supported Features
Feature / SupportPart Number / PI-IN-SI-PTG-NTI
* Platforms / 32-bit Interface
Windows XP
32-bit OS / Yes
64-bit OS / Yes (Emulation Mode)
Windows 2003 Server
32-bit OS / Yes
64-bit OS / Yes (Emulation Mode)
Windows Vista
32-bit OS / Yes
64-bit OS / Yes (Emulation Mode)
Windows 2008
32-bit OS / Yes
Windows 2008 R2
64-bit OS / Yes (Emulation Mode)
Windows 7
32-bit OS / Yes
64-bit OS / Yes (Emulation Mode)
Auto Creates PI Points / Yes (using Generic_CSV APS Connector)
Point Builder Utility / No
ICU Control / Yes
PI Point Types / float64 / float32 / float16 / int32 / int16 / digital
Sub-second Timestamps / Yes
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Unsolicited
Supports Questionable Bit / Yes
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
* Uses PI SDK / No
PINet String Support / No
* Source of Timestamps / PowerTG system
* History Recovery / No, but buffering between the PowerTG system and the interface is supported
UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / Interface specific failover
* 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 / All types supported by the Power TG historian software including alarm and event messages
Serial-Based Interface / No
* See available 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.
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 data received from the Power TG system includes a UTC timestamp for each event. That timestamp is passed to the PI server with the event values.
History Recovery
The Interface does not explicitly support history recovery. But if the interface is not running and processing the data files, then the Power TG system will buffer the data in the data files. When the interface is restarted, the buffered data will be processed normally and no events should be lost.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoftdeveloped 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 SIPowerTG 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 PISIPowerTG 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 successfully collected data from its first scan.
“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.
“4 | Intf Shutdown” – The Interface has shut down.
The Interface updates this point whenever the interface is started or stopped.
Failover
The interface itself does not support failover. However, the Power TG system does support failover between stations. This means that if an instance of the interface is run on both stations, when the station fails over, the interface on the active station will send events to the PI server. See section Interface Specific Failover for more details.
Vendor Software Required
Power TG Historian (HIS) software version 8.3 SP1or greater is required to generate the event data and message data files used by the interface. The interface runs directly on the Power TG historian machine.
Additional PI Software
Two utilities are included with the interface to allow the input files from the Power TG system to be dumped to stdout and can be used to validate the raw data that the interface will be reading. The utilities are “DumpInputFile” and “DumpAlarmFile”.
Device Point Types
The interface can support any measurement point type and field that is encoded in the event data files or any alarm or event message stored in the alarm files produced by the Power TG historian software.
Diagram of Hardware Connection
The following illustrates a simple configuration for sending data from a single Power TG station to a stand-alone PI server.
Siemens Spectrum Power TG Interface1
Chapter 2.Principles of Operation
The PI SIPowerTG Interface establishes the initial connection to PI and reconnects to PI in the event that the connection is lost for some reason. If the Interface is started while the PI Server is down, the Interface will periodically try to establish a connection until the PI Server is up.
When the Interface starts, the interface searches the PI Point Database for points that belong to the Interface and a point list is created for the interface.
Once startup is complete, the Interface enters the processing loop, which includes:
Every 0.5 seconds, the interface will check to see whether a measurement data file or an alarm message file has been created by the Power TG system. If a file is found, the interface will process the file. For details on the file processing, see the Processing of the Event Data File and Processing of the Alarm Message File sections below. After processing, if the /renamedata= or /renamealarm= parameter has been specified then the interface will rename the file, so it can be processed by other applications. By default, the interface will delete the processed file and will wait for the next data file.
The PI Point Database is checked every 2 minutes for points that are added, edited, and deleted. If point updates are detected, the points are loaded (or reloaded) by the Interface as appropriate. The 2-minute update interval can be adjusted with the /updateinterval command-line parameter discussed in the UniInt Interface User Manual. The Interface will only process 25 point updates at a time. If more than 25 points are added, edited, or deleted at one time, the Interface will process the first 25 points, wait 30 seconds (or by the time specified by the /updateinterval parameter, whichever is lower), process the next 25 points, and so on. Once all points have been processed, the Interface will resume checking for updates every 2 minutes (or by the time specified by the /updateinterval parameter). The Interface will write the digital state SCAN OFF to any points that are removed from the Interface while it is running.
Processing of the Event Data File
The interface reads each of the events from the buffer event data file.
For each event, it will first decode the event and extract the value and quality. It will then search for any PI points that are configured for the id@field in the event. When it finds a point, it will format the data in the required format for the PI point and send the data to the PI system.
Depending on the configuration of the PI point, the point can store the value from the Power TG field or the data quality, and the data quality can be represented in several formats. A keyword appended to the InstrumentTag is used to differentiate what the interface will store in the PI point. The interface is able to store