PI Autopointsync Connector for the Pitopi Interface to the PI System

PIAutoPointSync Connector
for the PItoPI
Interface to the PI System

Version 1.3.2.0
Revision A

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
/ OSIsoft Australia
Perth, Australia
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

Summary of Features and Requirements

Supported PI Point Attributes

Diagram of PIAPS for the PItoPI Interface

PItoPI_APS Features and Limitations

Filtering Source Points

Synchronization of Renamed Source Points

Limitations

Principles of Operation

Point Class

Point Source and Instance ID

Key Attributes

How PitoPI and PitoPI_APS Find Source Points

Creatable and Synchronizable Attributes

Available and Hidden Points

Tag Naming Conventions

Point Type

Updated Attributes

Installation, Upgrading, and Uninstallation Instructions

Installation Instructions

Upgrading Instructions

Uninstallation Instructions

Registering an Interface Instance with PIAPS

Configure the Settings

Rules

Synchronization Schedule

Userset Defaults

Connectorspecific Options

Enable Synchronization

Connector-specific Configuration Control

Source Point Filter

Tag Naming

Point Attributes

Digital Set Names

Best Practices, Hints and Techniques

PitoPI Interface with Multiple Instances

Example 1: PitoPI Interface with Multiple Instances Using Method 1

Example 2: PitoPI Interface with Multiple Instances Using Method 2

Appendix A: Error and Informational Messages

Installation Problems

Upgrade Problems

Operational Problems

Revision History

Terminology

In order to understand this manual, you mustbe familiar with the terminology used in this document.Specifically, you must have read the PIAutoPointSync for Interfaces and PICOM Connectors user manual that explains important PIAutoPointSync concepts and provides full definitions of PIAutoPointSync terminology.

PI AutoPointSyncTerms

APS

An acronymfor PIAutoPointSync.

APS Configuration Utility

The interactive application that registers instances of interfaces for automatic point synchronization and configures PIAPS options.

APS Connector

An interfacespecific module that communicates with the same data source as the interface to obtain current tag attribute values. Generally, a PIAPS Connector is designed for a particular interface and its implementation is based on a specific programming interface for the data source.During each synchronization scan, the PIAPS Synchronization Engine dynamically loads the PIAPS Connector for the interface instance and calls it to retrieve information for updating the PI point database.

APS Connector-specific Control

A module that provides the user interface for configuring the options of a specific PIAPS Connector. Most PIAPS Connectors have companion PIAPS Connector-specific Controls. The PIAPS Configuration Utility dynamically loads the PIAPS Connector-specific Control that is identified by the PIAPS Connector for the selected interface instance.

APS Synchronization Engine

The core service of the PIAutoPointSync product that schedules and performs synchronization scans for registered interface instances.During a synchronization scan, it obtains current tags and their attributes from a data source by dynamically loading and calling “plug-ins” known as PIAPS Connectors.The PIAPS Synchronization Engine adds, edits, or deletes PI points as necessary to agree with current tag definitions in the data source.

APS Synchronization Trigger Service

A service that monitors for events that are configured to trigger a synchronization scan for a registered interface instance.

Available Points

PI points that can be created for data source tags that are not associated with a PI point. Available points do not exist in PI.

Existing Points or Existing PI Points

Interface points that already exist in PI and are assigned to an interface instance that is registered with PIAPS.

Hidden Points

Former available points that someone marked for PIAPSto ignore. Hidden points do not exist in PI. They are excluded from the display of available points and prevent creation of PI points for the associated data source tags.

Key Attributes

The PI point attributes that arerequired by the interface and PIAPS to identify and access the data sourcetagfor the PI point.

Known Attributes

The attributes for which a PIAPS Connector can provide values when a PI point is created.

Master Synchronization Setting

A per-point configuration option that controls whether aPI point is synchronized by PIAPS. Synchronization is enabled or disabled individually for each existing PI point.

PI Point Deletes

Existing PI points that no longer have a valid data source tag.

PI Point Edits

Attributes of existing PI Points that are not in agreement with the corresponding data sourcetag attributes.

Syncable Attributes

Attributes for which a PIAPS Connector can provide values to update an existing PI point.

Synchronization or Synchronization Scan

The process that compares PI points for an interface with data source tags and either changes the PIServer to resolve any differences or logs the differences.

General Terms

Attribute

