OPC Alarms and Events Interface to the PI System

OPC Alarms and Events
Interface to the PI System
for OPC Alarms and Event Servers

Version 1.1.0.65

Document Revision G

UniInt End-User Interface to the PI System

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 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. 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_OPCAE.doc

 2003-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Storing Event Attributes

Event Categories

Handling Time Stamps

Connections - Creating, Losing, and Recreating

Advising

Installation Checklist

Interface Installation

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as an NT Service

Installing the Interface Service with PI-Interface Configuration Utility

Installing the Interface Service Manually

PI Point Configuration Tool

Configuration Tool Command-line Parameters

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

Performance Point Configuration

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI-ICU (NT-Intel)

Configuring I/O Rate Tags Manually

Configure the PI Point on the PI Server

Configuration Tag on the Interface Node

Interface Status Tag

Choosing an Interface Watchdog Tag

Configuring Interface Status Tag Manually

Startup Command File

Configuring the Interface with PI-ICU

Interface-specific Parameters

General Parameters

Other Uniint Parameters

Command-line Parameters

Sample piopcae.bat File

Interface Node Clock

Security

Starting / Stopping the Interface

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI-ICU (NT-Intel)

Configuring Buffering Manually

Example piclient.ini File

Debugging

Appendix A: Error and Informational Messages

General

PIPC.log File

Troubleshooting

System Errors and PI Errors

Error Descriptions

Appendix B: DeltaV OPC Alarm and Events Server ®

Introduction

Event Category

Vendor Specific Attributes

Buffer Times and Max Events

Appendix C: DCOM Configuration Details

General Steps for DCOM Configuration

DCOM Configuration for Windows XP Systems

DCOM Configuration for Windows NT/2000 Systems

Using DCOM without a Windows NT Primary Domain Controller

Using DCOM with an NT Primary Domain Controller

OPC Server Registration

Revision History

OPC Alarms and Events Interface to the PI System1

Introduction

The OPC Alarms and Events specification defines a means for transmitting alarm and event information between OPC servers and clients. Alarms and events are process alerts that require attention and are defined as follows.

An alarm is an abnormal condition, for example, a tank level alarm (which may also have these sub-conditions, LO, LOLO, HI, and HIHI).
An event is a detectable occurrence that usually concerns configuration changes, operator action, system messages or errors.

This document uses the same terms and definitions found in the OPC Alarms and Events Custom Interface Document v. 1.10; and the terms alarm and event are used interchangeably.

