pi-autopointsync connector for the cimplicity...

PI-AutoPointSync Connectorfor the Cimplicity Interface to

the PI System

Version 1.0.0.0Rev A

How to Contact Us

Phone (510) 297-5800 (main number)(510) 297-5828 (technical support)

Fax (510) 357-8136

E-mail [email protected]

World Wide Web http://www.osisoft.com

Mail OSIsoftP.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

OSI Software, LtdP O Box 8256Symonds StreetAuckland 1035 New Zealand

OSI Software, Asia Pte Ltd152 Beach Road#09-06 Gateway EastSingapore, 189721

Unpublished – rights reserved under the copyright laws of the United States.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

Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX

and DEC Alpha are registered trademarks of the Digital Equipment Corporation.PI_GECimpi_APS

2004-2005 OSIsoft, Inc. All rights reserved777 Davis Street, Suite 250, San Leandro, CA 94577

http://www.osisoft.com/

mailto:[email protected]

Table of Contents

Introduction......................................................................................................................1Modules..........................................................................................................................1

GECimpi_APS................................................................................................................1

Software Requirements..................................................................................................1

Vendor Software Requirements.....................................................................................1

Platforms........................................................................................................................2

Reference Manuals........................................................................................................2

Principles of Operation...................................................................................................3Operational Details.........................................................................................................3

Available Points..........................................................................................................3

Update Attributes........................................................................................................3

Features and Assumptions.............................................................................................4Interface Identification Attribute......................................................................................4

Key Attributes.................................................................................................................4

Syncable Attributes.........................................................................................................5

Known Attributes............................................................................................................5

Installation Instructions..................................................................................................7Installation Checklist.......................................................................................................7

Uninstall Procedure.......................................................................................................15Configuration Control....................................................................................................17

Tag Naming Convention...............................................................................................17

Cimplicity Project Name...............................................................................................17

Cimplicity Points...........................................................................................................17

Troubleshooting.............................................................................................................19Error -2130706431.......................................................................................................19

Glossary..........................................................................................................................21Revision History.............................................................................................................23

PI-AutoPointSync Connector for the Cimplicity Interface to the PI System iii

IntroductionThe PI-AutoPointSync (PI-APS) Connector for the PI-GE FANUC CIMPLICITY HMI Interface (PI-CIMPI) to the PI System is a program that automatically synchronizes (i.e., either creates new, deletes or edits existing) PI Server points with the Cimplicity point configuration. Such point configuration information is obtained from the Cimplicity Project. As point configuration changes on the Cimplicity side, GECimpi_APS Connector automatically modifies existing PI Server points to incorporate these changes.

PI-APS is versatile enough to allow the user to configure on a per point basis, using the PI-APS Configuration Utility to set up the rules, whether an existing point attribute should be changed to reflect new configuration information on the Cimplicity side. The user may also set up rules as to how PI-APS will handle PI Server points that correspond to newly added or deleted Cimplicity points.

PI-APS logs all actions and changes for the PI System administrator in order to allow for proper auditing of automated point changes. These audit logs, coupled with the versatility of point-by-point configuration, afford users a powerful tool for PI Server maintenance.

ModulesBased on Microsoft’s Component Object Model (COM) architecture, PI-APS comprises three types of modules:

The PI-APS Configuration Utility (user interface) allows for user configuration of PI-APS for all available PI Server Interface programs.

The PI-APS Synchronization Engine scheduler module (Sync Engine) handles point attribute synchronization for all PI Server interfaces. This module is the workhorse of PI-APS, and is the only module that is always running.

The PI-APS Interface Connector (PI-APS Connector) is an interface-specific module that communicates with a particular system in order to determine point attribute updates. At each synchronization period, the PI-APS Sync Engine invokes an individual PI-APS Connector and its attendant routines.

GECimpi_APSThe PI-APS Connector for Cimplicity (GECimpi_APS) is an interface-specific module that creates and modifies PI points for use with the Cimplicity Interface.

Software RequirementsThe Cimplicity APS Connector uses the PI-SDK to create and maintain PI points. The connector requires that the SDK installed be version 1.3.1 or higher.