A parameter that describes a PI point. Each PI point has an associated list of attributes. Some attributes are simply descriptive. Other attributes are configuration parameters for the PIServer, the interface instance that transfers data between the PI point and data source, or both.

COM Connector

A COM object that allows the PI Server to access data from a foreign data historian and make it available to any PI client application in a seamless fashion. Some currently available COM Connectors include those for data historians from AspenTech and Honeywell as well as one for any data source with an OLEDB provider. COM Connectors are only available on Windows platforms.

DCS

An acronym for Distributed Control System. DCS was used in earlier versions of PIAPS documentation as a generic term for any data source that provides data to a PIServer, including measurement and control systems or other historian systems, even other PIServers.

ICU

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, PIAPS cannot access interface parameters from a startup command file. Therefore, configuring an interface instance with the ICU is a prerequisite to registering the interface instance with PIAPS.

Interface

A software program that collects data from some type of data source and sends the data to a PIServer. Some interfaces also have the ability to read data from a PIServer and write back to the data source.

Interface Node

A computer on which

the PIAPI and/or PISDK are installed, and
PIServer programs are not installed.

PI API

A library of functions that PI clientapplications call to communicate and exchange data with the PIServer. All PI interfaces use the PIAPI.

PI Collective

Two or more replicated PIServers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PIServer in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.

PIHOME

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. Most PIAPS files are in the APS directory under PIHOME.

pipc.log

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 and PIAPS Configuration Utility provide easy access to the pipc.log. The pipc.log file is in the datsubdirectory ofPIHOME.

PI SDK

A library of functions that clientapplications call to communicate and exchange data with the PIServer. Some PI interfaces, in addition to using the PIAPI, require the use of the PISDK.PIAPS uses PISDK to communicate with the PIServer.

PI Server Node

A computer on which PIServer programs are installed. The PIServer runs on the PIServer Node.

PI SMT

PI System Management Tools. PISMT is the program that you use for configuring PIServers. A single copy of PISMT manages multiple PIServers. PISMT runs on either a PIServer Node or a PI Interface Node.

Point

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 data source. For example, a single "point" on the data source 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.

In PIAPS documentation, point means a PIpoint and tag designates a “point” on the data source.

Service

A Windows program that runs without user interaction. A service has the ability to start up when the computer itself starts up.If started manually, it continues to run after you log off from Windows.

Tag (Input Tag and Output Tag)

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.

In PIAPS documentation, point means a PIpoint and tag designates a “point” on the data source.

Interfaces read values from a data sourceand write these values to an Input Tag. Interfaces use an Output Tag to write a value to the data source.

UniInt (Universal Interface)

A framework for interfaces to the PIServer. UniInt provides common features and generic functions required by most interfaces. Most interfaces developed by OSIsoft are based on the UniInt framework, which results in a consistent set of features in the OSIsoft interfaces to PI. For example, the UniInt framework supports special points that can be used to monitor the performance and health of an interface. The UniInt framework also supports a failover mechanism for interface redundancy. The UniInt Interface User Manual provides complete information about the features provided by UniInt.

Introduction

This manual describes the operation of the PIAutoPointSync(PIAPS) Connector for thePItoPI Interface. The informal name of the interface is PItoPI and the informal name of this PIAPS Connector is PItoPI_APS.

The PItoPI_APS Connector is different from all other PIAPS Connectors because the data source is a second PIServer. Therefore, references to the PIServers in this manual must be qualified to distinguish between the two. The target PIServer contains the interface points for the PItoPI Interface instance. Each interface point on the target PIServer is configured to identify a unique point on the source PIServer. The source PIServer points provide time-series data for the interface points on the target PIServer.
References to PI points in this manual also must be qualified to indicate which PIServer contains each point. The terms interface point and existing point indicate a point in the target PIserver. The term source point indicates a point in the source PIServer.

PIAPS is a tool for synchronizing the PI pointsfor interface instances with the tag definitions in the data sourcesassociated with the interface instances. PIAPS is based on Microsoft’s Component Object Model (COM) technology andincludes the following applications and modules:

The PIAPS Configuration and Management Utility.
The PIAPS Configuration Utilityis the interactiveapplication which registers instances of interfacesthat have corresponding PIAPS Connectors for automatic point synchronization and configuresPIAPSoptions.
The PIAPS Synchronization Engine (Sync Engine).
The PIAPS Synchronization Engine schedules synchronization scansand performs point attribute synchronization for all interface instances that are registered with PIAPS. This module is the foundation of PIAPSand does most of the work.The PIAPS Synchronization Engine is installed as a Windows service that starts automatically and runs continuously.
The PIAPS Synchronization Trigger Service.
The PIAPS Synchronization Trigger service monitors for events that are configured to trigger a synchronization scan for a registered interface instance. The PIAPS Synchronization Trigger service is installed as a Windows service that starts automatically and runs continuously.
PIAPS Connector modules (Interfacespecific Connectors).
PIAPS Connectorsareinterfacespecific modulesthat communicate with the same data source as the interface to obtain current tag attribute values. During each synchronization scan, the PIAPS Synchronization Engine calls the PIAPS Connector for the interface instance to retrieve a list of current tag definitionsin the data source. The PIAPS Synchronization Engine uses this information for updating the PI point database.
PIAPS Connectorspecific Configuration Controls.
Each PIAPS Connectorspecific Configuration Controlprovidesthe user interface for configuring the options of a specific PIAPS Connector. If the PIAPS Connector for an interface instance has a connectorspecific configuration control, the PIAPS Configuration Utility makes it available when the interface instance is selected for configuration.

The modularized architecture of PIAPS allows a single instance of the PIAPS Configuration Utility and PIAPS Synchronization Engine to support multiplePIAPS Connector modules on one computer. Also, adding new PIAPS Connector modules does not require changes to the PIAPS Configuration Utility or PIAPS Synchronization Engine. The use of COM allows individual components to be upgraded independently of the other components.

When synchronizing the PI points for an interface instance, the PIAPS Synchronization Engine uses an interfacespecific PIAPS Connector to obtain current tag definitions from the data source. For thePItoPI Interface, the PIAPS Synchronization Engine calls thePItoPI_APS Connector to retrieve a list of the current tag definitions from thesource PIServer. This information is used for creating, updating, or deleting PI points for thePItoPI Interfaceinstance registered with thePItoPI_APS Connector.

PIAPS provides many options to configure its operation for each registered interface instance. Some options apply to the interface instance, such as the interval between synchronization scans or the changes that the PIAPS Synchronization Engine is permitted to make automatically. Other options apply to individual interface points, such as whether the PIAPS Synchronization Engine is allowed to synchronize the point as a whole and, if so, which specific attributes are editable. The PIAPS Synchronization Engine logs all automated actions and changes for auditing by the administrator.

Note:When an interface instance is registered with PIAPS,PIAPS synchronization rules are preset to non-automatic selections and the default per-point synchronization settings are preset to disable synchronization on each point.

The preset options are designed toprevent PIAPS from changing the PI point database until explicitly enabled.While the preset selections for default per-point synchronization settings are in effect, synchronization is disabled for points created or discovered by PIAPS until you manually enable synchronization for those points.

Reference Manuals

OSIsoft

PIAutoPointSync for Interfaces and PICOM Connectors(PIAPSUserManual.pdf)
PIInterface Configuration Utility(PIInterface Configuration Utility.pdf)
PItoPI TCP/IP Interface to the PI System (PI_PItoPI.doc)

Summary of Features and Requirements

The following table summarizes the main features and requirements of thePItoPI_APS Connector. An asterisk (*) in the table indicates that additional explanation follows the table.

Feature / Support
* Platforms / Windows (2000 SP3 or SP4, XP, 2003, Vista, 2008 Server)
PI Point Types / int16, int32, float16, float32, float64, digital, string
Interface Instance ID Attribute / Location1
Point Class / Classic (see the “Point Class” section)
Synchronizable PI Attributes / See the “SupportedPI Point Attributes” table
Must install on target PI Server Node / No
Must install on source PIServerNode / No
Must install on Interface Node / No
* Tag Selection Conditions / No
* Tag Naming Rules / No
Attribute Formulas / No
Attribute Lookup / No
* Additional PI Software Required / Yes
Vendor Software Required on PIAPS Node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
Additional PI Software Included with PIAPS Connector / No

Platforms

The PIAPS Connector is designed to run on the above-mentionedMicrosoft Windowsoperating systems and their associated service packs.

Please contact OSIsoft Technical Support for more information.

Tag Selection Conditions

The PItoPI_APS Connector does not support the standard PIAPS Tag Selection feature. However, the PItoPI_APS Connector supports a configurable WHERE clause that selects a subset of points on the source PIServer to consider for creation of new interface points. See the “SourcePoint Filter” section for additional information.