OPC Alarms and Events Interface

Version 1.5.0.189 –1.5.4.x

OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web:
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • MontrealCalgary, Canada
OSIsoft, LLC 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
OPC Alarms and Events Interface
Copyright: © 2003-2018 OSIsoft, LLC. 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, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint,PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 05/2012

Table of Contents

Terminology

Chapter 1.Introduction

OPC Compatibility

Reference Manuals

Supported Features

Diagram of Hardware Connection

Chapter 2.Principles of Operation

Storing Event Attributes

Event Categories

Handling Time Stamps

Connections - Creating, Losing, and Recreating

Advising

Chapter 3.Installation Checklist

Data Collection Steps

Interface Diagnostics

Advanced Interface Features

Chapter 4.Interface Installation

Naming Conventions and Requirements

Interface Directories

PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing Interface as a Windows Service

Installing Interface Service with PIInterfaceConfigurationUtility

Service Configuration

Installing Interface Service Manually

Chapter 5.PI Point Configuration Tool

Configuration Tool Command-line Parameters

Chapter 6.Digital States

Chapter 7.PointSource

Chapter 8.PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

Chapter 9.Startup Command File

Configuring the Interface with PI ICU

OPCAE Interface page

General Parameters

Other UniInt Parameters

Command-line Parameters

Sample PIOPCAE.bat File

Chapter 10.UniInt Failover Configuration

Introduction

Quick Overview

Synchronization through a Shared File (Phase 2)

Configuring Synchronization through a Shared File (Phase 2)

Configuring UniInt Failover through a Shared File (Phase 2)

Start-Up Parameters

Failover Control Points

PI Tags

Detailed Explanation of Synchronization through a Shared File (Phase2)

Steady State Operation

Failover Configuration Using PI ICU

Create the Interface Instance with PI ICU

Configuring the UniInt Failover Startup Parameters with PIICU

Creating the Failover State Digital State Set

Using the PI ICU Utility to create Digital State Set

Using the PI SMT 3 Utility to create Digital State Set

Creating the UniInt Failover Control and Failover State Tags (Phase 2)

Chapter 11.Interface Node Clock

Chapter 12.Security

Windows

Chapter 13.Starting / Stopping the Interface

Starting Interface as a Service

Stopping Interface Running as a Service

Chapter 14.Buffering

Which Buffering Application to Use

How Buffering Works

Buffering and PI Server Security

Enabling Buffering on an Interface Node with the ICU

Choose Buffer Type

Buffering Settings

Buffered Servers

Installing Buffering as a Service

Chapter 15.Interface Diagnostics Configuration

Scan Class Performance Points

Performance Counters Points

Performance Counters

Performance Counters for both (_Total) and (Scan Class x)

Performance Counters for (_Total) only

Performance Counters for (Scan Class x) only

Interface Health Monitoring Points

I/O Rate Point

Interface Status Point

Chapter 16.Debugging

Appendix A.Error and Informational Messages

Message Logs

Messages

System Errors and PI Errors

UniInt Failover Specific Error Messages

Informational

Errors (Phase 1 & 2)

Errors (Phase 2)

Appendix B.PI SDK Options

Appendix C.DeltaV OPC Alarm and Events Server®

Introduction

Event Category

Vendor-Specific Attributes

Buffer Times and Max Events

InstrumentTag

Appendix D.DCOM Configuration Details

General Steps for DCOM Configuration

DCOM Configuration for Windows XP Systems

Using DCOM without a Windows Primary Domain Controller

Using DCOM with an Windows Primary Domain Controller

OPC Server Registration

Appendix E.Technical Support and Resources

Before You Call or Write for Help

Help Desk and Telephone Support

Search Support

Email-based Technical Support

Online Technical Support

Remote Access

On-site Service

Knowledge Center

Upgrades

OSIsoft Virtual Campus (vCampus)

Appendix F.Revision History

OPC Alarms and Events Interface1

Chapter 1.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 is extremely flexible in how it can store the alarms and events data. Alarm and event attributes can be chosen separately as part of the data that will be stored in PI. All chosen data can be stored in a single tag with the fields delimited by the pipe (|) symbol or can be stored into separate PI tags.

The PI OPCAE Interface to PI runs under Windows XP, and Windows 2003 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.

Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface is being installed on a 32-bit operating system (C:\ProgramFiles\PIPC) or a 64bit operating system (C:\ProgramFiles(x86)\PIPC).

The value of [PIHOME64] variable for a 64-bit interface will be C:\ProgramFiles\PIPC on the 64-bit Operating system.

In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.

Note:Throughout this manual there are references to where messages are written by the interface which is the PIPC.log. This interface has been built against a of UniInt version (4.5.0.59 and later) which now writes all its messages to the local PI Message log.

Please note that any place in this manual where it references PIPC.log should now refer to the local PI message log. Please see the document UniInt Interface Message Logging.docx in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these messages.

