PI-AutoPointSync Connector for the OPC Interface
User Manual
Version 1.1.0.8 and greater
22-Feb-2005
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
Internet /
World Wide Web /
Bulletin Board / (510) 895-9423
Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)
8 data bits, 1 stop bit, no parity, up to 14400 bps download
protocols: Xmodem, Ymodem, Zmodem, Kermit
Mail / OSIsoft, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland /
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
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. HPUX 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_OPCInt_APS.doc
1997 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
PIAutoPointSync Connector for OPCInt1
Table of Contents
Introduction
Modules
OPCInt_APS
Software Requirements
Platforms
Reference Manuals
Principles of Operation
Features and Assumptions
Tag Attributes
Available Points
Point Types
Scan Class
Naming Convention
Installation Instructions
Installation Checklist
Un-installation Procedure
Configuration Instructions
Configuration Checklist
OPC Configuration Control
OPC Data Type Mapping
Tag Name Masks
Filtering
OPCInt_APS Connector Updates
Upgrade Checklist
Troubleshooting
Installation Problems
Upgrade Problems
Operational Problems
Glossary
Appendix A: Manually Installing .NET Assemblies
Installing Assemblies into the GAC
Registering Assemblies with COM
Versions lower than 1.1.0.10
Version 1.1.0.10 and newer
Revision History
Introduction
PIAutoPointSync (PIAPS) is a Windowsbased software product that creates, edits, or deletes the PIServer points for an interface to match the tags defined in the interface’s data source. PIAPS is based on Windows COM (Component Object Model) technology, which enables PIAPS to dynamically load COM objects called APS Connectors. Each APS Connector is designed to communicate with a specific data source and configure PI points for its companion PI interface. This document presents the features of the PIAPS Connector for the OPC (OLE for Process Control) Interface. The APS Connector for the OPC Interface can synchronize points collected by the PIOPC interface (OPCInt) to the PIServer. Both the PIOPC interface and the PIAPS Connector for the OPC Interface use the OPC Data Access interface to communicate with OPC Servers.
PIAPS operates in parallel with the interface. Instead of transferring process data, however, PIAPSuses the APS Connector for the OPC Interface to obtain point attribute information or entire point definitions. As Items in the OPC Server change or are deleted, PIAPS can either report them or automatically modify or delete PI points to reflect these changes. PIAPS allows you to configure, on a pointbypoint basis, which attributes will be synchronized. PIAPS offers several options for handling a PI point whose corresponding OPC Item has been deleted. Choices include deleting the PI point, changing the PI point’s scan attribute to off, and several other options.
In addition, PIAPS locates Itemsin the OPC Server that do not yet have points in the PIServer and can either report them or automatically create PI points for them.
To allow auditing of automated point changes, PIAPS logs all actions and changes for the PIServer administrator to review. The audit logs, coupled with the versatility of pointbypoint configuration, afford users a powerful tool for PISystem maintenance.
Modules
Based on Microsoft’s Component Object Model (COM), PIAPS is comprised of four types of modules:
- The PIAPS Configuration Utility (interactive user interface) provides the means to configure PIAPS for any interfaces that have corresponding PIAPS Connectors.
- The PIAPS Synchronization Engine (Sync Engine) handles scheduling and point attribute synchronization for all interfaces that are registered with PIAPS. This module is the workhorse of PIAPS and is the only module that is always running (as a Windows service).
- The PIAPS Connectors are interfacespecific modules that communicate with a particular interface’s data source to determine point attribute updates. During each synchronization scan, the Sync Engine invokes an interfacespecific PIAPS Connector and its attendant routines.
- The PIAPS Custom Configuration Controls are PIAPS Connectorspecific controls that provide the user interface for extending the basic configuration settings. If the PIAPS Connector for a particular interface has a companion custom configuration control, the PIAPS Configuration Utility makes it available when the interface is selected for configuration.
The modularized architecture of PIAPS allows a single instance of the PIAPS Configuration Utility and PIAPS Sync Engine to be connected to more than one PIAPS Connector module, possibly of different types. Also, new PIAPS Connector modules may be added at any time, allowing for expansion in the capabilities of the application as new PIAPS Connectors are developed. Lastly, the use of COM allows individual components to be upgraded independently of the other components.
OPCInt_APS
OPCInt_APS is the PIAPS Connector that creates and modifies PI points for use with the PIOPC interface. The architecture and technology of thisPIAPS Connector is described in the “Principles of Operation” section later in this manual.
Software Requirements
The PIAPS Connector for the OPC Interface is an OPC Data Access client. The OPC Data Access Standard requires an OPC Data Access Server to implement a basic set of capabilities. Using the minimal set of APS Data Access interfaces, this connector supports synchronization of existing OPC Interface points and detection of deleted points. For this connector to detect OPC Items for which PI points could be created, the OPC Data Access Server must implement the optional address space browsing interface and support a hierarchical address space.
Note: The OPC Data Access Server must provide the optional address space browsing interface and support a hierarchical address space for PIAPS to create new PI points.
PIAPS is based on PISDK version 1.1 or newer, which is used to store settings in the Module Database on a PIServer. PIServer version 3.3.361.43 or greater is required to support PIAPS.
Also, you must use the PIInterface Configuration Utility (PIICU) to register any interface for which PIAPS is to synchronize points. However, you need not run the PIICU on the same machine as the one on which the PIAPS modules run.
Platforms
OPCInt_APS runs on a Windows NT4.0 (SP6), Windows200x, or WindowsXP machine. This same computer runs the PIAPS Sync Engine and PIAPS Configuration Utility. This machine may be either a PIServer node or a PI application (API) node. However, OSIsoft recommends that you run the various PIAPS modules (Configuration Utility, Sync Engine, and Connector) on a PI application node and not on the PIServer node.
Reference Manuals
OSIsoft
- OPC Interface to the PI System
- PIAutoPointSync for Interfaces and PI COM Connectors User Manual
OPC Foundation
- Data Access Automation Interface Standard, Version 2.x or higher
- DataAccess Custom Interface Standard, Version 2.x or higher
Principles of Operation
This connector is an OPC Data Access Automation client.
The PIAutoPointSync Connector for the OPC Interface is implemented as a .NET assembly in a DLL called OPCInt_APS.dll. The assembly is registered for interoperation with COM during installation, making it appear to be a COM object.
The APS Connector will never appear in the Windows Task Manager process list as an independent process. It is loaded by a PIAPS process called the Synchronization Engine, which is a Windows service that appears in the process list as PIAPSEngine.exe. The Synchronization Engine loads the PIAPS Connectorfor theOPC Interfaceautomatically at the scheduled synchronization times or ondemand from the PIAPS Configuration Utility.
The Sync Engine is a program that is installed as a Windows Service. The Sync Engine implements scheduling and the generic aspects of synchronization, including all PISDK calls to obtain or change PI point information. By itself, the Sync Engine is unable to communicate with any data source.
PIAPS Connectors embody the interfacespecific details. Each PIAPS Connector is a wrapper for a specific data source’s programming interface – the OPC Data Access Automation Interfaces in the case of this connector. All PIAPS Connectors implement a specific set of functions required by the Sync Engine and are built as COM objects, which allows them to be dynamically loaded into the Sync Engine. That is, the PIAPS Connectors “plug into” the Sync Engine and the Sync Engine calls functions in the PIAPS Connector that actually call the data source’s programming interface. PIAPS Connectors cannot execute on their own and, except in unusual cases, PIAPS Connectors do not contain any PIAPI or PISDK calls.
The PIAPS Synchronization Engine uses the PIAPS Connector for the OPCInterfaceto obtain the information necessary to synchronize existing OPCInterfacepoints in the PIServer, create new PIServer points for new OPC Items, and remove PIServer points whose corresponding OPCItems have been deleted.
For details on how to configure PIAPS to create, edit, and delete PIServer points as desired, please refer to the PIAutoPointSync for Interfaces and PI COM Connectors User Manual in addition to this manual.
Please take the time to read both manuals before you begin to install and configure PIAPS.
The PIAPS Synchronization Engine and the PIAPS Connector for the OPC Interface must run on the same machine. They do not need to run on the PIServer node or the OPC Server node. However, prior to OPCInt_APS version 1.1.0.10, PIAPS and the PIAPS Connector for the OPC Interface had to be installed on the same node as the OPC Interface. OPCInt_APS version 1.1.0.10 removed this restriction and allows PIAPS and the PIAPS Connector for the OPC Interface to be installed onany application (API)node.
Because the OPC Data Access Standard does not dictate any rules for Item naming or address space structure, the biggest challenge for the PIAPS Connector for the OPC Interface is recognizing related Items without knowledge of any specific vendor’s OPC Data Access Server implementation. That is, the objective of the PIAPS Connector for the OPC Interface is to work with any compliant OPC Data Access Server. Otherwise, specific connectors would have to be developed for each different OPC Data Access Server. The OPC Data Access Standard defines an “interface [that] can be used by clients to browse the available properties (also referred to as attributes or parameters) associated with an ITEMID and to read the current values of these properties.” The OPC Data Access Standard proceeds to say that the “design of this interface is based upon the assumption is [sic] that many ITEMIDs are associated with other ITEMIDs which represent related values such as Engineering units range or Description… As a result, this interface allows a flexible and convenient way to browse, locate and read this related information …”
Because properties are the only generic mechanism available, the PIAPS Connector for the OPC Interface uses the OPC Data Access Standard properties interface to locate properties that can be used (directly or indirectly) as sources for PI point attributes. Unfortunately, the OPC Data Access Standard recommends, but does not require, a set of generally applicable properties and most OPC Data Access Servers have not implemented them. That is, very few OPC Data Access Servers actually provide properties that this connector can use to obtain attribute values for PI points corresponding to OPC Items. Even though a particular OPC Data Access Server does not provide properties that are usable for PI point attributes, the OPC Data Access Server may have Items that appear to the usable for PI point attributes. Because there is no standardized naming system, the PIAPS Connector for the OPC Interface cannot use the Items without 1) knowing the specific OPC Data Access Server with which it is communicating, and 2) having serverspecific internal code for the server’s particular naming system and Item relationship rules.
Note: Current versions of the PIAPS Connector for the OPC Interface cannot obtain attribute values from Items unless they are linked to the PI point Item as properties.
Features and Assumptions
ThePIAPS Connector for the OPC Interface is an OPC Data Access Automation client. In contrast, the PI OPC Interface is an OPC Data Access Custom Interface client. Both Data Access Interfaces provide essentially the same functionality. The Custom Interface standard was primarily intended to be used from C++. Since using the Custom Interface from other languages can be difficult or impossible, the OPC Foundation created the Automation Interface to simplify or enable access to OPC servers from “automation” languages. The Automation Interface can be implemented directly by an OPC Server in parallel with the Custom Interface. Or, the OPC Data Access Automation Interface can be implemented as a generic “wrapper” that translates Automation Interface calls into Custom Interface calls to an actual OPC Server. The wrapper approach has a second benefit when the client is implemented with .NET technology: the wrapper helps bridge between the .NET Framework and COM. The PIAPS Connector for the OPC Interface is implemented with .NET technology and is bound to the Data Access Automation wrapper that is distributed by OSIsoft with this connector and other OSIsoft products.
The PI OPC Interface allows the OPC ItemID to be configured in either the instrumenttag attribute (recommended) or inexdesc.
Note: This connector does not recognize ItemID in exdesc.
Tag Attributes
The following table lists the source from the OPC Server for each PI point attribute supported by the PIAPS Connector for the OPC Interface:
Description / OPCSource / PIServer Attribute Name / Syncable / Key FieldPIServer Tag Name / ItemID / Tag / No / Yes
PIServerInstrumentTag / ItemID / InstrumentTag / No / Yes
Array Element Number / N/A / UserInt1 / No / Yes
Min Value in Engineering Units / Low EU,
Raw Low,
PVEULO (v9),
RANGELO (v10) / Zero / Yes / No
Max Value in Engineering Units / High EU,
Raw High,
PVEUHI (v9),
RANGEHI (v10) / Span, MaxValue – MinValue / Yes / No
OPC Tag Description / Item Description,
PTDESC (v9) / Descriptor / Yes / No
OPC Engineering units / EU Units (v9),
Eng Units,
EUDESC (v9) / EngUnits / Yes / No
PIServer PointType / N/A / PointType / No / Yes
PIServer Point Class / N/A / PtClassName / No / No
PIServer Scan Class / N/A / Location4 / No / No
PIServer Location3 / N/A / Location3 / No / No
PIServer Location2 / N/A / Location2 / No / No
Digital Set / N/A / DigitalSet / No / No
In the table above, the names in the OPC Source column other than “ItemID” are OPC Property descriptions. The first Property description in each cell is the one recommended by the OPC Data Access Standard. These Property descriptions are built into the PIAPS Connector for the OPC Interface. The notation “(v9)” indicates that the Property description was added in OPCInt_APS version 1.1.0.9 and was not implemented in earlier versions. Similarly, the notation “(v10)” indicates that the Property description was addedin version 1.1.0.10.
Available Points
Available Points are points that PIAutoPointSynccan create for OPC Items that do not yet have corresponding PI points. The Data Access browse interface is the only way for a client to enumerate the Items in the OPC Server.
Note: The OPC Server must support the optional browsing interface for Available Points to be found.
The OPC Data Access Standard recommends that the browse interface should return actual Items. However, the standard permits an implementation to return a “hint” string instead of items. For example, the browse interface in an OPC Server for a PLC with registers numbered from 0 to 32766 is allowed to return a hint like “R032766” instead of the 32767 actual items “R0”, “R1”, “R2”, etc. The connector can detect that such “hints” are not valid items. However, the structure (syntax) of “hint” strings is not standardized, so the connector cannot make use of them to generate actual Items.
Note: If an OPC Server’s browse interface returns only “hint” strings (i.e. does not return individual items), the PIAPS Connector for the OPC Interface will not be able to identify available points.
Point Types
In order to create a PIServerpoint for an OPCItem, a PI pointtype has to be specified. The PIAPS Connector for the OPC Interface uses a map based on the OPC data type of the Item to select the PI pointtype for Available Points. The mapping from OPC data type to PI pointtype is configured using the connectorspecific control discussed later in this manual.
Scan Class
All points created by the APS Connector for OPC will be Advise points, in scan class1. Read the OPC Interface to the PI Systemmanual for more details on how Advise points are configured.
Naming Convention
The default tag name that will be used for the points created in PI is the OPC ItemID. However,the configuration settings for this connector provide additional options for constructing the tag name. More information can be found in the “Tag Name Masks” section later in this manual.
Installation Instructions
The PIAPS Connector for the OPC Interface requires that PIAPS be installed on the machine on which the APS Connector is to be run.
Note: Prior to version 1.1.0.10, PIAPS and this connector must be installed on the same node as the OPC Interface to be synchronized.