PI-AutoPointSync Connector for the Cimplicity Interface to the PI System 1

Introduction

Vendor Software RequirementsThe Cimplicity APS Connector requires that the CIMPLICITY Point Management API be installed on the computer where the interface will run. This provides the functions required by the interface to access the CIMPLICITY database. To install the CIMPLICITY Point Management API, CIMPLICITY must be installed as a Viewer or as a Server on the interface node. When installing as a Viewer, the Point Management option must be checked.

PlatformsGECimpi_APS runs on a Windows NT 4.0 (SP 6), Windows 2000, or Windows XP machine. This same computer runs the PI-APS Sync Engine and PI-APS Configuration. This machine may be either a PI Server node or a PI Interface node. However, OSISoft recommends the various PI-APS modules (Configuration Utility, Sync Engine, and Connector) be run on a PI Interface node and not on the PI Server node.

The PI Server version that PI-APS talks to must be 3.3.361.43 or greater.

Also, the PI-Interface Configuration Utility (PI-ICU) must be used to register any interface for which PI-APS is synchronizing points. However, the PI-ICU does not need to run on the same machine as the one on which the PI-APS modules run.

Reference ManualsOSIsoft

GE FANUC Cimplicity HMI Interface to the PI System Manual

PI-AutoPointSync Connector for the Cimplicity Interface to the PI System

2

Principles of OperationThe PI-APS Connector for the Cimplicity interface is implemented as an in-process COM object in a DLL file called GECimpi_APS.dll. This COM object is registered during the installation of the PI-APS Connector.

The PI-APS Connector will never appear in the Windows NT/2000/XP Task Manager process list as an independent process. Instead, it is loaded by the PI-APS Sync Engine, which appears in the process list as PIAPSEngine.exe. The PI-APS Sync Engine loads GECimpi_APS automatically at the scheduled synchronization times.

Operational DetailsWhen the Sync Engine invokes the functions either to get the new points available on the Cimplicity side or to update those sync-able point attributes, the GECimpi_APS Connector reads from the running Cimplicity Project a list of Cimplicity point information and establishes the mapping between the Cimplicity Properties and PI Attributes. For example:

PI Attributes Cimplicity Properties

InstrumentTag PointID

Zero Range Limit Low

Span Limit High – Limit Low

Descriptor Description

DigitalSet EnumerationID *

EngUnits EngineeringUnits

PointType TypeID* This attribute is available for Cimplicity HMI version 5.5 and higher only.

Available PointsAvailable points are those points which do not yet exist on the PI Server, but which GECimpi_APS can create in PI in order to reflect the changes on the Cimplicity side. When the Sync Engine invokes the function to get the new points available on the Cimplicity project, it provides GECimpi_APS with a list of existing PI points. GECimpi_APS compares each element in this list with each Cimplicity point that is available on the Cimplicity project. From this comparison, for each available Cimplicity point that is not in the vector of existing PI points, GECimpi_APS adds it to a list of available points. This list is then returned as a parameter to the Sync Engine.

Update AttributesWhen the Sync Engine invokes the functions to update those sync-able point attributes, it provides GECimpi_APS with a list of existing PI points. GECimpi_APS compares this list with the map of all available Cimplicity tags. If one of the existing


PI points has a counterpart in the map, its (sync-able) attributes will be updated. If an existing PI point references a Cimplicity tag that is not in the Cimplicity project, GECimpi_APS sets an error status, saying that the tag is not found on the Cimplicity side.

Features and AssumptionsGECimpi_APS uses the following attributes:

PI Server Point Attribute Name

Cimplicity Point Properties Syncable Key Field

Tag No Yes

InstrumentTag PointID No Yes

Descriptor Description Yes No

Location2 n/a No No

EngUnits EngineeringUnits Yes No

Zero RangeLimitLow Yes No

Span RangeLimitHigh - RangeLimitLow

Yes No

Digital Set EnumerationID * No No

Location3 n/a No No

Location5 Has EU (Location5 = 1 if the Cimplicity point has a conversion, otherwise 0)