The OSIsoft OPC Alarms and Events (PI-OPCAE) Interface receives both alarm and event data, including all three event types (Simple, Tracking-related, and Condition-related.

The PI-OPCAE Interface to PI runs under Windows NT, Windows 2000 or Windows XP Server or Workstation operating systems, on the Intel Platform. The Interface transfers data to PI from these systems.

An OPC Alarms and Events Server
An OPC DA Server that supports the OPC Alarms and Events interface.

OPC Compatibility

OPC Alarms and Events Custom Interface Standard – 1.10.

Reference Manuals

OSIsoft

UniInt End User Document
PI Data Archive Manual
PI-API Installation Instructions

OPC Foundation

These manuals describe the protocols in detail:

OPC Alarms and Events Custom Interface (Version 1.10)
OPC Data Access and OPC Historical Data Archive

Supported Features

Feature / Support
Part Number / PI-IN-OS-OPCAE-NT
Platforms / Windows NTI 4.0/W2K/XP/2003
APS Connector / No
Point Builder Utility / Yes
ICU Control / Yes
PI Point Types / Int16, Int32, Float16, Float32, Float64, String, Digital
Sub-second Time stamps / Yes
Sub-second Scan Classes / No
Automatically Incorporates PI Point Attribute Changes / Yes
Exception Reporting / Done by Interface / Done by DCS
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Unsolicited
Maximum Point Count / Unlimited
Uses PI-SDK / Yes
PINet to PI 3 String Support / No
* Source of Time stamps / OPC AE Server / Interface
History Recovery / No
* Server-Level Failover / Yes
Interface-Level Failover / No
* UniInt-based / Yes
Vendor Software Required on PI Interface/ API / PINet node / No
*Vendor Software Required on DCS System / Yes
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
* Device Point Types / Float16, Float32, Int16, Int32, Digital String

* See paragraphs that follow for further explanation.

Source of Time Stamps

The Interface accepts time stamps from either the OPC AE server or it can provide time stamps.

Server-Level Failover

This interface supports server-level failover which allows the interface to continue to collect data from the currently active OPC AE server where two servers are running in unison in case of the primary server shutdown or unexpected communication failure.

Uniint-based

UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the OPC Alarms and Events interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our 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 End User Document is a supplement to this manual.

Vendor Software Required on DCS System

The OPC AE server can run on the same system as the Interface itself, or it can run on another system. The Interface does not ship with an OSI-supplied OPC AE server.

Diagram of Hardware Connection

OPC Alarms and Events Interface to the PI System1

Principles of Operation

The PI-OPCAE interface is designed to retrieve alarming data from an OPC compliant Alarm and Events Server and store the data in PI. This section describes operation of the interface, including the storage of event attributes, handling of time stamps, making/breaking connections, and OPC advising.

At startup the interface attempts a connection to the OPC AE server, if the server will not start, the interface will perform retries every 5 seconds. The Interface Status Utility can be used to monitor the connections between the server and the interface. Upon connection the interface will check the status of the OPC AE server: RUNNING, FAILED, NOCONFIG, SUSPENDED and TEST. The server time is also retrieved and will be compared to the PI time to compute a bias for the timestamps associated with PI archived events.

Tags to be advised are then added to the interface, and are specific to the event type configured: Simple, Tracking or Condition. When the interface starts, optional Quality/Severity tags are built to store the quality/severity attribute(s) of events when the ExDesc field contains the directive for these optional tags. If these tags already exist, no action is taken. Optional quality/severity tags are only built for conditional event tags. If the ExDesc is edited for the parent tag and one or both directives are removed the tags will not be deleted and the interface will write ScanOff for those tags. If the parent tag is deleted the interface will write Scan-Off also.

Storing Event Attributes

Events have attributes that contain important information about the alarm or event. Some attributes are standard for all OPC AE servers and some are vendor specific attributes are unique to individual servers. There are 2 mechanisms used to store these attributes. The first is to store attributes in a PI tag based on the default set by the interface. These attributes are stored in a PI string tag. Quality and severity attributes associated with conditional events are optional and stored in separate tags

Below is the standard mechanism for storing alarms and events attributes for Simple, Tracking and Condional types:

Simple Events

Simple events are events that store information about a single event such as a system or device failure. Simple event attributes are stored in a single string tag, separated by the pipe character (|), in the order listed below.

EventCategory
Severity
Message
OPC States – Enabled/Active/Acked/AckReqd
Vendor specific attribute(s) (optional) – VSA(1); …VSA(n);

Tracking Events

Tracking events represent occurrences with changes directed from an OPC AE client with an object in the OPC AE server. An example of a tracking event would be logging of the operator when changes are made to a process point. Tracking event attributes are stored in a single string tag, separated by the pipe character (|), in the order listed below.

EventCategory
Severity
Message
OPC States – Enabled/Active/Acked/AckReqd
AckReqd
OperatorID
Vendor-specific attribute(s) (optional) – VSA(1); …VSA(n);

Condition-related Events

Condition-related events are stored as string tags, and represent changes into and out of process states. Example of a condition-related event would be a Temperature Alarm transitioning into a state of High Alarm. All event related information is stored in a single string tag and is separated by the pipe character (|). The Quality and Severity tags are created by the interface during start-up if configured in the ExDesc using the /QY and/or /SY options (Optional – See ExDesc)..

Conditions
Sub-Conditions
Message
ActorID
OPC States – Enabled/Active/Ackd
AckReqd
Vendor-specific attribute(s) (optional) – VSA(1);…VSA(n);
Quality – tag (Optional – See ExDesc)
Severity – tag (Optional – See ExDesc)

The second mechanism used to store alarms and events is to allow the attribute(s) to be stored to be chosen (Attribute PI Tag Identity).

Event Categories

Events are assigned category numbers by the OPC AE server. However category numbering conventions are not standard among different servers. Most OPC AE servers begin numbering event categories from 1, while others may start from a different index.

The interface always begins numbering event categories relative to 1. It is important to relate the lowest OPC AE server event category number to 1 and verify that each event category is listed sequentially. For example, an OPC AE server providing event categories 256, 257, 258, 391, 423 and 424 would be configured in the Interface Configuration Utility as shown in the screenshot below.

Note that event category 1 is configured such that it corresponds to event category 256 (the lowest event category number provided by this particular OPC AE server). Also note that OPC AE server event categories appear in the list sequentially, despite gaps between categories 258, 391 and 423.

Proper configuration of event categories is imperative when using location2 for event category filtering (see PI Point Configuration).

Handling Time Stamps

The Interface obtains time stamps from the OPC AE server along with the AE data. The interface adjusts the time stamps to match the time on the PI server. This is done because PI cannot store data in the future, and the PI-OPCAE interface and/or the device may have a clock setting that is different from that of the PI server. The adjustments to the time stamps also correct for clock drift. The Interface attempts to get new time stamps from the PI server and the OPC AE server every 30 seconds.

Note: It is highly recommended that you set both machines to the same time-zone and the same behavior for daylight savings time.

If the OPC AE server does not provide time stamps, or does not provide time stamps for all data, you can use the /TS command line switch (See Command-line Parameters) to adjust the behavior of the Interface.

The preferred setting is /TS=Y. This setting causes the OPC AE server to provide time stamps, and does not adjust them only to localize them to the PI server.
The default setting is /TS=N. Use this setting when the OPC server cannot provide time stamps. The Interface time stamps each value as it receives it with the time stamp of the PI Server.
Using /TS=A causes the interface to adjust the timestamps to match the time on the PI server.

Connections - Creating, Losing, and Recreating

The Interface is very persistent in creating and maintaining a connection with both the OPC AE server and PI. If either is not available at startup, the Interface logs an entry to the pipc.log file and retries the connection periodically. If the Interface loses the connection to the PI server, it continues to gather data and attempts to send it to PI, while it tries to re-establish the connection to PI. It is recommended that you use the PI-API buffering program (bufserv) to avoid losing data if PI is unavailable (See Buffering). If the Interface loses the connection to the OPC AE server it will try to re-establish that connection.

If the connection to PI is lost, the only indication on the PI side is that no data is coming in and I/O Timeout is written to the tag values.

If the connection to the OPC AE Server is lost because the server has been shutdown or has abnormally exited, the interface will try to re-establish the connection for the amount of time specified by the /FT startup parameter. If this time elapses and the connection cannot be re-established, the interfaces attempts to connect to the Backup OPC AE Server, if one has been specified. The above steps are repeated, and the interface tries again to connect to the Primary OPC AE Server if no connection can be made to the Backup OPC AE Server and the wait time has expired. This process continues until a connection is made to one of the two OPC AE Servers specified. The interface will stay on a given server, once connected, until that server fails.

Advising

The Alarms/Events server notifies clients when a change in data has occurred. Read-on-change points are advised, which means that the OPC AE server sends data whenever a new value is read into the server's cache. The PI-OPCAE Interface does advise operations only and does not poll for new values.

OPC Alarms and Events Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-OPCAE Interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.

Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
Verify that PI-API has been installed.
Install the Interface.
Configure DCOM permissions. If the PI-OPCAE Interface and the OPC Server are on different nodes, configure DCOM settings for both nodes
Test the connection between the Interface node and the foreign device using the configuration tool.
Define digital states.
Choose a point source.
Configure PI points.

InstrumentTag specifies the OPC AE server source or /ALL for all sources.
Location1 is the interface instance.
Location2specifies the event categories for this event
Location3 specifies the event-type (Simple, Tracking, Condition-related).
Location4 should be set to zero for all points.
Location5specifies area filtering for this event.
ExDescspecifies which attribute(s) and vendor specific attribute identities are to be stored in the PI tag, along with the optional quality and severity tag directives.

UserInt1 specifies the attribute index where the area name is stored.

Configure I/O Rate tag.
Edit start-up command file.
Set interface node clock.
Set up security.
Start the Interface without buffering.
Verify data.
Stop Interface, start buffering, start Interface.

OPC Alarms and Events Interface to the PI System1

Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PIServer node. A PI Interface Node is any node other than the PI Server node where the PIApplication Programming Interface (PI-API) has been installed (see the PIAPImanual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PIServer is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI-API manual). Bufserv is distributed with the PI-API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.