Ping Interface to the PI System

Ping
Interface to the PI System

Version 1.6.3.0
Revision B

Copyright © 1993-2009 OSIsoft, Inc.

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
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
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

Table of Contents

Terminology

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Bandwidth and Network Traffic Issues

Resolution Limits

Topology Issues

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

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

Startup Command File

Configuring the Interface with PI ICU

Ping Interface page

Command-line Parameters

Sample PIPing.bat File

UniInt Failover Configuration

Introduction

Quick Overview

Configuring Synchronization through a Shared File (Phase 2)

Synchronization through a Shared File (Phase 2)

Configuring UniInt Failover through a Shared File (Phase 2)

Start-Up Parameters

Failover Control Points

PI Tags

Detailed Explanation of Synchronization through a Shared File (Phase 2)

Steady State Operation

Failover Configuration Using PI ICU

Create the Interface Instance with PI ICU

Configuring the UniInt Failover Startup Parameters with PIICU

Creating the Failover State Digital State Set

Using the PI ICU Utility to create Digital State Set

Using the PI SMT 3 Utility to create Digital State Set

Creating the UniInt Failover Control and Failover State Tags (Phase 2)

Interface Node Clock

Security

Windows

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

Messages

Location5

Bad Input

System Errors and PI Errors

UniInt Failover Specific Error Messages

Informational

Errors (Phase 1 & 2)

Errors (Phase 2)

Appendix B: PI SDK Options

Revision History

Ping 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 PI interfaces run, they 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.

Ping Interface to the PI System1

Introduction

OSIsoft’s PI Ping Interface program determines the latency of a TCP/IP network. In particular, PI Ping measures the response times of ICMP echo messages (i.e., “pings”) that it sends to a remote machine. Accordingly, this program can help the user in diagnosing network connection problems between machines residing in a TCP/IP network.

PI Ping comes in two versions: a regular (full) version and a limited version known as PI Ping Basic. The latter has the following limitations:

• it gets data for up to 32 PI points,
• only one copy of the program may be running at a time,
• it runs only on a machine that is also running the PI Server version 3.3 or higher, and
• it sends data only to this PI Server machine

PI Ping Basic is installed as part of PI Server v3.3 and higher.

The filename of PI Ping Basic is piping_basic.exe. The filename of the regular version of PI Ping is PIPing.exe.

The following table summarizes the differences between the regular and basic versions of PI Ping.

PI Ping / PI Ping Basic
Maximum point count / Unlimited / 32
Availability / Available for purchase / Installed as part of PI Server 3.3 and higher
Can run on a PI Interface node / Yes / No
Must run on a PI Server node / No / Yes
Must send data to the PI Server node on which it runs / No / Yes
Number of copies that can run simultaneously / Unlimited / 1
Filename / PIPing.exe / PIPing_basic.exe

PI Ping does not require any special hardware. A standard network interface card on the Windows machine is sufficient.

Reference Manuals

OSIsoft

• PI Server manuals
• PI API Installationmanual
• UniInt Interface User Manual

Supported Features

Feature / Support
Part Number / PI-IN-OS-PING-NTI
* Platforms / Windows 2000 SP3 & SP4 / XP / 2003 / Vista / 2008 Server
APS Connector / No
Point Builder Utility / Yes
ICU Control / Yes
PI Point Types / Int16 / Int32 / Float16 / Float32 / Float64
Sub-second Timestamps / No
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 / Scan-based / Event Tags
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Point Count of PI Server (Full version)
32 (Basic version)
* Uses PI SDK / No
PINet String Support / Not Applicable
* Source of Timestamps / PI server Machine
History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / UniInt Failover (Phase 2) Cold and Hot
Vendor Software Required on PI Interface Node / PINet Node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
Device Point Types / Not Applicable
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. Unless otherwise noted, the remainder of this document uses the term “Windows” to refer to all these platforms.

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

The clock on the computer running the PI Server provides the source of timestamps for the values sent by PI Ping. The Interface writes a timestamp that reflects the time at which it begins to measure ping responses. That is, all points that belong to the same scan class will have the same timestamp.

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

For a Health Tag whose Extended Descriptor attribute contains [UI_DEVSTAT], the Interface writes the following values:

a)"1 | Starting" – the Interface has started.

b)"Good" –the Interface has started successfully and is ready to measure ping response times; or, for all the points in the current scan class, the Interface has successfully measured the ping response time.

c)"3 | n device(s) in error" – for at least one of the points in the current scan class, the Interface has recorded an I/O Timeout value.

d)"4 | Intf Shutdown" – the Interface has shut down.

Please refer to the UniInt Interface User Manual.doc file for more information on how to configure Health Tags.

Failover

• UniInt Failover Support

UniInt Phase 2 Failover provides support for cold, warm, or hot failover configurations. The Phase 2 hot failover results in a no data loss solution for bi-directional data transfer between the PI Server and the Data Source given a single point of failure in the system architecture similar to Phase 1. However, in warm and cold failover configurations, you can expect a small period of data loss during a single point of failure transition. This failover solution requires that two copies of the interface be installed on different interface nodes collecting data simultaneously from a single data source.Phase 2 Failover requires each interface have access to a shared data file. Failover operation is automatic and operates with no user interaction. Each interface participating in failover has the ability to monitor and determine liveliness and failover status. To assist in administering system operations, the ability to manually trigger failover to a desired interface is also supported by the failover scheme.

The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. Details for configuring this Interface to use failover are described in theUniInt Failover Configurationsection of this manual.

Diagram of Hardware Connection

Ping Interface to the PI System1

Principles of Operation

PI Ping was developed primarily as a system manager's tool for the monitoring and analysis of a PI client-server network. It is specifically tailored for use on a machine running Windows. PI Ping uses functions in Microsoft's IPHLPAPI.DLL or ICMP.DLL to send Internet Control Message Protocol (ICMP) echo ("ping") request messages to a remote machine. These same functions provide PI Ping with the corresponding ICMP echo reply times. No additional hardware is required beyond the machine running PI Ping and a network connection to the remote machine of interest.

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:

• Servicing scheduled input points. Each Scan Class is processed in turn.
• Servicing output points as events arrive.
• Servicing triggered input points as events arrive.
• 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 –updateintervalcommand-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 30seconds (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.

UniInt Failover

This interface supports UniInt failover. Refer to the UniInt FailoverConfiguration section of this document for configuring the interface for failover.

Bandwidth and Network Traffic Issues

Continuous generation of ICMP echo packets at very high frequencies to multiple machines can create bandwidth and network traffic problems. For this reason, the user should run the interface with scan classes that are at least 1 minute (i.e., measure ping response times at frequencies that are at least 1 minute). This ensures that the network is not overloaded with PI Ping traffic.

Resolution Limits

On Windows 2000, PI Ping has a resolution lower limit of 10 milliseconds. This restriction can limit its applicability with respect to very fast networks. Therefore, PI Ping should be viewed as a tool that records automated attempts that quantify the quality of troublesome client-server connections.

Topology Issues

PI Ping measures ping response times only between the computer on which it runs and a remote machine. For example, in the following configuration, PI Ping cannot determine the ping time between Machine1 and Machine2.