Yes No

PointType TypeID No No

Point Class n/a No No

Location4 n/a No No

DigitalState Array of string values * No No

n/a ResourceID ** No No

n/a DeviceID ** No No* - This attribute is available for Cimplicity HMI version 5.5 and higher only.

** - These attributes are used for tag naming / selection features only.

Interface Identification AttributeThis Cimplicity interface use the Location1 attribute together with the PointSource attribute to determine which PI points it will service.

Key AttributesThe Key Attributes are a set of one or more PI point attributes that allow an Interface to uniquely map a PI point to the data source (e.g., DCS object name) on the foreign


device. GECimpi_APS uses the InstrumentTag parameter as the interface specific key attribute.

Syncable AttributesThe Updated Attributes are a set of one or more PI point attributes whose values correspond to an attribute value for a data source on the foreign device. The Updated Attributes for the GECimpi_APS are listed in the Syncable column.

Note: though DigitalState and DigitalSet are not syncable attributes, they are required by the Synchronization Engine for creating digital states for new points. The Synchronization Engine creates a digital set for the new points automatically, using DigitalState and DigitalSet attributes. For Cimplicity HMI version 5.5 it is possible to assign EnumerationID to particular point types (Integer and Bool).

Known AttributesThe Known Attributes are a set of PI point attributes that the Interface itself needs so that it can

collect data from a data source, and

provide descriptive information about the data source (i.e. descriptor, engineering units, zero, span)

The Known Attributes for the GECimpi_APS are listed in the column PI Server Point Attribute Name.


Installation Instructions The Cimplicity APS Connector requires that PI-APS be installed on the machine on which the Cimplicity APS Connector is to be run.

The Cimplicity APS Connector Installation package is called GECimpi_APSSetup.msi. This installation package will install just the Cimplicity APS Connector, not the Cimplicity Interface or PI-APS. To install the Cimplicity APS Connector, run GECimpi_APSSetup.msi on the node where PI-APS is installed.

Installation Checklist1. Install PI-AutoPointSync (PI-APS). (The PI-APS setup installs the PI-SDK

and PI-Interface Configuration Utility (PI-ICU)).

2. Install the required vendor software (CIMPLICITY HMI as a Viewer or as a Server) and the interface whose points are to be synchronized, if they are not already installed.

3. Run the PI-ICU (installed by PIAPSSetup) and configure the Cimplicity interface whose tags are to be synchronized.

4. Install the Cimplicity APS Connector with GECimpi_APSSetup.msi.


5. Run the PI-AutoPointSync Configuration Utility and select Register New from the Interface menu

The Configure Interface or COM Connector for PI-APS dialog will be displayed:


6. Follow the instructions for configuring the Cimplicity interface for PI-APS: select APS Connector from available connectors list, select PI_UDS host and interface. The PI-APS Sync Engine will be started automatically when the PI-AutoPointSync Configuration Utility is run. For details on using the Add an Interface dialog, see the section that is titled Add an Interface - Configure an Interface for AutoPointSync in the PI-APSUserManual.doc.

7. Configure the APS Connector for the newly added interface with the options under the Settings menu on the PI-AutoPointSync Configuration Utility main window. Review all of the following settings under the Settings menu, as it is likely that the default settings need to be changed for individual interfaces and sites:

Rules

Sync Schedule


User-set Defaults


and


Installation Instructions

and

12

and

For details on using the Configuration & Settings dialog, see the section that is titled PI-APS Configuration Utility in the PI-APSUserManual.doc.

8. Configure the Cimplicity-specific settings for the newly added interface with the Connector-specific… dialog under the Settings menu on the PI-AutoPointSync Configuration Utility main window. For details about the GECimpi_APS Connector settings, see the section titled “Configuration Control”.

9. Enable the Sync Engine with the Tools menu option titled Enable Sync Engine via the PI-AutoPointSync Configuration Utility. The PI-APS Sync Engine is installed disabled and requires the user to enable it. If this menu item has a check next to it, the Sync Engine is already enabled and does not


Installation Instructions

