CiscoPhone
Interface to the PI System
Version 1.0.2.0
i
UniInt End-User Interface to the PI System
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.
© 2006-2007 OSIsoft, Inc. PI_CiscoPhone.doc
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 4
Principles of Operation 5
Installation Checklist 13
Interface Installation 15
Naming Conventions and Requirements 15
Interface Directories 16
The PIHOME Directory Tree 16
Interface Installation Directory 16
Interface Installation Procedure 16
Installing the Interface as a Windows Service 16
Installing the Interface Service with PI Interface Configuration Utility 17
Installing the Interface Service Manually 19
Connection Tool 21
Digital States 23
PointSource 25
PI Point Configuration 27
Point Attributes 27
Tag 27
PointSource 27
PointType 27
Location1 27
Location2 28
Location3 28
Location4 28
Location5 29
InstrumentTag 29
ExDesc 30
Scan 32
Shutdown 32
Performance Point Configuration 33
I/O Rate Tag Configuration 35
Monitoring I/O Rates on the Interface Node 35
Configuring I/O Rate Tags with PI ICU (Windows) 35
Configuring I/O Rate Tags Manually 37
Configuring the PI Point on the PI Server 37
Configuration on the Interface Node 37
Startup Command File 39
Configuring the Interface with PI-ICU 39
ciscophone Interface Tab 41
Command-Line Parameters 44
Sample PICiscoPhone.bat File 48
Interface Node Clock 49
Security 51
Windows 51
Starting / Stopping the Interface on Windows 53
Starting Interface as a Service 53
Stopping Interface Running as a Service 53
Buffering 55
Configuring Buffering with PI-ICU (Windows-Intel) 55
Configuring Buffering Manually 59
Example piclient.ini File 60
Appendix A: Error and Informational Messages 61
Log File Messages 61
System Errors and PI Errors 63
Appendix B: Acknowledgments 65
CURL 65
OpenSSL 65
Revision History 69
47
CiscoPhone Interface to the PI System 47
Introduction
The PI CiscoPhone interface is designed to read data from Cisco IP phones running Cisco Call Manager software. Each phone on a network can expose performance and network statistics in table format on a series of html pages. Each PI point loaded in the interface reads one value off a single phone and sends this value to a PI server.
The PI CiscoPhone interface runs on the Windows NT family (Windows NT 4.0 Service Pack 6 or greater, Windows 2000, Windows XP, and Windows Server 2003) on the Intel architecture.
Most of the functions of this interface are handled effectively by the PI HTML interface. However, in some cases, it may be more suitable to use the PI CiscoPhone interface instead. Both interfaces read an html file and select a value from this file to be sent to PI. The PI CiscoPhone differs from the PI HTML interface in that a single instance of the interface is capable of reading files from more than one address. The PI HTML interface however is a more richly featured interface that offers the user greater flexibility with locating the required data on a page.
Reference Manuals
OSIsoft
· PI Server manuals
· PI API manual
· UniInt Interface User Manual
Supported Features
Feature / Support /Part Number / PI-IN-CISCO-PH-NTI
* Platforms / Windows NT 4.0 / 2000 / XP /2003
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Float64, Float32, Float16, Int16, Int32, Digital, String
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
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 the PI Server
* Uses PI SDK / No
* Source of Timestamps / PI server
History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
Failover / No
Vendor Software Required on PI Interface Node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes
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 and greater. Windows NT 4.0 requires Service Pack 6.
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 clock on the computer running the PI Server provides the source of timestamps for the values sent by the interface. The Interface writes a timestamp that reflects the time at which it requested the html page.
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 Startup
The interface now supports startup without a connection to the PI server. Previously a PI server connection was required in order to obtain a list of which PI points belonged to an interface. Now this information is stored in a local cache. This cache is synchronized with the PI server point database. This not only reduces the time required for interface startup but also prevents data loss if starting the interface when the PI server is unavailable. Refer to the New Interface Features PR1 Manual for a more complete discussion on disconnected startup. Note this functionality requires PI API 1.6.1.x or later and is only supported for PI 3.x servers.
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 successfully obtained the requested values for all its points.
c) "2 | Connected / No Data | Failed to read from (n) devices" - for at least one its points, the Interface was able to connect to the point's URL, but not able to obtain the requested value.
d) "3 | (n) devices in error" - for at least one its points, the Interface was unable to connect to the point's URL.
e) "4 | Intf Shutdown" - the interface has shut down.
Please refer to the UniInt Interface User Manual file for more information on how to configure Health Tags.
Additional PI Software
A utility for testing regular expressions (RegExpTester.exe) is included in the install of this interface. This utility is useful for testing the syntax of regular expressions before using them in a PI Point.
Diagram of Hardware Connection
47
CiscoPhone Interface to the PI System 47
Principles of Operation
The PI CiscoPhone interface reads data presented in table format on html pages. Typically this interface is used to get data from Cisco IP Phones running Cisco Call Manager software. In this case each phone makes available a number of HTML pages that display operating statistics for the phone. A single instance of the interface can read any number of pages from any number of phones.
The interface is scan based; each PI point loaded in the interface will read a single value from a page on a phone at regular intervals according to its scan class. This interface does not support output points.
Interface Operation
PI points loaded in the interface are grouped by scan class. If multiple points in a scan class get their value from the same page (the URL is the same), then this page is read only once for each scan.
The interface works by representing any table it finds on an html page in an internal data table. By default this internal table should match table(s) found on the html page (see html parsing). Each PI point loads its values from this internal table. The point’s Location2 and ExDesc indicate the column number and row in this internal table of the value to send to PI.
Thread Pool
To perform a scan, the interface must read each page from each device required by the points in the scan class. In order to minimize the effect of one or more devices taking a long time to respond, the interface uses a thread pool to read and process each page. The interface groups all points that read pages from the same device (address) and submits this group as a single task to the thread pool. Tasks submitted to a thread pool are processed in turn, whenever a thread in the pool becomes available. The thread pool thread count determines how many tasks can be processed simultaneously (see /TC).
A thread pool task is performed in the following manner:
· A single html page (URL) in this task is read from the device. If the page is read without errors then the html is parsed into one or more data tables.
· A value is then written to each point that is configured for this URL. If an error was encountered either with reading the page or parsing the html data then the value written to the point will reflect this and an error message will be written to the PIPC.log file.
· The next page in this thread pool task is then processed in turn. When all the pages have been processed the thread pool task exits.
· The timestamp of the values written to PI is the time the page was requested from the device.
Each thread pool task requests pages from a single device. In cases where the device is unavailable, each request for a page will time out. When many devices are unavailable, all the threads in the thread pool may become busy waiting for each connection to timeout. This will result in a delay of the execution for other thread pool tasks. A reserve thread pool is available to alleviate this problem. The reserve thread pool operates in an identical manner to the main thread pool, however the interface submits to this thread pool any pool task that was not able to connect to a device during its last scan. Under normal operating conditions, the main thread pool has pool tasks only for devices that are connecting and reading values correctly. All failed connections are in the reserve thread pool.
Error Values
If the interface is unable to load a page from a device then the interface will write the system digital state I/O Timeout to each point configured with the URL of this page. If the interface is unable to find a value for a point or the value is the wrong type then the system state Failed is written to the PI Point. In either case a message will be written to the PIPC.log file indicating the nature of the error. If a PI point or page continues to be in error then the interface will suppress further identical error messages from being written to the log file. Editing a point in error will cause the interface to resume writing error messages for this point until it reaches 10 identical messages again.
Performance Counters
In addition to the normal UniInt performance counters the interface exposes three new counters to monitor the status of the interface. These are
· Write Queue Length: This counter monitors the length of the queue used to pass values for PI from the thread pools to the UniInt thread. If the counter’s value stays high for an extended period of time, the interface is overloaded.
· Main ThreadPool Queue Length: This is the number of pool tasks that have been submitted to the queue and are awaiting execution. If this queue stays large then scans will be late and may be skipped.
· Reserve ThreadPool Queue Length: This is the number of pool tasks that have been submitted to the reserve thread pool queue and are awaiting execution. This queue may be large without affecting the scan rate of good points. Points with values of I/OTimeout may have their scans delayed or skipped.
Pages are read using CURL. CURL is a freely available library for retrieving HTML pages from the internet. The CURL library is built into the PI CiscoPhone interface, therefore no external .dll is required.