Reference Manuals

OSIsoft
  • PI Server manuals
  • PI API Installation manual
  • UniInt Interface User Manual
Vendor
  • OPC Alarms and Events Custom Interface (Version 1.10)
  • OPC Data Access and OPC Historical Data Archive

Supported Operating Systems

Platforms / 32-bit application / 64-bit application
Windows XP / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows 2003 Server / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows Vista / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows 2008 / 32-bit OS / Yes / No
Windows 2008 R2 / 64-bit OS / Yes (Emulation Mode) / No
Windows 7 / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No

The Interface is designed to run on the above mentioned Microsoft Windows operating systems.

Please contact OSIsoft Technical Support for more information.

Supported Features

Feature / Support
Part Number / PI-IN-OS-OPCAE-NT
Auto Creates PI Points / No
Point Builder Utility / Yes
ICU Control / Yes
PI Point Types / String
Sub-second Timestamps / Yes
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Unsolicited
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
* Uses PI SDK / Yes
PINet String Support / No
* Source of Timestamps / OPC AE Server / Interface
History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / UniInt Failover (Phase 2) Cold/Warm/Hot;
Server-level failover
Vendor Software Required on PI Interface Node / PINet Node / No
* Vendor Software Required on Foreign Device / Yes
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
Device Point Types / String
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.

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 specifically makes PI SDK calls to create PI Points.

Source of Timestamps

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

UniInt-based

UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoftdeveloped 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 Start-Up

The OPCAE interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.

SetDeviceStatus

The [UI_DEVSTAT] Health Point provides an indication of the connection status between the Interface and the OPC AE Server. The possible values for this string point are:

  • "1 | Starting" – The Interface remains in this state until it has successfully collected data from its first scan.
  • "Good" – This value indicates that the Interface is able to connect to the OPC AE Server. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems.
  • "4 | Intf Shutdown" – The Interface has shut down.
  • "5 | | 192.168.9.77 DISCONNECTED" – This value indicates that the Interface cannot establish the TCP/IP connection to 192.168.9.77. A possible cause is that there is a network problem. Another reason is that a tag is improperly configured; specifically, it refers to an incorrect IP address. However, after you have verified that your tag configuration is correct, this value is a good indication of network problems

If the Interface cannot establish communication to multiple IP addresses, the value of this point contains these addresses. For example, "5 | | 172.16.10.10,172.16.10.11 DISCONNECTED"

  • "5 | | 1 Device IN EXCEPTION" – This value indicates that the OPC AE Server returned an Exception Response of 4, 10, or 11. (Appendix A, “Troubleshooting” contains a list of Exception Responses.) The connection to the IP Address associated with the device is valid. However, the target device is either in severe error, unreachable, or unresponsive for some reason. You must look in the pipc.log file to determine the particular exception response and to determine the particular device and IP Address.

If there are disconnected IP Addresses as well as devices in exception, the Interface appends the "IN EXCEPTION" string to the "DISCONNECTED" error string.

  • "5 | | 6 IP Addresses DISCONNECTED or with devices IN EXCEPTION" – The Interface writes this value when the message associated with a "5 | | ... DISCONNECTED" or "5 | | ... IN EXCEPTION" exceeds 200 bytes. This error message reports only the number of IP addresses that are disconnected or the number of devices that return EXCEPTION response of 4, 10, or 11. You must retrieve detailed error information from the pipc.log.

Please refer to the UniInt Interface User Manual for more information on how to configure health points

Failover
  • 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 Failover Support (Cold/Warm/Hot)

UniInt Phase 2 Failover provides support for cold, warm, or hot failover configurations. The Phase 2 hot failover results in a no data loss solution for bi-directional data transfer between the PI Server and the Data Source given a single point of failure in the system architecture similar to Phase 1. However, in warm and cold failover configurations, you can expect a small period of data loss during a single point of failure transition. This failover solution requires that two copies of the interface be installed on different interface nodes collecting data simultaneously from a single data source.Phase 2 Failover requires each interface have access to a shared data file. Failover operation is automatic and operates with no user interaction. Each interface participating in failover has the ability to monitor and determine liveliness and failover status. To assist in administering system operations, the ability to manually trigger failover to a desired interface is also supported by the failover scheme.

The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. Details for configuring this Interface to use failover are described in the UniInt Failover Configuration section of this manual.

Vendor Software Required

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 Interface1

Chapter 2.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 Scan Off 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 that 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 Conditional 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.

  1. EventCategory
  2. Severity
  3. Message
  4. OPC States – Enabled/Active/Acked/AckReqd
  5. 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.

  1. EventCategory
  1. Severity
  2. Message
  3. OPC States – Enabled/Active/Acked/AckReqd
  4. AckReqd
  5. OperatorID
  6. 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. An 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).