need to be enabled.

10. Enable the Connector for the selected interface with the Tools menu option titled Enable Connector via the PI-AutoPointSync Configuration Utility. All PI-APS Connectors are installed disabled and require the user to enable them. If this menu item has a check next to it, then the Connector is already enabled and does not need to be enabled.

14

Uninstall ProcedureTo uninstall the Cimplicity APS Connector, run the Add-Remove Programs applet (this is found from the Start Menu, Settings>Control Panel> Add-Remove Programs). The following program needs to be removed:

Cimplicity HMI Interface (Cimplicity) APS Connector


Configuration ControlThe APS Connector for the Cimplicity Interface has an extra configuration control that is used to configure the illegal characters substitution rules. The Cimplicity HMI software allows some characters for point naming which are not allowed in PI System. To have tags created on PI automatically, these illegal PI characters must be substituted with legal ones.

The control looks like this:

Tag Naming ConventionFor more tag naming conventions, use Tag Naming settings inside User set defaults dialog.

Cimplicity Project NameThe control displays current settings for Cimplicity Project name, which is read from interface arguments. When this control is displayed, it checks if the specified Project exists and if it is running. The test result is displayed in the label.

See Interface user manual for details.

Cimplicity PointsThe Cimplicity HMI system has different point types and all of them are supported by Cimplicity interface (see Interface user manual).

The following default settings are used for adding new points to PI System:


Cimplicity Point Type

TypeID PI PointType

Analog DINT Int32 or Digital *

INT Int32 or Digital *

REAL Float32

SINT Int32 or Digital *

UDINT Int32 or Digital *

UINT Int32 or Digital *

USINT Int32 or Digital *

Boolean BOOL Int32 or Digital *

BYTE Int32

DWORD Int32

WORD Int32

TEXT STRING String

STRING_20 String

STRING_8 String

STRING_80 String PI point created as Digital type if corresponding Cimplicity point has an enumeration ID attached. This is valid only for Cimplicity HMI version 5.5 or higher.


TroubleshootingThe following is a list of known error messages, their explanations and steps for resolving the circumstances that caused those messages to be displayed. The user is advised to review the PIPC.LOG file in PIPC\DAT and APS connector log files following each sync cycle, to monitor the operation of point synchronization.

Error -2130706431The full error message appears similar to this:

PIAPSEngine.exe>PI-APS>Error> Error -2130706431: Cimplicity error. See PIPC.log file for details (ptrAPSC->GetAvailablePoints in PerformASynchronization)

This error indicates that the APS Connector was unable to open Cimplicity Project. The possible reason: Project is not running or doesn’t exist.


GlossaryAvailable PointsAvailable points are points that PI-AutoPointSync has detected on the DCS, but that do not exist in PI. Available Points are displayed grayed out.

Hidden PointsHidden points are points that PI-AutoPointSync has detected on the DCS, but that do not exist in PI, that the user has marked to be hidden from view.

Existing Points or Existing PI PointsExisting Points or Existing PI Points refers to points that already exist in PI and belong to the current interface.

APS Connector (APS Interface Connector)The APS Connector or APS Interface Connector is responsible for attribute data collection from the DCS.

ID AttributePI UDS point attribute that holds the interface’s ID number. For example, the PItoPI interface uses location1 to hold the interface’s ID number – the number that matches up with the /ID command-line argument.

Key Field (Key Attribute)A Key Field or Key Attribute is a PI UDS point attribute that is required in order to identify what point on the DCS the PI tag corresponds to. For example, the PItoPI interface uses the target PItoPI point’s ExDesc attribute, InstrumentTag attribute or the Tag attribute to locate the source tag.

GECimpi_APS Connector (APS Interface Connector)The GECimpi_APS Connector or APS Interface Connector is responsible for mapping Cimplicity point information into PI points for use with the Cimplicity Interface.


Revision History

Date Author Comments

01-Dec-04 Galina First draft

20-Apr-05 Chrys Version 1.0.0.0 Rev A: Reformatted; fixed headers & footers


pi-autopointsync connector for the cimplicity...

Documents